Converters¶
The converter
parameter of the uplink.Consumer
constructor
accepts a custom adapter class that handles serialization of HTTP
request properties and deserialization of HTTP response objects:
github = GitHub(BASE_URL, converter=...)
Starting with version v0.5, some out-of-the-box converters are included
automatically and don’t need to be explicitly provided through the
converter
parameter. These implementations are detailed below.
Marshmallow¶
Uplink comes with optional support for marshmallow
.
-
class
uplink.converters.
MarshmallowConverter
¶ A converter that serializes and deserializes values using
marshmallow
schemas.To deserialize JSON responses into Python objects with this converter, define a
marshmallow.Schema
subclass and set it as the return annotation of a consumer method:@get("/users") def get_users(self, username) -> UserSchema(): '''Fetch a single user'''
Note
This converter is an optional feature and requires the
marshmallow
package. For example, here’s how to install this feature using pip:$ pip install uplink[marshmallow]
Note
Starting with version v0.5, this converter factory is automatically
included if you have marshmallow
installed, so you don’t need
to provide it when constructing your consumer instances.
Converting Collections¶
New in version v0.5.0.
Uplink can convert collections of a type, such as deserializing a
response body into a list of users. If you have typing
installed (the module is part of the standard library starting Python
3.5), you can use type hints (see PEP 484) to specify such
conversions. You can also leverage this feature without typing
by using one of the proxy types defined in uplink.types
.
The following converter factory implements this feature and is automatically included, so you don’t need to provide it when constructing your consumer instance:
-
class
uplink.converters.
TypingConverter
¶ An adapter that serializes and deserializes collection types from the
typing
module, such astyping.List
.Inner types of a collection are recursively resolved, using other available converters if necessary. For instance, when resolving the type hint
typing.Sequence[UserSchema]
, whereUserSchema
is a custommarshmallow.Schema
subclass, the converter will resolve the inner type usinguplink.converters.MarshmallowConverter
.@get("/users") def get_users(self) -> typing.Sequence[UserSchema]: '''Fetch all users.'''
Note
The
typing
module is available in the standard library starting from Python 3.5. For earlier versions of Python, there is a port of the module available on PyPI.However, you can utilize this converter without the
typing
module by using one of the proxies defined byuplink.returns
(e.g.,uplink.types.List
).
Here are the collection types defined in uplink.types
. You can
use these or the corresponding type hints from typing
to leverage
this feature:
-
uplink.types.
List
[source]¶ list() -> new empty list list(iterable) -> new list initialized from iterable’s items A proxy for
typing.List
that is safe to use in type hints with Python 3.4 and below.@get("/users") def get_users(self) -> types.List[str]: """Fetches all users"""
-
uplink.types.
Dict
[source]¶ dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s
(key, value) pairs- dict(iterable) -> new dictionary initialized as if via:
d = {} for k, v in iterable:
d[k] = v- dict(**kwargs) -> new dictionary initialized with the name=value pairs
- in the keyword argument list. For example: dict(one=1, two=2)
A proxy for
typing.Dict
that is safe to use in type hints with Python 3.4 and below.@returns.json @get("/users") def get_users(self) -> types.Dict[str, str]: """Fetches all users"""
Writing a Custom Converter¶
You can define custom converters by using uplink.loads
and
uplink.dumps
.
These classes can be used as decorators to create converters of a class and its subclasses:
# Registers the function as a loader for the given model class.
@loads.from_json(Model)
def load_model_from_json(model_type, json):
...
To use the converter, you can generated converter object when
instantiating a Consumer
subclass, through the
converter
constructor parameter:
github = GitHub(BASE_URL, converter=load_model_from_json)
Alternatively, you can add the uplink.loads.install()
or
uplink.dumps.install()
decorator to register the converter
function as a default converter, meaning the converter will be included
automatically with any consumer instance and doesn’t need to be
explicitly provided through the converter
parameter:
# Register the function as a default loader for the given model class.
@loads.install
@loads.from_json(Model)
def load_model_from_json(model_type, json):
...
-
class
uplink.
loads
(base_class, annotations=())¶ Builds a custom object deserializer.
This class takes a single argument, the base model class, and registers the decorated function as a deserializer for that base class and all subclasses.
Further, the decorated function should accept two positional arguments: (1) the encountered type (which can be the given base class or a subclass), and (2) the response data.
@loads(ModelBase) def load_model(model_cls, data): ...
New in version v0.5.0.
-
classmethod
from_json
(base_class, annotations=())¶ Builds a custom JSON deserialization strategy.
This decorator accepts the same arguments and behaves like
uplink.loads
, except that the second argument of the decorated function is a JSON object:@loads.from_json(ModelBase) def from_json(model_cls, json_object): return model_cls.from_json(json_object)
Notably, only consumer methods that have the expected return type (i.e., the given base class or any subclass) and are decorated with
uplink.returns.json
can leverage the registered strategy to deserialize JSON responses.For example, the following consumer method would leverage the
from_json()
strategy defined above, givenUser
is a subclass ofModelBase
:@returns.json @get("user") def get_user(self) -> User: pass
New in version v0.5.0.
-
classmethod
-
class
uplink.
dumps
(base_class, annotations=())¶ Builds a custom object serializer.
This decorator takes a single argument, the base model class, and registers the decorated function as a serializer for that base class and all subclasses.
Further, the decorated function should accept two positional arguments: (1) the encountered type (which can be the given base class or a subclass), and (2) the encountered instance.
@dumps(ModelBase) def deserialize_model(model_cls, model_instance): ...
New in version v0.5.0.
-
classmethod
to_json
(base_class, annotations=())¶ Builds a custom JSON serialization strategy.
This decorator accepts the same arguments and behaves like
uplink.dumps
. The only distinction is that the decorated function should be JSON serializable.@dumps.to_json(ModelBase) def to_json(model_cls, model_instance): return model_instance.to_json()
Notably, only consumer methods that are decorated with py:class:uplink.json and have one or more argument annotations with the expected type (i.e., the given base class or a subclass) can leverage the registered strategy.
For example, the following consumer method would leverage the
to_json()
strategy defined above, givenUser
is a subclass ofModelBase
:@json @post("user") def change_user_name(self, name: Field(type=User): pass
New in version v0.5.0.
-
classmethod