Update dependancies and Python to 3.13

.github/workflows/publish.yml

@@ -75,7 +75,7 @@ jobs:
       - name: Set-up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.13'
           cache: 'poetry'
 
       # Configure project

.github/workflows/pull_request.yml

@@ -75,7 +75,7 @@ jobs:
       - name: Set-up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.13'
           cache: 'poetry'
 
       # Configure project

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
 
   # Some minor quality of life things
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-merge-conflict
       - id: check-added-large-files
@@ -18,28 +18,28 @@ repos:
   # Ensure that revisions for tools such as ruff, black, etc. can be
   #   managed by Poetry but synced here before commiting code
   - repo: https://github.com/floatingpurr/sync_with_poetry
-    rev: 1.1.0
+    rev: 1.2.0
     hooks:
       - id: sync_with_poetry
         args: ['--db','.pre-commit-db.json']
 
   # Format code
   - repo: https://github.com/psf/black
-    rev: 24.8.0
+    rev: 25.1.0
     hooks:
       - id: black
         exclude: "{{cookiecutter.repo_name}}|hooks"
 
   # Lint code
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.5.6
+    rev: v0.11.2
     hooks:
       - id: ruff
         exclude: "{{cookiecutter.repo_name}}|hooks"
 
   # Make sure the Poetry project is properly maintained
   - repo: https://github.com/python-poetry/poetry
-    rev: 1.8.0
+    rev: 2.1.1
     hooks:
       - id: poetry-check
       - id: poetry-lock

.readthedocs.yml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "3.11"
+    python: "3.13"
   # Uncomment this and any needed lines below if your project has dependencies needed for install
   # apt_packages:
   #   - mpich

Dockerfile

@@ -1,29 +1,62 @@
 #############
 # Base image
 #############
-FROM python:3.11-buster
+FROM python:3.13-bookworm
 
-RUN pip install poetry==1.4.2
+RUN apt-get update -y  && \
+    apt-get upgrade -y
 
-ENV POETRY_NO_INTERACTION=1 \
-    POETRY_VIRTUALENVS_CREATE=0 \
-    POETRY_CACHE_DIR=/tmp/poetry_cache
+ENV HOME=/home/pytest
+ENV USERNAME=pytest
+ENV PACKAGE_ROOT=${HOME}/package
 
-ENV TEST_ROOT /test_template
-ENV TEMPLATE_ROOT /template
+# Create user USERNAME
+RUN mkdir -p ${HOME} && \
+    useradd --home-dir ${HOME} ${USERNAME} && \
+    chown ${USERNAME} ${HOME}
 
-WORKDIR ${TEST_ROOT}
+############################################################
+# Switch to the user that we just created
+#===========================================================
+# n.b.: we're not running as root because root's ability
+#       to write to read-only temp files (!) can break tests
+#       that check for proper I/O exceptions, for example
+############################################################
+USER ${USERNAME}
+WORKDIR ${HOME}
+
+# Needed to fix dubious ownership error when installing with Poetry
+RUN git config --global --add safe.directory ${PACKAGE_ROOT} && \
+    git config --global user.email "${USERNAME}@pytest.com" && \
+    git config --global user.name "${USERNAME}"
+
+##################################################
+# Create a virtual env and install poetry into it
+##################################################
+ENV POETRY_HOME=${HOME}"/poetry" \
+    POETRY_CACHE_DIR="/tmp/poetry_cache" \
+    POETRY_NO_INTERACTION=true
+RUN python -m venv venv && \
+    . venv/bin/activate && \
+    pip install poetry
 
 ################################################################
 # Copy and install Poetry dependencies (but not the actual 
 # application, which will get installed by the entry_point 
-# script when we start the container)
+# script when we start the container).  Clear the cache after
+# to lighten the container.
 ################################################################
 COPY pyproject.toml poetry.lock .
-RUN poetry install --no-root --compile && \
+RUN . venv/bin/activate && \
+    poetry install --no-root --compile && \
     rm -rf ${POETRY_CACHE_DIR} && \
