From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 8 Apr 2022 13:28:47 +0000 (-0400)
Subject: explicitly refer to Apple M1 for greenlet issue
X-Git-Tag: rel_2_0_0b1~369
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f7ebfa6072d65c32c61194b265662c957d3f09dd;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

explicitly refer to Apple M1 for greenlet issue

As developers are now buying lots of Apple M1
machines, and AFAWK greenlet is still not able
to provide a pre-built wheel, we are going to get a lot
of devs trying to use asyncio on their Apple M1s, in
greater proportions compared to devs running containers
etc. on other various less popular CPU architectures.

Add a new FAQ section for installation, add new
red dragon to the very top of asyncio docs,
add new verbiage, all of which includes
"Apple M1" in bold text, to minimize the chance of anyone
missing this.

Fixes: #7922
Fixes: #7714
Change-Id: I106923a2860a4efd77d1b999197be102afc1f73d
---

diff --git a/doc/build/faq/index.rst b/doc/build/faq/index.rst
index 810a040115..4b2397d5b8 100644
--- a/doc/build/faq/index.rst
+++ b/doc/build/faq/index.rst
@@ -10,6 +10,7 @@ observed questions to well-known issues.
 .. toctree::
     :maxdepth: 2
 
+    installation
     connections
     metadata_schema
     sqlexpressions
diff --git a/doc/build/faq/installation.rst b/doc/build/faq/installation.rst
new file mode 100644
index 0000000000..500198df8a
--- /dev/null
+++ b/doc/build/faq/installation.rst
@@ -0,0 +1,29 @@
+Installation
+=================
+
+.. contents::
+    :local:
+    :class: faq
+    :backlinks: none
+
+.. _faq_asyncio_installation:
+
+I'm getting an error about greenlet not being installed when I try to use asyncio
+----------------------------------------------------------------------------------
+
+The ``greenlet`` dependency does not install by default for CPU architectures
+for which ``greenlet`` does not supply a `pre-built binary wheel <https://pypi.org/project/greenlet/#files>`_.
+Notably, **this includes Apple M1**.    To install including ``greenlet``,
+add the ``asyncio`` `setuptools extra <https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-setuptools-extras>`_
+to the ``pip install`` command::
+
+    pip install sqlalchemy[asyncio]
+
+For more background, see :ref:`asyncio_install`.
+
+
+.. seealso::
+
+    :ref:`asyncio_install`
+
+
diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst
index 5d552b419b..9badcb4184 100644
--- a/doc/build/orm/extensions/asyncio.rst
+++ b/doc/build/orm/extensions/asyncio.rst
@@ -8,7 +8,10 @@ included, using asyncio-compatible dialects.
 
 .. versionadded:: 1.4
 
-.. note:: The asyncio extension as of SQLAlchemy 1.4.3 can now be considered to
+.. warning:: Please read :ref:`asyncio_install` for important platform
+   installation notes for many platforms, including **Apple M1 Architecture**.
+
+.. tip:: The asyncio extension as of SQLAlchemy 1.4.3 can now be considered to
    be **beta level** software. API details are subject to change however at this
    point it is unlikely for there to be significant backwards-incompatible
    changes.
@@ -22,22 +25,33 @@ included, using asyncio-compatible dialects.
 
 .. _asyncio_install:
 
-Asyncio Platform Installation Notes
-------------------------------------
+Asyncio Platform Installation Notes (Including Apple M1)
+---------------------------------------------------------
 
-The asyncio extension requires at least Python version 3.6. It also depends
+The asyncio extension requires Python 3 only. It also depends
 upon the `greenlet <https://pypi.org/project/greenlet/>`_ library. This
 dependency is installed by default on common machine platforms including::
 
     x86_64 aarch64 ppc64le amd64 win32
 
 For the above platforms, ``greenlet`` is known to supply pre-built wheel files.
-To ensure the ``greenlet`` dependency is present on other platforms, the
-``[asyncio]`` extra may be installed as follows, which will include an attempt
-to build and install ``greenlet``::
+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
+``[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``::
 
   pip install sqlalchemy[asyncio]
 
+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.
+
 
 Synopsis - Core
 ---------------