Align to cookiecutter template

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/arup-group/cookiecutter-pypackage.git",
-  "commit": "641cc1cd08b540e5dad4f8f3b294e81a0e62440e",
+  "commit": "071e1fadde5a9c4cb45da7bb1801cbe1925c8e0a",
   "checkout": null,
   "context": {
     "cookiecutter": {

.github/workflows/daily-scheduled-ci.yml

@@ -16,7 +16,7 @@ jobs:
     uses: arup-group/actions-city-modelling-lab/.github/workflows/python-install-lint-test.yml@main
     with:
       os: ubuntu-latest
-      py3version: "11"
+      py3version: "12"
       notebook_kernel: pam
       pytest_args: '--no-cov'  # ignore coverage
       cache_mamba_env: false

.github/workflows/pr-ci.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       matrix:
         os: [windows-latest, ubuntu-latest, macos-latest]
-        py3version: ["9", "11"]
+        py3version: ["10", "12"]
       fail-fast: false
     uses: arup-group/actions-city-modelling-lab/.github/workflows/python-install-lint-test.yml@main
     with:
@@ -32,7 +32,7 @@ jobs:
     uses: arup-group/actions-city-modelling-lab/.github/workflows/python-install-lint-test.yml@main
     with:
       os: ubuntu-latest
-      py3version: "11"
+      py3version: "12"
       notebook_kernel: pam
       lint: false
       pytest_args: 'tests/'  # ignore example notebooks
@@ -42,4 +42,7 @@ jobs:
     uses: arup-group/actions-city-modelling-lab/.github/workflows/python-memory-profile.yml@main
     with:
       py3version: "11"
-      upload_flamegraph: true
+      upload_flamegraph: true
+
+  cruft-check:
+    uses: arup-group/actions-city-modelling-lab/.github/workflows/template-check.yml@main

.github/workflows/pre-release.yml

@@ -11,9 +11,11 @@ jobs:
     secrets: inherit
     with:
       package_name: cml-pam
+      environment: pre-release
 
   pip-build:
     uses: arup-group/actions-city-modelling-lab/.github/workflows/pip-build.yml@main
     secrets: inherit
     with:
-      package_name: cml-pam
+      package_name: cml-pam
+      environment: pre-release

.github/workflows/release.yml

@@ -11,13 +11,15 @@ jobs:
     with:
       package_name: cml-pam
       build_workflow: pre-release.yml
+      environment: release
 
   pip-upload:
     uses: arup-group/actions-city-modelling-lab/.github/workflows/pip-upload.yml@main
     secrets: inherit
     with:
       package_name: cml-pam
       build_workflow: pre-release.yml
+      environment: release
 
   docs-stable:
     permissions:

.pre-commit-config.yaml

@@ -1,20 +1,20 @@
-default_language_version: 
+default_language_version:
   python: python3
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0 
+    rev: v4.5.0
     hooks:
       - id: check-added-large-files
         args: ["--maxkb=1000"]
 
   - repo: https://github.com/psf/black
-    rev: 23.11.0
+    rev: 24.2.0
     hooks:
       - id: black
 
   - repo: https://github.com/astral-sh/ruff-pre-commit  # https://beta.ruff.rs/docs/usage/#github-action
-    rev: v0.1.6
+    rev: v0.2.2
     hooks:
       - id: ruff
         args: [ --fix, --exit-non-zero-on-fix ]

CHANGELOG.md

@@ -7,6 +7,9 @@ Deprecated: for soon-to-be removed features.
 Removed: for now removed features.
 Fixed: for any bug fixes.
 Security: in case of vulnerabilities.
+
+Release headings should be of the form:
+## [X.Y.Z] - YEAR-MONTH-DAY
 -->
 
 # Changelog
@@ -26,6 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **internal** Align project to the [CML cookiecutter template](https://github.com/arup-group/cookiecutter-pypackage/) and track it with a Cruft config and CI job.
 
 ## [v0.3.1] - 2023-11-07
 

CONTRIBUTING.md

@@ -88,16 +88,16 @@ When adding docstrings, we request you use the [Google docstring style](https://
 
 ### Create release
 
-- [ ] Bump the version number in `pam/__init__.py`
-- [ ] Update the [changelog][changelog] with final version number of the form `vX.Y.Z`, release date, and github `compare` link (at the bottom of the page).
+- [ ] Bump the version number in `src/pam/__init__.py`
+- [ ] Update the [changelog][changelog] with final version number of the form `vX.Y.Z`, release date, and [github `compare` link](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits) (at the bottom of the page).
 - [ ] Commit with message `Release vX.Y.Z`, then add a `vX.Y.Z` tag.
 - [ ] Create a release pull request to verify that the conda package builds successfully.
 - [ ] Once the PR is approved and merged, create a release through the GitHub web interface, using the same tag, titling it `Release vX.Y.Z` and include all the changelog elements that are *not* flagged as **internal**.
 
 ### Post-release
 
 - [ ] Update the changelog, adding a new `[Unreleased]` heading.
-- [ ] Update `pam/__init__.py` to the next version appended with `.dev0`, in preparation for the next main commit.
+- [ ] Update `src/pam/__init__.py` to the next version appended with `.dev0`, in preparation for the next main commit.
 
 
 <!--- --8<-- [end:docs] -->

README.md

@@ -114,3 +114,7 @@ mike serve
 ```
 
 Then you can view the documentation in a browser at <http://localhost:8000/>.
+
+## Credits
+
+This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [arup-group/cookiecutter-pypackage](https://github.com/arup-group/cookiecutter-pypackage) project template.

docs/static/hooks.py

@@ -14,11 +14,10 @@ def on_files(files: list, config: dict, **kwargs):
     """Link (1) top-level files to mkdocs files and (2) generate the python API documentation."""
     for file in sorted(Path("./examples").glob("*.ipynb")):
         files.append(_new_file(file, config))
-        nav_reference = [idx for idx in config["nav"] if set(idx.keys()) == {"Examples"}][0]
-        nav_reference["Examples"].append(file.as_posix())
+        _get_nav_list(config["nav"], "Examples").append(file.as_posix())
     for file in Path("./resources").glob("**/*.*"):
         files.append(_new_file(file, config))
-    files.append(_new_file("./CHANGELOG.md", config))
+    files.append(_new_file(Path("./CHANGELOG.md"), config))
 
     api_nav = _api_gen(files, config)
     _update_nav(api_nav, config)
@@ -117,8 +116,27 @@ def _update_nav(api_nav: dict, config: dict) -> None:
     api_reference_nav = {
         "Python API": [*api_nav.pop("top_level"), *[{k: v} for k, v in api_nav.items()]]
     }
-    nav_reference = [idx for idx in config["nav"] if set(idx.keys()) == {"Reference"}][0]
-    nav_reference["Reference"].append(api_reference_nav)
+    _get_nav_list(config["nav"], "Reference").append(api_reference_nav)
+
+
+def _get_nav_list(nav: list[dict | str], ref: str) -> list:
+    """Get navigation entry sub-page list.
+    Navigation list entries can be dictionaries or strings.
+    Sub-list entries can then also be dictionaries or strings. E.g.,
+
+    ```python
+    [{"Page Title": ["sub-page-1", {"Sub-Page-2 Title": "sub-page-2"}, ...], ...}]
+    ```
+
+    Args:
+        nav (list[dict  |  str]): MKdocs `nav` config entry.
+        ref (str): Page title reference to return the sub-list of.
+
+    Returns:
+        list: Nav sub-list linked to `ref`.
+    """
+    nav_ref = [idx for idx in nav if isinstance(idx, dict) and set(idx.keys()) == {ref}][0]
+    return nav_ref[ref]
 
 
 @mkdocs.plugins.event_priority(-100)

mkdocs.yml

@@ -18,6 +18,9 @@ theme:
   custom_dir: docs/overrides
   features:
     - navigation.indexes
+    - navigation.top
+    - content.code.copy
+    - content.code.annotate
   logo: resources/logos/small.png
   favicon: resources/logos/mini.png
 repo_url: https://github.com/arup-group/pam/
@@ -36,6 +39,8 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.superfences
   - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.tasklist:
       clickable_checkbox: true
   - toc:
@@ -44,6 +49,7 @@ markdown_extensions:
 hooks:
   - docs/static/hooks.py
 plugins:
+  - search
   - autorefs
   - mkdocs-jupyter:
       include: ["examples/*.ipynb"]
@@ -67,14 +73,14 @@ plugins:
             show_root_toc_entry: false
             show_signature_annotations: false
             inherited_members: true
+          paths: [src]
           import:
             - https://docs.python.org/3/objects.inv
             - https://shapely.readthedocs.io/en/stable/objects.inv
             - https://pandas.pydata.org/docs/objects.inv
             - https://geopandas.org/en/stable/objects.inv
-  - search
 watch:
-  - pam
+  - src/pam
 extra_css:
   - static/extras.css
 extra:

pyproject.toml

@@ -18,7 +18,7 @@ filterwarnings = [
 
 [tool.coverage.run]
 branch = true
-source = ["pam/"]
+source = ["src/"]
 
 [tool.coverage.report]
 fail_under = 89
@@ -31,10 +31,12 @@ output = "reports/coverage/coverage.xml"
 
 [tool.black]
 line-length = 100
-skip_magic_trailing_comma = true
+skip-magic-trailing-comma = true
 
 [tool.ruff]
 line-length = 100
+
+[tool.ruff.lint]
 select = ["E", "F", "I", "Q"]
 
 ignore = [
@@ -48,27 +50,22 @@ exclude = [".*", "__pypackages__", "build", "dist", "venv", "reports/"]
 # Allow unused variables when underscore-prefixed.
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 
-[tool.ruff.pydocstyle]
-convention = "google"
+pydocstyle = {convention = "google"}
 
-[tool.ruff.mccabe]
 # Unlike Flake8, default to a complexity level of 10.
-max-complexity = 10
+mccabe = {max-complexity = 10}
 
 # Ignore `E402` (import violations) and `F401` (unused imports) in all `__init__.py` files
-[tool.ruff.per-file-ignores]
-"__init__.py" = ["E402", "F401"]
-"*.ipynb" = ["E402"]
+per-file-ignores = {"__init__.py" = ["E402", "F401"]}
+
+flake8-quotes = {docstring-quotes = "double"}
 
 # Ignore `E402` for all notebooks
 [tool.nbqa.addopts]
 ruff = ["--extend-ignore=E402"]
 
-
-[tool.ruff.flake8-quotes]
-docstring-quotes = "double"
-
 [tool.setuptools.packages.find]
+where = ["src"]
 include = ["pam*"]
 
 [tool.setuptools.package-data]

requirements/dev.txt

@@ -1,3 +1,4 @@
+cruft >= 2, < 3
 jupyter < 2
 mike < 2
 mkdocs < 2
@@ -6,7 +7,7 @@ mkdocs-jupyter < 0.25
 mkdocstrings-python < 2
 nbmake < 2
 pre-commit < 4
-pytest < 8
+pytest >= 8, < 9
 pytest-cov < 5
 pytest-mock < 4
 pytest-timeout < 3

pam/__init__.py → src/pam/__init__.py

@@ -1,6 +1,15 @@
+"""Top-level module for pam."""
+
+import pyproj
+
+__author__ = """Fred Shone"""  # triple quotes in case the name has quotes in it.
+__email__ = "[email protected]"
 __version__ = "0.3.1"
 
 
+pyproj.network.set_network_enabled(False)
+
+
 class PAMValidationError(Exception):
     """Custom exception raised for an Activity Plan validation Error."""