summaryrefslogtreecommitdiff
path: root/doc/build/tutorial
Commit message (Collapse)AuthorAgeFilesLines
* Merge "add deterministic imv returning ordering using sentinel columns" into ↵mike bayer2023-04-213-4/+18
|\ | | | | | | main
| * add deterministic imv returning ordering using sentinel columnsMike Bayer2023-04-213-4/+18
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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
* | fix typo ('resemblence' -> 'resemblance') (#9674)Tim Stewart2023-04-201-5/+1
|/
* Update data_select.rst (#9616)Chris2023-04-071-1/+1
| | | Fix literal text in example
* docs: 📚 fix duplicate word typo (#9539)Tom Wolfskämpf2023-03-251-1/+1
|
* add tip that reflection is not necessary for an existing databaseMike Bayer2023-03-211-2/+13
| | | | | | | a new user spent many days misled by this paragraph thinking they were required to use reflection for an existing database. Change-Id: I4c6757b931481db7a8d4202334382143e1491935
* additional consistency for ORM/Core in tutorialMike Bayer2023-03-085-13/+41
| | | | | | | | | | | * Make sure we have blue borders for all sections * rewrite "blue border" text, refer to textual means of determining subject matter for a section; "blue borders" are not a primary source of information * Add some more intro text that was missing Change-Id: I4d599e13d23bad8bb3c199a11afb53e3e9100c59 References: #9450
* Remove duplicate word in tutorial (#9420)Viicos2023-03-031-1/+1
|
* Fix Typo In Tutorial (#9399)easy_markie_tee2023-03-011-1/+1
| | | | | | | Missing a word on the page `Working with Database Metadata`. First paragraph under section 'Setting up MetaData with Table objects'. "...the database which we query from is know [as] a table." Co-authored-by: markie tee <cassette.head@gmail.com>
* Unify doc typingHarry Lees2023-01-311-3/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ### 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
* reword INSERT explanationMike Bayer2023-01-191-29/+65
| | | | Change-Id: I08460f0a77131c8c1406c3496e9d64a5a26bf6ff
* avoid confusion in rst commentFederico Caselli2023-01-181-1/+1
| | | | Change-Id: I6e971f7445ae19f73097516b58776ab05a5371f1
* super-fine pass through the metadata tutorialMike Bayer2023-01-151-130/+143
| | | | | | | | | | 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
* fix orm-header for standaloneMike Bayer2023-01-151-1/+1
| | | | Change-Id: I20e7f8ad5800c2ce5cdc9645c4dbe66f53b8cdf8
* fix typoMike Bayer2023-01-131-1/+1
| | | | Change-Id: I273459175a3c55290b1f6c28f656ed9c4db17ccf
* Make the custom type map more discoverableFederico Caselli2023-01-131-16/+24
| | | | Change-Id: Id6cdaddad83aa93508e256e54010a6c53218b717
* Fixes related to improved sql formattingFederico Caselli2023-01-121-11/+9
| | | | | | Follow up of I07b72e6620bb64e329d6b641afa27631e91c4f16 Change-Id: I1f61974bf9cdc3da5317e546d4f9b649c2029e4d
* Improve sql formattingFederico Caselli2023-01-117-140/+140
| | | | | | change {opensql} to {printsql} in prints, add missing markers Change-Id: I07b72e6620bb64e329d6b641afa27631e91c4f16
* remove anchor removed by mistakeMike Bayer2023-01-091-0/+2
| | | | Change-Id: I20e196f63c8cea9cd805501ab174cab320575b05
* fix inconsistent title levelMike Bayer2023-01-091-1/+1
| | | | Change-Id: I954818fdf9f5b56a895dbfdaf191c4c5867b574f
* more thoughts on tutorial presentation of ORM /CoreMike Bayer2023-01-044-47/+82
| | | | Change-Id: Iaa0c160e3f8285f1ca989dcb12b86de15ea82f03
* tutorial updates re: Core /ORM commonalityMike Bayer2023-01-033-32/+35
| | | | | | | | | | | updates for Insert / bulk insert, executemanyvalues, as well as beginning to describe Table / declared class more closely together, mentioning typing support. Fixed a long-standing issue where sphinx would complain about the Insert symbol being ambiguous. Change-Id: Id4cc09b9581e8fa39c9c00bc8f229636e626e9bc
* Oracle COLUMN_VALUE is a column name, not a keywordMike Bayer2022-12-071-1/+1
| | | | | | | | | Fixed issue in Oracle compiler where the syntax for :meth:`.FunctionElement.column_valued` was incorrect, rendering the name ``COLUMN_VALUE`` without qualifying the source table correctly. Fixes: #8945 Change-Id: Ia04bbdc68168e78b67a74bb3834a63f5d5000627
* Small tutorial rewordingAndy Garfield2022-11-151-1/+1
| | | The language is this sentence took me a few reads to understand. This is just a rewording.
* further 2.0 modernizationsMike Bayer2022-10-131-8/+7
| | | | | | | 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-132-5/+4
| | | | | | | * requirements needs typing_extensions * update all "future=True" references to be appropriate to 2.0 Change-Id: I2eeb0ae65afdb587f21aeb0020f1d8a292f67c21
* update executemany for new featuresMike Bayer2022-10-111-23/+28
| | | | | | | | also fixes issue in format_docs_code which didn't work with pre-commit for more than one file. will backport Fixes: #8597 Change-Id: I21b2625514987b1cd90f7c00f06e72e57e257390
* the future is hereMike Bayer2022-10-025-44/+44
| | | | | | | | | the autodoc for the "future" Engine / Connection were removed, so all these links weren't working. Replace all _future for these with _engine. There was just one _future pointing to select, changed that separately. Change-Id: Ib28270d8da8616b533953204e22eabee9388d620
* Add proper code block formattingFederico Caselli2022-10-022-9/+9
| | | | Change-Id: I63585eeae0b0bc78109da64520696928dfb3982c
* Improvements to code formatterFederico Caselli2022-10-022-17/+17
| | | | Change-Id: I75cf7143f3ed3bbc09aa8bc18edbce5c8af0f0be
* add disable doctest tag for autodoc test suiteMike Bayer2022-10-011-24/+37
| | | | | | | | | | | ahead of trying to get everything formatted, some more flexibility so that we can use doctest for all python + sql code, while still being able to tell the test suite to not run doctests on a sample. All of the "non-console python with SQL" in the docs is because I was showing an example that I didn't want tested. Change-Id: Iae876ae1ffd93c36b096c6c2d6048843ae9698c8
* Format code in the rst docs fileFederico Caselli2022-09-307-300/+293
| | | | | | | | 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
* New ORM Query Guide featuring DML supportMike Bayer2022-09-253-342/+60
| | | | | | | | | | | | | | | | | reviewers: these docs publish periodically at: https://docs.sqlalchemy.org/en/gerrit/4042/orm/queryguide/index.html See the "last generated" timestamp near the bottom of the page to ensure the latest version is up Change includes some other adjustments: * small typing fixes for end-user benefit * removal of a bunch of old examples for patterns that nobody uses or aren't really what we promote now * modernization of some examples, including inheritance Change-Id: I9929daab7797be9515f71c888b28af1209e789ff
* implement batched INSERT..VALUES () () for executemanyMike Bayer2022-09-242-8/+6
| | | | | | | | | | | | | | | | | | | | 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
* remove obtuse section about "bundled bind parameters"Mike Bayer2022-09-171-45/+3
| | | | | | | | | | | | | Just looking for basics on insert in the first pages of the tutorial I see this weird detour into something that nobody ever uses and definitely isn't going to make sense to the people I see complaining about our docs on twitter, remove this. the tutorial probably needs a big sweep for wordy obtuse things. the userbase is changing and we really have a lot of brand-new-to-programming types coming in. Change-Id: I3bb11f0399e55edbb8f874e7eb63c40616b04e8b
* add docs for session.get()Mike Bayer2022-09-071-2/+2
| | | | | | | also use the term "primary key" a bit more Change-Id: Ib654b30a9d06a2aeed019b4754db920afe05d774 References: https://twitter.com/encthenet/status/1567644850471989248
* implement tuple-slices from .c collectionsMike Bayer2022-08-011-0/+13
| | | | | | | | | | | | Added new syntax to the ``.c`` collection on all :class:`.FromClause` objects allowing tuples of keys to be passed to ``__getitem__()``, along with support for ``select()`` handling of ``.c`` collections directly, allowing the syntax ``select(table.c['a', 'b', 'c'])`` to be possible. The sub-collection returned is itself a :class:`.ColumnCollection` which is also directly consumable by :func:`_sql.select` and similar now. Fixes: #8285 Change-Id: I2236662c477ffc50af079310589e213323c960d1
* update ORM declarative docs for new featuresMike Bayer2022-07-162-156/+208
| | | | | | | I screwed up a rebase or something so this was temporarily in Ic51a12de3358f3a451bd7cf3542b375569499fc1 Change-Id: I847ee1336381221c0112b67854df022edf596b25
* fix documentation typoJefferson Oliveira2022-06-291-1/+1
|
* sub-categorize special function formsMike Bayer2022-06-221-4/+13
| | | | | | | | | | | | | this is the tutorial, which should have some semblence of not getting too far into the weeds. however, as we dont really have other places to explain SQL concepts, and SQL functions have a lot of them, we dont have another home right now. so at least further sub-categorize window functions, table/column valued functions, and WITHIN GROUP into an "advanced function techniques" section with a disclaimer that these are less common use cases. Change-Id: I4b16bd5673c0bd39a9b880338f6ce3cfbafbe271
* rearchitect reflection for batched performanceFederico Caselli2022-06-181-1/+1
| | | | | | | | | | | | | | | | | | | | | | | Rearchitected the schema reflection API to allow some dialects to make use of high performing batch queries to reflect the schemas of many tables at once using much fewer queries. The new performance features are targeted first at the PostgreSQL and Oracle backends, and may be applied to any dialect that makes use of SELECT queries against system catalog tables to reflect tables (currently this omits the MySQL and SQLite dialects which instead make use of parsing the "CREATE TABLE" statement, however these dialects do not have a pre-existing performance issue with reflection. MS SQL Server is still a TODO). The new API is backwards compatible with the previous system, and should require no changes to third party dialects to retain compatibility; third party dialects can also opt into the new system by implementing batched queries for schema reflection. Along with this change is an updated reflection API that is fully :pep:`484` typed, features many new methods and some changes. Fixes: #4379 Change-Id: I897ec09843543aa7012bcdce758792ed3d415d08
* migrate labels to new tutorialMike Bayer2022-06-074-7/+156
| | | | | | | other org changes and some sections from old tutorial ported to new tutorial. Change-Id: Ic0fba60ec82fff481890887beef9ed0fa271875a
* Update dbapi_transactions.rst (#8032)Robert Kulagowski2022-05-181-1/+1
| | | If you're defining 'y=row.y' then you might as well use 'y' in the print statement.
* fix most sphinx warnings (1.4)Mike Bayer2022-05-162-2/+1
| | | | | | | | | | | | | | | still can't figure out the warnings with some of the older changelog files. this cherry-picks the sphinx fixes from 1.4 and additionally fixes a small number of new issues in the 2.0 docs. However, 2.0 has many more errors to fix, primarily from the removal of the legacy tutorials left behind a lot of labels that need to be re-linked to the new tutorial. Fixes: #7946 Change-Id: Id657ab23008eed0b133fed65b2f9ea75a626215c (cherry picked from commit 9b55a423459236ca8a2ced713c9e93999dd18922)
* more expire_on_commit remindersMike Bayer2022-05-131-0/+23
| | | | | | | | | | | | the session commit/close docs still feel awkward in how one learns about this operation. hopefully another pass over 2.0 can make things more linear. removed a 1.4 note about autobegin that was completely inaccurate; commit() does autobegin so it has an effect, just not usually on the database. Change-Id: Iaa4b96bd3df6cf82e851b2943322ddad7abbbac0
* clarify alternative mapping exampleMike Bayer2022-04-031-0/+12
| | | | | | | | | | | | | | this second example is not part of the doctest steps, clarify that it's not part of code examples to be present in execution steps. Add an extra registry + declarative base on top so that even if someone does run it, the Base will have been reset and the examples will continue to work (noting that column order in statements may change, but probably nothing else). Fixes: #7891 Change-Id: Icb1ba310230841e502185d9d0cadd3c18d467292
* fix small indentation typo (#7882)Maple2022-04-031-5/+5
|
* ORM quickstartMike Bayer2022-03-112-0/+19
| | | | | | | | | This is done in 1.4 style so it can be backported to 1.4. Will put this up as is, we can work on it. For 2.0, the ORM mapping will be updated to mapped_column() style when we do the full pass. Change-Id: Icfdf81449973844dac244b3a107ce955a7d3b16c
* pep-484 for engineMike Bayer2022-03-013-8/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | All modules in sqlalchemy.engine are strictly typed with the exception of cursor, default, and reflection. cursor and default pass with non-strict typing, reflection is waiting on the multi-reflection refactor. Behavioral changes: * create_connect_args() methods return a tuple of list, dict, rather than a list of list, dict * removed allow_chars parameter from pyodbc connector ._get_server_version_info() method * the parameter list passed to do_executemany is now a list in all cases. previously, this was being run through dialect.execute_sequence_format, which defaults to tuple and was only intended for individual tuple params. * broke up dialect.dbapi into dialect.import_dbapi class method and dialect.dbapi module object. added a deprecation path for legacy dialects. it's not really feasible to type a single attr as a classmethod vs. module type. The "type_compiler" attribute also has this problem with greater ability to work around, left that one for now. * lots of constants changing to be Enum, so that we can type them. for fixed tuple-position constants in cursor.py / compiler.py (which are used to avoid the speed overhead of namedtuple), using Literal[value] which seems to work well * some tightening up in Row regarding __getitem__, which we can do since we are on full 2.0 style result use * altered the set_connection_execution_options and set_engine_execution_options event flows so that the dictionary of options may be mutated within the event hook, where it will then take effect as the actual options used. Previously, changing the dict would be silently ignored which seems counter-intuitive and not very useful. * A lot of DefaultDialect/DefaultExecutionContext methods and attributes, including underscored ones, move to interfaces. This is not fully ideal as it means the Dialect/ExecutionContext interfaces aren't publicly subclassable directly, but their current purpose is more of documentation for dialect authors who should (and certainly are) still be subclassing the DefaultXYZ versions in all cases Overall, Result was the most extremely difficult class hierarchy to type here as this hierarchy passes through largely amorphous "row" datatypes throughout, which can in fact by all kinds of different things, like raw DBAPI rows, or Row objects, or "scalar"/Any, but at the same time these types have meaning so I tried still maintaining some level of semantic markings for these, it highlights how complex Result is now, as it's trying to be extremely efficient and inlined while also being very open-ended and extensible. Change-Id: I98b75c0c09eab5355fc7a33ba41dd9874274f12a
* Fix various source comment/doc typosluz paz2021-12-291-1/+1
| | | | | | | | | | | | | | | | | | | ### 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
View Lorry Controller Status