First thing first, you need Poetry if you don’t have it already.
Poetry is the new standard for creating and managing virtual environment for your Python project. It is also a Python dependency management tool that is working differently as pip. It uses the new standard
pyproject.toml decided by the Python Packaging Authority with PEP-518. This file merges all the previous config files that were necessary before,
Pipfile, in one unique file to rule them all ! Ok, enough of Lord of the Ring.
I advise you to follow along with the documentation of poetry open.
Feel free to look here for more instructions. Updating Poetry is very easy by the way
Create the package you want to publish on PyPi
Poetry has a nice command that can create your project tree at once
poetry new <package_name>.
You will need to add things to the generated
pyproject.toml file, feel free to check the poetry documentation to see all the options.
[tool.poetry] name = "vspoetry" version = "0.1.0" description = "Description of your package" authors = ["MattiooFR <email@example.com>"] keywords = ["keyword", "another_keyword"] readme = "README.md" license = "MIT" homepage = "https://github.com/MattiooFR/package_name" repository = "https://github.com/MattiooFR/package_name" include = [ "LICENSE", ] [tool.poetry.dependencies] python = "^3.5" [tool.poetry.dev-dependencies] [tool.poetry.scripts] cli_command_name = 'package_name:function' [build-system] requires = ["poetry>=0.12"] build-backend = "poetry.masonry.api"
The beginning of the file is pretty straightforward. Lets focus on those three part :
[tool.poetry.dependencies]: This is where you can list all the dependencies that your package needs to work. It’s like the old
requirements.txtfile. You can do it by hand and then call the command
poetry installto install them all for your package development and working purposes. If you use
poetry add <dependency_name>(equivalent to the
pip install <dependency_name>), poetry will add it there for you.
[tool.poetry.dev-dependencies]: If you need development dependencies, that’s where they go. Again, you can also install them with
poetry add <dependency_name> --dev (or -D)and poetry will also put that in the right place in your
[tool.poetry.scripts]: This last block is very important if you want your package to have script callable from the terminal.
By the way, if you still need to have a
requirements.txt with all the dependencies (if you use Heroku for example), you can easily have it with this command :
Build your package
When your package is ready, simply do
poetry build to create the package files
You can test your package by doing
If everything works, congrats ! Now lets publish it to PyPi so others can use your great package too.
Publish your package
Your package need to be built, so first run
poetry build if you haven’t done it already.
Then simply run
poetry publish and your package will be publish on PyPi :
If you need to update your package, simply increment the version in the
pyproject.toml file and use
poetry publish (after you build the new package with
Once you have done that you can then install your package :
Congrats on publishing your package on PyPi and experiencing the simplicity of using a tool like Poetry.
Happy coding !
I actually just published my first package, vspoetry, while writing this tutorial. It is a package that add the
vspoetry script command to my terminal and this simply add the path of the current poetry virtual environment of the project to VScode
settings.json. This tells to VScode where to grab the project python venv because VScode does not do that automatically yet.