========================
Python Package Generator

| | Generate Python Project and enjoy streamlined DevOps using a powerful CI/CD Pipeline. | | Documentation available at https://python-package-generator.readthedocs.io/.

What's included?

Generator of Python Project (see Quickstart_), with CLI for Linux, MacOS, and Windows
Option to Generate Python Package designed as module, module+cli, or pytest-plugin!
Scaffold over 24 files, from Template_, to have a ready-to-develop Project equipped with:
- Fully-featured CI/CD Pipeline, running on Github Actions_, defined in .github/
- Continuous Delivery to PyPI (i.e. pypi.org, test.pypi.org) and Dockerhub
- Continuous Integration, with Test Suite running pytest_, located in the tests dir
- Continuous Documentation, building with mkdocs or sphinx, and hosting on readthedocs, located in the docs dir
- Static Type Checking, using mypy_
- Lint Check and Apply commands, using the fast Ruff_ linter, along with standard isort, and black
- Build Command, using the build_ python package

What to expect?

You can to be up and running with a new Python Package, and run workflows on Github Actions, such as:

.. image is expected to mostly be rendered on github.com, pypi.org, readthedocs.io in any case we care for these pages. Adjust images props (ie width if needed)

.. image:: https://raw.githubusercontent.com/boromir674/cookiecutter-python-package/master/docs/assets/CICD-Pipe.png :alt: CI Pipeline, running on Github Actions, for a Biskotaki Python Package :align: center :width: 100%

Link: https://github.com/boromir674/biskotaki/actions/runs/4157571651

CI Pipeline, running on Github Actions_, defined in .github/

a. Job Matrix, spanning different platform's and python version's
1. Platforms: ubuntu-latest, macos-latest
2. Python Interpreters: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12
  b. Parallel Job execution, generated from the matrix, that runs the Test Suite
  c. Artifact store of Source and Wheel Distributions, factoring Platform and Python Version

Auto Generated Sample Package Biskotaki

Check the Biskotaki Python Package Project, for a taste of the project structure and capabilities this Template can generate!

It it entirely generated using this Python Package Template:

| Source Code hosted on Github at https://github.com/boromir674/biskotaki | Python Package hosted on pypi.org at https://pypi.org/project/biskotaki/ | CI Pipeline hosted on Github Actions at https://github.com/boromir674/biskotaki/actions

Quickstart

To install the latest Generator in your environment, run:

.. code-block:: shell

pip install cookiecutter-python

The generate-python (executable) CLI should now be available in your environment.

Next, create a file, let's call it gen-config.yml, with the following content:

.. code-block:: yaml

default_context:
    project_name: Demo Generated Project
    project_type: module+cli
    full_name: John Doe
    email: [email protected]
    github_username: john-doe
    project_short_description: 'Demo Generated Project Description'
    initialize_git_repo: 'no'
    interpreters: {"supported-interpreters": ["3.8", "3.9", "3.10", "3.11"]}

To generate a Python Package Project, run:

.. code-block:: sh

mkdir gen-demo-dir
cd gen-demo-dir

generate-python --config-file ../gen-config.yml --no-input

Now, you should have generated a new Project for a Python Package, based on the Template_!

The Project should be located in the newly created demo-generated-project directory.

To leverage all out-of-the-box development operations (ie scripts), install tox_:

.. code-block:: shell

python3 -m pip install --user 'tox==3.27.1'

To verify tox available in your environment, run: tox --version

Please, do a cd into the newly created directory, ie cd <my-great-python-package>.

To run the Test Suite, cd into the newly created Project folder, and run:

.. code-block:: shell

tox -e dev

All Tests should pass, and you should see a coverage report!

To run Type Checking against the Source Code, run:

.. code-block:: shell

tox -e type

All Type Checks should pass!

To setup a Git Repository, run:

.. code-block:: shell

git init
git add .
git checkout -b main
git commit -m "Initial commit"

To setup a Remote Repository, run for example:

.. code-block:: shell

git remote add origin <remote-repository-url>
git push -u origin main

To trigger the CI/CD Pipeline, run:

.. code-block:: shell

git push

Navigate to your github.com/username/your-repo/actions page, to see the CI Pipeline running!

| Develop your package's Source Code (business logic) inside src/my_great_python_package dir :) | Develop your package's Test Suite (ie unit-tests, integration tests) inside tests dir :-)

Read the Documentation's Use Cases_ section for more on how to leverage your generated Python Package features.

Next Steps

To prepare for an Open Source Project Development Lifecycle, you should visit the following websites:

PyPI, test.pypi.org, Dockerhub, and Read the Docs, for setting up Release and Documentation Pipelines
github.com/your-account to configure Actions, through the web UI
Codecov, Codacy, and Codeclimate, for setting up Automated Code Quality, with CI Pipelines
https://www.bestpractices.dev/ for registering your Project for OpenSSF Best Practices Badge

Happy Developing!