Skip to content

relations

expand_reverse_relationship(model_field)

If the reverse relation has not been set before it's set here.

Parameters:

Name Type Description Default
model_field ForeignKeyField
required

Returns:

Type Description
None

None
Source code in ormar\models\helpers\relations.py 
62
63
64
65
66
67
68
69
70
71
72
def expand_reverse_relationship(model_field: "ForeignKeyField") -> None:
    """
    If the reverse relation has not been set before it's set here.

    :param model_field:
    :type model_field:
    :return: None
    :rtype: None
    """
    if reverse_field_not_already_registered(model_field=model_field):
        register_reverse_model_fields(model_field=model_field)

expand_reverse_relationships(model)

Iterates through model_fields of given model and verifies if all reverse relation have been populated on related models.

If the reverse relation has not been set before it's set here.

Parameters:

Name Type Description Default
model Type[Model]

model on which relation should be checked and registered

 required
Source code in ormar\models\helpers\relations.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def expand_reverse_relationships(model: Type["Model"]) -> None:
    """
    Iterates through model_fields of given model and verifies if all reverse
    relation have been populated on related models.

    If the reverse relation has not been set before it's set here.

    :param model: model on which relation should be checked and registered
    :type model: Model class
    """
    model_fields = list(model.Meta.model_fields.values())
    for model_field in model_fields:
        if model_field.is_relation and not model_field.has_unresolved_forward_refs():
            model_field = cast("ForeignKeyField", model_field)
            expand_reverse_relationship(model_field=model_field)

register_many_to_many_relation_on_build(field)

Registers connection between through model and both sides of the m2m relation. Registration include also reverse relation side to be able to join both sides.

Relation is registered by model name and relation field name to allow for multiple relations between two Models that needs to have different aliases for proper sql joins.

By default relation name is a model.name.lower().

Parameters:

Name Type Description Default
field ManyToManyField

relation field

 required
Source code in ormar\models\helpers\relations.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def register_many_to_many_relation_on_build(field: "ManyToManyField") -> None:
    """
    Registers connection between through model and both sides of the m2m relation.
    Registration include also reverse relation side to be able to join both sides.

    Relation is registered by model name and relation field name to allow for multiple
    relations between two Models that needs to have different
    aliases for proper sql joins.

    By default relation name is a model.name.lower().

    :param field: relation field
    :type field: ManyToManyField class
    """
    alias_manager.add_relation_type(
        source_model=field.through,
        relation_name=field.default_source_field_name(),
        reverse_name=field.get_source_related_name(),
    )
    alias_manager.add_relation_type(
        source_model=field.through,
        relation_name=field.default_target_field_name(),
        reverse_name=field.get_related_name(),
    )

register_relation_in_alias_manager(field)

Registers the relation (and reverse relation) in alias manager. The m2m relations require registration of through model between actual end models of the relation.

Delegates the actual registration to: m2m - register_many_to_many_relation_on_build fk - register_relation_on_build

Parameters:

Name Type Description Default
field ForeignKeyField

relation field

 required
Source code in ormar\models\helpers\relations.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
def register_relation_in_alias_manager(field: "ForeignKeyField") -> None:
    """
    Registers the relation (and reverse relation) in alias manager.
    The m2m relations require registration of through model between
    actual end models of the relation.

    Delegates the actual registration to:
    m2m - register_many_to_many_relation_on_build
    fk - register_relation_on_build

    :param field: relation field
    :type field: ForeignKey or ManyToManyField class
    """
    if field.is_multi:
        if field.has_unresolved_forward_refs():
            return
        field = cast("ManyToManyField", field)
        register_many_to_many_relation_on_build(field=field)
    elif field.is_relation and not field.is_through:
        if field.has_unresolved_forward_refs():
            return
        register_relation_on_build(field=field)

register_relation_on_build(field)

Registers ForeignKey relation in alias_manager to set a table_prefix. Registration include also reverse relation side to be able to join both sides.

Relation is registered by model name and relation field name to allow for multiple relations between two Models that needs to have different aliases for proper sql joins.

Parameters:

Name Type Description Default
field ForeignKeyField

relation field

 required
Source code in ormar\models\helpers\relations.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
def register_relation_on_build(field: "ForeignKeyField") -> None:
    """
    Registers ForeignKey relation in alias_manager to set a table_prefix.
    Registration include also reverse relation side to be able to join both sides.

    Relation is registered by model name and relation field name to allow for multiple
    relations between two Models that needs to have different
    aliases for proper sql joins.

    :param field: relation field
    :type field: ForeignKey class
    """
    alias_manager.add_relation_type(
        source_model=field.owner,
        relation_name=field.name,
        reverse_name=field.get_source_related_name(),
    )

register_reverse_model_fields(model_field)

Registers reverse ForeignKey field on related model. By default it's name.lower()+'s' of the model on which relation is defined.

But if the related_model name is provided it's registered with that name. Autogenerated reverse fields also set related_name to the original field name.

Parameters:

Name Type Description Default
model_field ForeignKeyField

original relation ForeignKey field

 required
