Model Definition

class SQLModel(BaseModel, metaclass=SQLModelMetaclass):
    """
    Base class for SQLModel models that combines SQLAlchemy and Pydantic functionality.
    
    Attributes:
        metadata: SQLAlchemy MetaData object for schema management
        __tablename__: Table name (can be string or callable)
        __sqlmodel_relationships__: Dictionary of relationship definitions
    """
    metadata: ClassVar[MetaData]
    __tablename__: ClassVar[Union[str, Callable[..., str]]]
    __sqlmodel_relationships__: ClassVar[Dict[str, RelationshipProperty[Any]]]
    
    @classmethod
    def model_validate(
        cls,
        obj: Any,
        *,
        strict: Union[bool, None] = None,
        from_attributes: Union[bool, None] = None,
        context: Union[Dict[str, Any], None] = None,
        update: Union[Dict[str, Any], None] = None,
    ) -> "SQLModel":
        """Validate and create a SQLModel instance from various data sources."""
    
    def model_dump(
        self,
        *,
        mode: Union[Literal["json", "python"], str] = "python",
        include: Union[IncEx, None] = None,
        exclude: Union[IncEx, None] = None,
        context: Union[Dict[str, Any], None] = None,
        by_alias: bool = False,
        exclude_unset: bool = False,
        exclude_defaults: bool = False,
        exclude_none: bool = False,
        round_trip: bool = False,
        warnings: Union[bool, Literal["none", "warn", "error"]] = True,
        serialize_as_any: bool = False,
    ) -> Dict[str, Any]:
        """Export model data as a dictionary."""
    
    def dict(
        self,
        *,
        include: Union[IncEx, None] = None,
        exclude: Union[IncEx, None] = None,
        by_alias: bool = False,
        exclude_unset: bool = False,
        exclude_defaults: bool = False,
        exclude_none: bool = False,
    ) -> Dict[str, Any]:
        """Export model data as a dictionary (Pydantic v1 compatibility)."""
    
    @classmethod
    def from_orm(cls, obj: Any, update: Optional[Dict[str, Any]] = None) -> "SQLModel":
        """Create a SQLModel instance from an ORM object (deprecated, use model_validate)."""
    
    @classmethod 
    def parse_obj(cls, obj: Any, update: Optional[Dict[str, Any]] = None) -> "SQLModel":
        """Parse object into SQLModel (deprecated, use model_validate)."""
    
    def sqlmodel_update(
        self,
        obj: Union[Dict[str, Any], BaseModel],
        *,
        update: Union[Dict[str, Any], None] = None,
    ) -> "SQLModel":
        """Update SQLModel instance with data from another object."""

