Have you ever wanted to create a Python package so you can type the following?
pip install my-awesome-package
If so, this tutorial is for you.
1. Getting Poetry
Poetry is a system package you can use to very easily manage your Python Packages.
It makes handling your packages super easy. I have 9 Python packages under my name, and this is by far the best solution.
First, you need to install Poetry on your system.
osx / linux / bashonwindows install instructions
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
windows powershell install instructions
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -
More details about installation here
Now you can type poetry --version
to see the version you're running. If this doesn't work for you, try closing and re-opening your terminal.
2. Creating a Poetry project
In this tutorial we're going to create a new package from scratch.
Go ahead and type:
poetry new test-package
As the docs mention, it'll create a new folder with a bunch of files for you that are structured like this:
test-package
├── pyproject.toml
├── README.rst
├── test_package
│ └── __init__.py
└── tests
├── __init__.py
└── test_test_package.py
3. Adding your code
Create a new file in test-package/test_package/
called myfile.py
.
Your file structure should look like this now:
test-package
├── pyproject.toml
├── README.rst
├── test_package
│ ├── __init__.py
│ └── myfile.py # <- This is new
└── tests
├── __init__.py
└── test_test_package.py
All of your code will go in the test_package/
folder.
Note: This folder name will be different if you used a different package name during step 2.
You can add any files you want in this folder. This is what get's bundled in your package.
Now in your myfile.py
file, add this function:
def custom_function(name):
print(f"Hello {name}!")
Later we can use this code like so:
from test_package.myfile import custom_function
👆 We'll get to that later, first we need to build the package.
4. Building your package
So far we just have a bunch of code sitting on our computer and if someone else wants to use our code, they need to copy all the files and folders.
Let's "build" the project.
poetry build
This will take all your code, bundle it, and put it in a versioned file inside of a /dist/
folder. The file should look something like this: test-package-0.1.0.tar.gz
.
It will also create a wheel file for you that looks something like this: test_package-0.1.0-py3-none-any.whl
5. Testing your code in other virtual environments
Now what I like to do is test my package in a brand new virtual environment.
Create a new virtual env in a new folder somewhere else on your computer.
mkdir testenv && cd testenv
python3 -m venv .venv/
source .venv/bin/activate
Note: Your virtual env will be created differently if you're on Windows. You can use virtualenv, pipenv, Docker, etc. It just needs to be a fresh environment.
Now that you're in a new Python environment, copy that .tar.gz from from earlier into this folder. (I usually use the operating systems OS for this, but there's nothing wrong with using cp
to copy the file). The only file in this virtual environment should be your .tar.gz file.
Now install this file with:
pip install test-package-0.1.0.tar.gz
Assuming everything went well, let's test this out.
Open a new Python shell (REPL) with:
python
(on non-Windows) or py
on Windows. And type this out:
from test_package.myfile import custom_function
custom_function("Kalob")
It should print out Hello Kalob!
.
And just like that, you have create a bundled package. But it's not available for everybody just yet.
6. Push it to GitHub
At this stage I like to push my code up to GitHub.
Because we're making a public package, I tend to make my repo's public as well. No use hiding the source code when it will be easily downloaded from PyPi.org anyway.
Dont forget to add /dist/
and other files to your .gitignore file. The /dist/
folder is where your bundled code goes when it's built by Poetry.
7. Publish the package
Now let's publish this code on PyPi.org.
First, you need a free PyPi.org account. You'll need your username and password handy because Poetry will ask for it so it can upload your file to PyPi and associate it with your account.
Once you have a free PyPi account, go ahead and run this in your terminal:
poetry publish
It will ask for your username and password. Go ahead and type those in.
And now your package will be on PyPi.org.
Note: If the package of
test-package
already exists, or at one point existed, on PyPi.org you cannot use the same name. Making your Python packages have unique names is the best way to avoid this problem.
If you didn't run into a naming problem, you'll have successfully published a package to PyPi.org!
Congrats!
8. Install your package using pip
Assuming your package is now on PyPi, let's install your package in another project and test it out.
pip install test-package
Everything should work as expected now. And your code is now easily accessible to every Python developer. 🎉
Example repo
If you'd like to see a simple package I recently created for Arbington.com take a look at python-vimeo on GitHub and feel free to use any part of that repo. That's why we open sourced it! :)
Top comments (0)