examplepackage

---

is a template for a strict package build using my python cookiecutter template.

📝 Table of Contents

• Usage
• Features
• Roadmap
• Getting Started
• Deployment
• Usage
• Built Using
• Contributing
• Authors
• Acknowledgments

🏁 Getting Started

To add and install this package as a dependency of your project, run poetry add examplepackage.

Prerequisites

1. Set up Git to use SSH

1. Generate an SSH key and add the SSH key to your GitHub account.

2. Configure SSH to automatically load your SSH keys:

   cat << EOF >> ~/.ssh/config
   Host *
     AddKeysToAgent yes
     IgnoreUnknown UseKeychain
     UseKeychain yes
   EOF

2. Install Docker

1. Install Docker Desktop.
   • Enable Use Docker Compose V2 in Docker Desktop's preferences window.
   • Linux only:

     • Export your user's user id and group id so that files created in the Dev Container are owned by your user:

       cat << EOF >> ~/.bashrc
       export UID=$(id --user)
       export GID=$(id --group)
       EOF

3. Install VS Code or PyCharm

1. Install VS Code and VS Code's Dev Containers extension. Alternatively, install PyCharm.
2. Optional: install a Nerd Font such as FiraCode Nerd Font and configure VS Code or configure PyCharm to use it.

Development environments

The following development environments are supported:

1. ⭐️ GitHub Codespaces: click on Code and select Create codespace to start a Dev Container with GitHub Codespaces.
2. ⭐️ Dev Container (with container volume): click on Open in Dev Containers to clone this repository in a container volume and create a Dev Container with Cursor AI/VS Code.
3. Dev Container: clone this repository, open it with Cursor AI/VS Code, and run Ctrl/⌘ + ⇧ + P → Dev Containers: Reopen in Container.
4. PyCharm: clone this repository, open it with PyCharm, and configure Docker Compose as a remote interpreter with the dev service.
5. Terminal: clone this repository, open it with your terminal, and run docker compose up --detach dev to start a Dev Container in the background, and then run docker compose exec dev zsh to open a shell prompt in the Dev Container.

Features

• 🧑‍💻 Quick and reproducible development environments with VS Code's Dev Containers, PyCharm's Docker Compose interpreter, and GitHub Codespaces
• 🌈 Cross-platform support for Linux, macOS (Apple silicon and Intel), and Windows
• 🐚 Modern shell prompt with Starship
• 📦 Packaging and dependency management with Poetry
• 🌍 Environment management with Micromamba
• 📖 Comprehensive documentation generation with Sphinx or pdoc
• 🚚 Installing from and publishing to private package repositories and PyPI
• ⚡️ Task running with Poe the Poet
• ✍️ Code formatting with Ruff
• ✅ Code linting with Pre-commit, Mypy, and Ruff
• 🏷 Optionally follows the Conventional Commits standard to automate Semantic Versioning and Keep A Changelog with Commitizen
• 💌 Verified commits with GPG
• ♻️ Continuous integration with GitHub Actions or GitLab CI/CD
• 🧪 Test coverage with Coverage.py
• 🏗 Scaffolding updates with Cookiecutter and Cruft
• 🧰 Dependency updates with Dependabot

🚗 Roadmap

• Add support for Nox for automated testing across various platforms and python versions.

🏗️ Development Setup

• This project follows the Conventional Commits standard to automate Semantic Versioning and Keep A Changelog with Commitizen.
• Run poe from within the development environment to print a list of Poe the Poet tasks available to run on this project.
• Run poetry add {package} from within the development environment to install a run time dependency and add it to pyproject.toml and poetry.lock. Add --group test or --group dev to install a CI or development dependency, respectively.
• Run poetry update from within the development environment to upgrade all dependencies to the latest versions allowed by pyproject.toml.
• Run cz bump to bump the package's version, update the CHANGELOG.md, and create a git tag, settings can be made in both cz-config.js and bumpversion.yml.

🎣 Hooks

This project uses two hooks, pre_gen_project.py and post_gen_project.py, which are scripts that run before and after the project generation process, respectively.

This section shows users how to setup your environment using your micromamba file and poetry.

Setup Mamba Environment (w/Poetry)

This project uses a micromamba environment. The micromamba environment will be automatically setup for you after generating the project from the template using a post_gen_project hook. The following steps are for reference only (if you need to recreate the environment). This assumes you use bash as your shell.

Prerequisites

1. Installing `micromamba`

