flowgrate 0.1.0__tar.gz

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

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest
+          pip install -e .
+
+      - name: Run tests
+        run: pytest tests/ -v

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

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install hatchling build
+
+      - name: Set version from tag
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+
+      - name: Run tests
+        run: |
+          pip install pytest
+          pip install -e .
+          pytest tests/ -v
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_KEY }}

flowgrate-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/

flowgrate-0.1.0/LICENSE

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

flowgrate-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: flowgrate
+Version: 0.1.0
+Summary: Python SDK for Flowgrate — Laravel-style database migrations with a fluent API
+Project-URL: Homepage, https://github.com/flowgrate/python
+Project-URL: Repository, https://github.com/flowgrate/python
+Project-URL: Issues, https://github.com/flowgrate/python/issues
+Author-email: flowgrate <hi@flowgrate.dev>
+License: MIT
+License-File: LICENSE
+Keywords: database,fluent,migrations,postgresql,schema
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# flowgrate/python
+
+Python SDK for [Flowgrate](https://github.com/flowgrate/core) — Laravel-style database migrations with a fluent API.
+
+## How it works
+
+Define migrations in Python using the fluent Blueprint API. The SDK serializes them to JSON and pipes to the Flowgrate CLI, which compiles and executes the SQL.
+
+## Requirements
+
+- Python 3.10+
+- [Flowgrate CLI](https://github.com/flowgrate/core/releases) — download the binary for your platform and put it on your `PATH`
+
+```bash
+# Linux (amd64)
+curl -L https://github.com/flowgrate/core/releases/latest/download/flowgrate-linux-amd64 -o flowgrate
+chmod +x flowgrate
+sudo mv flowgrate /usr/local/bin/
+
+# macOS (Apple Silicon)
+curl -L https://github.com/flowgrate/core/releases/latest/download/flowgrate-darwin-arm64 -o flowgrate
+chmod +x flowgrate
+sudo mv flowgrate /usr/local/bin/
+
+# macOS (Intel)
+curl -L https://github.com/flowgrate/core/releases/latest/download/flowgrate-darwin-amd64 -o flowgrate
+chmod +x flowgrate
+sudo mv flowgrate /usr/local/bin/
+
+# Or build from source
+go install github.com/flowgrate/core@latest
+```
+
+## Setup
+
+**1. Install the SDK:**
+
+```bash
+pip install flowgrate
+```
+
+**2. Create `Program.py` (entry point for the CLI to invoke):**
+
+```python
+from flowgrate import FlowgrateRunner
+import os
+
+FlowgrateRunner.run(os.path.dirname(__file__))
+```
+
+**3. Create `flowgrate.yml` next to your migrations:**
+
+Generate it with the CLI (recommended):
+
+```bash
+flowgrate init --db=postgres://user:pass@localhost/mydb
+```
+
+Or create manually:
+
+```yaml
+database:
+  url: postgres://user:pass@localhost/mydb
+
+migrations:
+  project: ./migrations
+  sdk: python
+  run: python Program.py
+```
+
+**4. Generate and run migrations:**
+
+```bash
+flowgrate make CreateUsersTable
+flowgrate up
+```
+
+## Migration anatomy
+
+```python
+from flowgrate import Migration, Schema
+
+
+class CreateUsersTable(Migration):
+    def up(self):
+        with Schema.create("users") as t:
+            t.id()
+            t.string("name")
+            t.string("email", 100)
+            t.timestamps()
+
+    def down(self):
+        Schema.drop_if_exists("users")
+```
+
+Migration files must follow the naming convention: `YYYYMMDD_HHMMSS_MigrationName.py`
+
+## Blueprint API reference
+
+### Create / drop table
+
+```python
+Schema.create("users")          # CREATE TABLE
+Schema.table("users")           # ALTER TABLE
+Schema.drop("users")            # DROP TABLE
+Schema.drop_if_exists("users")  # DROP TABLE IF EXISTS
+```
+
+### Column types
+
+```python
+t.id()                          # BIGSERIAL PRIMARY KEY
+t.small_integer("level")        # SMALLINT
+t.integer("views")              # INTEGER
+t.big_integer("score")          # BIGINT
+t.decimal("price", 10, 2)       # NUMERIC(10, 2)
+t.float("rating")               # REAL
+t.double("latitude")            # DOUBLE PRECISION
+t.boolean("active")             # BOOLEAN
+t.string("name")                # VARCHAR(255)
+t.string("code", 10)            # VARCHAR(10)
+t.text("bio")                   # TEXT
+t.uuid("public_id")             # UUID
+t.json("settings")              # JSON
+t.jsonb("metadata")             # JSONB
+t.binary("avatar")              # BYTEA
+t.date("birthday")              # DATE
+t.time("opens_at")              # TIME
+t.timestamp("verified_at")      # TIMESTAMP
+```
+
+### Column modifiers (chainable)
+
+```python
+.nullable()                     # NULL
+.default(value)                 # DEFAULT value
+.default_expression("NOW()")    # DEFAULT NOW()  — raw SQL
+.generated_uuid()               # DEFAULT gen_random_uuid()
+.comment("description")
+.unique()                       # single-column unique index
+```
+
+### Helpers
+
+```python
+t.timestamps()                  # created_at + updated_at TIMESTAMP DEFAULT NOW()
+t.soft_deletes()                # deleted_at TIMESTAMP NULL
+t.remember_token()              # remember_token VARCHAR(100) NULL
+t.polymorphic("commentable")    # commentable_id BIGINT + commentable_type VARCHAR(255) + index
+t.nullable_polymorphic("taggable")
+```
+
+### Foreign keys
+
+```python
+t.foreign_id("role_id") \
+ .constrained("roles") \
+ .on_delete("cascade") \
+ .on_update("cascade")
+```
+
+### Indexes
+
+```python
+t.unique("email", "tenant_id", name="uq_users_email_tenant")
+t.index("created_at")
+t.index("email", "name", name="idx_users_search")
+```
+
+### ALTER TABLE
+
+```python
+with Schema.table("users") as t:
+    t.add_column("phone").string(20).nullable()
+    t.change_column("name").string(500)
+    t.drop_column("avatar")
+```
+
+## Running in Docker
+
+```bash
+docker compose exec sdk python Program.py | flowgrate up
+```

flowgrate-0.1.0/README.md

@@ -0,0 +1,183 @@
+# flowgrate/python
+
+Python SDK for [Flowgrate](https://github.com/flowgrate/core) — Laravel-style database migrations with a fluent API.
+
+## How it works
+
+Define migrations in Python using the fluent Blueprint API. The SDK serializes them to JSON and pipes to the Flowgrate CLI, which compiles and executes the SQL.
+
+## Requirements
+
+- Python 3.10+
+- [Flowgrate CLI](https://github.com/flowgrate/core/releases) — download the binary for your platform and put it on your `PATH`
+
+```bash
+# Linux (amd64)
+curl -L https://github.com/flowgrate/core/releases/latest/download/flowgrate-linux-amd64 -o flowgrate
+chmod +x flowgrate
+sudo mv flowgrate /usr/local/bin/
+
+# macOS (Apple Silicon)
+curl -L https://github.com/flowgrate/core/releases/latest/download/flowgrate-darwin-arm64 -o flowgrate
+chmod +x flowgrate
+sudo mv flowgrate /usr/local/bin/
+
+# macOS (Intel)
+curl -L https://github.com/flowgrate/core/releases/latest/download/flowgrate-darwin-amd64 -o flowgrate
+chmod +x flowgrate
+sudo mv flowgrate /usr/local/bin/
+
+# Or build from source
+go install github.com/flowgrate/core@latest
+```
+
+## Setup
+
+**1. Install the SDK:**
+
+```bash
+pip install flowgrate
+```
+
+**2. Create `Program.py` (entry point for the CLI to invoke):**
+
+```python
+from flowgrate import FlowgrateRunner
+import os
+
+FlowgrateRunner.run(os.path.dirname(__file__))
+```
+
+**3. Create `flowgrate.yml` next to your migrations:**
+
+Generate it with the CLI (recommended):
+
+```bash
+flowgrate init --db=postgres://user:pass@localhost/mydb
+```
+
+Or create manually:
+
+```yaml
+database:
+  url: postgres://user:pass@localhost/mydb
+
+migrations:
+  project: ./migrations
+  sdk: python
+  run: python Program.py
+```
+
+**4. Generate and run migrations:**
+
+```bash
+flowgrate make CreateUsersTable
+flowgrate up
+```
+
+## Migration anatomy
+
+```python
+from flowgrate import Migration, Schema
+
+
+class CreateUsersTable(Migration):
+    def up(self):
+        with Schema.create("users") as t:
+            t.id()
+            t.string("name")
+            t.string("email", 100)
+            t.timestamps()
+
+    def down(self):
+        Schema.drop_if_exists("users")
+```
+
+Migration files must follow the naming convention: `YYYYMMDD_HHMMSS_MigrationName.py`
+
+## Blueprint API reference
+
+### Create / drop table
+
+```python
+Schema.create("users")          # CREATE TABLE
+Schema.table("users")           # ALTER TABLE
+Schema.drop("users")            # DROP TABLE
+Schema.drop_if_exists("users")  # DROP TABLE IF EXISTS
+```
+
+### Column types
+
+```python
+t.id()                          # BIGSERIAL PRIMARY KEY
+t.small_integer("level")        # SMALLINT
+t.integer("views")              # INTEGER
+t.big_integer("score")          # BIGINT
+t.decimal("price", 10, 2)       # NUMERIC(10, 2)
+t.float("rating")               # REAL
+t.double("latitude")            # DOUBLE PRECISION
+t.boolean("active")             # BOOLEAN
+t.string("name")                # VARCHAR(255)
+t.string("code", 10)            # VARCHAR(10)
+t.text("bio")                   # TEXT
+t.uuid("public_id")             # UUID
+t.json("settings")              # JSON
+t.jsonb("metadata")             # JSONB
+t.binary("avatar")              # BYTEA
+t.date("birthday")              # DATE
+t.time("opens_at")              # TIME
+t.timestamp("verified_at")      # TIMESTAMP
+```
+
+### Column modifiers (chainable)
+
+```python
+.nullable()                     # NULL
+.default(value)                 # DEFAULT value
+.default_expression("NOW()")    # DEFAULT NOW()  — raw SQL
+.generated_uuid()               # DEFAULT gen_random_uuid()
+.comment("description")
+.unique()                       # single-column unique index
+```
+
+### Helpers
+
+```python
+t.timestamps()                  # created_at + updated_at TIMESTAMP DEFAULT NOW()
+t.soft_deletes()                # deleted_at TIMESTAMP NULL
+t.remember_token()              # remember_token VARCHAR(100) NULL
+t.polymorphic("commentable")    # commentable_id BIGINT + commentable_type VARCHAR(255) + index
+t.nullable_polymorphic("taggable")
+```
+
+### Foreign keys
+
+```python
+t.foreign_id("role_id") \
+ .constrained("roles") \
+ .on_delete("cascade") \
+ .on_update("cascade")
+```
+
+### Indexes
+
+```python
+t.unique("email", "tenant_id", name="uq_users_email_tenant")
+t.index("created_at")
+t.index("email", "name", name="idx_users_search")
+```
+
+### ALTER TABLE
+
+```python
+with Schema.table("users") as t:
+    t.add_column("phone").string(20).nullable()
+    t.change_column("name").string(500)
+    t.drop_column("avatar")
+```
+
+## Running in Docker
+
+```bash
+docker compose exec sdk python Program.py | flowgrate up
+```

flowgrate-0.1.0/flowgrate/__init__.py

@@ -0,0 +1,5 @@
+from .migration import Migration
+from .runner import FlowgrateRunner
+from .schema import Schema, Blueprint, ColumnBuilder, ColumnType
+
+__all__ = ["Migration", "FlowgrateRunner", "Schema", "Blueprint", "ColumnBuilder", "ColumnType"]

flowgrate-0.1.0/flowgrate/migration.py

@@ -0,0 +1,9 @@
+from abc import ABC, abstractmethod
+
+
+class Migration(ABC):
+    @abstractmethod
+    def up(self) -> None: ...
+
+    @abstractmethod
+    def down(self) -> None: ...

flowgrate-0.1.0/flowgrate/runner.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+import importlib.util
+import inspect
+import json
+import os
+import re
+import sys
+
+from .migration import Migration
+from .schema.schema import Schema, SchemaOperation
+from .schema.types import ColumnDefinition, ColumnAction, IndexDefinition, ForeignKeyDefinition
+
+
+_MIGRATION_PATTERN = re.compile(r"^\d{8}_\d{6}_\w+\.py$")
+
+
+def main() -> None:
+    """Entry point: run migrations from the current directory."""
+    directory = sys.argv[1] if len(sys.argv) > 1 else os.path.dirname(os.path.abspath(sys.argv[0]))
+    FlowgrateRunner.run(directory)
+
+
+class FlowgrateRunner:
+    @classmethod
+    def run(cls, directory: str) -> None:
+        """Discover all migrations in directory, serialize to JSON and write to stdout."""
+        migrations = cls._discover(directory)
+        for name, migration_cls in migrations:
+            manifest = cls._build_manifest(name, migration_cls())
+            print(json.dumps(manifest, ensure_ascii=False))
+
+    @classmethod
+    def _discover(cls, directory: str) -> list[tuple[str, type[Migration]]]:
+        directory = os.path.abspath(directory)
+        files = sorted(
+            f for f in os.listdir(directory)
+            if _MIGRATION_PATTERN.match(f)
+        )
+        result = []
+        for filename in files:
+            path = os.path.join(directory, filename)
+            migration_cls = cls._load(path)
+            if migration_cls:
+                name = os.path.splitext(filename)[0]
+                result.append((name, migration_cls))
+        return result
+
+    @classmethod
+    def _load(cls, path: str) -> type[Migration] | None:
+        spec = importlib.util.spec_from_file_location("_migration", path)
+        if spec is None or spec.loader is None:
+            return None
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)  # type: ignore[union-attr]
+
+        for _, obj in inspect.getmembers(module, inspect.isclass):
+            if issubclass(obj, Migration) and obj is not Migration:
+                return obj
+        return None
+
+    @classmethod
+    def _build_manifest(cls, name: str, migration: Migration) -> dict:
+        Schema.reset()
+        migration.up()
+        up = [cls._serialize_op(op) for op in Schema._operations]
+
+        Schema.reset()
+        migration.down()
+        down = [cls._serialize_op(op) for op in Schema._operations]
+
+        Schema.reset()
+        return {"migration": name, "up": up, "down": down}
+
+    @classmethod
+    def _serialize_op(cls, op: SchemaOperation) -> dict:
+        result: dict = {"action": op.action, "table": op.table}
+
+        if op.if_exists:
+            result["if_exists"] = True
+
+        if op.blueprint:
+            bp = op.blueprint
+            is_alter = op.action == "alter_table"
+            if bp.columns:
+                result["columns"] = [cls._serialize_col(c, is_alter) for c in bp.columns]
+            if bp.indexes:
+                result["indexes"] = [cls._serialize_idx(i) for i in bp.indexes]
+            if bp.foreign_keys:
+                result["foreign_keys"] = [cls._serialize_fk(f) for f in bp.foreign_keys]
+
+        return result
+
+    @classmethod
+    def _serialize_col(cls, col: ColumnDefinition, in_alter: bool = False) -> dict:
+        d: dict = {"name": col.name, "type": col.type.value}
+
+        if in_alter or col.action != ColumnAction.ADD:
+            d["column_action"] = col.action.value
+        if col.length is not None:
+            d["length"] = col.length
+        if col.precision is not None:
+            d["precision"] = col.precision
+        if col.scale is not None:
+            d["scale"] = col.scale
+        if col.nullable:
+            d["nullable"] = True
+        if col.primary:
+            d["primary"] = True
+        if col.auto_increment:
+            d["auto_increment"] = True
+        if col.has_default:
+            if col.is_default_expression:
+                d["default_expression"] = col.default_value
+            else:
+                d["default"] = col.default_value
+        if col.comment:
+            d["comment"] = col.comment
+
+        return d
+
+    @classmethod
+    def _serialize_idx(cls, idx: IndexDefinition) -> dict:
+        d: dict = {"columns": idx.columns}
+        if idx.unique:
+            d["unique"] = True
+        if idx.name:
+            d["name"] = idx.name
+        return d
+
+    @classmethod
+    def _serialize_fk(cls, fk: ForeignKeyDefinition) -> dict:
+        d: dict = {
+            "column": fk.column,
+            "references_table": fk.references_table,
+            "references_column": fk.references_column,
+        }
+        if fk.on_update:
+            d["on_update"] = fk.on_update
+        if fk.on_delete:
+            d["on_delete"] = fk.on_delete
+        return d

flowgrate-0.1.0/flowgrate/schema/__init__.py

@@ -0,0 +1,11 @@
+from .types import ColumnType, ColumnAction, ColumnDefinition, IndexDefinition, ForeignKeyDefinition
+from .blueprint import Blueprint
+from .column_builder import ColumnBuilder
+from .schema import Schema, SchemaOperation
+
+__all__ = [
+    "ColumnType", "ColumnAction", "ColumnDefinition",
+    "IndexDefinition", "ForeignKeyDefinition",
+    "Blueprint", "ColumnBuilder",
+    "Schema", "SchemaOperation",
+]