Initial commit

Author: edircoli

.github/workflows/README.md

@@ -0,0 +1,11 @@
+# Workflows
+
+## cicd
+
+Basic continuous integration and deployment (CI/CD) workflow for Python packages.
+
+- checks formatting (black, isort)
+- checks linting (ruff)
+- run unit tests (pytest)
+- optional: add c extensions to a package
+- if all checks pass, build and deploy to PyPI if `tag` triggered the workflow

.github/workflows/cicd.yml

@@ -0,0 +1,133 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python application
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  schedule:
+    - cron: "0 2 * * 3"
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: psf/black@stable
+      - uses: isort/isort-action@v1
+  lint:
+    name: Lint with ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install ruff
+        run: |
+          pip install ruff
+      - name: Lint with ruff
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          ruff check src
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip" # caching pip dependencies
+          cache-dependency-path: "**/pyproject.toml"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest
+          pip install -e .
+      - name: Run tests
+        run: python -m pytest tests
+
+  build_source_dist:
+    name: Build source distribution
+    if: startsWith(github.ref, 'refs/heads/main') || startsWith(github.ref, 'refs/tags')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install build
+        run: python -m pip install build
+
+      - name: Run build
+        run: python -m build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          path: ./dist/*.tar.gz
+  # Needed in case of building packages with external binaries (e.g. Cython, RUst-extensions, etc.)
+  # build_wheels:
+  #   name: Build wheels on ${{ matrix.os }}
+  #   if: startsWith(github.ref, 'refs/heads/main') || startsWith(github.ref, 'refs/tags')
+  #   runs-on: ${{ matrix.os }}
+  #   strategy:
+  #       matrix:
+  #         os: [ubuntu-20.04, windows-2019, macOS-10.15]
+
+  #   steps:
+  #       - uses: actions/checkout@v4
+
+  #       - uses: actions/setup-python@v5
+  #         with:
+  #           python-version: "3.10"
+
+  #       - name: Install cibuildwheel
+  #         run: python -m pip install cibuildwheel==2.3.1
+
+  #       - name: Build wheels
+  #         run: python -m cibuildwheel --output-dir wheels
+
+  #       - uses: actions/upload-artifact@v4
+  #         with:
+  #           path: ./wheels/*.whl
+
+  publish:
+    name: Publish package
+    if: startsWith(github.ref, 'refs/tags')
+    permissions:
+      id-token: write
+    needs:
+      - format
+      - lint
+      - test
+      - build_source_dist
+      # - build_wheels
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: artifact
+          path: ./dist
+      # register PyPI integration:
+      # https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # remove repository key to set the default to pypi (not test.pypi.org)
+          repository-url: https://test.pypi.org/legacy/

.gitignore

@@ -0,0 +1,56 @@
+# find more examples here:
+# https://github.com/github/gitignore/blob/main/Python.gitignore
+# Binaries (object files) produced by a compiler
+*.so
+*.o
+
+# Python/Jupyter uses these cache directories
+__pycache__
+.ipynb_checkpoints
+
+# Produced when measuring code coverage
+.coverage
+
+# These files are produced during the Python build process
+build/
+.eggs
+dist/
+**.egg-info
+
+# Sphinx documenter creates these
+_build
+_static
+_templates
+/docs/reference
+/docs/jupyter_execute
+
+# MacOS automatically creates these files
+.DS_Store
+
+# VSCode may create a config file with this name
+**.vscode
+
+# Ruff stuff:
+.ruff_cache/
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/

.readthedocs.yaml

@@ -0,0 +1,38 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+  # apt_packages:
+  #  - some_package
+
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CITATION.cff

@@ -0,0 +1,12 @@
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Last"
+  given-names: "First"
+  orcid: "https://orcid.org/0000-0000-0000-0000"
+title: "Python Package Template repository"
+version: 0.0.1
+doi: 10.5281/zenodo.1234
+date-released: 2025-07-23
+url: "https://github.com/biosustain/python_package"

Contributing.md

@@ -0,0 +1,36 @@
+# Contributing code
+
+Install the code with development dependencies:
+
+```bash
+pip install -e '.[dev]'
+```
+
+## Format code and sort imports
+
+```bash
+black .
+isort .
+```
+
+## lint code
+
+```bash
+ruff check .
+```
+
+## Run tests
+
+```bash
+pytest
+```
+
+## Sync notebooks with jupytext
+
+For easier diffs, you can use jupytext to sync notebooks in the `docs/tutorial` directory with the percent format.
+
+```bash
+jupytext --sync docs/tutorial/*.ipynb
+```
+
+This is configured in the [`.jupytext`](docs/tutorial/.jupytext) file in that directory.