summaryrefslogtreecommitdiff
path: root/doc/build/orm
Commit message (Collapse)AuthorAgeFilesLines
* qualify session.execute() resulting in autoflushMike Bayer2023-05-121-1/+3
| | | | | | | | maybe this was planned differently at some point but session.execute() only autoflushes for ORM contexts. Change-Id: Ia10af232248e321875f79d5bde71f64d3dc25177 References: #9776
* Merge "fix test suite warnings" into mainmike bayer2023-05-101-1/+1
|\
| * fix test suite warningsMike Bayer2023-05-091-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | fix a handful of warnings that were emitting but not raising, usually because they were inside an "expect_warnings" block. modify "expect_warnings" to always use "raise_on_any_unexpected" behavior; remove this parameter. Fixed issue in semi-private ``await_only()`` and ``await_fallback()`` concurrency functions where the given awaitable would remain un-awaited if the function threw a ``GreenletError``, which could cause "was not awaited" warnings later on if the program continued. In this case, the given awaitable is now cancelled before the exception is thrown. Change-Id: I33668c5e8c670454a3d879e559096fb873b57244
* | add AsyncAttrsMike Bayer2023-05-081-6/+72
|/ | | | | | | | | | Added a new helper mixin :class:`_asyncio.AsyncAttrs` that seeks to improve the use of lazy-loader and other expired or deferred ORM attributes with asyncio, providing a simple attribute accessor that provides an ``await`` interface to any ORM attribute, whether or not it needs to emit SQL. Change-Id: I1427b288dc28319c854372643066c491b9ee8dc0 References: #9731
* Add scalar example in association proxy examplesFederico Caselli2023-04-281-4/+75
| | | | | Fixes: #9699 Change-Id: I73f800b9b3676cbf0ac04534c0ca4e40f23bf0ec
* Fix import for selectinload in docs (#9712)Holly Becker2023-04-271-2/+2
| | | selectinload is in sqlalchemy.orm, not sqlalchemy
* :pencil2: Fix repetition for same reference page on documentation (#9694)HoonCheol Shin2023-04-231-3/+2
| | | | | * :pencil2: remove repeat for same reference * :pencil2: apply the suggestion from @zzzeek
* changelog fixes; editsMike Bayer2023-04-211-1/+1
| | | | Change-Id: I6bbef2416f864d1414d56f9bf39026156aed5e67
* add deterministic imv returning ordering using sentinel columnsMike Bayer2023-04-214-30/+115
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Repaired a major shortcoming which was identified in the :ref:`engine_insertmanyvalues` performance optimization feature first introduced in the 2.0 series. This was a continuation of the change in 2.0.9 which disabled the SQL Server version of the feature due to a reliance in the ORM on apparent row ordering that is not guaranteed to take place. The fix applies new logic to all "insertmanyvalues" operations, which takes effect when a new parameter :paramref:`_dml.Insert.returning.sort_by_parameter_order` on the :meth:`_dml.Insert.returning` or :meth:`_dml.UpdateBase.return_defaults` methods, that through a combination of alternate SQL forms, direct correspondence of client side parameters, and in some cases downgrading to running row-at-a-time, will apply sorting to each batch of returned rows using correspondence to primary key or other unique values in each row which can be correlated to the input data. Performance impact is expected to be minimal as nearly all common primary key scenarios are suitable for parameter-ordered batching to be achieved for all backends other than SQLite, while "row-at-a-time" mode operates with a bare minimum of Python overhead compared to the very heavyweight approaches used in the 1.x series. For SQLite, there is no difference in performance when "row-at-a-time" mode is used. It's anticipated that with an efficient "row-at-a-time" INSERT with RETURNING batching capability, the "insertmanyvalues" feature can be later be more easily generalized to third party backends that include RETURNING support but not necessarily easy ways to guarantee a correspondence with parameter order. Fixes: #9618 References: #9603 Change-Id: I1d79353f5f19638f752936ba1c35e4dc235a8b7c
* Merge "Add pool creation functions" into mainmike bayer2023-04-131-0/+2
|\
| * Add pool creation functionsFederico Caselli2023-04-121-0/+2
| | | | | | | | | | | | | | | | | | | | Added :func:`_sa.create_pool_from_url` and :func:`_asyncio.create_async_pool_from_url` to create a :class:`_pool.Pool` instance from an input url passed as string or :class:`_sa.URL`. Fixes: #9613 Change-Id: Icd8aa3f2849e6fd1bc5341114f3ef8d216a2c543
* | Merge "Remove old versionadded and versionchanged" into mainmike bayer2023-04-126-30/+0
|\ \
| * | Remove old versionadded and versionchangedFederico Caselli2023-04-126-30/+0
| |/ | | | | | | | | | | | | Removed versionadded and versionchanged for version prior to 1.2 since they are no longer useful. Change-Id: I5c53d1188bc5fec3ab4be39ef761650ed8fa6d3e
* | Merge "establish column_property and query_expression as readonly from a dc ↵Federico Caselli2023-04-121-2/+2
|\ \ | |/ |/| | | perspective" into main
| * establish column_property and query_expression as readonly from a dc perspectiveMike Bayer2023-04-121-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Fixed bug in ORM Declarative Dataclasses where the :func:`_orm.queryable_attribute` and :func:`_orm.column_property` constructs, which are documented as read-only constructs in the context of a Declarative mapping, could not be used with a :class:`_orm.MappedAsDataclass` class without adding ``init=False``, which in the case of :func:`_orm.queryable_attribute` was not possible as no ``init`` parameter was included. These constructs have been modified from a dataclass perspective to be assumed to be "read only", setting ``init=False`` by default and no longer including them in the pep-681 constructor. The dataclass parameters for :func:`_orm.column_property` ``init``, ``default``, ``default_factory``, ``kw_only`` are now deprecated; these fields don't apply to :func:`_orm.column_property` as used in a Declarative dataclasses configuration where the construct would be read-only. Also added read-specific parameter :paramref:`_orm.queryable_attribute.compare` to :func:`_orm.queryable_attribute`; :paramref:`_orm.queryable_attribute.repr` was already present. Added missing :paramref:`_orm.mapped_column.active_history` parameter to :func:`_orm.mapped_column` construct. Fixes: #9628 Change-Id: I2ab44d6b763b20410bd1ebb5ac949a6d223f1ce2
* | make the linter happyFederico Caselli2023-04-121-3/+1
| | | | | | | | Change-Id: I7104c7cb081c9b61894958cef5d0b4707474994d
* | Fix Association Proxy exampleGord Thompson2023-04-111-1/+4
|/ | | | | | | | Minor corrections to "Simplifying Association Objects" example in the Association Proxy docs. https: //github.com/sqlalchemy/sqlalchemy/discussions/9636 Change-Id: Ib433cf78b149d330889d947bbaf2b03c9dd87c29
* mypy 1.2 has fixed dataclass descriptor supportMike Bayer2023-04-041-44/+5
| | | | | | | Currently using the PR for test. Change-Id: Idc4c475587f5151ef79046d24ca3ac274c2cb2ca References: https://github.com/python/mypy/issues/14868
* warn for DC mixin / abstract fields that are not on a dataclassMike Bayer2023-03-301-0/+47
| | | | | | | | | | | | Fields that are declared on Declarative Mixins and then combined with classes that make use of :class:`_orm.MappedAsDataclass`, where those mixin fields are not themselves part of a dataclass, now emit a deprecation warning as these fields will be ignored in a future release, as Python dataclasses behavior is to ignore these fields. Type checkers will not see these fields under pep-681. Fixes: #9350 Change-Id: Ie0a0ac0f0bb58d1c2aae13b4a8dcd0439a4f5477
* add explicit overload for composite -> callableMike Bayer2023-03-171-2/+6
| | | | | | | | Fixed typing issue where :func:`_orm.composite` would not allow an arbitrary callable as the source of the composite class. Fixes: #9502 Change-Id: I5b098b70b2fb7b48f54eaccbb7d5d3d9bdebc781
* document no-pep681 workaroundsMike Bayer2023-03-122-6/+50
| | | | | | | | | | | | | | | | | | | Mypy 1.1.1 has been released which includes a non-compliant pep-681 implementation that fails with SQLAlchemy's :class:`.MappedAsDataclass` and similar features. In order to work around this issue until Mypy is able to release a fix, as well as to support other typing tools which may have non-compliant pep-681 implementations, document a workaround class for :class:`.MappedAsDataclass`. Including this class as well as a decorator was considered, but overall this is an issue with typing tools that they will have to resolve and I'm not ready to set up for this issue going on long term. There's also no good solution for the decorator version since you have to have an ``__init__`` method indicated somewhere. References: https://github.com/python/mypy/issues/13856 Fixes: #9467 Change-Id: I1be6abea7f7fc72883c14ab2447edad937d0c23f
* clarify "selecting individual columns" docMike Bayer2023-03-081-10/+8
| | | | | | | | | Just went to refer to this and it was full of difficult terminology for no good reason. What's troubling is that this doc is like the tenth time I've rewritten this and it still was loaded with too much jargon and not clear about the behavior. Change-Id: I22745962568277eead6081a82003ac90665048e0
* Merge "Create public QueryPropertyDescriptor type for query_property" into mainmike bayer2023-02-271-1/+3
|\
| * Create public QueryPropertyDescriptor type for query_propertyFederico Caselli2023-02-261-1/+3
| | | | | | | | | | | | | | | | | | | | | | Exported the type returned by :meth:`_orm.scoped_session.query_property` using a new public type :class:`.orm.QueryPropertyDescriptor`. Also stated ``scoped_session()`` from ``sqlalchemy.orm`` in the documentation rather than from ``sqlalchemy.orm.scoping``. Fixes: #9338 Change-Id: I77da54891860095edcb1f0625ead99fee89bd76f
* | update case statement to v2 syntaxFederico Caselli2023-02-241-3/+1
| | | | | | | | | | | | Change-Id: If278ea170e0a17b1e8ace2d470fb2fbdb7a6e9c1 References: #9370 References: #9365
* | use Column for legacy dataclasses mappingMike Bayer2023-02-231-45/+33
|/ | | | | Fixes: #9361 Change-Id: I9c433960664aa2b75cd03925d9dcf2e1ff27d8ce
* add notes to all mapper flush events that these are only for flushMike Bayer2023-02-211-9/+17
| | | | | Fixes: #9339 Change-Id: I44542166417776733245e2ba39cd5de89b6d748b
* Merge "add dataclasses callable and apply annotations more strictly" into mainmike bayer2023-02-161-0/+48
|\
| * add dataclasses callable and apply annotations more strictlyMike Bayer2023-02-161-0/+48
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Added new parameter ``dataclasses_callable`` to both the :class:`_orm.MappedAsDataclass` class as well as the :meth:`_orm.registry.mapped_as_dataclass` method which allows an alternative callable to Python ``dataclasses.dataclass`` to be used in order to produce dataclasses. The use case here is to drop in Pydantic's dataclass function instead. Adjustments have been made to the mixin support added for :ticket:`9179` in version 2.0.1 so that the ``__annotations__`` collection of the mixin is rewritten to not include the :class:`_orm.Mapped` container, in the same way as occurs with mapped classes, so that the Pydantic dataclasses constructor is not exposed to unknown types. Fixes: #9266 Change-Id: Ia0fab6f20b93a5cb853799dcf1b70a0386837c14
* | immediateload lazy relationships named in refresh.attribute_namesMike Bayer2023-02-161-0/+25
|/ | | | | | | | | | | | | | | | | | The :meth:`_orm.Session.refresh` method will now immediately load a relationship-bound attribute that is explicitly named within the :paramref:`_orm.Session.refresh.attribute_names` collection even if it is currently linked to the "select" loader, which normally is a "lazy" loader that does not fire off during a refresh. The "lazy loader" strategy will now detect that the operation is specifically a user-initiated :meth:`_orm.Session.refresh` operation which named this attribute explicitly, and will then call upon the "immediateload" strategy to actually emit SQL to load the attribute. This should be helpful in particular for some asyncio situations where the loading of an unloaded lazy-loaded attribute must be forced, without using the actual lazy-loading attribute pattern not supported in asyncio. Fixes: #9298 Change-Id: I9b50f339bdf06cdb2ec98f8e5efca2b690895dd7
* note column ordering change, indicate recipe to control orderingMike Bayer2023-02-131-0/+2
| | | | | Change-Id: I520c18ac8c84923558e2042265943b6340700788 References: #9294
* update asyncio examples and add notes about writeonlyMike Bayer2023-02-051-33/+45
| | | | Change-Id: I1233eb1a860b915fb265ec8bf177f1a0471cdbd1
* Fix minor documentation glitch, replace "row" with "column" (#9215)Lele Gaifax2023-02-011-1/+1
|
* fix late-eval exampleMike Bayer2023-02-011-1/+1
| | | | | Fixes: #9209 Change-Id: Ic5bc87b25281e3cecc967843c402e96c7c2a3dbb
* Merge "Add support for typing.Literal in Mapped" into mainmike bayer2023-02-011-101/+247
|\
| * Add support for typing.Literal in MappedFrederik Aalund2023-01-311-101/+247
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Added support for :pep:`586` ``Literal`` to be used in the :paramref:`_orm.registry.type_annotation_map` as well as within :class:`.Mapped` constructs. To use custom types such as these, they must appear explicitly within the :paramref:`_orm.registry.type_annotation_map` to be mapped. Pull request courtesy Frederik Aalund. As part of this change, the support for :class:`.sqltypes.Enum` in the :paramref:`_orm.registry.type_annotation_map` has been expanded to include support for ``Literal[]`` types consisting of string values to be used, in addition to ``enum.Enum`` datatypes. If a ``Literal[]`` datatype is used within ``Mapped[]`` that is not linked in :paramref:`_orm.registry.type_annotation_map` to a specific datatype, a :class:`.sqltypes.Enum` will be used by default. Fixed issue involving the use of :class:`.sqltypes.Enum` within the :paramref:`_orm.registry.type_annotation_map` where the :paramref:`_sqltypes.Enum.native_enum` parameter would not be correctly copied to the mapped column datatype, if it were overridden as stated in the documentation to set this parameter to False. Fixes: #9187 Fixes: #9200 Closes: #9191 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/9191 Pull-request-sha: 7d13f705307bf62560fc831f6f049a425d411374 Change-Id: Ife3ba2655f4897f806d6a9cf0041c69fd4f39e9d
* | Unify doc typingHarry Lees2023-01-3110-61/+71
|/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ### Description <!-- Describe your changes in detail --> Fixes #9168 This PR replaces common occurrences of [PEP 585](https://peps.python.org/pep-0585/) style type annotations with annotations compatible with older versions of Python. I searched for instances of the following supported types from the PEP and replaced with their legacy typing couterparts. * tuple # typing.Tuple * list # typing.List * dict # typing.Dict * set # typing.Set * frozenset # typing.FrozenSet * type # typing.Type ``` grep -r "list\[.*\]" ./build --exclude-dir="./build/venv/*" --exclude-dir="./build/output/*" --exclude="changelog_[0-9]*\.rst" ``` I excluded changelog files from being altered, I think some of these could be changed if necessary but others are likely to require manual checking as the change may target the new typing style specifically. For any examples that included imports, I tried to ensure that the correct typing imports were included and properly ordered. ### Checklist <!-- go over following points. check them with an `x` if they do apply, (they turn into clickable checkboxes once the PR is submitted, so no need to do everything at once) --> This pull request is: - [x] A documentation / typographical error fix - Good to go, no issue or tests are needed - [ ] A short code fix - please include the issue number, and create an issue if none exists, which must include a complete example of the issue. one line code fixes without an issue and demonstration will not be accepted. - Please include: `Fixes: #<issue number>` in the commit message - please include tests. one line code fixes without tests will not be accepted. - [ ] A new feature implementation - please include the issue number, and create an issue if none exists, which must include a complete example of how the feature would look. - Please include: `Fixes: #<issue number>` in the commit message - please include tests. Closes: #9198 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/9198 Pull-request-sha: 05ad4651b57c6275b29433e5e76e166344ba6c4c Change-Id: I41b93b3dee85f9fe00cfbb3d3eb011212795de29
* add set_shard_id() loader option for horizontal shardMike Bayer2023-01-251-0/+3
| | | | | | | | | | | | | | Added new option to horizontal sharding API :class:`_horizontal.set_shard_id` which sets the effective shard identifier to query against, for both the primary query as well as for all secondary loaders including relationship eager loaders as well as relationship and column lazy loaders. Modernize sharding examples with new-style mappings, add new asyncio example. Fixes: #7226 Fixes: #7028 Change-Id: Ie69248060c305e8de04f75a529949777944ad511
* Merge "Add public protocol for mapped class" into mainmike bayer2023-01-252-0/+5
|\
| * Add public protocol for mapped classFederico Caselli2023-01-252-0/+5
| | | | | | | | | | Fixes: #8624 Change-Id: Ia7a66ae9ba534ed7152f95dfd0f7d05b9d00165a
* | Improve examples, make typing beta, remove beta from asyncioFederico Caselli2023-01-251-5/+0
|/ | | | Change-Id: Icbde11dcaae5fa6f5e83cd50b6a301081a3ab962
* fix typo, add missing command to unittest pg docker exampleFederico Caselli2023-01-181-1/+1
| | | | Change-Id: Ic640ccf7459c39cb4f6ab8dcfb3efed1a1dbb55f
* apply changelog note for change of column loader optionsMike Bayer2023-01-161-1/+69
| | | | | | Change-Id: Ib9a69e20420e1fda755f4533c5f90bc08ba11b48 References: #8879 References: #9101
* super-fine pass through the metadata tutorialMike Bayer2023-01-151-3/+4
| | | | | | | | | | try to keep the wordiness down here, using sidebars and topics for non-essential information. Sphinx seems to read out attrs from under TYPE_CHECKING sections now so link out the attrs in DeclarativeBase w/ docstrings, not sure why we didn't think of this earlier. looks great Change-Id: Ib2e07e3606185998561c2d77b2564fd3eddb4d75
* implement polymorphic_abstract=True featureMike Bayer2023-01-142-16/+198
| | | | | | | | | | | | | | | | | | | | | | | | | | | | Added a new parameter to :class:`_orm.Mapper` called :paramref:`_orm.Mapper.polymorphic_abstract`. The purpose of this directive is so that the ORM will not consider the class to be instantiated or loaded directly, only subclasses. The actual effect is that the :class:`_orm.Mapper` will prevent direct instantiation of instances of the class and will expect that the class does not have a distinct polymorphic identity configured. In practice, the class that is mapped with :paramref:`_orm.Mapper.polymorphic_abstract` can be used as the target of a :func:`_orm.relationship` as well as be used in queries; subclasses must of course include polymorphic identities in their mappings. The new parameter is automatically applied to classes that subclass the :class:`.AbstractConcreteBase` class, as this class is not intended to be instantiated. Additionally, updated some areas of the single table inheritance documentation to include mapped_column(nullable=False) for all subclass-only columns; the mappings as given didn't work as the columns were no longer nullable using Annotated Declarative Table style. Fixes: #9060 Change-Id: Ief0278e3945a33a6ff38ac14d39c38ce24910d7f
* Make the custom type map more discoverableFederico Caselli2023-01-132-8/+8
| | | | Change-Id: Id6cdaddad83aa93508e256e54010a6c53218b717
* Merge "Remove old file and missing doc section" into mainmike bayer2023-01-131-471/+0
|\
| * Remove old file and missing doc sectionFederico Caselli2023-01-121-471/+0
| | | | | | | | Change-Id: Ic6dda7f32a7561a0c0a92b8a7c08e44cb174eec1
* | Fixes related to improved sql formattingFederico Caselli2023-01-127-24/+54
|/ | | | | | Follow up of I07b72e6620bb64e329d6b641afa27631e91c4f16 Change-Id: I1f61974bf9cdc3da5317e546d4f9b649c2029e4d
* Improve sql formattingFederico Caselli2023-01-1120-189/+182
| | | | | | change {opensql} to {printsql} in prints, add missing markers Change-Id: I07b72e6620bb64e329d6b641afa27631e91c4f16
View Lorry Controller Status