n6sdk.exceptions

class n6sdk.exceptions._ErrorWithPublicMessageMixin(*args, **kwargs)

Bases: object

A mix-in class that provides the public_message property.

The value of this property is a unicode string. It is taken either from the public_message constructor keyword argument (which should be a unicode string or an UTF-8-decodable str string) or – if the argument was not specified – from the value of the default_public_message attribute (which should also be a unicode string or an UTF-8-decodable str string).

The public message should be a complete sentence (or several sentences): first word capitalized (if not being an identifier that begins with a lower case letter) + the period at the end.

Warning

Generally, the message is intended to be presented to clients. Ensure that you do not disclose any sensitive details in the message.

See also

See the documentation of the public exception classes provided by this module.

The str and unicode conversions that are provided by the class use the value of public_message:

>>> class SomeError(_ErrorWithPublicMessageMixin, Exception):
...     pass
...
>>> str(SomeError('a', 'b'))  # using attribute default_public_message
'Internal error.'
>>> str(SomeError('a', 'b', public_message='Sp\xc4\x85m.'))
'Sp\xc4\x85m.'
>>> str(SomeError('a', 'b', public_message=u'Sp\u0105m.'))
'Sp\xc4\x85m.'
>>> unicode(SomeError('a', 'b'))  # using attribute default_public_message
u'Internal error.'
>>> unicode(SomeError('a', 'b', public_message='Sp\xc4\x85m.'))
u'Sp\u0105m.'
>>> unicode(SomeError('a', 'b', public_message=u'Sp\u0105m.'))
u'Sp\u0105m.'

The repr() conversion results in a programmer-readable representation (containing the class name, repr()-formatted constructor arguments and the public_message property):

>>> SomeError('a', 'b')   # using class's default_public_message
<SomeError: args=('a', 'b'); public_message=u'Internal error.'>
>>> SomeError('a', 'b', public_message='Spam.')
<SomeError: args=('a', 'b'); public_message=u'Spam.'>

default_public_message = u'Internal error.'

(overridable in subclasses)

public_message

The aforementioned property.

class n6sdk.exceptions._KeyCleaningErrorMixin(illegal_keys, missing_keys)

Bases: object

Mix-in for key cleaning-related exception classes.

Each instance of such a class:

• should be initialized with two (positional or keyword) arguments: illegal_keys and missing_keys that should be sets of – respectively – illegal or missing keys (each key being a string);
• exposes these arguments as the illegal_keys and missing_keys attributes (for possible later inspection).

class n6sdk.exceptions._ValueCleaningErrorMixin(error_info_seq)

Bases: object

Mix-in for value cleaning-related exception classes.

Each instance of such a class:

• should be initialized with one argument being a list of (<key>, <offending value or list of offending values>, <actual exception>) tuples – where <actual exception> is the exception instance that caused the error (e.g. a ValueError or an instance of some _ErrorWithPublicMessageMixin subclass);
• exposes that argument as the error_info_seq attribute (for possible later inspection).

exception n6sdk.exceptions.FieldValueError(*args, **kwargs)

Bases: n6sdk.exceptions._ErrorWithPublicMessageMixin, exceptions.ValueError

Intended to be raised in clean_param_value() and clean_result_value() methods of n6sdk.data_spec.fields.Field subclasses.

When using it in a clean_param_value()‘s implementation it is recommended (though not required) to insantiate the exception specifying the public_message keyword argument.

Typically, this exception (as any other Exception subclass/instance raised in a field’s clean_*_value() method) is caught by the n6sdk machinery – then, appropriately, ParamValueCleaningError (with public_message including public_message of this exception – see: the ParamValueCleaningError documentation) or ResultValueCleaningError (with public message being just the default and safe "Internal error.") is raised.

See also

See: _ErrorWithPublicMessageMixin as well as the ParamValueCleaningError and ResultValueCleaningError.

exception n6sdk.exceptions.FieldValueTooLongError(*args, **kwargs)

Bases: n6sdk.exceptions.FieldValueError

Intended to be raised when the length of the given value is too big.

Instances must be initialized with the following keyword-only arguments:

• field (n6sdk.data_spec.fields.Field instance): the field whose method raised the exception;
• checked_value: the value which caused the exception (possibly already partially processed by methods of field);
• max_length: the length limit that was exceeded (what caused the exception).

They become attributes of the exception instance – respectively: field, checked_value, max_length.

>>> exc = FieldValueTooLongError(
...     field='sth', checked_value=['foo'], max_length=42)
>>> exc.field
'sth'
>>> exc.checked_value
['foo']
>>> exc.max_length
42

>>> FieldValueTooLongError(   
...     checked_value=['foo'], max_length=42)
Traceback (most recent call last):
  ...
TypeError: __init__() needs keyword-only argument field

>>> FieldValueTooLongError(   
...     field='sth', max_length=42)
Traceback (most recent call last):
  ...
TypeError: __init__() needs keyword-only argument checked_value

>>> FieldValueTooLongError(   
...     field='sth', checked_value=['foo'])
Traceback (most recent call last):
  ...
TypeError: __init__() needs keyword-only argument max_length

exception n6sdk.exceptions.DataAPIError(*args, **kwargs)

Bases: n6sdk.exceptions._ErrorWithPublicMessageMixin, exceptions.Exception

The base class for client-data-or-backend-API-related exceptions.

(They are not intended to be raised in clean_*_value() of Field subclasses – use FieldValueError instead.)

>>> exc = DataAPIError('a', 'b')
>>> exc.args
('a', 'b')
>>> exc.public_message   # using attribute default_public_message
u'Internal error.'
>>> unicode(exc)
u'Internal error.'
>>> str(exc)
'Internal error.'
>>> u'{}'.format(exc)
u'Internal error.'
>>> '{}'.format(exc)
'Internal error.'

