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
(cherry picked from commit f7ebfa6072d65c32c61194b265662c957d3f09dd)

diff --git a/doc/build/faq/index.rst b/doc/build/faq/index.rst
index 810a040115727eb618354a134934629820941a02..4b2397d5b8d645caba217fe5b2cf25b3e0d615b0 100644 (file)
--- 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 (file)
index 0000000..500198d
--- /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 679d8f0564bf4bba08e0672186c67f894c05ed3b..8516ad851adffb0e965f10f2019abc42fd46e4b7 100644 (file)
--- 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
 ---------------