Skip to content

cache

Per-model cache of statement templates.

Every model class gets its own least-recently-used cache, keyed by cache key (see cache_keys), holding statements built with named slots (see slots). Reads and writes share it::

Text Only
1
2
cache = template_cache_for(model_cls=Author)
cache.get(key)  # -> cached statement or None

StatementTemplate

Bases: NamedTuple

A statement from the template cache and the values to run it with for one call::

Text Only
1
2
3
template = queryset.filter(name="a").limit(5).build_select_template()
template.params  # -> {"ormar_p0": "a", "ormar_limit": 5}
await executor.fetch_all(template.statement, template.params)
Source code in ormar/queryset/templates/cache.py
Python
31
32
33
34
35
36
37
38
39
40
41
42
class StatementTemplate(NamedTuple):
    """
    A statement from the template cache and the values to run it with for one
    call::

        template = queryset.filter(name="a").limit(5).build_select_template()
        template.params  # -> {"ormar_p0": "a", "ormar_limit": 5}
        await executor.fetch_all(template.statement, template.params)
    """

    statement: Executable
    params: Dict[str, Any]

TemplateCache

Least-recently-used cache of one model's statements, keyed by cache key.

The size is bounded so an application that builds queries from many different filter combinations cannot grow memory without limit: once max_size keys are cached, adding one drops the key used longest ago.

Source code in ormar/queryset/templates/cache.py
Python
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 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
 95
 96
 97
 98
 99
100
class TemplateCache:
    """
    Least-recently-used cache of one model's statements, keyed by cache key.

    The size is bounded so an application that builds queries from many
    different filter combinations cannot grow memory without limit: once
    ``max_size`` keys are cached, adding one drops the key used longest ago.
    """

    def __init__(self, max_size: int = TEMPLATE_CACHE_SIZE) -> None:
        """
        :param max_size: number of cache keys kept
        :type max_size: int
        """
        self.max_size = max_size
        self.entries: "OrderedDict[Any, Any]" = OrderedDict()

    def get(self, key: Any) -> Any:
        """
        Return the statement cached for a key, or None, and mark it as the
        most recently used.

        Another thread using the same model may evict the entry between reading
        it and marking it, so that case is ignored: the statement is still
        valid for this call.

        :param key: cache key of the statement
        :type key: Any
        :return: cached statement or None
        :rtype: Any
        """
        statement = self.entries.get(key)
        if statement is not None:
            try:
                self.entries.move_to_end(key)
            except KeyError:  # pragma: no cover - evicted concurrently
                pass
        return statement

    def put(self, key: Any, statement: Any) -> None:
        """
        Cache the statement of a key. When the cache is full, the key used
        longest ago is dropped.

        :param key: cache key of the statement
        :type key: Any
        :param statement: statement to cache
        :type statement: Any
        """
        self.entries[key] = statement
        if len(self.entries) > self.max_size:
            self.entries.popitem(last=False)

    def clear(self) -> None:
        """Remove every cached statement."""
        self.entries.clear()

__init__(max_size=TEMPLATE_CACHE_SIZE)

Parameters:

Name Type Description Default
max_size int

number of cache keys kept

TEMPLATE_CACHE_SIZE
Source code in ormar/queryset/templates/cache.py
Python
54
55
56
57
58
59
60
def __init__(self, max_size: int = TEMPLATE_CACHE_SIZE) -> None:
    """
    :param max_size: number of cache keys kept
    :type max_size: int
    """
    self.max_size = max_size
    self.entries: "OrderedDict[Any, Any]" = OrderedDict()

clear()

Remove every cached statement.

Source code in ormar/queryset/templates/cache.py
Python
 98
 99
100
def clear(self) -> None:
    """Remove every cached statement."""
    self.entries.clear()

get(key)

Return the statement cached for a key, or None, and mark it as the most recently used.

Another thread using the same model may evict the entry between reading it and marking it, so that case is ignored: the statement is still valid for this call.

Parameters:

Name Type Description Default
key Any

cache key of the statement

required

Returns:

Type Description
Any

cached statement or None

