Velexi Python Package Cookiecutter

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.

Features

• 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

---

Table of Contents

1. Usage

   1.1 Cookiecutter Parameters

   1.2 Setting Up a New Project

   1.3 Publishing Package Documentation to GitHub Pages

2. Contributor Notes

   2.1. License

   2.2. Repository Contents

   2.3. Software Requirements

   2.4. Setting Up to Develop the Cookiecutter

   2.5. Additional Notes

3. Documentation

---

1. Usage

1.1. Cookiecutter Parameters

• 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

1.2. Setting Up a New Project

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

2. Use cookiecutter to create a new Python project.

   $ cookiecutter https://github.com/velexi-research/VLXI-Cookiecutter-Python.git

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

4. Install the base Python package dependencies.

   $ poetry install

5. 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).

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

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

   1. Log into Codecov and enable the project GitHub repository on Codecov.

   2. Get the Codecov token for the repository by navigating to "Settings" from the project Codecov repo page.

   3. From the project GitHub repository, navigate to "Settings" > "Secrets" (in the "Security" section of the side menu).

   4. Add a repository secret named CODECOV_TOKEN.

8. Recommended. Customize the settings for the project GitHub repository.

   Code Stability

   1. From the project GitHub repository, navigate to "Settings" > "Branches" (in the "Code and automation" section of the side menu).

   2. Set the default branch to main.

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

   1. From the project GitHub repository, navigate to "Settings" > "Actions" > "General" (in the "Code and automation" section of the side menu).

   2. 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@*,
          

   3. Configure "Workflow permissions".

      • Select "Read repository content permissions".

      • Allow GitHub Actions to create and approve pull requests: no

1.3. Publishing Package Documentation to GitHub Pages

1. 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".

   • Source: GitHub Actions

2. In the "About" section of the project GitHub repository, set "Website" to the URL for the project GitHub Pages.

3. That's it! Every time the main branch is updated, the CI workflow will automatically update the package documentation on GitHub Pages.

---

2. Contributor Notes

2.1. License

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.

2.2. Repository Contents

├── 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.name}}/  <- cookiecutter template

2.3. Software Requirements

Base Requirements

• Git
• Python (>=3.9)
• Poetry (>=1.2)

Optional Packages

• direnv

Python Packages

See [tool.poetry.dependencies] section of pyproject.toml.

2.4. Setting Up to Develop the Cookiecutter

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

2. Install the Python packages required for development.

   $ poetry install
   

3. Install the Git pre-commit hooks.

   $ pre-commit install

4. Make the cookiecutter better!

2.5. Additional Notes

Updating Template Dependencies

To update the Python dependencies for the template (contained in the {{cookiecutter.__project_name}} 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 {{cookiecutter.__project_name}}/pyproject.toml.

  • Copy pyproject.toml from the instance of the template to {{cookiecutter.__project_name}}/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 {{cookiecutter.__project_name}}/poetry.lock.

  • Copy poetry.lock from the instance of the template to {{cookiecutter.__project_name}}/poetry.lock.

• Commit the updated pyproject.toml and poetry.lock files to the Git repository.

---

3. Documentation

• Poetry Quick Reference

---