CWI Computational Imaging’s Python template
This is a template for starting your Python projects at CWI’s computational imaging group.
This template lets you easily set up a Python package for your own projects. It automatically creates a directory tree with sensible locations for your code, documentation and tests, and directly makes a number of useful tools available to more conveniently install, document and eventually publish your project.
This template is BSD licensed.
- Boilerplate for documentation with Sphinx
- Boilerplate for unit testing
- Setup configuration
- Conda packaging
- Software License
- A good initial README file
- Various files such as a changelog, a contributor guide, and more.
How to use
Step 1: Install cookiecutter
Install the latest Cookiecutter if you haven’t installed it yet (this requires Cookiecutter 1.4.0 or higher):
pip install -U cookiecutter
Step 2: Generate a new Python project
To generate a new project, execute the following in your terminal:
Cookiecutter will ask you some questions to get your project started.
|full_name||Your Name||Your full name, e.g. Alice Johnson|
|firstname.lastname@example.org||Your e-mail address|
|github_username||cicwi||The GitHub organization where you will host the code. Use your own GitHub username if you will host the code on your own page. It is nice to get this right, as several links will automatically be generated and link to your GitHub repository. You can always change this later with some judicious use of |
|project_name||Human readable project name||The name of your project as you would write it for fellow humans.|
|project_slug||cone_balls||The project name without spaces, dots, or hyphens. This is used as the directory name, GitHub repository name, and Python package name for instance.|
|project_short_description||Python CI CWI boilerplate package.||A short description of your package.|
|version||0.1.0||The initial version of your package. This is a good default.|
|use_pytest||n||Whether or not you want to use pytest as a testing framework. You can use the default ‘no’.|
|open_source_license||GPLv3||Which license you want your code to fall under. Our group recommends GPLv3.|
Step 3: Use your project
To start using version control execute the following code
cd your-project-name git init # Initialized the git repository git add . # Stages all files git commit -m "Initial commit" # Creates an initial commit
You can also create a GitHub repository. Once you have one, push your code there by executing
git remote add origin email@example.com:<your-GitHub-username>/<your-project-name>.git git push -u origin master
It is recommended you create a separate
conda environment for each
project you work on. Do this by executing
conda create -n <your-project-name> python=3.6 source activate <your-project-name>
python=3.6 in the command-line above. The project template
works best for versions of Python 3.6 and higher. In fact, it has not
been tested and might not work for older versions of Python at all.
The following command does two things. First of all, it installs your newly created package as “editable” into the Conda environment. This means that any change you make to the source files is reflected in the ‘installed’ package. Secondly, this command installs some required development tools used for documentation, testing, and linting.
Of course, once this is done, you can start writing software. You can
start by extending the script in
create more scripts in the
examples directory. Once you identify
common functionality, you can add functions to the main module file in
file contains examples how to call these functions.
Step 4: Sharing your code
To make your code usable for others, it is a good idea to have documentation, publish a Conda package, and release versioned code.
In your project’s README.md, you will find a checklist with steps to guide to a first release.
In any case, do not forget to:
- Update the README
- Keep a CHANGELOG
- Update your documentation using
- Create GitHub pages documentation
- Update version in
VERSIONfile for a new release
- Create releases on GitHub
Overview of generated files
If you create a new project called
following files will be created:
. ├── CHANGELOG.md # The changelog ├── conda # Conda packaging metadata │ ├── build.sh │ ├── conda_build_config.yaml │ └── meta.yaml ├── CONTRIBUTING.rst # Contributor guide ├── doc_sources # Boilerplate for documentation generation │ ├── conf.py │ ├── index.rst │ ├── ... ├── examples # Example scripts │ ├── getting_started.py ├── human_readable_project_name # Main source code directory │ ├── human_readable_project_name.py # Main module │ ├── __init__.py # Module dir │ └── VERSION # Version file ├── LICENSE.md # License ├── Makefile # Makefile: contains common 'make' recipes (see below) ├── MANIFEST.in # Boilerplate used for packaging ├── README.md # Readme ├── setup.cfg # Configuration for python tooling ├── setup.py # Packaging information for the package └── tests # Boilerplate for unit testing ├── __init__.py └── test_human_readable_project_name.py
The project comes with a default Makefile. The Makefile has a reasonable number of built-in commands.
Download and install development requirements into your current conda environment with
This command also install your current project as an “editable” project into your current Conda environment. This means that any change to your source files will be reflected in the “installed” environment.
Download and install your project requirements into your current conda environment with
Update the documentation.
Update your documentation with
Automatically reformat the code of your project to a common format with
Build conda package
builds a conda package, which you can share on https://anaconda.org/.
Authors and contributors
- Allard Hendriksen
- Jan-Willem Buurlage
- Willem Jan Palenstijn
- Daniël Pelt
How to contribute
Contributions are always welcome. Please submit a pull request.
If you have any issues, questions, or remarks, then please open an issue on GitHub.
This template is based on Audrey Roy Greenfeld’s cookiecutter-pypackage.
This project is licensed under the BSD License - see the
LICENSE file for details