pgcraft 0.1.2__tar.gz

pgcraft-0.1.2/LICENSE

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

pgcraft-0.1.2/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.3
+Name: pgcraft
+Version: 0.1.2
+Summary: Configuration-driven PostgreSQL dimension tables, migrations, and APIs.
+Author: Rodda John
+Author-email: Rodda John <roddarjohn@protonmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 Rodda John
+         
+         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.
+Requires-Dist: pglast>=7.11
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: sqlalchemy-declarative-extensions>=0.16.8
+Requires-Dist: typer>=0.24.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# pgcraft
+
+[Documentation](https://roddarjohn.github.io/pgcraft/)
+
+**Configuration-driven PostgreSQL dimension tables, migrations, and APIs.**
+
+pgcraft generates SQLAlchemy models, Alembic migrations, and
+[PostgREST](https://postgrest.org) API views from declarative dimension
+configurations. Define your schema once; pgcraft handles the rest.
+
+---
+
+## Features
+
+- **Dimension types** — Simple, Append-Only (SCD Type 2), and
+  Entity-Attribute-Value, each with generated backing tables, views, and
+  triggers.
+- **Plugin architecture** — Composable plugins with `@requires` / `@produces`
+  decorators, executed in topological order.
+- **Automatic migrations** — Alembic integration with SQL-formatted migration
+  scripts via sqlglot.
+- **PostgREST API layer** — API views, roles, and grants declared alongside
+  your models.
+- **Postgres is king** — Logic lives in the database (views, triggers, check
+  constraints). Python orchestrates; Postgres enforces.
+
+## Quick start
+
+### Install
+
+```bash
+pip install pgcraft            # or: uv add pgcraft
+```
+
+### Define a dimension
+
+```python
+from sqlalchemy import Column, MetaData, String
+from pgcraft.factory.dimension import SimpleDimensionResourceFactory
+
+metadata = MetaData()
+
+SimpleDimensionResourceFactory(
+    tablename="users",
+    schemaname="public",
+    metadata=metadata,
+    schema_items=[
+        Column("name", String, nullable=False),
+        Column("email", String),
+    ],
+)
+```
+
+This creates:
+
+- A `public.users` table with `id`, `name`, and `email` columns.
+- An `api.users` view exposing the same columns for PostgREST.
+- Alembic migration support out of the box.
+
+### Generate migrations
+
+```bash
+pgcraft migrate revision --autogenerate -m "add users"
+pgcraft migrate upgrade head
+```
+
+## Dimension types
+
+pgcraft ships with three built-in dimension types:
+
+| Type | Use case | History? |
+|------|----------|----------|
+| **Simple** | Static reference data | No |
+| **Append-Only** (SCD Type 2) | Track changes over time | Yes |
+| **EAV** | Flexible / sparse attributes with full audit trail | Yes |
+
+See the [dimensions documentation](https://roddarjohn.github.io/pgcraft/dimensions.html) for ERD diagrams, schema details, and worked examples.
+
+## Documentation
+
+Full documentation is available at
+[roddarjohn.github.io/pgcraft](https://roddarjohn.github.io/pgcraft/).
+
+- [Setup & installation](https://roddarjohn.github.io/pgcraft/setup.html)
+- [Built-in dimensions](https://roddarjohn.github.io/pgcraft/dimensions.html)
+- [Plugin system](https://roddarjohn.github.io/pgcraft/plugins.html)
+- [API reference](https://roddarjohn.github.io/pgcraft/api.html)
+- [Development guide](https://roddarjohn.github.io/pgcraft/development.html)
+- [Playground](https://roddarjohn.github.io/pgcraft/playground.html)
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/<username>/pgcraft.git
+cd pgcraft
+uv sync --all-groups
+
+# Run checks
+just lint          # ruff check + format
+just type-check    # ty check src/
+just dev-test      # pytest (fast, needs DATABASE_URL)
+just test          # tox (full isolation)
+just docs          # build Sphinx HTML docs
+```
+
+Tests require a running PostgreSQL instance:
+
+```bash
+DATABASE_URL=postgresql+psycopg:///pgcraft just dev-test
+```
+
+## Design philosophy
+
+See [PLAN.md](PLAN.md) for the full design philosophy. The short version:
+
+- **Postgres is king.** Push logic into the database when it is obviously
+  correct and declarative.
+- **Explicit over implicit.** No magic — if behavior is not obvious from
+  reading the code, it needs a docstring explaining *why*.
+- **Simple over clever.** Three similar lines are better than a premature
+  abstraction.
+
+## License
+
+See [LICENSE](LICENSE) for details.

pgcraft-0.1.2/README.md

@@ -0,0 +1,126 @@
+# pgcraft
+
+[Documentation](https://roddarjohn.github.io/pgcraft/)
+
+**Configuration-driven PostgreSQL dimension tables, migrations, and APIs.**
+
+pgcraft generates SQLAlchemy models, Alembic migrations, and
+[PostgREST](https://postgrest.org) API views from declarative dimension
+configurations. Define your schema once; pgcraft handles the rest.
+
+---
+
+## Features
+
+- **Dimension types** — Simple, Append-Only (SCD Type 2), and
+  Entity-Attribute-Value, each with generated backing tables, views, and
+  triggers.
+- **Plugin architecture** — Composable plugins with `@requires` / `@produces`
+  decorators, executed in topological order.
+- **Automatic migrations** — Alembic integration with SQL-formatted migration
+  scripts via sqlglot.
+- **PostgREST API layer** — API views, roles, and grants declared alongside
+  your models.
+- **Postgres is king** — Logic lives in the database (views, triggers, check
+  constraints). Python orchestrates; Postgres enforces.
+
+## Quick start
+
+### Install
+
+```bash
+pip install pgcraft            # or: uv add pgcraft
+```
+
+### Define a dimension
+
+```python
+from sqlalchemy import Column, MetaData, String
+from pgcraft.factory.dimension import SimpleDimensionResourceFactory
+
+metadata = MetaData()
+
+SimpleDimensionResourceFactory(
+    tablename="users",
+    schemaname="public",
+    metadata=metadata,
+    schema_items=[
+        Column("name", String, nullable=False),
+        Column("email", String),
+    ],
+)
+```
+
+This creates:
+
+- A `public.users` table with `id`, `name`, and `email` columns.
+- An `api.users` view exposing the same columns for PostgREST.
+- Alembic migration support out of the box.
+
+### Generate migrations
+
+```bash
+pgcraft migrate revision --autogenerate -m "add users"
+pgcraft migrate upgrade head
+```
+
+## Dimension types
+
+pgcraft ships with three built-in dimension types:
+
+| Type | Use case | History? |
+|------|----------|----------|
+| **Simple** | Static reference data | No |
+| **Append-Only** (SCD Type 2) | Track changes over time | Yes |
+| **EAV** | Flexible / sparse attributes with full audit trail | Yes |
+
+See the [dimensions documentation](https://roddarjohn.github.io/pgcraft/dimensions.html) for ERD diagrams, schema details, and worked examples.
+
+## Documentation
+
+Full documentation is available at
+[roddarjohn.github.io/pgcraft](https://roddarjohn.github.io/pgcraft/).
+
+- [Setup & installation](https://roddarjohn.github.io/pgcraft/setup.html)
+- [Built-in dimensions](https://roddarjohn.github.io/pgcraft/dimensions.html)
+- [Plugin system](https://roddarjohn.github.io/pgcraft/plugins.html)
+- [API reference](https://roddarjohn.github.io/pgcraft/api.html)
+- [Development guide](https://roddarjohn.github.io/pgcraft/development.html)
+- [Playground](https://roddarjohn.github.io/pgcraft/playground.html)
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/<username>/pgcraft.git
+cd pgcraft
+uv sync --all-groups
+
+# Run checks
+just lint          # ruff check + format
+just type-check    # ty check src/
+just dev-test      # pytest (fast, needs DATABASE_URL)
+just test          # tox (full isolation)
+just docs          # build Sphinx HTML docs
+```
+
+Tests require a running PostgreSQL instance:
+
+```bash
+DATABASE_URL=postgresql+psycopg:///pgcraft just dev-test
+```
+
+## Design philosophy
+
+See [PLAN.md](PLAN.md) for the full design philosophy. The short version:
+
+- **Postgres is king.** Push logic into the database when it is obviously
+  correct and declarative.
+- **Explicit over implicit.** No magic — if behavior is not obvious from
+  reading the code, it needs a docstring explaining *why*.
+- **Simple over clever.** Three similar lines are better than a premature
+  abstraction.
+
+## License
+
+See [LICENSE](LICENSE) for details.

pgcraft-0.1.2/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "pgcraft"
+version = "0.1.2"
+description = "Configuration-driven PostgreSQL dimension tables, migrations, and APIs."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Rodda John", email = "roddarjohn@protonmail.com" }]
+requires-python = ">=3.12"
+dependencies = [
+  "pglast>=7.11",
+  "pydantic>=2.12.5",
+  "sqlalchemy-declarative-extensions>=0.16.8",
+  "typer>=0.24.1",
+]
+
+[project.scripts]
+pgcraft = "pgcraft.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.10.8,<0.11.0"]
+build-backend = "uv_build"
+
+
+[dependency-groups]
+dev = [
+  "alembic>=1.18.4",
+  "psycopg[binary]>=3.3.3",
+  "pytest>=8",
+  "pytest-alembic>=0.12.1",
+  "python-dotenv>=1.2.2",
+  "slipcover>=1.0.17",
+  "sqlalchemy>=2.0.48",
+  "tox>=4.49.1",
+  "tox-uv>=1.33.2",
+]
+docs = [
+  "furo>=2025.12.19",
+  "sphinx>=7.0",
+  "sphinx-autobuild>=2025.8.25",
+  "sphinx-autodoc-typehints>=3.0.1",
+  "sphinx-copybutton>=0.5.2",
+]
+lint = ["ruff>=0.15.5", "ty>=0.0.20"]
+
+[tool.ruff]
+line-length = 80
+exclude = ["docs", "playground", "tests/db/migrations"]
+
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  # Conflicts with formatter
+  "COM812",
+  "ISC001",
+  # Docstring convention (use D211 + D212)
+  "D203",
+  "D213",
+  # Only enforce docstrings on public classes, functions, and methods
+  "D100", # missing docstring in public module
+  "D104", # missing docstring in public package
+  # Not applicable to this project
+  "AIR",
+  "DJ",
+  "FAST",
+  "NPY",
+  "PD",
+  "INT",
+  "CPY",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/**" = [
+  "INP001", # scripts/ doesn't need __init__.py
+  "T201",   # print is fine in scripts
+]
+"tests/**" = [
+  "S101",    # assert is fine in tests
+  "S608",    # f-string SQL in tests uses controlled schema names, not user input
+  "S702",    # Mako templates in tests are not serving HTML
+  "ANN",     # no annotations required in tests
+  "D",       # no docstrings required in tests
+  "PLR2004", # magic numbers are fine in test assertions
+  "PLC0415", # local imports acceptable in test methods
+  "RUF003",  # unicode × in comments is fine
+  "RUF059",  # unpacked dummy variables are fine in tests
+]
+"**/migrations/versions/*.py" = [
+  "INP001", # migration versions aren't a package
+  "D400",   # migration docstrings don't need to end with a period
+  "D415",   # migration docstrings don't need closing punctuation
+  "W291",   # trailing whitespace on "Revises:" line when there's no parent
+]
+
+[tool.ty.environment]
+extra-paths = ["tests/db"]
+
+[tool.ty.analysis]
+# pglast has no type stubs.
+allowed-unresolved-imports = ["pglast.**"]
+
+[tool.tox]
+requires = ["tox-uv>=1"]
+env_list = ["3.12", "3.13", "3.14"]
+
+[tool.tox.env_run_base]
+dependency_groups = ["dev"]
+pass_env = ["DATABASE_URL"]
+commands = [["pytest", "{posargs:}"]]