From: Mike Bayer Date: Sun, 12 Apr 2020 19:18:02 +0000 (-0400) Subject: Enable zzzeeksphinx module prefixes X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=6a26da0efb1d18936dd036986d8aa3e0ba99b56e;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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 (cherry picked from commit d8d755ad619e2ee78f2c7cb60ae9a1feee4c6d76) (cherry picked from commit 8f992000a4ed59d5f91796cef5cec7697ce464fc) --- diff --git a/doc/build/Makefile b/doc/build/Makefile index 58fdc6c162..2a0216b781 100644 --- a/doc/build/Makefile +++ b/doc/build/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = -j auto -v +SPHINXOPTS = -j auto SPHINXBUILD = sphinx-build PAPER = BUILDDIR = output diff --git a/doc/build/changelog/changelog_07.rst b/doc/build/changelog/changelog_07.rst index f921d29491..43ae2fe0d3 100644 --- a/doc/build/changelog/changelog_07.rst +++ b/doc/build/changelog/changelog_07.rst @@ -2578,7 +2578,7 @@ The behavior of =/!= when comparing a scalar select to a value will no longer produce IN/NOT IN as of 0.8; - this behavior is a little too heavy handed (use in_() if + this behavior is a little too heavy handed (use ``in_()`` if you want to emit IN) and now emits a deprecation warning. To get the 0.8 behavior immediately and remove the warning, a compiler recipe is given at diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst index e50b140ac6..508669d3c8 100644 --- a/doc/build/changelog/changelog_08.rst +++ b/doc/build/changelog/changelog_08.rst @@ -356,9 +356,9 @@ :tickets: 2957 :versions: 0.9.3 - Fixed bug where :meth:`.in_()` would go into an endless loop if - erroneously passed a column expression whose comparator included - the ``__getitem__()`` method, such as a column that uses the + Fixed bug where :meth:`.ColumnOperators.in_()` would go into an endless + loop if erroneously passed a column expression whose comparator + included the ``__getitem__()`` method, such as a column that uses the :class:`.postgresql.ARRAY` type. .. change:: diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst index 3437b74f4d..a47d612abf 100644 --- a/doc/build/changelog/changelog_10.rst +++ b/doc/build/changelog/changelog_10.rst @@ -1006,8 +1006,8 @@ :tickets: 3459 Added a :meth:`.ColumnElement.cast` method which performs the same - purpose as the standalone :func:`.cast` function. Pull request - courtesy Sebastian Bank. + purpose as the standalone :func:`.expression.cast` function. Pull + request courtesy Sebastian Bank. .. change:: :tags: bug, engine @@ -1181,7 +1181,7 @@ Repaired the :class:`.ExcludeConstraint` construct to support common features that other objects like :class:`.Index` now do, that the column expression may be specified as an arbitrary SQL - expression such as :obj:`.cast` or :obj:`.text`. + expression such as :obj:`.expression.cast` or :obj:`.expression.text`. .. change:: :tags: feature, postgresql @@ -1206,14 +1206,13 @@ :tags: bug, orm :tickets: 3448 - Fixed an unexpected-use regression whereby custom :class:`.Comparator` - objects that made use of the ``__clause_element__()`` method and - returned an object that was an ORM-mapped - :class:`.InstrumentedAttribute` and not explicitly a - :class:`.ColumnElement` would fail to be correctly - handled when passed as an expression to :meth:`.Session.query`. - The logic in 0.9 happened to succeed on this, so this use case is now - supported. + Fixed an unexpected-use regression whereby custom + :class:`.types.TypeEngine.Comparator` objects that made use of the + ``__clause_element__()`` method and returned an object that was an + ORM-mapped :class:`.InstrumentedAttribute` and not explicitly a + :class:`.ColumnElement` would fail to be correctly handled when passed + as an expression to :meth:`.Session.query`. The logic in 0.9 happened + to succeed on this, so this use case is now supported. .. change:: :tags: bug, sql diff --git a/doc/build/changelog/changelog_12.rst b/doc/build/changelog/changelog_12.rst index d7eece95c9..a8fb55ba3d 100644 --- a/doc/build/changelog/changelog_12.rst +++ b/doc/build/changelog/changelog_12.rst @@ -882,15 +882,15 @@ :released: May 28, 2018 .. change:: - :tags: bug, orm - :tickets: 4256 + :tags: bug, orm + :tickets: 4256 - Fixed regression in 1.2.7 caused by :ticket:`4228`, which itself was fixing - a 1.2-level regression, where the ``query_cls`` callable passed to a - :class:`.Session` was assumed to be a subclass of :class:`.Query` with - class method availability, as opposed to an arbitrary callable. In - particular, the dogpile caching example illustrates ``query_cls`` as a - function and not a :class:`.Query` subclass. + Fixed regression in 1.2.7 caused by :ticket:`4228`, which itself was fixing + a 1.2-level regression, where the ``query_cls`` callable passed to a + :class:`.Session` was assumed to be a subclass of :class:`.Query` with + class method availability, as opposed to an arbitrary callable. In + particular, the dogpile caching example illustrates ``query_cls`` as a + function and not a :class:`.Query` subclass. .. change:: :tags: bug, engine @@ -928,15 +928,15 @@ .. change:: - :tags: bug, ext - :tickets: 4247 + :tags: bug, ext + :tickets: 4247 - The horizontal sharding extension now makes use of the identity token - added to ORM identity keys as part of :ticket:`4137`, when an object - refresh or column-based deferred load or unexpiration operation occurs. - Since we know the "shard" that the object originated from, we make - use of this value when refreshing, thereby avoiding queries against - other shards that don't match this object's identity in any case. + The horizontal sharding extension now makes use of the identity token + added to ORM identity keys as part of :ticket:`4137`, when an object + refresh or column-based deferred load or unexpiration operation occurs. + Since we know the "shard" that the object originated from, we make + use of this value when refreshing, thereby avoiding queries against + other shards that don't match this object's identity in any case. .. change:: :tags: bug, sql @@ -1009,15 +1009,15 @@ of these issues as part of issue :ticket:`4258`. .. change:: - :tags: bug, ext - :tickets: 4266 + :tags: bug, ext + :tickets: 4266 - Fixed a race condition which could occur if automap - :meth:`.AutomapBase.prepare` were used within a multi-threaded context - against other threads which may call :func:`.configure_mappers` as a - result of use of other mappers. The unfinished mapping work of automap - is particularly sensitive to being pulled in by a - :func:`.configure_mappers` step leading to errors. + Fixed a race condition which could occur if automap + :meth:`.AutomapBase.prepare` were used within a multi-threaded context + against other threads which may call :func:`.configure_mappers` as a + result of use of other mappers. The unfinished mapping work of automap + is particularly sensitive to being pulled in by a + :func:`.configure_mappers` step leading to errors. .. change:: :tags: bug, orm @@ -1029,12 +1029,12 @@ the post criteria feature is now used by the lazy loader. .. change:: - :tags: bug, tests - :tickets: 4249 + :tags: bug, tests + :tickets: 4249 - Fixed a bug in the test suite where if an external dialect returned - ``None`` for ``server_version_info``, the exclusion logic would raise an - ``AttributeError``. + Fixed a bug in the test suite where if an external dialect returned + ``None`` for ``server_version_info``, the exclusion logic would raise an + ``AttributeError``. .. change:: :tags: bug, orm @@ -1954,18 +1954,18 @@ index implicitly added by Oracle onto the primary key columns. .. change:: - :tags: bug, orm - :tickets: 4071 + :tags: bug, orm + :tickets: 4071 - Removed the warnings that are emitted when the LRU caches employed - by the mapper as well as loader strategies reach their threshold; the - purpose of this warning was at first a guard against excess cache keys - being generated but became basically a check on the "creating many - engines" antipattern. While this is still an antipattern, the presence - of test suites which both create an engine per test as well as raise - on all warnings will be an inconvenience; it should not be critical - that such test suites change their architecture just for this warning - (though engine-per-test suite is always better). + Removed the warnings that are emitted when the LRU caches employed + by the mapper as well as loader strategies reach their threshold; the + purpose of this warning was at first a guard against excess cache keys + being generated but became basically a check on the "creating many + engines" antipattern. While this is still an antipattern, the presence + of test suites which both create an engine per test as well as raise + on all warnings will be an inconvenience; it should not be critical + that such test suites change their architecture just for this warning + (though engine-per-test suite is always better). .. change:: :tags: bug, orm @@ -2093,11 +2093,12 @@ Internal refinements to the :class:`.Enum`, :class:`.Interval`, and :class:`.Boolean` types, which now extend a common mixin :class:`.Emulated` that indicates a type that provides Python-side - emulation of a DB native type, switching out to the DB native type when a - supporting backend is in use. The PostgreSQL :class:`.INTERVAL` type - when used directly will now include the correct type coercion rules for - SQL expressions that also take effect for :class:`.sqltypes.Interval` - (such as adding a date to an interval yields a datetime). + emulation of a DB native type, switching out to the DB native type when + a supporting backend is in use. The PostgreSQL + :class:`.postgresql.INTERVAL` type when used directly will now include + the correct type coercion rules for SQL expressions that also take + effect for :class:`.sqltypes.Interval` (such as adding a date to an + interval yields a datetime). .. change:: diff --git a/doc/build/changelog/migration_08.rst b/doc/build/changelog/migration_08.rst index f0661c4fc1..a569126548 100644 --- a/doc/build/changelog/migration_08.rst +++ b/doc/build/changelog/migration_08.rst @@ -413,7 +413,7 @@ and :meth:`.PropComparator.has`:: .. seealso:: - :ref:`of_type` + :ref:`inheritance_of_type` :ticket:`2438` :ticket:`1106` @@ -960,7 +960,7 @@ when features such as :meth:`.MetaData.create_all` and :func:`.cast` is used:: :ticket:`2276` "Prefixes" now supported for :func:`.update`, :func:`.delete` -------------------------------------------------------------- +---------------------------------------------------------------------------- Geared towards MySQL, a "prefix" can be rendered within any of these constructs. E.g.:: diff --git a/doc/build/changelog/migration_09.rst b/doc/build/changelog/migration_09.rst index 49db699376..16a0a3c8c8 100644 --- a/doc/build/changelog/migration_09.rst +++ b/doc/build/changelog/migration_09.rst @@ -83,7 +83,7 @@ accessor:: .. _migration_2736: :meth:`.Query.select_from` no longer applies the clause to corresponding entities ---------------------------------------------------------------------------------- +----------------------------------------------------------------------------------------------- The :meth:`.Query.select_from` method has been popularized in recent versions as a means of controlling the first thing that a :class:`.Query` object @@ -564,8 +564,9 @@ by that of most database documentation:: -- 0.9 behavior x = :x_1 COLLATE en_EN -The potentially backwards incompatible change arises if the :meth:`.collate` -operator is being applied to the right-hand column, as follows:: +The potentially backwards incompatible change arises if the +:meth:`.ColumnOperators.collate` operator is being applied to the right-hand +column, as follows:: print(column('x') == literal('somevalue').collate("en_EN")) diff --git a/doc/build/conf.py b/doc/build/conf.py index be448ad1c2..9c6305de88 100644 --- a/doc/build/conf.py +++ b/doc/build/conf.py @@ -11,51 +11,61 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys import os +import sys # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('../../lib')) -sys.path.insert(0, os.path.abspath('../..')) # examples -sys.path.insert(0, os.path.abspath('.')) - -import sqlalchemy +sys.path.insert(0, os.path.abspath("../../lib")) +sys.path.insert(0, os.path.abspath("../..")) # examples +sys.path.insert(0, os.path.abspath(".")) # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.6.0' +needs_sphinx = "1.6.0" # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ - 'sphinx.ext.autodoc', - 'zzzeeksphinx', - 'changelog', - 'sphinx_paramlinks', - ] + "sphinx.ext.autodoc", + "zzzeeksphinx", + "changelog", + "sphinx_paramlinks", +] +needs_extensions = {"zzzeeksphinx": "1.1.2"} # Add any paths that contain templates here, relative to this directory. # not sure why abspath() is needed here, some users # have reported this. -templates_path = [os.path.abspath('templates')] +templates_path = [os.path.abspath("templates")] -nitpicky = True +nitpicky = False # The suffix of source filenames. -source_suffix = '.rst' +source_suffix = ".rst" # section names used by the changelog extension. -changelog_sections = ["general", "orm", "orm declarative", "orm querying", \ - "orm configuration", "engine", "sql", \ - "schema", \ - "postgresql", "mysql", "sqlite", "mssql", \ - "oracle", "firebird"] +changelog_sections = [ + "general", + "orm", + "orm declarative", + "orm querying", + "orm configuration", + "engine", + "sql", + "schema", + "postgresql", + "mysql", + "sqlite", + "mssql", + "oracle", + "firebird", +] # tags to sort on inside of sections changelog_inner_tag_sort = ["feature", "changed", "removed", "bug", "moved"] @@ -70,10 +80,13 @@ changelog_render_pullreq = { changelog_render_changeset = "http://www.sqlalchemy.org/trac/changeset/%s" exclude_patterns = [ - 'build', - '**/unreleased*/*', + "build", + "**/unreleased*/*", ] +# zzzeeksphinx makes these conversions when it is rendering the +# docstrings classes, methods, and functions within the scope of +# Sphinx autodoc autodocmods_convert_modname = { "sqlalchemy.sql.sqltypes": "sqlalchemy.types", "sqlalchemy.sql.type_api": "sqlalchemy.types", @@ -83,8 +96,10 @@ autodocmods_convert_modname = { "sqlalchemy.sql.dml": "sqlalchemy.sql.expression", "sqlalchemy.sql.ddl": "sqlalchemy.schema", "sqlalchemy.sql.base": "sqlalchemy.sql.expression", + "sqlalchemy.event.base": "sqlalchemy.event", "sqlalchemy.engine.base": "sqlalchemy.engine", "sqlalchemy.engine.result": "sqlalchemy.engine", + "sqlalchemy.util._collections": "sqlalchemy.util", } autodocmods_convert_modname_w_class = { @@ -92,15 +107,51 @@ autodocmods_convert_modname_w_class = { ("sqlalchemy.sql.base", "DialectKWArgs"): "sqlalchemy.sql.base", } +# on the referencing side, a newer zzzeeksphinx extension +# applies shorthand symbols to references so that we can have short +# names that are still using absolute references. +zzzeeksphinx_module_prefixes = { + "_sa": "sqlalchemy", + "_engine": "sqlalchemy.engine", + "_schema": "sqlalchemy.schema", + "_types": "sqlalchemy.types", + "_expression": "sqlalchemy.sql.expression", + "_functions": "sqlalchemy.sql.functions", + "_pool": "sqlalchemy.pool", + "_event": "sqlalchemy.event", + "_events": "sqlalchemy.events", + "_exc": "sqlalchemy.exc", + "_reflection": "sqlalchemy.engine.reflection", + "_orm": "sqlalchemy.orm", + "_query": "sqlalchemy.orm.query", + "_ormevent": "sqlalchemy.orm.event", + "_ormexc": "sqlalchemy.orm.exc", + "_baked": "sqlalchemy.ext.baked", + "_associationproxy": "sqlalchemy.ext.associationproxy", + "_automap": "sqlalchemy.ext.automap", + "_hybrid": "sqlalchemy.ext.hybrid", + "_compilerext": "sqlalchemy.ext.compiler", + "_mutable": "sqlalchemy.ext.mutable", + "_declarative": "sqlalchemy.ext.declarative", + "_future": "sqlalchemy.future", + "_futureorm": "sqlalchemy.future.orm", + "_postgresql": "sqlalchemy.dialects.postgresql", + "_mysql": "sqlalchemy.dialects.mysql", + "_mssql": "sqlalchemy.dialects.mssql", + "_oracle": "sqlalchemy.dialects.oracle", + "_sqlite": "sqlalchemy.dialects.sqlite", +} + + # The encoding of source files. -#source_encoding = 'utf-8-sig' +# source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'contents' +master_doc = "contents" # General information about the project. -project = u'SQLAlchemy' -copyright = u'2007-2019, the SQLAlchemy authors and contributors' +project = u"SQLAlchemy" +copyright = u"2007-2019, the SQLAlchemy authors and contributors" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -123,33 +174,33 @@ build_number = "3" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +# language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# today_fmt = '%B %d, %Y' # The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None +# default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +# modindex_common_prefix = [] # have the "gettext" build generate .pot for each individual # .rst @@ -159,36 +210,36 @@ gettext_compact = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'zzzeeksphinx' +html_theme = "zzzeeksphinx" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +# html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +# html_theme_path = [] # The style sheet to use for HTML and HTML Help pages. A file of that name # must exist either in Sphinx' static/ path, or in one of the custom paths # given in html_static_path. -html_style = 'default.css' +html_style = "default.css" # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". html_title = "%s %s Documentation" % (project, version) # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +# html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +# html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +# html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -197,148 +248,154 @@ html_static_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -html_last_updated_fmt = '%m/%d/%Y %H:%M:%S' +html_last_updated_fmt = "%m/%d/%Y %H:%M:%S" # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -html_additional_pages = { - "notfound": "notfound.html" -} +html_additional_pages = {"notfound": "notfound.html"} # If false, no module index is generated. html_domain_indices = False # If false, no index is generated. -#html_use_index = True +# html_use_index = True # If true, the index is split into individual pages for each letter. -#html_split_index = False +# html_split_index = False # If true, the reST sources are included in the HTML build as _sources/. -#html_copy_source = True +# html_copy_source = True html_copy_source = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +# html_show_sourcelink = True html_show_sourcelink = False # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +# html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. -#html_use_opensearch = '' +# html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'SQLAlchemydoc' +htmlhelp_basename = "SQLAlchemydoc" -#autoclass_content = 'both' +# autoclass_content = 'both' # -- Options for LaTeX output -------------------------------------------------- # The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' +# latex_paper_size = 'letter' # The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' +# latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('contents', 'sqlalchemy_%s.tex' % release.replace('.', '_'), 'SQLAlchemy Documentation', - 'Mike Bayer', 'manual'), + ( + "contents", + "sqlalchemy_%s.tex" % release.replace(".", "_"), + "SQLAlchemy Documentation", + "Mike Bayer", + "manual", + ), ] # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +# latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +# latex_use_parts = False # If true, show page references after internal links. -#latex_show_pagerefs = False +# latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +# latex_show_urls = False # Additional stuff for the LaTeX preamble. # sets TOC depth to 2. -latex_preamble = '\setcounter{tocdepth}{3}' +latex_preamble = "\setcounter{tocdepth}{3}" # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True +# latex_domain_indices = True -#latex_elements = { +# latex_elements = { # 'papersize': 'letterpaper', # 'pointsize': '10pt', -#} +# } # -- Options for manual page output -------------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'sqlalchemy', u'SQLAlchemy Documentation', - [u'SQLAlchemy authors'], 1) + ( + "index", + "sqlalchemy", + u"SQLAlchemy Documentation", + [u"SQLAlchemy authors"], + 1, + ) ] # -- Options for Epub output --------------------------------------------------- # Bibliographic Dublin Core info. -epub_title = u'SQLAlchemy' -epub_author = u'SQLAlchemy authors' -epub_publisher = u'SQLAlchemy authors' -epub_copyright = u'2007-2015, SQLAlchemy authors' +epub_title = u"SQLAlchemy" +epub_author = u"SQLAlchemy authors" +epub_publisher = u"SQLAlchemy authors" +epub_copyright = u"2007-2015, SQLAlchemy authors" # The language of the text. It defaults to the language option # or en if the language is not set. -#epub_language = '' +# epub_language = '' # The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' +# epub_scheme = '' # The unique identifier of the text. This can be a ISBN number # or the project homepage. -#epub_identifier = '' +# epub_identifier = '' # A unique identification for the text. -#epub_uid = '' +# epub_uid = '' # HTML files that should be inserted before the pages created by sphinx. # The format is a list of tuples containing the path and title. -#epub_pre_files = [] +# epub_pre_files = [] # HTML files that should be inserted after the pages created by sphinx. # The format is a list of tuples containing the path and title. -#epub_post_files = [] +# epub_post_files = [] # A list of files that should not be packed into the epub file. -#epub_exclude_files = [] +# epub_exclude_files = [] # The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 +# epub_tocdepth = 3 # Allow duplicate toc entries. -#epub_tocdup = True - - +# epub_tocdup = True diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 269bc0ff5e..ad51b86fb1 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -103,6 +103,7 @@ The :meth:`~.Connection.execute` method can of course accommodate more than that, including the variety of SQL expression constructs described in :ref:`sqlexpression_toplevel`. + Using Transactions ================== diff --git a/doc/build/core/dml.rst b/doc/build/core/dml.rst index 51c9a2f1cd..96a1700d93 100644 --- a/doc/build/core/dml.rst +++ b/doc/build/core/dml.rst @@ -16,19 +16,29 @@ constructs build on the intermediary :class:`.ValuesBase`. .. autoclass:: Delete :members: - :inherited-members: + + .. automethod:: Delete.where + + .. automethod:: Delete.returning .. autoclass:: Insert :members: - :inherited-members: + + .. automethod:: Insert.values + + .. automethod:: Insert.returning .. autoclass:: Update - :members: - :inherited-members: + :members: + + .. automethod:: Update.returning + + .. automethod:: Update.where + + .. automethod:: Update.values .. autoclass:: sqlalchemy.sql.expression.UpdateBase - :members: - :inherited-members: + :members: .. autoclass:: sqlalchemy.sql.expression.ValuesBase :members: diff --git a/doc/build/core/inspection.rst b/doc/build/core/inspection.rst index 313b4d6e72..01343102d9 100644 --- a/doc/build/core/inspection.rst +++ b/doc/build/core/inspection.rst @@ -5,7 +5,9 @@ Runtime Inspection API ====================== .. automodule:: sqlalchemy.inspection - :members: + +.. autofunction:: sqlalchemy.inspect + Available Inspection Targets ---------------------------- diff --git a/doc/build/core/selectable.rst b/doc/build/core/selectable.rst index 8952daec5e..2931d98fa0 100644 --- a/doc/build/core/selectable.rst +++ b/doc/build/core/selectable.rst @@ -83,14 +83,16 @@ elements are themselves :class:`.ColumnElement` subclasses). .. autoclass:: Select :members: - :inherited-members: + :inherited-members: ClauseElement + :exclude-members: memoized_attribute, memoized_instancemethod .. autoclass:: Selectable :members: .. autoclass:: SelectBase :members: - :inherited-members: + :inherited-members: ClauseElement + :exclude-members: memoized_attribute, memoized_instancemethod .. autoclass:: TableClause :members: diff --git a/doc/build/faq/metadata_schema.rst b/doc/build/faq/metadata_schema.rst index e15a537890..ce7648ac77 100644 --- a/doc/build/faq/metadata_schema.rst +++ b/doc/build/faq/metadata_schema.rst @@ -50,7 +50,7 @@ Does SQLAlchemy support ALTER TABLE, CREATE VIEW, CREATE TRIGGER, Schema Upgrade General ALTER support isn't present in SQLAlchemy directly. For special DDL on an ad-hoc basis, the :class:`.DDL` and related constructs can be used. -See :doc:`core/ddl` for a discussion on this subject. +See :ref:`metadata_ddl_toplevel` for a discussion on this subject. A more comprehensive option is to use schema migration tools, such as Alembic or SQLAlchemy-Migrate; see :ref:`schema_migrations` for discussion on this. diff --git a/doc/build/faq/performance.rst b/doc/build/faq/performance.rst index c30e96abba..540965fe49 100644 --- a/doc/build/faq/performance.rst +++ b/doc/build/faq/performance.rst @@ -212,7 +212,7 @@ the profiling output of this intentionally slow operation can be seen like this: that is, we see many expensive calls within the ``type_api`` system, and the actual time consuming thing is the ``time.sleep()`` call. -Make sure to check the :doc:`Dialect documentation ` +Make sure to check the :ref:`Dialect documentation ` for notes on known performance tuning suggestions at this level, especially for databases like Oracle. There may be systems related to ensuring numeric accuracy or string processing that may not be needed in all cases. @@ -295,14 +295,14 @@ ORM as a first-class component. For the use case of fast bulk inserts, the SQL generation and execution system that the ORM builds on top of -is part of the :doc:`Core `. Using this system directly, we can produce an INSERT that +is part of the :ref:`Core `. Using this system directly, we can produce an INSERT that is competitive with using the raw database API directly. .. note:: - When using the psycopg2 dialect, consider making use of the - :ref:`batch execution helpers ` feature of psycopg2, - now supported directly by the SQLAlchemy psycopg2 dialect. + When using the psycopg2 dialect, consider making use of the :ref:`batch + execution helpers ` feature of psycopg2, now + supported directly by the SQLAlchemy psycopg2 dialect. Alternatively, the SQLAlchemy ORM offers the :ref:`bulk_operations` suite of methods, which provide hooks into subsections of the unit of diff --git a/doc/build/orm/extensions/declarative/inheritance.rst b/doc/build/orm/extensions/declarative/inheritance.rst index f234106833..b988438165 100644 --- a/doc/build/orm/extensions/declarative/inheritance.rst +++ b/doc/build/orm/extensions/declarative/inheritance.rst @@ -248,4 +248,3 @@ on concrete inheritance for details. :ref:`concrete_inheritance` - :ref:`inheritance_concrete_helpers` diff --git a/doc/build/orm/join_conditions.rst b/doc/build/orm/join_conditions.rst index 13bdd63e6f..983e53bacb 100644 --- a/doc/build/orm/join_conditions.rst +++ b/doc/build/orm/join_conditions.rst @@ -663,6 +663,8 @@ complexity is kept within the middle. .. _relationship_non_primary_mapper: +.. _relationship_aliased_class: + Relationship to Non Primary Mapper ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/build/orm/mapping_api.rst b/doc/build/orm/mapping_api.rst index 99e0ba52d4..250bd26a48 100644 --- a/doc/build/orm/mapping_api.rst +++ b/doc/build/orm/mapping_api.rst @@ -15,8 +15,8 @@ Class Mapping API .. autofunction:: sqlalchemy.orm.util.identity_key -.. autofunction:: sqlalchemy.orm.util.polymorphic_union +.. autofunction:: polymorphic_union -.. autoclass:: sqlalchemy.orm.mapper.Mapper +.. autoclass:: Mapper :members: diff --git a/doc/build/orm/session_state_management.rst b/doc/build/orm/session_state_management.rst index 2730bb8b23..8b4d7a572f 100644 --- a/doc/build/orm/session_state_management.rst +++ b/doc/build/orm/session_state_management.rst @@ -543,8 +543,8 @@ or loaded with :meth:`~.Session.refresh` varies based on several factors, includ expired column-based attributes being accessed. * Regarding relationships, :meth:`~.Session.refresh` is more restrictive than - :meth:`~.Session.expire` with regards to attributes that aren't column-mapped. - Calling :meth:`.refresh` and passing a list of names that only includes + :meth:`.Session.expire` with regards to attributes that aren't column-mapped. + Calling :meth:`.Session.refresh` and passing a list of names that only includes relationship-mapped attributes will actually raise an error. In any case, non-eager-loading :func:`.relationship` attributes will not be included in any refresh operation. @@ -620,7 +620,7 @@ The second bullet has the important caveat that "it is also known that the isola allow this data to be visible." This means that it cannot be assumed that an UPDATE that happened on another database connection will yet be visible here locally; in many cases, it will not. This is why if one wishes to use -:meth:`.expire` or :meth:`.refresh` in order to view data between ongoing +:meth:`.Session.expire` or :meth:`.Session.refresh` in order to view data between ongoing transactions, an understanding of the isolation behavior in effect is essential. .. seealso:: diff --git a/doc/build/replacments/fix_xref_state.txt b/doc/build/replacments/fix_xref_state.txt new file mode 100644 index 0000000000..380657df2e --- /dev/null +++ b/doc/build/replacments/fix_xref_state.txt @@ -0,0 +1,93 @@ +.MetaData _schema.MetaData +.ForeignKey _schema.ForeignKey +.ForeignKeyConstraint _schema.ForeignKeyConstraint +.PoolEvents _events.PoolEvents +.DisconnectionError _exc.DisconnectionError +.SADeprecationWarning _exc.SADeprecationWarning +.Engine _engine.Engine +.Pool _pool.Pool +.future _future +.inspect _sa.inspect +.Inspector _reflection.Inspector +.orm _orm +.Mapper _orm.Mapper +.engine _engine +.JSON _types.JSON +.postgresql _postgresql +.types _types +._mysql _mysql +.sqlite _sqlite +.array_agg _functions.array_agg +.TIMESTAMP _types.TIMESTAMP +.JSONB _postgresql.JSONB +.ARRAY _types.ARRAY +.mssql _mssql +.sqltypes _types +.functions _functions +.INTERVAL _postgresql.INTERVAL +.INTERVAL _oracle.INTERVAL +.oracle _oracle +.NCHAR _types.NCHAR +.Query _query.Query +.relationship _orm.relationship +.FromClause _expression.FromClause +.join _expression.join +.SelectBase _expression.SelectBase +.Load _orm.Load +.joinedload _orm.joinedload +.sql _expression +.sql.expression _expression +.INTEGER _types.INTEGER +.VARBINARY _types.VARBINARY +.joinedload_all _orm.joinedload_all +.Insert _expression.Insert +.Update _expression.Update +.Delete _expression.Delete +.insert _expression.insert +.update _expression.update +.delete _expression.delete +.select _expression.select +.expression _expression +.future _future.Subquery _expression.Subquery +.Select _expression.Select +.ReturnsRows _expression.ReturnsRows +.ColumnCollection _expression.ColumnCollection +.ColumnElement _expression.ColumnElement +.Selectable expression.Selectable +.Lateral _expression.Lateral +.HasPrefixes _expression.HasPrefixes +.prefix_with _expression.HasPrefixes.prefix_with +.ClauseElement _expression.ClauseElement +.HasSuffixes _expression.HasSuffixes +.suffix_with _expression.HasSuffixes.suffix_with +.Table _schema.Table +.Join _expression.Join +.Alias _expression.Alias +.TableSample _expression.TableSample +.CTE _expression.CTE +.HasCte _expression.HasCTE +.HasCTE _expression.HasCTE +.CompoundSelect _selectable.CompoundSelect +.TextualSelect _expression.TextualSelect +.TableClause _expression.TableClause +.schema _schema +.Values _expression.Values +.column _expression.column +.GenerativeSelect _expression.GenerativeSelect +.Column _schema.Column +.union _expression.union +.union_all _expression.union_all +.intersect _expression.intersect +.intersect_all _expression.intersect_all +.except _expression.except +.except_all _expression.except_all +.Text _expression.TextClause +.text _expression.text +.literal_column _expression.literal_column +.Connection _engine.Connection +.Engine _engine.Engine +.apply_labels _expression.Select.apply_labels +.BooleanClauseList _expression.BooleanClauseList +.ScalarSelect _expression.ScalarSelect +.Exists _expression.Exists +.TextClause _expression.TextClause diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py index 2a9307e4f4..4ef7836320 100644 --- a/lib/sqlalchemy/dialects/mssql/base.py +++ b/lib/sqlalchemy/dialects/mssql/base.py @@ -326,9 +326,10 @@ behavior of this flag is as follows: * Complete control over whether the "old" or "new" types are rendered is available in all SQLAlchemy versions by using the UPPERCASE type objects - instead: :class:`.NVARCHAR`, :class:`.VARCHAR`, :class:`.types.VARBINARY`, - :class:`.TEXT`, :class:`.mssql.NTEXT`, :class:`.mssql.IMAGE` will always - remain fixed and always output exactly that type. + instead: :class:`.types.NVARCHAR`, :class:`.types.VARCHAR`, + :class:`.types.VARBINARY`, :class:`.types.TEXT`, :class:`.mssql.NTEXT`, + :class:`.mssql.IMAGE` will always remain fixed and always output exactly that + type. .. versionadded:: 1.0.0 diff --git a/lib/sqlalchemy/ext/associationproxy.py b/lib/sqlalchemy/ext/associationproxy.py index 5ab76857b8..73b5aa1606 100644 --- a/lib/sqlalchemy/ext/associationproxy.py +++ b/lib/sqlalchemy/ext/associationproxy.py @@ -81,7 +81,7 @@ def association_proxy(target_collection, attr, **kw): ASSOCIATION_PROXY = util.symbol("ASSOCIATION_PROXY") -"""Symbol indicating an :class:`InspectionAttr` that's +"""Symbol indicating an :class:`.InspectionAttr` that's of type :class:`.AssociationProxy`. Is assigned to the :attr:`.InspectionAttr.extension_type` diff --git a/lib/sqlalchemy/ext/declarative/api.py b/lib/sqlalchemy/ext/declarative/api.py index 5c92060535..ea357ae69a 100644 --- a/lib/sqlalchemy/ext/declarative/api.py +++ b/lib/sqlalchemy/ext/declarative/api.py @@ -461,8 +461,6 @@ class ConcreteBase(object): :ref:`concrete_inheritance` - :ref:`inheritance_concrete_helpers` - """ @@ -571,8 +569,6 @@ class AbstractConcreteBase(ConcreteBase): :ref:`concrete_inheritance` - :ref:`inheritance_concrete_helpers` - """ __no_table__ = True diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py index 88f4e305bf..9edb815060 100644 --- a/lib/sqlalchemy/orm/attributes.py +++ b/lib/sqlalchemy/orm/attributes.py @@ -399,10 +399,10 @@ class Event(object): .. versionadded:: 0.9.0 - :var impl: The :class:`.AttributeImpl` which is the current event + :attribute impl: The :class:`.AttributeImpl` which is the current event initiator. - :var op: The symbol :attr:`.OP_APPEND`, :attr:`.OP_REMOVE`, + :attribute op: The symbol :attr:`.OP_APPEND`, :attr:`.OP_REMOVE`, :attr:`.OP_REPLACE`, or :attr:`.OP_BULK_REPLACE`, indicating the source operation. diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py index 4790bb2869..656389b680 100644 --- a/lib/sqlalchemy/orm/strategy_options.py +++ b/lib/sqlalchemy/orm/strategy_options.py @@ -804,9 +804,9 @@ class loader_option(object): self._unbound_fn = fn fn_doc = self.fn.__doc__ self.fn.__doc__ = """Produce a new :class:`.Load` object with the -:func:`.orm.%(name)s` option applied. +:func:`_orm.%(name)s` option applied. -See :func:`.orm.%(name)s` for usage examples. +See :func:`_orm.%(name)s` for usage examples. """ % { "name": self.name @@ -817,13 +817,14 @@ See :func:`.orm.%(name)s` for usage examples. def _add_unbound_all_fn(self, fn): self._unbound_all_fn = fn - fn.__doc__ = """Produce a standalone "all" option for :func:`.orm.%(name)s`. + fn.__doc__ = """Produce a standalone "all" option for +:func:`_orm.%(name)s`. .. deprecated:: 0.9 - The :func:`.%(name)s_all` function is deprecated, and will be removed - in a future release. Please use method chaining with :func:`.%(name)s` - instead, as in:: + The :func:`_orm.%(name)s_all` function is deprecated, and will be removed + in a future release. Please use method chaining with + :func:`_orm.%(name)s` instead, as in:: session.query(MyClass).options( %(name)s("someattribute").%(name)s("anotherattribute") @@ -1509,7 +1510,7 @@ def selectin_polymorphic(loadopt, classes): .. seealso:: - :ref:`inheritance_polymorphic_load` + :ref:`polymorphic_selectin` """ loadopt.set_class_strategy( diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py index 3c40e79143..28f20add41 100644 --- a/lib/sqlalchemy/sql/dml.py +++ b/lib/sqlalchemy/sql/dml.py @@ -823,7 +823,7 @@ class Delete(UpdateBase): prefixes=None, **dialect_kw ): - """Construct :class:`.Delete` object. + r"""Construct :class:`.Delete` object. Similar functionality is available via the :meth:`~.TableClause.delete` method on diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index 5552d34eab..c3afb7a35e 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -395,7 +395,7 @@ class FromClause(Selectable): message="The :meth:`.FromClause.count` method is deprecated, " "and will be removed in a future release. Please use the " ":class:`.functions.count` function available from the " - ":attr:`.func` namespace." + ":attr:`.func` namespace.", ) @util.dependencies("sqlalchemy.sql.functions") def count(self, functions, whereclause=None, **params): @@ -2014,7 +2014,7 @@ class SelectBase(HasCTE, Executable, FromClause): "and will be removed in a future release. Please use the " "the :paramref:`.Connection.execution_options.autocommit` " "parameter in conjunction with the " - ":meth:`.Executable.execution_options` method." + ":meth:`.Executable.execution_options` method.", ) def autocommit(self): """return a new selectable with the 'autocommit' flag set to @@ -2649,7 +2649,7 @@ class Select(HasPrefixes, HasSuffixes, GenerativeSelect): All arguments which accept :class:`.ClauseElement` arguments also accept string arguments, which will be converted as appropriate into - either :func:`text()` or :func:`literal_column()` constructs. + either :func:`.text()` or :func:`.literal_column()` constructs. .. seealso:: diff --git a/lib/sqlalchemy/util/deprecations.py b/lib/sqlalchemy/util/deprecations.py index e7b972deb2..75a1bb2eec 100644 --- a/lib/sqlalchemy/util/deprecations.py +++ b/lib/sqlalchemy/util/deprecations.py @@ -105,7 +105,7 @@ def _sanitize_restructured_text(text): name += "()" return name - return re.sub(r"\:(\w+)\:`~?\.?(.+?)`", repl, text) + return re.sub(r"\:(\w+)\:`~?(?:_\w+)?\.?(.+?)`", repl, text) def _decorate_with_warning(func, wtype, message, docstring_header=None): diff --git a/tox.ini b/tox.ini index 872acf2c35..fbcd4192a7 100644 --- a/tox.ini +++ b/tox.ini @@ -13,7 +13,7 @@ cov_args=--cov=sqlalchemy --cov-report term --cov-append --cov-report xml --excl usedevelop= cov: True -deps=pytest!=3.9.1,!=3.9.2 +deps=pytest!=3.9.1,!=3.9.2,<5.4 pytest-xdist mock # needed only for correct profiling results @@ -52,7 +52,7 @@ whitelist_externals=sh setenv= PYTHONPATH= PYTHONNOUSERSITE=1 - BASECOMMAND=python -m pytest --log-info=sqlalchemy.testing + BASECOMMAND=python -m pytest --log-info=sqlalchemy.testing -k "not aaa_profiling" WORKERS={env:TOX_WORKERS:-n4} oracle,oracle6,oracle5: WORKERS={env:TOX_WORKERS:-n2}