Cookiecutter for creating open source Python packages

Last update: Dec 22, 2022

Overview

Wolt Python Package Cookiecutter

Cookiecutter for rapidly developing new open source Python packages. Best practices with all the modern bells and whistles included.

Example projects which use Wolt Python Package Cookiecutter

jerry-git/pytest-split

Features

Automatic updates to the projects generated from this cookiecutter

Powered by cruft
Keep your project up-to-date with best practices

Continuous integration

Powered by Github Actions
Testing against multiple different versions

Documentation

Automatically published as GitHub Pages
Powered by mkdocs-material
Auto-generated API documentation from docstrings via mkdocstrings
See the extensive list of MkDocs plugins which can help you to tune the documentation to fit your project's needs

Automated releases

Publishing to PyPI when a release is made in GitHub

Changelog management

Gently enforced: Keep a Changelog
GitHub releases get their description automatically populated based on the changelog content
The Unreleased section is automatically updated when a release is done
Changelog is embedded in the documentation

Bells and whistles

Poetry for managing dependencies and packaging
pre-commit for running all the goodies listed below
mypy for static type checking
flake8 (with multiple plugins) for linting (e.g. style and complexity checks)
black for auto-formatting the code
isort for auto-sorting imports
autoflake for auto-removing unused imports

Automation

Updates to the best practices (via GHA workflow which runs cruft update and creates a PR)
Dependency updates (via GHA workflow which creates a PR)

Usage

Make sure you have cruft installed. Alternatively, you can use cookiecutter if you are not interested in getting updates to the project "boilerplate" in the future.

Create a new project:

cruft create https://github.com/woltapp/wolt-python-package-cookiecutter

The CLI interface will ask some basic questions, such the name of the project, and then generate all the goodies automatically.

After that you can make it a proper git repo:

cd <your-project-slug>
git init
git add .
git commit -m "Initial project structure from Wolt Python Package cookiecutter"

We update this cookiecutter template regularly to keep it up-to-date with the best practices of the Python world. You can get the updates into your project with:

cruft update

Configure secrets

`PYPI_TOKEN`

Required for publishing the package to PyPI. You can generate a token by logging into PyPI and navigating to Add API token in your account settings.

`AUTO_UPDATE_GITHUB_TOKEN`

This cookiecutter template comes with an auto update feature if the project was created using cruft. A GitHub action automatically checks for updates and creates a pull request.

Generate personal access token and use it as the value for AUTO_UPDATE_GITHUB_TOKEN secret. When creating the access token, the following permissions have to be granted

repo
workflow

After the first release

The first release will create gh-pages branch which will contain the static files for the documentation. Enable GitHub Pages in the Pages section of the repository settings.

Comments

`python-kacl` depends on `pychalk` 2.0.1 which is incompatible with Python 3.10

I love this template! I just published my first package with this template. One problem though. When running poetry install and during the CI, it fails. How do I fix this??

opened by IceBotYT 3
fix: autoupdate is broken due to changed GHA behaviour

The auto update does not work anymore. Unfortunately, the pipeline is still reported as successfully... thus we have to manually update all repositories.

This solution is much much simpler and has not external dependency. See https://github.com/UnicornGlobal/has-changes-action/issues/5 for more information.

opened by escaped 1
Update mkdocstrings

They apparently flipped the show_submodules default value to False at some point. Also, they stopped shipping the Python handler so it needs to be explicitly added as requirement.

opened by jerry-git 0
Support for shellcheck and verify generated project.

Actionlint lints our workflow. When it was integrated, we weren't aware that an accompanying script (shellcheck) is used as well if available. This PR fixes our workflows and makes sure that all workflows and project files are validated on CI.

opened by escaped 0
lint workflows

It's easy to screw up the workflows. Let's validate them beforehand :)

It's also possible to integrate it into pre-commit, but the downside of that approach is that actionlint needs to be manually installed on the system. Using docker would be an option, but I don't think it's a good idea to force everyone to have docker installed.

opened by escaped 0
Update `actions/setup-python` version
Hi! 👋

Since actions/setup-python@v2 has some deprecation warnings, the version can be upgraded to v4. More info:

https://github.com/actions/setup-python/issues/526

