Skip to content
/ templatepy Public template

Template repository for best-practice Python packages

License

Notifications You must be signed in to change notification settings

larsrollik/templatepy

Contributions DOI Website PyPI Wheel CI Code style: black pre-commit

templatepy

Template repo for python repositories & PyPi integration

Version: "0.0.3"

Usage

  1. Change files according to overview in TODO below
  2. Develop package...
  3. Install package:
    • static/normal install: pip install .
    • editable install:pip install -e .
    • dev install: pip install -e .[dev] (some terminals require to escape brackets with \ as \[, esp. zsh)

File overview

General

  • LICENSE: license text

  • README.md: Github-flavored markdown file

  • templatepy: placeholder folder for any python package that is configured for install via setup.cfg and pyproject.toml

    • __init__.py: contains basic package info and example function that is called by console entrypoint (see setup.cfg)
    • example.data.file.config: a file to demonstrate that data files are included based on setup.cfg criteria
    • example.data.file.test-extension-yu48: a file to demonstrate data exclusion via setup.py

Testing

  • tests: placeholder folder for unit/integration tests and associated data
  • pytest.ini: config for testing framework with pytest and coverage plugin (pytest-cov)

Packaging system (see: packaging and setup.cfg)

  • MANIFEST.in: manifest file describes included/excluded files for build

  • pyproject.toml:

    • specifies build system: this replaces the usual setup.py architecture for setuptools
    • config for black code formatter
  • setup.cfg:

    • package specification and install dependencies
    • config for flake8 formatting (see pre-commit)
  • setup.py: legacy file (see notes on new build-system below)

Code maintenance (linting/formatting/github)

  • .pre-commit-config.yaml: use pre-commit to run code formatting (e.g. with black and flake8) and PEP compliance checks

    • Install pre-commit hook with pre-commit install (Note: only installs it in the current virtual environment)
    • Run it manually with pre-commit run --all or leave it to run on commit (requires to re-stage changed files!)
  • .github: folder that contains github automation workflows and issues templates

  • .gitignore: ignored files/folders in git tools

  • .bumpversion.cfg: config for bump2version

TODO for adapting template to new project

  • Change package name:
    • (1) templatepy folder
    • (2) README.md
    • (3) name argument in setup.cfg
    • (4) .github/workflows files
    • (5) setup.cfg: [bumpversion:file:templatepy/__init__.py]
  • Change details about project author, etc. in setup.cfg, README.md, and templatepy/__init__.py
  • Change license holder in LICENSE
  • Change README badge paths at top
  • Verify inclusions/exclusions of installable files/folders in MANIFEST.in and setup.cfg
  • Check .gitignore contains relevant criteria
  • Add all version string locations to setup.cfg/bump2version field.
    • Use same syntax as for [bumpversion:file:PACKAGEFOLDER/__init__.py] line to describe how to find version on version increment
  • To upload to pypi: see below for workflow
  • To upload to Zenodo if repo is a publication:
    • (1) Connect Zenodo to Github account
    • (2) Flip switch on zenodo view of repo - NOTE: Zenodo can only copy from public repos
    • (3) Create new release version of github repo (manual or via .github/workflows/CI.yaml)
    • (4) Wait! Zenodo view with DOI assignment should update within about a minute
    • (5) Add DOI badge to README file

Workflow for (automatically) uploading package to pypi or test.pypi

  • (1) On pypi, make new API key for repo or general
  • (2) On Github, in repository settings add a new actions secret named TWINE_API_KEY and copy in the pypi API key
  • (3) Create a new release manually on github or by triggering the github workflow with a version without release extension (e.g. x.y.z)

Notes

New(er) build system with pyproject.toml and setup.cfg

  • pip
    • tested with pip install . --use-feature=in-tree-build for forward-compatibility with pip 21.3
    • keeping empty setup.py for enabling install in editable mode -e as this still requires such a file
    • added wheel as build-system dependency for compatibility with pip that does not implement PEP 517
  • setup.cfg/setup.py might be fully replaced with pyproject.toml. See this discussion about PEP-426, PEP-517, PEP-518

Contributing

Contributions are very welcome! Please see the contribution guidelines or check out the issues

License

This software is released under the BSD 3-Clause License