Pypkg is an example package that exists as an aid to the Python Packaging User Guide Tutorial and demonstrates best practices for Python packages. This project was forked from github.com/pypa/sampleproject.
- Copy/clone Pypkg to use as the basis for your project.
- Setup your Python package in a package directory with a matching name (e.g. package pypkg in the pypkg package directory).
- Set the package version x.x.x in the package's VERSION file.
- Update setup.py and setup.cfg with the name, dependencies, etc. of your package.
- Install development dependencies into a virtual environment and list them in requirements.txt.
- Develop the package locally.
python setup.py develop # setuptools way
pip install -e . # pip way
- Write tests for the package and ensure the .travis.yml config will run them.
nosetests # autodiscover and run tests (run from project root)
- Write Sphinx documentation for the package.
cd docs
make html
- Change the LICENSE file to a license you like. Update the license link in README.rst.
After making changes, complete the following tasks:
- Local nosetests pass
- Changes are summarized in CHANGES.rst
- Increment the version in pypkg/VERSION and the documentation
- README summary matches DESCRIPTION.rst
- Continuous Integration tests pass (sandbox)
- Code pushed to source host
- Rebuild the ReadTheDocs docs from the project overview
- Upload releases to PyPI. If metadata has changed, re-register the package to upload the new metadata.
- Create a new repository on a source host such as Github or Bitbucket.
- Go to Travis CI or another CI runner and setup your repository.
- Update the badge links in the project README.rst.
- Push the source to your repository host.
- Go to ReadTheDocs and build your docs from the hosted source.
- Build and pack the package.
python setup.py sdist # source distribution
python setup.py bdist_wheel # binary wheel distribution
- Register the package name with PyPI.
python setup.py register # uploads all metadata to PyPI
Note that registration still currently occurs over insecure http rather than https. The first attempt to connect to PyPI prompts for a username and password and generates a .pypirc file like the following:
[distutils]
index-servers =
pypi
[pypi]
username:dghubble
password:mypass
to simplify future registrations/uploads. Registration also updates the
- Upload the package distributions to PyPI.
twine upload dist/* # using twine
- Check all README.rst links, documentation links, and PyPI links for correctness.
- Improve and maintain the project, docs, and tests. There is no last step. You are never done.
Summary...
Install pypkg via pip
$ pip install pypkg
If you want to remove the package later
$ pip uninstall pypkg
$ pypkg
~Call your main application code here~
>>> from pypkg.core import fancy_print
>>> fancy_print("hello world")
~hello world~
Documentation is available here.
To get the source from Github
$ git clone git@github.com:dghubble/pypkg.git
$ cd pypkg
$ pip install -r requirements.txt
$ python setup.py develop
If you want to remove the development install
$ cd pypkg
$ python setup.py develop --uninstall
$ pip install nose
$ nosetests
....
----------------------------------------------------------------------
Ran 4 tests in 0.147s
OK
If you'd like to contact me, feel free to Tweet to @dghubble or email dghubble@gmail.com.