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.

Features include:

• 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 https://github.com/cicwi/cookiecutter-cicwi.git

Cookiecutter will ask you some questions to get your project started.

Question	Default	Description
full_name	Your Name	Your full name, e.g. Alice Johnson
email	example@example.com	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 grep
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 git@github.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>

Note the 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.

make install_dev

Of course, once this is done, you can start writing software. You can start by extending the script in examples/getting_started.py, or create more scripts in the examples directory. Once you identify common functionality, you can add functions to the main module file in your_project_slug/your_project_slug.py. The getting_started.py 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:

1. Update the README
2. Keep a CHANGELOG
3. Update your documentation using make docs
4. Create GitHub pages documentation
5. Update version in VERSION file for a new release
6. Create releases on GitHub

Overview of generated files

If you create a new project called human_readable_project_name, the 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

Make commands

The project comes with a default Makefile. The Makefile has a reasonable number of built-in commands.

Development requirements

Download and install development requirements into your current conda environment with

make install_dev

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.

Install requirements

Download and install your project requirements into your current conda environment with

make install

Update the documentation.

Update your documentation with

make docs

Code formatting

Automatically reformat the code of your project to a common format with

make style

Build conda package

The command

make 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.

Acknowledgements

This template is based on Audrey Roy Greenfeld’s cookiecutter-pypackage.

License

This project is licensed under the BSD License - see the LICENSE file for details