Patch docs (#211)

docs/api.rst

@@ -47,6 +47,8 @@ Request Sessions
 .. autoclass:: Session
    :inherited-members:
 
+.. autoclass:: AsyncSession
+   :inherited-members:
 
 Lower-Level Classes
 -------------------
@@ -57,6 +59,10 @@ Lower-Level Classes
 .. autoclass:: Response
    :inherited-members:
 
+.. autoclass:: AsyncResponse
+   :inherited-members:
+
+.. warning:: AsyncResponse are only to be expected in async mode when you specify ``stream=True``. Otherwise expect the typical Response instance.
 
 Lower-Lower-Level Classes
 -------------------------
@@ -70,6 +76,12 @@ Lower-Lower-Level Classes
 .. autoclass:: niquests.adapters.HTTPAdapter
    :inherited-members:
 
+.. autoclass:: niquests.adapters.AsyncBaseAdapter
+   :inherited-members:
+
+.. autoclass:: niquests.adapters.AsyncHTTPAdapter
+   :inherited-members:
+
 Authentication
 --------------
 
@@ -78,6 +90,8 @@ Authentication
 .. autoclass:: niquests.auth.HTTPProxyAuth
 .. autoclass:: niquests.auth.HTTPDigestAuth
 
+.. autoclass:: niquests.auth.AsyncAuthBase
+
 .. _api-cookies:
 
 Cookies
@@ -117,7 +131,6 @@ Removed
 * Property ``apparent_encoding`` in favor of a discrete internal inference.
 * Support for the legacy ``chardet`` detector in case it was present in environment.
   Extra ``chardet_on_py3`` is now unavailable.
-* **requests.compat** no longer hold reference to _chardet_.
 * Deprecated ``requests.packages`` that was meant to avoid breakage from people importing ``urllib3`` or ``chardet`` within this package.
   They were _vendored_ in early versions of Requests. A long time ago.
 * Deprecated function ``get_encodings_from_content`` from utils.

docs/community/extensions.rst

@@ -141,7 +141,19 @@ requests-mock
 
 You will need to create a fixture to override the default bind to Requests in ``conftest.py`` like so::
 
-    import niquests as requests
+    from sys import modules
+
+    import requests
+    import niquests
+    import urllib3
+
+    # impersonate Requests!
+    modules["requests"] = niquests
+    modules["requests.adapters"] = niquests.adapters
+    modules["requests.models"] = niquests.models
+    modules["requests.exceptions"] = niquests.exceptions
+    modules["requests.packages.urllib3"] = urllib3
+    modules["requests.compat"] = requests.compat
 
     @pytest.fixture(scope='function')
     def patched_requests_mock():
@@ -154,7 +166,7 @@ You will need to create a fixture to override the default bind to Requests in ``
 
             def __init__(self, session=None, **kwargs):
                 # we purposely skip invoking super() to avoid the strict typecheck on session.
-                self._mock_target = session or requests.Session
+                self._mock_target = session or niquests.Session
                 self.case_sensitive = kwargs.pop('case_sensitive', self.case_sensitive)
                 self._adapter = (
                     kwargs.pop('adapter', None)
@@ -183,6 +195,11 @@ Then, use it as you were used to::
     def test_sometime(patched_requests_mock):
         patched_requests_mock.get("https://example.com/", text="hello world")
 
+.. warning:: This extension load/import Requests at pytest startup.
+    Disable the plugin auto-loading first by either passing ``PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`` (in environment)
+    or ``pytest -p "no:requests_mock"`` in CLI parameters. You may also append ``-p "no:requests_mock"`` in addopts
+    of your pyproject.toml or equivalent.
+
 requests-ntlm
 -------------
 

docs/community/faq.rst

@@ -62,6 +62,10 @@ Do as follow::
         ...
 
 
+.. note:: Previously Requests and urllib3 was non-strict and allowed infinite growth of the pool by default. This was undesirable.
+    Upon exceeding the maximum pool capacity, urllib3 starts to create "disposable" connections that are killed as soon as possible.
+    This behavior masked an issue and users were misinformed about it.
+
 What is "urllib3.future"?
 -------------------------
 
@@ -97,8 +101,8 @@ It does not change anything for you. You may still pass ``urllib3.Retry`` and
 ``urllib3.Timeout`` regardless of the cohabitation, Niquests will do
 the translation internally.
 
-What are my headers are lowercased?
------------------------------------
+Why are my headers are lowercased?
+----------------------------------
 
 This may come as a surprise for some of you. Until Requests-era, header keys could arrive
 as they were originally sent (case-sensitive). This is possible thanks to HTTP/1.1 protocol.
@@ -128,7 +132,7 @@ A shortcut would be::
 
     $ pip uninstall qh3
 
-.. warning:: Your site-packages is shared, thus it is possible that other libraries depends on some of the listed programs. Do it with care!
+.. warning:: Your site-packages is shared, do it only if you are sure nothing else is using it.
 
 What are "pem lib" errors?
 --------------------------
@@ -150,7 +154,7 @@ If none of those seems related to your situation, feel free to open an issue at
 Why HTTP/2 and HTTP/3 seems slower than HTTP/1.1?
 -------------------------------------------------
 
-Because you are not leveraging its potential properly. Most of the time, developers tends to
+Because you are not leveraging its potential properly. Most of the time, developers tend to
 make a request and immediately consume the response afterward. Let's call that making OneToOne requests.
 HTTP/2, and HTTP/3 both requires more computational power for a single request than HTTP/1.1 (in OneToOne context).
 The true reason for them to exist, is not the OneToOne scenario.
@@ -194,6 +198,6 @@ This example will quickly demonstrate, how to utilize and leverage your HTTP/2 c
     print("> With multiplexing:")
     make_requests(REQUEST_URL, REQUEST_COUNT, True)
 
-.. note:: This piece of code showcase how to emit concurrent requests in a synchronous context without threads and async.
+.. note:: This piece of code demonstrate how to emit concurrent requests in a synchronous context without threads and async.
 
 We would gladly discuss potential implementations if needed, just open a new issue at https://github.com/jawah/niquests/issues

docs/community/updates.rst

@@ -15,4 +15,4 @@ The best way to track the development of Niquests is through
 `the GitHub repo <https://github.com/jawah/niquests>`_.
 
 
-.. include:: ../../HISTORY.md
+.. mdinclude:: ../../HISTORY.md

docs/conf.py

@@ -40,7 +40,9 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "sphinxcontrib.gtagjs",
     "sphinx_copybutton",
+    "sphinx_mdinclude",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -136,6 +138,10 @@
     },
 }
 
