1
# sqlalchemy/inspect.py
2
# Copyright (C) 2005-2013 the SQLAlchemy authors and contributors <see AUTHORS file>
4
# This module is part of SQLAlchemy and is released under
5
# the MIT License: http://www.opensource.org/licenses/mit-license.php
7
"""The inspection module provides the :func:`.inspect` function,
8
which delivers runtime information about a wide variety
9
of SQLAlchemy objects, both within the Core as well as the
12
The :func:`.inspect` function is the entry point to SQLAlchemy's
13
public API for viewing the configuration and construction
14
of in-memory objects. Depending on the type of object
15
passed to :func:`.inspect`, the return value will either be
16
a related object which provides a known interface, or in many
17
cases it will return the object itself.
19
The rationale for :func:`.inspect` is twofold. One is that
20
it replaces the need to be aware of a large variety of "information
21
getting" functions in SQLAlchemy, such as :meth:`.Inspector.from_engine`,
22
:func:`.orm.attributes.instance_state`, :func:`.orm.class_mapper`,
23
and others. The other is that the return value of :func:`.inspect`
24
is guaranteed to obey a documented API, thus allowing third party
25
tools which build on top of SQLAlchemy configurations to be constructed
26
in a forwards-compatible way.
28
.. versionadded:: 0.8 The :func:`.inspect` system is introduced
33
from . import util, exc
34
_registrars = util.defaultdict(list)
37
def inspect(subject, raiseerr=True):
38
"""Produce an inspection object for the given target.
40
The returned value in some cases may be the
41
same object as the one given, such as if a
42
:class:`.orm.Mapper` object is passed. In other
43
cases, it will be an instance of the registered
44
inspection type for the given object, such as
45
if a :class:`.engine.Engine` is passed, an
46
:class:`.engine.Inspector` object is returned.
48
:param subject: the subject to be inspected.
49
:param raiseerr: When ``True``, if the given subject
51
correspond to a known SQLAlchemy inspected type,
52
:class:`sqlalchemy.exc.NoInspectionAvailable`
53
is raised. If ``False``, ``None`` is returned.
57
for cls in type_.__mro__:
58
if cls in _registrars:
59
reg = _registrars[cls]
69
reg is None or ret is None
71
raise exc.NoInspectionAvailable(
72
"No inspection system is "
73
"available for object of type %s" %
78
def _inspects(*types):
79
def decorate(fn_or_cls):
81
if type_ in _registrars:
85
_registrars[type_] = fn_or_cls
90
def _self_inspects(*types):
91
_inspects(*types)(True)