summaryrefslogtreecommitdiff
path: root/doc/build/faq
Commit message (Collapse)AuthorAgeFilesLines
* Fixes related to improved sql formattingFederico Caselli2023-01-122-29/+61
| | | | | | Follow up of I07b72e6620bb64e329d6b641afa27631e91c4f16 Change-Id: I1f61974bf9cdc3da5317e546d4f9b649c2029e4d
* Improve sql formattingFederico Caselli2023-01-112-8/+8
| | | | | | change {opensql} to {printsql} in prints, add missing markers Change-Id: I07b72e6620bb64e329d6b641afa27631e91c4f16
* update rel/fk FAQ entryMike Bayer2022-10-281-10/+17
| | | | | | | | | | | | | this entry still made the assumptions of behavior before ticket #3061, that accessing a non-initialized scalar attribute on a pending object would populate the attribute with None. It also used the word "initialize" when referring to a persistent object which is a misleading term, it's "loaded", even though in this example it's "loading" the value of None. Fix up the language to be more consistent with the #3061 change. Change-Id: I1abd8f1d2e9c44ebc9a29737ea270b338f104a3e
* further 2.0 modernizationsMike Bayer2022-10-131-1/+1
| | | | | | | biggest change here is the old tutorials were removed from the TOC and some additional links to them have been corrected. Change-Id: I79b878a946422eac24ed2449b440fc5d556576c4
* fixes for doc buildsMike Bayer2022-10-131-1/+1
| | | | | | | * requirements needs typing_extensions * update all "future=True" references to be appropriate to 2.0 Change-Id: I2eeb0ae65afdb587f21aeb0020f1d8a292f67c21
* Remove all formatting errorsFederico Caselli2022-10-036-16/+48
| | | | | | Improve format docs script, replace {sql} with {opensql} Change-Id: Ie1aaa8f3d8ff8f8e89b7b5149a1876d9f8a211ed
* Add proper code block formattingFederico Caselli2022-10-024-12/+32
| | | | Change-Id: I63585eeae0b0bc78109da64520696928dfb3982c
* Improvements to code formatterFederico Caselli2022-10-023-8/+8
| | | | Change-Id: I75cf7143f3ed3bbc09aa8bc18edbce5c8af0f0be
* Format code in the rst docs fileFederico Caselli2022-09-307-131/+159
| | | | | | | | Added script to format code in the rst documentation using black. This is also added to the lint tox job to ensure that the code in the docs is properly formatted. Change-Id: I799444f22da153484ca5f095d57755762348da40
* implement batched INSERT..VALUES () () for executemanyMike Bayer2022-09-241-230/+10
| | | | | | | | | | | | | | | | | | | | the feature is enabled for all built in backends when RETURNING is used, except for Oracle that doesn't need it, and on psycopg2 and mssql+pyodbc it is used for all INSERT statements, not just those that use RETURNING. third party dialects would need to opt in to the new feature by setting use_insertmanyvalues to True. Also adds dialect-level guards against using returning with executemany where we dont have an implementation to suit it. execute single w/ returning still defers to the server without us checking. Fixes: #6047 Fixes: #7907 Change-Id: I3936d3c00003f02e322f2e43fb949d0e6e568304
* migrate labels to new tutorialMike Bayer2022-06-072-15/+10
| | | | | | | other org changes and some sections from old tutorial ported to new tutorial. Change-Id: Ic0fba60ec82fff481890887beef9ed0fa271875a
* repair incorrect "cursor" var name in connection faqJosep Pascual Badia2022-05-301-3/+3
| | | | | | | | Closes: #8075 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/8075 Pull-request-sha: 34e5eaf3870f89c9c38ffe81121fa1b42e363752 Change-Id: Iab8cdc9f8da68ac955eea75efeba263d0a9dcb7b
* explicitly refer to Apple M1 for greenlet issueMike Bayer2022-04-082-0/+30
| | | | | | | | | | | | | | | | | | | As developers are now buying lots of Apple M1 machines, and AFAWK greenlet is still not able to provide a pre-built wheel, we are going to get a lot of devs trying to use asyncio on their Apple M1s, in greater proportions compared to devs running containers etc. on other various less popular CPU architectures. Add a new FAQ section for installation, add new red dragon to the very top of asyncio docs, add new verbiage, all of which includes "Apple M1" in bold text, to minimize the chance of anyone missing this. Fixes: #7922 Fixes: #7714 Change-Id: I106923a2860a4efd77d1b999197be102afc1f73d
* Upgrade parts of the documentation to 2.0 styleprovinzkraut2022-03-223-31/+28
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | <!-- Provide a general summary of your proposed changes in the Title field above --> I've started to work on #7659, implementing the low hanging fruit changes for now. Some still remain, which I've outlined as a [comment](https://github.com/sqlalchemy/sqlalchemy/issues/7659#issuecomment-1073029151), and probably also some that I didn't catch. <!-- 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. **Have a nice day!** Closes: #7829 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/7829 Pull-request-sha: a89561dd0c96c2f9a6d992fa0fb94683afaf7e30 Change-Id: Ibc5ea94b5c4b2d7b1cf7bea24f4394d1fde749be
* pep-484 for poolMike Bayer2022-02-171-15/+15
| | | | | | | | | | | | | | | | | also extends into some areas of utils, events and others as needed. Formalizes a public hierarchy for pool API, with ManagesConnection -> PoolProxiedConnection / ConnectionPoolEntry for connectionfairy / connectionrecord, which are now what's exposed in the event API and other APIs. all public API docs moved to the new objects. Corrects the mypy plugin's check for sqlalchemy-stubs not being insatlled, which has to be imported using the dash in the name to be effective. Change-Id: I16c2cb43b2e840d28e70a015f370a768e70f3581
* Merge "Fix various source comment/doc typos" into mainmike bayer2022-01-071-2/+2
|\
| * Fix various source comment/doc typosluz paz2021-12-291-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ### Description Found via `codespell -q 3 -L ba,crate,datas,froms,gord,hist,inh,nd,selectin,strat,ue` Also added codespell to the pep8 tox env ### Checklist This pull request is: - [x] A documentation / typographical error fix - Good to go, no issue or tests are needed Closes: #7338 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/7338 Pull-request-sha: 0deac2219396bc0eba7da53eb3a80932edbf2dd7 Change-Id: Icd61db31c8dc655d4a39d8a304194804d08555fe
* | Remove all remaining removed_in_20 warnings slated for removalMike Bayer2022-01-051-2/+2
|/ | | | | | | | | | | | | | | | | | | | | | | | | Finalize all remaining removed-in-2.0 changes so that we can begin doing pep-484 typing without old things getting in the way (we will also have to do public_factory). note there are a few "moved_in_20()" and "became_legacy_in_20()" warnings still in place. The SQLALCHEMY_WARN_20 variable is now removed. Also removed here are the legacy "in place mutators" for Select statements, and some keyword-only argument signatures in Core have been added. Also in the big change department, the ORM mapper() function is removed entirely; the Mapper class is otherwise unchanged, just the public-facing API function. Mappers are now always given a registry in which to participate, however the argument signature of Mapper is not changed. ideally "registry" would be the first positional argument. Fixes: #7257 Change-Id: Ic70c57b9f1cf7eb996338af5183b11bdeb3e1623
* Merge "Warn when caching is disabled / document" into mainmike bayer2021-12-071-0/+160
|\
| * Warn when caching is disabled / documentMike Bayer2021-12-061-0/+160
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This patch adds new warnings for all elements that don't indicate their caching behavior, including user-defined ClauseElement subclasses and third party dialects. it additionally adds new documentation to discuss an apparent performance degradation in 1.4 when caching is disabled as a result in the significant expense incurred by ORM lazy loaders, which in 1.3 used BakedQuery so were actually cached. As a result of adding the warnings, a fair degree of lesser used SQL expression objects identified that they did not define caching behavior so would have been producing ``[no key]``, including PostgreSQL constructs ``hstore`` and ``array``. These have been amended to use inherit cache where appropriate. "on conflict" constructs in PostgreSQL, MySQL, SQLite still explicitly don't generate a cache key at this time. The change also adds a test for all constructs via assert_compile() to assert they will not generate cache warnings. Fixes: #7394 Change-Id: I85958affbb99bfad0f5efa21bc8f2a95e7e46981
* | qualify the stringification warningMike Bayer2021-12-061-2/+4
|/ | | | | | | | the recipe which uses render_postcompile itself is not insecure as it still renders bound parameters and does not stringify any literal values. Change-Id: Ib5ac2f7ce37dc1415a67b117a9c31c0ee37270b3
* Remove object in class definitionFederico Caselli2021-11-221-1/+1
| | | | | References: #4600 Change-Id: I2a62ddfe00bc562720f0eae700a497495d7a987a
* De-emphasize notion of "default driver" (DBAPI)Gord Thompson2021-11-092-7/+7
| | | | | | | | | | | Fixes: #6960 Even though a default driver still exists for each dialect, remove most usages of `dialect://` to encourage users to explicitly specify `dialect+driver://` Change-Id: I0ad42167582df509138fca64996bbb53e379b1af
* Revise "literal parameters" FAQ sectionMike Bayer2021-11-011-36/+218
| | | | | | | | | | based on feedback in #7271, the emphasis on TypeDecorator as a solution to this problem is not very practical. illustrate a series of quick recipes that are useful for debugging purposes to print out a repr() or simple stringify of a parameter without the need to construct custom dialects or types. Change-Id: I788ce1b5ea01d88dd0a22d03d06f35aabff5e5c8
* 📚 DOCS: Update performance scriptChris Sewell2021-10-041-130/+172
| | | | Updated to Python 3, and to use `future=True`. Also added outputs for `return_default=True`
* Surface driver connection object when using a proxied dialectFederico Caselli2021-09-171-8/+87
| | | | | | | | | | | | | | | | | | | | | | | | | | Improve the interface used by adapted drivers, like the asyncio ones, to access the actual connection object returned by the driver. The :class:`_engine._ConnectionRecord` and :class:`_engine._ConnectionFairy` now have two new attributes: * ``dbapi_connection`` always represents a DBAPI compatible object. For pep-249 drivers, this is the DBAPI connection as it always has been, previously accessed under the ``.connection`` attribute. For asyncio drivers that SQLAlchemy adapts into a pep-249 interface, the returned object will normally be a SQLAlchemy adaption object called :class:`_engine.AdaptedConnection`. * ``driver_connection`` always represents the actual connection object maintained by the third party pep-249 DBAPI or async driver in use. For standard pep-249 DBAPIs, this will always be the same object as that of the ``dbapi_connection``. For an asyncio driver, it will be the underlying asyncio-only connection object. The ``.connection`` attribute remains available and is now a legacy alias of ``.dbapi_connection``. Fixes: #6832 Change-Id: Ib72f97deefca96dce4e61e7c38ba430068d6a82e
* fix: typos in doc/build/changelog (#7004)Kevin Kirsche2021-09-081-1/+1
|
* standardizing docs #6821jonathan vanasco2021-08-232-9/+9
| | | | | | | | | | | | | | | | | | | | | | | | | (redo of 2999/I5609025feee8cfdecc09b55bfbf1bd13fa2e6602) This PR is designed to bring more clarity within the docs by renaming object instances that may be consfusingly similar to class, method, and attribute names. For example, instances of the class `MetaData` are available on some objects as `.metadata` property, and had appeared within the docs as both `meta` and `metadata` which has confused some users in the past. By this PR, the docs now utilize the following naming convention: * MetaData - SQLAlchemy class * .metadata - SQLAlchemy API attributes * metadata_obj - developer instantiated metadata objects or references Detailed Changes: * standardized `meta` and `metadata` instances to `metadata_obj`. note: the docs were evenly split between 'meta' and 'metadata'. * standardized 'cursor' to 'cursor_obj' to avoid confusion with the method. * standardized a 'scalar_subquery = ' to 'scalar_subq' to avoid confusion with the method. * standardized a 'cte = ' to 'cte_obj' to avoid confusion with the method Change-Id: I79c98aee16c5fc6649289b2dd7d6dfc368222fb4
* Replace all http:// links to https://Federico Caselli2021-07-045-7/+7
| | | | | | Also replace http://pypi.python.org/pypi with https://pypi.org/project Change-Id: I84b5005c39969a82140706472989f2a30b0c7685
* FAQ for render_postcompileMike Bayer2021-04-081-0/+31
| | | | | Change-Id: If0231623491d7901046c76af3461f33ba504ff53 References: #6230
* provide FAQ entry for percent sign escaping in SQL compilerMike Bayer2021-01-131-0/+55
| | | | | | this is coming up more than once so provide a document Change-Id: I23dcd4c7a6527b2f33502e67ffad4335f895e6f9
* tutorial 2.0 WIPreview/mike_bayer/tutorial20Mike Bayer2020-10-311-2/+3
| | | | | | | | | | | | | | Add SelectBase.exists() method as it seems strange this is not available already. The Exists construct itself does not provide full SELECT-building capabilities so it makes sense this should be used more like a scalar_subquery. Make sure stream_results is getting set up when yield_per is used, for 2.0 style statements as well. this was hardcoded inside of Query.yield_per() and is now moved to take place within QueryContext. Change-Id: Icafcd4fd9b708772343d56edf40995c9e8f835d6
* Add FAQ entry for retry subject; recipe w/ autocommitMike Bayer2020-10-191-0/+204
| | | | | | | | | | | | | | | | | In order to invalidate a connection within a Transaction block and an execution context, we need to take advantage of the simpler transaction design added in 1.4. The recipe can be done on 1.3 but it requires a lot more hacking and isn't worth it. Clearly since the recipe is part of the tests now we can in the future consider adding a feature that's built in for this case but it would have to absolutely guarantee the DBAPI is in autocommit mode and also prevent any "write" operations from taking place. Recipe for now. Fixes: #5657 Change-Id: Ia9ea8cced084d154e83e4d1c259e080b776ec38a
* Build out new declarative systems; deprecate mapper()Mike Bayer2020-09-101-1/+1
| | | | | | | | | | | | | The ORM Declarative system is now unified into the ORM itself, with new import spaces under ``sqlalchemy.orm`` and new kinds of mappings. Support for decorator-based mappings without using a base class, support for classical style-mapper() calls that have access to the declarative class registry for relationships, and full integration of Declarative with 3rd party class attribute systems like ``dataclasses`` and ``attrs`` is now supported. Fixes: #5508 Change-Id: I130b2b6edff6450bfe8a3e6baa099ff04b5471ff
* Add 3rd party integration issues FAQ; add numpyMike Bayer2020-09-102-0/+76
| | | | | | | | | Users of numpy and pandas should refer to this section where we will try to catalog the common issues that don't really have an automatic solution. Fixes: #5552 Change-Id: I02990e328616ccb21933ffda1167c52256bace07
* Add more docs for populate_existing(); link with_for_updateMike Bayer2020-09-101-0/+1
| | | | | | | | | | | | | The populate_existing() method is actually changing to be an execution option, however it has almost no mention in the narrative docs so add docs in terms of the 1.x version first, including that we mention you almost definitely want to use this method if you are also using with_for_update(). Fixes: #5572 Fixes: #4774 Change-Id: Ieca916400622c1ffc1ae81204132a02a0983594c
* Update select usage to use the new 1.4 formatFederico Caselli2020-09-081-2/+2
| | | | | | | | | | | | | | | | This change includes mainly that the bracketed use within select() is moved to positional, and keyword arguments are removed from calls to the select() function. it does not yet fully address other issues such as keyword arguments passed to the table.select(). Additionally, allows False / None to both be considered as "disable" for all of select.correlate(), select.correlate_except(), query.correlate(), which establishes consistency with passing of ``False`` for the legact select(correlate=False) argument. Change-Id: Ie6c6e6abfbd3d75d4c8de504c0cf0159e6999108
* Repair doubled "using engines in fork()" sectionMike Bayer2020-07-151-77/+2
| | | | | | | | | 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
* introduce deferred lambdasMike Bayer2020-07-031-0/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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
* Fix a wide variety of typos and broken linksaplatkouski2020-06-251-1/+1
| | | | | | | | | | | | Note the PR has a few remaining doc linking issues listed in the comment that must be addressed separately. Signed-off-by: aplatkouski <5857672+aplatkouski@users.noreply.github.com> Closes: #5371 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5371 Pull-request-sha: 7e7d233cf3a0c66980c27db0fcdb3c7d93bc2510 Change-Id: I9c36e8d8804483950db4b42c38ee456e384c59e3
* Improve ``Rendering Bound Parameters Inline`` documentationFederico Caselli2020-06-041-6/+11
| | | | | | This is mainly to make this section more discoverable by users Change-Id: I58ba19e4a9ae85b227e5b5553ba5c30c01f3e005
* Documentation updates for ResultProxy -> ResultMike Bayer2020-05-011-1/+1
| | | | | | | | | This is based off of I8091919d45421e3f53029b8660427f844fee0228 and includes all documentation-only changes as a separate merge, once the parent is merged. Change-Id: I711adea23df0f9f0b1fe7c76210bd2de6d31842d
* Set up absolute references for create_engine and relatedMike Bayer2020-04-142-6/+6
| | | | | | | includes more replacements for create_engine(), Connection, disambiguation of Result from future/baked Change-Id: Icb60a79ee7a6c45ea9056c211ffd1be110da3b5e
* Run search and replace of symbolic module namesMike Bayer2020-04-146-71/+71
| | | | | | | | Replaces a wide array of Sphinx-relative doc references with an abbreviated absolute form now supported by zzzeeksphinx. Change-Id: I94bffcc3f37885ffdde6238767224296339698a2
* Enable zzzeeksphinx module prefixesMike Bayer2020-04-142-6/+6
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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
* Correct ambiguous func / class linksMike Bayer2020-03-252-2/+2
| | | | | | | | | :func:`.sql.expression.select`, :func:`.sql.expression.insert` and :class:`.sql.expression.Insert` were hitting many ambiguous symbol errors, due to future.select, as well as the PG/MySQL variants of Insert. Change-Id: Iac862bfc172a7f7f0cbba5353a83dc203bed376c
* Remove print statement in favor of print() function in docs and examplesAlbert Tugushev2020-02-261-4/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | <!-- Provide a general summary of your proposed changes in the Title field above --> ### Description <!-- Describe your changes in detail --> Remove print statements ### 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. **Have a nice day!** Closes: #5166 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5166 Pull-request-sha: 04a7394f71298322188f0861b4dfe93e5485839d Change-Id: Ib90a59fac929661a18748c6e44966fb87e3978c6
* import StringIO => import ioMatt Kohl2019-10-041-2/+2
|
* Document Query deduplicationMike Bayer2019-09-051-0/+72
| | | | | | | | | | Users are frequently confused why count() does not return the same number as the number of objects returned by all(). While we continue to want to find a better solution to this problem, in the meantime this has never been clearly documented. Add an FAQ section with links from .count() , .all(), ORM tutorial. Change-Id: I6eff36b686ff6cdd55489036fc48a981bc47d5ee
* Remove threadlocal engine strategy, engine strategies pool threadlocalMike Bayer2019-07-151-3/+8
| | | | | | | | | | | | The "threadlocal" execution strategy, deprecated in 1.3, has been removed for 1.4, as well as the concept of "engine strategies" and the ``Engine.contextual_connect`` method. The "strategy='mock'" keyword argument is still accepted for now with a deprecation warning; use :func:`.create_mock_engine` instead for this use case. Fixes: #4632 Change-Id: I8a351f9fa1f7dfa2a56eec1cd2d1a4b9d65765a2 (cherry picked from commit b368c49b44c5716d93c7428ab22b6761c6ca7cf5)
View Lorry Controller Status