mgnipy.V2.mgnifier.describe module

class DescribeEmgapiModule(endpoint_module)

Bases: object

A class to describe and interact with an endpoint module from the metagenomics API v2. This class provides methods to list supported parameters, validate keyword arguments, construct URLs, and retrieve endpoint documentation. It also includes functionality to determine if the endpoint is private or a list endpoint, and to calculate pagination details based on the number of items and page size.

Parameters:

endpoint_module (ModuleType) – The endpoint module to describe.

describe_endpoint(as_dict=False)

Provides a description of the endpoint from the openapi documentation i.e., https://www.ebi.ac.uk/metagenomics/api/v2/openapi.json

Parameters:

as_dict (bool , optional) – Whether to return the description as a dictionary mapping parameter names to their descriptions (default is False).

Returns:

A dictionary mapping parameter names to their descriptions if as_dict is True, otherwise None.

Return type:

dict of str to str or None

property emgapi_docs: str

property emgapi_resource: str | None

Retrieves the name of the endpoint resource based on the endpoint module. E.g., if the endpoint module corresponds to the “studies” resource, this property would return “studies”.

Returns:

The name of the endpoint resource, or None if the endpoint module is not set.

Return type:

str or None

get_num_items(params=None)

Parameters:

params (dict | None)

Return type:

int | None

get_num_pages(num_items, page_size=None)

Calculates the total number of pages based on the total count and default page size.

Parameters:

• num_items (int | None)

• page_size (int | None)

Return type:

int | None

property id_param_key: str

Get the parameter name used to identify this resource.

Returns:

The identifier parameter (e.g., “accession”, “biome_lineage”).

Return type:

str

property is_list_endpoint: bool

Checks if the endpoint module corresponds to a list endpoint.

property is_private: bool

Checks if the endpoint module corresponds to a private only endpoint.

list_supported_params()

Lists supported keyword arguments for the endpoint module.

Returns:

List of supported keyword argument names.

Return type:

list of str

page_param_iter(num_pages)

Generates a list of parameter dictionaries for each page based on the total number of pages.

Parameters:

num_pages (int )

Return type:

list [dict [str , int ]]

resolve_query_string(**kwargs)

Resolves the query string for the endpoint based on the current parameters.

Parameters:

**kwargs – Keyword arguments to validate and include in the query string.

Returns:

The resolved query string.

Return type:

str

sub_url(**kwargs)

Constructs the sub-URL for the endpoint based on the current parameters.

Returns:

The constructed sub-URL, or None if the endpoint module is not set.

Return type:

str or None

url_path(**kwargs)

Constructs the full URL path for the endpoint based on the current parameters.

Parameters:

**kwargs – Keyword arguments to validate and include in the URL construction.

Returns:

The constructed URL path.

Return type:

str

validate_endpoint_kwargs(**kwargs)

Validates the provided keyword arguments against the supported parameters of the endpoint module.

Parameters:

**kwargs – Keyword arguments to validate.

Returns:

The validated keyword arguments.

Return type:

dict of str to Any

Raises:

ValueError – If any provided keyword argument is not supported by the endpoint module.