diff options
Diffstat (limited to 'lib/sqlalchemy')
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/base.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/mysql/dml.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/dialects/postgresql/psycopg2.py | 4 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/cursor.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/row.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/url.py | 53 | ||||
| -rw-r--r-- | lib/sqlalchemy/ext/asyncio/result.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/_orm_constructors.py | 10 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/query.py | 5 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/relationships.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/_dml_constructors.py | 16 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/_elements_constructors.py | 24 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/_selectable_constructors.py | 5 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/dml.py | 14 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/elements.py | 6 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/functions.py | 4 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/selectable.py | 30 |
17 files changed, 87 insertions, 96 deletions
diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py index 68653d976..7c9a68236 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -593,7 +593,7 @@ forms are accepted, including a single dictionary: as well as a list of 2-tuples, which will automatically provide a parameter-ordered UPDATE statement in a manner similar to that described -at :ref:`updates_order_parameters`. Unlike the :class:`_expression.Update` +at :ref:`tutorial_parameter_ordered_updates`. Unlike the :class:`_expression.Update` object, no special flag is needed to specify the intent since the argument form is this context is unambiguous: diff --git a/lib/sqlalchemy/dialects/mysql/dml.py b/lib/sqlalchemy/dialects/mysql/dml.py index f5e4f03e9..b93116c38 100644 --- a/lib/sqlalchemy/dialects/mysql/dml.py +++ b/lib/sqlalchemy/dialects/mysql/dml.py @@ -128,7 +128,7 @@ class Insert(StandardInsert): in the UPDATE clause should be ordered as sent, in a manner similar to that described for the :class:`_expression.Update` construct overall - in :ref:`updates_order_parameters`:: + in :ref:`tutorial_parameter_ordered_updates`:: insert().on_duplicate_key_update( [("name", "some name"), ("value", "some value")]) diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py index 3f4ee2a20..7488e431d 100644 --- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py +++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py @@ -205,7 +205,7 @@ performance, primarily with INSERT statements, by multiple orders of magnitude. SQLAlchemy internally makes use of these extensions for ``executemany()`` style calls, which correspond to lists of parameters being passed to :meth:`_engine.Connection.execute` as detailed in :ref:`multiple parameter -sets <execute_multiple>`. The ORM also uses this mode internally whenever +sets <tutorial_multiple_parameters>`. The ORM also uses this mode internally whenever possible. The two available extensions on the psycopg2 side are the ``execute_values()`` @@ -281,7 +281,7 @@ size defaults to 100. These can be affected by passing new values to .. seealso:: - :ref:`execute_multiple` - General information on using the + :ref:`tutorial_multiple_parameters` - General information on using the :class:`_engine.Connection` object to execute statements in such a way as to make use of the DBAPI ``.executemany()`` method. diff --git a/lib/sqlalchemy/engine/cursor.py b/lib/sqlalchemy/engine/cursor.py index 7947456af..4b0047e34 100644 --- a/lib/sqlalchemy/engine/cursor.py +++ b/lib/sqlalchemy/engine/cursor.py @@ -1244,7 +1244,7 @@ class CursorResult(Result[_T]): .. seealso:: - :ref:`coretutorial_selecting` - introductory material for accessing + :ref:`tutorial_selecting_data` - introductory material for accessing :class:`_engine.CursorResult` and :class:`.Row` objects. """ diff --git a/lib/sqlalchemy/engine/row.py b/lib/sqlalchemy/engine/row.py index 7c9eacb78..06976dd4b 100644 --- a/lib/sqlalchemy/engine/row.py +++ b/lib/sqlalchemy/engine/row.py @@ -65,7 +65,7 @@ class Row(BaseRow, Sequence[Any], Generic[_TP]): .. seealso:: - :ref:`coretutorial_selecting` - includes examples of selecting + :ref:`tutorial_selecting_data` - includes examples of selecting rows from SELECT statements. .. versionchanged:: 1.4 diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py index 5558b397c..6dea3677e 100644 --- a/lib/sqlalchemy/engine/url.py +++ b/lib/sqlalchemy/engine/url.py @@ -75,13 +75,7 @@ class URL(NamedTuple): * :attr:`_engine.URL.drivername`: database backend and driver name, such as ``postgresql+psycopg2`` * :attr:`_engine.URL.username`: username string - * :attr:`_engine.URL.password`: password string, or object that includes - a ``__str__()`` method that produces a password. - - .. note:: A password-producing object will be stringified only - **once** per :class:`_engine.Engine` object. For dynamic password - generation per connect, see :ref:`engines_dynamic_tokens`. - + * :attr:`_engine.URL.password`: password string * :attr:`_engine.URL.host`: string hostname * :attr:`_engine.URL.port`: integer port number * :attr:`_engine.URL.database`: string database name @@ -93,12 +87,57 @@ class URL(NamedTuple): """ drivername: str + """database backend and driver name, such as + ``postgresql+psycopg2`` + + """ + username: Optional[str] + "username string" + password: Optional[str] + """password, which is normally a string but may also be any + object that has a ``__str__()`` method.""" + host: Optional[str] + """hostname or IP number. May also be a data source name for some + drivers.""" + port: Optional[int] + """integer port number""" + database: Optional[str] + """database name""" + query: util.immutabledict[str, Union[Tuple[str, ...], str]] + """an immutable mapping representing the query string. contains strings + for keys and either strings or tuples of strings for values, e.g.:: + + >>> from sqlalchemy.engine import make_url + >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt") + >>> url.query + immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'}) + + To create a mutable copy of this mapping, use the ``dict`` constructor:: + + mutable_query_opts = dict(url.query) + + .. seealso:: + + :attr:`_engine.URL.normalized_query` - normalizes all values into sequences + for consistent processing + + Methods for altering the contents of :attr:`_engine.URL.query`: + + :meth:`_engine.URL.update_query_dict` + + :meth:`_engine.URL.update_query_string` + + :meth:`_engine.URL.update_query_pairs` + + :meth:`_engine.URL.difference_update_query` + + """ # noqa: E501 @classmethod def create( diff --git a/lib/sqlalchemy/ext/asyncio/result.py b/lib/sqlalchemy/ext/asyncio/result.py index ff3dcf417..8a1b1be32 100644 --- a/lib/sqlalchemy/ext/asyncio/result.py +++ b/lib/sqlalchemy/ext/asyncio/result.py @@ -18,6 +18,7 @@ from typing import TypeVar from . import exc as async_exc from ... import util +from ...engine import Result from ...engine.result import _NO_ROW from ...engine.result import _R from ...engine.result import FilterResult @@ -31,7 +32,6 @@ from ...util.typing import Literal if TYPE_CHECKING: from ...engine import CursorResult - from ...engine import Result from ...engine.result import _KeyIndexType from ...engine.result import _UniqueFilterType from ...engine.result import RMKeyView diff --git a/lib/sqlalchemy/orm/_orm_constructors.py b/lib/sqlalchemy/orm/_orm_constructors.py index ece6a52be..e68282865 100644 --- a/lib/sqlalchemy/orm/_orm_constructors.py +++ b/lib/sqlalchemy/orm/_orm_constructors.py @@ -856,7 +856,7 @@ def relationship( :ref:`relationship_config_toplevel` - Full introductory and reference documentation for :func:`_orm.relationship`. - :ref:`orm_tutorial_relationship` - ORM tutorial introduction. + :ref:`tutorial_orm_related_objects` - ORM tutorial introduction. :param argument: A mapped class, or actual :class:`_orm.Mapper` instance, @@ -923,9 +923,6 @@ def relationship( :ref:`relationships_many_to_many` - Reference example of "many to many". - :ref:`orm_tutorial_many_to_many` - ORM tutorial introduction to - many-to-many relationships. - :ref:`self_referential_many_to_many` - Specifics on using many-to-many in a self-referential case. @@ -1029,9 +1026,6 @@ def relationship( :ref:`unitofwork_cascades` - Full detail on each of the available cascade options. - :ref:`tutorial_delete_cascade` - Tutorial example describing - a delete cascade. - :param cascade_backrefs=False: Legacy; this flag is always False. @@ -2095,8 +2089,6 @@ def aliased( :ref:`orm_queryguide_orm_aliases` - in the :ref:`queryguide_toplevel` - :ref:`ormtutorial_aliases` - in the legacy :ref:`ormtutorial_toplevel` - :param element: element to be aliased. Is normally a mapped class, but for convenience can also be a :class:`_expression.FromClause` element. diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index 419891708..596e91099 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -3050,9 +3050,8 @@ class Query( :param values: a dictionary with attributes names, or alternatively mapped attributes or SQL expressions, as keys, and literal values or sql expressions as values. If :ref:`parameter-ordered - mode <updates_order_parameters>` is desired, the values can be - passed as a list of 2-tuples; - this requires that the + mode <tutorial_parameter_ordered_updates>` is desired, the values can + be passed as a list of 2-tuples; this requires that the :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order` flag is passed to the :paramref:`.Query.update.update_args` dictionary as well. diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py index deaf52147..630f6898f 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -985,7 +985,7 @@ class Relationship( See :meth:`~.Relationship.Comparator.any` for a less-performant alternative using EXISTS, or refer to :meth:`_query.Query.outerjoin` - as well as :ref:`ormtutorial_joins` + as well as :ref:`orm_queryguide_joins` for more details on constructing outer joins. kwargs may be ignored by this operator but are required for API diff --git a/lib/sqlalchemy/sql/_dml_constructors.py b/lib/sqlalchemy/sql/_dml_constructors.py index 926e5257b..293d225f9 100644 --- a/lib/sqlalchemy/sql/_dml_constructors.py +++ b/lib/sqlalchemy/sql/_dml_constructors.py @@ -35,9 +35,6 @@ def insert(table: _DMLTableArgument) -> Insert: .. seealso:: - :ref:`coretutorial_insert_expressions` - in the - :ref:`1.x tutorial <sqlexpression_toplevel>` - :ref:`tutorial_core_insert` - in the :ref:`unified_tutorial` @@ -79,9 +76,7 @@ def insert(table: _DMLTableArgument) -> Insert: .. seealso:: - :ref:`coretutorial_insert_expressions` - SQL Expression Tutorial - - :ref:`inserts_and_updates` - SQL Expression Tutorial + :ref:`tutorial_core_insert` - in the :ref:`unified_tutorial` """ return Insert(table) @@ -104,15 +99,6 @@ def update(table: _DMLTableArgument) -> Update: :meth:`_expression.TableClause.update` method on :class:`_schema.Table`. - .. seealso:: - - :ref:`inserts_and_updates` - in the - :ref:`1.x tutorial <sqlexpression_toplevel>` - - :ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial` - - - :param table: A :class:`_schema.Table` object representing the database table to be updated. diff --git a/lib/sqlalchemy/sql/_elements_constructors.py b/lib/sqlalchemy/sql/_elements_constructors.py index f6dd92865..8b8f6b010 100644 --- a/lib/sqlalchemy/sql/_elements_constructors.py +++ b/lib/sqlalchemy/sql/_elements_constructors.py @@ -605,15 +605,6 @@ def bindparam( .. versionchanged:: 1.3 the "expanding" bound parameter feature now supports empty lists. - - .. seealso:: - - :ref:`coretutorial_bind_param` - - :ref:`coretutorial_insert_expressions` - - :func:`.outparam` - :param literal_execute: if True, the bound parameter will be rendered in the compile phase with a special "POSTCOMPILE" token, and the SQLAlchemy compiler will @@ -635,6 +626,12 @@ def bindparam( :ref:`change_4808`. + .. seealso:: + + :ref:`tutorial_sending_parameters` - in the + :ref:`unified_tutorial` + + """ return BindParameter( key, @@ -827,7 +824,7 @@ def cast( .. seealso:: - :ref:`coretutorial_casts` + :ref:`tutorial_casts` :func:`.type_coerce` - an alternative to CAST that coerces the type on the Python side only, which is often sufficient to generate the @@ -932,7 +929,7 @@ def column( :func:`_expression.text` - :ref:`sqlexpression_literal_column` + :ref:`tutorial_select_arbitrary_text` """ return ColumnClause(text, type_, is_literal, _selectable) @@ -1468,8 +1465,7 @@ def text(text: str) -> TextClause: .. seealso:: - :ref:`sqlexpression_text` - in the Core tutorial - + :ref:`tutorial_select_arbitrary_text` """ return TextClause(text) @@ -1615,7 +1611,7 @@ def type_coerce( .. seealso:: - :ref:`coretutorial_casts` + :ref:`tutorial_casts` :func:`.cast` diff --git a/lib/sqlalchemy/sql/_selectable_constructors.py b/lib/sqlalchemy/sql/_selectable_constructors.py index ea824d622..b661d6f47 100644 --- a/lib/sqlalchemy/sql/_selectable_constructors.py +++ b/lib/sqlalchemy/sql/_selectable_constructors.py @@ -290,7 +290,7 @@ def lateral( .. seealso:: - :ref:`lateral_selects` - overview of usage. + :ref:`tutorial_lateral_correlation` - overview of usage. """ return Lateral._factory(selectable, name=name) @@ -466,8 +466,7 @@ def select(*entities: _ColumnsClauseArgument[Any], **__kw: Any) -> Select[Any]: .. seealso:: - :ref:`coretutorial_selecting` - Core Tutorial description of - :func:`_expression.select`. + :ref:`tutorial_selecting_data` - in the :ref:`unified_tutorial` :param \*entities: Entities to SELECT from. For Core usage, this is typically a series diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py index 28ea512a7..2ed3be9cb 100644 --- a/lib/sqlalchemy/sql/dml.py +++ b/lib/sqlalchemy/sql/dml.py @@ -800,7 +800,7 @@ class ValuesBase(UpdateBase): .. seealso:: - :ref:`execute_multiple` - an introduction to + :ref:`tutorial_multiple_parameters` - an introduction to the traditional Core method of multiple parameter set invocation for INSERTs and other statements. @@ -1256,16 +1256,6 @@ class DMLWhereBase: .. seealso:: - **1.x Tutorial Examples** - - :ref:`tutorial_1x_correlated_updates` - - :ref:`multi_table_updates` - - :ref:`multi_table_deletes` - - **2.0 Tutorial Examples** - :ref:`tutorial_correlated_updates` :ref:`tutorial_update_from` @@ -1381,7 +1371,7 @@ class Update(DMLWhereBase, ValuesBase): .. seealso:: - :ref:`updates_order_parameters` - full example of the + :ref:`tutorial_parameter_ordered_updates` - full example of the :meth:`_expression.Update.ordered_values` method. .. versionchanged:: 1.4 The :meth:`_expression.Update.ordered_values` diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py index 6032253c2..625e1d94b 100644 --- a/lib/sqlalchemy/sql/elements.py +++ b/lib/sqlalchemy/sql/elements.py @@ -190,7 +190,7 @@ def literal_column( :func:`_expression.text` - :ref:`sqlexpression_literal_column` + :ref:`tutorial_select_arbitrary_text` """ return ColumnClause(text, type_=type_, is_literal=True) @@ -1568,7 +1568,7 @@ class ColumnElement( .. seealso:: - :ref:`coretutorial_casts` + :ref:`tutorial_casts` :func:`_expression.cast` @@ -3198,7 +3198,7 @@ class Cast(WrapsColumnExpression[_T]): .. seealso:: - :ref:`coretutorial_casts` + :ref:`tutorial_casts` :func:`.cast` diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py index 0cba1a1a8..befd262ec 100644 --- a/lib/sqlalchemy/sql/functions.py +++ b/lib/sqlalchemy/sql/functions.py @@ -102,7 +102,7 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative): .. seealso:: - :ref:`coretutorial_functions` - in the Core tutorial + :ref:`tutorial_functions` - in the :ref:`unified_tutorial` :class:`.Function` - named SQL function. @@ -821,7 +821,7 @@ class _FunctionGenerator: .. seealso:: - :ref:`coretutorial_functions` - in the Core Tutorial + :ref:`tutorial_functions` - in the :ref:`unified_tutorial` :class:`.Function` diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index eebefb877..ce561697b 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -105,6 +105,7 @@ and_ = BooleanClauseList.and_ _T = TypeVar("_T", bound=Any) if TYPE_CHECKING: + import sqlalchemy from ._typing import _ColumnExpressionArgument from ._typing import _FromClauseArgument from ._typing import _JoinTargetArgument @@ -129,7 +130,6 @@ if TYPE_CHECKING: from .cache_key import _CacheKeyTraversalType from .compiler import SQLCompiler from .dml import Delete - from .dml import Insert from .dml import Update from .elements import KeyedColumnElement from .elements import Label @@ -292,7 +292,7 @@ class Selectable(ReturnsRows): .. seealso:: - :ref:`lateral_selects` - overview of usage. + :ref:`tutorial_lateral_correlation` - overview of usage. """ return Lateral._construct(self, name) @@ -751,7 +751,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): .. seealso:: - :ref:`core_tutorial_aliases` + :ref:`tutorial_using_aliases` :func:`_expression.alias` @@ -1893,7 +1893,7 @@ class Lateral(FromClauseAlias, LateralFromClause): .. seealso:: - :ref:`lateral_selects` - overview of usage. + :ref:`tutorial_lateral_correlation` - overview of usage. """ @@ -2063,7 +2063,7 @@ class CTE( .. seealso:: - :ref:`core_tutorial_aliases` + :ref:`tutorial_using_aliases` :func:`_expression.alias` @@ -2996,7 +2996,7 @@ class TableClause(roles.DMLTableRole, Immutable, NamedFromClause): c.table = self @util.preload_module("sqlalchemy.sql.dml") - def insert(self) -> Insert: + def insert(self) -> sqlalchemy.sql.expression.Insert: """Generate an :func:`_expression.insert` construct against this :class:`_expression.TableClause`. @@ -3180,7 +3180,7 @@ class Values(Generative, LateralFromClause): .. seealso:: - :ref:`core_tutorial_aliases` + :ref:`tutorial_using_aliases` :func:`_expression.alias` @@ -3462,8 +3462,6 @@ class SelectBase( :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial - :ref:`scalar_selects` - in the 1.x tutorial - """ if self._label_style is not LABEL_STYLE_NONE: self = self.set_label_style(LABEL_STYLE_NONE) @@ -3491,7 +3489,7 @@ class SelectBase( .. seealso:: - :ref:`lateral_selects` - overview of usage. + :ref:`tutorial_lateral_correlation` - overview of usage. """ return Lateral._factory(self, name) @@ -4970,8 +4968,6 @@ class Select( :func:`_sql.select` - :ref:`coretutorial_selecting` - in the 1.x tutorial - :ref:`tutorial_selecting_data` - in the 2.0 tutorial """ @@ -6022,7 +6018,7 @@ class Select( :meth:`_expression.Select.correlate_except` - :ref:`correlated_subqueries` + :ref:`tutorial_scalar_subquery` """ @@ -6072,7 +6068,7 @@ class Select( :meth:`_expression.Select.correlate` - :ref:`correlated_subqueries` + :ref:`tutorial_scalar_subquery` """ @@ -6345,8 +6341,6 @@ class ScalarSelect( :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial - :ref:`scalar_selects` - in the 1.x tutorial - """ _traverse_internals: _TraverseInternalsType = [ @@ -6444,8 +6438,6 @@ class ScalarSelect( :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial - :ref:`correlated_subqueries` - in the 1.x tutorial - """ self.element = cast("Select[Any]", self.element).correlate( @@ -6483,8 +6475,6 @@ class ScalarSelect( :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial - :ref:`correlated_subqueries` - in the 1.x tutorial - """ |