How to create a simple python package
python3 setup.py install
pip install package_name
With a very simple tool that have only 1 python script file, the
.py script file can be placed under the root folder.
└── tool-name ├── tool-name.py ├── LICENCE ├── README.md └── setup.py
But with a more complex tool with several python script files,
.py script files must be place under a "lib" folder.
└── tool-name ├── tool-name │ ├── __init__.py │ ├── script.py │ └── main.py ├── LICENCE ├── README.md └── setup.py
And of course a
__init__.py will be needed.
First line of distutils setup script will always be the same:
from distutils.core import setup
This will import
setup() function that will take some parameters.
Only 3 field are required:
An a vey important field in order to differentiate the source code and all the others things around like documentation:
Additional meta-data can be found in the Python Doc.
There is also a PEP 314 describing a mechanism for adding metadata to Python packages.
PyPI (formerly Python Package Index) contains thousands of Python libraries and tools. So a proper classification of metada will allow people to easily find the package.
To classify the package, use the
classifiers parameter of the
setup() function. This contains a list of strings.
All classifier strings must match with PyPi classifiers list.
from distutils.core import setup setup( name = "chardet", packages = ["chardet"], version = "1.0.2", description = "Universal encoding detector", author = "Mark Pilgrim", author_email = "email@example.com", url = "http://chardet.feedparser.org/", download_url = "http://chardet.feedparser.org/download/python3-chardet-1.0.1.tgz", keywords = ["encoding", "i18n", "xml"], classifiers = [ "Programming Language :: Python", "Programming Language :: Python :: 3", "Development Status :: 4 - Beta", "Environment :: Other Environment", "Intended Audience :: Developers", "License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)", "Operating System :: OS Independent", "Topic :: Software Development :: Libraries :: Python Modules", "Topic :: Text Processing :: Linguistic", ], long_description = """\ Universal character encoding detector ------------------------------------- Detects - ASCII, UTF-8, UTF-16 (2 variants), UTF-32 (4 variants) - Big5, GB2312, EUC-TW, HZ-GB-2312, ISO-2022-CN (Traditional and Simplified Chinese) - EUC-JP, SHIFT_JIS, ISO-2022-JP (Japanese) - EUC-KR, ISO-2022-KR (Korean) - KOI8-R, MacCyrillic, IBM855, IBM866, ISO-8859-5, windows-1251 (Cyrillic) - ISO-8859-2, windows-1250 (Hungarian) - ISO-8859-5, windows-1251 (Bulgarian) - windows-1252 (English) - ISO-8859-7, windows-1253 (Greek) - ISO-8859-8, windows-1255 (Visual and Logical Hebrew) - TIS-620 (Thai) This version requires Python 3 or later; a Python 2 version is available separately. """ )
By default, Distutils will only include the following files in the release package:
So to include a
LICENCE file, a
NOTICE file, use a different file extension like a
docs/ documentation folder, a Manifest file will be needed.
The Manifest file is called
MANIFEST.in, placed in the project's root directory. This is not a python script. It allows to include or exclude files and directories.
include README.md recursive-include docs *.html *.css
It maintains the directory structure.
setup.cfg is a powerful tool that can do a lot but here we only need it because we're using a markdown readme file. Because Distutils only check for
[metadata] description-file = README.md
Distutils has a built-in validation command:
python3 setup.py check running check
The minimum is too build a source distribution containing the source code, the setup script, the README file and additional files that come with the MANIFEST.
python3 setup.py sdist
This will create a
dist/ folder in your project directory and a
package_name.tar.gz archive inside it (or a
.zip for Windows users).
python setup.py bdist_rpm
python setup.py bdist --formats=rpm
python setup.py bdist_wininst
python setup.py bdist --formats=wininst
PyPI is the Python Package Index
pip install something
.pypircconfiguration file (1/2)
To make life easier when uploading packages, create a
[distutils] index-servers = pypi pypitest [pypi] repository=https://pypi.python.org/pypi username=your_username password=your_password [pypitest] repository=https://testpypi.python.org/pypi username=your_username password=your_password
.pypircconfiguration file (2/2)
Passwords can be omitted in
~/.pypirc and written when uploading.
Warning: in Python 3
% must be escaped in password by doubling them.
Info: Spaces don't need to be escaped, there must be not quote.
Register the package project:
python setup.py register -r pypi
Upload the package distribution:
python setup.py sdist upload -r pypi
To make sure the package is set up correctly, package can be upload on PyPI's test server first:
python setup.py register -r pypitest python setup.py sdist upload -r pypitest
If the package code source is hosted on a Git repository:
.gitignorecan be added (ex: GitHub Python gitignore to avoid uploading
build/folders to the remote Git repository.
git tag 0.1 -m "message"&
git push --tags origin mastercan be used to generate and host package
Warning: To use
git tag on GitHub there must be only one tool per repository (no multi-tools repository).