class Hero(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: Optional[int] = None

# The class can be used as both a Pydantic model and SQLAlchemy table
hero = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")  # Pydantic validation
hero_dict = hero.model_dump()  # Pydantic serialization
# Also works as SQLAlchemy table for database operations

# Basic field definition (most common usage)
def Field(
    default: Any = Undefined,
    *,
    default_factory: Optional[NoArgAnyCallable] = None,
    alias: Optional[str] = None,
    title: Optional[str] = None,
    description: Optional[str] = None,
    exclude: Union[AbstractSet[Union[int, str]], Mapping[Union[int, str], Any], Any] = None,
    include: Union[AbstractSet[Union[int, str]], Mapping[Union[int, str], Any], Any] = None,
    const: Optional[bool] = None,
    gt: Optional[float] = None,
    ge: Optional[float] = None,
    lt: Optional[float] = None,
    le: Optional[float] = None,
    multiple_of: Optional[float] = None,
    max_digits: Optional[int] = None,
    decimal_places: Optional[int] = None,
    min_items: Optional[int] = None,
    max_items: Optional[int] = None,
    unique_items: Optional[bool] = None,
    min_length: Optional[int] = None,
    max_length: Optional[int] = None,
    allow_mutation: bool = True,
    regex: Optional[str] = None,
    discriminator: Optional[str] = None,
    repr: bool = True,
    primary_key: Union[bool, UndefinedType] = Undefined,
    foreign_key: Any = Undefined,
    unique: Union[bool, UndefinedType] = Undefined,
    nullable: Union[bool, UndefinedType] = Undefined,
    index: Union[bool, UndefinedType] = Undefined,
    sa_type: Union[Type[Any], UndefinedType] = Undefined,
    sa_column_args: Union[Sequence[Any], UndefinedType] = Undefined,
    sa_column_kwargs: Union[Mapping[str, Any], UndefinedType] = Undefined,
    schema_extra: Optional[Dict[str, Any]] = None,
) -> Any: ...

# Foreign key field definition (with ondelete support)
def Field(
    default: Any = Undefined,
    *,
    default_factory: Optional[NoArgAnyCallable] = None,
    alias: Optional[str] = None,
    title: Optional[str] = None,
    description: Optional[str] = None,
    exclude: Union[AbstractSet[Union[int, str]], Mapping[Union[int, str], Any], Any] = None,
    include: Union[AbstractSet[Union[int, str]], Mapping[Union[int, str], Any], Any] = None,
    const: Optional[bool] = None,
    gt: Optional[float] = None,
    ge: Optional[float] = None,
    lt: Optional[float] = None,
    le: Optional[float] = None,
    multiple_of: Optional[float] = None,
    max_digits: Optional[int] = None,
    decimal_places: Optional[int] = None,
    min_items: Optional[int] = None,
    max_items: Optional[int] = None,
    unique_items: Optional[bool] = None,
    min_length: Optional[int] = None,
    max_length: Optional[int] = None,
    allow_mutation: bool = True,
    regex: Optional[str] = None,
    discriminator: Optional[str] = None,
    repr: bool = True,
    primary_key: Union[bool, UndefinedType] = Undefined,
    foreign_key: str,
    ondelete: Union[OnDeleteType, UndefinedType] = Undefined,
    unique: Union[bool, UndefinedType] = Undefined,
    nullable: Union[bool, UndefinedType] = Undefined,
    index: Union[bool, UndefinedType] = Undefined,
    sa_type: Union[Type[Any], UndefinedType] = Undefined,
    sa_column_args: Union[Sequence[Any], UndefinedType] = Undefined,
    sa_column_kwargs: Union[Mapping[str, Any], UndefinedType] = Undefined,
    schema_extra: Optional[Dict[str, Any]] = None,
) -> Any:
    """
    Define a field with both Pydantic validation and SQLAlchemy column properties.
    
    Parameters:
        default: Default value for the field
        default_factory: Function to generate default values
        alias: Alternative name for serialization
        title: Human-readable field title
        description: Field description
        
        # Pydantic validation parameters
        gt, ge, lt, le: Numeric comparison validators
        min_length, max_length: String/sequence length validators
        regex: Regular expression validator
        
        # SQLAlchemy column parameters  
        primary_key: Whether this field is a primary key
        foreign_key: Foreign key reference (table.column format)
        ondelete: Foreign key on-delete behavior
        unique: Whether values must be unique
        nullable: Whether NULL values are allowed
        index: Whether to create an index
        sa_type: Explicit SQLAlchemy type
        sa_column: Pre-configured SQLAlchemy Column object
        sa_column_args: Additional positional args for Column
        sa_column_kwargs: Additional keyword args for Column
    
    Returns:
        FieldInfo object with combined Pydantic and SQLAlchemy configuration
    """

class User(SQLModel, table=True):
    # Primary key field
    id: Optional[int] = Field(default=None, primary_key=True)
    
    # Required string with validation
    username: str = Field(min_length=3, max_length=50, unique=True)
    
    # Optional field with database index
    email: Optional[str] = Field(default=None, index=True)
    
    # Foreign key field
    team_id: Optional[int] = Field(default=None, foreign_key="team.id", ondelete="SET NULL")
    
    # Field with custom SQLAlchemy type
    status: str = Field(sa_type=VARCHAR(20), default="active")

def Relationship(
    *,
    back_populates: Optional[str] = None,
    cascade_delete: Optional[bool] = False,
    passive_deletes: Optional[Union[bool, Literal["all"]]] = False,
    link_model: Optional[Any] = None,
    sa_relationship: Optional[RelationshipProperty[Any]] = None,
    sa_relationship_args: Optional[Sequence[Any]] = None,
    sa_relationship_kwargs: Optional[Mapping[str, Any]] = None,
) -> Any:
    """
    Define relationships between SQLModel models.
    
    Parameters:
        back_populates: Name of the reverse relationship attribute
        cascade_delete: Whether to cascade delete operations
        passive_deletes: How to handle deletes (True, False, or "all")
        link_model: Model class for many-to-many relationships
        sa_relationship: Pre-configured SQLAlchemy relationship
        sa_relationship_args: Additional positional args for relationship
        sa_relationship_kwargs: Additional keyword args for relationship
    
    Returns:
        RelationshipInfo object with relationship configuration
    """

class Team(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str
    
    # One-to-many relationship
    heroes: List["Hero"] = Relationship(back_populates="team")

class Hero(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str
    team_id: Optional[int] = Field(default=None, foreign_key="team.id")
    
    # Many-to-one relationship
    team: Optional[Team] = Relationship(back_populates="heroes")

# Many-to-many with link model
class HeroTeamLink(SQLModel, table=True):
    team_id: Optional[int] = Field(default=None, foreign_key="team.id", primary_key=True)
    hero_id: Optional[int] = Field(default=None, foreign_key="hero.id", primary_key=True)

class Hero(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str
    
    teams: List[Team] = Relationship(back_populates="heroes", link_model=HeroTeamLink)

class FieldInfo(PydanticFieldInfo):
    """
    Extended FieldInfo with SQLAlchemy-specific attributes.
    
    Attributes:
        primary_key: Whether this is a primary key field
        nullable: Whether NULL values are allowed
        foreign_key: Foreign key reference
        ondelete: Foreign key on-delete behavior
        unique: Whether values must be unique
        index: Whether to create an index
        sa_type: SQLAlchemy type override
        sa_column: Pre-configured Column object
        sa_column_args: Additional Column positional arguments
        sa_column_kwargs: Additional Column keyword arguments
    """
    primary_key: bool
    nullable: Union[bool, UndefinedType]
    foreign_key: Any
    ondelete: Union[OnDeleteType, UndefinedType]
    unique: Union[bool, UndefinedType]
    index: Union[bool, UndefinedType]
    sa_type: Union[Type[Any], UndefinedType]
    sa_column: Union[Column, UndefinedType]
    sa_column_args: Union[Sequence[Any], UndefinedType]
    sa_column_kwargs: Union[Mapping[str, Any], UndefinedType]

class RelationshipInfo:
    """
    Information class for relationship configuration.
    
    Attributes:
        back_populates: Name of the reverse relationship
        cascade_delete: Whether to cascade deletes
        passive_deletes: Passive delete handling
        link_model: Model for many-to-many relationships
        sa_relationship: Pre-configured relationship
        sa_relationship_args: Additional relationship args
        sa_relationship_kwargs: Additional relationship kwargs
    """
    back_populates: Optional[str]
    cascade_delete: bool
    passive_deletes: Union[bool, Literal["all"]]
    link_model: Optional[Any]
    sa_relationship: Optional[RelationshipProperty[Any]]
    sa_relationship_args: Optional[Sequence[Any]]
    sa_relationship_kwargs: Optional[Mapping[str, Any]]

class SQLModelMetaclass(ModelMetaclass, DeclarativeMeta):
    """
    Metaclass that combines Pydantic ModelMetaclass and SQLAlchemy DeclarativeMeta.
    
    This metaclass enables SQLModel classes to work as both Pydantic models
    and SQLAlchemy table models simultaneously.
    """
    __sqlmodel_relationships__: Dict[str, RelationshipInfo]
    model_config: SQLModelConfig
    model_fields: Dict[str, FieldInfo]

UndefinedType = type(None)  # Placeholder for undefined values
Undefined: UndefinedType  # Singleton undefined value

OnDeleteType = Literal["CASCADE", "SET NULL", "RESTRICT"]  # Foreign key delete actions

NoArgAnyCallable = Callable[[], Any]  # Callable with no arguments returning Any

IncEx = Union[
    Set[int],
    Set[str],
    Mapping[int, Union["IncEx", bool]],
    Mapping[str, Union["IncEx", bool]],
]  # Include/exclude type for model serialization