Permalink
Browse files

Fix documentation for v0.6.0

  • Loading branch information...
prkumar committed Sep 10, 2018
1 parent 567a937 commit 3c6aded416e6fb4868258ca6606fcbe59ac17c5c
Showing with 53 additions and 20 deletions.
  1. +2 −2 README.rst
  2. +37 −4 docs/source/user/clients.rst
  3. +14 −14 docs/source/user/serialization.rst
View
@@ -86,9 +86,9 @@ Uplink officially supports Python 2.7 & 3.3-3.7.
.. |marshmallow| replace:: ``marshmallow``
.. |requests-oauthlib| replace:: ``requests-oauthlib``
.. _`Non-blocking I/O support`: https://github.com/prkumar/uplink/tree/master/examples/async-requests
.. _`Supply your own session`: https://uplink.readthedocs.io/en/latest/user/clients.html#swapping-out-the-default-http-client
.. _`Supply your own session`: https://uplink.readthedocs.io/en/latest/user/clients.html#swapping-out-the-default-http-session
.. _`marshmallow`: https://github.com/prkumar/uplink/tree/master/examples/marshmallow
.. _`custom converters`: https://uplink.readthedocs.io/en/latest/user/serialization.html#custom-serialization
.. _`custom converters`: https://uplink.readthedocs.io/en/latest/user/serialization.html#custom-json-deserialization
.. _`handling collections`: https://uplink.readthedocs.io/en/latest/user/serialization.html#converting-collections
.. _`custom response and error handling`: https://uplink.readthedocs.io/en/latest/user/quickstart.html#response-and-error-handling
.. _`protobuf support`: https://github.com/prkumar/uplink-protobuf
@@ -1,14 +1,27 @@
Clients
*******
To use a common English metaphor: Uplink stands on the shoulders of giants.
Uplink doesn't implement any code to handle HTTP protocol stuff
directly; for that, the library delegates to an actual HTTP client, such
as Requests or Aiohttp. Whatever backing client you choose, when a
request method on a :class:`Consumer` subclass is invoked, Uplink
ultimately interacts with the backing library's interface, at minimum to
submit requests and read responses.
This section covers the interaction between Uplink and the backing HTTP
client library of your choosing, including how to specify your
selection.
.. _swap_default_http_client:
Swapping Out the Default HTTP Client
====================================
Swapping Out the Default HTTP Session
=====================================
By default, Uplink sends requests using the Requests library. You can
configure the backing HTTP client using the :obj:`client` parameter of the
:py:class:`~uplink.Consumer` constructor:
configure the backing HTTP client object using the :obj:`client`
parameter of the :py:class:`~uplink.Consumer` constructor:
.. code-block:: python
@@ -25,6 +38,26 @@ object:
session.verify = False
github = GitHub(BASE_URL, client=session)
This also go for session objects from other HTTP client libraries that
Uplink supports, such as :mod:`aiohttp` (i.e., a custom
:class:`~aiohttp.ClientSession` works here, as well).
Following the above example, the :obj:`client` parameter also accepts an
instance of any :class:`requests.Session` subclass. This makes it easy
to leverage functionality from third-party Requests extensions, such as
`requests-oauthlib`_, with minimal integration overhead:
.. code-block:: python
from requests_oauthlib import OAuth2Session
session = OAuth2Session(...)
api = MyApi(BASE_URL, client=session)
.. |requests-oauthlib| replace:: ``requests-oauthlib``
.. _`requests-oauthlib`: https://github.com/requests/requests-oauthlib
.. _sync_vs_async:
Synchronous vs. Asynchronous
@@ -151,16 +151,16 @@ Converting Collections
======================
Data-driven web applications, such as social networks and forums, devise
a lot of functionality around large queries on related data. And, these
APIs normally encode the results of these queries as collections of a
common **type**. Examples include a curated feed of **posts** from
subscribed accounts, the top **restaurants** in your area, upcoming
**tasks** on a checklist, etc.
a lot of functionality around large queries on related data. Their APIs
normally encode the results of these queries as collections of a common
**type**. Examples include a curated feed of **posts** from subscribed
accounts, the top **restaurants** in your area, upcoming *tasks** on a
checklist, etc.
You can use the other strategies in this section to add serialization
support for a specific type, such as a **post** or a **restaurant**.
Importantly, once added, this support automatically extends to
collections of that type, such as sequences and mappings.
Once added, this support automatically extends to collections of that
type, such as sequences and mappings.
For example, consider a hypothetical Task Management API that supports
adding tasks to one or more user-created checklists. Here's the JSON
@@ -195,11 +195,11 @@ register a custom converter with :meth:`loads.from_json
:ref:`custom_json_deserialization`. For the sake of brevity, I'll omit the
implementation here, but you can follow the link above for details.
Now, Uplink lets us leverage the added support to handle collections of
type :class:`Task`. The :mod:`uplink.types` module exposes two
collection types, :data:`~uplink.List` and :data:`~uplink.types.Dict`,
to be used as function return type annotations. In our example, the
query for pending tasks returns a list:
Notably, Uplink lets us leverage the added support to also handle
collections of type :class:`Task`. The :mod:`uplink.types` module
exposes two collection types, :data:`~uplink.List` and
:data:`~uplink.types.Dict`, to be used as function return type
annotations. In our example, the query for pending tasks returns a list:
.. code-block:: python
:emphasize-lines: 6
@@ -263,11 +263,11 @@ could look like:
"""Adapter for Python's Pickle protocol."""
def create_response_body_converter(self, cls, request_definition):
# Return callable that deserialize response body into Python object.
# Return callable to deserialize response body into Python object.
return lambda response: pickle.loads(response.content)
def create_request_body_converter(self, cls, request_definition):
# Return callable that serialize Python object into bytes.
# Return callable to serialize Python object into bytes.
return pickle.dumps
Then, when instantiating a new consumer, you can supply this

0 comments on commit 3c6aded

Please sign in to comment.