README.md

Python Project Cookiecutter Template

This is a template to bootstrap a Python Project including the setup for the KM3NeT CI facilities.

Usage

You need to install cookiecutter on your computer first:

pip install cookiecutter

To bootstrap a Python project, run:

cookiecutter https://git.km3net.de/templates/python-project.git

and fill the required metadata. After filling the required metadata, a folder is created inside the working directory. The name of this folder depends on the metadata provided after running the cookiecutter command above. Here, we asume that this folder is named project_dir. This is folder is the base directory of the new python project.

Files and directories inside the python project

cookiecutter uses the provided metadata to generate a set of files and directories inside the project_dir folder. These files are necessary to package and distribute python projects with (setuptools)[https://packaging.python.org/en/latest/key_projects/#setuptools]:

LICENSE

This file describes under which conditions the python project is or will be made available. The default LICENSE is MIT, feel free to replace it with the one you prefer.

CHANGELOG.rst

Open-source projects often include a changelog file as one of the top-level files in the base directory. The changelog file is a record of all the significant changes made to the project such as bug fixes or new features. There are ways of automating the changelog update based on the git commit messages. One can also edit the CHANGELOG.rst file manually and write the relevant changes there.

CONTRIBUTING.rst

This file contains guidelines for external users who would like to contribute to the project.

setup.py

This file is normally located in the base direcotry of a python project, and it is the most basic requirement for packaging a python project. It defines the configuration of the python project, and it is used by setuptools to ensure that this configuration is created at the time of building and using the package. The most important feature of this file is the call to a setup() function, to setup the environment. This can receive multiple arguments. In this template, the arguments used in the call to the setup() function are obtained from the metadata provided after running the cookiecutter command above. A list of the most relevant arguments and their description is given (here)[https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#setup-args]. This template includes the following arguments:

• name: Name of the project
• url: Url of the project
• description: A short description of the project
• long_description: A longer description of the project
• author: Name of the author of the project
• author_email: email-address of the author of the project
• packages: list of packages and subpackages in the project. This list of packages will be made available from the python environment after installing it. By default, the packages argument includes a single package with the same name as the project name. A package is a folder which includes a file named __init__.py and some other source files. This default package is also generated by the cookiecutter (see below).
• include_package_data: Set to True by default. It installs data files if these are specified in the MANIFEST.in file. See below.
• platforms: List of strings indicating what platforms is the project expected to be used from. The default value is set to ['any'].
• setup_requires: A string or list of strings specifying what other distributions need to be present in order for the setup script to run. See (here)[https://setuptools.pypa.io/en/latest/userguide/keywords.html]
• use_scm_version: By default is set to true. If scm (source control management) version is used, then versions of the python software are tracked and assoiated to versions of the git repository.
• python_requires: Specifies required python versions. By default set to >=3.6
• install_requires: Specifies list of dependencies for this project. These are installed by pip when typing make (see below). Instead of writing the list on the setup.py file, this template provides a file located on <project_dir>/requirements/install.txt. This file is parsed at install time and each of the depencencies defined within, are used as install_requires argument.
• extras_require: The same as install_requires, but used when the code is built in developer mode. In this case, the dependencies are specified on the file <project_dir>/requirements/install.txt.
• classifiers: Specifies classifiers for the project. Read more about it (here)[https://pypi.org/classifiers/]

Makefile

It declares multiple recipes for the project which include install, install_dev, clean, and multiple test recipes.

Additional Setup

After filling in the required metadata, create a Git repository on https://git.km3net.de/projects/new and proceed with the repository initialisation:

cd project_dir
git init
git add .
git commit -m 'Initial commit'
git tag -a 'vX.Y.Z' -m 'Release X.Y.Z'
git remote add origin git@git.km3net.de:YOURUSERNAME_OR_GITGROUP/PROJECT.git
git push -u origin master
git push --tags

Features

• unit tests
• automatic documentation generation
• API documentation
• continuous integration on the KM3NeT GitLab server
• and more...