Source code in ormar/queryset/templates/cache.py
Python
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def get(self, key: Any) -> Any:
    """
    Return the statement cached for a key, or None, and mark it as the
    most recently used.

    Another thread using the same model may evict the entry between reading
    it and marking it, so that case is ignored: the statement is still
    valid for this call.

    :param key: cache key of the statement
    :type key: Any
    :return: cached statement or None
    :rtype: Any
    """
    statement = self.entries.get(key)
    if statement is not None:
        try:
            self.entries.move_to_end(key)
        except KeyError:  # pragma: no cover - evicted concurrently
            pass
    return statement

put(key, statement)

Cache the statement of a key. When the cache is full, the key used longest ago is dropped.

Parameters:

Name Type Description Default
key Any

cache key of the statement

required
statement Any

statement to cache

required
Source code in ormar/queryset/templates/cache.py
Python
84
85
86
87
88
89
90
91
92
93
94
95
96
def put(self, key: Any, statement: Any) -> None:
    """
    Cache the statement of a key. When the cache is full, the key used
    longest ago is dropped.

    :param key: cache key of the statement
    :type key: Any
    :param statement: statement to cache
    :type statement: Any
    """
    self.entries[key] = statement
    if len(self.entries) > self.max_size:
        self.entries.popitem(last=False)

cached_statement(model_cls, key, builder, **builder_kwargs)

Return the statement cached for a write cache key, building it on a miss. The statement is marked as a template (TEMPLATE_OPTION), so the native compiler keeps its plan even when SQLAlchemy cannot cache it.

A write's cache key is small (the kind of statement and the written column names), so callers pass the key directly. The statement is only built on a miss, from builder(**builder_kwargs)::

Text Only
1
2
3
4
5
6
7
cached_statement(
    model_cls=Author,
    key=("insert", ("name", "score")),
    builder=build_insert,
    table=Author.ormar_config.table,
    names=("name", "score"),
)

Parameters:

Name Type Description Default
model_cls Type[Any]

model the statement writes

required
key Tuple[Any, ...]

cache key of the write

required
builder Callable[..., Executable]

builds the statement from builder_kwargs

required
builder_kwargs Any

keyword arguments of the builder

{}

Returns:

Type Description
Executable

statement for the key

Source code in ormar/queryset/templates/cache.py
Python
127
128
129
130
131
132
133
134
135
136
137
138
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 cached_statement(
    model_cls: Type[Any],
    key: Tuple[Any, ...],
    builder: Callable[..., Executable],
    **builder_kwargs: Any,
) -> Executable:
    """
    Return the statement cached for a write cache key, building it on a miss.
    The statement is marked as a template (``TEMPLATE_OPTION``), so the native
    compiler keeps its plan even when SQLAlchemy cannot cache it.

    A write's cache key is small (the kind of statement and the written column
    names), so callers pass the key directly. The statement is only built on
    a miss, from ``builder(**builder_kwargs)``::

        cached_statement(
            model_cls=Author,
            key=("insert", ("name", "score")),
            builder=build_insert,
            table=Author.ormar_config.table,
            names=("name", "score"),
        )

    :param model_cls: model the statement writes
    :type model_cls: Type[Any]
    :param key: cache key of the write
    :type key: Tuple[Any, ...]
    :param builder: builds the statement from ``builder_kwargs``
    :type builder: Callable[..., Executable]
    :param builder_kwargs: keyword arguments of the builder
    :type builder_kwargs: Any
    :return: statement for the key
    :rtype: Executable
    """
    cache = template_cache_for(model_cls=model_cls)
    statement = cache.get(key)
    if statement is None:
        statement = builder(**builder_kwargs).execution_options(
            **{TEMPLATE_OPTION: True}
        )
        cache.put(key=key, statement=statement)
    return statement

template_cache_for(model_cls)

Return the statement template cache of a model class, creating it on the model's first read. setdefault keeps a single cache when two threads create it at the same time.

Parameters:

Name Type Description Default
model_cls Type[Any]

model class

required

Returns:

Type Description
TemplateCache

the model's template cache

Source code in ormar/queryset/templates/cache.py
Python
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def template_cache_for(model_cls: Type[Any]) -> TemplateCache:
    """
    Return the statement template cache of a model class, creating it on the
    model's first read. ``setdefault`` keeps a single cache when two threads
    create it at the same time.

    :param model_cls: model class
    :type model_cls: Type[Any]
    :return: the model's template cache
    :rtype: TemplateCache
    """
    cache = TEMPLATE_CACHES.get(model_cls)
    if cache is None:
        cache = TEMPLATE_CACHES.setdefault(model_cls, TemplateCache())
    return cache