Skip to content

Commit b99012d

Browse files
zzzeekzzzeek
committed
Enable zzzeeksphinx module prefixes
zzzeeksphinx 1.1.2 in git can now convert short prefix names in a configured lookup to fully qualified module names, so that we can have succinct and portable pyrefs that still resolve absolutely. It also includes a formatter that will format all pyrefs in a fully consistent way regardless of the package path, by unconditionally removing all package tokens but always leaving class names in place including for methods, which means we no longer have to deal with tildes in pyrefs. The most immediate goal of the absolute prefixes is that we have lots of "ambiguous" names that appear in muliple places, like select(), ARRAY, ENUM etc. With the incoming future packages there is going to be lots of name overlap so it is necessary that all names eventually use absolute package paths when Sphinx receives them. In multiple stages, pyrefs will be converted using the zzzeeksphinx tools/fix_xrefs.py tool so that doclinks can be made absolute using symbolic prefixes. For this review, the actual search and replace of symbols is not performed, instead some general cleanup to prepare the docs as well as a lookup file used by the tool to do the conversion. this relatively small patch will be backported with appropriate changes to 1.3, 1.2, 1.1 and the tool can then be run on each branch individually. We are shooting for almost no warnings at all for master (still a handful I can't figure out which don't seem to have any impact) , very few for 1.3, and for 1.2 / 1.1 we hope for a significant reduction in warnings. Overall for all versions pyrefs should always point to the correct target, if they are in fact hyperlinked. it's better for a ref to go nowhere and be plain text than go to the wrong thing. Right now, hundreds of API links are pointing to the wrong thing as they are ambiguous names such as refresh(), insert(), update(), select(), join(), JSON etc. and Sphinx sends these all to essesntially random destinations among as many as five or six possible choices per symbol. A shorthand system that allows us to use absolute refs without having to type out a full blown absoulte module is the only way this is going to work, and we should ultimately seek to abandon any use of prefix dot for lookups. Everything should be on an underscore token so at the very least the module spaces can be reorganized without having to search and replace the entire documentation every time. Change-Id: I484a7329034af275fcdb322b62b6255dfeea9151
1 parent 1b1fe51 commit b99012d

36 files changed

Lines changed: 314 additions & 185 deletions

‎doc/build/changelog/changelog_07.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2578,7 +2578,7 @@
25782578

