Employ a src-based layout for code base (#1971)

### What kind of change does this PR introduce?

* Adapts the code base to use a `src`-based layout (in lieu of a flat
code base layout)
* Added a stricter `yamllint` configuration (no changes made to existing
YAML files)
* Pins `pint` to >=0.24.4 in order to support Python3.13 (and evade
failures from `flexparser>=0.4`).

### Does this PR introduce a breaking change?

Yes. The code base has been modified such that existing interactive
(`--editable`) installations will need to be re-installed.

This change prevents developers from accidentally running tests or
importing `xclim` from the root directory. That's essentially the major
gain.

Otherwise, we can say that this brings `xclim` closer in line with the
other `Ouranosinc/cookiecutter-pypackage` template-based projects.

### Other information:


https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/

https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#the-src-layout-and-testing

.flake8

@@ -14,7 +14,7 @@ ignore =
 	RST213,
 	W503
 per-file-ignores =
-	xclim/core/locales.py:RST399
+	src/xclim/core/locales.py:RST399
 rst-directives =
 	bibliography,
 	autolink-skip

.github/labeler.yml

@@ -40,10 +40,10 @@
 'indicators':
   - changed-files:
     - any-glob-to-any-file:
-      - 'xclim/indicators/**/*'
-      - 'xclim/indices/**/_*.py'
-      - 'xclim/data/**/*.json'
-      - 'xclim/data/**/*.yml'
+      - 'src/xclim/indicators/**/*'
+      - 'src/xclim/indices/**/_*.py'
+      - 'src/xclim/data/**/*.json'
+      - 'src/xclim/data/**/*.yml'
 
 'information':
   - changed-files:
@@ -53,5 +53,5 @@
 'sdba':
   - changed-files:
     - any-glob-to-any-file:
-      - 'xclim/sdba/**/*'
+      - 'src/xclim/sdba/**/*'
       - 'tests/test_sdba/*.py'

.github/workflows/bump-version.yml

@@ -23,8 +23,8 @@ on:
       - environment.yml
       - pylintrc
       - pyproject.toml
+      - src/xclim/__init__.py
       - tox.ini
-      - xclim/__init__.py
 
 permissions:
   contents: read
@@ -70,7 +70,7 @@ jobs:
           trust_level: 5
       - name: Current Version
         run: |
-          CURRENT_VERSION="$(grep -E '__version__'  xclim/__init__.py | cut -d ' ' -f3)"
+          CURRENT_VERSION="$(grep -E '__version__'  src/xclim/__init__.py | cut -d ' ' -f3)"
           echo "current_version=${CURRENT_VERSION}"
           echo "CURRENT_VERSION=${CURRENT_VERSION}" >> $GITHUB_ENV
       - name: Install CI libraries
@@ -85,7 +85,7 @@ jobs:
             echo "Version is stable, bumping 'patch' version"
             bump-my-version bump patch
           fi
-          NEW_VERSION="$(grep -E '__version__'  xclim/__init__.py | cut -d ' ' -f3)"
+          NEW_VERSION="$(grep -E '__version__'  src/xclim/__init__.py | cut -d ' ' -f3)"
           echo "new_version=${NEW_VERSION}"
           echo "NEW_VERSION=${NEW_VERSION}" >> $GITHUB_ENV
       - name: Push Changes

.github/workflows/codeql.yml

@@ -10,7 +10,7 @@ on:
       - Makefile
       - pyproject.toml
       - tox.ini
-      - xclim/__init__.py
+      - src/xclim/__init__.py
       - docs/*/*.ipynb
       - docs/*/*.py
       - docs/*/*.rst

.github/workflows/main.yml

@@ -8,7 +8,7 @@ on:
       - CHANGELOG.rst
       - README.rst
       - pyproject.toml
-      - xclim/__init__.py
+      - src/xclim/__init__.py
   pull_request:
     types:
       - opened
@@ -86,7 +86,7 @@ jobs:
           key: ${{ runner.os }}-xclim-testdata-${{ env.XCLIM_TESTDATA_BRANCH }}-${{ hashFiles('pyproject.toml', 'tox.ini') }}-lint
       - name: Run pylint
         run: |
-          python -m pylint --rcfile=.pylintrc.toml --disable=import-error --exit-zero xclim
+          python -m pylint --rcfile=.pylintrc.toml --disable=import-error --exit-zero src/xclim
       - name: Run linting suite
         run: |
           python -m tox -e lint

.github/workflows/upstream.yml

@@ -7,7 +7,7 @@ on:
       - CHANGELOG.rst
       - README.rst
       - pyproject.toml
-      - xclim/__init__.py
+      - src/xclim/__init__.py
   schedule:
     - cron: "0 0 * * *" # Daily “At 00:00” UTC
   workflow_dispatch: # allows you to trigger the workflow run manually

.gitignore

@@ -24,7 +24,6 @@ parts/
 sdist/
 var/
 wheels/
-src/
 *.egg-info/
 .installed.cfg
 *.egg

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ repos:
     hooks:
       - id: pyupgrade
         args: ['--py310-plus']
-        exclude: 'xclim/core/indicator.py'
+        exclude: 'src/xclim/core/indicator.py'
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
@@ -91,7 +91,7 @@ repos:
     hooks:
       - id: blackdoc
         additional_dependencies: [ 'black==24.10.0' ]
-        exclude: '(xclim/indices/__init__.py|docs/installation.rst)'
+        exclude: '(src/xclim/indices/__init__.py|docs/installation.rst)'
       - id: blackdoc-autoupdate-black
   - repo: https://github.com/codespell-project/codespell
     rev: v2.3.0
@@ -104,7 +104,7 @@ repos:
     hooks:
       - id: numpydoc-validation
         # Exclude the missing submodule from the xclim.core, see:
-        exclude: ^docs/|^tests/|^xclim/sdba|^xclim/core/missing.py
+        exclude: ^docs/|^tests/|^src/xclim/sdba|^src/xclim/core/missing.py
   - repo: https://github.com/gitleaks/gitleaks
     rev: v8.21.2
     hooks:

.readthedocs.yml

@@ -13,9 +13,9 @@ build:
     python: "mambaforge-22.9"
   jobs:
     pre_build:
-      - sphinx-apidoc -o docs/apidoc/ --private --module-first xclim xclim/testing/tests xclim/indicators xclim/indices
+      - sphinx-apidoc -o docs/apidoc/ --private --module-first src/xclim src/xclim/testing/tests src/xclim/indicators src/xclim/indices
       - rm docs/apidoc/xclim.rst
-      - env SPHINX_APIDOC_OPTIONS="members,undoc-members,show-inheritance,noindex" sphinx-apidoc -o docs/apidoc/ --private --module-first xclim xclim/testing/tests
+      - env SPHINX_APIDOC_OPTIONS="members,undoc-members,show-inheritance,noindex" sphinx-apidoc -o docs/apidoc/ --private --module-first src/xclim src/xclim/testing/tests
       - sphinx-build -b linkcheck docs/ _build/linkcheck || true
 
 conda:

.yamllint.yaml

@@ -1,8 +1,39 @@
 ---
 
 rules:
+
+  brackets:
+    forbid: false
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+
+  commas:
+    min-spaces-after: 1
+
   document-start: disable
+
+  float-values:
+    require-numeral-before-decimal: true
+
+  hyphens:
+    max-spaces-after: 1
+
+  indentation:
+    indent-sequences: whatever
+    spaces: consistent
+
+  key-duplicates:
+    forbid-duplicated-merge-keys: true
+
   line-length:
+    allow-non-breakable-words: true
+    allow-non-breakable-inline-mappings: true
     max: 120
     level: warning
+
+  new-lines:
+    type: unix
+
+  trailing-spaces: {}
+
   truthy: disable

CHANGELOG.rst

@@ -31,6 +31,8 @@ Internal changes
 * In order to address 403 (forbidden) request errors when retrieving data from GitHub via ReadTheDocs, the ``nimbus`` class has been modified to use an overloaded `fetch` method that appends a User-Agent header to the request. (:pull:`2001`).
 * Addressed a very rare race condition that can happen if `pytest` is tearing down the test environment when running across multiple workers. (:pull:`1863`).
 * The `numpydoc` linting tool has been added to the development dependencies, linting checks, and the `pre-commit` configuration. (:pull:`1988`).
+* `xclim` now uses a `src` layout for the codebase. Structure-dependent functions, documentation, and build commands have been adapted to reflect these changes. (:pull:`1971`).
+* Added a more robust `yamllint` configuration to ensure that all YAML files are linted consistently. (:pull:`1971`).
 
 CI changes
 ^^^^^^^^^^