summaryrefslogtreecommitdiff
path: root/doc
Commit message (Collapse)AuthorAgeFilesLines
* Create a real type for Tuple() and handle appropriately in compilerMike Bayer2020-08-171-0/+19
| | | | | | | | | | | | | | | | | | | | | | | | | | | Improved the :func:`_sql.tuple_` construct such that it behaves predictably when used in a columns-clause context. The SQL tuple is not supported as a "SELECT" columns clause element on most backends; on those that do (PostgreSQL, not surprisingly), the Python DBAPI does not have a "nested type" concept so there are still challenges in fetching rows for such an object. Use of :func:`_sql.tuple_` in a :func:`_sql.select` or :class:`_orm.Query` will now raise a :class:`_exc.CompileError` at the point at which the :func:`_sql.tuple_` object is seen as presenting itself for fetching rows (i.e., if the tuple is in the columns clause of a subquery, no error is raised). For ORM use,the :class:`_orm.Bundle` object is an explicit directive that a series of columns should be returned as a sub-tuple per row and is suggested by the error message. Additionally ,the tuple will now render with parenthesis in all contexts. Previously, the parenthesization would not render in a columns context leading to non-defined behavior. As part of this change, Tuple receives a dedicated datatype which appears to allow us the very desirable change of removing the bindparam._expanding_in_types attribute as well as ClauseList._tuple_values (which might already have not been needed due to #4645). Fixes: #5127 Change-Id: Iecafa0e0aac2f1f37ec8d0e1631d562611c90200
* Dont run py3k-only test files on Python 3.5Mike Bayer2020-08-131-0/+2
| | | | | | | these are failing on the github runners because 3.5 doesnt have the async keywords. Change-Id: I9c58d38f8d7595313b7648b9840b334da8238bd0
* Doc fix; use normal TOX_POSTGRESQL env nowMike Bayer2020-08-131-1/+1
| | | | Change-Id: Ie47a9e9377858641f2f8e038133be27dc9aacd64
* Merge "Implement rudimentary asyncio support w/ asyncpg"mike bayer2020-08-1411-135/+442
|\
| * Implement rudimentary asyncio support w/ asyncpgMike Bayer2020-08-1311-135/+442
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Using the approach introduced at https://gist.github.com/zzzeek/6287e28054d3baddc07fa21a7227904e We can now create asyncio endpoints that are then handled in "implicit IO" form within the majority of the Core internals. Then coroutines are re-exposed at the point at which we call into asyncpg methods. Patch includes: * asyncpg dialect * asyncio package * engine, result, ORM session classes * new test fixtures, tests * some work with pep-484 and a short plugin for the pyannotate package, which seems to have so-so results Change-Id: Idbcc0eff72c4cad572914acdd6f40ddb1aef1a7d Fixes: #3414
* | Merge "Further fixes for ticket 5470"mike bayer2020-08-131-1/+4
|\ \ | |/ |/|
| * Further fixes for ticket 5470Mike Bayer2020-08-131-1/+4
| | | | | | | | | | | | | | | | | | | | The fix for #5470 didn't actually take into account that the "distinct" logic in query was also doubling up the criteria. Added many more tests. the 1.3 version here will be different than 1.4 as the regression is not quite the same. Fixes: #5470 Change-Id: I16a23917cab175761de9c867d9d9ac55031d9b97
* | Use importlib_metadata; add namespace for mariadbMike Bayer2020-08-133-2/+25
|/ | | | | | | | | | | | | | | | | | | | | | | | | | The ``importlib_metadata`` library is used to scan for setuptools entrypoints rather than pkg_resources. as importlib_metadata is a small library that is included as of Python 3.8, the compatibility library is installed as a dependency for Python versions older than 3.8. Unfortunately setuptools "attr:" is broken because it tries to import the module; seems like this is fixed as part of https://github.com/pypa/setuptools/pull/1753 however this is too recent to rely upon for now. Added a new dialect token "mariadb" that may be used in place of "mysql" in the :func:`_sa.create_engine` URL. This will deliver a MariaDB dialect subclass of the MySQLDialect in use that forces the "is_mariadb" flag to True. The dialect will raise an error if a server version string that does not indicate MariaDB in use is received. This is useful for MariaDB-specific testing scenarios as well as to support applications that are hardcoding to MariaDB-only concepts. As MariaDB and MySQL featuresets and usage patterns continue to diverge, this pattern may become more prominent. Fixes: #5400 Fixes: #5496 Change-Id: I330815ebe572b6a9818377da56621397335fa702
* Merge "Break scalars() and mappings() into separate objects"mike bayer2020-08-123-4/+13
|\
| * Break scalars() and mappings() into separate objectsMike Bayer2020-08-123-4/+13
| | | | | | | | | | | | | | | | | | | | | | | | The issue of Result.fetchXXX() methods returning Row objects unless filtering is applied will not provide a clear enough API story when type annotations are applied, so break out scalars/mappings into separate wrapper objects. this makes some things more intuitive and other things a little more bumpy. however the return type story is now clearer. Fixes: #5503 Change-Id: I629a061823179680dc0723559183859a67ea4db1
* | Fix mysql CREATE TABLE / COLLATE issueGord Thompson2020-08-091-0/+6
|/ | | | | Fixes: #5411 Change-Id: Ib0c53f5ed3f9d3ff0586580c9a9cce73b4b870f4
* Fix typosKarthikeyan Singaravelan2020-08-0917-36/+36
|
* Don't link on_connect to first_connect event handlerMike Bayer2020-08-071-0/+11
| | | | | | | | | | | | | Adjusted the dialect initialization process such that the :meth:`_engine.Dialect.on_connect` is not called a second time on the first connection. The hook is called first, then the :meth:`_engine.Dialect.initialize` is called if that connection is the first for that dialect, then no more events are called. This eliminates the two calls to the "on_connect" function which can produce very difficult debugging situations. Fixes: #5497 Change-Id: Icefc2e884e30ee7b4ac84b99dc54bf992a6085e3
* Merge "Pass schema_translate_map from DDLCompiler to SQLCompiler"mike bayer2020-08-071-0/+10
|\
| * Pass schema_translate_map from DDLCompiler to SQLCompilerMike Bayer2020-08-071-0/+10
| | | | | | | | | | | | | | | | | | | | | | | | Fixed issue where the :paramref:`_engine.Connection.execution_options.schema_translate_map` feature would not take effect when the :meth:`_schema.Sequence.next_value` function function for a :class:`_schema.Sequence` were used in the :paramref:`_schema.Column.server_default` parameter and the create table DDL were emitted. Fixes: #5500 Change-Id: I74a9fa13d22749d06c8202669f9ea220d9d984d9
* | Include bulk update/delete in RoutingSession exampleMike Bayer2020-08-071-2/+4
| | | | | | | | | | Fixes: #5407 Change-Id: Ia0965dbc88d744cded5c23021898388f2cf95f8d
* | base all_orm_descriptors ordering on cls.__dict__ + cls.__mro__Mike Bayer2020-08-061-0/+13
|/ | | | | | | | | | | | | Adjusted the workings of the :meth:`_orm.Mapper.all_orm_descriptors` accessor to represent the attributes in the order that they are located in a deterministic way, assuming the use of Python 3.6 or higher which maintains the sorting order of class attributes based on how they were declared. This sorting is not guaranteed to match the declared order of attributes in all cases however; see the method documentation for the exact scheme. Fixes: #5494 Change-Id: I6ee8d4ace3eb8b3f7c9c0f2a3d7e27b5f62abfd3
* revise asyncio verbiage a bitMike Bayer2020-08-061-10/+11
| | | | Change-Id: I8bdf7c3271b8284ab82e01558024f933e1ee7b49
* Documentation updates for 1.4Mike Bayer2020-08-0519-838/+1341
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * major additions to 1.4 migration doc; removed additional verbosity regarding caching methodology and reorganized the doc to present itself more as a "what's changed" guide * as we now have a path for asyncio, update that doc so that we aren't spreading obsolete information * updates to the 2.0 migration guide with latest info, however this is still an architecture doc and not a migration guide yet, will need further rework. * start really talking about 1.x vs. 2.0 style everywhere. Querying is most of the docs so this is going to be a prominent theme, start getting it to fit in * Add introductory documentation for ORM example sections as these are too sparse * new documentation for do_orm_execute(), many separate sections, adding deprecation notes to before_compile() and similar * new example suites to illustrate do_orm_execute(), with_loader_criteria() * modernized horizontal sharding examples and added a separate example to distinguish between multiple databases and single database w/ multiple tables use case * introducing DEEP ALCHEMY, will use zzzeeksphinx 1.1.6 * no name for the alchemist yet however the dragon's name is Flambé Change-Id: Id6b5c03b1ce9ddb7b280f66792212a0ef0a1c541
* Implement relationship AND criteria; global loader criteriaMike Bayer2020-08-053-4/+65
| | | | | | | | | | | | | | | | | | | Added the ability to add arbitrary criteria to the ON clause generated by a relationship attribute in a query, which applies to methods such as :meth:`_query.Query.join` as well as loader options like :func:`_orm.joinedload`. Additionally, a "global" version of the option allows limiting criteria to be applied to particular entities in a query globally. Documentation is minimal at this point, new examples will be coming in a subsequent commit. Some adjustments to execution options in how they are represented in the ORMExecuteState as well as well as a few ORM tests that forgot to get merged in a preceding commit. Fixes: #4472 Change-Id: I2b8fc57092dedf35ebd16f6343ad0f0d7d332beb
* Convert lazy loader, selectinload, load_on_ident to lambda statementsMike Bayer2020-08-051-29/+5
| | | | | | | | | Building on newly robust lambdas in I29a513c98917b1d503abfdd61e6b6e8800851aa8, convert key loading off of the "baked" system so that baked is no longer used by the ORM. Change-Id: I3abfb45dd6e50f84f29d39434caa0b550ce27864
* Add MariaDB 1927 to is_disconnect codesMike Bayer2020-08-051-0/+7
| | | | | | | | | Added MariaDB code 1927 to the list of "disconnect" codes, as recent MariaDB versions apparently use this code when the database server was stopped. Fixes: #5493 Change-Id: I63f1d692f36cb0411ead278556e3f8c64ab72ea4
* Merge "Establish future behavior for Session cascade backrefs, bind"mike bayer2020-08-054-3/+123
|\
| * Establish future behavior for Session cascade backrefs, bindMike Bayer2020-08-014-3/+123
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The behavior of the :paramref:`_orm.relationship.cascade_backrefs` flag will be reversed in 2.0 and set to ``False`` unconditionally, such that backrefs don't cascade save-update operations from a forwards-assignment to a backwards assignment. A 2.0 deprecation warning is emitted when the parameter is left at its default of ``True`` at the point at which such a cascade operation actually takes place. The new behavior can be established as always by setting the flag to ``False`` on a specific :func:`_orm.relationship`, or more generally can be set up across the board by setting the the :paramref:`_orm.Session.future` flag to True. Additionally in the interests of expediency, this commit will also move Session away from making use of bound metadata if the future=True flag is set. An application that sets future=True should ideally have to change as little else as possible for full 2.0 behavior. Fixes: #5150 Change-Id: I490d1d61f09c62ffc2de983208aeed25dfe48aec
* | Genericize str() for typesMike Bayer2020-08-011-0/+10
|/ | | | | | | | | | | | | | Remove lookup logic that attempts to locate a dialect for a type, just use StrSQLTypeCompiler. Cleaned up the internal ``str()`` for datatypes so that all types produce a string representation without any dialect present, including that it works for third-party dialect types without that dialect being present. The string representation defaults to being the UPPERCASE name of that type with nothing else. Fixes: #4262 Change-Id: I02149e8a1ba1e7336149e962939b07ae0df83c6b
* Merge "Consider default FROM DUAL for MySQL"mike bayer2020-07-291-0/+8
|\
| * Consider default FROM DUAL for MySQLMike Bayer2020-07-291-0/+8
| | | | | | | | | | | | | | | | | | | | | | MySQL claims it doesn't require FROM DUAL for no FROM clause even though the issue at #5481 locates a case which requires one. See if FROM DUAL the same way as Oracle without attempting to guess is potentially feasible. Fixes: #5481 Change-Id: I2a28876c10a8ce2d121cd344dcdd837db321d4ab
* | Merge "Imply `sync_backref` flag in a viewonly relationship"mike bayer2020-07-292-0/+62
|\ \
| * | Imply `sync_backref` flag in a viewonly relationshipFederico Caselli2020-07-072-0/+62
| | | | | | | | | | | | | | | | | | | | | | | | | | | Update :paramref:`_orm.relationship.sync_backref` flag in a relationship to make it implicitly set to False in ``viewonly=True`` relationships, preventing synchronization events in all cases. References: #5237 Change-Id: Ib02b228a1b6e66b5ffd4540af776ac8f759c9a48
* | | Passive deletes editsMike Bayer2020-07-291-63/+71
| | | | | | | | | | | | Change-Id: I863df033cae9bda4ce96d446a92984ae82797565
* | | Remove errant linkMike Bayer2020-07-291-2/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | The link to "passive_deletes" has moved in 9e1ee412b8650761af6df993e119906682604728 however the tag stayed here and caused a self link. Fixes: #5484 Change-Id: I3ac5970be30504367294b9e9a83eb5a2c579cc71
* | | Ensure is_comparison passed for PG RANGE op() methodsJim Bosch2020-07-261-0/+11
| |/ |/| | | | | | | | | | | | | | | | | | | | | | | | | | | Fixed issue where the return type for the various RANGE comparison operators would itself be the same RANGE type rather than BOOLEAN, which would cause an undesirable result in the case that a :class:`.TypeDecorator` that defined result-processing behavior were in use. Pull request courtesy Jim Bosch. Fixes: #5476 Closes: #5477 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5477 Pull-request-sha: 925b117e0c91cdd67d9ddbd9d65f5ca3e88af91f Change-Id: I52ab4d4362d379c8253990f9d328a40990a64520
* | Improve delete cascade and passive deletes sectionsMike Bayer2020-07-264-95/+304
| | | | | | | | | | | | | | | | | | Add cross linking from Core to ORM and also add new sections and examples regarding many-to-many. Move the section out of "collections" and into the "cascades" chapter where it's more likely to be found. Change-Id: If29360e463e5745279bc5335bd12352d50ad8953
* | Allow Grouping to pass along proxy_set of elementMike Bayer2020-07-211-0/+9
| | | | | | | | | | | | | | | | | | | | Repaired an issue where the "ORDER BY" clause rendering a label name rather than a complete expression, which is particularly important for SQL Server, would fail to occur if the expression were enclosed in a parenthesized grouping in some cases. This case has been added to test support. Fixes: #5470 Change-Id: Ie0e27c39e5d53be78b32f7810f93d2d0536375e7
* | Fix mssql dialect escaping object names containing ']'Gord Thompson2020-07-181-0/+6
| | | | | | | | | | Fixes: #5467 Change-Id: I054ec219717ba62847a9daf1214e215dd6b70633
* | Repair doubled "using engines in fork()" sectionMike Bayer2020-07-152-97/+59
| | | | | | | | | | | | | | | | | | This section was written twice in two different ways with the same recipe. consolidate into one section and add additional caveats regading dispose. Change-Id: I20524935e7c10e3624d561ea2735312fd04e673d References: #5460
* | Merge "test single and double quote inspection scenarios"2020_tutorialmike bayer2020-07-131-0/+9
|\ \
| * | test single and double quote inspection scenariosMike Bayer2020-07-131-0/+9
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Applied a sweep through all included dialects to ensure names that contain single or double quotes are properly escaped when querying system tables, for all :class:`.Inspector` methods that accept object names as an argument (e.g. table names, view names, etc). SQLite and MSSQL contained two quoting issues that were repaired. Fixes: #5456 Change-Id: I3bc98806f5166f3d82275650079ff561446f2aef
* | | more docs for autocommit isolation levelMike Bayer2020-07-123-67/+196
|/ / | | | | | | | | | | | | | | this concept is not clear that we offer real DBAPI autocommit everywhere. backport 1.3 with edits as well Change-Id: I2e8328b7fb6e1cdc5453ab29c94276f60c7ca149
* | Convert remaining ORM APIs to support 2.0 styleMike Bayer2020-07-1111-829/+1297
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This is kind of a mixed bag of all kinds to help get us to 1.4 betas. The documentation stuff is a work in progress. Lots of other relatively small changes to APIs and things. More commits will follow to continue improving the documentation and transitioning to the 1.4/2.0 hybrid documentation. In particular some refinements to Session usage models so that it can match Engine's scoping / transactional patterns, and a decision to start moving away from "subtransactions" completely. * add select().from_statement() to produce FromStatement in an ORM context * begin referring to select() that has "plugins" for the few edge cases where select() will have ORM-only behaviors * convert dynamic.AppenderQuery to its own object that can use select(), though at the moment it uses Query to support legacy join calling forms. * custom query classes for AppenderQuery are replaced by do_orm_execute() hooks for custom actions, a separate gerrit will document this * add Session.get() to replace query.get() * Deprecate session.begin->subtransaction. propose within the test suite a hypothetical recipe for apps that rely on this pattern * introduce Session construction level context manager, sessionmaker context manager, rewrite the whole top of the session_transaction.rst documentation. Establish context manager patterns for Session that are identical to engine * ensure same begin_nested() / commit() behavior as engine * devise all new "join into an external transaction" recipe, add test support for it, add rules into Session so it just works, write new docs. need to ensure this doesn't break anything * vastly reduce the verbosity of lots of session docs as I dont think people read this stuff and it's difficult to keep current in any case * constructs like case(), with_only_columns() really need to move to *columns, add a coercion rule to just change these. * docs need changes everywhere I look. in_() is not in the Core tutorial? how do people even know about it? Remove tons of cruft from Select docs, etc. * build a system for common ORM options like populate_existing and autoflush to populate from execution options. * others? Change-Id: Ia4bea0f804250e54d90b3884cf8aab8b66b82ecf
* | Merge "Add future=True to create_engine/Session; unify select()"mike bayer2020-07-085-85/+212
|\ \ | |/ |/|
| * Add future=True to create_engine/Session; unify select()Mike Bayer2020-07-085-85/+212
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Several weeks of using the future_select() construct has led to the proposal there be just one select() construct again which features the new join() method, and otherwise accepts both the 1.x and 2.x argument styles. This would make migration simpler and reduce confusion. However, confusion may be increased by the fact that select().join() is different Current thinking is we may be better off with a few hard behavioral changes to old and relatively unknown APIs rather than trying to play both sides within two extremely similar but subtly different APIs. At the moment, the .join() thing seems to be the only behavioral change that occurs without the user taking any explicit steps. Session.execute() will still behave the old way as we are adding a future flag. This change also adds the "future" flag to Session() and session.execute(), so that interpretation of the incoming statement, as well as that the new style result is returned, does not occur for existing applications unless they add the use of this flag. The change in general is moving the "removed in 2.0" system further along where we want the test suite to fully pass even if the SQLALCHEMY_WARN_20 flag is set. Get many tests to pass when SQLALCHEMY_WARN_20 is set; this should be ongoing after this patch merges. Improve the RemovedIn20 warning; these are all deprecated "since" 1.4, so ensure that's what the messages read. Make sure the inforamtion link is on all warnings. Add deprecation warnings for parameters present and add warnings to all FromClause.select() types of methods. Fixes: #5379 Fixes: #5284 Change-Id: I765a0b912b3dcd0e995426427d8bb7997cbffd51 References: #5159
* | Merge "Add **kw support to DeclarativeMeta.__init__"mike bayer2020-07-071-0/+8
|\ \
| * | Add **kw support to DeclarativeMeta.__init__EwenGillies2020-07-061-0/+8
| |/ | | | | | | | | | | | | | | | | | | | | | | | | Added a ``**kw`` argument to the :meth:`.DeclarativeMeta.__init__` method. This allows a class to support the :pep:`487` metaclass hook ``__init_subclass__``. Pull request courtesy Ewen Gillies. Fixes: #5357 Closes: #5363 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5363 Pull-request-sha: 0ad05a768316cba03a4d312ab39d3e8fbca7ac54 Change-Id: I1654befe9eb1c8b8e7fc0784bdbe64284614f0ea
* | Consolidate connection customization documentationMike Bayer2020-07-062-46/+73
|/ | | | | | | | | | | | | | | | | | | 1. move all discussion of how to customize connection to the engines.rst section. have the section in pooling.rst point to engines. 2. ensure all of the common use cases for connection modification are listed out in order of level of modification. the use case of modifying an existing connection is separate from that of modifying how connect is called; ensure that poolevents.connect is referred to just as prominently as dialectevents.do_connect. 3. completely replace any discussion of create_engine.creator, as this hook does not offer anything beyond what do_connect() does. "creator" is more about using a Pool object directly without an Engine, which is no longer a documented use case. Change-Id: Ibe366d2a6e63eb420a6136fdc71ce0fb545edf8f
* introduce deferred lambdasMike Bayer2020-07-037-8/+757
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The coercions system allows us to add in lambdas as arguments to Core and ORM elements without changing them at all. By allowing the lambda to produce a deterministic cache key where we can also cheat and yank out literal parameters means we can move towards having 90% of "baked" functionality in a clearer way right in Core / ORM. As a second step, we can have whole statements inside the lambda, and can then add generation with __add__(), so then we have 100% of "baked" functionality with full support of ad-hoc literal values. Adds some more short_selects tests for the moment for comparison. Other tweaks inside cache key generation as we're trying to approach a certain level of performance such that we can remove the use of "baked" from the loader strategies. As we have not yet closed #4639, however the caching feature has been fully integrated as of b0cfa7379cf8513a821a3dbe3028c4965d9f85bd, we will also add complete caching documentation here and close that issue as well. Closes: #4639 Fixes: #5380 Change-Id: If91f61527236fd4d7ae3cad1f24c38be921c90ba
* Add missing function to documentation: cte, values, Exits, ValuesFederico Caselli2020-06-301-0/+10
| | | | | Fixes: #5432 Change-Id: I22e4ba3a7131165c551bcba7e377fa45d71d70e0
* Merge "Rename Table.tometadata to to_metadata"mike bayer2020-06-292-0/+8
|\
| * Rename Table.tometadata to to_metadataGord Thompson2020-06-292-0/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Renamed the :meth:`_schema.Table.tometadata` method to :meth:`_schema.Table.to_metadata`. The previous name remains with a deprecation warning. Updated the "decorate" utility function to support decoration of functions that include non-builtins as default values. Moves test for deprecated "databases" package into test/dialect/test_deprecations.py Fixes: #5413 Fixes: #5426 Change-Id: I6ed899871c935f9e46360127c17ccb7cf97cea6e
* | Docuemnt current workarounds for MySQL TIMESTAMPMike Bayer2020-06-291-0/+9
|/ | | | | | | | | | | MySQL 8 no longer generates the DEFAULT or ON UPDATE clauses for TIMESTAMP by default, hence users will begin to hit this regularly. add warnings that this non-standard SQL is not accommodated by server_onupdate and docuemnt the workaround used in issues such as #4652. Fixes: #5427 Change-Id: Ie048dcc91c648dd0b80ed395208c1d665b6c968b
View Lorry Controller Status