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.
See also¶
Python packaging recommendations: