pkpdutils 1.0.0__tar.gz

pkpdutils-1.0.0/.bumpversion.toml

@@ -0,0 +1,28 @@
+[tool.bumpversion]
+current_version = "1.0.0"
+commit = true
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(\\.dev(?P<dev>\\d+))?"
+serialize = ["{major}.{minor}.{patch}.dev{dev}", "{major}.{minor}.{patch}"]
+search = "{current_version}"
+replace = "{new_version}"
+regex = false
+ignore_missing_version = false
+# no tag: the bump is merged into develop through a pull request, which
+# rewrites the commit, so the tag is created on develop afterwards
+tag = false
+sign_tags = false
+tag_name = "{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+allow_dirty = false
+message = "Bump version: {current_version} → {new_version}"
+commit_args = ""
+
+[tool.bumpversion.parts.dev]
+optional_value = "final"
+values = ["0", "final"]
+
+[[tool.bumpversion.files]]
+filename = "./src/pkpdutils/__init__.py"
+
+[[tool.bumpversion.files]]
+filename = "./CITATION.cff"

pkpdutils-1.0.0/.editorconfig

@@ -0,0 +1,20 @@
+# Editor Configuration (http://editorconfig.org)
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 4
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+max_line_length = 88
+
+[*.{json,yml}]
+indent_size = 2
+
+[*.{md,rst}]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

pkpdutils-1.0.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @matthiaskoenig

pkpdutils-1.0.0/.github/ISSUE_TEMPLATE/01-bug-report.md