-    rm pyproject.toml && \
-    mv poetry.lock poetry.lock.image
+    rm pyproject.toml
+
+#################################################3
+# Make a copy of the lock file so we can check for
+# changes in the entry script (below).
+#################################################3
+RUN mv poetry.lock ${HOME}/poetry.lock.image
 
 ##########################
 # Set-up the entry script
@@ -32,17 +65,24 @@ RUN touch entry_script.sh
 RUN chmod a+rx entry_script.sh
 RUN echo \
 '#!/bin/bash \n\
-if ! test -d ${TEMPLATE_ROOT} ; then\n\
-  echo "The project directory has not been mounted properly.  Please run the container with: docker run -v $""PWD:"${TEMPLATE_ROOT}" etc."\n\
+# Check that the container was run with a defined PACKAGE_ROOT\n\
+if ! test -d ${PACKAGE_ROOT} ; then\n\
+  echo "The project directory has not been mounted properly.  Please run the container with: docker run -v $""PWD:"${PACKAGE_ROOT}" etc."\n\
   exit 1\n\
 fi\n\
-if ! cmp -s ${TEST_ROOT}/poetry.lock.image ${TEMPLATE_ROOT}/poetry.lock ; then\n\
+# Check that the lock file hasn't changed since the container was built\n\
+# (if it has, then the container should be rebuilt)\n\
+if ! cmp -s ${HOME}/poetry.lock.image ${PACKAGE_ROOT}/poetry.lock ; then\n\
   echo poetry.lock has been updated since the image was built.  Please rebuild it and try again.\n\
   exit 1\n\
 fi\n\
-cd ${TEMPLATE_ROOT}\n\
-\n\
+# Activate the virtual env\n\
+cd ${HOME}\n\
+. venv/bin/activate\n\
+# Install the version of the package that is on disk when the container is run\n\
+cd ${PACKAGE_ROOT}\n\
 poetry install --only-root\n\
 echo\n\
+# Run pytest\n\
 pytest' \
 >> entry_script.sh

Makefile

@@ -10,4 +10,4 @@ docker-build:
 	@docker build -t ${PRJ_SLUG} .
 
 docker-tests:
-	@docker run -t -i --rm -v ${PRJ_PATH}:/template ${PRJ_SLUG} ./entry_script.sh
+	@docker run -t -i --rm -v ${PRJ_PATH}:/home/pytest/package ${PRJ_SLUG} /home/pytest/entry_script.sh

README.md

@@ -4,7 +4,7 @@
 
 <p align="center">
   <a href="https://www.python.org/downloads/release/python-3110/">
-    <img src="https://img.shields.io/badge/python-3.11-blue.svg" alt="Python 3.11">
+    <img src="https://img.shields.io/badge/python-3.13-blue.svg" alt="Python 3.13">
   </a>
   <a href='https://adacs-base-python-template.readthedocs.io/en/latest/?badge=latest'>
     <img src='https://readthedocs.org/projects/adacs-base-python-template/badge/?version=latest' alt='Documentation Status' />
