ForeignKey class

edgy.fields.ForeignKey

Bases: ForeignKeyFieldFactory, cast(Any, object)

A factory for creating ForeignKey fields in Edgy models.

This factory extends ForeignKeyFieldFactory to provide a convenient interface for defining foreign key relationships. It ensures that specific server-side default and update operations are not mistakenly applied to foreign key fields, and validates the embed_parent configuration.

methods_overwritable_by_factory class-attribute instance-attribute

methods_overwritable_by_factory = frozenset(default_methods_overwritable_by_factory)

field_bases class-attribute instance-attribute

field_bases = (BaseForeignKeyField,)

build_field classmethod

build_field(**kwargs)

Constructs and returns a new field instance based on the factory's configuration.

This method orchestrates the creation of a BaseFieldType instance. It determines the column type, Pydantic type, and constraints from the provided kwargs and the factory's properties. It then instantiates the field and calls overwrite_methods to apply any factory-defined method overrides.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments for configuring the field. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
BaseFieldType	The newly constructed and configured field instance. TYPE: BaseFieldType

Source code in edgy/core/db/fields/factories.py

@classmethod
def build_field(cls, **kwargs: Any) -> BaseFieldType:
    """
    Constructs and returns a new field instance based on the factory's configuration.

    This method orchestrates the creation of a `BaseFieldType` instance.
    It determines the column type, Pydantic type, and constraints from the
    provided `kwargs` and the factory's properties. It then instantiates
    the field and calls `overwrite_methods` to apply any factory-defined
    method overrides.

    Args:
        **kwargs (Any): Keyword arguments for configuring the field.

    Returns:
        BaseFieldType: The newly constructed and configured field instance.
    """
    column_type = cls.get_column_type(kwargs)
    pydantic_type = cls.get_pydantic_type(kwargs)
    constraints = cls.get_constraints(kwargs)

    # Get the dynamically generated field class.
    new_field = cls._get_field_cls(cls)

    # Instantiate the new field with all relevant properties.
    new_field_obj: BaseFieldType = new_field(  # type: ignore
        field_type=pydantic_type,
        annotation=pydantic_type,
        column_type=column_type,
        constraints=constraints,
        factory=cls,  # Store a reference to the factory itself.
        **kwargs,
    )
    # Apply any methods from the factory that should override the field's methods.
    cls.overwrite_methods(new_field_obj)
    return new_field_obj

overwrite_methods classmethod

overwrite_methods(field_obj)

Overwrites methods on the given field_obj with methods defined in the factory.

This method iterates through the factory's own methods. If a method's name is present in methods_overwritable_by_factory, it replaces the corresponding method on the field_obj. It handles class methods and ensures proper staticmethod wrapping for consistent behavior across Python versions.

PARAMETER	DESCRIPTION
field_obj	The field instance whose methods are to be overwritten. TYPE: BaseFieldType

Source code in edgy/core/db/fields/factories.py

@classmethod
def overwrite_methods(cls, field_obj: BaseFieldType) -> None:
    """
    Overwrites methods on the given `field_obj` with methods defined in the factory.

    This method iterates through the factory's own methods. If a method's name
    is present in `methods_overwritable_by_factory`, it replaces the corresponding
    method on the `field_obj`. It handles class methods and ensures proper
    `staticmethod` wrapping for consistent behavior across Python versions.

    Args:
        field_obj (BaseFieldType): The field instance whose methods are to be
                                   overwritten.
    """
    for key in dir(cls):
        # Check if the method is intended to be overwritten and exists in the factory.
        if key in cls.methods_overwritable_by_factory and hasattr(cls, key):
            fn = getattr(cls, key)
            original_fn = getattr(field_obj, key, None)
            # Unwrap the function if it's a method wrapper.
            if hasattr(fn, "__func__"):
                fn = fn.__func__

            # Set the method on the field_obj, binding it with partial to preserve
            # `cls` and `field_obj` context, and making it a static method.
            setattr(
                field_obj,
                key,
                # .__func__ is a workaround for python < 3.10, python >=3.10 works without
                staticmethod(partial(fn, cls, field_obj, original_fn=original_fn)).__func__,
            )

repack classmethod

repack(field_obj)

Repacks methods on the given field_obj that were previously overwritten by the factory.

This method is used to re-apply the partial and staticmethod wrappers to methods that were already overwritten. This can be necessary in scenarios where field objects are serialized/deserialized or otherwise lose their original method bindings. It ensures that the context (cls, field_obj) remains correctly bound.

