Python has become one of the most popular programming languages. One major reason is that we, regular Python users, are free to share our code and others can use it very conveniently. A formal way of such code sharing is to pack all your code into a package and upload it to the Python Package Index (pypi.org), through which other Python users can install your package easily using the pip tool.
If you have published a Python package yourself, you should know that the process is not difficult. However, for those who have never done it, you may have mistakenly thought that it must be a painful process.
In this article, I’ll show you the steps to preparing your package and publishing it.
But I will do it by uploading to bitbucket, not in PyPI.org. Because If you are doing it for a company they may not want to upload it for public use. So let's get into it.
Apparently, the first step is to complete your project. However, we all understand that packages are never perfect. As a result, you don’t have to wait for the completion of your project before you can figure out how to publish your package. The setup file
As mentioned previously, we use the setup.py file to indicate how our package should be prepared. The following code shows you what a typical setup.py file looks like:
For the purpose of the current tutorial, let’s suppose that the directory that has all your Python files (e.g. file_1.py, as shown later) is called you_package. This is the one that you want to publish. To keep things simple, the file file_1.py has just the following code, which will be used when we’re ready to import the package after its publication:
def hello_world():
print("Hello World!")
1. Prepare Files
Before we dive into the details for publishing, let’s first structure the directory with the necessary support files:
the_root_dir/
|-- README.md
|-- setup.py
|-- your_package
|--|-- __init__.py
|--|-- file_0.py
|--|-- file_1.py
|--|-- file_2.py
At the root directory, at the same level as the your_package, create the README.md file. This file will cover things that you want the users to know about your package, such as installation and use instructions.
Another file at the same level is the setup.py file. This file will contain the information necessary to set up the package for publishing. We’ll talk about what’s inside this file in a minute.
Within the your_package directory, create the init.py file. This file has to be named such, and what it does is convert a regular directory to a Python package. For the current simple package, we can just put the code in the file_1.py for exporting
from you_package.file_0 import hello_world
The README file
Theoretically, you can use just plain text for this file, but I prefer to use a markdown file that gives you formatting options to make it more interesting to read.
Please note that the gist is saved as a TXT file, which shows you the source text for the markdown before bitbucket automatically applies the formatting for markdown files.
Usually, it’s recommended that you include the license information about the package so that the users can know the terms.
The setup file
As mentioned previously, we use the 'setup.py' file to indicate how our package should be prepared. The following code shows you what a typical 'setup.py' file looks like:
import setuptools
with open("README.md") as file:
read_me_description = file.read()
setuptools.setup(
name="your-package-username",
version="0.1",
author="Your Name",
author_email="your_email",
description="This is a test package.",
long_description=read_me_description,
long_description_content_type="text/markdown",
url="package_bitbucket_page",
packages=['your_package'],
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
python_requires='>=3.7',
)
- We first import the setup tools module, which has convenient methods for packaging setup.
- In the setup() function call, most parameters are very straightforward and should be self-explanatory. Some highlights are shown below:
name: The distribution name of the package, which has to be unique on pypi.org. To ensure uniqueness, it’s always a good idea that you append your PyPI username to your package name if you want to upload it in Pypi also.
long_description: The long description is usually set from the README.md file. To show the description properly, you specify that it is a markdown file by setting the long_description_content_type parameter.
packages: The list of packages that you want to publish in the distribution package. Because we’re only publishing just one package (your_package), its name is shown in a list. However, if you want to publish all packages in the directory, you can use setup tools.find_packages() to retrieve them conveniently.
python_requires: Specifies the version of Python that your package requires.
When you use it from another codebase pip will take the version name you mentioned in the setup.py file.
Now I am assuming you have committed and pushed this code into Bitbucket. Now it is time to use it from another codebase.
from the root directory, you want to use this library
pip install git+https://user_name@bitbucket.org/company_name/your_project.git#egg=name_in_setup_file_you_wrote
or if you want to download a specific tagged version
pip install git+https://user_name@bitbucket.org/company_name/your_project.git@1.0.7#egg=name_in_setup_file_you_wrote
It will download the version you have in the setup.py file, actually the latest version.
If you want to download a specific version tagged in 'git tag', you can tag that commit using git and update that version in the setup.py file also. Because pip does not recognize git tag. Pip download that Commit you have tagged and treat the version written in setup.py as the library version.
Conclusion
In this article, we learned the major steps that we use to create a Python package for distribution through bitbucket.
Top comments (0)