Skip to content

aliases

alias_for(relation_path) cached

Returns the table alias for a relation path.

The path is the dunder separated chain of relation names from the root model of a single sql statement. The alias is a short hash of the path, stable between queries and processes. Two paths with the same hash would share an alias in one statement, so each alias is owned by the first path that gets it and a colliding path gets a salted hash (an alias that is unique in the process, but depends on which path came first). Through tables of many to many relations use the relation path followed by the through model name.

Parameters:

Name Type Description Default
relation_path str

dunder separated relation path, empty for the root model

required

Returns:

Type Description
str

alias of the table joined under that path, empty for the root model

Source code in ormar/relations/aliases.py
Python
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
@lru_cache(maxsize=4096)
def alias_for(relation_path: str) -> str:
    """
    Returns the table alias for a relation path.

    The path is the dunder separated chain of relation names from the root model
    of a single sql statement. The alias is a short hash of the path, stable
    between queries and processes. Two paths with the same hash would share an
    alias in one statement, so each alias is owned by the first path that gets
    it and a colliding path gets a salted hash (an alias that is unique in the
    process, but depends on which path came first). Through tables of many to
    many relations use the relation path followed by the through model name.

    :param relation_path: dunder separated relation path, empty for the root model
    :type relation_path: str
    :return: alias of the table joined under that path, empty for the root model
    :rtype: str
    """
    if not relation_path:
        return ""
    attempt = 0
    alias = path_hash(relation_path=relation_path, attempt=attempt)
    while ALIAS_OWNERS.setdefault(alias, relation_path) != relation_path:
        attempt += 1
        alias = path_hash(relation_path=relation_path, attempt=attempt)
    return alias

build_prefixed_columns(*, alias, table, fields) cached

Builds labelled columns of a table, cached as labels are immutable and the same model/alias/fields combination is selected over and over.

Parameters:

Name Type Description Default
alias str

alias of given table

required
table Table

table from which fields should be aliased

required
fields Optional[frozenset[str]]

column names (ormar aliases) to include, None for all

required

Returns:

Type Description
tuple[Label[Any], ...]

tuple of labelled columns

Source code in ormar/relations/aliases.py
Python
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
@lru_cache(maxsize=2048)
def build_prefixed_columns(
    *, alias: str, table: sqlalchemy.Table, fields: Optional[frozenset[str]]
) -> tuple[Label[Any], ...]:
    """
    Builds labelled columns of a table, cached as labels are immutable and the
    same model/alias/fields combination is selected over and over.

    :param alias: alias of given table
    :type alias: str
    :param table: table from which fields should be aliased
    :type table: sqlalchemy.Table
    :param fields: column names (ormar aliases) to include, None for all
    :type fields: Optional[frozenset[str]]
    :return: tuple of labelled columns
    :rtype: tuple[Label[Any], ...]
    """
    alias = f"{alias}_" if alias else ""
    aliased_fields = {f"{alias}{x}" for x in fields} if fields else set()
    all_columns = (
        table.columns
        if not fields
        else [
            col
            for col in table.columns
            if col.name in fields or col.name in aliased_fields
        ]
    )
    return tuple(column.label(f"{alias}{column.name}") for column in all_columns)

path_hash(relation_path, attempt)

Returns a candidate alias of a relation path, the plain hash of the path on the first attempt and a hash salted with the attempt number afterwards.

Parameters:

Name Type Description Default
relation_path str

dunder separated relation path

required
attempt int

number of the candidate, 0 for the plain hash

required

Returns:

Type Description
str

candidate alias

Source code in ormar/relations/aliases.py
Python
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
def path_hash(relation_path: str, attempt: int) -> str:
    """
    Returns a candidate alias of a relation path, the plain hash of the path on
    the first attempt and a hash salted with the attempt number afterwards.

    :param relation_path: dunder separated relation path
    :type relation_path: str
    :param attempt: number of the candidate, 0 for the plain hash
    :type attempt: int
    :return: candidate alias
    :rtype: str
    """
    key = relation_path if not attempt else f"{relation_path}#{attempt}"
    return (
        "t" + hashlib.blake2s(key.encode(), digest_size=ALIAS_DIGEST_SIZE).hexdigest()
    )

prefixed_columns(alias, table, fields=None)

Creates a list of labelled columns of a table prefixed with the table alias.

Optional list of fields to include can be passed to extract only those columns. List has to have sqlalchemy names of columns (ormar aliases) not the ormar ones.

Parameters:

Name Type Description Default
alias str

alias of given table

required
table Table

table from which fields should be aliased

required
fields Optional[list]

fields to include

None

Returns:

Type Description
list[Label[Any]]

list of labelled columns

Source code in ormar/relations/aliases.py
Python
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def prefixed_columns(
    alias: str, table: sqlalchemy.Table, fields: Optional[list] = None
) -> list[Label[Any]]:
    """
    Creates a list of labelled columns of a table prefixed with the table alias.

    Optional list of fields to include can be passed to extract only those columns.
    List has to have sqlalchemy names of columns (ormar aliases) not the ormar ones.

    :param alias: alias of given table
    :type alias: str
    :param table: table from which fields should be aliased
    :type table: sqlalchemy.Table
    :param fields: fields to include
    :type fields: Optional[list[str]]
    :return: list of labelled columns
    :rtype: list[Label[Any]]
    """
    return list(
        build_prefixed_columns(
            alias=alias, table=table, fields=frozenset(fields) if fields else None
        )
    )

prefixed_table(*, alias, table) cached

Returns the table aliased under its table alias.

Cached without a size limit, as filters and joins of one statement have to reference the same aliased table object, and the number of aliases is bounded by the relation paths of the defined models. The parameters are keyword-only, as the cache keys keyword and positional calls differently, and two aliased objects of one table break the query.

Parameters:

Name Type Description Default
alias str

alias of given table

required
table Table

table to alias

required

Returns:

Type Description
NamedFromClause

aliased table

Source code in ormar/relations/aliases.py
Python
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
@lru_cache(maxsize=None)
def prefixed_table(*, alias: str, table: sqlalchemy.Table) -> NamedFromClause:
    """
    Returns the table aliased under its table alias.

    Cached without a size limit, as filters and joins of one statement have to
    reference the same aliased table object, and the number of aliases is bounded
    by the relation paths of the defined models.
    The parameters are keyword-only, as the cache keys keyword and positional
    calls differently, and two aliased objects of one table break the query.

    :param alias: alias of given table
    :type alias: str
    :param table: table to alias
    :type table: sqlalchemy.Table
    :return: aliased table
    :rtype: NamedFromClause
    """
    return table.alias(f"{alias}_{table.name}")