Merge pull request #472 from TheHive-Project/467-investigate-the-usefulness-of-the-nox-project-for-dev-scripts

Kamforka · web-flow · commit ae2b0cfec34d · 2025-07-08T11:08:19.000+02:00
#467 - Introduce nox to manage dev scripts
diff --git a/.github/workflows/_build-docs.yml b/.github/workflows/_build-docs.yml
@@ -11,7 +11,7 @@ jobs:
         uses: actions/setup-python@v4
         with: 
           python-version: 3.13
-      - name: Install build dependencies
-        run: pip install --no-cache-dir -U pip .['docs']
+      - name: Install dependencies
+        run: pip install --no-cache-dir -U pip .['dev']
       - name: Build docs
-        run: ./scripts/cd.py --build-docs
+        run: nox --session=build-docs
diff --git a/.github/workflows/_build-package.yml b/.github/workflows/_build-package.yml
@@ -11,10 +11,10 @@ jobs:
         uses: actions/setup-python@v4
         with: 
           python-version: 3.13
-      - name: Install build dependencies
-        run: pip install --no-cache-dir -U pip .['build']
+      - name: Install dependencies
+        run: pip install --no-cache-dir -U pip .['dev']
       - name: Build package
-        run: ./scripts/cd.py --build
+        run: nox --session=build
       - name: Upload built distributions
         uses: actions/upload-artifact@v4
         with:
diff --git a/.github/workflows/_check-release-notes.yml b/.github/workflows/_check-release-notes.yml
@@ -11,12 +11,7 @@ jobs:
         uses: actions/setup-python@v4
         with: 
           python-version: 3.13
+      - name: Install dependencies
+        run: pip install --no-cache-dir -U pip .['dev']
       - name: Check release notes
-        run: ./scripts/linkify_release_notes.py --check
-      - name: Lookup version in release notes 
-        run: |
-          VERSION=$(grep -Po '(?<=version = ")[^"]*' pyproject.toml)
-          if ! grep -qF "## $VERSION " "docs/release-notes.md"; then
-            echo "No release notes found for version '$VERSION'"
-            exit 1
-          fi
+        run: nox --session=check-release-notes
diff --git a/.github/workflows/_deploy-docs.yml b/.github/workflows/_deploy-docs.yml
@@ -11,12 +11,12 @@ jobs:
         uses: actions/setup-python@v4
         with: 
           python-version: 3.13
-      - name: Install build dependencies
-        run: pip install --no-cache-dir -U pip .['docs']
+      - name: Install dependencies
+        run: pip install --no-cache-dir -U pip .['dev']
       - name: Configure git
         run: |
           git fetch origin gh-pages --depth=1
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
       - name: Deploy to github pages
-        run: ./scripts/cd.py --deploy-docs
+        run: nox --session=deploy-docs
diff --git a/.github/workflows/_integration-tests.yml b/.github/workflows/_integration-tests.yml
@@ -15,9 +15,9 @@ jobs:
         with:
           python-version: 3.13
       - name: Install dependencies
-        run: pip install --no-cache-dir -U pip .['test']
+        run: pip install --no-cache-dir -U pip .['dev']
       - name: Run integration tests
-        run: scripts/ci.py --test
+        run: nox --session=test
       - name: Upload coverage results
         uses: codecov/codecov-action@v4
         with:
diff --git a/.github/workflows/_static-checks.yml b/.github/workflows/_static-checks.yml
@@ -16,13 +16,13 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: pip install --no-cache-dir -U pip .['dev']
-      - name: Lint check with flake8
-        run: scripts/ci.py --lint
+      - name: Style check with flake8
+        run: nox --session=style
       - name: Format check with black
-        run: scripts/ci.py --format
+        run: nox --session=format
       - name: Type check with mypy
-        run: scripts/ci.py --type 
+        run: nox --session=type
       - name: CVE check with pip-audit
-        run: scripts/ci.py --cve
+        run: nox --session=cve
       - name: Security check with bandit
