The Velexi Python Project Cookiecutter is intended to streamline the process of setting up a Python project that
encourages the creation of high-quality software,
promotes developer efficiency, and
is distribution-ready.
Modern Python package structure (e.g., package metadata and tool configuration
specified in pyproject.toml)
Automated testing and coverage reporting framework (e.g., pytest, coverage, tox)
Integration with code quality tools (e.g., pre-commit, black, flake8, radon)
Continuous integration (CI) via GitHub Actions (e.g., testing, documentation deployment)
Quick references for software development tools (e.g., Poetry, pdoc, etc.)
Python package and dependency management using Poetry
Directory-based development environment isolation with direnv
2.1. License
2.2. Repository Contents
2.4. Setting Up to Develop the Cookiecutter
2.5. Additional Notes
project_name: project name
author: project’s primary author
email: primary author’s email
license: type of license to use for the project
python_version: Python versions compatible with project. See the
“Dependency sepcification” section
of the Poetry documentation for version specifier semantics.
github_repo_owner: owner of the GitHub repository for the project
enable_github_pages: flag indicating whether GitHub Pages should be enabled
for the project
ci_include_codecov: flag indicating whether the CI workflow should upload
coverage statistics to Codecov
ci_include_x86: flag indicating whether the CI workflow should include testing on
the x86 (32-bit) architecture
ci_include_macOS: flag indicating whether the CI workflow should include testing on
macOS
ci_include_windows: flag indicating whether the CI workflow should include testing on
Windows
Prerequisites
Install Git.
Install Python 3.9 (or greater).
Install Poetry 1.2 (or greater).
Note. The project template uses poetry instead of pip for
management of Python package dependencies.
Install the Cookiecutter Python package.
Optional. Install direnv.
Use cookiecutter to create a new Python project.
$ cookiecutter https://github.com/velexi-research/VLXI-Cookiecutter-Python.git
Set up a dedicated virtual environment for the project. Any of the common
virtual environment options (e.g., venv, direnv, conda) should work.
Below are instructions for setting up a direnv or poetry environment.
Note: to avoid conflicts between virtual environments, only one method should be used to manage the virtual environment.
direnv Environment. Note: direnv manages the environment for
both Python and the shell.
Prerequisite. Install direnv.
Copy extras/dot-envrc to the project root directory, and rename it to
.envrc.
$ cd $PROJECT_ROOT_DIR
$ cp extras/dot-envrc .envrc
Grant permission to direnv to execute the .envrc file.
$ direnv allow
poetry Environment. Note: poetry only manages the Python
environment (it does not manage the shell environment).
Create a poetry environment that uses a specific Python executable.
For instance, if python3 is on your PATH, the following command
creates (or activates if it already exists) a Python virtual environment
that uses python3 for the project.
$ poetry env use python3
For commands to use other Python executables for the virtual environment, see the Poetry Quick Reference.
Install the base Python package dependencies.
$ poetry install
Configure Git.
Install the Git pre-commit hooks.
$ pre-commit install
Optional. Set up a remote Git repository (e.g., GitHub repository).
Create a remote Git repository.
Configure the remote Git repository.
$ git remote add origin GIT_REMOTE
where GIT_REMOTE is the URL of the remote Git repository.
Push the main branch to the remote Git repository.
$ git checkout main
$ git push -u origin main
Note. When GitHub Pages are enabled, the “Build and Deploy Documentation” GitHub Actions job will fail until the GitHub Pages settings for the GitHub repository been configured (see Section #1.3).
Finish setting up the new Python project.
Verify the copyright year and owner in the copyright notice. If the
project is licensed under Apache License 2.0, the copyright notice is
located in the NOTICE file. Otherwise, the copyright notice is located
in the LICENSE file.
Update the base Python package dependencies to the latest available versions.
$ poetry update
Fill in any empty fields in pyproject.toml.
Customize the README.md file to reflect the specifics of the project.
Commit all updated files (e.g., poetry.lock) to the project Git
repository.
Add GitHub keys that are required for GitHub Actions workflows.
Codecov Token
These steps are needed only if the CI workflow includes uploading of
coverage statistics to Codecov (i.e., ci_include_codecov set to yes
when creating the project).
Log into Codecov and enable the project GitHub repository on Codecov.
Get the Codecov token for the repository by navigating to “Settings” from the project Codecov repo page.
From the project GitHub repository, navigate to “Settings” > “Secrets” (in the “Security” section of the side menu).
Add a repository secret named CODECOV_TOKEN.
Recommended. Customize the settings for the project GitHub repository.
Code Stability
From the project GitHub repository, navigate to “Settings” > “Branches” (in the “Code and automation” section of the side menu).
Set the default branch to main.
Add branch protection for the main branch and enable the following
configurations.
Require a pull request before merging
Require approvals
Recommendation: enable for projects with multiple active developers who can serve as reviewers
Warning: must be disabled for projects with a single developer
Require conversation resolution before merging
Do not allow bypassing the above settings
GitHub Actions Security
From the project GitHub repository, navigate to “Settings” > “Actions” > “General” (in the “Code and automation” section of the side menu).
Configure “Actions permissions”.
Select the most restrictive option and customize the sub-options.
Allow actions created by GitHub: yes
Allow actions by Marketplace verified creators: no
Allow specified actions and reusable workflows.
codecov/codecov-action@*,
snok/install-poetry@*,
Configure “Workflow permissions”.
Select “Read repository content permissions”.
Allow GitHub Actions to create and approve pull requests: no
From the project GitHub repository, navigate to “Settings” > “Pages” (in the “Code and automation” section of the side menu) and configure GitHub Pages to use “GitHub Actions” as its “Source”.
In the “About” section of the project GitHub repository, set “Website” to the URL for the project GitHub Pages.
That’s it! Every time the main branch is updated, the CI workflow will
automatically update the package documentation on GitHub Pages.
The contents of this cookiecutter are covered under the Apache License 2.0
(included in the LICENSE file). The copyright for this cookiecutter is
contained in the NOTICE file.
├── README.md <- this file
├── RELEASE-NOTES.md <- cookiecutter release notes
├── LICENSE <- cookiecutter license
├── NOTICE <- cookiecutter copyright notice
├── cookiecutter.json <- cookiecutter configuration file
├── pyproject.toml <- Python project metadata file for cookiecutter
│ development
├── poetry.lock <- Poetry lockfile
├── docs/ <- cookiecutter documentation
├── extras/ <- additional files that may be useful for
│ cookiecutter development
├── hooks/ <- cookiecutter scripts that run before and/or
│ after project generation
├── spikes/ <- experimental code
└── / <- cookiecutter template
See [tool.poetry.dependencies] section of pyproject.toml.
Set up a dedicated virtual environment for cookiecutter development.
See Step 3 from Section 2.1 for instructions on how to set up
direnv and poetry environments.
Install the Python packages required for development.
```shell $ poetry install
Install the Git pre-commit hooks.
$ pre-commit install
Make the cookiecutter better!
To update the Python dependencies for the template (contained in the
`` directory), use the following procedure to
ensure that Python package dependencies for developing the non-template
components of the cookiecutter (e.g., hooks/pre_gen_project.py) do not
interfere with Python package dependencies for the template.
Create a local clone of the cookiecutter Git repository to use for cookiecutter development.
$ git clone git@github.com:velexi-research/VLXI-Cookiecutter-Python.git
Use cookiecutter from the local cookiecutter Git repository to create an
instance of the template to use for updating Python package dependencies.
$ cookiecutter PATH/TO/LOCAL/REPO
In the instance of the template, perform the following steps to update the template’s Python package dependencies.
Set up a virtual environment for developing the template (e.g., a direnv environment).
Use poetry or manually edit pyproject.toml to (1) make changes to the
Python package dependency list and (2) update the versions of the package
dependencies.
Use poetry to update the Python package dependencies and versions recorded
in the poetry.lock file.
Update /pyproject.toml.
Copy pyproject.toml from the instance of the template to
/pyproject.toml.
Restore the templated values in the [tool.poetry] section to the
following:
[tool.poetry]
name = "{{ cookiecutter.__project_name }}"
version = "0.1.0"
description = ""
license = "{% if cookiecutter.license == 'Apache License 2.0' %}Apache-2.0{% elif cookiecutter.license == 'BSD-3-Clause License' %}BSD-3-Clause{% elif cookiecutter.license == 'MIT License' %}MIT{% endif %}"
readme = "README.md"
authors = ["{{ cookiecutter.author }} <{{ cookiecutter.email }}>"]
Update /poetry.lock.
poetry.lock from the instance of the template to
/poetry.lock.Commit the updated pyproject.toml and poetry.lock files to the Git
repository.