templatepy 0.0.2__tar.gz → 0.2.0__tar.gz

templatepy-0.2.0/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.1
+Name: templatepy
+Version: 0.2.0
+Summary: templatepy: template for derivative python packages
+Author-email: "Lars B. Rollik" <L.B.Rollik@protonmail.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2021, Lars B. Rollik
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Repository, https://github.com/larsrollik/templatepy
+Project-URL: Issue Tracker, https://github.com/larsrollik/templatepy/issues
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: black
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: bump2version; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+
+[//]: # (Links)
+[Github-flavored markdown]: https://github.github.com/gfm
+
+[manifest]: https://packaging.python.org/en/latest/guides/using-manifest-in
+[packaging]: https://packaging.python.org/en/latest/tutorials/packaging-projects
+[setup.cfg]: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html
+
+[bump2version]: (https://github.com/c4urself/bump2version
+[pre-commit]: https://pre-commit.com
+[black]: https://github.com/psf/black
+
+[pypi]: pypi.org
+[test.pypi]: test.pypi.org
+
+[Zenodo]: https://zenodo.org
+
+[contribution guidelines]: https://github.com/larsrollik/templatepy/blob/main/CONTRIBUTING.md
+[issues]: https://github.com/larsrollik/templatepy/issues
+[BSD 3-Clause License]: https://github.com/larsrollik/templatepy/blob/main/LICENSE
+[Github]: https://github.com/larsrollik/templatepy/settings/secrets/actions/new
+[release]: https://github.com/larsrollik/templatepy/releases/new
+
+[//]: # (Badges)
+
+[![Contributions](https://img.shields.io/badge/Contributions-Welcome-brightgreen.svg)](https://github.com/larsrollik/templatepy/blob/main/CONTRIBUTING.md)
+[![DOI](https://zenodo.org/badge/370470893.svg)](https://zenodo.org/badge/latestdoi/370470893)
+[![Website](https://img.shields.io/website?up_message=online&url=https%3A%2F%2Fgithub.com/larsrollik/templatepy)](https://github.com/larsrollik/templatepy)
+[![PyPI](https://img.shields.io/pypi/v/templatepy.svg)](https://pypi.org/project/templatepy)
+[![Wheel](https://img.shields.io/pypi/wheel/templatepy.svg)](https://pypi.org/project/templatepy)
+![CI](https://github.com/larsrollik/templatepy/workflows/tests/badge.svg)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+
+
+# templatepy
+Template repo for python repositories & PyPi integration
+---
+**Version: "0.2.0"**
+
+
+## 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 [pyproject.toml])
+
+- **`MANIFEST.in`**:
+  Defines additional files to include/exclude in the build (if not automatically detected).
+
+- **`pyproject.toml`**:
+  Central configuration file that replaces the traditional `setup.cfg` and `setup.py` files:
+  - **Build System**: Specifies the build system requirements and configuration, as defined in [PEP 518](https://peps.python.org/pep-0518/) and [PEP 621](https://peps.python.org/pep-0621/).
+  - **Package Metadata**: Includes the project's metadata (name, version, dependencies, etc.).
+  - **Code Formatting**: Configuration for tools like [black] and [flake8] (if used).
+  - **Optional Dependencies**: Organizes extra dependencies for development or other environments.
+
+- **`setup.py`**:
+  Legacy file retained only for backward compatibility if needed (e.g., older tooling). New projects should avoid it entirely.
+
+
+## CI Workflow Overview
+
+The CI workflow is triggered on push to `main` or when a tag is created. It ensures code quality and automates the release process:
+
+1. **Linting and Testing**:
+   - `lint`: Checks code style with `black` and `flake8`, runs pre-commit hooks.
+   - `test`: Runs tests with `pytest` and generates coverage reports.
+
+2. **Tag Validation**:
+   - `check-tag`: Verifies that the tag is valid (not `dev` or `rc`) before proceeding.
+
+3. **Release Creation**:
+   - `release`: Creates a GitHub release when the tag is valid.
+
+4. **Deployment to PyPI**:
+   - `deploy`: Builds and uploads the package to PyPI using `twine`.
+
+The pipeline ensures code quality, passing tests, and automated deployment on new releases.
+
+### Testing CI Locally
+
+- Install `act`:
+  - **macOS/Linux**: `brew install act` / `sudo apt install act`
+  - **Windows**: Download from [act GitHub Releases](https://github.com/nektos/act/releases) and follow the installation instructions.
+- Ensure Docker is installed and running. Download from [Docker Desktop](https://www.docker.com/products/docker).
+- Run the CI workflow with `act`:
+  ```bash
+  act push
+  act push --verbose  # very verbose output !
+  ```
+
+
+### 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) Rename the `templatepy` folder.
+  - (2) Update all occurrences in `README.md`.
+  - (3) Update the `name` field in `pyproject.toml`.
+  - (4) Update `.github/workflows` files.
+  - (5) Update version references in `pyproject.toml` and `templatepy/__init__.py`.
+- [ ] Update project author and metadata details in `pyproject.toml`, `README.md`, and `templatepy/__init__.py`.
+- [ ] Update the license holder in the `LICENSE` file.
+- [ ] Update `README.md` badge paths at the top.
+- [ ] Verify inclusions/exclusions of installable files/folders in `MANIFEST.in` and `pyproject.toml` under `[tool.setuptools]`.
+- [ ] Ensure `.gitignore` contains relevant entries for the new project.
+- [ ] Add all version string locations to `[tool.bump2version]` in `pyproject.toml`.
+  - Use syntax like `[bumpversion:file:templatepy/__init__.py]` to specify locations for version updates.
+- [ ] To upload to [PyPI], follow the instructions in the section below.
+- [ ] To upload to [Zenodo] (if the repository is for a publication):
+  - (1) Connect Zenodo to your GitHub account.
+  - (2) Enable Zenodo integration for the repository (Zenodo requires the repository to be **public**).
+  - (3) Create a new GitHub release (manually or via `.github/workflows/CI.yaml`).
+  - (4) Wait for Zenodo to sync and assign a DOI (this usually takes about a minute).
+  - (5) Add the DOI badge to `README.md`.
+
+
+## Workflow for Automatically Uploading Package to [PyPI] or [Test PyPI]
+
+1. **Generate a PyPI API Key**:
+   - Go to [PyPI](https://pypi.org/) and create a new API key, either specific to the repository or a general-purpose key.
+
+2. **Add the API Key to GitHub**:
+   - In your repository's settings on [GitHub](https://github.com/):
+     - Navigate to **Settings > Secrets and variables > Actions**.
+     - Add a new **Actions secret** with the name `TWINE_API_KEY`.
+     - Paste the PyPI API key into the secret's value field.
+
+3. **Create a New Release**:
+   - On [GitHub](https://github.com/), create a new release manually via the **Releases** page.
+     - Use a version number without a release extension (e.g., `x.y.z`).
+   - Alternatively, trigger the GitHub workflow configured for releasing by incrementing the version with `bump2version` (see info below)
+   - Desperately, manually update the version strings in the relevant files and add git commit tag to trigger the release workflow on push
+
+The package will then be automatically uploaded to [PyPI](https://pypi.org/) or [Test PyPI](https://test.pypi.org/) as configured in your CI/CD workflow.
+
+
+## Using `bump2version` for Versioning
+
+`bump2version` is used to increment version numbers based on semantic versioning. Here’s how you can use it with the current setup to trigger a release:
+
+1. **Bumping the Minor Version**:
+   Increment the minor version (e.g., from `1.2.3` to `1.3.0`):
+   ```bash
+   # Bumping the minor Version:
+   bump2version minor
+
+   # Bumping the major version (e.g., from 1.2.3 to 2.0.0):
+   bump2version major
+
+   # Bumping for a release Version (e.g., from 1.0.0.dev to 1.0.0.rc or 1.0.0):
+   bump2version release
+   ```
+
+## Notes
+
+#### New(er) Build System with `pyproject.toml` and `setup.cfg`
+
+Historically, packaging in Python was governed by standards such as `PEP-426`, `PEP-517`, and `PEP-518`. These PEPs introduced various mechanisms for packaging and building Python projects, but with certain limitations, especially regarding flexibility and future-proofing.
+
+- **PEP-426**: Introduced the `setup.cfg` and `setup.py` files as the standard way to define package metadata and build configuration.
+- **PEP-517**: Introduced a standardized interface for building Python projects, separating the build process from the packaging process and allowing for more flexible build systems.
+- **PEP-518**: Defined how `pyproject.toml` should be used to declare build dependencies and system requirements, allowing tools like `pip` to know which backend to use for the build process.
+
+While these PEPs were important milestones, the latest changes to the packaging ecosystem make `pyproject.toml` the preferred way to configure projects going forward.
+
+- **`pip`**:
+  - Tested with `pip install . --use-feature=in-tree-build` for forward compatibility with `pip 21.3` and later.
+  - While `setup.py` is technically optional, an empty `setup.py` is still kept for enabling editable installs (`pip install -e .`), as this requires such a file for now.
+  - `wheel` is added as a build-system dependency to maintain compatibility with versions of `pip` that do not yet fully implement `PEP 517`.
+
+- **Replacing `setup.cfg` and `setup.py` with `pyproject.toml`**:
+  - In the modern packaging ecosystem, `pyproject.toml` is increasingly the standard for declaring build systems, dependencies, and metadata. This configuration file simplifies the process and eliminates the need for separate `setup.py` and `setup.cfg` files in many cases.
+
+For further reading on the transition to `pyproject.toml` and the removal of `setup.py`/`setup.cfg`, see the following discussions:
+- [PEP-426](https://peps.python.org/pep-0426/)
+- [PEP-517](https://peps.python.org/pep-0517/)
+- [PEP-518](https://peps.python.org/pep-0518/)
+- [Discussion on Setup.cfg Deprecation](https://stackoverflow.com/questions/44878600/is-setup-cfg-deprecated)
+
+
+## Common issues
+
+### `bump2version` fails on git tag with exit status 128
+
+- check a signing key is configured: `git config --global user.signingkey` (see below for generating a key)
+- repo is a detached HEAD? check out a branch: `git checkout main`
+- there are changes that need to be committed? `git commit -am "commit message"`
+- tag already exists? `git tag` to list tags, `git tag -d <tag>` to delete a tag
+
+### no gpg key for signing commits
+- generate a key with `gpg --full-generate-key`
+- list keys with `gpg --list-secret-keys --keyid-format LONG`
+- set the key for signing commits with `git config --global user.signingkey <key-id>`
+- enable signing commits with `git config --global commit.gpgsign true`
+- set the key for signing tags with `git config --global tag.gpgSign true`
+- export the public key with `gpg --armor --export <key-id>`
+  - and add it to your GitHub account: select 'New key' -> paste output of command above
+
+Which one is the key id you might ask?
+```
+/home/user/.gnupg/secring.gpg
+------------------------------
+sec   4096R/<KEY_ID> 2024-11-22 [expires: 2025-11-22]
+      uid                          Your Name <youremail@example.com>
+ssb   4096R/<KEY_SUBKEY_ID> 2024-11-22
+
+```
+
+### GPG hangs/errors and never asks for passphrase of key?
+
+- try: `export GPG_TTY=$(tty)`
+
+
+## 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]**

templatepy-0.2.0/README.md

@@ -0,0 +1,255 @@
+[//]: # (Links)
+[Github-flavored markdown]: https://github.github.com/gfm
+
+[manifest]: https://packaging.python.org/en/latest/guides/using-manifest-in
+[packaging]: https://packaging.python.org/en/latest/tutorials/packaging-projects
+[setup.cfg]: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html
+
+[bump2version]: (https://github.com/c4urself/bump2version
+[pre-commit]: https://pre-commit.com
+[black]: https://github.com/psf/black
+
+[pypi]: pypi.org
+[test.pypi]: test.pypi.org
+
+[Zenodo]: https://zenodo.org
+
+[contribution guidelines]: https://github.com/larsrollik/templatepy/blob/main/CONTRIBUTING.md
+[issues]: https://github.com/larsrollik/templatepy/issues
+[BSD 3-Clause License]: https://github.com/larsrollik/templatepy/blob/main/LICENSE
+[Github]: https://github.com/larsrollik/templatepy/settings/secrets/actions/new
+[release]: https://github.com/larsrollik/templatepy/releases/new
+
+[//]: # (Badges)
+
+[![Contributions](https://img.shields.io/badge/Contributions-Welcome-brightgreen.svg)](https://github.com/larsrollik/templatepy/blob/main/CONTRIBUTING.md)
+[![DOI](https://zenodo.org/badge/370470893.svg)](https://zenodo.org/badge/latestdoi/370470893)
+[![Website](https://img.shields.io/website?up_message=online&url=https%3A%2F%2Fgithub.com/larsrollik/templatepy)](https://github.com/larsrollik/templatepy)
+[![PyPI](https://img.shields.io/pypi/v/templatepy.svg)](https://pypi.org/project/templatepy)
+[![Wheel](https://img.shields.io/pypi/wheel/templatepy.svg)](https://pypi.org/project/templatepy)
+![CI](https://github.com/larsrollik/templatepy/workflows/tests/badge.svg)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+
+
+# templatepy
+Template repo for python repositories & PyPi integration
+---
+**Version: "0.2.0"**
+
+
+## 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 [pyproject.toml])
+
+- **`MANIFEST.in`**:
+  Defines additional files to include/exclude in the build (if not automatically detected).
+
+- **`pyproject.toml`**:
+  Central configuration file that replaces the traditional `setup.cfg` and `setup.py` files:
+  - **Build System**: Specifies the build system requirements and configuration, as defined in [PEP 518](https://peps.python.org/pep-0518/) and [PEP 621](https://peps.python.org/pep-0621/).
+  - **Package Metadata**: Includes the project's metadata (name, version, dependencies, etc.).
+  - **Code Formatting**: Configuration for tools like [black] and [flake8] (if used).
+  - **Optional Dependencies**: Organizes extra dependencies for development or other environments.
+
+- **`setup.py`**:
+  Legacy file retained only for backward compatibility if needed (e.g., older tooling). New projects should avoid it entirely.
+
+
+## CI Workflow Overview
+
+The CI workflow is triggered on push to `main` or when a tag is created. It ensures code quality and automates the release process:
+
+1. **Linting and Testing**:
+   - `lint`: Checks code style with `black` and `flake8`, runs pre-commit hooks.
+   - `test`: Runs tests with `pytest` and generates coverage reports.
+
+2. **Tag Validation**:
+   - `check-tag`: Verifies that the tag is valid (not `dev` or `rc`) before proceeding.
+
+3. **Release Creation**:
+   - `release`: Creates a GitHub release when the tag is valid.
+
+4. **Deployment to PyPI**:
+   - `deploy`: Builds and uploads the package to PyPI using `twine`.
+
+The pipeline ensures code quality, passing tests, and automated deployment on new releases.
+
+### Testing CI Locally
+
+- Install `act`:
+  - **macOS/Linux**: `brew install act` / `sudo apt install act`
+  - **Windows**: Download from [act GitHub Releases](https://github.com/nektos/act/releases) and follow the installation instructions.
+- Ensure Docker is installed and running. Download from [Docker Desktop](https://www.docker.com/products/docker).
+- Run the CI workflow with `act`:
+  ```bash
+  act push
+  act push --verbose  # very verbose output !
+  ```
+
+
+### 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) Rename the `templatepy` folder.
+  - (2) Update all occurrences in `README.md`.
+  - (3) Update the `name` field in `pyproject.toml`.
+  - (4) Update `.github/workflows` files.
+  - (5) Update version references in `pyproject.toml` and `templatepy/__init__.py`.
+- [ ] Update project author and metadata details in `pyproject.toml`, `README.md`, and `templatepy/__init__.py`.
+- [ ] Update the license holder in the `LICENSE` file.
+- [ ] Update `README.md` badge paths at the top.
+- [ ] Verify inclusions/exclusions of installable files/folders in `MANIFEST.in` and `pyproject.toml` under `[tool.setuptools]`.
+- [ ] Ensure `.gitignore` contains relevant entries for the new project.
+- [ ] Add all version string locations to `[tool.bump2version]` in `pyproject.toml`.
+  - Use syntax like `[bumpversion:file:templatepy/__init__.py]` to specify locations for version updates.
+- [ ] To upload to [PyPI], follow the instructions in the section below.
+- [ ] To upload to [Zenodo] (if the repository is for a publication):
+  - (1) Connect Zenodo to your GitHub account.
+  - (2) Enable Zenodo integration for the repository (Zenodo requires the repository to be **public**).
+  - (3) Create a new GitHub release (manually or via `.github/workflows/CI.yaml`).
+  - (4) Wait for Zenodo to sync and assign a DOI (this usually takes about a minute).
+  - (5) Add the DOI badge to `README.md`.
+
+
+## Workflow for Automatically Uploading Package to [PyPI] or [Test PyPI]
+
+1. **Generate a PyPI API Key**:
+   - Go to [PyPI](https://pypi.org/) and create a new API key, either specific to the repository or a general-purpose key.
+
+2. **Add the API Key to GitHub**:
+   - In your repository's settings on [GitHub](https://github.com/):
+     - Navigate to **Settings > Secrets and variables > Actions**.
+     - Add a new **Actions secret** with the name `TWINE_API_KEY`.
+     - Paste the PyPI API key into the secret's value field.
+
+3. **Create a New Release**:
+   - On [GitHub](https://github.com/), create a new release manually via the **Releases** page.
+     - Use a version number without a release extension (e.g., `x.y.z`).
+   - Alternatively, trigger the GitHub workflow configured for releasing by incrementing the version with `bump2version` (see info below)
+   - Desperately, manually update the version strings in the relevant files and add git commit tag to trigger the release workflow on push
+
+The package will then be automatically uploaded to [PyPI](https://pypi.org/) or [Test PyPI](https://test.pypi.org/) as configured in your CI/CD workflow.
+
+
+## Using `bump2version` for Versioning
+
+`bump2version` is used to increment version numbers based on semantic versioning. Here’s how you can use it with the current setup to trigger a release:
+
+1. **Bumping the Minor Version**:
+   Increment the minor version (e.g., from `1.2.3` to `1.3.0`):
+   ```bash
+   # Bumping the minor Version:
+   bump2version minor
+
+   # Bumping the major version (e.g., from 1.2.3 to 2.0.0):
+   bump2version major
+
+   # Bumping for a release Version (e.g., from 1.0.0.dev to 1.0.0.rc or 1.0.0):
+   bump2version release
+   ```
+
+## Notes
+
+#### New(er) Build System with `pyproject.toml` and `setup.cfg`
+
+Historically, packaging in Python was governed by standards such as `PEP-426`, `PEP-517`, and `PEP-518`. These PEPs introduced various mechanisms for packaging and building Python projects, but with certain limitations, especially regarding flexibility and future-proofing.
+
+- **PEP-426**: Introduced the `setup.cfg` and `setup.py` files as the standard way to define package metadata and build configuration.
+- **PEP-517**: Introduced a standardized interface for building Python projects, separating the build process from the packaging process and allowing for more flexible build systems.
+- **PEP-518**: Defined how `pyproject.toml` should be used to declare build dependencies and system requirements, allowing tools like `pip` to know which backend to use for the build process.
+
+While these PEPs were important milestones, the latest changes to the packaging ecosystem make `pyproject.toml` the preferred way to configure projects going forward.
+
+- **`pip`**:
+  - Tested with `pip install . --use-feature=in-tree-build` for forward compatibility with `pip 21.3` and later.
+  - While `setup.py` is technically optional, an empty `setup.py` is still kept for enabling editable installs (`pip install -e .`), as this requires such a file for now.
+  - `wheel` is added as a build-system dependency to maintain compatibility with versions of `pip` that do not yet fully implement `PEP 517`.
+
+- **Replacing `setup.cfg` and `setup.py` with `pyproject.toml`**:
+  - In the modern packaging ecosystem, `pyproject.toml` is increasingly the standard for declaring build systems, dependencies, and metadata. This configuration file simplifies the process and eliminates the need for separate `setup.py` and `setup.cfg` files in many cases.
+
+For further reading on the transition to `pyproject.toml` and the removal of `setup.py`/`setup.cfg`, see the following discussions:
+- [PEP-426](https://peps.python.org/pep-0426/)
+- [PEP-517](https://peps.python.org/pep-0517/)
+- [PEP-518](https://peps.python.org/pep-0518/)
+- [Discussion on Setup.cfg Deprecation](https://stackoverflow.com/questions/44878600/is-setup-cfg-deprecated)
+
+
+## Common issues
+
+### `bump2version` fails on git tag with exit status 128
+
+- check a signing key is configured: `git config --global user.signingkey` (see below for generating a key)
+- repo is a detached HEAD? check out a branch: `git checkout main`
+- there are changes that need to be committed? `git commit -am "commit message"`
+- tag already exists? `git tag` to list tags, `git tag -d <tag>` to delete a tag
+
+### no gpg key for signing commits
+- generate a key with `gpg --full-generate-key`
+- list keys with `gpg --list-secret-keys --keyid-format LONG`
+- set the key for signing commits with `git config --global user.signingkey <key-id>`
+- enable signing commits with `git config --global commit.gpgsign true`
+- set the key for signing tags with `git config --global tag.gpgSign true`
+- export the public key with `gpg --armor --export <key-id>`
+  - and add it to your GitHub account: select 'New key' -> paste output of command above
+
+Which one is the key id you might ask?
+```
+/home/user/.gnupg/secring.gpg
+------------------------------
+sec   4096R/<KEY_ID> 2024-11-22 [expires: 2025-11-22]
+      uid                          Your Name <youremail@example.com>
+ssb   4096R/<KEY_SUBKEY_ID> 2024-11-22
+
+```
+
+### GPG hangs/errors and never asks for passphrase of key?
+
+- try: `export GPG_TTY=$(tty)`
+
+
+## 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]**

templatepy-0.2.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "templatepy"
+version = "0.2.0"
+authors = [
+    { name = "Lars B. Rollik", email = "L.B.Rollik@protonmail.com" }
+]
+license = { file = "LICENSE" }
+description = "templatepy: template for derivative python packages"
+readme = { file = "README.md", content-type = "text/markdown" }
+classifiers = [
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+#    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "black"
+]
+
+[project.urls]
+Repository = "https://github.com/larsrollik/templatepy"
+"Issue Tracker" = "https://github.com/larsrollik/templatepy/issues"
+
+
+[project.optional-dependencies]
+dev = [
+    "black",
+    "bump2version",
+    "pytest-cov",  # implies: pytest, coverage dependencies
+    "pre-commit",
+    "flake8"
+]
+
+[project.entry-points.console_scripts]
+templatepy-entrypoint = "templatepy.__init__:run"
+
+[tool.setuptools]
+zip-safe = false
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = [""]
+
+[tool.setuptools.package-data]
+"*" = ["*.config"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=templatepy --cov-report=term-missing --maxfail=5"
+
+[tool.black]
+target-version = ["py310", "py311"]  #, "py312"
+skip-string-normalization = false
+line-length = 79
+include = '\\.pyi?$'
+exclude = '''
+/(
+    \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | _build
+  | buck-out
+  | build
+  | dist
+)/
+'''
+
+[tool.flake8]
+ignore = ["E203", "E266", "E501", "W503", "F403", "F401"]
+max-line-length = 79
+max-complexity = 18
+select = ["B", "C", "E", "F", "W", "T4", "B9"]
+exclude = ["__init__.py", "build", "__pycache__", ".git", "tests"]

templatepy-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

{templatepy-0.0.2 → templatepy-0.2.0}/templatepy/__init__.py

@@ -1,5 +1,5 @@
 __author__ = "Lars B. Rollik"
-__version__ = "0.0.2"
+__version__ = "0.2.0"
 
 
 def run():