User documentation

Getting started

For a new project, run ct-mkproject. You’ll be prompted for information and the project structure will be generated. For details on which files are created and/or managed by ct-mkproject, see ct-mkproject --help.

ct-mkproject can also be used on an existing project, though you may want to restructure your project structure according to the one expected by ct-mkproject (see ct-mkproject --help)

Project info

Instead of managing setup.py directly, you specify your project info in project.py in a format that resembles setuptools.setup. When project.py does not exist, ct-mkproject will create a template of it for you, which includes documentation of the options.

Project invariants

Having run ct-mkproject once, you will never have to call it again. It will have installed a git pre-commit hook that ensures the project state is up to date and valid at each commit.

This ensures that for all of your (future) commits:

  • there are no errors in the documentation (i.e. sphinx-build encounters no errors or warnings)
  • there is a LICENSE.txt, a README file, ...
  • the version is up to date across the project

Further, it is guaranteed that any release commit can be checked out and having run ct-mkvenv, all tests will succeed. This also holds for non-release commits with no editable requirements. (editable requirements cannot be pinned in requirements.txt, so when you later revisit such a commit, the editable requirement may have changed (e.g. an amended commit)).

Managing dependencies

Required dependencies should be listed in requirements.in, optional dependencies should be listed in ${name}_requirements.in. A requirements.txt file will be generated from these files using pip-compile (pip-tools), containing both required and optional dependencies. Required dependencies will appear in setup.py‘s install_requires. Optional dependencies will appear in extras_require with $name as key, e.g. test_requirements.in corresponds to extras_require['test'].

Package data

Package data can be provided by placing a directory named data in the package you want to add data to. The data directory should not have a __init__.py (as direct descendant) as that would make it a package instead of a data directory.

You can then access this data (regardless of whether and how the project is installed) using pkg_resources.

Testing

Tests must be placed in $package_name.tests or a sub-package thereof. Tests are run from within the venv using py.test. To enter the venv, run . venv/bin/activate.

To get a coverage report, run: py.test --cov=$your_project_name.

Documenting

Sphinx is used to generate documentation. ct-mkproject generates a docs directory containing the source of the documentation of the project. Running ct-mkdoc compiles the documentation to html, which can be viewed at docs/build/html.

Releasing to Python indices

To release your project to a Python index (e.g. PyPI, devpi), use ct-release. This ensures releases are made correctly. Simply call ct-release VERSION with the version you want to release. ct-release will first validate the project and build the documentation before trying to release it. Then it sets the version in the relevant files, adds a commit, tags it with the version, releases the project to a test index and finally it releases to the production index and pushes all commits in the working directory.

Versions should adhere to PEP-0440 and use semantic versioning. Versions are only set on release commits made by ct-release. At any other time, setup.py‘s version is 0.0.0. If you need to refer to a specific unreleased commit, use the commit’s id instead.

Deployment

Chicken Turtle Project does not enforce a particular methodology for deployments, but we recommend shell scripts for simple deployments as they don’t have dependencies (assuming you only deploy to unix-like machines). If you need to do more complex work such as migrating data to a new database structure, include a Python script and call it from the shell script after having made the venv.