feat: first commit

.github/CODEOWNERS

@@ -0,0 +1 @@
+*       @amv213

.github/workflows/core.yaml

@@ -0,0 +1,133 @@
+name: core
+
+env:
+  FORCE_COLOR: "1"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+jobs:
+
+  run-pre-commit:
+
+    name: run-pre-commit
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install nox uv
+    - uses: pre-commit/action@v3.0.1
+
+  run-formatting-check:
+
+    name: run-formatting-check
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install nox uv
+    - name: Run nox
+      run: |
+        nox -s formatting_check
+
+  run-linting-check:
+
+    name: run-linting-check
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install nox uv
+    - name: Run nox
+      run: |
+        nox -s linting_check -- --output-format=github
+
+  run-type-checking:
+
+    name: run-type-checking
+    runs-on: ubuntu-latest
+
+    needs:
+      - run-pre-commit
+      - run-formatting-check
+      - run-linting-check
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install nox uv
+    - name: Run nox
+      run: |
+        nox -s typing_check
+
+  run-tests-pinned:
+
+    name: run-tests-pinned
+    runs-on: ubuntu-latest
+
+    needs:
+      - run-type-checking
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install nox uv
+    - name: Run nox
+      run: |
+        nox -s tests_run
+
+
+  packaging:
+
+    name: packaging
+    uses: ./.github/workflows/deploy-package.yaml
+
+    # only start build if core pipeline was successful
+    needs: run-tests-pinned

.github/workflows/deploy-package.yaml

@@ -0,0 +1,110 @@
+name: packaging
+
+env:
+  FORCE_COLOR: "1"
+
+on:
+
+  workflow_call:
+  workflow_dispatch:
+  push:
+    tags:
+      - '*.*.*'
+
+jobs:
+
+  build-distribution:
+
+    # only start build if core pipeline was successful
+    name: build-distribution
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install nox uv
+    - name: Run nox
+      run: |
+        nox -s dist_build
+    # only persist the built artefact if we are doing an actual release
+    - if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+      name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+
+    # only publish to PyPI on tag pushes
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    name: publish-to-pypi
+    runs-on: ubuntu-latest
+
+    needs:
+    - build-distribution
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/voltorb
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  sign-and-create-github-release:
+
+    name: sign-and-create-github-release
+    runs-on: ubuntu-latest
+
+    needs:
+      - publish-to-pypi
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Sign the dists with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v2.1.1
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create
+          '${{ github.ref_name }}'
+          --repo '${{ github.repository }}'
+          --notes ""
+      - name: Upload artifact signatures to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        # Upload to GitHub Release using the `gh` CLI.
+        # `dist/` contains the built packages, and the
+        # sigstore-produced signatures and certificates.
+        run: >-
+          gh release upload
+          '${{ github.ref_name }}' dist/**
+          --repo '${{ github.repository }}'

.gitignore

@@ -0,0 +1,45 @@
+# local virtualenv
+.venv
+
+# Log files
+*.log
+
+# Generated by MacOS
+.DS_Store
+
+# Bytecompiles, caches
+*.py[cod]
+__pycache__
+
+# Package builds / installs
+build
+dist
+.eggs
+*.egg-info/
+*.egg
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Local Pycharm project configuration settings
+.idea
+
+# VSCode
+.vscode
+
+# local secret .emv file
+.env
+
+# cache directory configured for various python tools
+.cache
+
+# Test and coverage artefacts
+artefacts
+
+# Docs
+docs/build
+!docs/build/.jupyter_cache
+docs/source/pages/reference/api
+
+# setuptools_scm version file
+src/**/*version.py

.pre-commit-config.yaml

@@ -0,0 +1,84 @@
+# Pre-commit configuration file
+#
+# If it's your first time run:
+#   $ python -m pre_commit install --hook-type pre-commit --hook-type pre-push
+#
+# To run these hooks locally:
+#   $ python -m pre_commit run --all-files
+#
+# To update these hooks:
+#   $ python -m pre_commit autoupdate
+#
+# References:
+#   https://pre-commit.com/index.html
+
+repos:
+
+  # baseline consistency checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-xml
+      - id: check-yaml
+        args: [ --allow-multiple-documents ]
+      - id: detect-aws-credentials
+        args: [ --allow-missing-credentials ]
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: pretty-format-json
+        args: [ --no-sort-keys, --autofix ]
+      - id: trailing-whitespace
+
+  # validate pyproject.toml file
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.16
+    hooks:
+      - id: validate-pyproject
+
+  # some useful and quality-of-life checks for shell scripts
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+
+  # fix spelling
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.6
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli
+
+  # ensure commit messages format consistency
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v3.24.0
+    hooks:
+      - id: commitizen
+
+  # code quality checks
+  - repo: local
+    hooks:
+      - id: linting
+        name: linting
+        entry: python -m nox -s linting_check
+        pass_filenames: false
+        language: system
+        types: [ python ]
+        require_serial: true
+        stages: [ push ]
+      - id: formatting
+        name: formatting
+        entry: python -m nox -s formatting_check
+        files: 'src|tests|noxfile.py'
+        pass_filenames: false
+        language: system
+        types: [ python ]
+        require_serial: true
+        stages: [ push ]

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 amv213
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.