it seems to have gotten lost in our newer docs that we're looking
at the first dict only for core insert. add sections to both
INSERT tutorials explaining this difference
references: #12962
Change-Id: Id2e6c7e7db57fba6aa7838d5c3c65dea1939445a
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
* 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
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
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
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
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
### 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: 0deac22193
Change-Id: Icd61db31c8dc655d4a39d8a304194804d08555fe
(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
This breaks data.rst into three separate sub-sections,
as SELECT is getting very long. It then adds sections
on select() + text/literal_column as well as unions
and set operations, and also tries to improve the
ORDER BY section a bit.
Change-Id: Id90e6b4ff3699b2bbcb6e2eebbd23193e2ede00a
Mike Bayer