@@ -0,0 +1,49 @@
+---
+name: Bug report
+about: Report a bug to help improve this project
+---
+
+<!--
+
+Before you create a new problem report, please look through the list of existing open
+ and closed issues to see if there are similar ones.
+
+https://github.com/matthiaskoenig/pkdb_analysis/issues
+
+-->
+
+#### Problem description
+
+Please explain:
+* **what** you tried to achieve,
+* **how** you went about it (referring to the code sample), and
+* **why** the current behaviour is a problem and what output
+  you expected instead.
+
+#### Code Sample
+
+Create a [minimal, complete, verifiable example](https://stackoverflow.com/help/mcve).
+
+<!-- Paste your code between the ``` tickmarks below or link to a gist. -->
+```python
+```
+
+<!-- If there was a crash, please include the traceback between the ``` tickmarks below. -->
+```
+```
+
+### Context
+
+<!-- Run the following code and paste the output between the ``` tickmarks below
+inside the details block.
+
+python -c "import pkdb_analysis;pkdb_analysis.show_versions()"
+
+-->
+
+<details>
+
+```
+```
+
+</details>

pkpdutils-1.0.0/.github/ISSUE_TEMPLATE/02-question.md

@@ -0,0 +1,16 @@
+---
+name: Question
+about: Ask a question
+---
+
+### Checklist
+
+<!-- To help keep this issue tracker clean and focused, please make sure that you have
+ tried *all* of the following resources before submitting your question. -->
+
+- [ ] I searched the [documentation](https://pkdb-analysis.readthedocs.io).
+- [ ] I looked through [similar issues on GitHub](https://github.com/matthiaskoenig/pkdb_analysis/issues).
+
+### Question
+
+<!-- Please ask your question here. -->

pkpdutils-1.0.0/.github/ISSUE_TEMPLATE/03-feature-request.md

@@ -0,0 +1,36 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+---
+
+### Checklist
+
+<!-- Please make sure you check all these items before submitting your feature request. -->
+
+- [ ] There are [no similar issues or pull requests](https://github.com/matthiaskoenig/pkdb_analysis/issues) for this yet.
+
+### Is your feature related to a problem? Please describe it.
+
+<!--
+A clear and concise description of what you are trying to achieve.
+"I want to be able to [...] but I can't because [...]".
+-->
+
+## Describe the solution you would like.
+
+<!--
+A clear and concise description of what you would want to happen.
+For API changes, try to provide a code snippet of what you would like the new API to
+look like.
+-->
+
+## Describe alternatives you considered
+
+<!--
+Please describe any alternative solutions or features you've considered to solve
+your problem and why they wouldn't solve it.
+-->
+
+## Additional context
+
+<!-- Provide any additional context, screenshots, tracebacks, etc. about the feature here. -->

pkpdutils-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+# Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
+blank_issues_enabled: true

pkpdutils-1.0.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+# Keep the GitHub Actions used in the workflows up to date.
+# See https://docs.github.com/code-security/dependabot/dependabot-version-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    # a single pull request for all action updates instead of one per action
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"

pkpdutils-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Summary
+
+<!-- what does this change and why -->
+
+## Checklist
+
+- [ ] the pull request targets `develop`
+- [ ] tests were added or updated for the change
+- [ ] `tox run-parallel` passes locally (tests and `ty`)
+- [ ] `ruff check` and `ruff format` are clean, e.g., via `pre-commit run --all-files`
+- [ ] public functions and classes have type annotations and a docstring
+- [ ] user visible changes are in `release-notes/` and, if needed, in `docs/`

pkpdutils-1.0.0/.github/rulesets/apply.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# Apply the repository policies of pkpdutils: the merge settings of the
+# repository and the rulesets in this directory. The script is idempotent, i.e.,
+# a ruleset which already exists is updated instead of added a second time, so
+# it can be run again after every change of the json files.
+#
+# The file name of a ruleset has to match the "name" in the json. A ruleset which
+# is removed from this directory stays on the repository, delete it with
+# `gh api -X DELETE repos/<owner>/<repo>/rulesets/<id>`.
+#
+# Requires the github cli (https://cli.github.com) authenticated as a user with
+# admin permission on the repository:
+#
+#   gh auth login
+#   .github/rulesets/apply.sh [owner/repo]
+#
+set -euo pipefail
+
+REPO="${1:-matthiaskoenig/pkpdutils}"
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "repository settings of ${REPO}"
+gh api -X PATCH "repos/${REPO}" \
+  -F allow_auto_merge=true \
+  -F delete_branch_on_merge=true \
+  -F allow_update_branch=true \
+  -F allow_squash_merge=true \
+  -F allow_rebase_merge=true \
+  -F allow_merge_commit=false \
+  --silent
+
+for path in "${DIR}"/*.json; do
+  name="$(basename "${path}" .json)"
+  id="$(gh api "repos/${REPO}/rulesets" --jq "map(select(.name == \"${name}\")) | .[0].id // empty")"
+  if [[ -n "${id}" ]]; then
+    gh api -X PUT "repos/${REPO}/rulesets/${id}" --input "${path}" --silent
+    echo "ruleset ${name} updated (${id})"
+  else
+    id="$(gh api -X POST "repos/${REPO}/rulesets" --input "${path}" --jq .id)"
+    echo "ruleset ${name} created (${id})"
+  fi
+done

pkpdutils-1.0.0/.github/rulesets/develop.json

@@ -0,0 +1,61 @@
+{
+  "name": "develop",
+  "target": "branch",
+  "enforcement": "active",
+  "bypass_actors": [],
+  "conditions": {
+    "ref_name": {
+      "include": [
+        "refs/heads/develop"
+      ],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    },
+    {
+      "type": "required_linear_history"
+    },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": true,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": true,
+        "allowed_merge_methods": [
+          "squash",
+          "rebase"
+        ],
+        "require_extra_approval_for_unattributed_changes": false
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "do_not_enforce_on_create": false,
+        "required_status_checks": [
+          {
+            "context": "tests"
+          },
+          {
+            "context": "ruff"
+          },
+          {
+            "context": "ty"
+          },
+          {
+            "context": "docs"
+          }
+        ]
+      }
+    }
+  ]
+}

pkpdutils-1.0.0/.github/rulesets/main.json

@@ -0,0 +1,22 @@
+{
+  "name": "main",
+  "target": "branch",
+  "enforcement": "active",
+  "bypass_actors": [],
+  "conditions": {
+    "ref_name": {
+      "include": [
+        "refs/heads/main"
+      ],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    }
+  ]
+}

pkpdutils-1.0.0/.github/rulesets/tags.json

@@ -0,0 +1,16 @@
+{
+  "name": "tags",
+  "target": "tag",
+  "enforcement": "active",
+  "bypass_actors": [],
+  "conditions": {
+    "ref_name": {
+      "include": ["~ALL"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {"type": "deletion"},
+    {"type": "non_fast_forward"}
+  ]
+}

pkpdutils-1.0.0/.github/workflows/ci-cd.yml

@@ -0,0 +1,117 @@
+name: CI-CD
+
+on:
+  push:
+    # feature branches are tested through their pull request, tags release
+    branches: [develop, main]
+    tags: ['*']
+  pull_request:
+    branches: [develop, main]
+  workflow_dispatch:
+
+# least privilege by default, the release job raises what it needs
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  # superseded branch runs are cancelled, release runs are never cancelled
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.13", "3.14"]
+        # linux covers the full range, windows and macos only the newest version
+        exclude:
+          - os: windows-latest
+            python-version: "3.13"
+          - os: macos-latest
+            python-version: "3.13"
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+    - name: Install uv and set the python version
+      # astral-sh/setup-uv publishes no floating major tag beyond v7
+      uses: astral-sh/setup-uv@v10.0.1
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+    - name: Test with tox
+      run:
+        uvx --with tox-uv tox -e py${{ matrix.python-version }}
+
+  tests:
+    # the one check the branch protection requires; the names of the matrix
+    # jobs change with the matrix, this name does not, see .github/rulesets/
+    name: tests
+    needs: test
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+    - name: Check the result of the test matrix
+      env:
+        RESULT: ${{ needs.test.result }}
+      run: |
+        echo "test matrix: $RESULT"
+        test "$RESULT" = "success"
+
+  release:
+    needs: tests
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pkpdutils
+    permissions:
+      id-token: write  # trusted publishing to PyPI
+      contents: write  # create the GitHub release
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+    - name: Install uv
+      uses: astral-sh/setup-uv@v10.0.1
+      with:
+        python-version: "3.14"
+        enable-cache: true
+    - name: Build package
+      run: uvx hatch build
+    - name: Check the package
+      run: uvx twine check dist/*
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        packages-dir: dist
+    - name: Create GitHub release
+      uses: softprops/action-gh-release@v3
+      with:
+        body_path: "release-notes/${{ github.ref_name }}.md"
+        draft: false
+        prerelease: false
+
+  sync-main:
+    # main tracks the latest published release, see docs/development.md
+    needs: release
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write  # fast-forward main to the released commit
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        # a shallow clone cannot be pushed to another branch
+        fetch-depth: 0
+    - name: Fast-forward main to the release
+      # no --force: the push fails loudly if it would not be a fast-forward
+      run: git push origin HEAD:main

pkpdutils-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+name: documentation
+
+on:
+  push:
+    # feature branches are built through their pull request
+    branches: [develop, main]
+  pull_request:
+    branches: [develop, main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  # one run per branch or pull request, so that a deployment of `develop` is
+  # never overtaken by the next one, which would leave the site half published
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  docs:
+    # the name the branch protection requires, see .github/rulesets/
+    name: docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Build the documentation
+        # the API reference is rendered from the docstrings by mkdocstrings,
+        # so the package has to be importable
+        run: uv run zensical build --clean --strict
+      - name: Generate the agent facing files
+        # llms.txt, llms-full.txt and the markdown of every page
+        run: uv run python scripts/llms_txt.py
+      - name: Upload the site
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    needs: docs
+    # only the default branch publishes to https://matthiaskoenig.github.io/pkpdutils
+    if: github.ref == 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write     # deploy to GitHub Pages
+      id-token: write  # verify the deployment originates from this workflow
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

pkpdutils-1.0.0/.github/workflows/ruff.yml

@@ -0,0 +1,37 @@
+name: ruff
+
+on:
+  push:
+    # feature branches are checked through their pull request
+    branches: [develop, main]
+  pull_request:
+    branches: [develop, main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  ruff:
+    # required by the branch protection, see .github/rulesets/develop.json
+    name: ruff
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      # the ruff version is read from the dev dependencies in pyproject.toml
+      - name: Lint
+        # astral-sh/ruff-action publishes no floating major tag beyond v3
+        uses: astral-sh/ruff-action@v4.1.0
+        with:
+          args: check --output-format=github
+      - name: Format
+        uses: astral-sh/ruff-action@v4.1.0
+        with:
+          args: format --check --diff

pkpdutils-1.0.0/.github/workflows/ty.yml

@@ -0,0 +1,38 @@
+name: ty
+
+on:
+  push:
+    # feature branches are checked through their pull request
+    branches: [develop, main]
+  pull_request:
+    branches: [develop, main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  ty:
+    # required by the branch protection, see .github/rulesets/develop.json
+    name: ty
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - name: Type check with tox
+        env:
+          # render diagnostics as GitHub Actions workflow annotations
+          TY_OUTPUT_FORMAT: github
+        run:
+          uvx --with tox-uv tox -e ty

pkpdutils-1.0.0/.gitignore

@@ -0,0 +1,34 @@
+# python
+__pycache__/
+*.pyc
+
+# packaging artifacts (hatchling builds into dist/)
+dist/
+*.egg-info/
+
+# environments, tool caches
+.venv/
+.tox/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+# build cache of zensical
+.cache/
+
+# rendered documentation, built by the `documentation` workflow
+site/
+
+# the lock file is not committed, pkpdutils is a library and pins nothing
+uv.lock
+
+# output of the examples, they write into the working directory
+examples/**/results/
+/results/
+
+# editors, operating system
+.idea/
+.vscode/
+*~
+.DS_Store
+.ipynb_checkpoints/