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