Base code

Base module for resources.

This module represent all the base code for resources, the resources can inherit behaviour from these classes to perform requests and actions to the API.

Classes

facturapi.resources.base.Downloadable

Generic Downloadable class.

Used by resources that can be downloaded as a file.

Methods

facturapi.resources.base.Downloadable.download(id, file_type) classmethod

Download a file from resource.

Performs a GET request to download a file given a resource ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the resource.	required
file_type	FileType	Type of the file to be downloaded. (zip, pdf or xml).	required

Returns:

Type	Description
bytes	bytes: Bytes of the file.

Source code in facturapi/resources/base.py

@classmethod
def download(cls, id: str, file_type: FileType) -> bytes:
    """Download a file from resource.

    Performs a GET request to download a file given a
    resource ID.

    Args:
        id: The ID of the resource.
        file_type: Type of the file to be downloaded.
            (zip, pdf or xml).

    Returns:
        bytes: Bytes of the file.

    """
    return client.download_request(
        f'/{cls._resource}/{id}/{file_type.value}'
    )

facturapi.resources.base.Queryable dataclass

Generic Queryable class.

Used by resources that can be queried in lists. Refer to this class to see the query actions that can be performed on a resource.

Attributes:

Name	Type	Description
_query_params	ClassVar	A class with the parameters that can be queried.

Methods

facturapi.resources.base.Queryable.all(**query_params) classmethod

Retrieve all resources given a query.

All the returned resources are paginated, the method yields the first page of results and if more are found; then it continues to yield pages until all results are queried.

Parameters:

Name	Type	Description	Default
**query_params	dict	Arbitrary query keyword arguments.	{}

Returns:

Type	Description
Generator[facturapi.resources.base.Resource, NoneType, NoneType]	Generator: A generator containing the queried results.

Source code in facturapi/resources/base.py

@classmethod
def all(cls, **query_params) -> Generator[Resource, None, None]:
    """Retrieve all resources given a query.

    All the returned resources are paginated, the method `yields`
    the first page of results and if more are found; then it
    continues to `yield` pages until all results are queried.

    Args:
        **query_params (dict): Arbitrary query keyword arguments.

    Returns:
        Generator: A generator containing the queried results.

    """
    q = cls._query_params(**query_params)
    next_page_uri = f'{cls._resource}?{urlencode(q.dict())}'
    current_page = 1
    while next_page_uri:
        page = client.get(next_page_uri)
        yield from (cls._from_dict(item) for item in page['data'])
        next_page_uri = ''
        if current_page < page['total_pages']:
            current_page += 1
            q.page = current_page
            next_page_uri = f'{cls._resource}?{urlencode(q.dict())}'

facturapi.resources.base.Queryable.count(**query_params) classmethod

Get the total number of results given a query.

Parameters:

Name	Type	Description	Default
**query_params	dict	Arbitrary query keyword arguments.	{}

Returns:

Type	Description
int	int: The total count of results.

Source code in facturapi/resources/base.py

@classmethod
def count(cls, **query_params) -> int:
    """Get the total number of results given a query.

    Args:
        **query_params (dict): Arbitrary query keyword arguments.

    Returns:
        int: The total count of results.

    """
    q = cls._query_params(**query_params)
    response = client.get(cls._resource, q.dict())
    items = response['data']
    return len(items)

facturapi.resources.base.Queryable.first(**query_params) classmethod

Retrieve the first resource found given a query or none.

Parameters:

Name	Type	Description	Default
**query_params	dict	Arbitrary query keyword arguments.	{}

Returns:

Type	Description
Optional[facturapi.resources.base.Resource]	Optional[Resource]: The first resource queried or None if none found.

Source code in facturapi/resources/base.py

@classmethod
def first(cls, **query_params) -> Optional[Resource]:
    """Retrieve the first resource found given a query or none.

    Args:
        **query_params (dict): Arbitrary query keyword arguments.

    Returns:
        Optional[Resource]: The first resource queried or `None`
            if none found.

    """
    q = cls._query_params(limit=1, **query_params)
    response = client.get(cls._resource, q.dict())
    try:
        item = response['data'][0]
    except IndexError:
        rv = None
    else:
        rv = cls._from_dict(item)
    return rv

facturapi.resources.base.Queryable.one(**query_params) classmethod

Retrieve only one resource given a query.

Given a query, retrieve one and only one resource. If more than one resource or none are found, this method throws an exception.

Parameters:

Name	Type	Description	Default
**query_params	dict	Arbitrary query keyword arguments.	{}

Exceptions:

Type	Description
NoResultFound	If no result is found.
MultipleResultsFound	If more than one result is found.

Returns:

Type	Description
Resource	Resource: The one resource queried.

Source code in facturapi/resources/base.py

@classmethod
def one(cls, **query_params) -> Resource:
    """Retrieve only one resource given a query.

    Given a query, retrieve one and only one resource. If more
    than one resource or none are found, this method throws an
    exception.

    Args:
        **query_params (dict): Arbitrary query keyword arguments.

    Raises:
        NoResultFound: If no result is found.
        MultipleResultsFound: If more than one result is found.

    Returns:
        Resource: The one resource queried.

    """
    q = cls._query_params(limit=2, **query_params)
    response = client.get(cls._resource, q.dict())
    items = response['data']
    len_items = len(items)
    if not len_items:
        raise NoResultFound
    if len_items > 1:
        raise MultipleResultsFound
    return cls._from_dict(items[0])

facturapi.resources.base.Resource dataclass

Generic resource from Facturapi.

Generic Resource class used by Facturapi resources.

Attributes:

Name	Type	Description
_resource	ClassVar[str]	Name of the resource the class corresponds to.
id	str	ID of the resource.

facturapi.resources.base.Retrievable

Generic Retrievable class.

Used by resources that can be retrieved, i.e: resources that can be retrieved by a GET request to its ID.

Methods

facturapi.resources.base.Retrievable.refresh(self)

Refresh a resource

Refresh resource's data to be sure its the latest. It performs a GET request on the resource.

Returns:

Type	Description
Resource	The refreshed resource.

Source code in facturapi/resources/base.py

def refresh(self):
    """Refresh a resource

    Refresh resource's data to be sure its the latest. It
    performs a GET request on the resource.

    Returns:
        Resource: The refreshed resource.

    """
    new = self.retrieve(self.id)
    for attr, value in new.__dict__.items():
        setattr(self, attr, value)

facturapi.resources.base.Retrievable.retrieve(id) classmethod

Retrieve a resource given its ID

Performs a GET request with the ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the resource	required

Returns:

Type	Description
Resource	Resource: The resource retrieved.

Source code in facturapi/resources/base.py

@classmethod
def retrieve(cls, id: str) -> Resource:
    """Retrieve a resource given its ID

    Performs a GET request with the ID.

    Args:
        id: The ID of the resource

    Returns:
        Resource: The resource retrieved.

    """
    response = client.get(f'/{cls._resource}/{id}')
    return cls._from_dict(response)