ormar/docs/api/fields/foreign-key.md

fields.foreign_key

create_dummy_instance

create_dummy_instance(fk: Type["Model"], pk: Any = None) -> "Model"

Ormar never returns you a raw data. So if you have a related field that has a value populated it will construct you a Model instance out of it.

Creates a "fake" instance of passed Model from pk value. The instantiated Model has only pk value filled. To achieve this pk_only flag has to be passed as it skips the validation.

If the nested related Models are required they are set with -1 as pk value.

Arguments:

• fk (Model class): class of the related Model to which instance should be constructed
• pk (Any): value of the primary_key column

Returns:

(Model): Model instance populated with only pk

create_dummy_model

create_dummy_model(base_model: Type["Model"], pk_field: Type[Union[BaseField, "ForeignKeyField", "ManyToManyField"]]) -> Type["BaseModel"]

Used to construct a dummy pydantic model for type hints and pydantic validation. Populates only pk field and set it to desired type.

Arguments:

• base_model (Model class): class of target dummy model
• pk_field (Type[Union[BaseField, "ForeignKeyField", "ManyToManyField"]]): ormar Field to be set on pydantic Model

Returns:

(pydantic.BaseModel): constructed dummy model

UniqueColumns Objects

class UniqueColumns(UniqueConstraint)

Subclass of sqlalchemy.UniqueConstraint. Used to avoid importing anything from sqlalchemy by user.

ForeignKeyConstraint Objects

@dataclass
class ForeignKeyConstraint()

Internal container to store ForeignKey definitions used later to produce sqlalchemy.ForeignKeys

name

ondelete

onupdate

ForeignKey

ForeignKey(to: Type["Model"], *, name: str = None, unique: bool = False, nullable: bool = True, related_name: str = None, virtual: bool = False, onupdate: str = None, ondelete: str = None, **kwargs: Any, ,) -> Any

Despite a name it's a function that returns constructed ForeignKeyField. This function is actually used in model declaration (as ormar.ForeignKey(ToModel)).

Accepts number of relation setting parameters as well as all BaseField ones.

Arguments:

• to (Model class): target related ormar Model
• name (str): name of the database field - later called alias
• unique (bool): parameter passed to sqlalchemy.ForeignKey, unique flag
• nullable (bool): marks field as optional/ required
• related_name (str): name of reversed FK relation populated for you on to model
• virtual (bool): marks if relation is virtual. It is for reversed FK and auto generated FK on through model in Many2Many relations.
• onupdate (str): parameter passed to sqlalchemy.ForeignKey. How to treat child rows on update of parent (the one where FK is defined) model.
• ondelete (str): parameter passed to sqlalchemy.ForeignKey. How to treat child rows on delete of parent (the one where FK is defined) model.
• kwargs (Any): all other args to be populated by BaseField

Returns:

(ForeignKeyField): ormar ForeignKeyField with relation to selected model

ForeignKeyField Objects

class ForeignKeyField(BaseField)

Actual class returned from ForeignKey function call and stored in model_fields.

to

name

related_name

virtual

_extract_model_from_sequence

 | @classmethod
 | _extract_model_from_sequence(cls, value: List, child: "Model", to_register: bool, relation_name: str) -> List["Model"]

Takes a list of Models and registers them on parent. Registration is mutual, so children have also reference to parent.

Used in reverse FK relations.

Arguments:

• value (List): list of Model
• child (Model): child/ related Model
• to_register (bool): flag if the relation should be set in RelationshipManager

Returns:

(List["Model"]): list (if needed) registered Models

_register_existing_model

 | @classmethod
 | _register_existing_model(cls, value: "Model", child: "Model", to_register: bool, relation_name: str) -> "Model"

Takes already created instance and registers it for parent. Registration is mutual, so children have also reference to parent.

Used in reverse FK relations and normal FK for single models.

Arguments:

• value (Model): already instantiated Model
• child (Model): child/ related Model
• to_register (bool): flag if the relation should be set in RelationshipManager

Returns:

(Model): (if needed) registered Model

_construct_model_from_dict

 | @classmethod
 | _construct_model_from_dict(cls, value: dict, child: "Model", to_register: bool, relation_name: str) -> "Model"

Takes a dictionary, creates a instance and registers it for parent. If dictionary contains only one field and it's a pk it is a pk_only model. Registration is mutual, so children have also reference to parent.

Used in normal FK for dictionaries.

Arguments:

• value (dict): dictionary of a Model
• child (Model): child/ related Model
• to_register (bool): flag if the relation should be set in RelationshipManager

Returns:

(Model): (if needed) registered Model

_construct_model_from_pk

 | @classmethod
 | _construct_model_from_pk(cls, value: Any, child: "Model", to_register: bool, relation_name: str) -> "Model"

Takes a pk value, creates a dummy instance and registers it for parent. Registration is mutual, so children have also reference to parent.

Used in normal FK for dictionaries.

Arguments:

• value (Any): value of a related pk / fk column
• child (Model): child/ related Model
• to_register (bool): flag if the relation should be set in RelationshipManager

Returns:

(Model): (if needed) registered Model

register_relation

 | @classmethod
 | register_relation(cls, model: "Model", child: "Model", relation_name: str) -> None

Registers relation between parent and child in relation manager. Relation manager is kep on each model (different instance).

Used in Metaclass and sometimes some relations are missing (i.e. cloned Models in fastapi might miss one).

Arguments:

• model (Model class): parent model (with relation definition)
• child (Model class): child model

expand_relationship

 | @classmethod
 | expand_relationship(cls, value: Any, child: Union["Model", "NewBaseModel"], to_register: bool = True, relation_name: str = None) -> Optional[Union["Model", List["Model"]]]

For relations the child model is first constructed (if needed), registered in relation and returned. For relation fields the value can be a pk value (Any type of field), dict (from Model) or actual instance/list of a "Model".

Selects the appropriate constructor based on a passed value.

Arguments:

• value (Any): a Model field value, returned untouched for non relation fields.
• child (Union["Model", "NewBaseModel"]): a child Model to register
• to_register (bool): flag if the relation should be set in RelationshipManager

Returns:

(Optional[Union["Model", List["Model"]]]): returns a Model or a list of Models