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