woob.capabilities.base

exception UserError

Bases: Exception

Exception containing an error message for user.

exception FieldNotFound(obj, field)

Bases: Exception

A field isn’t found.

Parameters:

• obj (BaseObject) – object

• field (Field) – field not found

class Capability

Bases: object

This is the base class for all capabilities.

A capability may define abstract methods (which raise NotImplementedError) with an explicit docstring to tell backends how to implement them.

Also, it may define some objects, using BaseObject.

class Field(doc, *args, **kwargs)

Bases: object

Field of a BaseObject class.

Parameters:

• doc (str) – docstring of the field

• args – list of types accepted

• default – default value of this field. If not specified, NotLoaded is used.

convert(value)

Convert value to the wanted one.

class IntField(doc, **kwargs)

Bases: Field

A field which accepts only int types.

convert(value)

Convert value to the wanted one.

class DecimalField(doc, **kwargs)

Bases: Field

A field which accepts only decimal type.

convert(value)

Convert value to the wanted one.

class FloatField(doc, **kwargs)

Bases: Field

A field which accepts only float type.

convert(value)

Convert value to the wanted one.

class StringField(doc, **kwargs)

Bases: Field

A field which accepts only str strings.

convert(value)

Convert value to the wanted one.

class BytesField(doc, **kwargs)

Bases: Field

A field which accepts only bytes strings.

convert(value)

Convert value to the wanted one.

class BoolField(doc, **kwargs)

Bases: Field

A field which accepts only bool type.

convert(value)

Convert value to the wanted one.

class Enum(*args, **kwargs)

Bases: object

class EnumField(doc, enum, **kwargs)

Bases: Field

convert(value)

Convert value to the wanted one.

empty(value)

Checks if a value is empty (None, NotLoaded or NotAvailable).

Return type:

bool

class BaseObject(id='', url=NotLoaded, backend=None)

Bases: object

This is the base class for a capability object.

A capability interface may specify to return several kind of objects, to formalise retrieved information from websites.

As python is a flexible language where variables are not typed, we use a system to force backends to set wanted values on all fields. To do that, we use the Field class and all derived ones.

For example:

class Transfer(BaseObject):
    " Transfer from an account to a recipient.  "

    amount =    DecimalField('Amount to transfer')
    date =      Field('Date of transfer', str, date, datetime)
    origin =    Field('Origin of transfer', int, str)
    recipient = Field('Recipient', int, str)

The docstring is mandatory.

Variables:

url – (str) url

id: str | None = None

backend: str | None = None

property fullid: str

Full ID of the object, in form ‘ID@backend’.

copy()

Return type:

BaseObject

set_empty_fields(value, excepts=())

Set the same value on all empty fields.

Parameters:

• value (Any) – value to set on all empty fields

• excepts – if specified, do not change fields listed (default: ())

iter_fields()

Iterate on the fields keys and values.

Can be overloaded to iterate on other things.

Return type:

iter[(key, value)]

to_dict()

Return type:

Dict[str, Any]

classmethod from_dict(values, backend=None)

find_object(mylist, error=None, **kwargs)

Very simple tools to return an object with the matching parameters in kwargs.

find_object_any_match(objects, key_value_pairs, error=None, with_priority=True, ignore_empty=True)

Tool method that returns an object that match any parameter given in key_value_pairs.

Compared with find_object, this method does not need all parameters to be matching. If no priority is set, the method will return the first successful match. With several key-values set, this may not be the object instance with the most key matches.

Parameters:

• objects (Iterable[TypeVar(T)]) – The list or iterator of objects that can match

• key_value_pairs (list) – The key-values that the object should have to match. This is given as a list of pairs, where each pair represent a key-value, the first item being the key, and the second is the value.

• error (Exception or None) – The error to raise in case no object matches. (default: None)

• with_priority (bool) – If True, the key-value pairs order decides the priority of the matching. (default: True) With priority enabled, an object matching with a more important key will be matched over another object matching with a less important keys. This means that all objects will be iterated in order to assure this priority, unless the most preferred key matches, in which case the iteration stops early. This feature is enabled by default. See the example sections for more details.

• ignore_empty (bool) – If True, empty key-values (None, EmptyType) will not be matched. True by default. (default: True)

Return type:

TypeVar(T) | None

Returns:

The matching object if any

Examples:

>>> class Point:
...     def __init__(self, x, y):
...         self.x = x
...         self.y = y
...     def __repr__(self):
...         return f'Point({self.x},{self.y})'
>>> points = (Point(0,0), Point(1, 2), Point(None, 3))
>>> find_object_any_match(points, (('x', 0), ('y', 1))) # Will match on x with first point
Point(0,0)
>>> find_object_any_match(points, (('x', 2), ('y', 2))) # Will match on y with second point
Point(1,2)
>>> find_object_any_match(points, (('x', 1), ('y', 0))) # Will match on x with second point because priority
Point(1,2)
>>> find_object_any_match(points, (('x', 1), ('y', 0)), with_priority=False) # Will return first successful match
Point(0,0)
>>> find_object_any_match(points, (('x', None),)) # second condition (None) is ignored by default
None
>>> find_object_any_match(points, (('x', None),), ignore_empty=False) # will match last point
Point(None,3)
>>> find_object_any_match(points, (('x', -1),), error=ValueError) # Will raise ValueError
ValueError:

strict_find_object(mylist, error=None, **kwargs)

Tools to return an object with the matching parameters in kwargs. Parameters with empty value are skipped

Return type:

BaseObject | None

capability_to_string(capability_klass)

Return type:

str