Wrangle

Convert and validate remote ID and item types according to specific remote implementations.

Classes:

RemoteDataWrangler()

Convert and validate remote ID and item types according to specific remote implementations.

class musify.libraries.remote.core.wrangle.RemoteDataWrangler

Bases: object

Convert and validate remote ID and item types according to specific remote implementations.

Attributes:

`source`	The name of the service for which data can be processed by this wrangler
`unavailable_uri_dummy`	The value to use as a URI for an item which does not have an associated remote object.
`url_api`	The base URL of the API for this remote source
`url_ext`	The base URL of external links for this remote source

Methods:

`get_id_type`(value[, kind])	Determine the remote ID type of the given `value` and return its type.
`validate_id_type`(value[, kind])	Check that the given `value` is a type of remote ID given by `kind`
`get_item_type`(values[, kind])	Determine the remote object type of `values`.
`validate_item_type`(values, kind)	Check that the given `values` are a type of item given by `kind` or a simple ID.
`convert`(value[, kind, type_in, type_out])	Converts ID to required format - API URL, EXT URL, URI, or ID.
`extract_ids`(values[, kind])	Extract a list of IDs from input `values`.

abstract property source: str: The name of the service for which data can be processed by this wrangler

abstract property unavailable_uri_dummy: str: The value to use as a URI for an item which does not have an associated remote object. An item that has this URI value will be excluded from most remote logic.

abstract property url_api: URL: The base URL of the API for this remote source

abstract property url_ext: URL: The base URL of external links for this remote source

abstractmethod static get_id_type(value, kind=None)

Determine the remote ID type of the given value and return its type.

Parameters:

value (str) – URL/URI/ID to check.
kind (RemoteObjectType | None (default: None)) – When this is equal to USER, ignore checks and always return ID as type.

Returns:

RemoteIDType – The RemoteIDType.

Raises:

RemoteIDTypeError – Raised when the function cannot determine the ID type of the input value.

abstractmethod classmethod validate_id_type(value, kind=RemoteIDType.ALL)

Check that the given value is a type of remote ID given by kind

Return type:: bool

classmethod get_item_type(values, kind=None)

Determine the remote object type of values.

values may be:

A string representing a URL/URI/ID.
A MutableSequence of strings representing URLs/URIs/IDs of the same type.
A remote API JSON response for a collection including a valid item type value under a type key.
A MutableSequence of remote API JSON responses for a collection including the same structure as above.
A RemoteResponse of the appropriate type for this RemoteAPI which holds a valid API JSON response as described above.
A Sequence of RemoteResponses as above.

Parameters:

values (GenericAlias[RemoteResponse]) – The values representing some remote objects. See description for allowed value types. These items must all be of the same type of item to pass i.e. all tracks OR all artists etc.
kind (RemoteObjectType | None (default: None)) – The RemoteObjectType to use as backup if the value is found to be an ID.

Returns:

RemoteObjectType – The RemoteObjectType

Raises:

RemoteObjectTypeError – Raised when the function cannot determine the item type of the input values. Or when the list contains strings representing many differing remote object types or only IDs.

classmethod validate_item_type(values, kind)

Check that the given values are a type of item given by kind or a simple ID.

values may be:

A string representing a URL/URI/ID.
A MutableSequence of strings representing URLs/URIs/IDs of the same type.
A remote API JSON response for a collection including a valid item type value under a type key.
A MutableSequence of remote API JSON responses for a collection including the same structure as above.
A RemoteResponse of the appropriate type for this RemoteAPI which holds a valid API JSON response as described above.
A Sequence of RemoteResponses as above.

Parameters:

values (GenericAlias[RemoteResponse]) – The values representing some remote objects. See description for allowed value types. These items must all be of the same type of item to pass i.e. all tracks OR all artists etc.
kind (RemoteObjectType) – The remote object type to check for.

Raises:

RemoteObjectTypeError – Raised when the function cannot validate the item type of the input values is of type kind or a simple ID.

Return type:

None

abstractmethod classmethod convert(value, kind=None, type_in=RemoteIDType.ALL, type_out=RemoteIDType.ID)

Converts ID to required format - API URL, EXT URL, URI, or ID.

Parameters:

value (str) – URL/URI/ID to convert.
kind (RemoteObjectType | None (default: None)) – Optionally, give the item type of the input value to skip some checks. This is required when the given value is an ID.
type_in (RemoteIDType (default: <RemoteIDType.ALL: 0>)) – Optionally, give the ID type of the input value to skip some checks.
type_out (RemoteIDType (default: <RemoteIDType.ID: 22>)) – The ID type of the output value.

Returns:

str – Formatted string.

Raises:

RemoteIDTypeError – Raised when the function cannot determine the item type of the input value.
RemoteObjectTypeError – Raised when the function cannot process the input value as a type of the given type_in i.e. the type_in does not match the actual type of the value.

abstractmethod classmethod extract_ids(values, kind=None)

Extract a list of IDs from input values.

values may be:

A string representing a URL/URI/ID.
A MutableSequence of strings representing URLs/URIs/IDs of the same type.
A remote API JSON response for a collection including:
- a valid ID value under an id key,
- a valid item type value under a type key if kind is None.
A MutableSequence of remote API JSON responses for a collection including the same structure as above.
A RemoteResponse of the appropriate type for this RemoteAPI which holds a valid API JSON response as described above.
A Sequence of RemoteResponses as above.

Parameters:

values (GenericAlias[RemoteResponse]) – The values representing some remote objects. See description for allowed value types. These items may be of mixed item types e.g. some tracks AND some artists.
kind (RemoteObjectType | None (default: None)) – Optionally, give the item type of the input value to skip some checks. This is required when the given value is an ID.

Returns:

list[str] – List of IDs.

Raises:

RemoteError – Raised when the function cannot determine the item type of the input values. Or when it does not recognise the type of the input values parameter.