--- /dev/null
+=============
+2.1 Changelog
+=============
+
+.. changelog_imports::
+
+ .. include:: changelog_20.rst
+ :start-line: 5
+
+
+.. changelog::
+ :version: 2.1.0b1
+ :include_notes_from: unreleased_21
.. toctree::
:titlesonly:
- migration_20
- whatsnew_20
+ migration_21
Change logs
-----------
.. toctree::
:titlesonly:
+ changelog_21
changelog_20
changelog_14
changelog_13
.. toctree::
:titlesonly:
+ migration_20
+ whatsnew_20
migration_14
migration_13
migration_12
--- /dev/null
+.. _whatsnew_21_toplevel:
+
+=============================
+What's New in SQLAlchemy 2.1?
+=============================
+
+.. admonition:: About this Document
+
+ This document describes changes between SQLAlchemy version 2.0 and
+ version 2.1.
+
+
+.. _change_10197:
+
+Asyncio "greenlet" dependency no longer installs by default
+------------------------------------------------------------
+
+SQLAlchemy 1.4 and 2.0 used a complex expression to determine if the
+``greenlet`` dependency, needed by the :ref:`asyncio <asyncio_toplevel>`
+extension, could be installed from pypi using a pre-built wheel instead
+of having to build from source. This because the source build of ``greenlet``
+is not always trivial on some platforms.
+
+Disadantages to this approach included that SQLAlchemy needed to track
+exactly which versions of ``greenlet`` were published as wheels on pypi;
+the setup expression led to problems with some package management tools
+such as ``poetry``; it was not possible to install SQLAlchemy **without**
+``greenlet`` being installed, even though this is completely feasible
+if the asyncio extension is not used.
+
+These problems are all solved by keeping ``greenlet`` entirely within the
+``[asyncio]`` target. The only downside is that users of the asyncio extension
+need to be aware of this extra installation dependency.
+
+:ticket:`10197`
+
--- /dev/null
+.. change::
+ :tags: change, installation
+ :tickets: 10197
+
+ The ``greenlet`` dependency used for asyncio support no longer installs
+ by default. This dependency does not publish wheel files for every architecture
+ and is not needed for applications that aren't using asyncio features.
+ Use the ``sqlalchemy[asyncio]`` install target to include this dependency.
+
+ .. seealso::
+
+ :ref:`change_10197`
+
+
--- /dev/null
+.. change::
+ :tags: change, installation
+ :tickets: 10357
+
+ Python 3.8 or above is now required; support for Python 3.7 is dropped as
+ this version is EOL.
--- /dev/null
+Individual per-changelog files go here
+in .rst format, which are pulled in by
+changelog (version 0.4.0 or higher) to
+be rendered into the changelog_xx.rst file.
+At release time, the files here are removed and written
+directly into the changelog.
+
+Rationale is so that multiple changes being merged
+into gerrit don't produce conflicts. Note that
+gerrit does not support custom merge handlers unlike
+git itself.
+
# built documents.
#
# The short X.Y version.
-version = "2.0"
+version = "2.1"
# The full version, including alpha/beta/rc tags.
-release = "2.0.23"
+release = "2.1.0b1"
-release_date = "November 2, 2023"
+release_date = None
site_base = os.environ.get("RTD_SITE_BASE", "https://www.sqlalchemy.org")
site_adapter_template = "docs_adapter.mako"
.. container::
- Users coming from older versions of SQLAlchemy, especially those transitioning
- from the 1.x style of working, will want to review this documentation.
+ Users coming SQLAlchemy version 2.0 will want to read:
+
+ * :doc:`What's New in SQLAlchemy 2.1? <changelog/migration_21>` - New features and behaviors in version 2.1
+
+ Users transitioning from 1.x versions of SQLAlchemy, such as version 1.4, will want to
+ transition to version 2.0 overall before making any additional changes needed for
+ the much smaller transition from 2.0 to 2.1. Key documentation for the 1.x to 2.x
+ transition:
* :doc:`Migrating to SQLAlchemy 2.0 <changelog/migration_20>` - Complete background on migrating from 1.3 or 1.4 to 2.0
* :doc:`What's New in SQLAlchemy 2.0? <changelog/whatsnew_20>` - New 2.0 features and behaviors beyond the 1.x migration
+
+ An index of all changelogs and migration documentation is at:
+
* :doc:`Changelog catalog <changelog/index>` - Detailed changelogs for all SQLAlchemy Versions
The documentation is separated into four sections:
-* :ref:`unified_tutorial` - this all-new tutorial for the 1.4/2.0 series of
+* :ref:`unified_tutorial` - this all-new tutorial for the 1.4/2.0/2.1 series of
SQLAlchemy introduces the entire library holistically, starting from a
description of Core and working more and more towards ORM-specific concepts.
New users, as well as users coming from the 1.x series of
Supported Platforms
-------------------
-SQLAlchemy supports the following platforms:
+SQLAlchemy 2.1 supports the following platforms:
-* cPython 3.7 and higher
+* cPython 3.8 and higher
* Python-3 compatible versions of `PyPy <http://pypy.org/>`_
-.. versionchanged:: 2.0
- SQLAlchemy now targets Python 3.7 and above.
+.. versionchanged:: 2.1
+ SQLAlchemy now targets Python 3.8 and above.
-AsyncIO Support
-----------------
-
-SQLAlchemy's ``asyncio`` support depends upon the
-`greenlet <https://pypi.org/project/greenlet/>`_ project. This dependency
-will be installed by default on common machine platforms, however is not
-supported on every architecture and also may not install by default on
-less common architectures. See the section :ref:`asyncio_install` for
-additional details on ensuring asyncio support is present.
Supported Installation Methods
-------------------------------
.. sourcecode:: text
- pip install SQLAlchemy
+ pip install sqlalchemy
This command will download the latest **released** version of SQLAlchemy from
the `Python Cheese Shop <https://pypi.org/project/SQLAlchemy>`_ and install it
.. sourcecode:: text
- pip install --pre SQLAlchemy
+ pip install --pre sqlalchemy
Where above, if the most recent version is a prerelease, it will be installed
instead of the latest released version.
+Installing with AsyncIO Support
+-------------------------------
+
+SQLAlchemy's ``asyncio`` support depends upon the
+`greenlet <https://pypi.org/project/greenlet/>`_ project. This dependency
+is not inclued by default. To install with asyncio support, run this command:
+
+.. sourcecode:: text
+
+ pip install sqlalchemy[asyncio]
+
+This installation will include the greenlet dependency in the installation.
+See the section :ref:`asyncio_install` for
+additional details on ensuring asyncio support is present.
+
+.. versionchanged:: 2.1 SQLAlchemy no longer installs the "greenlet"
+ dependency by default; use the ``sqlalchemy[asyncio]`` pip target to
+ install.
+
Installing manually from the source distribution
-------------------------------------------------
Checking the Installed SQLAlchemy Version
------------------------------------------
-This documentation covers SQLAlchemy version 2.0. If you're working on a
+This documentation covers SQLAlchemy version 2.1. If you're working on a
system that already has SQLAlchemy installed, check the version from your
Python prompt like this::
>>> import sqlalchemy
>>> sqlalchemy.__version__ # doctest: +SKIP
- 2.0.0
+ 2.1.0
Next Steps
----------
.. _migration:
-1.x to 2.0 Migration
+2.0 to 2.1 Migration
=====================
-Notes on the new API released in SQLAlchemy 2.0 is available here at :doc:`changelog/migration_20`.
+Users coming SQLAlchemy version 2.0 will want to read:
+
+* :doc:`What's New in SQLAlchemy 2.1? <changelog/migration_21>` - New features and behaviors in version 2.1
+
+Users transitioning from 1.x versions of SQLAlchemy, such as version 1.4, will want to
+transition to version 2.0 overall before making any additional changes needed for
+the much smaller transition from 2.0 to 2.1. Key documentation for the 1.x to 2.x
+transition:
+
+* :doc:`Migrating to SQLAlchemy 2.0 <changelog/migration_20>` - Complete background on migrating from 1.3 or 1.4 to 2.0
+* :doc:`What's New in SQLAlchemy 2.0? <changelog/whatsnew_20>` - New 2.0 features and behaviors beyond the 1.x migration
+
+An index of all changelogs and migration documentation is at:
+
+* :doc:`Changelog catalog <changelog/index>` - Detailed changelogs for all SQLAlchemy Versions
.. versionadded:: 1.4
.. warning:: Please read :ref:`asyncio_install` for important platform
- installation notes for many platforms, including **Apple M1 Architecture**.
+ installation notes on **all** platforms.
.. seealso::
.. _asyncio_install:
-Asyncio Platform Installation Notes (Including Apple M1)
----------------------------------------------------------
+Asyncio Platform Installation Notes
+-----------------------------------
-The asyncio extension requires Python 3 only. It also depends
+The asyncio extension depends
upon the `greenlet <https://pypi.org/project/greenlet/>`_ library. This
-dependency is installed by default on common machine platforms including:
+dependency is **not installed by default**.
-.. sourcecode:: text
-
- x86_64 aarch64 ppc64le amd64 win32
-
-For the above platforms, ``greenlet`` is known to supply pre-built wheel files.
-For other platforms, **greenlet does not install by default**;
-the current file listing for greenlet can be seen at
-`Greenlet - Download Files <https://pypi.org/project/greenlet/#files>`_.
-Note that **there are many architectures omitted, including Apple M1**.
-
-To install SQLAlchemy while ensuring the ``greenlet`` dependency is present
-regardless of what platform is in use, the
+To install SQLAlchemy while ensuring the ``greenlet`` dependency is present, the
``[asyncio]`` `setuptools extra <https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-setuptools-extras>`_
may be installed
as follows, which will include also instruct ``pip`` to install ``greenlet``:
wheel file means that ``greenlet`` will be built from source, which requires
that Python's development libraries also be present.
+.. versionchanged:: 2.1 ``greenlet`` is no longer installed by default; to
+ use the asyncio extension, the ``sqlalchemy[asyncio]`` target must be used.
+
Synopsis - Core
---------------
their own Python interpreter.
If running the examples, it is advised that the reader performs a quick check to
-verify that we are on **version 2.0** of SQLAlchemy:
+verify that we are on **version 2.1** of SQLAlchemy:
.. sourcecode:: pycon+sql
>>> import sqlalchemy
>>> sqlalchemy.__version__ # doctest: +SKIP
- 2.0.0
+ 2.1.0
from .types import VARBINARY as VARBINARY
from .types import VARCHAR as VARCHAR
-__version__ = "2.0.24"
+__version__ = "2.1.0b1"
def __go(lcls: Any) -> None:
Operating System :: OS Independent
Programming Language :: Python
Programming Language :: Python :: 3
- Programming Language :: Python :: 3.7
Programming Language :: Python :: 3.8
Programming Language :: Python :: 3.9
Programming Language :: Python :: 3.10
[options]
packages = find:
include_package_data = True
-python_requires = >=3.7
+python_requires = >=3.8
package_dir =
=lib
install_requires =
- importlib-metadata;python_version<"3.8"
- greenlet != 0.4.17;(platform_machine=='aarch64' or (platform_machine=='ppc64le' or (platform_machine=='x86_64' or (platform_machine=='amd64' or (platform_machine=='AMD64' or (platform_machine=='win32' or platform_machine=='WIN32'))))))
typing-extensions >= 4.2.0
[options.extras_require]
cov: True
extras=
+ asyncio
sqlite: aiosqlite
sqlite_file: aiosqlite
sqlite_file: sqlcipher; python_version < '3.10'
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
