This blog post shows an easy way to start packaging and publishing your Python code and especially the PyScaffold package which can help you a lot when starting a new project.

Setup

First of all one needs to install the package of cause pip install PyScaffold. Then one can begin a new project with the following command:

putup -p ProjectName -d "Cool short description for PyPI etc." -u http://github.com/smartsammler/ProjectURL -l new-bsd --with-tox DirectoryName

so one does not have to care about Inter sphinx questions like linking to NumPy.

Beside the necessary files there are some files which are good examples or starting points, like the tests/test_skeleton.py and the ProjectName/skeleton.py.

One thing you need to do manually is adding all files you want to add to the Git repo.

Required for a valid Python package installable via PIP are requirements.txt setup.py setup.cfg ProjectName/__init__.py

Files which require manual adjustments after setting up, but probably before the first commit are README.rst setup.cfg tox.ini docs/index.rst

On a regular basis you need to update the CHANGES.rst requirements.txt * All your tests and code

Virtual environments

Virtual environments are good for development, testing and for web-environments. They separate the Python runtime from your system. From Python 3.4 on it virtual environments are easy to use since venv is included. There are three typical commands for environments. * Create an environment:

python3 -m venv .venv 

• Join the environment

source .venv/bin/activate

Then you work on your project and if your done you * leave the environment

deactivate

Version bumping

pip install bumpversion

bumpversion [--commit] --allow-dirty --tag patch

patch or minor or major. For the first time you run bumpversion you must add --new-version 0.0.1 to provide a starting version. Be aware that running bumpversion modifies the setup.cfg and deletes all comments. So do your changes before running bumpversion since PyScaffold provides useful comments in the setup.cfg. Also be reminded that you also should git push --tags from now on to push the tags to the repository.

Code style/flake8

pip install flake8 tox Add flake8 options to the setup.cfg

[flake8]
ignore = E501
exclude = .tox/*,docs/*,tests/*

which will allow too long lines and igonre PEP-8 errors in the specified directories.

tox will run flake8 or you can run it by tox -eflake8

If a specific line should be ignored add # flake8: noqa after it, which will tell flake8 to ignore it. I often use it for the power-operator since I like it to be without spaces surrounding it.

c = sqrt(a**2 + b**2)  # flake8: noqa

Typing/MyPy

(pip install mypy)

mypy --ignore-missing-imports

Test coverage

Test coverage can be tested with coverage (pip install pytest-cov coverage)

coverage3 tests/
py.test -cov

Alternatives and complements

Python Boilerplate -- A website that generates a minimal version as a Python boilerplate/scaffold. Cookie cutter -- A project written in Python aiming to provide boilerplates for different languages and project types, each based on a git repository as a basis.

Further resources

Official packaging tutorial Official user guide, and the Python Packaging Authority