Replace Requests http client by Niquests and add built-in async support

.github/workflows/ci.yml

@@ -3,6 +3,10 @@ jobs:
     name: CI
     secrets: inherit
     uses: praw-dev/.github/.github/workflows/ci.yml@main
+    env:
+      # this avoids pytest loading betamax+Requests at boot.
+      # this allows us to patch betamax and makes it use Niquests instead.
+      PYTEST_DISABLE_PLUGIN_AUTOLOAD: "1"
     with:
       package: prawcore
 name: CI

CHANGES.rst

@@ -6,6 +6,16 @@ prawcore follows `semantic versioning <https://semver.org/>`_.
 Unreleased
 ----------
 
+**Added**
+
+- Asynchronous interfaces from our synchronous ones. Find :class:`AsyncRequestor` for
+  :class:`Requestor` and :class:`AsyncSession` for :class:`Session`.
+
+**Changed**
+
+- Switch HTTP Client Requests for the compatible Niquests. Support for HTTP/2+
+  introduced with mirrored sync / async interfaces.
+
 2.4.0 (2023/10/01)
 ------------------
 

README.rst

@@ -85,6 +85,32 @@ Save the above as ``trophies.py`` and then execute via:
 Additional examples can be found at:
 https://github.com/praw-dev/prawcore/tree/main/examples
 
+Or! with async/await!
+
+.. code-block:: python
+
+    #!/usr/bin/env python
+    import os
+    import pprint
+    import asyncio
+    import prawcore
+
+
+    async def main():
+        authenticator = prawcore.AsyncTrustedAuthenticator(
+            prawcore.Requestor("YOUR_VALID_USER_AGENT"),
+            os.environ["PRAWCORE_CLIENT_ID"],
+            os.environ["PRAWCORE_CLIENT_SECRET"],
+        )
+        authorizer = prawcore.AsyncReadOnlyAuthorizer(authenticator)
+        await authorizer.refresh()
+
+        async with prawcore.async_session(authorizer) as session:
+            pprint.pprint(await session.request("GET", "/api/v1/user/bboe/trophies"))
+
+
+    asyncio.run(main())
+
 Depending on prawcore
 ---------------------
 

examples/caching_requestor.py

@@ -10,12 +10,12 @@
 import os
 import sys
 
-import requests
+import niquests
 
 import prawcore
 
 
-class CachingSession(requests.Session):
+class CachingSession(niquests.Session):
     """Cache GETs in memory.
 
     Toy example of custom session to showcase the ``session`` parameter of

prawcore/__init__.py

@@ -2,6 +2,17 @@
 
 import logging
 
+from ._async.auth import (
+    AsyncAuthorizer,
+    AsyncDeviceIDAuthorizer,
+    AsyncImplicitAuthorizer,
+    AsyncReadOnlyAuthorizer,
+    AsyncScriptAuthorizer,
+    AsyncTrustedAuthenticator,
+    AsyncUntrustedAuthenticator,
+)
+from ._async.requestor import AsyncRequestor
+from ._async.sessions import AsyncSession, async_session
 from .auth import (
     Authorizer,
     DeviceIDAuthorizer,

prawcore/_async/__init__.py

@@ -0,0 +1,2 @@
+# this part should be autogenerated
+# mirror of our synchronous part.