pydantic-explain 0.0.1a0__tar.gz

pydantic_explain-0.0.1a0/.github/CODEOWNERS

@@ -0,0 +1 @@
+@MatthewMckee4

pydantic_explain-0.0.1a0/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,117 @@
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behaviour that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behaviour include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behaviour and will take appropriate and fair corrective action in
+response to any behaviour that they deem inappropriate,
+threatening, offensive, or harmful.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will
+communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be
+reported to the community leaders responsible for enforcement at
+<matthewmckee04@yahoo.co.uk>.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behaviour deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behaviour was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behaviour. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behaviour.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behaviour, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://contributor-covenant.org/), version
+[1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct/code_of_conduct.md) and
+[2.0](https://www.contributor-covenant.org/version/2/0/code_of_conduct/code_of_conduct.md),
+and was generated by
+[contributing-gen](https://github.com/bttger/contributing-gen).

pydantic_explain-0.0.1a0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [matthewmckee4]

pydantic_explain-0.0.1a0/.github/ISSUE_TEMPLATE/1_bug_report.yaml

@@ -0,0 +1,28 @@
+name: Bug report
+description: Report an error or unexpected behavior
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to report an issue!
+
+        **Before reporting, please make sure to search through
+        [existing issues](https://github.com/MatthewMckee4/pydantic-explain/issues?q=is:issue+is:open+label:bug)
+        (including
+        [closed](https://github.com/MatthewMckee4/pydantic-explain/issues?q=is:issue%20state:closed%20label:bug)).**
+
+  - type: textarea
+    attributes:
+      label: Summary
+      description: |
+        A clear and concise description of the bug, including a minimal reproducible example.
+    validations:
+      required: true
+
+  - type: input
+    attributes:
+      label: Version
+      description: What version of pydantic-explain are you using?
+      placeholder: e.g., 0.0.1
+    validations:
+      required: false

pydantic_explain-0.0.1a0/.github/ISSUE_TEMPLATE/2_question.yaml

@@ -0,0 +1,18 @@
+name: Question
+description: Ask a question about pydantic-explain
+labels: ["question"]
+body:
+  - type: textarea
+    attributes:
+      label: Question
+      description: Describe your question in detail.
+    validations:
+      required: true
+
+  - type: input
+    attributes:
+      label: Version
+      description: What version of pydantic-explain are you using?
+      placeholder: e.g., 0.0.1
+    validations:
+      required: false

pydantic_explain-0.0.1a0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+## Summary
+
+<!-- What's the purpose of the change? What does it do, and why? -->
+
+## Test Plan
+
+<!-- How was it tested? -->

pydantic_explain-0.0.1a0/.github/actionlint.yaml

@@ -0,0 +1,2 @@
+# Configuration for the actionlint tool, which we run via prek
+# to verify the correctness of the syntax in our GitHub Actions workflows.

pydantic_explain-0.0.1a0/.github/workflows/ci.yml

@@ -0,0 +1,117 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  determine_changes:
+    name: "determine changes"
+
+    runs-on: ubuntu-latest
+
+    outputs:
+      code: ${{ steps.check_code.outputs.changed }}
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Determine merge base
+        id: merge_base
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref || 'main' }}
+        run: |
+          sha=$(git merge-base HEAD "origin/${BASE_REF}")
+          echo "sha=${sha}" >> "$GITHUB_OUTPUT"
+
+      - name: Check if there was any code related change
+        id: check_code
+        env:
+          MERGE_BASE: ${{ steps.merge_base.outputs.sha }}
+        run: |
+          if git diff --quiet "${MERGE_BASE}...HEAD" -- \
+            . \
+            ':!docs/' \
+            ':!.markdownlint.yaml' \
+            ':!.pre-commit-config.yaml' \
+            ':!CHANGELOG.md' \
+            ':!CODE_OF_CONDUCT.md' \
+            ':!CONTRIBUTING.md' \
+            ':!LICENSE' \
+            ':!README.md' \
+            ':!zensical.toml' \
+          ; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  pre-commit:
+    name: "pre commit"
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+
+      - uses: j178/prek-action@0bb87d7f00b0c99306c8bcb8b8beba1eb581c037 # v1.1.1
+
+  test:
+    name: "test (Python ${{ matrix.python-version }})"
+
+    runs-on: ubuntu-latest
+
+    needs: determine_changes
+    if: ${{ (needs.determine_changes.outputs.code == 'true' || github.ref == 'refs/heads/main') }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - run: uv sync --all-groups
+
+      - run: uv run karva test
+
+  build-docs:
+    name: "Build docs"
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Prepare docs
+        run: uv run --script scripts/prepare_docs.py
+
+      - name: Build docs
+        run: uv run --isolated --only-group docs zensical build

pydantic_explain-0.0.1a0/.github/workflows/release.yml

@@ -0,0 +1,167 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to release (e.g., 1.0.0)"
+        required: true
+        default: dry-run
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  generate-release:
+    name: Generate release metadata
+    runs-on: ubuntu-latest
+    outputs:
+      release-metadata: ${{ steps.seal-generate.outputs.metadata }}
+      tag: ${{ github.event.inputs.tag }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - name: Install seal
+        run: |
+          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/MatthewMckee4/seal/releases/download/0.0.1-alpha.5/seal-installer.sh | sh
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+
+      - name: Generate release metadata
+        id: seal-generate
+        run: |
+          METADATA=$(seal generate release)
+          {
+            echo "metadata<<EOF"
+            echo "$METADATA"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+          echo "Release metadata:"
+          echo "$METADATA"
+
+  build:
+    name: Build distribution
+    needs: generate-release
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+
+      - run: uv build
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  create-release:
+    name: Create GitHub release
+    runs-on: ubuntu-latest
+    needs: [generate-release, build]
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - name: Download dist
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
+      - name: Parse release metadata
+        id: parse-metadata
+        env:
+          METADATA: ${{ needs.generate-release.outputs.release-metadata }}
+        run: |
+          TITLE=$(echo "$METADATA" | jq -r '.title')
+          BODY=$(echo "$METADATA" | jq -r '.body')
+          PRERELEASE=$(echo "$METADATA" | jq -r '.prerelease')
+
+          {
+            echo "title=$TITLE"
+            echo "prerelease=$PRERELEASE"
+          } >> "$GITHUB_OUTPUT"
+
+          echo "$BODY" > "$RUNNER_TEMP/release-notes.txt"
+
+      - name: Create GitHub release
+        env:
+          TAG: ${{ needs.generate-release.outputs.tag }}
+          TITLE: ${{ steps.parse-metadata.outputs.title }}
+          PRERELEASE: ${{ steps.parse-metadata.outputs.prerelease }}
+        run: |
+          ARGS=(
+            "$TAG"
+            --title "$TITLE"
+            --notes-file "$RUNNER_TEMP/release-notes.txt"
+          )
+
+          if [ "$PRERELEASE" = "true" ]; then
+            ARGS+=(--prerelease)
+          fi
+
+          ARGS+=(dist/*)
+
+          gh release create "${ARGS[@]}"
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build, create-release]
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pydantic-explain/
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
+      - run: uv publish -v dist/*
+
+  publish-docs:
+    name: Publish documentation
+    runs-on: ubuntu-latest
+    needs: create-release
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+
+      - name: Prepare docs
+        run: uv run --script scripts/prepare_docs.py
+
+      - name: Build docs
+        run: uv run --isolated --only-group docs zensical build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site
+          publish_branch: gh-pages
+          keep_files: false
+          force_orphan: true

pydantic_explain-0.0.1a0/.github/zizmor.yml

@@ -0,0 +1,4 @@
+rules:
+  excessive-permissions:
+    ignore:
+      - release.yaml

pydantic_explain-0.0.1a0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Distribution
+*.tar.gz
+
+.karva_cache/
+
+# Documentation
+site/

pydantic_explain-0.0.1a0/.markdownlint.yaml

@@ -0,0 +1,32 @@
+# default to true for all rules
+default: true
+
+# MD007/unordered-list-indent
+MD007:
+  indent: 4
+
+# MD033/no-inline-html
+MD033: false
+
+# MD041/first-line-h1
+MD041: false
+
+# MD013/line-length
+MD013: false
+
+# MD014/commands-show-output
+MD014: false
+
+# MD024/no-duplicate-heading
+MD024:
+  siblings_only: true
+
+# MD046/code-block-style
+MD046: false
+
+# Link text should be descriptive
+# Disallows link text like *here* which is annoying.
+MD059: false
+
+# MD036/no-emphasis-as-heading
+MD036: false

pydantic_explain-0.0.1a0/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: mixed-line-ending
+
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.44.0
+    hooks:
+      - id: markdownlint
+        args: ["--config", ".markdownlint.yaml"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.1
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false

pydantic_explain-0.0.1a0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.0.1-alpha.0
+
+This is the first alpha release of pydantic-explain. See the documentation for more information.
+
+### Contributors
+
+- [@MatthewMckee4](https://github.com/MatthewMckee4)

pydantic_explain-0.0.1a0/CLAUDE.md

@@ -0,0 +1,13 @@
+- ALWAYS read CONTRIBUTING.md for guidelines on how to run tools
+- ALWAYS attempt to add a test case for changed behavior. Get your tests to pass — if you didn't run the tests, your code does not work.
+- ALWAYS run `uvx prek run -a` at the end of a task.
+- ALWAYS run `uv run karva test tests` at the end of a task.
+- FOLLOW existing code style. Check neighboring files for patterns.
+- AVOID writing significant amounts of new code. Look for existing methods and utilities first.
+- PREFER short imports over fully-qualified paths for readability.
+- AVOID redundant comments and section separators (e.g., `// --- Section ---`) in test files. Use comments to explain invariants and why something unusual was done, not to narrate code.
+- PREFER function comments over inline comments.
+- ALWAYS add type annotations, our package should be fully typed.
+- AVOID using `Any` type, prefer a static type.
+- ALWAYS use the most modern type annotation style
+- NEVER use wildcard imports

pydantic_explain-0.0.1a0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+## Setup
+
+Clone the repo and install dependencies:
+
+```bash
+git clone https://github.com/MatthewMckee4/pydantic-explain.git
+cd pydantic-explain
+uv sync --all-groups
+pre-commit install
+```
+
+## Development
+
+### Run tests
+
+```bash
+uv run karva test
+```
+
+### Lint and format
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+### Type check
+
+```bash
+uv run ty check
+```
+
+## Pull Requests
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Ensure all checks pass: tests, lint, format, type check
+4. Submit a PR against `main`
+
+## Releases
+
+1. Update `CHANGELOG.md`
+2. Bump version in `pyproject.toml`
+3. Commit: `git commit -m "chore: release vX.Y.Z"`
+4. Tag: `git tag vX.Y.Z`
+5. Push: `git push origin vX.Y.Z`

pydantic_explain-0.0.1a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Mckee
+
+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.