PARAMETER	DESCRIPTION
field_obj	The field instance whose methods are to be repacked. TYPE: BaseFieldType

Source code in edgy/core/db/fields/factories.py

@classmethod
def repack(cls, field_obj: BaseFieldType) -> None:
    """
    Repacks methods on the given `field_obj` that were previously overwritten
    by the factory.

    This method is used to re-apply the `partial` and `staticmethod` wrappers
    to methods that were already overwritten. This can be necessary in scenarios
    where field objects are serialized/deserialized or otherwise lose their
    original method bindings. It ensures that the context (`cls`, `field_obj`)
    remains correctly bound.

    Args:
        field_obj (BaseFieldType): The field instance whose methods are to be repacked.
    """
    for key in dir(cls):
        # Check if the method is intended to be overwritten and exists in the factory.
        if key in cls.methods_overwritable_by_factory and hasattr(cls, key):
            packed_fn = getattr(field_obj, key, None)
            # If the method exists and has a `func` attribute (indicating a partial function).
            if packed_fn is not None and hasattr(packed_fn, "func"):
                # Reapply the staticmethod and partial binding.
                setattr(
                    field_obj,
                    key,
                    # .__func__ is a workaround for python < 3.10, python >=3.10 works without
                    staticmethod(
                        partial(packed_fn.func, cls, field_obj, **packed_fn.keywords)
                    ).__func__,
                )

get_constraints classmethod

get_constraints(kwargs)

Returns a sequence of constraints applicable to the column.

This method can be overridden by subclasses to provide specific database constraints for the column associated with this field type.

PARAMETER	DESCRIPTION
kwargs	Keyword arguments provided during field creation. TYPE: dict[str, Any]

RETURNS	DESCRIPTION
Sequence[Any]	Sequence[Any]: A sequence of constraint objects.

Source code in edgy/core/db/fields/factories.py

@classmethod
def get_constraints(cls, kwargs: dict[str, Any]) -> Sequence[Any]:
    """
    Returns a sequence of constraints applicable to the column.

    This method can be overridden by subclasses to provide specific database
    constraints for the column associated with this field type.

    Args:
        kwargs (dict[str, Any]): Keyword arguments provided during field creation.

    Returns:
        Sequence[Any]: A sequence of constraint objects.
    """
    return []

get_column_type classmethod

get_column_type(kwargs)

Returns the SQL column type for the field.

