Python Boilerplate

.gitignore

#### --- Python.gitignore from github.com/github/gitignore ---

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
#  Usually these files are written by a python script from a template
#  before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/

# Translations
*.mo
*.pot

# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal

# Flask stuff:
instance/
.webassets-cache

# Scrapy stuff:
.scrapy

# Sphinx documentation
docs/_build/

# PyBuilder
.pybuilder/
target/

# Jupyter Notebook
.ipynb_checkpoints

# IPython
profile_default/
ipython_config.py

# pyenv
#   For a library or package, you might want to ignore these files since the code is
#   intended to run in multiple environments; otherwise, check them in:
# .python-version

# pipenv
#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
#   However, in case of collaboration, if having platform-specific dependencies or dependencies
#   having no cross-platform support, pipenv may install dependencies that don't work, or not
#   install all needed dependencies.
#Pipfile.lock

# poetry
#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
#   This is especially recommended for binary packages to ensure reproducibility, and is more
#   commonly ignored for libraries.
#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
#poetry.lock

# pdm
#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
#   in version control.
#   https://pdm.fming.dev/#use-with-ide
.pdm.toml

# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/

# Celery stuff
celerybeat-schedule
celerybeat.pid

# SageMath parsed files
*.sage.py

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/

# Spyder project settings
.spyderproject
.spyproject

# Rope project settings
.ropeproject

# mkdocs documentation
/site

# mypy
.mypy_cache/
.dmypy.json
dmypy.json

# Pyre type checker
.pyre/

# pytype static type analyzer
.pytype/

# Cython debug symbols
cython_debug

.pre-commit-config.yaml

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v2.3.0
    hooks:
      - id: check-case-conflict
      - id: check-json
      - id: check-toml
      - id: check-vcs-permalinks
      - id: check-xml
      - id: check-yaml
      - id: mixed-line-ending
      - id: requirements-txt-fixer
      - id: trailing-whitespace

  # Black formats python files without changing the AST
  - repo: https://github.com/psf/black
    rev: 22.3.0
    hooks:
      - id: black

  # Ruff is a black-compatible python linter written in rust
  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: "v0.0.247"
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]

README-TEMPLATE.md

$REPO_NAME

this repository serves as a template for integrating common tools (eg. pre-commit, pytest, clang-format, Ruff) in a common repository

Transferring to your repository

cp -i `git ls-tree --full-tree --name-only HEAD` ../path/to/your/repo

Note that running cp * ../path/to/repo will miss hidden files like .pre-commit-config, so it's advised to use the above command. It's probably worth staging and committing your changes here, just incase you don't like what the formatters/linters do next.

git add .
git commit -m

Follow all instructions in 'Setup' and then:

pre-commit run --all-files
git add .
git commit -m "Applied `pre-commit` rules"

Setup

Every time you clone this repository, you should:

1. Setup Python virtual environment in .venv folder
2. Activate virtual environment
3. Install python packages
4. Install pre-commit for pre-commit hooks

python -m venv .venv
source .venv/bin/activate
pip install -r dev_requirements.txt
pre-commit install

Workflow

On every new terminal session, activate your virtual environment:

source .venv/bin/activate

• This will prepend $GIT_DIR/.venv/bin/ to your path, allowing you to run pre-commit, pytest and clang-format. Note that clang-format is installed through pip, and is tied at the same version for all developers.
• I personally find this a chore to type, so I've added alias source-venv="source .venv/bin/activate" to my .bashrc.

Every time you run git commit, pre-commit will run formatters and linters against your staged changes. If your code fails, you'll get a screen that looks like this:

$ git commit
Check for case conflicts.................................................Passed
Check JSON...........................................(no files to check)Skipped
Mixed line ending........................................................Passed
Fix requirements.txt.................................(no files to check)Skipped
Trim Trailing Whitespace.................................................Failed
- hook id: trailing-whitespace
- exit code: 1
- files were modified by this hook

Fixing README.md

black................................................(no files to check)Skipped
ruff.................................................(no files to check)Skipped

Simply run git add -p to inspect and stage your commits.

dev_requirements.txt

# clang-format version should match version in `.pre-commit-config`
clang-format == 16.0.6
pre-commit
pytest

pyproject.toml

[tool.ruff]
select = [
  "E", # Pyflakes `E` and `F` codes enabled by default.
  "F",
  "I", # isort sorts imports
  "N", # pep8-naming for naming conventions
  "UP", # pyupgrade to upgrade python syntax
]

# Never enforce `E501` (line length violations).
ignore = ["E501"]

requirements.txt

pre-commit
pytest