Merge pull request #103 from core-api/add-format-argument

Add format argument

Author: tomchristie

coreapi/__init__.py

@@ -4,7 +4,7 @@
 from coreapi.document import Array, Document, Link, Object, Error, Field
 
 
-__version__ = '2.0.7'
+__version__ = '2.0.8'
 __all__ = [
     'Array', 'Document', 'Link', 'Object', 'Error', 'Field',
     'Client',

coreapi/client.py

@@ -112,16 +112,22 @@ def decoders(self):
     def transports(self):
         return self._transports
 
-    def get(self, url, force_codec=False):
+    def get(self, url, format=None, force_codec=False):
         link = Link(url, action='get')
 
+        decoders = self.decoders
+        if format:
+            decoders = [decoder for decoder in self.decoders if decoder.format == format]
+            if not decoders:
+                raise ValueError("No decoder available with format='%s'" % format)
+
         # Perform the action, and return a new document.
         transport = determine_transport(self.transports, link.url)
-        return transport.transition(link, self.decoders, force_codec=force_codec)
+        return transport.transition(link, decoders, force_codec=force_codec)
 
-    def reload(self, document, force_codec=False):
+    def reload(self, document, format=None, force_codec=False):
         # Fallback for v1.x. To be removed in favour of explict `get` style.
-        return self.get(document.url, force_codec=force_codec)
+        return self.get(document.url, format=format, force_codec=force_codec)
 
     def action(self, document, keys, params=None, validate=True, overrides=None,
                action=None, encoding=None, transform=None):

coreapi/codecs/corejson.py

@@ -231,6 +231,7 @@ def _primative_to_document(data, base_url=None):
 
 class CoreJSONCodec(BaseCodec):
     media_type = 'application/coreapi+json'
+    format = 'corejson'
 
     # The following is due to be deprecated...
     media_types = ['application/coreapi+json', 'application/vnd.coreapi+json']

coreapi/codecs/download.py

@@ -100,6 +100,7 @@ class DownloadCodec(BaseCodec):
     A codec to handle raw file downloads, such as images and other media.
     """
     media_type = '*/*'
+    format = 'download'
 
     def __init__(self, download_dir=None):
         """

coreapi/codecs/jsondata.py

@@ -7,6 +7,7 @@
 
 class JSONCodec(BaseCodec):
     media_type = 'application/json'
+    format = 'json'
 
     def decode(self, bytestring, **options):
         """

coreapi/codecs/text.py

@@ -4,6 +4,7 @@
 
 class TextCodec(BaseCodec):
     media_type = 'text/*'
+    format = 'text'
 
     def decode(self, bytestring, **options):
         return bytestring.decode('utf-8')

docs/api-guide/client.md

@@ -74,6 +74,7 @@ Make a network request to the given URL. If fetching an API schema or hypermedia
 resource, then this should typically return a decoded `Document`.
 
 * `url` - The URL that should be retrieved.
+* `format` - Optional. Force the given codec to be used when decoding the response.
 
 For example:
 

docs/api-guide/codecs.md

@@ -64,6 +64,7 @@ The following attribute is available on codec instances:
 Supports decoding or encoding the Core JSON format.
 
 **.media_type**: `application/coreapi+json`
+**.format**: `openapi`
 
 Example of decoding a Core JSON bytestring into a `Document` instance:
 
@@ -99,6 +100,7 @@ URLs in the document.
 Supports decoding JSON data.
 
 **.media_type**: `application/json`
+**.format**: `json`
 
 Example:
 
@@ -116,6 +118,7 @@ Example:
 Supports decoding plain-text responses.
 
 **.media_type**: `text/*`
+**.format**: `text`
 
 Example:
 
@@ -133,6 +136,7 @@ Supports decoding arbitrary media as a download file. Returns a [temporary file]
 that will be deleted once it goes out of scope.
 
 **.media_type**: `*/*`
+**.format**: `download`
 
 Example:
 
@@ -183,7 +187,7 @@ indicate the download filename][content-disposition-filename].
 ## Custom codecs
 
 Custom codec classes may be created by inheriting from `BaseCodec`, setting
-the `media_type` and `supports` properties, and implementing one or both
+the `media_type` and `format` properties, and implementing one or both
 of the `decode` or `encode` methods.
 
 For example:
@@ -193,7 +197,7 @@ For example:
 
     class YAMLCodec(codecs.BaseCodec):
         media_type = 'application/yaml'
-        supports = ['data']
+        format = 'yaml'
 
         def decode(content, **options):
             return yaml.safe_load(content)