oxyde-postgres 0.1.0__tar.gz

oxyde_postgres-0.1.0/LICENSE

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

oxyde_postgres-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: oxyde-postgres
+Version: 0.1.0
+Summary: Type-safe asynchronous ORM for PostgreSQL 18+ with a Rust core
+Author-email: Nikita Ryzhenkov <nikita.ryzhenkoff@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Nikita Ryzhenkov
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/ebrake/oxyde-postgres
+Project-URL: Documentation, https://github.com/ebrake/oxyde-postgres/tree/main/docs
+Project-URL: Repository, https://github.com/ebrake/oxyde-postgres
+Project-URL: Issues, https://github.com/ebrake/oxyde-postgres/issues
+Keywords: orm,async,database,postgresql,pydantic
+Classifier: Development Status :: 4 - Beta
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Rust
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: msgpack>=1.0
+Requires-Dist: typer>=0.24
+Requires-Dist: oxyde-postgres-core<0.2.0,>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.14.7; extra == "dev"
+Requires-Dist: pre-commit>=4.5.0; extra == "dev"
+Requires-Dist: mypy==1.19.1; extra == "dev"
+Requires-Dist: pyright[nodejs]==1.1.411; extra == "dev"
+Requires-Dist: ty==0.0.59; extra == "dev"
+Requires-Dist: testcontainers[postgres]>=4.0; extra == "dev"
+Requires-Dist: psycopg2-binary>=2.9; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Dynamic: license-file
+
+# Oxyde for PostgreSQL
+
+Oxyde for PostgreSQL is a PostgreSQL-focused fork of [Oxyde ORM](https://github.com/mr-fatalyst/oxyde): a type-safe, Pydantic-centric asynchronous ORM with a high-performance Rust core designed for clarity, speed, and reliability. It builds on Oxyde's great work and optimizes it for PostgreSQL with bug fixes and PostgreSQL-specific features.
+
+**Requires PostgreSQL 18+ and Python 3.10+.** The Rust core checks the server version when connecting. Both `postgres://` and `postgresql://` connection URLs are supported.
+
+## Features
+
+- Pydantic v2 models with validation, type hints, and serialization.
+- Familiar `Model.objects.filter()` queries, joins, aggregates, and bulk operations.
+- Native PostgreSQL arrays, JSONB, enums, UUIDs, decimals, `RETURNING`, and row locks.
+- Array and JSON lookups: `contains`, `contained_by`, and `overlap`.
+- Async transactions with nested savepoints and public transaction-depth reporting.
+- Schema migrations with PostgreSQL advisory locking and transactional DDL.
+- Rust SQL generation, connection pooling, and execution, with Python 3.15 wheel support.
+- Cache-disabled unnamed statements for PostgreSQL/PgBouncer, including cold custom-type decoding without replaying queries.
+
+The initial fork release is **0.1.0**. [First-release notes](docs/changelog.md) list every addition and its source.
+
+## Installation
+
+```bash
+pip install oxyde-postgres
+```
+
+The distribution names are `oxyde-postgres` and `oxyde-postgres-core`. Python imports remain `oxyde`, the native module remains `_oxyde_core`, and the CLI remains `oxyde`. Use a separate virtual environment from upstream Oxyde because the packages share these import names.
+
+To build this checkout:
+
+```bash
+uv venv --python 3.13
+source .venv/bin/activate
+uv pip install maturin
+maturin develop --manifest-path crates/oxyde-core-py/Cargo.toml
+uv pip install -e './python[dev]'
+```
+
+## Quick start
+
+```python
+import asyncio
+from oxyde import Field, Model, db
+from oxyde.db.schema import create_tables
+
+class User(Model):
+    id: int | None = Field(default=None, db_pk=True)
+    name: str
+    email: str = Field(db_unique=True)
+    tags: list[str] = Field(default_factory=list)
+
+    class Meta:
+        is_table = True
+
+async def main():
+    await db.init(default="postgresql://user:password@localhost:5432/app")
+    try:
+        connection = await db.get_connection()
+        await create_tables(connection)
+        await User.objects.create(name="Alice", email="alice@example.com", tags=["python"])
+        users = await User.objects.filter(tags__contains=["python"]).all()
+        print(users)
+    finally:
+        await db.close()
+
+asyncio.run(main())
+```
+
+For managed schema changes, run `oxyde init`, `oxyde makemigrations`, and `oxyde migrate`. See the [documentation](docs/index.md), [connection guide](docs/guide/connections.md), and [contributor guide](.github/CONTRIBUTING.md).
+
+## Credit and license
+
+Oxyde for PostgreSQL is based on [Oxyde](https://github.com/mr-fatalyst/oxyde), created by Nikita Ryzhenkov and its contributors. The original MIT [license](LICENSE) is preserved. The vendored SQLx PostgreSQL driver retains its MIT and Apache-2.0 licenses.

oxyde_postgres-0.1.0/README.md

@@ -0,0 +1,72 @@
+# Oxyde for PostgreSQL
+
+Oxyde for PostgreSQL is a PostgreSQL-focused fork of [Oxyde ORM](https://github.com/mr-fatalyst/oxyde): a type-safe, Pydantic-centric asynchronous ORM with a high-performance Rust core designed for clarity, speed, and reliability. It builds on Oxyde's great work and optimizes it for PostgreSQL with bug fixes and PostgreSQL-specific features.
+
+**Requires PostgreSQL 18+ and Python 3.10+.** The Rust core checks the server version when connecting. Both `postgres://` and `postgresql://` connection URLs are supported.
+
+## Features
+
+- Pydantic v2 models with validation, type hints, and serialization.
+- Familiar `Model.objects.filter()` queries, joins, aggregates, and bulk operations.
+- Native PostgreSQL arrays, JSONB, enums, UUIDs, decimals, `RETURNING`, and row locks.
+- Array and JSON lookups: `contains`, `contained_by`, and `overlap`.
+- Async transactions with nested savepoints and public transaction-depth reporting.
+- Schema migrations with PostgreSQL advisory locking and transactional DDL.
+- Rust SQL generation, connection pooling, and execution, with Python 3.15 wheel support.
+- Cache-disabled unnamed statements for PostgreSQL/PgBouncer, including cold custom-type decoding without replaying queries.
+
+The initial fork release is **0.1.0**. [First-release notes](docs/changelog.md) list every addition and its source.
+
+## Installation
+
+```bash
+pip install oxyde-postgres
+```
+
+The distribution names are `oxyde-postgres` and `oxyde-postgres-core`. Python imports remain `oxyde`, the native module remains `_oxyde_core`, and the CLI remains `oxyde`. Use a separate virtual environment from upstream Oxyde because the packages share these import names.
+
+To build this checkout:
+
+```bash
+uv venv --python 3.13
+source .venv/bin/activate
+uv pip install maturin
+maturin develop --manifest-path crates/oxyde-core-py/Cargo.toml
+uv pip install -e './python[dev]'
+```
+
+## Quick start
+
+```python
+import asyncio
+from oxyde import Field, Model, db
+from oxyde.db.schema import create_tables
+
+class User(Model):
+    id: int | None = Field(default=None, db_pk=True)
+    name: str
+    email: str = Field(db_unique=True)
+    tags: list[str] = Field(default_factory=list)
+
+    class Meta:
+        is_table = True
+
+async def main():
+    await db.init(default="postgresql://user:password@localhost:5432/app")
+    try:
+        connection = await db.get_connection()
+        await create_tables(connection)
+        await User.objects.create(name="Alice", email="alice@example.com", tags=["python"])
+        users = await User.objects.filter(tags__contains=["python"]).all()
+        print(users)
+    finally:
+        await db.close()
+
+asyncio.run(main())
+```
+
+For managed schema changes, run `oxyde init`, `oxyde makemigrations`, and `oxyde migrate`. See the [documentation](docs/index.md), [connection guide](docs/guide/connections.md), and [contributor guide](.github/CONTRIBUTING.md).
+
+## Credit and license
+
+Oxyde for PostgreSQL is based on [Oxyde](https://github.com/mr-fatalyst/oxyde), created by Nikita Ryzhenkov and its contributors. The original MIT [license](LICENSE) is preserved. The vendored SQLx PostgreSQL driver retains its MIT and Apache-2.0 licenses.

oxyde_postgres-0.1.0/oxyde/__init__.py

@@ -0,0 +1,151 @@
+"""Oxyde ORM - High-performance async Python ORM with Rust core.
+
+This is the main entry point for the Oxyde ORM library. It re-exports
+all public APIs from submodules for convenient access.
+
+Public API:
+    Models:
+        Model: Base class for all ORM models (Pydantic v2 based).
+        Field: Field configuration with db_pk, db_index, db_default, etc.
+        Index: Composite index decorator for models.
+        Check: CHECK constraint decorator for models.
+
+    Queries:
+        Query: SELECT query builder with Django-like filter syntax.
+        QueryManager: Model.objects manager for CRUD operations.
+        Q: Boolean expressions for complex filters (AND/OR/NOT).
+        F: Database-side field references for expressions.
+
+    Aggregates:
+        Count, Sum, Avg, Max, Min: SQL aggregate functions.
+        Concat, Coalesce: SQL scalar functions.
+        RawSQL: Raw SQL expression wrapper.
+
+    Database:
+        db: Database module with init(), close(), connect(), lifespan().
+        AsyncDatabase: Connection pool wrapper.
+        PoolSettings: Pool configuration (max_connections, timeouts).
+        atomic: Transaction context manager (decorator or async with).
+
+    Exceptions:
+        OxydeError: Base exception for all Oxyde errors.
+        NotFoundError: Raised when get() finds no results.
+        MultipleObjectsReturned: Raised when get() finds multiple results.
+        IntegrityError: Raised on constraint violations.
+        FieldError, FieldLookupError, ManagerError: Validation errors.
+
+Example:
+    from oxyde import Model, Field, db
+
+    class User(Model):
+        id: int | None = Field(default=None, db_pk=True)
+        name: str
+
+        class Meta:
+            is_table = True
+
+    async with db.connect("postgresql://localhost/app"):
+        user = await User.objects.create(name="Alice")
+        users = await User.objects.filter(name__startswith="A").all()
+"""
+
+import warnings
+
+from oxyde import db
+from oxyde.db import (
+    AsyncDatabase,
+    PoolSettings,
+    TransactionTimeoutError,
+    atomic,
+    create_tables,
+    disconnect_all,
+    drop_tables,
+    get_connection,
+    register_connection,
+)
+from oxyde.exceptions import (
+    CheckViolationError,
+    FieldError,
+    FieldLookupError,
+    FieldLookupValueError,
+    ForeignKeyViolationError,
+    IntegrityError,
+    ManagerError,
+    MultipleObjectsReturned,
+    NotFoundError,
+    NotNullViolationError,
+    OxydeError,
+    UniqueViolationError,
+)
+from oxyde.models import Check, Field, Index, Model
+from oxyde.queries import (
+    Avg,
+    Coalesce,
+    Concat,
+    Count,
+    F,
+    Max,
+    Min,
+    Q,
+    Query,
+    QueryManager,
+    RawSQL,
+    Sum,
+    execute_raw,
+)
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str) -> type:
+    if name == "OxydeModel":
+        warnings.warn(
+            "OxydeModel is deprecated, use Model instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return Model
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "Model",
+    "db",
+    "AsyncDatabase",
+    "PoolSettings",
+    "TransactionTimeoutError",
+    "register_connection",
+    "get_connection",
+    "disconnect_all",
+    "create_tables",
+    "drop_tables",
+    "Field",
+    "Index",
+    "Check",
+    "Query",
+    "QueryManager",
+    "OxydeError",
+    "FieldError",
+    "FieldLookupError",
+    "FieldLookupValueError",
+    "ManagerError",
+    "NotFoundError",
+    "MultipleObjectsReturned",
+    "IntegrityError",
+    "UniqueViolationError",
+    "ForeignKeyViolationError",
+    "NotNullViolationError",
+    "CheckViolationError",
+    "atomic",
+    "F",
+    "Q",
+    "Count",
+    "Sum",
+    "Avg",
+    "Max",
+    "Min",
+    "Concat",
+    "Coalesce",
+    "RawSQL",
+    "execute_raw",
+]

oxyde_postgres-0.1.0/oxyde/_msgpack.py

@@ -0,0 +1,3 @@
+import msgpack  # type: ignore[import-untyped]
+
+__all__ = ["msgpack"]

oxyde_postgres-0.1.0/oxyde/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Oxyde CLI - Database migration and management tool."""
+
+# Import command modules to register them with the app (side-effect: registers commands)
+from oxyde.cli import codegen, config, migrations  # noqa: F401
+from oxyde.cli.app import app
+
+__all__ = ["app"]

oxyde_postgres-0.1.0/oxyde/cli/app.py

@@ -0,0 +1,107 @@
+"""Main CLI application and shared utilities."""
+
+from pathlib import Path
+
+import typer
+
+from oxyde.migrations.config import OxydeConfig, load_config
+
+# Main application
+app = typer.Typer(
+    name="oxyde",
+    help="Oxyde ORM - Database migration and management tool",
+    no_args_is_help=True,
+)
+
+
+def load_config_or_exit() -> OxydeConfig:
+    """Load config from oxyde_config.py or exit with error.
+
+    Returns:
+        OxydeConfig instance
+    """
+    config = load_config()
+    if config is None:
+        typer.secho(
+            "❌ No oxyde_config.py found",
+            fg=typer.colors.RED,
+        )
+        typer.echo()
+        typer.echo("Run 'oxyde init' to create configuration.")
+        raise typer.Exit(1)
+
+    if not config.models:
+        typer.secho(
+            "❌ No models configured in oxyde_config.py",
+            fg=typer.colors.RED,
+        )
+        typer.echo()
+        typer.echo("Add models to oxyde_config.py:")
+        typer.secho('  MODELS = ["models", "app.models"]', fg=typer.colors.CYAN)
+        raise typer.Exit(1)
+
+    return config
+
+
+def require_databases(config: OxydeConfig, db_alias: str = "default") -> None:
+    """Validate that databases are configured and alias exists.
+
+    Args:
+        config: OxydeConfig instance
+        db_alias: Database alias to check
+
+    Raises:
+        typer.Exit: If validation fails
+    """
+    if not config.databases:
+        typer.secho(
+            "❌ No databases configured in oxyde_config.py",
+            fg=typer.colors.RED,
+        )
+        typer.echo()
+        typer.echo("Add DATABASES to oxyde_config.py:")
+        typer.secho(
+            '  DATABASES = {"default": "postgresql://localhost/mydb"}',
+            fg=typer.colors.CYAN,
+        )
+        raise typer.Exit(1)
+
+    if db_alias not in config.databases:
+        typer.secho(
+            f"❌ Database '{db_alias}' not found in oxyde_config.py",
+            fg=typer.colors.RED,
+        )
+        typer.echo()
+        typer.echo(f"Available databases: {list(config.databases.keys())}")
+        raise typer.Exit(1)
+
+
+async def init_databases(databases: dict[str, str]) -> None:
+    """Initialize database connections from config.
+
+    Args:
+        databases: Dict mapping alias to connection URL
+    """
+    from oxyde.db import AsyncDatabase
+
+    for name, url in databases.items():
+        db = AsyncDatabase(url, name=name)
+        await db.connect()
+
+
+def ensure_migrations_dir(migrations_dir: str | Path, dry_run: bool = False) -> Path:
+    """Ensure migrations directory exists.
+
+    Args:
+        migrations_dir: Path to migrations directory
+        dry_run: If True, don't actually create directory
+
+    Returns:
+        Path to migrations directory
+    """
+    path = Path(migrations_dir)
+    if not path.exists():
+        typer.echo(f"   📁 Creating migrations directory: {path.absolute()}")
+        if not dry_run:
+            path.mkdir(parents=True, exist_ok=True)
+    return path

oxyde_postgres-0.1.0/oxyde/cli/codegen.py

@@ -0,0 +1,66 @@
+"""Code generation commands (generate-stubs)."""
+
+import typer
+
+from oxyde.cli.app import app, load_config_or_exit
+from oxyde.migrations.config import import_models
+
+
+@app.command(name="generate-stubs")
+def generate_stubs() -> None:
+    """
+    Generate .pyi stub files for all registered table models.
+
+    Creates type stub files with autocomplete support for QuerySet filter/exclude
+    methods with all field lookups (contains, gt, gte, etc.).
+    """
+    from oxyde.codegen import generate_stubs_for_models, write_stubs
+    from oxyde.models.registry import registered_tables
+
+    # Load config and import models
+    config = load_config_or_exit()
+
+    typer.echo("🔧 Generating type stubs...")
+    typer.echo()
+
+    # Import models first
+    imported = import_models(config.models)
+    if imported == 0:
+        typer.secho("❌ No modules imported", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    try:
+        # Get all registered table models
+        models = list(registered_tables().values())
+
+        if not models:
+            typer.secho("⚠️  No table models found", fg=typer.colors.YELLOW)
+            typer.echo("Make sure your models have 'class Meta: is_table = True'")
+            return
+
+        typer.echo(f"Found {len(models)} table model(s):")
+        for model in models:
+            typer.echo(f"  - {model.__module__}.{model.__name__}")
+
+        typer.echo()
+        typer.echo("Generating stubs...")
+
+        # Generate stubs
+        stub_mapping = generate_stubs_for_models(models)
+
+        # Write to disk
+        write_stubs(stub_mapping)
+
+        typer.echo()
+        typer.secho(
+            f"✅ Generated {len(stub_mapping)} stub file(s)",
+            fg=typer.colors.GREEN,
+            bold=True,
+        )
+
+    except Exception as e:
+        typer.secho(f"❌ Error generating stubs: {e}", fg=typer.colors.RED)
+        import traceback
+
+        traceback.print_exc()
+        raise typer.Exit(1)

oxyde_postgres-0.1.0/oxyde/cli/config.py

@@ -0,0 +1,84 @@
+"""Configuration commands (init)."""
+
+import typer
+
+from oxyde.cli.app import app
+from oxyde.migrations.config import load_config, save_config
+
+
+@app.command()
+def init() -> None:
+    """
+    Initialize Oxyde configuration.
+
+    Interactively asks for configuration values and creates oxyde_config.py.
+    """
+    typer.echo("🔧 Initializing Oxyde configuration...")
+    typer.echo()
+
+    # Check if config already exists
+    existing = load_config()
+    if existing:
+        typer.secho("Found existing oxyde_config.py:", fg=typer.colors.YELLOW)
+        typer.echo(f"  MODELS = {existing.models}")
+        typer.echo(f"  DIALECT = {existing.dialect}")
+        typer.echo(f"  MIGRATIONS_DIR = {existing.migrations_dir}")
+        typer.echo(f"  DATABASES = {existing.databases}")
+        typer.echo()
+        if not typer.confirm("Overwrite existing configuration?"):
+            typer.echo("Aborted.")
+            raise typer.Exit(0)
+        typer.echo()
+
+    # Ask for models
+    typer.echo("📦 Models configuration")
+    typer.echo("   Enter Python modules containing your Model classes.")
+    typer.echo("   Examples: 'models', 'app.models', 'myapp.db.models'")
+    typer.echo()
+
+    models_input = typer.prompt(
+        "   Models module(s)",
+        default="models",
+    )
+    # Parse comma or space separated list
+    models = [m.strip() for m in models_input.replace(",", " ").split() if m.strip()]
+
+    typer.echo()
+
+    dialect = "postgres"
+
+    # Ask for database URL
+    typer.echo("🔗 Database connection")
+    default_url = typer.prompt(
+        "   Database URL",
+        default="postgresql://localhost/mydb",
+    )
+
+    typer.echo()
+
+    # Ask for migrations directory
+    migrations_dir = typer.prompt(
+        "📁 Migrations directory",
+        default="migrations",
+    )
+
+    typer.echo()
+
+    # Save config
+    databases = {"default": default_url}
+    save_config(
+        models=models,
+        dialect=dialect,
+        migrations_dir=migrations_dir,
+        databases=databases,
+    )
+
+    typer.secho(
+        "✅ Configuration saved to oxyde_config.py", fg=typer.colors.GREEN, bold=True
+    )
+    typer.echo()
+    typer.echo("Next steps:")
+    typer.echo("  1. Edit oxyde_config.py to adjust settings if needed")
+    typer.echo("  2. Create your models in the specified module")
+    typer.echo("  3. Run 'oxyde makemigrations' to generate migrations")
+    typer.echo("  4. Run 'oxyde migrate' to apply migrations")