Add checks (#4)

* git ignore file

* pip tools config for generating lock files

* requirements for checkers and formatters

* nox sessions to automate checks

* add ci workflows

* add docs for nox sessions and dependencies

.github/workflows/ci.yaml

@@ -0,0 +1,26 @@
+name: Forge Webhook Parser CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - "main"
+  workflow_dispatch:
+
+jobs:
+  nox:
+    uses: ./.github/workflows/reusable-nox.yaml
+
+  check:
+    if: always()
+
+    needs:
+      - nox
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Decide whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@release/v1
+      with:
+        jobs: ${{ toJSON(needs) }}

.github/workflows/reusable-nox.yaml

@@ -0,0 +1,30 @@
+---
+name: nox
+
+"on":
+  workflow_call:
+
+jobs:
+  nox:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - session: static
+            python-versions: "3.12"
+          - session: formatters_check
+            python-versions: "3.12"
+          - session: typing
+            python-versions: "3.12"
+    name: "Run nox ${{ matrix.session }} session"
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+      - name: Setup nox
+        uses: wntrblm/[email protected]
+        with:
+          python-versions: "${{ matrix.python-versions }}"
+      - name: "Run nox -e ${{ matrix.session }}"
+        run: |
+          nox -e "${{ matrix.session }}"

.gitignore

@@ -0,0 +1,134 @@
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+site/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# VScode stuff
+.vscode/

.pip-tools.toml

@@ -0,0 +1,5 @@
+[tool.pip-tools]
+resolver = "backtracking"
+allow-unsafe = true
+strip-extras = true
+quiet = true

README.md

@@ -4,4 +4,70 @@
 
 Library for parsing webhook payloads from popular git forges
 
-Under construction
+## Verifying your pull request
+
+We welcome all contributions.
+If you plan to submit a pull request with changes, you should run the automated tests to check for issues.
+
+### Setting up nox
+
+This project includes a `nox` configuration to automate tests, checks, and other functions.
+You can use these automated tests to help you verify changes before you submit a PR.
+
+* Install `nox` using `python3 -m pip install nox` or your distribution's package manager.
+
+* Execute `nox` from the repository root with no arguments to run all Python code checkers.
+
+* Alternatively, you can run only certain tasks as outlined in the following sections.
+  Run `nox --list` to view available sessions.
+
+### Running automated tests
+
+* Perform static analysis with [ruff](https://docs.astral.sh/ruff/).
+
+  ``` bash
+  nox -s static
+  ```
+
+* Reformat code with [black](https://black.readthedocs.io/en/stable/) and [isort](https://pycqa.github.io/isort/).
+
+  ``` bash
+  nox -s formatters
+  ```
+
+* Check code for formatting issues without applying changes.
+
+  ``` bash
+  nox -s formatters_check
+  ```
+
+* Perform static type checking with [mypy](https://mypy.readthedocs.io/en/stable/).
+
+  ``` bash
+  nox -s typing
+  ```
+
+## Dependency files
+
+`nox` sessions use dependencies from requirements files in the `requirements/` directory.
+Each session has a `requirements/*.in` file with direct dependencies and a lock file in `requirements/*.txt` that pins exact versions for both direct and transitive dependencies.
+
+* Use the following `nox` session to update all dependency lock files:
+
+  ``` bash
+  nox -s pip-compile
+  ```
+
+* Update specific dependency lock files with individual `nox` sessions, for example:
+
+  ``` bash
+  nox -s "pip-compile-3.12(formatters)"
+  ```
+
+By default, the `nox` sessions upgrade dependencies.
+You can pass `pip-compile` options `--no-upgrade` and `--upgrade-package` to update only specific packages and keep other dependencies at their current version.
+For example, to upgrade the `isort` package only:
+
+``` bash
+nox -s "pip-compile-3.12(formatters)" -- --no-upgrade --upgrade-package=isort
+```

noxfile.py

@@ -0,0 +1,87 @@
+from pathlib import Path
+
+import nox
+
+LINT_FILES = ["forge-webhook-parser.py"]
+
+requirements_directory = Path("requirements")
+
+requirements_files = [
+    requirements_input_file_path.stem
+    for requirements_input_file_path in requirements_directory.glob("*.in")
+]
+
+
+@nox.session(name="pip-compile", python=["3.12"])
+@nox.parametrize(["req"], arg_values_list=requirements_files, ids=requirements_files)
+def pip_compile(session: nox.Session, req: str):
+    """Generate lock files from input files or upgrade packages in lock files."""
+    # fmt: off
+    session.install(
+      "-r", str(requirements_directory / "pip-tools.in"),
+      "-c", str(requirements_directory / "pip-tools.txt"),
+    )
+    # fmt: on
+
+    # Use --upgrade by default unless a user passes -P.
+    upgrade_related_cli_flags = ("-P", "--upgrade-package", "--no-upgrade")
+    has_upgrade_related_cli_flags = any(
+        arg.startswith(upgrade_related_cli_flags) for arg in session.posargs
+    )
+    injected_extra_cli_args = () if has_upgrade_related_cli_flags else ("--upgrade",)
+
+    session.run(
+        "pip-compile",
+        "--output-file",
+        str(requirements_directory / f"{req}.txt"),
+        *session.posargs,
+        *injected_extra_cli_args,
+        str(requirements_directory / f"{req}.in"),
+    )
+
+
+def install(session: nox.Session, req: str):
+    session.install(
+        "-r",
+        str(requirements_directory / f"{req}.in"),
+        "-c",
+        str(requirements_directory / f"{req}.txt"),
+    )
+
+
+@nox.session
+def static(session: nox.Session):
+    """
+    Run static checkers
+    """
+    install(session, req="static")
+    session.run("ruff", "check", *session.posargs, *LINT_FILES)
+
+
+@nox.session
+def formatters(session: nox.Session):
+    """
+    Reformat code
+    """
+    install(session, req="formatters")
+    session.run("isort", *session.posargs, *LINT_FILES)
+    session.run("black", *session.posargs, *LINT_FILES)
+
+
+@nox.session
+def formatters_check(session: nox.Session):
+    """
+    Check code formatting without making changes
+    """
+    install(session, req="formatters")
+    session.run("isort", "--check", *session.posargs, *LINT_FILES)
+    session.run("black", "--check", *session.posargs, *LINT_FILES)
+
+
+@nox.session
+def typing(session: nox.Session):
+    """
+    Run static type checker
+    """
+    install(session, req="typing")
+    session.run("mypy", *session.posargs, *LINT_FILES)

requirements/formatters.in

@@ -0,0 +1,2 @@
+black
+isort

requirements/formatters.txt

@@ -0,0 +1,20 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile --allow-unsafe --output-file=requirements/formatters.txt --strip-extras requirements/formatters.in
+#
+black==24.8.0
+    # via -r requirements/formatters.in
+click==8.1.7
+    # via black
+isort==5.13.2
+    # via -r requirements/formatters.in
+mypy-extensions==1.0.0
+    # via black
+packaging==24.1
+    # via black
+pathspec==0.12.1
+    # via black
+platformdirs==4.3.6
+    # via black

requirements/pip-tools.in

@@ -0,0 +1 @@
+pip-tools >= 7 # .pip-tools.toml was introduced in v6.14