25792579
The behavior of =/!= when comparing a scalar select
25802580
to a value will no longer produce IN/NOT IN as of 0.8;
2581-
this behavior is a little too heavy handed (use in_() if
2581+
this behavior is a little too heavy handed (use ``in_()`` if
25822582
you want to emit IN) and now emits a deprecation warning.
25832583
To get the 0.8 behavior immediately and remove the warning,
25842584
a compiler recipe is given at

‎doc/build/changelog/changelog_08.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -356,9 +356,9 @@
356356
:tickets: 2957
357357
:versions: 0.9.3
358358

359-
Fixed bug where :meth:`.in_()` would go into an endless loop if
360-
erroneously passed a column expression whose comparator included
361-
the ``__getitem__()`` method, such as a column that uses the
359+
Fixed bug where :meth:`.ColumnOperators.in_()` would go into an endless
360+
loop if erroneously passed a column expression whose comparator
361+
included the ``__getitem__()`` method, such as a column that uses the
362362
:class:`.postgresql.ARRAY` type.
363363

364364
.. change::

‎doc/build/changelog/changelog_10.rst‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1006,8 +1006,8 @@
10061006
:tickets: 3459
10071007

10081008
Added a :meth:`.ColumnElement.cast` method which performs the same
1009-
purpose as the standalone :func:`.cast` function. Pull request
1010-
courtesy Sebastian Bank.
1009+
purpose as the standalone :func:`.expression.cast` function. Pull
1010+
request courtesy Sebastian Bank.
10111011

10121012
.. change::
10131013
:tags: bug, engine
@@ -1181,7 +1181,7 @@
11811181
Repaired the :class:`.ExcludeConstraint` construct to support common
11821182
features that other objects like :class:`.Index` now do, that
11831183
the column expression may be specified as an arbitrary SQL
1184-
expression such as :obj:`.cast` or :obj:`.text`.
1184+
expression such as :obj:`.expression.cast` or :obj:`.expression.text`.
11851185

11861186
.. change::
11871187
:tags: feature, postgresql
@@ -1206,14 +1206,13 @@
12061206
:tags: bug, orm
12071207
:tickets: 3448
12081208

1209-
Fixed an unexpected-use regression whereby custom :class:`.Comparator`
1210-
objects that made use of the ``__clause_element__()`` method and
1211-
returned an object that was an ORM-mapped
1212-
:class:`.InstrumentedAttribute` and not explicitly a
1213-
:class:`.ColumnElement` would fail to be correctly
1214-
handled when passed as an expression to :meth:`.Session.query`.
1215-
The logic in 0.9 happened to succeed on this, so this use case is now
1216-
supported.
1209+
Fixed an unexpected-use regression whereby custom
1210+
:class:`.types.TypeEngine.Comparator` objects that made use of the
1211+
``__clause_element__()`` method and returned an object that was an
1212+
ORM-mapped :class:`.InstrumentedAttribute` and not explicitly a
1213+
:class:`.ColumnElement` would fail to be correctly handled when passed
1214+
as an expression to :meth:`.Session.query`. The logic in 0.9 happened
1215+
to succeed on this, so this use case is now supported.
12171216

12181217
.. change::
12191218
:tags: bug, sql

‎doc/build/changelog/changelog_12.rst‎

Lines changed: 46 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -882,15 +882,15 @@
882882
:released: May 28, 2018
883883

884884
.. change::
885-
:tags: bug, orm
886-
:tickets: 4256
885+
:tags: bug, orm
886+
:tickets: 4256
887887

888-
Fixed regression in 1.2.7 caused by :ticket:`4228`, which itself was fixing
889-
a 1.2-level regression, where the ``query_cls`` callable passed to a
890-
:class:`.Session` was assumed to be a subclass of :class:`.Query` with
891-
class method availability, as opposed to an arbitrary callable. In
892-
particular, the dogpile caching example illustrates ``query_cls`` as a
893-
function and not a :class:`.Query` subclass.
888+
Fixed regression in 1.2.7 caused by :ticket:`4228`, which itself was fixing
889+
a 1.2-level regression, where the ``query_cls`` callable passed to a
890+
:class:`.Session` was assumed to be a subclass of :class:`.Query` with
891+
class method availability, as opposed to an arbitrary callable. In
892+
particular, the dogpile caching example illustrates ``query_cls`` as a
893+
function and not a :class:`.Query` subclass.
894894

895895
.. change::
896896
:tags: bug, engine
@@ -928,15 +928,15 @@
928928

929929

930930
.. change::
931-
:tags: bug, ext
932-
:tickets: 4247
931+
:tags: bug, ext
932+
:tickets: 4247
933933

934-
The horizontal sharding extension now makes use of the identity token
935-
added to ORM identity keys as part of :ticket:`4137`, when an object
936-
refresh or column-based deferred load or unexpiration operation occurs.
937-
Since we know the "shard" that the object originated from, we make
938-
use of this value when refreshing, thereby avoiding queries against
939-
other shards that don't match this object's identity in any case.
934+
The horizontal sharding extension now makes use of the identity token
935+
added to ORM identity keys as part of :ticket:`4137`, when an object
936+
refresh or column-based deferred load or unexpiration operation occurs.
937+
Since we know the "shard" that the object originated from, we make
938+
use of this value when refreshing, thereby avoiding queries against
939+
other shards that don't match this object's identity in any case.
940940

941941
.. change::
942942
:tags: bug, sql
@@ -1009,15 +1009,15 @@
10091009
of these issues as part of issue :ticket:`4258`.
10101010

10111011
.. change::
1012-
:tags: bug, ext
1013-
:tickets: 4266
1012+
:tags: bug, ext
1013+
:tickets: 4266
10141014

1015-
Fixed a race condition which could occur if automap
1016-
:meth:`.AutomapBase.prepare` were used within a multi-threaded context
1017-
against other threads which may call :func:`.configure_mappers` as a
1018-
result of use of other mappers. The unfinished mapping work of automap
1019-
is particularly sensitive to being pulled in by a
1020-
:func:`.configure_mappers` step leading to errors.
1015+
Fixed a race condition which could occur if automap
1016+
:meth:`.AutomapBase.prepare` were used within a multi-threaded context
1017+
against other threads which may call :func:`.configure_mappers` as a
1018+
result of use of other mappers. The unfinished mapping work of automap
1019+
is particularly sensitive to being pulled in by a
1020+
:func:`.configure_mappers` step leading to errors.
10211021

10221022
.. change::
10231023
:tags: bug, orm
@@ -1029,12 +1029,12 @@
10291029
the post criteria feature is now used by the lazy loader.
10301030

10311031
.. change::
1032-
:tags: bug, tests
1033-
:tickets: 4249
1032+
:tags: bug, tests
1033+
:tickets: 4249
10341034

1035-
Fixed a bug in the test suite where if an external dialect returned
1036-
``None`` for ``server_version_info``, the exclusion logic would raise an
1037-
``AttributeError``.
1035+
Fixed a bug in the test suite where if an external dialect returned
1036+
``None`` for ``server_version_info``, the exclusion logic would raise an
1037+
``AttributeError``.
10381038

10391039
.. change::
10401040
:tags: bug, orm
@@ -1954,18 +1954,18 @@
19541954
index implicitly added by Oracle onto the primary key columns.
19551955

19561956
.. change::
1957-
:tags: bug, orm
1958-
:tickets: 4071
1957+
:tags: bug, orm
1958+
:tickets: 4071
19591959

1960-
Removed the warnings that are emitted when the LRU caches employed
1961-
by the mapper as well as loader strategies reach their threshold; the
1962-
purpose of this warning was at first a guard against excess cache keys
1963-
being generated but became basically a check on the "creating many
1964-
engines" antipattern. While this is still an antipattern, the presence
1965-
of test suites which both create an engine per test as well as raise
1966-
on all warnings will be an inconvenience; it should not be critical
1967-
that such test suites change their architecture just for this warning
1968-
(though engine-per-test suite is always better).
1960+
Removed the warnings that are emitted when the LRU caches employed
1961+
by the mapper as well as loader strategies reach their threshold; the
1962+
purpose of this warning was at first a guard against excess cache keys
1963+
being generated but became basically a check on the "creating many
1964+
engines" antipattern. While this is still an antipattern, the presence
1965+
of test suites which both create an engine per test as well as raise
1966+
on all warnings will be an inconvenience; it should not be critical
1967+
that such test suites change their architecture just for this warning
1968+
(though engine-per-test suite is always better).
19691969

19701970
.. change::
19711971
:tags: bug, orm
@@ -2093,11 +2093,12 @@
20932093
Internal refinements to the :class:`.Enum`, :class:`.Interval`, and
20942094
:class:`.Boolean` types, which now extend a common mixin
20952095
:class:`.Emulated` that indicates a type that provides Python-side
2096-
emulation of a DB native type, switching out to the DB native type when a
2097-
supporting backend is in use. The PostgreSQL :class:`.INTERVAL` type
2098-
when used directly will now include the correct type coercion rules for
2099-
SQL expressions that also take effect for :class:`.sqltypes.Interval`
2100-
(such as adding a date to an interval yields a datetime).
2096+
emulation of a DB native type, switching out to the DB native type when
2097+
a supporting backend is in use. The PostgreSQL
2098+
:class:`.postgresql.INTERVAL` type when used directly will now include
2099+
the correct type coercion rules for SQL expressions that also take
2100+
effect for :class:`.sqltypes.Interval` (such as adding a date to an
2101+
interval yields a datetime).
21012102

21022103

21032104
.. change::

‎doc/build/changelog/migration_08.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -413,7 +413,7 @@ and :meth:`.PropComparator.has`::
413413

414414
.. seealso::
415415

416-
:ref:`of_type`
416+
:ref:`inheritance_of_type`
417417

418418
:ticket:`2438` :ticket:`1106`
419419

@@ -960,7 +960,7 @@ when features such as :meth:`.MetaData.create_all` and :func:`.cast` is used::
960960
:ticket:`2276`
961961

962962
"Prefixes" now supported for :func:`.update`, :func:`.delete`
963-
-------------------------------------------------------------
963+
----------------------------------------------------------------------------
964964

965965
Geared towards MySQL, a "prefix" can be rendered within any of
966966
these constructs. E.g.::

‎doc/build/changelog/migration_09.rst‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ accessor::
8383
.. _migration_2736:
8484

8585
:meth:`.Query.select_from` no longer applies the clause to corresponding entities
86-
---------------------------------------------------------------------------------
86+
-----------------------------------------------------------------------------------------------
8787

8888
The :meth:`.Query.select_from` method has been popularized in recent versions
8989
as a means of controlling the first thing that a :class:`.Query` object
@@ -564,8 +564,9 @@ by that of most database documentation::
564564
-- 0.9 behavior
565565
x = :x_1 COLLATE en_EN
566566

567-
The potentially backwards incompatible change arises if the :meth:`.collate`
568-
operator is being applied to the right-hand column, as follows::
567+
The potentially backwards incompatible change arises if the
568+
:meth:`.ColumnOperators.collate` operator is being applied to the right-hand
569+
column, as follows::
569570

570571
print(column('x') == literal('somevalue').collate("en_EN"))
571572

‎doc/build/changelog/migration_13.rst‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1321,13 +1321,12 @@ SQL text from being rendered directly.
13211321
"threadlocal" engine strategy deprecated
13221322
-----------------------------------------
13231323

1324-
The :ref:`"threadlocal" engine strategy <threadlocal_strategy>` was added
1325-
around SQLAlchemy 0.2, as a solution to the problem that the standard way of
1326-
operating in SQLAlchemy 0.1, which can be summed up as "threadlocal
1327-
everything", was found to be lacking. In retrospect, it seems fairly absurd
1328-
that by SQLAlchemy's first releases which were in every regard "alpha", that
1329-
there was concern that too many users had already settled on the existing API
1330-
to simply change it.
1324+
The "threadlocal engine strategy" was added around SQLAlchemy 0.2, as a
1325+
solution to the problem that the standard way of operating in SQLAlchemy 0.1,
1326+
which can be summed up as "threadlocal everything", was found to be lacking.
1327+
In retrospect, it seems fairly absurd that by SQLAlchemy's first releases which
1328+
were in every regard "alpha", that there was concern that too many users had
1329+
already settled on the existing API to simply change it.
13311330

13321331
The original usage model for SQLAlchemy looked like this::
13331332

‎doc/build/changelog/migration_14.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ What's New in SQLAlchemy 1.4?
2323
Behavioral Changes - General
2424
============================
2525

26-
.. _change_change_deferred_construction:
26+
.. _change_deferred_construction:
2727

2828

2929
Many Core and ORM statement objects now perform much of their validation in the compile phase

‎doc/build/changelog/migration_20.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -731,7 +731,7 @@ ORM Query Unified with Core Select
731731

732732
Tenative overall, however there will almost definitely be
733733
architectural changes in :class:`.Query` that move it closer to
734-
:meth:`.select`.
734+
:func:`.select`.
735735

736736
The ``session.query(<cls>)`` pattern itself will likely **not** be fully
737737
removed. As this pattern is extremely prevalent and numerous within any

‎doc/build/conf.py‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@
3737
"changelog",
3838
"sphinx_paramlinks",
3939
]
40+
needs_extensions = {"zzzeeksphinx": "1.1.2"}
4041

