sqlobjects 1.0.7__tar.gz → 1.0.9__tar.gz

{sqlobjects-1.0.7/sqlobjects.egg-info → sqlobjects-1.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.0.7
+Version: 1.0.9
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{sqlobjects-1.0.7 → sqlobjects-1.0.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.0.7"
+version = "1.0.9"
 description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
 readme = "README.md"
 license = { text = "MIT" }

{sqlobjects-1.0.7 → sqlobjects-1.0.9}/sqlobjects/database/manager.py

@@ -174,37 +174,49 @@ class Database:
 
         return event.listens_for(target, event_name)
 
-    async def create_tables(self, base_class) -> None:
-        """Create all tables defined in the model registry of SQLObjects base class
+    async def create_tables(self, base_class, tables: list[type] | None = None) -> None:
+        """Create tables defined in the model registry of SQLObjects base class
 
-        Creates all tables, indexes, and constraints defined in the provided
+        Creates tables, indexes, and constraints defined in the provided
         SQLAlchemy metadata object using the database engine.
 
         Args:
             base_class: SQLObjects base class containing model registry
+            tables: List of model classes to create tables for, creates all if None
 
         Examples:
             >>> from sqlobjects.base import ObjectModel
-            >>> await db.create_tables(ObjectModel)
+            >>> await db.create_tables(ObjectModel)  # Create all tables
+            >>> await db.create_tables(ObjectModel, [User, Post])  # Create specific tables
         """
         async with self.engine.begin() as conn:
-            await conn.run_sync(base_class.__registry__.create_all)
+            if tables is None:
+                await conn.run_sync(base_class.__registry__.create_all)
+            else:
+                table_objects = [model.__table__ for model in tables]
+                await conn.run_sync(base_class.__registry__.create_all, tables=table_objects)
 
-    async def drop_tables(self, base_class) -> None:
-        """Drop all tables defined in the model registry of SQLObjects base class
+    async def drop_tables(self, base_class, tables: list[type] | None = None) -> None:
+        """Drop tables defined in the model registry of SQLObjects base class
 
-        Drops all tables, indexes, and constraints defined in the provided
+        Drops tables, indexes, and constraints defined in the provided
         SQLAlchemy metadata object from the database.
 
         Args:
             base_class: SQLObjects base class containing model registry
+            tables: List of model classes to drop tables for, drops all if None
 
         Examples:
             >>> from sqlobjects.base import ObjectModel
-            >>> await db.drop_tables(ObjectModel)
+            >>> await db.drop_tables(ObjectModel)  # Drop all tables
+            >>> await db.drop_tables(ObjectModel, [User, Post])  # Drop specific tables
         """
         async with self.engine.begin() as conn:
-            await conn.run_sync(base_class.__registry__.drop_all)
+            if tables is None:
+                await conn.run_sync(base_class.__registry__.drop_all)
+            else:
+                table_objects = [model.__table__ for model in tables]
+                await conn.run_sync(base_class.__registry__.drop_all, tables=table_objects)
 
     async def disconnect(self) -> None:
         """Disconnect database and clean up resources
@@ -286,15 +298,16 @@ class _DatabaseManager:
         return database.engine
 
     @classmethod
-    async def create_tables(cls, base_class, db_name: str | None = None) -> None:
-        """Create all tables defined in the base class registry
+    async def create_tables(cls, base_class, db_name: str | None = None, tables: list[type] | None = None) -> None:
+        """Create tables defined in the base class registry
 
-        Creates all tables, indexes, and constraints for models registered
+        Creates tables, indexes, and constraints for models registered
         in the base class registry using the specified database connection.
 
         Args:
             base_class: SQLObjects base class containing model registry
             db_name: Database name to use, uses default database if None
+            tables: List of model classes to create tables for, creates all if None
 
         Raises:
             ValueError: When specified database does not exist
@@ -303,20 +316,22 @@ class _DatabaseManager:
             >>> from sqlobjects.base import ObjectModel
             >>> await DatabaseManager.create_tables(ObjectModel)
             >>> await DatabaseManager.create_tables(ObjectModel, "analytics")
+            >>> await DatabaseManager.create_tables(ObjectModel, tables=[User, Post])
         """
         database = cls.get_database(db_name)
-        await database.create_tables(base_class)
+        await database.create_tables(base_class, tables)
 
     @classmethod
-    async def drop_tables(cls, base_class, db_name: str | None = None) -> None:
-        """Drop all tables defined in the base class registry
+    async def drop_tables(cls, base_class, db_name: str | None = None, tables: list[type] | None = None) -> None:
+        """Drop tables defined in the base class registry
 
-        Drops all tables, indexes, and constraints for models registered
+        Drops tables, indexes, and constraints for models registered
         in the base class registry from the specified database connection.
 
         Args:
             base_class: SQLObjects base class containing model registry
             db_name: Database name to use, uses default database if None
+            tables: List of model classes to drop tables for, drops all if None
 
         Raises:
             ValueError: When specified database does not exist
@@ -325,9 +340,10 @@ class _DatabaseManager:
             >>> from sqlobjects.base import ObjectModel
             >>> await DatabaseManager.drop_tables(ObjectModel)
             >>> await DatabaseManager.drop_tables(ObjectModel, "analytics")
+            >>> await DatabaseManager.drop_tables(ObjectModel, tables=[User, Post])
         """
         database = cls.get_database(db_name)
-        await database.drop_tables(base_class)
+        await database.drop_tables(base_class, tables)
 
     @classmethod
     async def close(cls, db_name: str | None = None, auto_default: bool = False) -> None:
@@ -476,36 +492,48 @@ async def init_dbs(
     return tuple(db_instances)
 
 
-async def create_tables(base_class, db_name: str | None = None) -> None:
-    """Create all tables defined in the base class registry
+async def create_tables(base_class, db_name: str | None = None, tables: list[type] | None = None) -> None:
+    """Create tables defined in the base class registry
 
-    Creates all tables, indexes, and constraints for models registered
+    Creates tables, indexes, and constraints for models registered
     in the base class registry using the specified database connection.
 
     Args:
         base_class: SQLObjects base class containing model registry
         db_name: Name of the database, uses default if None
+        tables: List of model classes to create tables for, creates all if None
 
     Raises:
         ValueError: When specified database does not exist
+
+    Examples:
+        >>> from sqlobjects.model import ObjectModel
+        >>> await create_tables(ObjectModel)  # Create all tables
+        >>> await create_tables(ObjectModel, tables=[User, Post])  # Create specific tables
     """
-    await _DatabaseManager.create_tables(base_class, db_name)
+    await _DatabaseManager.create_tables(base_class, db_name, tables)
 
 
-async def drop_tables(base_class, db_name: str | None = None) -> None:
-    """Drop all tables defined in the base class registry
+async def drop_tables(base_class, db_name: str | None = None, tables: list[type] | None = None) -> None:
+    """Drop tables defined in the base class registry
 
-    Drops all tables, indexes, and constraints for models registered
+    Drops tables, indexes, and constraints for models registered
     in the base class registry from the specified database connection.
 
     Args:
         base_class: SQLObjects base class containing model registry
         db_name: Name of the database, uses default if None
+        tables: List of model classes to drop tables for, drops all if None
 
     Raises:
         ValueError: When specified database does not exist
+
+    Examples:
+        >>> from sqlobjects.model import ObjectModel
+        >>> await drop_tables(ObjectModel)  # Drop all tables
+        >>> await drop_tables(ObjectModel, tables=[User, Post])  # Drop specific tables
     """
-    await _DatabaseManager.drop_tables(base_class, db_name)
+    await _DatabaseManager.drop_tables(base_class, db_name, tables)
 
 
 async def close_db(db_name: str | None = None, auto_default: bool = False) -> None:

{sqlobjects-1.0.7 → sqlobjects-1.0.9}/sqlobjects/fields/__init__.py

@@ -1,6 +1,12 @@
-from .core import Column, ColumnAttribute, column
+from .core import Column, ColumnAttribute, Related, column
 from .functions import computed, foreign_key, identity
-from .proxies import DeferredFieldProxy, RelationFieldProxy
+from .proxies import (
+    # Backward compatibility aliases
+    DeferredObject,
+    ManyToManyRelation,
+    OneToManyRelation,
+    RelatedObject,
+)
 from .relations import M2MTable, relationship
 from .shortcuts import (
     ArrayColumn,
@@ -25,6 +31,7 @@ __all__ = [
     # Core field system
     "Column",
     "ColumnAttribute",
+    "Related",
     "column",
     # Shortcut field classes
     "StringColumn",
@@ -48,9 +55,11 @@ __all__ = [
     # Relationship system
     "M2MTable",
     "relationship",
-    # Proxy system
-    "DeferredFieldProxy",
-    "RelationFieldProxy",
+    # Public proxy interfaces
+    "DeferredObject",
+    "RelatedObject",
+    "OneToManyRelation",
+    "ManyToManyRelation",
     # Utility functions
     "extract_field_metadata",
     "get_deferred_fields",

{sqlobjects-1.0.7 → sqlobjects-1.0.9}/sqlobjects/fields/core.py

@@ -1,21 +1,112 @@
 """Core field classes for SQLObjects"""
 
 from collections.abc import Callable
-from typing import Any, Generic, TypeVar, Union, cast, get_args, get_origin, overload
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, Union, cast, get_args, get_origin, overload
 
 from sqlalchemy import Column as CoreColumn
 from sqlalchemy import ForeignKey
 from sqlalchemy.sql.elements import ColumnElement
 
+from sqlobjects.fields.proxies import RelatedCollection, RelatedObject
+
 from ..cascade import OnDelete
 from ..expressions.mixins import ColumnAttributeFunctionMixin
 from .types import create_type_instance
 
 
+if TYPE_CHECKING:
+    pass
+
+
 T = TypeVar("T")
 NullableT = TypeVar("NullableT")
 
 
+class Related(Generic[T]):
+    """Relationship field container - returns appropriate relationship proxy.
+
+    This class serves as a type container for relationship fields, providing
+    clear type hints while delegating actual behavior to RelationshipDescriptor.
+
+    Type Parameters:
+        T: The related model type (single object or list)
+
+    Example:
+        >>> class User(ObjectModel):
+        ...     posts: Related[list["Post"]] = relationship("Post")
+        ...     profile: Related["Profile"] = relationship("Profile", uselist=False)
+    """
+
+    def __init__(self, **params):
+        """Initialize relationship field container.
+
+        Args:
+            **params: Relationship configuration parameters
+        """
+        self._params = params
+        self._is_relationship = True
+        self._relationship_descriptor = None
+        self.name = None
+
+    def __set_name__(self, owner, name):
+        """Set field name and create relationship descriptor.
+
+        Args:
+            owner: The model class that owns this field
+            name: The field name
+        """
+        self.name = name
+        self._setup_relationship(owner, name)
+
+    def _setup_relationship(self, owner, name):
+        """Set up relationship field descriptor.
+
+        Args:
+            owner: The model class that owns this field
+            name: The field name
+        """
+        from .relations.descriptors import RelationshipDescriptor
+
+        relationship_property = self._params.get("relationship_property")
+        if relationship_property:
+            # Set M2M definition if provided
+            m2m_def = self._params.get("m2m_definition")
+            if m2m_def:
+                relationship_property.m2m_definition = m2m_def
+                relationship_property.is_many_to_many = True
+
+            self._relationship_descriptor = RelationshipDescriptor(relationship_property)
+            self._relationship_descriptor.__set_name__(owner, name)
+
+    @overload
+    def __get__(self, instance: None, owner: type) -> "Related[T]": ...
+
+    @overload
+    def __get__(self: "Related[list[Any]]", instance: Any, owner: type) -> "RelatedCollection[Any]": ...
+
+    @overload
+    def __get__(self, instance: Any, owner: type) -> "RelatedObject[T]": ...
+
+    def __get__(self, instance, owner) -> "Related[T] | RelatedCollection[Any] | RelatedObject[T] | None":
+        """Fallback descriptor - should not be called in normal usage.
+
+        ModelProcessor metaclass extracts RelationshipDescriptor and replaces
+        this Related instance, so this method is only called if setup fails.
+
+        Args:
+            instance: Model instance or None for class access
+            owner: The model class
+
+        Returns:
+            RelationshipDescriptor or None as fallback
+        """
+        if self._relationship_descriptor:
+            return self._relationship_descriptor.__get__(instance, owner)
+        if instance is None:
+            return self
+        return None
+
+
 class Column(Generic[T]):
     """Field descriptor for parameter collection and ColumnAttribute creation.
 
@@ -56,11 +147,10 @@ class Column(Generic[T]):
         self._private_name = None
 
     def __set_name__(self, owner, name):
-        """Set field name and initialize appropriate descriptor.
+        """Set field name and initialize column descriptor.
 
         Called automatically by Python when the field is assigned to a class.
-        Creates either a ColumnAttribute for database fields or a relationship
-        descriptor for relationship fields.
+        Creates ColumnAttribute for database fields.
 
         Args:
             owner: The model class that owns this field
@@ -68,25 +158,7 @@ class Column(Generic[T]):
         """
         self.name = name
         self._private_name = f"_{name}"
-
-        if self._is_relationship:
-            self._setup_relationship(owner, name)
-        else:
-            self._setup_column(owner, name)
-
-    def _setup_relationship(self, owner, name):
-        """Set up relationship field descriptor.
-
-        Args:
-            owner: The model class that owns this field
-            name: The field name
-        """
-        from .relations.descriptors import RelationshipDescriptor
-
-        relationship_property = self._params.get("relationship_property")
-        if relationship_property:
-            self._relationship_descriptor = RelationshipDescriptor(relationship_property)
-            self._relationship_descriptor.__set_name__(owner, name)
+        self._setup_column(owner, name)
 
     def _setup_column(self, owner, name):
         """Set up database column field.
@@ -197,9 +269,6 @@ class Column(Generic[T]):
         Returns:
             ColumnAttribute when accessed on class, field value when accessed on instance
         """
-        if self._is_relationship and self._relationship_descriptor:
-            return self._relationship_descriptor.__get__(instance, owner)
-
         if instance is None:
             return self._column_attribute
         else:
@@ -221,14 +290,10 @@ class Column(Generic[T]):
         Raises:
             AttributeError: If trying to set value on class rather than instance
         """
-        if self._is_relationship:
-            # Relationship fields may not support direct setting
-            pass
-        else:
-            if instance is None:
-                raise AttributeError("Cannot set attribute on class")
-            private_name = self._private_name or f"_{self.name}"
-            setattr(instance, private_name, value)
+        if instance is None:
+            raise AttributeError("Cannot set attribute on class")
+        private_name = self._private_name or f"_{self.name}"
+        setattr(instance, private_name, value)
 
 
 class ColumnAttribute(ColumnAttributeFunctionMixin, Generic[T]):