Project general update

.devcontainer/Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.9
+FROM python:3.11
 
 RUN git config --global core.filemode false && \
     git config --global core.autocrlf true && \

.flake8

@@ -0,0 +1,20 @@
+[flake8]
+hang-closing              = true
+ignore                    = D101,D102,D103,D107,D401,E128,E251,E501,W503
+in-place                  = true
+inline-quotes             = "
+multiline-quotes          = """
+import-order-style        = appnexus
+no-accept-encodings       = true
+application-import-names  = openfisca_aotearoa
+application-package-names = openfisca_core
+exclude                   = .git,__pycache__,.venv,.github,.devcontainer,docs
+
+; D101:                   Variables already provide label/description
+; D102/103:               Do not document methods/functions
+; D107:                   Do not document __init__ method
+; D401:                   Do not require the imperative mood
+; E128/133:               Prefer hang-closing visual indents
+; E251:                   Prefer `function(x = 1)` over `function(x=1)`
+; E501:                   Do not enforce a maximum line length
+; W503/4:                 Break lines before binary operators (Knuth's style)

.github/ISSUE_TEMPLATE.md

@@ -1,6 +1,6 @@
 Hi there!
 
-I really enjoy OpenFisca, but I recently encountered an issue.
+While utilising OpenFisca Aotearoa I recently encountered an issue.
 
 ### Here is what I did:
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,4 +1,4 @@
-Thanks for contributing to OpenFisca ! Please remove this line, as well as, for each line below, the cases which are not relevant to your contribution :)
+Thanks for contributing to OpenFisca Aotearoa! Please remove this line, as well as, for each line below, the cases which are not relevant to your contribution :)
 
 * Tax and benefit system evolution. | Technical improvement. | Crash fix. | Minor change.
 * Impacted periods: all. | until DD/MM/YYYY. | from DD/MM/YYYY.

.github/has-functional-changes.sh

@@ -0,0 +1,12 @@
+#! /usr/bin/env bash
+
+IGNORE_DIFF_ON="README.md CONTRIBUTING.md Makefile .gitignore .github/*"
+
+last_tagged_commit=`git describe --tags --abbrev=0 --first-parent`  # --first-parent ensures we don't follow tags not published in main through an unlikely intermediary merge commit
+
+if git diff-index --name-only --exit-code $last_tagged_commit -- . `echo " $IGNORE_DIFF_ON" | sed 's/ / :(exclude)/g'`  # Check if any file that has not be listed in IGNORE_DIFF_ON has changed since the last tag was published.
+then
+  echo "No functional changes detected."
+  exit 1
+else echo "The functional files above were changed."
+fi

.github/is-version-number-acceptable.sh

@@ -0,0 +1,39 @@
+#! /usr/bin/env bash
+
+if [[ ${GITHUB_REF#refs/heads/} == main ]]
+then
+    echo "No need for a version check on main."
+    exit 0
+fi
+
+if ! $(dirname "$BASH_SOURCE")/has-functional-changes.sh
+then
+    echo "No need for a version update."
+    exit 0
+fi
+
+current_version=$(grep '^version =' pyproject.toml | cut -d '"' -f 2)  # parsing with tomllib is complicated, see https://github.com/python-poetry/poetry/issues/273
+
+if [[ ! $current_version ]]
+then
+    echo "Error getting current version"
+    exit 1
+fi
+
+if git rev-parse --verify --quiet $current_version
+then
+    echo "Version $current_version already exists in commit:"
+    git --no-pager log -1 $current_version
+    echo
+    echo "Update the version number in pyproject.toml before merging this branch into main."
+    echo "Look at the CONTRIBUTING.md file to learn how the version number should be updated."
+    exit 2
+fi
+
+if ! $(dirname "$BASH_SOURCE")/has-functional-changes.sh | grep --quiet CHANGELOG.md
+then
+    echo "CHANGELOG.md has not been modified, while functional changes were made."
+    echo "Explain what you changed before merging this branch into main."
+    echo "Look at the CONTRIBUTING.md file to learn how to write the changelog."
+    exit 2
+fi

.github/lint-files.sh

@@ -0,0 +1,32 @@
+#! /usr/bin/env bash
+
+# Usage: lint-files.sh <file_pattern> <linter_command>
+#
+# Example usage: 
+#   lint-files.sh "*.py" "flake8"
+#   lint-files.sh "tests/*.yaml" "yamllint"
+
+file_pattern=$1
+linter_command=$2
+
+if [ -z "$file_pattern" ] || [ -z "$linter_command" ]
+then
+    echo "Usage: $0 <file_pattern> <linter_command>"
+    exit 1
+fi
+
+last_tagged_commit=$(git describe --tags --abbrev=0 --first-parent 2>/dev/null) # Attempt to find the last tagged commit in the direct ancestry of the main branch avoiding tags introduced by merge commits from other branches
+
+if [ -z "$last_tagged_commit" ]
+then
+    last_tagged_commit=$(git rev-list --max-parents=0 HEAD) # Fallback to finding the root commit if no tags are present
+fi
+
+if ! changed_files=$(git diff-index --name-only --diff-filter=ACMR --exit-code $last_tagged_commit -- "$file_pattern")
+then
+    echo "Linting the following files:"
+    echo "$changed_files"
+    $linter_command $changed_files
+else
+    echo "No changed files matching pattern '$file_pattern' to lint."
+fi

.github/publish-git-tag.sh

@@ -0,0 +1,5 @@
+#! /usr/bin/env bash
+
+current_version=$(grep '^version =' pyproject.toml | cut -d '"' -f 2)  # parsing with tomllib is complicated, see https://github.com/python-poetry/poetry/issues/273
+git tag $current_version
+git push --tags  # update the repository version

.github/test-api.sh

@@ -0,0 +1,14 @@
+#! /usr/bin/env bash
+
+PORT=5000
+ENDPOINT=spec
+
+openfisca serve --country-package openfisca_aotearoa --port $PORT &
+server_pid=$!
+
+curl --retry-connrefused --retry 10 --retry-delay 5 --fail http://127.0.0.1:$PORT/$ENDPOINT | python -m json.tool > /dev/null
+result=$?
+
+kill $server_pid
+
+exit $?

.github/workflows/build.yml

@@ -0,0 +1,34 @@
+name: Build
+
+on:
+  workflow_call:
+
+jobs:
+  build-and-cache:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11.9 # Patch version must be specified to avoid any cache confusion, since the cache key depends on the full Python version. Any difference in patches between jobs will lead to a cache not found error.
+
+      - name: Cache build
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }} # Cache the entire build Python environment
+          restore-keys: |
+            build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}
+            build-${{ env.pythonLocation }}-
+
+      - name: Build package
+        run: make build
+
+      - name: Cache release
+        uses: actions/cache@v4
+        with:
+          path: dist
+          key: release-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }}

.github/workflows/deploy.yml

@@ -0,0 +1,70 @@
+ame: Deploy
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  validate:
+    uses: "./.github/workflows/validate.yml"
+
+  # GitHub Actions does not have a halt job option to stop from deploying if no functional changes were found.
+  # We thus execute a separate deployment job depending on the output of this job.
+  check-for-functional-changes:
+    runs-on: ubuntu-22.04
+    outputs:
+      status: ${{ steps.stop-early.outputs.status }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all the tags
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11.9
+      - id: stop-early
+        run: |
+          if "${GITHUB_WORKSPACE}/.github/has-functional-changes.sh"
+          then 
+            echo "status=success" >> $GITHUB_OUTPUT
+          fi
+
+  check-pypi-token: # Use intermediary job as secrets cannot be directly referenced in `if:` conditionals; see https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#using-secrets-in-a-workflow
+    runs-on: ubuntu-22.04
+    outputs:
+      pypi_token_present: ${{ steps.check_token.outputs.pypi_token_present }}
+    steps:
+      - name: Check PyPI token is defined
+        id: check_token
+        run: |
+          if [[ -n "${{ secrets.PYPI_TOKEN }}" ]]
+          then
+            echo "pypi_token_present=true" >> $GITHUB_OUTPUT
+          else
+            echo "pypi_token_present=false" >> $GITHUB_OUTPUT
+          fi
+
+  deploy:
+    runs-on: ubuntu-22.04
+    needs: [ validate, check-for-functional-changes, check-pypi-token ]
+    if: needs.check-for-functional-changes.outputs.status == 'success' && needs.check-pypi-token.outputs.pypi_token_present == 'true'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11.9
+      - name: Restore build
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }}
+      - name: Restore built package
+        uses: actions/cache@v4
+        with:
+          path: dist
+          key: release-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }}
+      - name: Upload a Python package to PyPi
+        run: twine upload dist/* --username __token__ --password ${{ secrets.PYPI_TOKEN }}
+      - name: Publish a git tag
+        run: "${GITHUB_WORKSPACE}/.github/publish-git-tag.sh"