4142
# Add any paths that contain templates here, relative to this directory.
4243
# not sure why abspath() is needed here, some users
@@ -88,6 +89,9 @@
8889

8990
exclude_patterns = ["build", "**/unreleased*/*"]
9091

92+
# zzzeeksphinx makes these conversions when it is rendering the
93+
# docstrings classes, methods, and functions within the scope of
94+
# Sphinx autodoc
9195
autodocmods_convert_modname = {
9296
"sqlalchemy.sql.sqltypes": "sqlalchemy.types",
9397
"sqlalchemy.sql.type_api": "sqlalchemy.types",
@@ -97,15 +101,53 @@
97101
"sqlalchemy.sql.dml": "sqlalchemy.sql.expression",
98102
"sqlalchemy.sql.ddl": "sqlalchemy.schema",
99103
"sqlalchemy.sql.base": "sqlalchemy.sql.expression",
104+
"sqlalchemy.event.base": "sqlalchemy.event",
100105
"sqlalchemy.engine.base": "sqlalchemy.engine",
101106
"sqlalchemy.engine.result": "sqlalchemy.engine",
107+
"sqlalchemy.util._collections": "sqlalchemy.util",
102108
}
103109

104110
autodocmods_convert_modname_w_class = {
105111
("sqlalchemy.engine.interfaces", "Connectable"): "sqlalchemy.engine",
106112
("sqlalchemy.sql.base", "DialectKWArgs"): "sqlalchemy.sql.base",
107113
}
108114

