sqlspec 0.46.2__tar.gz → 0.47.0__tar.gz

sqlspec-0.47.0/.gitignore

@@ -0,0 +1,79 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Generated demo GIFs
+docs/_static/demos/*
+!docs/_static/demos/.gitkeep
+!docs/_static/demos/*.gif
+
+# folders
+.auto_pytabs_cache/
+.hypothesis/
+.mypy_cache/
+.pytest_cache/
+.venv/
+*.egg-info/
+build/
+dist/
+results/
+site/
+target/
+.idea/
+.vscode/
+.cursor/
+.zed/
+.cache
+.coverage*
+# files
+**/*.so
+**/*.sqlite
+**/*.sqlite*
+*.iml
+.coverage
+.dmypy.json
+.python-version
+.ruff_cache
+/docs/_build/
+docs/autoapi/
+coverage.*
+setup.py
+tmp/
+*.log
+.tmp
+.tmp_mypyc
+TODO*
+.env
+tools/*.json
+benchmarks/
+.benchmark
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+*.duckdb
+.crush
+CRUSH.md
+CLAUDE.md
+AGENTS.md
+docs-build
+.envs/
+.claude/*
+.gh-cache
+.gemini/
+specs/
+.playwright-mcp
+.geminiignore
+uv.toml
+.agent/
+.geminiignore
+.beads/
+tools/scripts/profiles/*.prof
+.agents/
+
+# Beads / Dolt files (added by bd init)
+.dolt/
+.beads-credential-key
+.codex
+.mypy_worker*

sqlspec-0.47.0/.pre-commit-config.yaml

@@ -0,0 +1,53 @@
+default_language_version:
+  python: "3"
+repos:
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.4.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-ast
+      - id: check-case-conflict
+      - id: check-toml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: "v0.15.14"
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.2
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli
+  - repo: https://github.com/python-formate/flake8-dunder-all
+    rev: v0.5.0
+    hooks:
+      - id: ensure-dunder-all
+        exclude: "test*|tools"
+        args: ["--use-tuple"]
+  - repo: https://github.com/ariebovenberg/slotscheck
+    rev: v0.19.1
+    hooks:
+      - id: slotscheck
+        exclude: "docs|.github"
+  - repo: https://github.com/sphinx-contrib/sphinx-lint
+    rev: "v1.0.2"
+    hooks:
+      - id: sphinx-lint
+        args: ["--jobs", "1"]
+  - repo: local
+    hooks:
+      - id: pypi-readme
+        name: pypi-readme
+        language: python
+        entry: python tools/pypi_readme.py
+        types: [markdown]

sqlspec-0.47.0/CONTRIBUTING.rst

@@ -0,0 +1,165 @@
+Contribution guide
+==================
+
+Setting up the environment
+--------------------------
+
+1. Run ``make install-uv`` to install `uv <https://docs.astral.sh/uv/>`_ if not already installed
+1. Run ``make install`` to install all dependencies and pre-commit hooks
+
+
+Code contributions
+------------------
+
+Workflow
+++++++++
+
+1. `Fork <https://github.com/litestar-org/sqlspec/fork>`_ the `sqlspec repository <https://github.com/litestar-org/sqlspec>`_
+2. Clone your fork locally with git
+3. `Set up the environment <#setting-up-the-environment>`_
+4. Make your changes
+5. Run ``make lint`` to run linters and formatters. This step is optional and will be executed
+   automatically by git before you make a commit, but you may want to run it manually in order to apply fixes
+6. Commit your changes to git
+7. Push the changes to your fork
+8. Open a `pull request <https://docs.github.com/en/pull-requests>`_. Give the pull request a descriptive title
+   indicating what it changes. If it has a corresponding open issue, the issue number should be included in the title as
+   well. For example a pull request that fixes issue ``bug: Increased stack size making it impossible to find needle #100``
+   could be titled ``fix(#100): Make needles easier to find by applying fire to haystack``
+
+.. tip:: Pull requests and commits all need to follow the
+    `Conventional Commit format <https://www.conventionalcommits.org>`_
+
+Guidelines for writing code
+----------------------------
+
+- All code should be fully `typed <https://peps.python.org/pep-0484/>`_. This is enforced via
+  `mypy <https://mypy.readthedocs.io/en/stable/>`_.
+- All code should be tested. This is enforced via `pytest <https://docs.pytest.org/en/stable/>`_.
+- All code should be properly formatted. This is enforced via `black <https://black.readthedocs.io/en/stable/>`_ and `Ruff <https://docs.astral.sh/ruff/>`_.
+
+Logging
+++++++++
+
+- Logger names must follow the ``sqlspec.<module>`` hierarchy.
+- Always obtain loggers via ``sqlspec.utils.logging.get_logger`` to ensure filters are attached.
+- Use static event names in structured logs and include context fields instead of dynamic message strings.
+
+Writing and running tests
++++++++++++++++++++++++++
+
+.. todo:: Write this section
+
+Mypyc and performance gates
++++++++++++++++++++++++++++
+
+SQLSpec keeps a narrow compiled surface for hot paths. If a change touches
+``pyproject.toml`` mypyc includes or excludes, ``tools/scripts/bench*.py``,
+``tools/scripts/mypyc_*.py``, compiled ``sqlspec/core`` or ``sqlspec/driver``
+modules, storage registry/pipeline code, data dictionary registry code, or
+adapter ``core.py`` / ``type_converter.py`` files, run the focused gates below
+before opening a pull request:
+
+.. code-block:: console
+
+   make test-mypyc
+   uv run python tools/scripts/mypyc_inventory.py
+
+For pull requests that change build hooks, wheel workflows, or compiled import
+boundaries, also run:
+
+.. code-block:: console
+
+   make build-performance
+   uv run python tools/scripts/mypyc_smoke.py
+
+Benchmark claims need current artifacts rather than estimates. Use JSON output
+when capturing baselines for review:
+
+.. code-block:: console
+
+   uv run python tools/scripts/bench.py --json-output /tmp/sqlspec-bench.json
+   uv run python tools/scripts/bench_gate.py --json-output /tmp/sqlspec-bench-gate.json
+   uv run python tools/scripts/bench_subsystems.py --json-output /tmp/sqlspec-bench-subsystems.json
+
+CI gate ownership:
+
+- Pull requests always run lint, mypy, pyright, slotscheck, docs, and the Python
+  test matrix through ``.github/workflows/ci.yml``.
+- Pull requests that touch build configuration run
+  ``.github/workflows/test-build.yml``. The default pull-request path builds a
+  subset mypyc wheel matrix; maintainers can dispatch the full architecture
+  matrix when release confidence is needed.
+- Releases run ``.github/workflows/publish.yml`` with standard wheels, mypyc
+  wheels, PGO on Linux and macOS, and mypyc smoke imports before publishing.
+- ``.github/workflows/pgo-validate.yml`` is manual Linux PGO validation. It is
+  useful for build-hook changes but is not required for every pull request.
+- Optional services and container-backed adapter benchmarks remain manual unless
+  their owning PR explicitly opts into those dependencies.
+
+Project documentation
+---------------------
+
+The documentation is located in the ``/docs`` directory and is `ReST <https://docutils.sourceforge.io/rst.html>`_ and
+`Sphinx <https://www.sphinx-doc.org/en/master/>`_. If you're unfamiliar with any of those,
+`ReStructuredText primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ and
+`Sphinx quickstart <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_ are recommended reads.
+
+Running the docs locally
+++++++++++++++++++++++++
+
+You can serve the documentation with ``make docs-serve``, or build them with ``make docs``.
+
+CLI demo recordings
++++++++++++++++++++
+
+SQLSpec uses `VHS <https://github.com/charmbracelet/vhs>`_ to record terminal demos as GIF files
+that are embedded in the documentation.
+
+**Requirements:** VHS, ffmpeg, ttyd
+
+**Installation:**
+
+.. code-block:: console
+
+   go install github.com/charmbracelet/vhs@latest
+
+**Recording demos:**
+
+.. code-block:: console
+
+   make docs-demos
+
+This will process every ``.tape`` file in ``docs/_tapes/`` and write GIF output to
+``docs/_static/demos/``.
+
+**Creating a new tape:**
+
+1. Create a new ``.tape`` file in ``docs/_tapes/``.
+2. Use the standard header (see existing tapes for examples). All tapes should use
+   the ``Catppuccin Mocha`` theme, font size 14, and 1000x600 dimensions.
+3. Use ``Hide``/``Show`` commands to hide setup steps like virtual environment activation.
+4. Include generous ``Sleep`` durations after commands that produce output.
+5. Run ``make docs-demos`` to generate the GIF.
+6. Reference the GIF in your documentation with an ``.. image::`` directive pointing to
+   ``/_static/demos/<name>.gif``.
+
+**Building docs with demos:**
+
+.. code-block:: console
+
+   make docs-all
+
+Creating a new release
+----------------------
+
+1. Increment the version in `pyproject.toml <https://github.com/litestar-org/sqlspec/blob/main/pyproject.toml>`_.
+    .. note:: The version should follow `semantic versioning <https://semver.org/>`_ and `PEP 440 <https://peps.python.org/pep-0440/>`_.
+2. `Draft a new release <https://github.com/litestar-org/sqlspec/releases/new>`_ on GitHub
+
+   * Use ``vMAJOR.MINOR.PATCH`` (e.g. ``v1.2.3``) as both the tag and release title
+   * Fill in the release description. You can use the "Generate release notes" function to get a draft for this
+3. Commit your changes and push to ``main``
+4. Publish the release
+5. Go to `Actions <https://github.com/litestar-org/sqlspec/actions>`_ and approve the release workflow
+6. Check that the workflow runs successfully