+gtagjs_ids = [
+    'G-F8C2DJ1CJN',
+]
+
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
 

docs/dev/migrate.rst

@@ -17,25 +17,26 @@ Developer migration
 Niquests aims to be as compatible as possible with Requests, and that is
 with confidence that you can migrate to Niquests without breaking changes.
 
-::
+.. code:: python
 
     import requests
     requests.get(...)
 
 Would turn into either
 
-::
+.. code:: python
 
     import niquests
     niquests.get(...)
 
 Or simply
 
-::
+.. code:: python
 
     import niquests as requests
     requests.get(...)
 
+.. tip:: If you were used to use ``urllib3.Timeout`` or ``urllib3.Retry`` you can either keep them as-is or use our fully compatible ``niquests.RetryConfiguration`` or ``niquests.TimeoutConfiguration`` instead.
 
 Maintainer migration
 --------------------
@@ -51,7 +52,7 @@ To overcome this, we will introduce you to a clever bypass. If you are using pyt
 following in your ``conftest.py``, see https://docs.pytest.org/en/6.2.x/fixture.html#conftest-py-sharing-fixtures-across-multiple-files
 for more information. (The goal would simply to execute the following piece of code before the tests)
 
-::
+.. code:: python
 
     from sys import modules
 

docs/requirements.txt

@@ -6,3 +6,5 @@ urllib3.future>=2.12.900
 wassima>=1,<2
 kiss_headers>=2,<4
 furo>=2023.9.10
+sphinx-mdinclude==0.6.2
+sphinxcontrib-gtagjs==0.2.1

docs/user/advanced.rst

@@ -1302,6 +1302,8 @@ Verify the availability by running ``python -m niquests.help``.
 
 .. note:: Access property ``ocsp_verified`` in both ``PreparedRequest``, and ``Response`` to have information about this post handshake verification.
 
+.. warning:: You may be interested in caching and restoring the OCSP validator state in between runs for performance concerns. To achieve that you are invited to pickle and restore your ``niquests.Session`` object.
+
 Specify HTTP/3 capable endpoint preemptively
 --------------------------------------------
 

docs/user/authentication.rst

@@ -161,6 +161,8 @@ authentication will additionally add hooks to provide further functionality.
 Further examples can be found under the `Requests organization`_ and in the
 ``auth.py`` file.
 
+.. tip:: As Niquests support async http requests natively you can create async authentication classes by just inheriting from :class:`AsyncAuthBase <niquests.auth.AsyncAuthBase>`
+
 .. _OAuth: https://oauth.net/
 .. _requests_oauthlib: https://github.com/requests/requests-oauthlib
 .. _requests-oauthlib OAuth2 documentation: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html