>>> exc = DataAPIError('a', 'b', public_message='Spam.')
>>> exc.args
('a', 'b')
>>> exc.public_message   # the message passed into constructor
u'Spam.'
>>> unicode(exc)
u'Spam.'
>>> str(exc)
'Spam.'
>>> u'{}'.format(exc)
u'Spam.'
>>> '{}'.format(exc)
'Spam.'

exception n6sdk.exceptions.AuthorizationError(*args, **kwargs)

Bases: n6sdk.exceptions.DataAPIError

Intended to be raised by data backend API to signal authorization problems.

default_public_message = u'Access not allowed.'

exception n6sdk.exceptions.TooMuchDataError(*args, **kwargs)

Bases: n6sdk.exceptions.DataAPIError

Intended to be raised by data backend API when too much data have been requested.

default_public_message = u'Too much data requested.'

exception n6sdk.exceptions.ParamCleaningError(*args, **kwargs)

Bases: n6sdk.exceptions.DataAPIError

The base class for exceptions raised when query parameter cleaning fails.

Instances of its subclasses are raised by the data specification machinery.

default_public_message = u'Invalid parameter(s).'

exception n6sdk.exceptions.ParamKeyCleaningError(illegal_keys, missing_keys)

Bases: n6sdk.exceptions._KeyCleaningErrorMixin, n6sdk.exceptions.ParamCleaningError

This exception should be raised by the data specification machinery (in particular, it is raised in n6sdk.data_spec.BaseDataSpec.clean_param_dict()) when some client-specified parameter keys (names) are illegal and/or missing.

This exception class provides default_public_message (see: _ErrorWithPublicMessageMixin) as a property whose value is a nice, user-readable message that includes all illegal and missing keys.

>>> try:
...     raise ParamKeyCleaningError({'zz', 'x'}, {'Ę', 'b'})
... except ParamCleaningError as exc:
...     pass
...
>>> exc.public_message == (
...     u'Illegal query parameters: "x", "zz". ' +
...     u'Required but missing query parameters: "\\u0118", "b".')
True
>>> exc.illegal_keys == {'zz', 'x'}
True
>>> exc.missing_keys == {'Ę', 'b'}
True

illegal_keys_msg_template = u'Illegal query parameters: {}.'

missing_keys_msg_template = u'Required but missing query parameters: {}.'

default_public_message

The aforementioned property.

exception n6sdk.exceptions.ParamValueCleaningError(error_info_seq)

Bases: n6sdk.exceptions._ValueCleaningErrorMixin, n6sdk.exceptions.ParamCleaningError

Raised when query parameter value(s) cannot be cleaned (are not valid).

Especially, this exception should be raised by the data specification machinery (in particular, it is raised in n6sdk.data_spec.BaseDataSpec.clean_param_dict()) when any Exception subclass(es)/instance(s) (possibly, FieldValueError) have been caught after being raised by data specification fields’ clean_param_value().

This exception class provides default_public_message (see: _ErrorWithPublicMessageMixin) as a property whose value is a nice, user-readable message that includes, for each contained exception: the key, the offending value(s) and the public_message attribute of that contained exception (the latter only for instances of _ErrorWithPublicMessageMixin subclasses).

>>> err1 = TypeError('foo', 'bar')
>>> err2 = FieldValueError('foo', 'bar', public_message='Message.')
>>> try:
...     raise ParamValueCleaningError([
...         ('k1', 'ł-1', err1),
...         ('k2', ['ł-2', 'xyz'], err2),
...     ])
... except ParamCleaningError as exc:
...     pass
...
>>> exc.public_message == (
...     u'Problem with value(s) ("\\u0142-1") of query parameter "k1". ' +
...     u'Problem with value(s) ("\\u0142-2", "xyz")' +
...     u' of query parameter "k2" (Message).')
True
>>> exc.error_info_seq == [
...     ('k1', 'ł-1', err1),
...     ('k2', ['ł-2', 'xyz'], err2),
... ]
True

msg_template = u'Problem with value(s) ({values_repr}) of query parameter "{key}"{optional_exc_public_message}.'

default_public_message

The aforementioned property.

exception n6sdk.exceptions.ResultCleaningError(*args, **kwargs)

Bases: n6sdk.exceptions.DataAPIError

The base class for exceptions raised when result data cleaning fails.

Instances of its subclasses are raised by the data specification machinery.

exception n6sdk.exceptions.ResultKeyCleaningError(illegal_keys, missing_keys)

Bases: n6sdk.exceptions._KeyCleaningErrorMixin, n6sdk.exceptions.ResultCleaningError

This exception should be raised by the data specification machinery (in particular, it is raised in n6sdk.data_spec.BaseDataSpec.clean_result_dict()) when some keys in a data-backend-API-produced result dictionary are illegal and/or missing.

Note

default_public_message (see: _ErrorWithPublicMessageMixin) is consciously left as the default and safe u'Internal error.'.

exception n6sdk.exceptions.ResultValueCleaningError(error_info_seq)

Bases: n6sdk.exceptions._ValueCleaningErrorMixin, n6sdk.exceptions.ResultCleaningError

Raised when result item value(s) cannot be cleaned (are not valid).

Especially, this exception should be raised by the data specification machinery (in particular, it is raised in n6sdk.data_spec.BaseDataSpec.clean_result_dict()) when any Exception subclass(es)/instance(s) have been caught after being raised by data specification fields’ clean_result_value().

Note

default_public_message (see: _ErrorWithPublicMessageMixin) is consciously left as the default and safe u'Internal error.' – so (unlike for ParamValueCleaningError and fields’ clean_param_value()) no information from underlying FieldValueError or other exceptions raised in fields’ clean_result_value() is disclosed in the default_public_message value.