publish-package

Instructions to publish a Python package using Pycharm and Anaconda Prompt.

Instructions are given in the README file. Required directory structure and exemplary contents are given in the repo.

This repo is created by following this Medium post about how to create a library, this tutorial about how to publish one, and some extra research.

Steps

Virtual Environment

Create a virtual environment and install the necessary packages with specific versions. These packages will be the dependencies for your new package. Anaconda creates the new environment at C:\Users\yourusername\Anaconda3\envs by default.

1. Create a virtual environment with name venv: conda create -n venv
2. Activate the virtual environment: conda activate venv
3. Install pip (will be used to install other packages): conda install pip
4. Install package dependencies. If conda distribution is available, it is better to install it. Else, you can install using pip.
   • For conda installation: conda install numpy=1.23.5
   • For pip installation: pip install numpy==1.23.5
5. Install packages necessary to create a package (setuptools, wheel) and to upload it (twine). In my case, only twine was missing.
   • conda install setuptools
   • conda install wheel
   • conda install twine
6. Install packages necessary to test the package.
   • conda install pytest==7.1.2
   • conda install pytest-runner==6.0.0

Creating Project

Create a project which will be the contents of your package. This chapter of the Python Packages book gives a detailed explanation on the structure of Python packages, feel free to check it out if you wish. Project directory for package creation should have the following structure:

package_project
|   README.md
|   setup.py
|
+---package_name
|   |   module1.py
|   |   __init__.py
|   |
|   \---subpkg
|           module2.py
|           __init__.py
|
\---tests
        test_module1.py
        __init__.py

• README.md file should include the information about the package. You can leave it empty or explain the basics and purpose of the package as a reference for the users of the package.
• setup.py file includes the metadata of the package, such as version, dependencies, license, etc.
• package_name is the main package folder. This is how the package will be imported, i.e. import package_name. It has modules and subpackages.
• __init__.py file indicates that this folder is a package. When we import a package (not a module), this file can import from modules so that we can use functions/classes of other modules as if they are part of an imaginary module named package_name. Also, when we run ?package_name, we see the contents of docstring of __init__.py.
• module1 is a python file. Modules can have functions, classes, and variables.
  
• subpkg is a subpackage under our main package. For example, ensemble is a subpackage under sklearn (sklearn.ensemble).
  
• module2.py is a module under subpackage.
• tests folder includes test module. Test module is used to check if our package produces expected outcomes (for example, using assert to check if a function returns the expected value for specific input values).

For example, sklearn is a package and ensemble is its subpackage. When we run from sklearn import ensemble, ensemble subpackage is imported. Even though ensemble is not a module, we can create an object using ensemble.RandomForestClassifier(). This is because __init__.py file of the ensemble subpackage imports this class definition form another module (._forest.py).

Creating Package

In this step, you will write your own functions and classes inside module files.

When creating the package, you should use the virtual environment. In Pycharm, you can click the bottom right button (on the left of lock button) where it says something similar to 'Python 3.x ...'. Then, Add New Interpreter>Add Local Interpreter>Existing>Three Dot. Here, you need to locate the virtual environment that we created in the Virtual Environment step.

This is important for the consistency of your package. Whenever you need to install a package, you should install it to the virtual environment. This way, you will know exactly which versions of which packages your new package requires. These will be the dependencies for your package. Also, by using a virtual environment, you ensure that your package is guaranteed to work under these conditions.

If you want to go one step further, you can check every version of the packages that you are requiring and instead of writing numpy==1.23.5 as dependency, you can write numpy>=1.23.5.

Testing the Package

To test the package, run python setup.py pytest. This will run all the tests inside the tests folder.

Building and Publishing the Package

• To build the package, run python setup.py sdist bdist_wheel. This will create two files under the dist file: one wheel file and one tar.gz file.

In setuptools.pypa site, it is stated that it is deprecated to build the packages this way. For the up-to-date solution, you need to do the following: Install the build package pip install build (conda version didn't work properly for me). Then, run python -m build.

• To install the package locally, you can run pip install dist/name_of_wheel_file. Then, you can import it in your python files.
• To check if your package description is convenient for PyPI, run twine check dist/*. (convenient = it will be properly shown on the page)
• To publish your package to PyPI, run twine upload dist/*. You will be required to provide you PyPI username and password. After providing them, your package will be published to PyPI. From now on, anybody can install your package using pip install package_name.