Merge pull request #184 from ImperialCollegeLondon/dynamic-versions

Enable dynamic versions in pip-tools

.github/workflows/ci-pip-tools.yml

@@ -35,6 +35,7 @@ jobs:
       - name: Install project dependencies
         working-directory: my_project
         run: |
+          git init
           pip install --upgrade pip
           pip install -r dev-requirements.txt
           pip install -e .
@@ -50,6 +51,5 @@ jobs:
       - name: Run pre-commit hooks for project
         working-directory: my_project
         run: |
-          git init
           git add .
           pre-commit run -a

{{ cookiecutter.project_slug }}/.vscode/settings.json

@@ -7,5 +7,6 @@
         88
     ],
     "python.testing.unittestEnabled": false,
-    "python.testing.pytestEnabled": true
+    "python.testing.pytestEnabled": true,
+    "editor.formatOnSave": false
 }

{{ cookiecutter.project_slug }}/README.pip-tools.jinja

@@ -1,12 +1,28 @@
-This is a Python application that uses [`pip-tools`] for packaging and dependency management. It also provides [`pre-commit`](https://pre-commit.com/) hooks (for for [ruff](https://pypi.org/project/ruff/) and [`mypy`](https://mypy.readthedocs.io/en/stable/)) and automated tests using [`pytest`](https://pytest.org/) and [GitHub Actions](https://github.com/features/actions). Pre-commit hooks are automatically kept updated with a dedicated GitHub Action, this can be removed and replace with [pre-commit.ci](https://pre-commit.ci) if using an public repo. It was developed by the [Imperial College Research Computing Service](https://www.imperial.ac.uk/admin-services/ict/self-service/research-support/rcs/).
+This is a Python application that uses [`pip-tools`][pip-tools] for packaging and
+dependency management. It also provides [`pre-commit`][pre-commit] hooks (for
+[`ruff`][ruff] and [`mypy`][mypy]) and automated tests using [`pytest`][pytest] and
+[GitHub Actions]. Pre-commit hooks are automatically kept updated with a dedicated
+GitHub Action, this can be removed and replaced with [pre-commit.ci] if using a public
+repo. The package version is dynamically generated from the most recent git tag using
+[`setuptools-scm`][setuptools-scm].
 
-[`pip-tools`] is chosen as a lightweight dependency manager that adheres to the [latest standards](https://peps.python.org/pep-0621/) using `pyproject.toml`.
+[`pip-tools`][pip-tools] is chosen as a lightweight dependency manager that adheres to
+the [latest standards] using `pyproject.toml`.
+
+It was developed by the [Imperial College Research Software Engineering Team].
 
 ## Usage
 
 To get started:
 
-1. Create and activate a [virtual environment](https://docs.python.org/3/library/venv.html):
+1. Activate a git repository (required for `pre-commit` and the package versioning with
+`setuptools-scm`):
+
+   ```bash
+   git init
+   ```
+
+1. Create and activate a [virtual environment]:
 
    ```bash
    python -m venv .venv
@@ -48,29 +64,46 @@ To get started:
 
 To add or remove dependencies:
 
-1. Edit the `dependencies` variables in the `pyproject.toml` file (aim to keep development tools separate from the project requirements).
-2. Update the requirements files:
+1. Edit the `dependencies` variables in the `pyproject.toml` file (aim to keep
+development tools separate from the project requirements).
+1. Update the requirements files:
    - `pip-compile` for `requirements.txt` - the project requirements.
    - `pip-compile --extra dev -o dev-requirements.txt` for the development requirements.
-{% if cookiecutter.mkdocs %}   - `pip-compile --extra doc -o doc-requirements.txt` for the documentation tools.
-{% endif %}3. Sync the files with your installation (install packages):
+{% if cookiecutter.mkdocs %}   - `pip-compile --extra doc -o doc-requirements.txt` for
+the documentation tools.
+{% endif %}1. Sync the files with your installation (install packages):
    - `pip-sync *requirements.txt`
 
 To upgrade pinned versions, use the `--upgrade` flag with `pip-compile`.
 
-Versions can be restricted from updating within the `pyproject.toml` using standard python package version specifiers, i.e. `"black<23"` or `"pip-tools!=6.12.2"`
+Versions can be restricted from updating within the `pyproject.toml` using standard
+python package version specifiers, i.e. `"black<23"` or `"pip-tools!=6.12.2"`
 
 ## Customising
 
 All configuration can be customised to your preferences. The key places to make changes
 for this are:
 
 - The `pyproject.toml` file, where you can edit:
-  - The build system (change from setuptools to other packaging tools like [Hatch](https://hatch.pypa.io/) or [flit](https://flit.pypa.io/)).
+  - The build system (change from setuptools to other packaging tools like [Hatch] or
+[flit]).
   - The python version.
-  - The project dependencies. Extra optional dependencies can be added by adding another list under `[project.optional-dependencies]` (i.e. `doc = ["mkdocs"]`).
+  - The project dependencies. Extra optional dependencies can be added by adding another
+list under `[project.optional-dependencies]` (i.e. `doc = ["mkdocs"]`).
   - The `mypy` and `pytest` configurations.
 - The `.pre-commit-config.yaml` for pre-commit settings.
 - The `.github` directory for all the CI configuration.
 
-[`pip-tools`]: https://pip-tools.readthedocs.io/en/latest/
+[pip-tools]: https://pip-tools.readthedocs.io/en/stable/
+[pre-commit]: https://pre-commit.com/
+[ruff]: https://pypi.org/project/ruff/
+[mypy]: https://mypy.readthedocs.io/en/stable/
+[pytest]: https://pytest.org/
+[GitHub Actions]: https://github.com/features/actions
+[pre-commit.ci]: https://pre-commit.ci
+[setuptools-scm]: https://setuptools-scm.readthedocs.io/en/latest/
+[latest standards]: https://peps.python.org/pep-0621/
+[Imperial College Research Software Engineering Team]: https://www.imperial.ac.uk/admin-services/ict/self-service/research-support/rcs/service-offering/research-software-engineering/
+[virtual environment]: https://docs.python.org/3/library/venv.html
+[Hatch]: https://hatch.pypa.io/
+[flit]: https://flit.pypa.io/

{{ cookiecutter.project_slug }}/pyproject.toml

@@ -36,7 +36,7 @@ build-backend = "poetry.core.masonry.api"
 {%- elif cookiecutter.packaging == "pip-tools" -%}
 [project]
 name = "{{ cookiecutter.project_slug }}"
-version = "0.1.0"
+dynamic = ["version"]
 description = "{{ cookiecutter.project_description }}"
 authors = [
     { name = "{{ cookiecutter.author }}", email = "{{ cookiecutter.author_email }}" }
@@ -73,6 +73,8 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
 exclude = ["htmlcov"] # Exclude the coverage report file from setuptools package finder
+
+[tool.setuptools_scm]
 {%- endif %}
 
 [tool.mypy]

{{ cookiecutter.project_slug }}/tests/test_{{ cookiecutter.project_slug}}.py

@@ -5,4 +5,4 @@
 
 def test_version():
     """Check that the version is acceptable."""
-    assert __version__ == "0.1.0"
+    assert isinstance(__version__, str)

{{ cookiecutter.project_slug }}/{{ cookiecutter.project_slug }}/__init__.py

@@ -1,5 +1,7 @@
 """The main module for {{ cookiecutter.project_name }}."""
 
-from importlib.metadata import version
+from contextlib import suppress
+from importlib.metadata import PackageNotFoundError, version
 
-__version__ = version(__name__)
+with suppress(PackageNotFoundError):
+    __version__ = version(__name__)