Initial development

.github/ISSUE_TEMPLATE/issue.yml

@@ -0,0 +1,47 @@
+---
+# GitHub Issue template for bug reports
+name: Open a GitHub issue
+description: >
+  Please use this form to send along new ideas for content or
+  changes that might be helpful!
+
+body:
+  - type: checkboxes
+    attributes:
+      label: Is this a duplicate of an existing idea for this project?
+      description: >
+        Please make sure to search the existing issues first
+        to see whether the same issue was reported already.
+        If you find an existing issue, please don't hesitate to comment
+        on it or add a reaction to existing content!
+      options:
+        - label: >
+            I found no existing issue covering this topic.
+          required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What is your idea?
+      description: >
+        Please provide a specific description of what you'd like to see
+        including the context and what the result might look like.
+      placeholder: >
+        For example: "When x happens I see y.
+        The following might be a good way to address this ..."
+    validations:
+      required: true
+
+  - type: checkboxes
+    attributes:
+      label: Would you like to work on a solution for this?
+      description: >
+        This is a community-driven project and we
+        love new contributors (including through opening or adding to issues)!
+        This is an optional check to help us understand your interest to be
+        involved (especially if you already have a good understanding
+        of how to implement it).
+        We are happy to guide you in the contribution process and please
+        don't hesitate to reach out for help along the way.
+      options:
+        - label: Yes I am willing to submit a PR for this!

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+<!-- _modified from [EmbeddedArtistry](https://embeddedartistry.com/blog/2017/08/04/a-github-pull-request-template-for-your-projects/)_
+_referenced with modifications from [pycytominer](https://github.com/cytomining/pycytominer/blob/master/.github/PULL_REQUEST_TEMPLATE.md)_ -->
+
+# Description
+
+<!--
+Thank you so much for your contribution to this project!
+
+Please _succinctly_ summarize your proposed change.
+Namely, consider addressing the following questions:
+
+- What motivated you to open this pull request?
+- Were there any special adjustments you had to make to complete the work?
+- Are there any issues which are related to this pull request (you may use a `#<digit>` to reference GitHub issues as links within this description)?
+
+Also, if you haven't already, please use `pre-commit run --all-files` to help check your files using this project's pre-commit configuration.
+Pre-commit checks will automatically run as part of opening this pull request and we seek to ensure all checks pass before merging changes.
+-->
+
+## What kind of change(s) are included?
+
+- [ ] Documentation (changes docs or other related content)
+- [ ] Bug fix (fixes an issue).
+- [ ] Enhancement (adds functionality).
+- [ ] Breaking change (these changes would cause existing functionality to not work as expected).
+
+# Checklist
+
+Please ensure that all boxes are checked before indicating that this pull request is ready for review.
+
+- [ ] I have read and followed the [CONTRIBUTING.md](CONTRIBUTING.md) guidelines.
+- [ ] I have searched for existing content to ensure this is not a duplicate.
+- [ ] I have performed a self-review of these additions (including spelling, grammar, and related).
+- [ ] These changes pass all pre-commit checks.
+- [ ] I have added comments to my code to help provide understanding
+- [ ] I have added a test which covers the code changes found within this PR
+- [ ] I have deleted all non-relevant text in this pull request template.

.github/dependabot.yml

@@ -0,0 +1,28 @@
+---
+# GitHub Dependabot configuration
+# Note: there is no interaction between this
+# configuration and dependabot security updates.
+# See here for more information:
+# https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-dependabot-security-updates
+
+version: 2
+updates:
+  # GitHub Actions checks
+  # See here for more information:
+  # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "weekly"
+
+  # Perform checks and updates for python uv environment.
+  # This depends on changes to dependabot via:
+  # https://github.com/dependabot/dependabot-core/pull/10040
+  # See here for more information:
+  # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#pip-and-pip-compile
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      # Check for updates to uv environment files every week
+      interval: "weekly"

.github/release-drafter.yml

@@ -0,0 +1,21 @@
+---
+# template configuration for release-drafter
+# see: https://github.com/release-drafter/release-drafter
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+version-resolver:
+  major:
+    labels:
+      - 'release-major'
+  minor:
+    labels:
+      - 'release-minor'
+  patch:
+    labels:
+      - 'release-patch'
+  default: patch
+change-template: '- $TITLE (@$AUTHOR via #$NUMBER)'
+template: |
+  ## Changes
+
+  $CHANGES

.github/workflows/draft-release.yml

@@ -0,0 +1,26 @@
+---
+# workflow for drafting releases on GitHub
+# see: https://github.com/release-drafter/release-drafter
+name: release drafter
+
+'on':
+  push:
+    branches:
+      - main
+
+jobs:
+  draft_release:
+    permissions:
+      # write permission is required to create a github release
+      contents: write
+      # write permission is required for autolabeler
+      # otherwise, read permission is required at least
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      # release-drafter/release-drafter v6.1.0
+      # yamllint disable rule:line-length
+      - uses: release-drafter/release-drafter@b1476f6e6eb133afa41ed8589daba6dc69b4d3f5
+      # yamllint enable rule:line-length
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-docs.yml

@@ -0,0 +1,44 @@
+---
+# used for publishing documentation on push to main or published release
+name: publish docs
+
+'on':
+  push:
+    branches:
+      - main
+  release:
+    types:
+      - published
+
+jobs:
+  build:
+    # only build and deploy docs if the actor is not dependabot
+    if: ${{ github.actor != 'dependabot[bot]' }}
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+      - name: Build documentation
+        run: |
+          mkdir pages
+          touch pages/.nojekyll
+          uv run --group docs --frozen sphinx-build \
+            -b html \
+            docs/src \
+            docs/_build/html
+          find docs/_build/html -type d -name '.doctrees' -exec rm -rf {} +
+          cp -r docs/_build/html/* pages/
+      - name: Deploy documentation
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: pages
+          folder: pages

.github/workflows/publish-pypi.yml

@@ -0,0 +1,35 @@
+---
+# used for publishing packages to pypi on release
+name: publish pypi release
+
+'on':
+  release:
+    types:
+      - published
+
+jobs:
+  publish_pypi:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Fetch tags
+        run: git fetch --all --tags
+      - name: Python setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+      - name: Build distribution content
+        run: uv build
+      - name: Check built distributions
+        run: uvx twine check dist/*
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/run-tests.yml

@@ -0,0 +1,71 @@
+---
+name: tests
+
+'on': [push, pull_request]
+
+jobs:
+  pre_commit_checks:
+    runs-on: ubuntu-24.04
+    steps:
+      # actions/checkout v4.3.1
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - name: Python setup
+        # actions/setup-python v5.6.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        # astral-sh/setup-uv v6.7.0
+        uses: astral-sh/setup-uv@b75a909f75acd358c2196fb9a5f1299a9a8868a4
+      - name: Install pre-commit
+        run: uv tool install pre-commit
+      - name: Run pre-commit
+        run: |
+          uv run --with pre-commit \
+            pre-commit run --all-files
+
+  test_matrix:
+    strategy:
+      matrix:
+        python_version: ["3.11", "3.12", "3.13"]
+        os: [ubuntu-24.04, macos-14]
+    runs-on: ${{ matrix.os }}
+    steps:
+      # actions/checkout v4.3.1
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - name: Python setup
+        # actions/setup-python v5.6.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: ${{ matrix.python_version }}
+      - name: Install uv
+        # astral-sh/setup-uv v6.7.0
+        uses: astral-sh/setup-uv@b75a909f75acd358c2196fb9a5f1299a9a8868a4
+      - name: Run pytest
+        run: uv run --frozen pytest
+
+  docs_and_integrations:
+    runs-on: ubuntu-24.04
+    steps:
+      # actions/checkout v4.3.1
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - name: Python setup
+        # actions/setup-python v5.6.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        # astral-sh/setup-uv v6.7.0
+        uses: astral-sh/setup-uv@b75a909f75acd358c2196fb9a5f1299a9a8868a4
+      - name: Run Ruff
+        run: uv run --group dev --frozen ruff check
+      - name: Build docs
+        run: |
+          uv run --group docs --frozen sphinx-build \
+            -b html \
+            docs/src \
+            docs/_build/html
+      - name: Run optional DuckDB integration tests
+        run: |
+          uv run --group dev --group duckdb --frozen \
+            pytest tests/test_duckdb.py

.gitignore

@@ -182,9 +182,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 

.pre-commit-config.yaml

@@ -0,0 +1,58 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: detect-private-key
+-   repo: https://github.com/tox-dev/pyproject-fmt
+    rev: "v2.20.0"
+    hooks:
+    -   id: pyproject-fmt
+-   repo: https://github.com/citation-file-format/cffconvert
+    rev: 5295f87c0e261da61a7b919fc754e3a77edd98a7
+    hooks:
+    -   id: validate-cff
+-   repo: https://github.com/codespell-project/codespell
+    rev: v2.4.2
+    hooks:
+    -   id: codespell
+        exclude: |
+          (?x)^(
+              .*\.lock |
+              .*\.csv |
+              .*\.cff |
+              .*\.ipynb
+          )$
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.21
+    hooks:
+    -   id: mdformat
+        additional_dependencies:
+        -   mdformat-gfm
+-   repo: https://github.com/adrienverge/yamllint
+    rev: v1.38.0
+    hooks:
+    -   id: yamllint
+        exclude: \.pre-commit-config\.yaml
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.15.8"
+    hooks:
+    -   id: ruff-format
+    -   id: ruff-check
+-   repo: https://github.com/rhysd/actionlint
+    rev: v1.7.11
+    hooks:
+    -   id: actionlint
+-   repo: https://gitlab.com/vojko.pribudic.foss/pre-commit-update
+    rev: v0.6.0
+    hooks:
+    -   id: pre-commit-update
+        args: ["--keep", "mdformat", "--keep", "pre-commit-update", "--keep", "cffconvert"]
+-   repo: https://github.com/jendrikseipp/vulture
+    rev: 'v2.16'
+    hooks:
+    -   id: vulture

.python-version

@@ -0,0 +1 @@
+3.11