-        run: scripts/ci.py --security
+        run: nox --session=security
diff --git a/.github/workflows/_upload-package.yml b/.github/workflows/_upload-package.yml
@@ -10,14 +10,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Compare tag and package version
-        run: |
-          TAG=${GITHUB_REF#refs/*/}
-          VERSION=$(grep -Po '(?<=version = ")[^"]*' pyproject.toml)
-          if [ "$TAG" != "$VERSION" ]; then
-            echo "Tag value and package version are different: ${TAG} != ${VERSION}"
-            exit 1
-          fi
       - name: Download built distributions
         uses: actions/download-artifact@v4
         with:
@@ -27,10 +19,10 @@ jobs:
         uses: actions/setup-python@v4
         with: 
           python-version: 3.13
-      - name: Install build dependencies
-        run: pip install --no-cache-dir -U pip .['build']
+      - name: Install dependencies
+        run: pip install --no-cache-dir -U pip .['dev']
       - name: Upload to PyPI
-        run: ./scripts/cd.py --upload
+        run: nox --session=upload
         env:
           TWINE_REPOSITORY_URL: https://upload.pypi.org/legacy/
           TWINE_USERNAME: __token__
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -4,7 +4,7 @@ repos:
   hooks:
     - id: ci-checks 
       name: ci-checks
-      entry: scripts/ci.py
+      entry: nox
       language: system
       pass_filenames: false
       always_run: true
diff --git a/README.md b/README.md
@@ -307,17 +307,23 @@ To contribute to `thehive4py`, follow these steps:
 
 ## Run CI checks before pushing changes
 
-To ensure the integrity of your changes and maintain code quality, you can run CI checks before pushing your changes to the repository. Use one of the following methods:
+The project is utilizing the [nox] library to define and run automated dev scripts.
+
+To ensure the integrity of your changes and maintain code quality you can use the provided sessions from the local `noxfile.py`.
+For example you can run CI checks before pushing your changes to the repository. Use one of the following methods:
 
 **Method 1: Manual check**
 
-Run the CI checks manually by executing the following command:
+Run the CI checks manually by using the following command:
 
-```
-python scripts/ci.py 
-```
+    nox
+
+This will trigger all CI checks except tests as the `noxfile.py` is configured to do so by default.
+
+
+To run individual checks one can list all the available sessions with:
 
-This command will trigger the CI checks and provide feedback on any issues that need attention.
+    nox --list
 
 **Method 2: Automatic checks with pre-commit hooks [experimental]**
 
@@ -353,15 +359,25 @@ Once TheHive is responsive the suite will initialize the instance with a setup r
 Please note that due to this initial setup the very first test run will idle for some time to make sure everything is up and running. Any other subsequent runs' statup time should be significantly faster.  
 
 ### Testing locally
-To execute the whole test suite locally one can use the `scripts/ci.py` utility script like:
+To execute the whole test suite locally one can use the `test` session provided by the local `noxfile.py` utility script like:
+
+    nox --session=test
+
+or
+
+    nox -s test
+
+for short.
+
+Note however that the above will command execute the entire test suite which can take several minutes to complete.
+In case one wants to execute only a portion of the test suite then the easiest workaround is to pass additional arguments to the session e.g.:
 
-    ./scripts/ci.py --test
+    nox -s test -- tests/test_observable_endpoint.py -v
 
-Note however that the above will execute the entire test suite which can take several minutes to complete.
-In case one wants to execute only a portion of the test suite then the easiest workaround is to use `pytest` and pass the path to the specific test module. For example to only execute tests for the alert endpoints one can do:
+The nox command will parse additional arguments after the `--` option terminator argument and they will be passed to the underlying `pytest` command.
 
-    pytest -v tests/test_alert_endpoint.py
 
 [get-docker]: https://docs.docker.com/get-docker/
 [query-api-docs]: https://docs.strangebee.com/thehive/api-docs/#operation/Query%20API
 [thehive-image]: https://hub.docker.com/r/strangebee/thehive
+[nox]: https://nox.thea.codes/en/stable/
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -75,7 +75,7 @@ plugins:
   - mkdocstrings:
       handlers:
         python:
-          import:
+          inventories:
             - https://docs.python.org/3/objects.inv
             - https://requests.readthedocs.io/en/stable/objects.inv
           options:
diff --git a/noxfile.py b/noxfile.py
@@ -0,0 +1,121 @@
+import os
+
+import nox
+
+PROJECT_DIR = os.path.dirname(__file__)
+THEHIVE4PY_DIR = os.path.join(PROJECT_DIR, "thehive4py/")
+TESTS_DIR = os.path.join(PROJECT_DIR, "tests/")
+
+nox.options.default_venv_backend = "none"
+nox.options.tags = ["audit", "lint"]
+
+
+@nox.session(tags=["ci", "lint"])
+def style(session: nox.Session):
+    """Run style checks with flake8."""
+    session.run("flake8", THEHIVE4PY_DIR, TESTS_DIR)
+
+
+@nox.session(tags=["ci", "lint"])
+def format(session: nox.Session):
+    """Run format checks with black."""
+    session.run("black", "--check", THEHIVE4PY_DIR, TESTS_DIR)
+
+
+@nox.session(tags=["ci", "lint"])
+def type(session: nox.Session):
+    """Run type checks with mypy."""
+    session.run("mypy", "--install-types", "--non-interactive", THEHIVE4PY_DIR)
+
+
+@nox.session(tags=["ci", "audit"])
+def cve(session: nox.Session):
+    """Run cve checks with pip-audit."""
+    session.run("pip-audit", PROJECT_DIR)
+
+
+@nox.session(tags=["ci", "audit"])
+def security(session: nox.Session):
+    """Run security checks with bandit."""
+    session.run("bandit", "-r", THEHIVE4PY_DIR)
+
+
+@nox.session(tags=["ci", "test"])
+def test(session: nox.Session):
+    """Run integration tests with pytest."""
+
+    if not session.posargs:
+        session.run("pytest", "-v", "--cov")
+    else:
+        session.run("pytest", *session.posargs)
+
+
+@nox.session(tags=["cd", "build"])
+def build(session: nox.Session):
+    """Build with the build module."""
+    session.run("rm", "-rf", "build/", "dist/")
+    session.run("python", "-m", "build", "--sdist", "--wheel")
+
+
+@nox.session(tags=["cd", "upload"])
+def upload(session: nox.Session):
+    """Upload to PyPI using twine."""
+
+    session.run(
+        "bash",
+        "-c",
+        r"""
+        TAG=${GITHUB_REF#refs/*/}
+        VERSION=$(grep -Po '(?<=version = ")[^"]*' pyproject.toml)
+        if [ "$TAG" != "$VERSION" ]; then
+          echo "Tag value and package version are different: ${TAG} != ${VERSION}"
+          exit 1
+        else
+          echo "Matching tag value and package version!"
+        fi
+        """,
+    )
+    session.run("twine", "upload", "dist/*")
+
+
+@nox.session(tags=["cd", "docs"], name="build-docs")
+def build_docs(session: nox.Session):
+    """Build docs locally."""
+    session.run("mkdocs", "build", "--clean", "--strict")
+
+
+@nox.session(tags=["cd", "docs"], name="deploy-docs")
+def deploy_docs(session: nox.Session):
+    """Deploy docs to gh-pages."""
+    session.run("mkdocs", "build", "--clean", "--strict")
+
+
+@nox.session(tags=["utils", "docs"], name="serve-docs")
+def serve_docs(session: nox.Session):
+    """Serve docs locally."""
+    session.run("mkdocs", "serve", "--clean", "--strict")
+
+
+@nox.session(tags=["utils", "docs"], name="linkify-release-notes")
+def linkify_release_notes(session: nox.Session):
+    """Linkify plain github release notes for the docs."""
+    session.run("./scripts/linkify_release_notes.py")
+
+
+@nox.session(tags=["cd", "docs"], name="check-release-notes")
+def check_release_notes(session: nox.Session):
+    """Check release notes for deployment."""
+    session.run("./scripts/linkify_release_notes.py", "--check")
+    session.run(
+        "bash",
+        "-c",
+        r"""
+        VERSION=$(grep -Po '(?<=version = ")[^"]*' pyproject.toml)
+        if ! grep -qF "## $VERSION " "docs/release-notes.md"; then
+          echo "No release notes found for version '$VERSION'"
+          exit 1
+        else
+          echo "Release notes found for version '$VERSION'"
+        fi
+        """,
+    )
diff --git a/pyproject.toml b/pyproject.toml
@@ -10,7 +10,7 @@ requires-python = ">=3.9"
 dependencies = ["requests~=2.27", "typing_extensions==4.*"]
 readme = "README.md"
 keywords = ["thehive5", "api", "client"]
-license = { text = "MIT" }
+license = "MIT"
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -21,7 +21,6 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
-    "License :: OSI Approved :: MIT License",
 ]
 authors = [{ name = "Szabolcs Antal", email = "antalszabolcs01@gmail.com" }]
 
@@ -31,7 +30,7 @@ build = ["build", "twine"]
 docs = ["mkdocs", "mkdocs-material", "mkdocstrings-python", "mike"]
 lint = ["black", "flake8-pyproject", "mypy", "pre-commit"]
 test = ["pytest", "pytest-cov"]
-dev = ["thehive4py[audit, lint, test, build, docs]"]
+dev = ["thehive4py[audit, lint, test, build, docs]", "nox"]
 
 [tool.setuptools.packages.find]
 include = ["thehive4py*"]
diff --git a/scripts/cd.py b/scripts/cd.py
diff --git a/scripts/ci.py b/scripts/ci.py
