mtg-carddb 0.1.0__tar.gz

mtg_carddb-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,94 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: Tests (${{ matrix.os }}, Python ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install package and development tools
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests with network access blocked
+        run: python -m pytest -q --disable-socket
+
+  distributions:
+    name: Build and test distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: python -m pip install "build>=1.2" "twine>=6"
+
+      - name: Build wheel and source distribution
+        run: python -m build
+
+      - name: Validate distribution metadata
+        run: python -m twine check --strict dist/*
+
+      - name: Smoke-test wheel in isolated environment
+        shell: bash
+        run: |
+          python -m venv "$RUNNER_TEMP/carddb-wheel"
+          "$RUNNER_TEMP/carddb-wheel/bin/python" -m pip install --no-index --no-deps dist/*.whl
+
+          cd "$RUNNER_TEMP"
+
+          "$RUNNER_TEMP/carddb-wheel/bin/python" -I -c 'from pathlib import Path; import mtg_carddb as m; assert "site-packages" in str(Path(m.__file__).resolve()); assert callable(m.initialize_database); print(m.__file__)'
+
+          "$RUNNER_TEMP/carddb-wheel/bin/python" -m mtg_carddb --help
+          "$RUNNER_TEMP/carddb-wheel/bin/mtg-carddb" --help
+          "$RUNNER_TEMP/carddb-wheel/bin/mtg-carddb" locks --database "$RUNNER_TEMP/nonexistent-carddb.sqlite"
+
+      - name: Smoke-test sdist in isolated environment
+        shell: bash
+        run: |
+          python -m venv "$RUNNER_TEMP/carddb-sdist"
+          "$RUNNER_TEMP/carddb-sdist/bin/python" -m pip install --no-deps dist/*.tar.gz
+
+          cd "$RUNNER_TEMP"
+
+          "$RUNNER_TEMP/carddb-sdist/bin/python" -I -c 'from pathlib import Path; import mtg_carddb as m; assert "site-packages" in str(Path(m.__file__).resolve()); assert callable(m.update_database); print(m.__file__)'
+
+          "$RUNNER_TEMP/carddb-sdist/bin/python" -m mtg_carddb --help
+          "$RUNNER_TEMP/carddb-sdist/bin/mtg-carddb" --help
+
+      - name: Preserve validated distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: mtg-carddb-distributions
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 7

mtg_carddb-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,112 @@
+# Publishing runs only when the maintainer manually starts this workflow.
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing release tag to publish (for example, v0.1.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Verify and build tagged release
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Validate tag input
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Expected a version tag like v0.1.0" >&2
+            exit 1
+          fi
+
+      - name: Check out the requested tag
+        uses: actions/checkout@v7
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - name: Confirm tag matches package version
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          import tomllib
+
+          project = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"]
+          actual = os.environ["RELEASE_TAG"]
+          expected = f"v{project['version']}"
+          if actual != expected:
+              raise SystemExit(f"Tag {actual!r} does not match package version {expected!r}")
+          if project["name"] != "mtg-carddb":
+              raise SystemExit("Unexpected distribution name")
+          PY
+
+      - name: Install development dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run offline tests
+        run: python -m pytest -q --disable-socket
+
+      - name: Build wheel and source distribution
+        run: python -m build
+
+      - name: Check distribution metadata and count
+        shell: bash
+        run: |
+          python -m twine check --strict dist/*
+          python - <<'PY'
+          from pathlib import Path
+          files = list(Path("dist").iterdir())
+          wheels = [p for p in files if p.suffix == ".whl"]
+          sdists = [p for p in files if p.name.endswith(".tar.gz")]
+          if len(files) != 2 or len(wheels) != 1 or len(sdists) != 1:
+              raise SystemExit(f"Expected one wheel and one sdist; found: {[p.name for p in files]}")
+          PY
+
+      - name: Save validated distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: mtg-carddb-release-dists
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish validated distributions
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/mtg-carddb/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download validated distributions
+        uses: actions/download-artifact@v7
+        with:
+          name: mtg-carddb-release-dists
+          path: dist/
+
+      - name: Publish to PyPI using Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

mtg_carddb-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   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, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

mtg_carddb-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+Notable user-facing changes to MTG CardDB are recorded here.
+
+The project follows a `MAJOR.MINOR.PATCH` version scheme. Releases below 1.0.0 may refine the public API, while SQLite schema compatibility is tracked separately using `PRAGMA user_version`.
+
+## Unreleased
+
+No changes recorded yet.
+
+## 0.1.0 — Initial release candidate
+
+### Added
+
+- Immutable, composable Oracle-ID search API.
+- Read-only SQLite-backed card records and associated metadata.
+- Color identity, color, type, keyword, mana value, produced-mana, legality, Oracle Tag, and historical set/rarity/game queries.
+- Normalization of multiface and reversible-card records.
+- Deterministic Oracle representative and legality selection.
+- Scryfall Default Cards, Oracle Tags, Sets API, and type-catalog acquisition.
+- Verified provenance and source-freshness reporting.
+- Explicit database initialization, update, information, and lock-inspection CLI commands.
+- Progress reporting during database builds.
+- Validated snapshot activation, guarded updates, and lock diagnostics.
+- Network, download-size, and decompression safeguards.
+- Cross-platform CI and clean distribution-installation checks.
+
+### Known limitations
+
+- No individual printing inventory, price history, or historical Oracle text revisions.
+- No automatically retained source archive for exact offline reconstruction.
+- No guaranteed atomic compare-and-replace against unrelated external filesystem writers.
+- Public Python API remains pre-1.0.

mtg_carddb-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to MTG CardDB
+
+Contributions, bug reports, regression tests, and documentation corrections are welcome.
+
+MTG CardDB is a local-first Python library. Its central guarantees are immutable Oracle-ID query results, deterministic normalization, read-only database access, and explicit, safe database updates.
+
+## Development setup
+
+Python 3.11 or newer is required.
+
+Clone the repository, create a virtual environment if desired, and install the development dependencies:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Run the offline test suite:
+
+```powershell
+python -m pytest -q --disable-socket
+```
+
+The ordinary test suite must not depend on the availability of Scryfall or any other external service. Use temporary files, synthetic fixtures, and mocked HTTP responses when testing network or import behavior.
+
+## Before submitting changes
+
+- Add regression tests for corrected bugs and new public behavior.
+- Run the complete offline test suite.
+- Keep imports and database queries free of implicit network requests.
+- Check Windows, Linux, and macOS considerations, especially filesystem replacement, locks, path handling, and timestamps.
+- Update documentation when public behavior changes.
+- Do not commit generated SQLite databases, downloaded Scryfall exports, local credentials, virtual environments, or build artifacts.
+
+GitHub Actions tests the supported Python versions on all three operating systems and verifies wheel and source-distribution builds.
+
+## Public API and schema
+
+The public API is documented in [docs/api.md](docs/api.md). Prefer exposing stable library interfaces through `mtg_carddb.__init__`.
+
+Queries should continue to return native `frozenset[str]` Oracle-ID memberships. Do not substitute printing IDs, mutable result collections, or custom query objects without an explicit API review.
+
+The persisted schema is documented in [docs/schema.md](docs/schema.md).
+
+**The SQL block in `docs/schema.md` must match `SCHEMA_SQL` in `src/mtg_carddb/schema.py`.** This is enforced by `tests/test_schema.py`.
+
+Do not change the SQL schema silently. A schema change requires coordinated changes to its documentation, builder, reader compatibility checks, tests, and SQLite schema version policy.
+
+The current implementation is pre-1.0. API changes should still be deliberate and documented, even though its interface is not yet declared fully stable.
+
+## Scryfall import changes
+
+The standard workflow consumes Default Cards, Oracle Tags, the Sets API, and type catalogs.
+
+Preserve the distinction between known-empty and missing source fields. Keep historical set, rarity, and game observations coupled. Preserve deterministic Oracle representative selection and the separate legality-selection policy.
+
+An unsupported required source shape should produce a diagnostic failure, not fabricated values or a partially activated database.
+
+Real Scryfall integration runs are separate from the offline test suite. Perform them explicitly when changing normalization, import logic, source acquisition, or the on-disk schema. Avoid unnecessary API requests; use bulk exports rather than per-card downloads.
+
+## Reporting issues
+
+When reporting a bug, include the CardDB version, Python version, operating system, the operation attempted, and a minimal reproducible example or traceback.
+
+For database build issues, source timestamps, source types, relevant hashes, and sanitized error messages are useful. Do not upload personal files or unrelated database contents without checking what they contain.
+
+For security-sensitive reports, avoid posting exploit details publicly before there is an opportunity to investigate.
+
+## Releases
+
+See [docs/releasing.md](docs/releasing.md) for the release checklist and compatibility expectations.
+
+The project is licensed under the [MIT License](LICENSE). Card data supplied by Scryfall is subject to its own terms and attribution requirements.

mtg_carddb-0.1.0/LICENSE

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