def create_resource(transport,
payload,
url,
mime_type=None,
item_mime_type=None,
guess_token=True):
"""Construct and return a resource object.
The mime type will be used to find a resource specific base class.
Alternatively, if no resource specific base class exists, one of
the generic base classes, Resource or ResourceList, will be used.
If an item mime type is provided, it will be used by list
resources to construct item resources from the list.
If 'guess_token' is True, we will try and guess what key the
resources body lives under. If False, we assume that the resource
body is the body of the payload itself. This is important for
constructing Item resources from a resource list.
"""
# Determine the key for the resources data.
token = None
if guess_token:
other_keys = set(payload.keys()).difference(SPECIAL_KEYS)
if len(other_keys) == 1:
token = other_keys.pop()
# Select the base class for the resource.
if 'count' in payload:
resource_class = CountResource
elif mime_type and rem_mime_format(mime_type) in RESOURCE_MAP:
resource_class = RESOURCE_MAP[rem_mime_format(mime_type)]
elif token and isinstance(payload[token], list):
resource_class = ListResource
else:
resource_class = ItemResource
return resource_class(transport,
payload,
url,
token=token,
item_mime_type=item_mime_type)
def create_resource(payload, url, mime_type=None, item_mime_type=None,
guess_token=True):
"""Construct and return a resource object.
The mime type will be used to find a resource specific base class.
Alternatively, if no resource specific base class exists, one of
the generic base classes, Resource or ResourceList, will be used.
If an item mime type is provided, it will be used by list
resources to construct item resources from the list.
If 'guess_token' is True, we will try and guess what key the
resources body lives under. If False, we assume that the resource
body is the body of the payload itself. This is important for
constructing Item resources from a resource list.
"""
# Determine the key for the resources data.
token = None
if guess_token:
other_keys = set(payload.keys()).difference(SPECIAL_KEYS)
if len(other_keys) == 1:
token = other_keys.pop()
# Select the base class for the resource.
if 'count' in payload:
resource_class = CountResource
elif mime_type and rem_mime_format(mime_type) in RESOURCE_MAP:
resource_class = RESOURCE_MAP[rem_mime_format(mime_type)]
elif token and isinstance(payload[token], list):
resource_class = ResourceList
else:
resource_class = ResourceItem
return resource_class(payload, url, token=token,
item_mime_type=item_mime_type)
def _wrap_field(self,
field_payload,
field_url=None,
field_mimetype=None,
list_item_mimetype=None,
force_resource=False):
"""Wrap the value of a field in a resource or field object.
This determines a suitable wrapper for a field, turning it into
a resource or a wrapper with utility methods that can be used to
interact with the field or perform additional queries.
Args:
field_payload (object):
The payload of the field. The type of value determines the
way in which this is wrapped.
field_url (unicode, optional):
The URL representing the payload in the field, if one is
available. If not provided, one may be computed, depending
on the type and contents of the field.
field_mimetype (unicode, optional):
The mimetype used to represent the field. If provided, this
may result in the wrapper being a :py:class:`Resource`
subclass.
list_item_mimetype (unicode, optional):
The mimetype used or any items within the field, if the
field is a list.
force_resource (bool, optional):
Force the return of a resource, even a generic one, instead
of a field wrapper.
Returns:
object:
A wrapper, or the field payload. This may be one of:
1. A subclass of :py:class:`Resource`.
2. A field wrapper (:py:class:`ResourceDictField`,
:py:class:`ResourceLinkField`, or
:py:class:`ResourceListField`).
3. The field payload itself, if no wrapper is needed.
"""
if isinstance(field_payload, dict):
if (force_resource
or (field_mimetype
and rem_mime_format(field_mimetype) in RESOURCE_MAP)):
# We have a resource backing this mimetype. Try to create
# an instance of the resource for this payload.
if not field_url:
try:
field_url = field_payload['links']['self']['href']
except KeyError:
field_url = ''
return _create_resource_for_field(parent_resource=self,
field_payload=field_payload,
mimetype=field_mimetype,
url=field_url)
else:
# If the payload consists solely of link-supported keys,
# then we'll return a special ResourceLinkField. Anything
# else is treated as a standard dictionary.
if ('href' in field_payload
and not set(field_payload.keys()) - LINK_KEYS):
return ResourceLinkField(self, field_payload)
else:
return ResourceDictField(self, field_payload)
elif isinstance(field_payload, list):
return ResourceListField(self,
field_payload,
item_mimetype=list_item_mimetype)
else:
return field_payload
def _wrap_field(self, field_payload, field_url=None, field_mimetype=None,
list_item_mimetype=None, force_resource=False):
"""Wrap the value of a field in a resource or field object.
This determines a suitable wrapper for a field, turning it into
a resource or a wrapper with utility methods that can be used to
interact with the field or perform additional queries.
Args:
field_payload (object):
The payload of the field. The type of value determines the
way in which this is wrapped.
field_url (unicode, optional):
The URL representing the payload in the field, if one is
available. If not provided, one may be computed, depending
on the type and contents of the field.
field_mimetype (unicode, optional):
The mimetype used to represent the field. If provided, this
may result in the wrapper being a :py:class:`Resource`
subclass.
list_item_mimetype (unicode, optional):
The mimetype used or any items within the field, if the
field is a list.
force_resource (bool, optional):
Force the return of a resource, even a generic one, instead
of a field wrapper.
Returns:
object:
A wrapper, or the field payload. This may be one of:
1. A subclass of :py:class:`Resource`.
2. A field wrapper (:py:class:`ResourceDictField`,
:py:class:`ResourceLinkField`, or
:py:class:`ResourceListField`).
3. The field payload itself, if no wrapper is needed.
"""
if isinstance(field_payload, dict):
if (force_resource or
(field_mimetype and
rem_mime_format(field_mimetype) in RESOURCE_MAP)):
# We have a resource backing this mimetype. Try to create
# an instance of the resource for this payload.
if not field_url:
try:
field_url = field_payload['links']['self']['href']
except KeyError:
field_url = ''
return _create_resource_for_field(parent_resource=self,
field_payload=field_payload,
mimetype=field_mimetype,
url=field_url)
else:
# If the payload consists solely of link-supported keys,
# then we'll return a special ResourceLinkField. Anything
# else is treated as a standard dictionary.
if ('href' in field_payload and
not set(field_payload.keys()) - LINK_KEYS):
return ResourceLinkField(self, field_payload)
else:
return ResourceDictField(self, field_payload)
elif isinstance(field_payload, list):
return ResourceListField(self, field_payload,
item_mimetype=list_item_mimetype)
else:
return field_payload