New Project Checklist

The following checklist is designed to help set up and complete a new python programming project and host it on PyPI.

Placing the source code on GitHub or Bitbucket will make the source code and documentation available to others.

Before You Start Programming

  1. Check that your project’s name is available on PyPI. Go to https://pypi.python.org/pypi and use the search feature to verify that your desired project name is available. When you decide on an available name, you can create a repository and register it with PyPI.
    • Also look for a project that already does what you intend to do.
    • You may be able to contribute to an existing project instead of reinventing the wheel ;-).
  2. Set up the project on GitHub or Bitbucket (I recommend GitHub).
  3. Run PyHatch to create the project folder and supporting files
    • Use the URL for either GitHub or Bitbucket project as project url in pyhatch GUI.
      • If using ReadTheDocs, you might want to use the ReadTheDocs url in pyhatch GUI.
    • Optionally delete examples subdirectory
      • PyHatch creates an examples subdirectory that you may choose not to use.
    • Optionally create a new logo image file (PNG, GIF, JPEG, SVG, etc.)

      • PyHatch creates a logo called generic_logo.svg located in the /docs/_static subdirectory

      • The current logo is a 210x62 pixel SVG file. An image file of similar characteristics would work well in the Sphinx-generated HTML pages.

      • To change the logo, look in the file /docs/conf.py and change the line:

        html_logo = "./_static/generic_logo.svg"
      to
html_logo = "./_static/<your new image file name>"
  4. Register yourself with PyPI (If you haven’t already)
  5. Configure your .pypirc file to make register and upload to PyPI easier.
    • Edit the username and password in the .pypirc file that PyHatch creates
      • PyHatch leaves only place-holders for username and password
    • Move .pypirc to your home directory after editing. See PyPI Configuration File for guidance.
  6. Register you package with PyPI (Python Package Index)
  7. Edit the tox.ini and .travis.yml files to match the python versions you want to support
    • Tox Automation is excellent for checking multiple versions of python on your development machine.
    • Travis CI is excellent for checking multiple versions of python on generic Linux machines when you check your code into GitHub.
  8. Edit MANIFEST.in and setup.py (This is the first of perhaps many edits)

The Programming Cycle

  1. Start programming and developing the code
    • Use Tox Automation and tk_nosy to constantly validate the code during development
      • Tox Automation makes the virtualenv setup easy for different python versions
        • Tox needs accurate requirements.txt file
        • Tox needs accurate install_requires option within setup.py
      • tk_nosy makes TDD (Test Driven Development) easy
        • better still, try TDDD (Test Driven Documented Development)
        • tk_nosy uses nosetests to run unittests. By default coverage is turned on. To turn coverage off, edit the setup.cfg file under the nosetests header. Change with-coverage from one to zero (1 to 0).
    • Use Pylint on each python file to constantly measure code quality
      • The right IDE should do this automatically
    • Use Travis CI to verify operation on Linux machines with different python versions
    • Use sphinx to keep documentation current with code
  2. Constantly Work the Documentation
    • Whether just a README.rst or a full sphinx HTML site, keep editing and re-editing the documentation.
    • Consider using the sphinxy.py script located in the docs subdirectory.
      • sphinxy.py rebuilds the HTML docs every time a *.rst file changes. It can make the documentation development cycle a little more convenient.
        • Note that sphinxy.py also changes the file system date for all *.rst files
    • Consider a QuickStart section in your docs (a quick install and use section)
  3. In addition to the Pylint already run on your code, consider running cheesecake to verify your code’s “readiness”.

Upload to PyPI (or testPyPI)

  1. Run Tox Automation before uploading to PyPI
    • This will test pip installs of package dependencies in the tox virtual environment.
    • Make sure that your tox.ini file dependencies (deps) are the same as in your setup.py and requirements.txt files.
  2. Set the correct version number of the code
    • Open the file _version.py and edit the version number at the bottom of the file
      • for example change __version__ = ‘0.0.1’
      • to __version__ = ‘0.0.2’

    • Commit to GitHub with comment like:

      git add .
git commit -m "Release 0.0.2"
  3. Create HISTORY.rst by running history_from_github_api.py
  4. Verify the docs
    • Whether just a README.rst or a full sphinx HTML site, re-read the documentation.
      • If using ReadTheDocs:
        • include a link to ReadTheDocs in README.rst
        • include a link back to GitHub repository somewhere in ReadTheDocs
  5. If you skipped this step before, Register you package with PyPI (Python Package Index)
    • Run python setup.py register
      • For testPyPI: python setup.py register -r https://testpypi.python.org/pypi
    • With .pypirc file can use python setup.py register -r pypi
      • or python setup.py register -r testpypi on testPyPI
    • Check the site http://pypi.python.org/pypi/<projectname>
      • Make sure that Home Page: links to your GitHub or Bitbucket source code repository.
  6. Create release file
    • Run `` python setup.py sdist``
    • Examine MyProject.tar.gz or MyProject.zip
      • Make sure the included files are what you want
        • Edit MANIFEST.in
        • Edit packages=find_packages(…) within setup.py
  7. Create wheel for upload to PyPI
    • python setup.py sdist bdist_wheel

Warning

Twine is now the preferred way to register and upload projects. The following setup.py approach has been abandoned for python versions < 2.7.13

  1. If twine is not available or if you are on Windows (Windows version is buggy right now) upload your package to PyPI as follows:

    python setup.py register -r pypi
python setup.py sdist bdist_wheel upload -r pypi

    OR for testPyPI

python setup.py register -r testpypi
python setup.py sdist bdist_wheel upload -r testpypi

Note

Twine is now the preferred way to register and upload projects for python version < 2.7.13

  1. If twine is available (it’s more secure than setup.py upload) and your .pypirc file is properly located and formatted, then try to upload package to PyPI using:

    twine upload dist/*

    OR for testPyPI

twine upload -r testpypi dist/*

  2. Test installing your project from PyPI (and/or testPyPI):

    pip install <package name>

    OR for testPyPI

pip install -i https://testpypi.python.org/pypi <package name>

    OR for testPyPI with PyPI_ Dependencies

pip install -i https://testpypi.python.org/pypi <package name> --extra-index-url https://pypi.python.org/pypi
  3. Run unittests on the install with a virtualenv or clean virtual machine.
    • Either nosetests or py.test should work
  4. Test the entry_points command from setup.py.
    • Should be able to simply run my_command from command line environment.

  5. Check the three main web pages for your project:

    The Code at: https://github.com/<github user name>/<package name>

The Docs at: http://<package name>.readthedocs.org/en/latest/

PyPI page at: https://pypi.python.org/pypi/<package name>
  6. Let the world know what you’ve done.