@@ -50,7 +50,7 @@ and answer the questions:
 ![ADACS Python Template Questions](https://github.com/ADACS-Australia/adacs_template_python_base/blob/main/docs/assets/adacs_python_template_cookiecutter_questions.png?raw=true)
 
 ### Install the new project
-Create and activate a new virtual environment (**use Python version >= 3.11**) using your favourite method (if you don't know how to use Python environments, we advise you to go learn about them now) and install the project by running the following in the new repo directory:
+Create and activate a new virtual environment (**use Python version >= 3.13**) using your favourite method (if you don't know how to use Python environments, we advise you to go learn about them now) and install the project by running the following in the new repo directory:
 ``` console
 poetry install
 ```

docs/content/configuring_services.md

@@ -1,17 +1,16 @@
-(configing-new)=
-# Configuring a New Project
+(configuring-services)=
+# Configuring Services
 
-Develpers and project owners/maintainers will require accounts with one or all of the following services to work with this codebase.  This section details how these services need to be configured.  Following these steps should only be necessarry - or partially necessary - if a developer chooses to fork the project.
+This section details how the services leveraged by this project need to be configured.  If you have just rendered a new project and followed the instructions that were given, you should have already done the following.  For reference - or in case you are looking to configure a fork of a project - we repeat those instructions here.
 
+::: {note}
+The following instructions are only for owners/maintainers of this codebase.  Developers don't need to worry about any of this unless they are setting up a fork of the project.
+:::
+
+(configuring-github)=
 1. [***GitHub***](https:/github.com)
 
     To work with this codebase, you will require a *GitHub* account ([go here to get one](https://github.com)).
-
-    ::: {note}
-    If you have just rendered a new project and have followed the instructions that were given, you should already have done the
-    following.  For completeness though - or in case you are looking to configure a fork of a project - we note that the following
-    needs to be done:
-    :::
 
     Branch permissions for the main project repository should be configured to only permit merges from pull requests.  To do so, navigate to `Settings->Branches->Add branch ruleset` and:
 
@@ -22,49 +21,44 @@ Develpers and project owners/maintainers will require accounts with one or all o
     - select `Require status checks to pass` and add `Run all build and unit tests` from GitHub Actions as a required check
 
     This will ensure that all CI/CD tests pass before a merge to the main branch can be made.
-    
+
     ::: {note}
-    For those who have just rendered a new project, followed the instructions and are continuing to configure it, you need to do
-    the following:
+    The following secrets do not need to be configured if you do not want to use these services.  If left unconfigured, the corresponding functionality will simply be ignored.
     :::
 
     Several (optional) secrets need to be configured by navigating to `Settings->Secrets->Actions` and adding the following:
-    
+
     - To host the project documentation on *Read the Docs* (see below), the following secrets need to be set (see below for where to find these values):
-    
+
         - **RTD_WEBHOOK_TOKEN**, and
         - **RTD_WEBHOOK_URL**
-    
+
     - To make code releases available on the **Python Package Index** (see below), then the following secret needs to be set (see below for where to find this value):
-    
+
         - **PYPI_TOKEN**,
-    
+
     - To test code releases with the **Test Python Package Index** (see below), then the following secret needs to be set (see below for where to find this value):
-
-        - **TEST_PYPI_TOKEN**,
 
+        - **TEST_PYPI_TOKEN**,
 
 2. [__Read the Docs__](https://readthedocs.org)
 
-    ::: {note}
-    **Read the Docs** (*RTD*) is used to build and host the project documentation.  To take advantage of this functionality, this service needs to be configured by the owner/maintainer of the project.  Contributing developers or those who don't wish to have documentation published on *RTD* can ignore the following.
-    :::
-
     To (optionally) publish this project's documentation you will need a *RTD* account ([go here to get one](https://readthedocs.org)).  It can be configured in either of the following ways:
 
     1. **By connecting *RTD* to your *GitHub* account**
         - Ensure that your *GitHub* account has been connected.  This is done automatically if you log into *RTD* with your *GitHub* credentials.  If you logged in with your email, navigate to `<login_id>->Settings->Connected Services` by clicking on `Connect Your Accounts` and click `Connect to GitHub`.  You know your account is linked if it is listed below under `Active Services`.
 
         - Return to your *RTD* landing page by clicking on your account name at the top.  Click `Import a Project`.  Your *GitHub* repository should be listed here (you may need to refresh the list if it has been created recently).  Import it.
-
-        - To obtain **RTD_WEBHOOK_TOKEN**, navigate to `<Account>->Settings->API Tokens` on *Read the Docs*.  If a token has been created already, you can use it.  Otherwise (or if you want a token specifically for this project), create a new one.
-
+        - To obtain **RTD_WEBHOOK_TOKEN**, navigate to `<Account>->Settings->API Tokens` on *Read the Docs*.  Create a new one.
         - To obtain **RTD_WEBHOOK_URL**, migrate to the `Admin->Integrations` tab on the *RTD* project page.  Click on your incomming webhook and get the URL there.
 
     2. **By creating a Generic Webhook**
-        - Navigate to the `Admin->Integrations` tab on the *RTD* project page and click `Add integration`.  Then select `Generic API incoming webhook` from the dropdown and click `Add integration`.
+        - If you do not have your *RTD* account connected to *GitHub*, import your project manually by
+        clicking `Import a Project->Import Manually` and providing the details of your *GitHub* repo.
+
+        - Navigate to your new project and click `Admin->Integrations->Add integration` and select `Generic API incoming webhook` from the dropdown.
 
-        - To obtain **RTD_WEBHOOK_URL** and **RTD_WEBHOOK_TOKEN**, migrate to the `Admin->Integrations` tab on the *RTD* project page and click on your incomming webhook.
+        - Values for **RTD_WEBHOOK_URL** and **RTD_WEBHOOK_TOKEN** are given when you create the webhook, but if you need to retrieve them late, migrate to the `Admin->Integrations` tab on the *RTD* project page and click on your incomming webhook.
 
     Once properly configured, the documentation for this project should build automatically on *RTD* every time you [generate a new release](#new-release).
 
@@ -75,20 +69,15 @@ Develpers and project owners/maintainers will require accounts with one or all o
 (config-pypi)=
 3. The [__Python Package Index (*PyPI*)__](https://pypi.org)
 
-    ::: {note}
-    **The Python Package Index** (*PyPI*) and **The Test Python Package Index (*TestPyPI*) are used to publish code releases.  To take advantage of this functionality, this service needs to be configured by the owner/maintainer of the project.  Contributing developers or those who don't wish to have documentation published on *RTD* can ignore the following.
-    :::
-
     To (optionally) publish releases of this project's code you will need a *PyPI* account ([go here to get one](https://pypi.org)).  To (optionally) generate test releases, you will need a *TestPyPI* account.  They operate the same way and can both be configured as follows:
+    - An API token will need to be created and added to your *GitHub* project as **PYPI_TOKEN** (as detailed above).  This can be generated from the *PyPI* UI by navigating to `Account Settings->Add API Token`.  **In the first instance - before the project exists on your account - generate a token with `Entire Account` scope.  Once the project has been published for a first time to *PyPI*, the initial token can be deleted and a new one generated with an project scope selected to be that of the project.  Make sure to update the *GitHub* secret value once you have done so.**
 
-        - An API token will need to be created and added to your *GitHub* project as **PYPI_TOKEN** (as detailed above).  This can be generated from the *PyPI* UI by navigating to `Account Settings->Add API Token`.  In the first instance - before the project exists on your account - generate a token with `Entire Account` scope.  Once the project has been published for a first time to *PyPI*, the initial token can be deleted and a new one generated with an project scope selected to be that of the project.  Make sure to update the *GitHub* secret value once you have done so.
-
-        - Repeat this process for *TestPyPI* if you want to be able to generate test releases, adding it as a secret to your *GitHub* repo with the name **TEST_PYPI_TOKEN**
+    - Repeat this process for *TestPyPI* if you want to be able to generate test releases, adding it as a secret to your *GitHub* repo with the name **TEST_PYPI_TOKEN**
 
     ::: {note}
     To create a test release, flag it as a `pre-release` through the *GitHub* interface when you generate a release, and it will be published on *test.PyPI.org* rather than *PyPI.org*.  If this token is not defined, publication will not happen on either, if this option is flagged.
     :::
 
-    ::: {note}
+    ::: {warning}
     Although `poetry` can be used to directly publish this project to *PyPI*, users should not do this.  The proper way to publish the project is through the *GitHub* interface, which leverages the *GitHub Workflows* of this project to ensure the enforcement of project standards before a new version can be created.
     :::