From: Federico Caselli Date: Mon, 24 Feb 2025 19:56:38 +0000 (+0100) Subject: various improvements to the docs X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=40b4845f9faa23e45cf6cd390997638a9b0b8fab;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git various improvements to the docs - remove references to the removed mypy plugin - add create table with partition examples in mysql Change-Id: Idc5c35519a0812f1d63be95c14afb9ce2b00ea93 --- diff --git a/doc/build/changelog/changelog_14.rst b/doc/build/changelog/changelog_14.rst index 1c41c586c4..e2d2f4d6c9 100644 --- a/doc/build/changelog/changelog_14.rst +++ b/doc/build/changelog/changelog_14.rst @@ -170,7 +170,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`mypy_toplevel` + mypy_toplevel -- section was removed .. changelog:: :version: 1.4.52 @@ -5683,7 +5683,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`mypy_declarative_mixins` + mypy_declarative_mixins -- section was removed .. change:: @@ -6337,7 +6337,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`mypy_toplevel` + mypy_toplevel -- section was removed .. change:: :tags: bug, sql diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index 523eb63810..70dd6c4119 100644 --- a/doc/build/changelog/migration_20.rst +++ b/doc/build/changelog/migration_20.rst @@ -458,7 +458,7 @@ of the :class:`_orm.Mapped` generic container. Annotations which don't use :class:`_orm.Mapped` which link to constructs such as :func:`_orm.relationship` will raise errors in Python, as they suggest mis-configurations. -SQLAlchemy applications that use the :ref:`Mypy plugin ` with +SQLAlchemy applications that use the Mypy plugin with explicit annotations that don't use :class:`_orm.Mapped` in their annotations are subject to these errors, as would occur in the example below:: diff --git a/doc/build/changelog/whatsnew_20.rst b/doc/build/changelog/whatsnew_20.rst index 5ff98646dd..f7c2b74f03 100644 --- a/doc/build/changelog/whatsnew_20.rst +++ b/doc/build/changelog/whatsnew_20.rst @@ -368,7 +368,7 @@ ORM Declarative Models ~~~~~~~~~~~~~~~~~~~~~~ SQLAlchemy 1.4 introduced the first SQLAlchemy-native ORM typing support -using a combination of sqlalchemy2-stubs_ and the :ref:`Mypy Plugin `. +using a combination of sqlalchemy2-stubs_ and the Mypy Plugin. In SQLAlchemy 2.0, the Mypy plugin **remains available, and has been updated to work with SQLAlchemy 2.0's typing system**. However, it should now be considered **deprecated**, as applications now have a straightforward path to adopting the @@ -729,7 +729,7 @@ and :class:`_engine.Row` objects:: Using Legacy Mypy-Typed Models ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -SQLAlchemy applications that use the :ref:`Mypy plugin ` with +SQLAlchemy applications that use the Mypy plugin with explicit annotations that don't use :class:`_orm.Mapped` in their annotations are subject to errors under the new system, as such annotations are flagged as errors when using constructs such as :func:`_orm.relationship`. diff --git a/doc/build/errors.rst b/doc/build/errors.rst index 237d5d0ab3..e3ba5cce8f 100644 --- a/doc/build/errors.rst +++ b/doc/build/errors.rst @@ -1384,7 +1384,7 @@ annotations within class definitions at runtime. A requirement of this form is that all ORM annotations must make use of a generic container called :class:`_orm.Mapped` to be properly annotated. Legacy SQLAlchemy mappings which include explicit :pep:`484` typing annotations, such as those which use the -:ref:`legacy Mypy extension ` for typing support, may include +legacy Mypy extension for typing support, may include directives such as those for :func:`_orm.relationship` that don't include this generic. diff --git a/doc/build/orm/declarative_tables.rst b/doc/build/orm/declarative_tables.rst index 9619c5b253..bbac1ea101 100644 --- a/doc/build/orm/declarative_tables.rst +++ b/doc/build/orm/declarative_tables.rst @@ -423,7 +423,7 @@ allow mapping database types that can support multiple Python types, such as The above example maps the union of ``list[int]`` and ``list[str]`` to the Postgresql :class:`_postgresql.JSONB` datatype, while naming a union of ``float, -str, bool`` will match to the :class:`.JSON` datatype. An equivalent +str, bool`` will match to the :class:`_types.JSON` datatype. An equivalent union, stated in the :class:`_orm.Mapped` construct, will match into the corresponding entry in the type map. diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py index 96eecc2ba6..b57a1e1343 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -182,6 +182,31 @@ For fully atomic transactions as well as support for foreign key constraints, all participating ``CREATE TABLE`` statements must specify a transactional engine, which in the vast majority of cases is ``InnoDB``. +Partitioning can similarly be specified using similar options. +In the example below the create table will specify ``PARTITION_BY``, +``PARTITIONS``, ``SUBPARTITIONS`` and ``SUBPARTITION_BY``:: + + # can also use mariadb_* prefix + Table( + "testtable", + MetaData(), + Column("id", Integer(), primary_key=True, autoincrement=True), + Column("other_id", Integer(), primary_key=True, autoincrement=False), + mysql_partitions="2", + mysql_partition_by="KEY(other_id)", + mysql_subpartition_by="HASH(some_expr)", + mysql_subpartitions="2", + ) + +This will render: + +.. sourcecode:: sql + + CREATE TABLE testtable ( + id INTEGER NOT NULL AUTO_INCREMENT, + other_id INTEGER NOT NULL, + PRIMARY KEY (id, other_id) + )PARTITION BY KEY(other_id) PARTITIONS 2 SUBPARTITION BY HASH(some_expr) SUBPARTITIONS 2 Case Sensitivity and Table Reflection ------------------------------------- diff --git a/lib/sqlalchemy/orm/decl_api.py b/lib/sqlalchemy/orm/decl_api.py index 97da200ef3..e01ad61362 100644 --- a/lib/sqlalchemy/orm/decl_api.py +++ b/lib/sqlalchemy/orm/decl_api.py @@ -503,7 +503,7 @@ def declarative_mixin(cls: Type[_T]) -> Type[_T]: The :func:`_orm.declarative_mixin` decorator currently does not modify the given class in any way; it's current purpose is strictly to assist - the :ref:`Mypy plugin ` in being able to identify + the Mypy plugin in being able to identify SQLAlchemy declarative mixin classes when no other context is present. .. versionadded:: 1.4.6 @@ -512,9 +512,6 @@ def declarative_mixin(cls: Type[_T]) -> Type[_T]: :ref:`orm_mixins_toplevel` - :ref:`mypy_declarative_mixins` - in the - :ref:`Mypy plugin documentation ` - """ # noqa: E501 return cls