graceful package¶
graceful.fields module¶
-
class
graceful.fields.
BaseField
(details, label=None, source=None, validators=None, many=False, read_only=False)¶ Bases:
object
Base field class for subclassing.
To create new field type subclass BaseField and implement following methods:
from_representation()
: converts representation (used in request/response body) to internal value.to_representation()
: converts internal value to representation that will be used in response body.
Parameters: - details (str) – human readable description of field (it will be used for describing resource on OPTIONS requests).
- label (str) –
human readable label of a field (it will be used for describing resource on OPTIONS requests).
Note: it is recommended to use field names that are self-explanatory intead of relying on field labels.
- source (str) – name of internal object key/attribute that will be
passed to field on
.to_representation()
call. Special'*'
value is allowed that will pass whole object to field when making representation. If not set then default source will be a field name used as a serializer’s attribute. - validators (list) – list of validator callables.
- many (bool) – set to True if field is in fact a list of given type objects
- read_only (bool) – True if field is read only and cannot be set/modified by POST and PUT requests
Example:
class BoolField(BaseField): def from_representation(self, data): if data in {'true', 'True', 'yes', '1', 'Y'}: return True: elif data in {'false', 'False', 'no', '0', 'N'}: return False: else: raise ValueError( "{data} is not valid boolean field".format( data=data ) ) def to_representation(self, value): return ["True", "False"][value]
-
describe
(**kwargs)¶ Describe this field instance for purpose of self-documentation.
Parameters: kwargs (dict) – dictionary of additional description items for extending default description Returns: dict – dictionary of description items Suggested way for overriding description fields or extending it with additional items is calling super class method with new/overriden fields passed as keyword arguments like following:
class DummyField(BaseField): def description(self, **kwargs): super().describe(is_dummy=True, **kwargs)
-
from_representation
(data)¶ Convert representation value to internal value.
Note
This is method handler stub and should be redifined in the
BaseField
subclasses.
-
spec
= None¶
-
to_representation
(value)¶ Convert representation value to internal value.
Note
This is method handler stub and should be redifined in the
BaseField
subclasses.
-
type
= None¶
-
validate
(value)¶ Perform validation on value by running all field validators.
Single validator is a callable that accepts one positional argument and raises “ValidationError” when validation fails.
Error message included in exception will be included in http error response
Parameters: value – internal value to validate Returns: None Note
Concept of validation for fields is understood here as a process of checking if data of valid type (successfully parsed/processed by
.from_representation
handler) does meet some other constraints (lenght, bounds, uniqueness, etc). So this method is always called with result of.from_representation()
passed as its argument.
-
class
graceful.fields.
BoolField
(details, representations=None, **kwargs)¶ Bases:
graceful.fields.BaseField
Represents boolean type of field.
By default accepts a wide range of incoming True/False representations:
- False:
['False', 'false', 'FALSE', 'F', 'f', '0', 0, 0.0, False]
- True:
['True', 'true', 'TRUE', 'T', 't', '1', 1, True]
By default, the outup representations of internal object’s value are Python’s False/True values that will be later serialized to form that is native for content-type of use.
This behavior can be changed using
representations
field argument. Note that when usingrepresentations
parameter you need to make strict decision and there is no ability to accept multiple options for true/false representations. Anyway, it is reccomended approach to strictly define these values.Parameters: representations (tuple) – two-tuple with representations for (False, True) values, that will be used instead of default values -
from_representation
(data)¶ Convert representation value to
bool
if it has expected form.
-
to_representation
(value)¶ Convert internal boolean value to one of defined representations.
-
type
= 'bool'¶
- False:
-
class
graceful.fields.
FloatField
(details, max_value=None, min_value=None, **kwargs)¶ Bases:
graceful.fields.BaseField
Represents float type of field.
Accepts both floats and strings as an incoming float number representation and always returns float as a representation of internal objects’s value that will be later serialized to form that is native for content-type of use.
This field accepts optional arguments that simply add new max and min value validation.
Parameters: - max_value (int) – optional max value for validation
- min_value (int) – optional min value for validation
-
from_representation
(data)¶ Convert representation value to
float
.
-
to_representation
(value)¶ Convert internal value to
float
.
-
type
= 'float'¶
-
class
graceful.fields.
IntField
(details, max_value=None, min_value=None, **kwargs)¶ Bases:
graceful.fields.BaseField
Represents integer type of field.
Field of this type accepts both integers and strings as an incoming integer representation and always returns int as a representation of internal objects’s value that will be later serialized to form that is native for content-type of use.
This field accepts optional arguments that simply add new max and min value validation.
Parameters: - max_value (int) – optional max value for validation
- min_value (int) – optional min value for validation
-
from_representation
(data)¶ Convert representation value to
int
.
-
to_representation
(value)¶ Convert internal value to
int
.
-
type
= 'int'¶
-
class
graceful.fields.
RawField
(details, label=None, source=None, validators=None, many=False, read_only=False)¶ Bases:
graceful.fields.BaseField
Represents raw field subtype.
Any value from resource object will be returned as is without any conversion and no control over serialized value type is provided. Can be used only with very simple data types like int, float, str etc. but can eventually cause problems if value provided in representation has type that is not accepted in application.
Effect of using this can differ between various content-types.
-
from_representation
(data)¶ Return representation value as-is (note: content-type dependent).
-
to_representation
(value)¶ Return internal value as-is (note: content-type dependent).
-
type
= 'raw'¶
-
-
class
graceful.fields.
StringField
(details, label=None, source=None, validators=None, many=False, read_only=False)¶ Bases:
graceful.fields.BaseField
Represents string field subtype without any extensive validation.
-
from_representation
(data)¶ Convert representation value to
str
.
-
to_representation
(value)¶ Convert representation value to
str
.
-
type
= 'string'¶
-
graceful.parameters module¶
-
class
graceful.parameters.
Base64EncodedParam
(details, label=None, required=False, default=None, many=False, validators=None)¶ Bases:
graceful.parameters.BaseParam
Describes string parameter with value encoded using Base64 encoding.
-
spec
= ('RFC-4648 Section 4', 'https://tools.ietf.org/html/rfc4648#section-4')¶
-
value
(raw_value)¶ Decode param with Base64.
-
-
class
graceful.parameters.
BaseParam
(details, label=None, required=False, default=None, many=False, validators=None)¶ Bases:
object
Base parameter class for subclassing.
To create new parameter type subclass
BaseParam
and implement.value()
method handler.Parameters: - details (str) – verbose description of parameter. Should contain all
information that may be important to your API user and will be used
for describing resource on
OPTIONS
requests and.describe()
call. - label (str) –
human readable label for this parameter (it will be used for describing resource on OPTIONS requests).
Note that it is recomended to use parameter names that are self-explanatory intead of relying on param labels.
- required (bool) – if set to
True
then all GET, POST, PUT, PATCH and DELETE requests will return400 Bad Request
response if query param is not provided. Defaults toFalse
. - default (str) –
set default value for param if it is not provided in request as query parameter. This MUST be a raw string value that will be then parsed by
.value()
handler.If default is set and
required
isTrue
it will raiseValueError
as having required parameters with default value has no sense. - many (str) –
- set to
True
if multiple occurences of this parameter - can be included in query string, as a result values for this
parameter will be always included as a list in params dict.
Defaults to
False
.
Note
If
many=False
and client inlcudes multiple values for this parameter in query string then only one of those values will be returned, and it is undefined which one. - set to
Example:
class BoolParam(BaseParam): def value(self, data): if data in {'true', 'True', 'yes', '1', 'Y'}: return True elif data in {'false', 'False', 'no', '0', 'N'}: return False else: raise ValueError( "{data} is not valid boolean field".format( data=data ) )
-
container
¶ alias of
list
-
describe
(**kwargs)¶ Describe this parameter instance for purpose of self-documentation.
Parameters: kwargs (dict) – dictionary of additional description items for extending default description Returns: dict – dictionary of description items Suggested way for overriding description fields or extending it with additional items is calling super class method with new/overriden fields passed as keyword arguments like following:
class DummyParam(BaseParam): def description(self, **kwargs): super().describe(is_dummy=True, **kwargs)
-
spec
= None¶
-
type
= None¶
-
validated_value
(raw_value)¶ Return parsed parameter value and run validation handlers.
Error message included in exception will be included in http error response
Parameters: value – raw parameter value to parse validate Returns: None Note
Concept of validation for params is understood here as a process of checking if data of valid type (successfully parsed/processed by
.value()
handler) does meet some other constraints (lenght, bounds, uniqueness, etc.). It will internally call itsvalue()
handler.
-
value
(raw_value)¶ Raw value deserialization method handler.
Parameters: raw_value (str) – raw value from GET parameters
- details (str) – verbose description of parameter. Should contain all
information that may be important to your API user and will be used
for describing resource on
-
class
graceful.parameters.
BoolParam
(details, label=None, required=False, default=None, many=False, validators=None)¶ Bases:
graceful.parameters.BaseParam
Describes parameter with value expressed as bool.
Accepted string values for boolean parameters are as follows:
- False:
['True', 'true', 'TRUE', 'T', 't', '1'}
- True:
['False', 'false', 'FALSE', 'F', 'f', '0', '0.0']
In case raw parameter value does not match any of these strings the
value()
method will raiseValueError
method.-
type
= 'bool'¶
-
value
(raw_value)¶ Decode param as bool value.
- False:
-
class
graceful.parameters.
DecimalParam
(details, label=None, required=False, default=None, many=False, validators=None)¶ Bases:
graceful.parameters.BaseParam
Describes parameter with value expressed as decimal number.
-
type
= 'decimal'¶
-
value
(raw_value)¶ Decode param as decimal value.
-
-
class
graceful.parameters.
FloatParam
(details, label=None, required=False, default=None, many=False, validators=None)¶ Bases:
graceful.parameters.BaseParam
Describes parameter with value expressed as float number.
-
type
= 'float'¶
-
value
(raw_value)¶ Decode param as float value.
-
-
class
graceful.parameters.
IntParam
(details, label=None, required=False, default=None, many=False, validators=None)¶ Bases:
graceful.parameters.BaseParam
Describes parameter with value expressed as integer number.
-
type
= 'integer'¶
-
value
(raw_value)¶ Decode param as integer value.
-
-
class
graceful.parameters.
StringParam
(details, label=None, required=False, default=None, many=False, validators=None)¶ Bases:
graceful.parameters.BaseParam
Describes parameter that will always be returned as-is (string).
Additional validation can be added to param instance usingvalidators
argument during initialization:from graceful.parameters import StringParam from graceful.validators import match_validator from graceful.resources.generic import Resource class ExampleResource(Resource): word = StringParam( 'one "word" parameter', validators=[match_validator('\w+')], )
-
type
= 'string'¶
-
value
(raw_value)¶ Return param value as-is (str).
-
graceful.serializers module¶
-
class
graceful.serializers.
BaseSerializer
¶ Bases:
object
Base serializer class for describing internal object serialization.
Example:
from graceful.serializers import BaseSerializer from graceful.fields import RawField, IntField, FloatField class CatSerializer(BaseSerializer): species = RawField("non normalized cat species") age = IntField("cat age in years") height = FloatField("cat height in cm")
-
describe
()¶ Describe all serialized fields.
It returns dictionary of all fields description defined for this serializer using their own
describe()
methods with respect to order in which they are defined as class attributes.Returns: OrderedDict – serializer description
-
fields
¶ Return dictionary of field definition objects of this serializer.
-
from_representation
(representation)¶ Convert given representation dict into internal object.
Internal object is simply a dictionary of values with respect to field sources.
This does not check if all required fields exist or values are valid in terms of value validation (see:
BaseField.validate()
) but still requires all of passed representation values to be well formed representation (success call tofield.from_representation
).In case of malformed representation it will run additional validation only to provide a full detailed exception about all that might be wrong with provided representation.
Parameters: representation (dict) – dictionary with field representation values Raises: DeserializationError
– when at least one representation field is not formed as expected by field object. Information about additional forbidden/missing/invalid fields is provided as well.
-
get_attribute
(obj, attr)¶ Get attribute of given object instance.
Reason for existence of this method is the fact that ‘attribute’ can be also object’s key from if is a dict or any other kind of mapping.
Note: it will return None if attribute key does not exist
Parameters: obj (object) – internal object to retrieve data from Returns: internal object’s key value or attribute
-
set_attribute
(obj, attr, value)¶ Set value of attribute in given object instance.
Reason for existence of this method is the fact that ‘attribute’ can be also a object’s key if it is a dict or any other kind of mapping.
Parameters: - obj (object) – object instance to modify
- attr (str) – attribute (or key) to change
- value – value to set
-
to_representation
(obj)¶ Convert given internal object instance into representation dict.
Representation dict may be later serialized to the content-type of choice in the resource HTTP method handler.
This loops over all fields and retrieves source keys/attributes as field values with respect to optional field sources and converts each one using
field.to_representation()
method.Parameters: obj (object) – internal object that needs to be represented Returns: dict – representation dictionary
-
validate
(object_dict, partial=False)¶ Validate given internal object returned by
to_representation()
.Internal object is validated against missing/forbidden/invalid fields values using fields definitions defined in serializer.
Parameters: - object_dict (dict) – internal object dictionart to perform to validate
- partial (bool) – if set to True then incomplete object_dict is accepter and will not raise any exceptions when one of fields is missing
Raises: DeserializationError
-
-
class
graceful.serializers.
MetaSerializer
¶ Bases:
type
Metaclass for handling serialization with field objects.
-
static
__new__
(mcs, name, bases, namespace)¶ Create new class object instance and alter its namespace.
-
classmethod
__prepare__
(mcs, name, bases, **kwargs)¶ Prepare class namespace in a way that ensures order of attributes.
This needs to be an OrderedDict so _get_fields() method can construct fields storage that preserves the same order of fields as defined in code.
Note: this is python3 thing and support for ordering of params in descriptions will not be backported to python2 even if this framework will get python2 support.
-
static
graceful.validators module¶
-
graceful.validators.
min_validator
(min_value)¶ Return validator function that ensures lower bound of a number.
Result validation function will validate the internal value of resource instance field with the
value >= min_value
checkParameters: min_value – minimal value for new validator
-
graceful.validators.
max_validator
(max_value)¶ Return validator function that ensures upper bound of a number.
Result validation function will validate the internal value of resource instance field with the
value >= min_value
check.Parameters: max_value – maximum value for new validator
-
graceful.validators.
choices_validator
(choices)¶ Return validator function that will check if
value in choices
.Parameters: max_value (list, set, tuple) – allowed choices for new validator
-
graceful.validators.
match_validator
(expression)¶ Return validator function that will check if matches given expression.
Parameters: match – if string then this will be converted to regular expression using re.compile
. Can be also any object that hasmatch()
method like already compiled regular regular expression or custom matching object/class.
graceful.errors module¶
-
exception
graceful.errors.
DeserializationError
(missing=None, forbidden=None, invalid=None, failed=None)¶ Bases:
ValueError
Raised when error happened during deserialization of representation.
-
as_bad_request
()¶ Translate this error to falcon’s HTTP specific error exception.
-
-
exception
graceful.errors.
ValidationError
¶ Bases:
ValueError
Raised when validation error occured.
-
as_bad_request
()¶ Translate this error to falcon’s HTTP specific error exception.
Note
Exceptions returned by this method should be used to inform about resource validation failures. In case of param validation failures the
as_invalid_param()
method should be used.
-
as_invalid_param
(param_name)¶ Translate this error to falcon’s HTTP specific error exception.
Note
Exceptions returned by this method should be used to inform about param validation failures. In case of resource validation failures the
as_bad_request()
method should be used.Parameters: param_name (str) – HTTP query string parameter name
-