Docs

Author: tomchristie

coreapi/client.py

@@ -54,7 +54,7 @@ def _lookup_link(document, keys):
 def _validate_parameters(link, parameters):
     """
     Ensure that parameters passed to the link are correct.
-    Raises a `ValidationError` if any parameters do not validate.
+    Raises a `ParameterError` if any parameters do not validate.
     """
     provided = set(parameters.keys())
     required = set([
@@ -77,7 +77,7 @@ def _validate_parameters(link, parameters):
         errors[item] = 'Unknown parameter.'
 
     if errors:
-        raise exceptions.ValidationError(errors)
+        raise exceptions.ParameterError(errors)
 
 
 def get_default_decoders():

coreapi/codecs/download.py

@@ -1,25 +1,14 @@
 # coding: utf-8
 from coreapi.codecs.base import BaseCodec
 from coreapi.compat import urlparse
+from coreapi.utils import DownloadedFile
 import cgi
 import mimetypes
 import os
 import posixpath
 import tempfile
 
 
-class DownloadedFile(tempfile._TemporaryFileWrapper):
-    basename = None
-
-    def __repr__(self):
-        state = "closed" if self.close_called else "open"
-        mode = "" if self.close_called else " '%s'" % self.file.mode
-        return "<DownloadedFile '%s', %s%s>" % (self.name, state, mode)
-
-    def __str__(self):
-        return self.__repr__()
-
-
 def _unique_output_path(path):
     """
     Given a path like '/a/b/c.txt'

coreapi/exceptions.py

@@ -37,7 +37,7 @@ class LinkLookupError(CoreAPIException):
     pass
 
 
-class ValidationError(CoreAPIException):
+class ParameterError(CoreAPIException):
     """
     Raised when the parameters passed do not match the link fields.
 

coreapi/transports/http.py

@@ -82,11 +82,11 @@ def _get_params(method, encoding, fields, params=None):
             elif location == 'form':
                 if not seen_body:
                     data[key] = utils.validate_form_param(value, encoding=encoding)
-        except exceptions.ValidationError as exc:
+        except exceptions.ParameterError as exc:
             errors[key] = exc.message
 
     if errors:
-        raise exceptions.ValidationError(errors)
+        raise exceptions.ParameterError(errors)
 
     # Move any files from 'data' into 'files'.
     if isinstance(data, dict):

coreapi/utils.py

@@ -2,6 +2,7 @@
 from coreapi.compat import string_types, text_type, urlparse
 from collections import namedtuple
 import os
+import tempfile
 
 
 File = namedtuple('File', 'name content content_type')
@@ -26,6 +27,18 @@ def guess_filename(obj):
     return None
 
 
+class DownloadedFile(tempfile._TemporaryFileWrapper):
+    basename = None
+
+    def __repr__(self):
+        state = "closed" if self.close_called else "open"
+        mode = "" if self.close_called else " '%s'" % self.file.mode
+        return "<DownloadedFile '%s', %s%s>" % (self.name, state, mode)
+
+    def __str__(self):
+        return self.__repr__()
+
+
 # Negotiation utilities. USed to determine which codec or transport class
 # should be used, given a list of supported instances.
 
@@ -109,7 +122,7 @@ def validate_path_param(value):
     value = _validate_form_field(value, allow_list=False)
     if not value:
         msg = 'Parameter %s: May not be empty.'
-        raise exceptions.ValidationError(msg)
+        raise exceptions.ParameterError(msg)
     return value
 
 
@@ -127,7 +140,7 @@ def validate_body_param(value, encoding):
     elif encoding == 'application/octet-stream':
         if not is_file(value):
             msg = 'Must be an file upload.'
-            raise exceptions.ValidationError(msg)
+            raise exceptions.ParameterError(msg)
         return value
     msg = 'Unsupported encoding "%s" for outgoing request.'
     raise exceptions.NetworkError(msg % encoding)
@@ -150,7 +163,7 @@ def _validate_form_object(value, allow_files=False):
     """
     if not isinstance(value, dict):
         msg = 'Must be an object.'
-        raise exceptions.ValidationError(msg)
+        raise exceptions.ParameterError(msg)
     return {
         text_type(item_key): _validate_form_field(item_val, allow_files=allow_files)
         for item_key, item_val in value.items()
@@ -179,7 +192,7 @@ def _validate_form_field(value, allow_files=False, allow_list=True):
         return value
 
     msg = 'Must be a primative type.'
-    raise exceptions.ValidationError(msg)
+    raise exceptions.ParameterError(msg)
 
 
 def _validate_json_data(value):
@@ -197,4 +210,4 @@ def _validate_json_data(value):
         }
 
     msg = 'Must be a JSON primative.'
-    raise exceptions.ValidationError(msg)
+    raise exceptions.ParameterError(msg)

docs/api-guide/exceptions.md

@@ -24,14 +24,14 @@ An issue occurred with the network request.
 
 The keys passed in a [`client.action()`][action] call did not reference a link in the document.
 
-## ValidationError
+## ParameterError
 
 The parameters passed in a [`client.action()`][action] call did not match the set of required and optional fields made available by the link, or if the type of parameters passed could
 not be supported by the given encoding on the link.
 
 ## ErrorMessage
 
-The server returned a CoreAPI [Error][error].
+The server returned a CoreAPI [Error][error] document.
 
 [action]: /api-guide/client.md#interacting-with-an-api
 [error]: /api-guide/document.md#error

docs/api-guide/utils.md

@@ -5,6 +5,52 @@ may be useful if writing a custom client or transport class.
 
 ---
 
+## File utilities
+
+The following classes are used to indicate upload and download file content.
+
+### File
+
+May be used as a parameter with links that require a file input.
+
+**Signature**: `File(name, content, content_type=None)`
+
+* `name` - The filename.
+* `content` - A string, bytestring, or stream object.
+* `content_type` - An optional string representing the content type of the file.
+
+An open file or other stream may also be used directly as a parameter, instead
+of a `File` instance, but the `File` instance makes it easier to specify the
+filename and content in code.
+
+Example:
+
+    >>> from coreapi.utils import File
+    >>> upload = File('example.csv', 'a,b,c\n1,2,3\n4,5,6\n')
+    >>> data = client.action(document, ['store', 'upload_media'], params={'upload': upload})
+
+### DownloadedFile
+
+A temporary file instance, used to represent downloaded media.
+
+Available attributes:
+
+* `name` - The full filename, including the path.
+* `basename` - The filename as determined at the point of download.
+
+Example:
+
+    >>> download = client.action(document, ['user', 'get_profile_image'])
+    >>> download.basename
+    'avatar.png'
+    >>> download.read()
+    b'...'
+
+By default the file will be deleted when this object goes out of scope. See
+[the `DownloadCodec` documentation][download-codec] for more details.
+
+---
+
 ## Negotiation utilities
 
 The following functions are used to determine which of a set of transports
@@ -57,15 +103,15 @@ if an invalid value is passed.
 
 Returns the value, coerced into a string primitive. Validates that the value that is suitable for use in URI-encoded path parameters. Empty strings and composite types such as dictionaries are disallowed.
 
-May raise `ValidationError`.
+May raise `ParameterError`.
 
 ### validate_query_param
 
 **Signature**: `validate_query_param(value)`
 
 Returns the value, coerced into a string primitive. Validates that the value is suitable for use in URL query parameters.
 
-May raise `ValidationError`.
+May raise `ParameterError`.
 
 ### validate_body_param
 
@@ -75,7 +121,7 @@ Returns the value, coerced into a primitive that is valid for the given encoding
 
 Valid encodings are `application/json`, `x-www-form-urlencoded`, `multipart/form-data` and `application/octet-stream`.
 
-May raise `ValidationError` for an invalid value, or `NetworkError` for an unsupported encoding.
+May raise `ParameterError` for an invalid value, or `NetworkError` for an unsupported encoding.
 
 ### validate_form_param
 
@@ -85,4 +131,7 @@ Returns the value, coerced into a primitive that is valid for the given encoding
 
 Valid encodings are `application/json`, `x-www-form-urlencoded`, `multipart/form-data`.
 
-May raise `ValidationError`, or `NetworkError` for an unsupported encoding.
+May raise `ParameterError`, or `NetworkError` for an unsupported encoding.
+
+
+[download-codec]: codecs.md#downloadcodec

docs/topics/release-notes.md

@@ -1 +1,25 @@
 # Release Notes
+
+## 2.0
+
+* Upload and download support.
+* Media type changes from `application/vnd.coreapi+json` to `application/coreapi+json`.
+  For backwards compatibility, either are currently accepted.
+* Codec methods `dump()`/`load()` become `encode()`/`decode()`. The old style
+  methods currently continue to work for backward compatibility.
+* The client instance validates that passed parameters match the available parameter names.
+  Fails if unknown parameters are included, or required parameters are not included.
+* `.action()` now accepts a `validate=False` argument, to turn off parameter validation.
+* Parameter values are validated against the encoding used on the link to ensure
+  that they can be represented in the request.
+* `type` annotation added to `Field` instances.
+* `multipart/form-data` is now consistently used on multipart links, even when
+  no file arguments are passed.
+* `action`, `encoding`, and `transform` parameters to `.action()` now replaced with a
+  single `overrides` argument. The old style arguments currently continue to work for
+  backward compatibility.
+* The `supports` attribute is no longer used when defining codec classes. A
+  `supports` property currently exists on the base class, to provide backwards
+  compatibility for `coreapi-cli`.
+
+The various backwards compatibility shims are planned to be removed in the 2.1 release.

tests/test_utils.py

@@ -6,13 +6,13 @@
 def test_validate_path_param():
     assert utils.validate_path_param(1) == '1'
     assert utils.validate_path_param(True) == 'true'
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_path_param(None)
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_path_param('')
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_path_param({})
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_path_param([])
 
 
@@ -22,9 +22,9 @@ def test_validate_query_param():
     assert utils.validate_query_param(None) == ''
     assert utils.validate_query_param('') == ''
     assert utils.validate_query_param([1, 2, 3]) == ['1', '2', '3']
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_query_param({})
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_query_param([1, 2, {}])
 
 
@@ -44,41 +44,41 @@ def test_validate_form_data():
 
     # Invalid JSON
     data = datetime.datetime.now()
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_form_param(data, 'application/json')
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_body_param(data, 'application/json')
 
     data = utils.File('abc.txt', None)
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_form_param(data, 'application/json')
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_body_param(data, 'application/json')
 
     # URL Encoded
     assert utils.validate_form_param(123, 'application/x-www-form-urlencoded') == '123'
     assert utils.validate_body_param({'a': 123}, 'application/x-www-form-urlencoded') == {'a': '123'}
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_form_param({'a': {'foo': 'bar'}}, 'application/x-www-form-urlencoded')
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_body_param(123, 'application/x-www-form-urlencoded')
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_form_param(utils.File('abc.txt', None), 'application/x-www-form-urlencoded')
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_body_param({'a': utils.File('abc.txt', None)}, 'application/x-www-form-urlencoded')
 
     # Multipart
     assert utils.validate_form_param(123, 'multipart/form-data') == '123'
     assert utils.validate_form_param(utils.File('abc.txt', None), 'multipart/form-data') == utils.File('abc.txt', None)
     assert utils.validate_body_param({'a': 123}, 'multipart/form-data') == {'a': '123'}
     assert utils.validate_body_param({'a': utils.File('abc.txt', None)}, 'multipart/form-data') == {'a': utils.File('abc.txt', None)}
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_form_param({'a': {'foo': 'bar'}}, 'multipart/form-data')
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_body_param(123, 'multipart/form-data')
 
     # Raw upload
-    with pytest.raises(exceptions.ValidationError):
+    with pytest.raises(exceptions.ParameterError):
         utils.validate_body_param(123, 'application/octet-stream')
 
     # Invalid encoding on outgoing request