Source code in ormar\models\helpers\relations.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def register_reverse_model_fields(model_field: "ForeignKeyField") -> None:
    """
    Registers reverse ForeignKey field on related model.
    By default it's name.lower()+'s' of the model on which relation is defined.

    But if the related_model name is provided it's registered with that name.
    Autogenerated reverse fields also set related_name to the original field name.

    :param model_field: original relation ForeignKey field
    :type model_field: relation Field
    """
    related_name = model_field.get_related_name()
    # TODO: Reverse relations does not register pydantic fields?
    if model_field.is_multi:
        model_field.to.Meta.model_fields[related_name] = ManyToMany(  # type: ignore
            model_field.owner,
            through=model_field.through,
            name=related_name,
            virtual=True,
            related_name=model_field.name,
            owner=model_field.to,
            self_reference=model_field.self_reference,
            self_reference_primary=model_field.self_reference_primary,
            orders_by=model_field.related_orders_by,
            skip_field=model_field.skip_reverse,
            through_relation_name=model_field.through_reverse_relation_name,
            through_reverse_relation_name=model_field.through_relation_name,
        )
        # register foreign keys on through model
        model_field = cast("ManyToManyField", model_field)
        register_through_shortcut_fields(model_field=model_field)
        adjust_through_many_to_many_model(model_field=model_field)
    else:
        model_field.to.Meta.model_fields[related_name] = ForeignKey(  # type: ignore
            model_field.owner,
            real_name=related_name,
            virtual=True,
            related_name=model_field.name,
            owner=model_field.to,
            self_reference=model_field.self_reference,
            orders_by=model_field.related_orders_by,
            skip_field=model_field.skip_reverse,
        )
    if not model_field.skip_reverse:
        setattr(model_field.to, related_name, RelationDescriptor(name=related_name))

register_through_shortcut_fields(model_field)

Registers m2m relation through shortcut on both ends of the relation.

Parameters:

Name Type Description Default
model_field ManyToManyField

relation field defined in parent model

 required
Source code in ormar\models\helpers\relations.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
def register_through_shortcut_fields(model_field: "ManyToManyField") -> None:
    """
    Registers m2m relation through shortcut on both ends of the relation.

    :param model_field: relation field defined in parent model
    :type model_field: ManyToManyField
    """
    through_model = model_field.through
    through_name = through_model.get_name(lower=True)
    related_name = model_field.get_related_name()

    model_field.owner.Meta.model_fields[through_name] = Through(
        through_model,
        real_name=through_name,
        virtual=True,
        related_name=model_field.name,
        owner=model_field.owner,
        nullable=True,
    )

    model_field.to.Meta.model_fields[through_name] = Through(
        through_model,
        real_name=through_name,
        virtual=True,
        related_name=related_name,
        owner=model_field.to,
        nullable=True,
    )
    setattr(model_field.owner, through_name, RelationDescriptor(name=through_name))
    setattr(model_field.to, through_name, RelationDescriptor(name=through_name))

reverse_field_not_already_registered(model_field)

Checks if child is already registered in parents pydantic fields.

Parameters:

Name Type Description Default
model_field ForeignKeyField

original relation ForeignKey field

 required

Returns:

Type Description
bool

result of the check

Raises:

Type Description
ModelDefinitionError

if related name is already used but lead to different related model
Source code in ormar\models\helpers\relations.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
def reverse_field_not_already_registered(model_field: "ForeignKeyField") -> bool:
    """
    Checks if child is already registered in parents pydantic fields.

    :raises ModelDefinitionError: if related name is already used but lead to different
    related model
    :param model_field: original relation ForeignKey field
    :type model_field: relation Field
    :return: result of the check
    :rtype: bool
    """
    related_name = model_field.get_related_name()
    check_result = related_name not in model_field.to.Meta.model_fields
    check_result2 = model_field.owner.get_name() not in model_field.to.Meta.model_fields

    if not check_result:
        verify_related_name_dont_duplicate(
            related_name=related_name, model_field=model_field
        )
    if not check_result2:
        verify_related_name_dont_duplicate(
            related_name=model_field.owner.get_name(), model_field=model_field
        )

    return check_result and check_result2

Verifies whether the used related_name (regardless of the fact if user defined or auto generated) is already used on related model, but is connected with other model than the one that we connect right now.

Parameters:

Name Type Description Default
related_name str
required
model_field ForeignKeyField

original relation ForeignKey field

 required

Returns:

Type Description
None

None

Raises:

Type Description
ModelDefinitionError

if name is already used but lead to different related model
Source code in ormar\models\helpers\relations.py 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
def verify_related_name_dont_duplicate(
    related_name: str, model_field: "ForeignKeyField"
) -> None:
    """
    Verifies whether the used related_name (regardless of the fact if user defined or
    auto generated) is already used on related model, but is connected with other model
    than the one that we connect right now.

    :raises ModelDefinitionError: if name is already used but lead to different related
    model
    :param related_name:
    :type related_name:
    :param model_field: original relation ForeignKey field
    :type model_field: relation Field
    :return: None
    :rtype: None
    """
    fk_field = model_field.to.Meta.model_fields.get(related_name)
    if not fk_field:  # pragma: no cover
        return
    if fk_field.to != model_field.owner and fk_field.to.Meta != model_field.owner.Meta:
        raise ormar.ModelDefinitionError(
            f"Relation with related_name "
            f"'{related_name}' "
            f"leading to model "
            f"{model_field.to.get_name(lower=False)} "
            f"cannot be used on model "
            f"{model_field.owner.get_name(lower=False)} "
            f"because it's already used by model "
            f"{fk_field.to.get_name(lower=False)}"
        )