https://github.com/joaopalmeiro/cloack/actions/runs/3629587864/jobs/6121966272
opened by joaopalmeiro 0
Remove version pinning of actionlint

Currently pinned to 1.6.21 (see https://github.com/woltapp/wolt-python-package-cookiecutter/pull/26). The next version requires a number of changes in the workflow yamls.

opened by jerry-git 0

question: why not mypy strict?

Hi,

In your article and this project, a few MyPy configurations are setuped.

I wonder why MyPy strict is not replacing some of them?

For instance, MyPy version 0.942 defines --strict as:

  --strict                  Strict mode; enables the following flags: --warn-unused-configs,
                            --disallow-any-generics, --disallow-subclassing-any, --disallow-
                            untyped-calls, --disallow-untyped-defs, --disallow-incomplete-
                            defs, --check-untyped-defs, --disallow-untyped-decorators, --no-
                            implicit-optional, --warn-redundant-casts, --warn-unused-ignores,
                            --warn-return-any, --no-implicit-reexport, --strict-equality

opened by tomsquest 0

Update pre-commit and other good checks to add

Pre-commit is up to 4.3.0 from 4.0.1 (can usually run pre-commit autoupdate)

Also just a few suggestions for good things to have for most repos:

    # Identify invalid files
    - id: check-ast                        
    - id: check-yaml                       
    - id: check-json                       
    - id: check-toml                       

    # git checks
    - id: check-merge-conflict             
    - id: check-added-large-files          
    - id: detect-private-key               
    - id: check-case-conflict              

    # Python checks
    - id: check-docstring-first            
    - id: debug-statements                 
    - id: requirements-txt-fixer           
    - id: fix-encoding-pragma              
    - id: fix-byte-order-marker            

    # General quality checks
    - id: mixed-line-ending                
    - id: trailing-whitespace              
      args: [--markdown-linebreak-ext=md]  
    - id: check-executables-have-shebangs  
    - id: end-of-file-fixer

opened by cdgriffith 0

Cookiecutter for creating open source Python packages

Related tags

Overview

Wolt Python Package Cookiecutter

Example projects which use Wolt Python Package Cookiecutter

Features

Automatic updates to the projects generated from this cookiecutter

Continuous integration

Documentation

Automated releases

Changelog management

Bells and whistles

Automation

Usage

Configure secrets

PYPI_TOKEN

AUTO_UPDATE_GITHUB_TOKEN

After the first release

Comments

Owner

Wolt

Open Source Intelligence gathering tool aimed at reducing the time spent harvesting information from open sources.

A python script to turn Ubuntu Desktop in a one stop security platform. The InfoSec Fortress installs the packages,tools, and resources to make Ubuntu 20.04 capable of both offensive and defensive security work.

This tool ability to analyze software packages of different programming languages that are being or will be used in their codes, providing information that allows them to know in advance if this library complies with processes.

A python tool capable of creating HUGE wordlists. Has the ability to add custom words for concatenation in any way you see fit.

A wordlist generator tool, that allows you to supply a set of words, giving you the possibility to craft multiple variations from the given words, creating a unique and ideal wordlist to use regarding a specific target.

Open source vulnerability DB and triage service.

An open-source post-exploitation framework for students, researchers and developers.

LinOTP - the open source solution for two factor authentication

🔍 IRIS: An open-source intelligence framework

Open Source Tool - Cybersecurity Graph Database in Neo4j

Dependency Combobulator is an Open-Source, modular and extensible framework to detect and prevent dependency confusion leakage and potential attacks.

Scout Suite - an open source multi-cloud security-auditing tool,

Linus-png.github.io - Versionsverwaltung & Open Source Hausaufgabe

Red Team Toolkit is an Open-Source Django Offensive Web-App which is keeping the useful offensive tools used in the red-teaming together.

SCodeScanner stands for Source Code scanner where the user can scans the source code for finding the Critical Vulnerabilities.

ORector - A Fast Python tool designed to detect open redirects vulnerabilities on websites

Dome - Subdomain Enumeration Tool. Fast and reliable python script that makes active and/or passive scan to obtain subdomains and search for open ports.

A tool for making python source difficult to read.

`PYPI_TOKEN`

`AUTO_UPDATE_GITHUB_TOKEN`