# Windows (Powershell)
Invoke-Expression ((Invoke-WebRequest -Uri https://micro.mamba.pm/install.ps1).Content)

# Linux and macOS
"${SHELL}" <(curl -L micro.mamba.pm/install.sh)

Creating Micromamba Environment

1. I created the environment with a --prefix and not a name, to ensure that it installed in my project directory, not the default path. This is executed in the project root dir.

   micromamba env create --file micromamba_env.yml

2. To avoid displaying the full path when using this environment, modify the .condarc file to show the environment name as the last directory where the environment is located. This can be done manually or by running the command micromamba config --set env_prompt '({name})'.

   micromamba config --set env_prompt '({name})'

   After the modification, your .condarc file should look like this:

   channels:
     - conda-forge
     - defaults
   env_prompt: ({name})
   repodata_threads: 2
   change_ps1: false
   envs_dirs:
     - ~/micromamba/envs

3. Activate the environment

   micromamba init bash / micromamba init zsh
   micromamba activate ./menv

4. Check if poetry is installed

   poetry --version
   # make sure it is the latest version
   # can use mamba search -f poetry

5. If poetry is showing any errors like:

   • Failed to create process
   • No Python at <path>

   You can simply run:

   micromamba remove -p ./menv poetry 
   micromamba install -p ./menv poetry 

6. If the python version doesnt match, just install the version you would like:

   micromamba install -p ./menv python=3.12.1

7. Install Packages from poetry.lock / pyproject.toml

   poetry install

Setting Up `Commitizen`

I am using the `vscode-commmitizen` extension to integrate `commitizen` into my workflow. This allows for nice keyboard shortcuts and UI integration. I have also installed `cz_customizable` globally to allow me to customize the commit message template using `cz-config.js`.

The pyproject.toml file has the specifications for cz_customizable and commitizen to work together.

Follow the quickstart guide and use the 'Quick Start' section to setup cz-customizable. You need to install cz-customizable globally in order for the vscode extension to work along with the settings provided in the pyproject.toml file.

• make sure you have a pre-commit-config.yml
• make sure you have a bumpversion.yml in .github/workflows

⚡️ GitHub Workflow Setup

There are 5 pre-made github actions that are used with this template. SOme require API_KEYS/TOKENS to work. Add your tokens to the secrets manager in your repo settings.

1. bump.yml: This workflow automates the versioning of the project using bumpversion.
   • Uses a GitHub PERSONAL_ACCESS_TOKEN
2. deploy.yml:
   • This workflow is responsible for deploying the project. It is triggered on push events that include tags in the format "v*.." and also manually through the GitHub Actions UI.
   • The workflow runs on an Ubuntu-latest environment and only if the GitHub reference starts with 'refs/tags/v'.
   • The steps involved in this workflow include:
     • Checking out the repository.
     • Logging into the Docker registry.
     • Setting the Docker image tag.
     • Building and pushing the Docker image.
   • The tokens/secrets used in this workflow include:
     • GITHUB_TOKEN: This is a GitHub secret used for authentication.
     • DOCKER_REGISTRY: This is an environment variable set to 'ghcr.io'.
     • DEFAULT_DEPLOYMENT_ENVIRONMENT: This is an environment variable set to 'feature'.
     • POETRY_HTTP_BASIC__USERNAME: This is a secret used for authentication with the private package repository.
     • POETRY_HTTP_BASIC__PASSWORD: This is a secret used for authentication with the private package repository.
3. publish.yml: This workflow is responsible for publishing the project. It is triggered when a new release is created. The workflow runs on an Ubuntu-latest environment.
   • The steps involved in this workflow include:
     • Checking out the repository.
     • Setting up Python with the specified version.
     • Installing Poetry, a tool for dependency management and packaging in Python.
     • Publishing the package using Poetry. If a private package repository is specified, the package is published there. Otherwise, it is published to PyPi.
   • The tokens/secrets used in this workflow include:
     • GITHUB_TOKEN: This is a GitHub secret used for authentication.
     • POETRY_HTTP_BASIC__USERNAME: This is a secret used for authentication with the private package repository.
     • POETRY_HTTP_BASIC__PASSWORD: This is a secret used for authentication with the private package repository.
     • POETRY_PYPI_TOKEN_PYPI: This is a secret used for authentication with PyPi, if the package is being published there.
4. test.yml:
   • This workflow is responsible for testing the project. It is triggered on push events to the main and master branches, and on pull requests.
   • The workflow runs on an Ubuntu-latest environment and uses the specified Python version.
   • The steps involved in this workflow include:
     • Checking out the repository.
     • Setting up Node.js with the specified version.
     • Installing @devcontainers/cli.
     • Starting the Dev Container.
     • Linting the package.
     • Testing the package.
     • Uploading coverage.
   • The tokens/secrets used in this workflow include:
     • GITHUB_TOKEN: This is a GitHub secret used for authentication.

🔧 Running the tests

Explain how to run the automated tests for this system. This project is setup for using nox.

Break down into end to end tests

Explain what these tests test and why

Give an example

And coding style tests

Explain what these tests test and why

Give an example

🚀 Deployment

Add additional notes about how to deploy this on a live system.

⛏️ Built Using

• Python - Programming Language

✍️ Authors

• @jjfantini - Idea & Initial work
• @cookiecutter.github_username - Additional Contributions

See also the list of contributors who participated in this project.

🎉 Acknowledgements

• Hat tip to anyone whose code was used
• Inspiration
• References

----- Extra Info -----

Python Project Template

This project is a template for creating Python projects that follows the Python Standards declared in PEP 621. It uses a pyproject.yaml file to configure the project and poetry to simplify the build process and publish to PyPI. You can manage all relevant configurations within the pyproject.toml file, streamlining development and promoting maintainability by centralizing project metadata, dependencies, and build specifications in one place.

Project Organization

• .github/workflows: Contains GitHub Actions used for building, testing, and publishing.
• .devcontainer/Dockerfile: Contains Dockerfile to build a development container for VSCode with all the necessary extensions for Python development installed.
• .devcontainer/devcontainer.json: Contains the configuration for the development container for VSCode, including the Docker image to use, any additional VSCode extensions to install, and whether or not to mount the project directory into the container.
• .vscode/settings.json: Contains VSCode settings specific to the project, such as the Python interpreter to use and the maximum line length for auto-formatting.
• src: Place new source code here.
• tests: Contains Python-based test cases to validate source code.
• pyproject.toml: Contains metadata about the project and configurations for additional tools used to format, lint, type-check, and analyze Python code.
• .prompts/: Contains useful prompts to use during development for modifying and generating code and tests.