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

.pre-commit-config.yaml

@@ -1,4 +1,17 @@
 repos:
+  - repo: local
+    hooks:
+      - id: async-generator
+        name: check async code
+        entry: python tools/generate_async.py -a --fix
+        language: python
+        types: [ python ]
+        pass_filenames: false
+        additional_dependencies:
+          - "ruff==0.7.4"
+          - "black==24.10.0"
+          - "docstrfmt==1.9.0"
+          - "niquests>=3.10,<4"
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
@@ -24,7 +37,7 @@ repos:
         files: ^(.*\.toml)$
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.9
+    rev: v0.7.4
     hooks:
       - id: ruff
         args: [ --exit-non-zero-on-fix, --fix ]

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,18 @@
 
 import logging
 
+from ._async.auth import (
+    AsyncAuthorizer,
+    AsyncDeviceIDAuthorizer,
+    AsyncImplicitAuthorizer,
+    AsyncReadOnlyAuthorizer,
+    AsyncScriptAuthorizer,
+    AsyncTrustedAuthenticator,
+    AsyncUntrustedAuthenticator,
+)
+from ._async.requestor import AsyncRequestor
+from ._async.sessions import AsyncSession
+from ._async.sessions import session as 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.