2.1 setup / initial dependency/min version change

this includes setup.cfg changes for asyncio and
3.8 min support.  it doesnt have any code changes in support
of these adjusments.

Fixes: #10197
Fixes: #10357

Change-Id: Ic4569c770d1b893a067a9a5dfe13a6e28aaf47fa

Author: zzzeek

doc/build/changelog/changelog_21.rst

@@ -0,0 +1,13 @@
+=============
+2.1 Changelog
+=============
+
+.. changelog_imports::
+
+    .. include:: changelog_20.rst
+        :start-line: 5
+
+
+.. changelog::
+    :version: 2.1.0b1
+    :include_notes_from: unreleased_21

doc/build/changelog/index.rst

@@ -17,15 +17,15 @@ capabilities and behaviors in SQLAlchemy 2.0.
 .. toctree::
    :titlesonly:
 
-   migration_20
-   whatsnew_20
+   migration_21
 
 Change logs
 -----------
 
 .. toctree::
    :titlesonly:
 
+   changelog_21
    changelog_20
    changelog_14
    changelog_13
@@ -49,6 +49,8 @@ Older Migration Guides
 .. toctree::
    :titlesonly:
 
+   migration_20
+   whatsnew_20
    migration_14
    migration_13
    migration_12

doc/build/changelog/migration_21.rst

@@ -0,0 +1,36 @@
+.. _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`
+

doc/build/changelog/unreleased_21/10197.rst

@@ -0,0 +1,14 @@
+.. 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`
+
+

doc/build/changelog/unreleased_21/10357.rst

@@ -0,0 +1,6 @@
+.. 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.

doc/build/changelog/unreleased_21/README.txt

@@ -0,0 +1,12 @@
+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.
+

doc/build/conf.py

@@ -240,11 +240,11 @@
 # 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"

doc/build/index.rst

@@ -52,11 +52,20 @@ SQLAlchemy Documentation
 
   .. 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
 
 

doc/build/intro.rst

@@ -55,7 +55,7 @@ Documentation Overview
 
 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
@@ -94,23 +94,14 @@ Installation Guide
 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
 -------------------------------
@@ -129,7 +120,7 @@ downloaded from PyPI and installed in one step:
 
 .. 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
@@ -141,11 +132,30 @@ pip requires that the ``--pre`` flag be used:
 
 .. 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
 -------------------------------------------------
@@ -238,13 +248,13 @@ the available DBAPIs for each database, including external links.
 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
 ----------
@@ -254,7 +264,21 @@ With SQLAlchemy installed, new and old users alike can
 
 .. _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

doc/build/orm/extensions/asyncio.rst

@@ -9,7 +9,7 @@ included, using asyncio-compatible dialects.
 .. 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::
 
@@ -20,25 +20,14 @@ included, using asyncio-compatible dialects.
 
 .. _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``:
@@ -51,6 +40,9 @@ Note that installation of ``greenlet`` on platforms that do not have a pre-built
 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
 ---------------