For regular fields, this will return the appropriate SQLAlchemy column type. For meta fields (fields that don't directly map to a database column), it should return None.

PARAMETER	DESCRIPTION
kwargs	Keyword arguments provided during field creation. TYPE: dict[str, Any]

RETURNS	DESCRIPTION
Any	The SQLAlchemy column type or None if it's a meta field. TYPE: Any

Source code in edgy/core/db/fields/factories.py

@classmethod
def get_column_type(cls, kwargs: dict[str, Any]) -> Any:
    """
    Returns the SQL column type for the field.

    For regular fields, this will return the appropriate SQLAlchemy column type.
    For meta fields (fields that don't directly map to a database column),
    it should return `None`.

    Args:
        kwargs (dict[str, Any]): Keyword arguments provided during field creation.

    Returns:
        Any: The SQLAlchemy column type or `None` if it's a meta field.
    """
    return None

get_pydantic_type classmethod

get_pydantic_type(kwargs)

Returns the Pydantic type for the field.

This type is used by Pydantic for validation and serialization. By default, it returns the field_type attribute of the factory.

PARAMETER	DESCRIPTION
kwargs	Keyword arguments provided during field creation. TYPE: dict[str, Any]

RETURNS	DESCRIPTION
Any	The Pydantic type associated with the field. TYPE: Any

Source code in edgy/core/db/fields/factories.py

@classmethod
def get_pydantic_type(cls, kwargs: dict[str, Any]) -> Any:
    """
    Returns the Pydantic type for the field.

    This type is used by Pydantic for validation and serialization. By default,
    it returns the `field_type` attribute of the factory.

    Args:
        kwargs (dict[str, Any]): Keyword arguments provided during field creation.

    Returns:
        Any: The Pydantic type associated with the field.
    """
    return cls.field_type

_get_field_cls cached staticmethod

_get_field_cls()

Internal static method to dynamically create and cache the actual field class.

This method uses lru_cache to ensure that the field class is created only once for each FieldFactory type. It constructs a new type based on the FieldFactory's __name__ and field_bases.

PARAMETER	DESCRIPTION
cls	The FieldFactory instance itself. TYPE: FieldFactory

RETURNS	DESCRIPTION
BaseFieldType	The dynamically created and cached field class. TYPE: BaseFieldType

Source code in edgy/core/db/fields/factories.py

@staticmethod
@lru_cache(None)
def _get_field_cls(cls: FieldFactory) -> BaseFieldType:
    """
    Internal static method to dynamically create and cache the actual field class.

    This method uses `lru_cache` to ensure that the field class is created
    only once for each `FieldFactory` type. It constructs a new type based
    on the `FieldFactory`'s `__name__` and `field_bases`.

    Args:
        cls (FieldFactory): The `FieldFactory` instance itself.

    Returns:
        BaseFieldType: The dynamically created and cached field class.
    """
    # Dynamically create a new type based on the factory's name and specified field bases.
    return cast(BaseFieldType, type(cls.__name__, cast(Any, cls.field_bases), {}))

__new__

__new__(to, **kwargs)

Creates a new ForeignKey field instance.

This method primarily passes the to argument (target model) and other kwargs to the parent ForeignKeyFieldFactory for field construction.

PARAMETER	DESCRIPTION
to	The target model class or its string name to which this foreign key points. TYPE: type[BaseModelType] | str
**kwargs	Additional keyword arguments for the foreign key field. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
BaseFieldType	The constructed ForeignKey field instance. TYPE: BaseFieldType

Source code in edgy/core/db/fields/foreign_keys.py

def __new__(
    cls,
    to: type[BaseModelType] | str,
    **kwargs: Any,
) -> BaseFieldType:
    """
    Creates a new `ForeignKey` field instance.

    This method primarily passes the `to` argument (target model) and other
    `kwargs` to the parent `ForeignKeyFieldFactory` for field construction.

    Args:
        to (type[BaseModelType] | str): The target model class or its string name
                                      to which this foreign key points.
        **kwargs (Any): Additional keyword arguments for the foreign key field.

    Returns:
        BaseFieldType: The constructed `ForeignKey` field instance.
    """
    return super().__new__(cls, to=to, **kwargs)

validate classmethod

validate(kwargs)

Validates the parameters for a ForeignKey field.

This method overrides the parent validate method to enforce rules specific to foreign keys. It explicitly disallows auto_compute_server_default, server_default, and server_onupdate to prevent issues with relational integrity. It also validates the format of the embed_parent argument.

PARAMETER	DESCRIPTION
kwargs	The dictionary of keyword arguments passed during field construction. TYPE: dict[str, Any]

RAISES	DESCRIPTION
FieldDefinitionError	If any validation rule is violated.

Source code in edgy/core/db/fields/foreign_keys.py

@classmethod
def validate(cls, kwargs: dict[str, Any]) -> None:
    """
    Validates the parameters for a `ForeignKey` field.

    This method overrides the parent `validate` method to enforce rules
    specific to foreign keys. It explicitly disallows `auto_compute_server_default`,
    `server_default`, and `server_onupdate` to prevent issues with relational
    integrity. It also validates the format of the `embed_parent` argument.

    Args:
        kwargs (dict[str, Any]): The dictionary of keyword arguments passed
                                 during field construction.

    Raises:
        FieldDefinitionError: If any validation rule is violated.
    """
    super().validate(kwargs)
    # Disallow auto_compute_server_default for ForeignKeys.
    if kwargs.get("auto_compute_server_default"):
        raise FieldDefinitionError(
            '"auto_compute_server_default" is not supported for ForeignKey.'
        ) from None
    kwargs["auto_compute_server_default"] = False  # Explicitly set to False.
    # Disallow server_default for ForeignKeys.
    if kwargs.get("server_default"):
        raise FieldDefinitionError(
            '"server_default" is not supported for ForeignKey.'
        ) from None
    # Disallow server_onupdate for ForeignKeys.
    if kwargs.get("server_onupdate"):
        raise FieldDefinitionError(
            '"server_onupdate" is not supported for ForeignKey.'
        ) from None
    # Validate embed_parent argument format.
    embed_parent = kwargs.get("embed_parent")
    if embed_parent and "__" in embed_parent[1]:
        raise FieldDefinitionError(
            '"embed_parent" second argument (for embedding parent) cannot contain "__".'
        )