115+
# on the referencing side, a newer zzzeeksphinx extension
116+
# applies shorthand symbols to references so that we can have short
117+
# names that are still using absolute references.
118+
zzzeeksphinx_module_prefixes = {
119+
"_sa": "sqlalchemy",
120+
"_engine": "sqlalchemy.engine",
121+
"_schema": "sqlalchemy.schema",
122+
"_types": "sqlalchemy.types",
123+
"_expression": "sqlalchemy.sql.expression",
124+
"_functions": "sqlalchemy.sql.functions",
125+
"_pool": "sqlalchemy.pool",
126+
"_event": "sqlalchemy.event",
127+
"_events": "sqlalchemy.events",
128+
"_exc": "sqlalchemy.exc",
129+
"_reflection": "sqlalchemy.engine.reflection",
130+
"_orm": "sqlalchemy.orm",
131+
"_query": "sqlalchemy.orm.query",
132+
"_ormevent": "sqlalchemy.orm.event",
133+
"_ormexc": "sqlalchemy.orm.exc",
134+
"_baked": "sqlalchemy.ext.baked",
135+
"_associationproxy": "sqlalchemy.ext.associationproxy",
136+
"_automap": "sqlalchemy.ext.automap",
137+
"_hybrid": "sqlalchemy.ext.hybrid",
138+
"_compilerext": "sqlalchemy.ext.compiler",
139+
"_mutable": "sqlalchemy.ext.mutable",
140+
"_declarative": "sqlalchemy.ext.declarative",
141+
"_future": "sqlalchemy.future",
142+
"_futureorm": "sqlalchemy.future.orm",
143+
"_postgresql": "sqlalchemy.dialects.postgresql",
144+
"_mysql": "sqlalchemy.dialects.mysql",
145+
"_mssql": "sqlalchemy.dialects.mssql",
146+
"_oracle": "sqlalchemy.dialects.oracle",
147+
"_sqlite": "sqlalchemy.dialects.sqlite",
148+
}
149+
150+
109151
# The encoding of source files.
110152
# source_encoding = 'utf-8-sig'
111153

0 commit comments

Comments
 (0)