Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# util/preloaded.py
2# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
7# mypy: allow-untyped-defs, allow-untyped-calls
9"""supplies the "preloaded" registry to resolve circular module imports at
10runtime.
12"""
14from __future__ import annotations
16import sys
17from typing import Any
18from typing import Callable
19from typing import TYPE_CHECKING
20from typing import TypeVar
22_FN = TypeVar("_FN", bound=Callable[..., Any])
25if TYPE_CHECKING:
26 from sqlalchemy import dialects as _dialects
27 from sqlalchemy import orm as _orm
28 from sqlalchemy.engine import cursor as _engine_cursor
29 from sqlalchemy.engine import default as _engine_default
30 from sqlalchemy.engine import reflection as _engine_reflection
31 from sqlalchemy.engine import result as _engine_result
32 from sqlalchemy.engine import url as _engine_url
33 from sqlalchemy.orm import attributes as _orm_attributes
34 from sqlalchemy.orm import base as _orm_base
35 from sqlalchemy.orm import clsregistry as _orm_clsregistry
36 from sqlalchemy.orm import decl_api as _orm_decl_api
37 from sqlalchemy.orm import decl_base as _orm_decl_base
38 from sqlalchemy.orm import dependency as _orm_dependency
39 from sqlalchemy.orm import descriptor_props as _orm_descriptor_props
40 from sqlalchemy.orm import mapperlib as _orm_mapper
41 from sqlalchemy.orm import properties as _orm_properties
42 from sqlalchemy.orm import relationships as _orm_relationships
43 from sqlalchemy.orm import session as _orm_session
44 from sqlalchemy.orm import state as _orm_state
45 from sqlalchemy.orm import strategies as _orm_strategies
46 from sqlalchemy.orm import strategy_options as _orm_strategy_options
47 from sqlalchemy.orm import util as _orm_util
48 from sqlalchemy.sql import default_comparator as _sql_default_comparator
49 from sqlalchemy.sql import dml as _sql_dml
50 from sqlalchemy.sql import elements as _sql_elements
51 from sqlalchemy.sql import functions as _sql_functions
52 from sqlalchemy.sql import naming as _sql_naming
53 from sqlalchemy.sql import schema as _sql_schema
54 from sqlalchemy.sql import selectable as _sql_selectable
55 from sqlalchemy.sql import sqltypes as _sql_sqltypes
56 from sqlalchemy.sql import traversals as _sql_traversals
57 from sqlalchemy.sql import util as _sql_util
59 # sigh, appease mypy 0.971 which does not accept imports as instance
60 # variables of a module
61 dialects = _dialects
62 engine_cursor = _engine_cursor
63 engine_default = _engine_default
64 engine_reflection = _engine_reflection
65 engine_result = _engine_result
66 engine_url = _engine_url
67 orm_clsregistry = _orm_clsregistry
68 orm_base = _orm_base
69 orm = _orm
70 orm_attributes = _orm_attributes
71 orm_decl_api = _orm_decl_api
72 orm_decl_base = _orm_decl_base
73 orm_descriptor_props = _orm_descriptor_props
74 orm_dependency = _orm_dependency
75 orm_mapper = _orm_mapper
76 orm_properties = _orm_properties
77 orm_relationships = _orm_relationships
78 orm_session = _orm_session
79 orm_strategies = _orm_strategies
80 orm_strategy_options = _orm_strategy_options
81 orm_state = _orm_state
82 orm_util = _orm_util
83 sql_default_comparator = _sql_default_comparator
84 sql_dml = _sql_dml
85 sql_elements = _sql_elements
86 sql_functions = _sql_functions
87 sql_naming = _sql_naming
88 sql_selectable = _sql_selectable
89 sql_traversals = _sql_traversals
90 sql_schema = _sql_schema
91 sql_sqltypes = _sql_sqltypes
92 sql_util = _sql_util
95class _ModuleRegistry:
96 """Registry of modules to load in a package init file.
98 To avoid potential thread safety issues for imports that are deferred
99 in a function, like https://bugs.python.org/issue38884, these modules
100 are added to the system module cache by importing them after the packages
101 has finished initialization.
103 A global instance is provided under the name :attr:`.preloaded`. Use
104 the function :func:`.preload_module` to register modules to load and
105 :meth:`.import_prefix` to load all the modules that start with the
106 given path.
108 While the modules are loaded in the global module cache, it's advisable
109 to access them using :attr:`.preloaded` to ensure that it was actually
110 registered. Each registered module is added to the instance ``__dict__``
111 in the form `<package>_<module>`, omitting ``sqlalchemy`` from the package
112 name. Example: ``sqlalchemy.sql.util`` becomes ``preloaded.sql_util``.
113 """
115 def __init__(self, prefix="sqlalchemy."):
116 self.module_registry = set()
117 self.prefix = prefix
119 def preload_module(self, *deps: str) -> Callable[[_FN], _FN]:
120 """Adds the specified modules to the list to load.
122 This method can be used both as a normal function and as a decorator.
123 No change is performed to the decorated object.
124 """
125 self.module_registry.update(deps)
126 return lambda fn: fn
128 def import_prefix(self, path: str) -> None:
129 """Resolve all the modules in the registry that start with the
130 specified path.
131 """
132 for module in self.module_registry:
133 if self.prefix:
134 key = module.split(self.prefix)[-1].replace(".", "_")
135 else:
136 key = module
137 if (
138 not path or module.startswith(path)
139 ) and key not in self.__dict__:
140 __import__(module, globals(), locals())
141 self.__dict__[key] = globals()[key] = sys.modules[module]
144_reg = _ModuleRegistry()
145preload_module = _reg.preload_module
146import_prefix = _reg.import_prefix
148# this appears to do absolutely nothing for any version of mypy
149# if TYPE_CHECKING:
150# def __getattr__(key: str) -> ModuleType:
151# ...