1
2
3
4
5
6
7
8
9
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
39
40
41
42
43
44
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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
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
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
Runtime Inspection API
—
SQLAlchemy 0.9 Documentation
</title>
<!-- begin iterate through SQLA + sphinx environment css_files -->
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/docs.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
<link rel="stylesheet" href="../_static/changelog.css" type="text/css" />
<!-- end iterate through SQLA + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.9.8',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<!-- begin iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<!-- end iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/detectmobile.js"></script>
<script type="text/javascript" src="../_static/init.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="SQLAlchemy 0.9 Documentation" href="../index.html" />
<link rel="up" title="SQLAlchemy Core" href="index.html" />
<link rel="next" title="Expression Serializer Extension" href="serializer.html" />
<link rel="prev" title="Custom SQL Constructs and Compilation Extension" href="compiler.html" />
<!-- end layout.mako headers -->
</head>
<body>
<div id="docs-container">
<div id="docs-top-navigation-container" class="body-background">
<div id="docs-header">
<div id="docs-version-header">
Release: <span class="version-num">0.9.8</span> | Release Date: October 13, 2014
</div>
<h1>SQLAlchemy 0.9 Documentation</h1>
</div>
</div>
<div id="docs-body-container">
<div id="fixed-sidebar" class="withsidebar">
<div id="docs-sidebar-popout">
<h3><a href="../index.html">SQLAlchemy 0.9 Documentation</a></h3>
<p id="sidebar-paginate">
<a href="index.html" title="SQLAlchemy Core">Up</a> |
<a href="compiler.html" title="Custom SQL Constructs and Compilation Extension">Prev</a> |
<a href="serializer.html" title="Expression Serializer Extension">Next</a>
</p>
<p id="sidebar-topnav">
<a href="../index.html">Contents</a> |
<a href="../genindex.html">Index</a>
</p>
<div id="sidebar-search">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="12" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div id="docs-sidebar">
<h3><a href="#">
Runtime Inspection API
</a></h3>
<ul>
<li><a class="reference internal" href="#">Runtime Inspection API</a><ul>
<li><a class="reference internal" href="#available-inspection-targets">Available Inspection Targets</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="docs-body" class="withsidebar" >
<div class="section" id="module-sqlalchemy.inspection">
<span id="runtime-inspection-api"></span><span id="inspection-toplevel"></span><span id="core-inspection-toplevel"></span><h1>Runtime Inspection API<a class="headerlink" href="#module-sqlalchemy.inspection" title="Permalink to this headline">¶</a></h1>
<p>The inspection module provides the <a class="reference internal" href="#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><tt class="xref py py-func docutils literal"><span class="pre">inspect()</span></tt></a> function,
which delivers runtime information about a wide variety
of SQLAlchemy objects, both within the Core as well as the
ORM.</p>
<p>The <a class="reference internal" href="#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><tt class="xref py py-func docutils literal"><span class="pre">inspect()</span></tt></a> function is the entry point to SQLAlchemy’s
public API for viewing the configuration and construction
of in-memory objects. Depending on the type of object
passed to <a class="reference internal" href="#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><tt class="xref py py-func docutils literal"><span class="pre">inspect()</span></tt></a>, the return value will either be
a related object which provides a known interface, or in many
cases it will return the object itself.</p>
<p>The rationale for <a class="reference internal" href="#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><tt class="xref py py-func docutils literal"><span class="pre">inspect()</span></tt></a> is twofold. One is that
it replaces the need to be aware of a large variety of “information
getting” functions in SQLAlchemy, such as <a class="reference internal" href="reflection.html#sqlalchemy.engine.reflection.Inspector.from_engine" title="sqlalchemy.engine.reflection.Inspector.from_engine"><tt class="xref py py-meth docutils literal"><span class="pre">Inspector.from_engine()</span></tt></a>,
<a class="reference internal" href="../orm/session.html#sqlalchemy.orm.attributes.instance_state" title="sqlalchemy.orm.attributes.instance_state"><tt class="xref py py-func docutils literal"><span class="pre">orm.attributes.instance_state()</span></tt></a>, <a class="reference internal" href="../orm/mapper_config.html#sqlalchemy.orm.class_mapper" title="sqlalchemy.orm.class_mapper"><tt class="xref py py-func docutils literal"><span class="pre">orm.class_mapper()</span></tt></a>,
and others. The other is that the return value of <a class="reference internal" href="#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><tt class="xref py py-func docutils literal"><span class="pre">inspect()</span></tt></a>
is guaranteed to obey a documented API, thus allowing third party
tools which build on top of SQLAlchemy configurations to be constructed
in a forwards-compatible way.</p>
<div class="versionadded">
<p><span>New in version 0.8: </span>The <a class="reference internal" href="#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><tt class="xref py py-func docutils literal"><span class="pre">inspect()</span></tt></a> system is introduced
as of version 0.8.</p>
</div>
<dl class="function">
<dt id="sqlalchemy.inspection.inspect">
<tt class="descclassname">sqlalchemy.inspection.</tt><tt class="descname">inspect</tt><big>(</big><em>subject</em>, <em>raiseerr=True</em><big>)</big><a class="headerlink" href="#sqlalchemy.inspection.inspect" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an inspection object for the given target.</p>
<p>The returned value in some cases may be the
same object as the one given, such as if a
<a class="reference internal" href="../orm/mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> object is passed. In other
cases, it will be an instance of the registered
inspection type for the given object, such as
if an <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">engine.Engine</span></tt></a> is passed, an
<a class="reference internal" href="reflection.html#sqlalchemy.engine.reflection.Inspector" title="sqlalchemy.engine.reflection.Inspector"><tt class="xref py py-class docutils literal"><span class="pre">Inspector</span></tt></a> object is returned.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.inspection.inspect.params.subject"></span><strong>subject</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.inspection.inspect.params.subject">¶</a> – the subject to be inspected.</li>
<li><span class="target" id="sqlalchemy.inspection.inspect.params.raiseerr"></span><strong>raiseerr</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.inspection.inspect.params.raiseerr">¶</a> – When <tt class="docutils literal"><span class="pre">True</span></tt>, if the given subject
does not
correspond to a known SQLAlchemy inspected type,
<a class="reference internal" href="exceptions.html#sqlalchemy.exc.NoInspectionAvailable" title="sqlalchemy.exc.NoInspectionAvailable"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.exc.NoInspectionAvailable</span></tt></a>
is raised. If <tt class="docutils literal"><span class="pre">False</span></tt>, <tt class="docutils literal"><span class="pre">None</span></tt> is returned.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<div class="section" id="available-inspection-targets">
<h2>Available Inspection Targets<a class="headerlink" href="#available-inspection-targets" title="Permalink to this headline">¶</a></h2>
<p>Below is a listing of many of the most common inspection targets.</p>
<ul class="simple">
<li><a class="reference internal" href="connections.html#sqlalchemy.engine.Connectable" title="sqlalchemy.engine.Connectable"><tt class="xref py py-class docutils literal"><span class="pre">Connectable</span></tt></a> (i.e. <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>,
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>) - returns an <a class="reference internal" href="reflection.html#sqlalchemy.engine.reflection.Inspector" title="sqlalchemy.engine.reflection.Inspector"><tt class="xref py py-class docutils literal"><span class="pre">Inspector</span></tt></a> object.</li>
<li><a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a> - all SQL expression components, including
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>, <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>, serve as their own inspection objects,
meaning any of these objects passed to <a class="reference internal" href="#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><tt class="xref py py-func docutils literal"><span class="pre">inspect()</span></tt></a> return themselves.</li>
<li><tt class="docutils literal"><span class="pre">object</span></tt> - an object given will be checked by the ORM for a mapping -
if so, an <a class="reference internal" href="../orm/internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> is returned representing the mapped
state of the object. The <a class="reference internal" href="../orm/internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> also provides access
to per attribute state via the <a class="reference internal" href="../orm/internals.html#sqlalchemy.orm.state.AttributeState" title="sqlalchemy.orm.state.AttributeState"><tt class="xref py py-class docutils literal"><span class="pre">AttributeState</span></tt></a> interface as well
as the per-flush “history” of any attribute via the <a class="reference internal" href="../orm/session.html#sqlalchemy.orm.attributes.History" title="sqlalchemy.orm.attributes.History"><tt class="xref py py-class docutils literal"><span class="pre">History</span></tt></a>
object.</li>
<li><tt class="docutils literal"><span class="pre">type</span></tt> (i.e. a class) - a class given will be checked by the ORM for a
mapping - if so, a <a class="reference internal" href="../orm/mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> for that class is returned.</li>
<li>mapped attribute - passing a mapped attribute to <a class="reference internal" href="#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><tt class="xref py py-func docutils literal"><span class="pre">inspect()</span></tt></a>, such
as <tt class="docutils literal"><span class="pre">inspect(MyClass.some_attribute)</span></tt>, returns a <a class="reference internal" href="../orm/internals.html#sqlalchemy.orm.attributes.QueryableAttribute" title="sqlalchemy.orm.attributes.QueryableAttribute"><tt class="xref py py-class docutils literal"><span class="pre">QueryableAttribute</span></tt></a>
object, which is the <a class="reference internal" href="../glossary.html#term-descriptor"><em class="xref std std-term">descriptor</em></a> associated with a mapped class.
This descriptor refers to a <a class="reference internal" href="../orm/internals.html#sqlalchemy.orm.interfaces.MapperProperty" title="sqlalchemy.orm.interfaces.MapperProperty"><tt class="xref py py-class docutils literal"><span class="pre">MapperProperty</span></tt></a>, which is usually
an instance of <a class="reference internal" href="../orm/internals.html#sqlalchemy.orm.properties.ColumnProperty" title="sqlalchemy.orm.properties.ColumnProperty"><tt class="xref py py-class docutils literal"><span class="pre">ColumnProperty</span></tt></a>
or <a class="reference internal" href="../orm/internals.html#sqlalchemy.orm.properties.RelationshipProperty" title="sqlalchemy.orm.properties.RelationshipProperty"><tt class="xref py py-class docutils literal"><span class="pre">RelationshipProperty</span></tt></a>, via its <a class="reference internal" href="../orm/internals.html#sqlalchemy.orm.attributes.QueryableAttribute.property" title="sqlalchemy.orm.attributes.QueryableAttribute.property"><tt class="xref py py-attr docutils literal"><span class="pre">QueryableAttribute.property</span></tt></a>
attribute.</li>
<li><a class="reference internal" href="../orm/query.html#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><tt class="xref py py-class docutils literal"><span class="pre">AliasedClass</span></tt></a> - returns an <a class="reference internal" href="../orm/query.html#sqlalchemy.orm.util.AliasedInsp" title="sqlalchemy.orm.util.AliasedInsp"><tt class="xref py py-class docutils literal"><span class="pre">AliasedInsp</span></tt></a> object.</li>
</ul>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links">
Previous:
<a href="compiler.html" title="previous chapter">Custom SQL Constructs and Compilation Extension</a>
Next:
<a href="serializer.html" title="next chapter">Expression Serializer Extension</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2014, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.
</div>
</div>
</div>
</body>
</html>
|
