The mgnipy.MGnipy() client

The mgnipy.MGnipy() client#

Here we provide additional information about the mgnipy.MGnipy() client

# uncomment below if colab
#!pip install mgnipy

Why start with the mgnipy.MGnipy client?#

  • Unified configuration: Central MGnipyConfig for base URL, credentials, token handling, and cache settings — one place to change behavior

  • Client as a context manager: Helps make sure that any connections are closed via with block also has helpers for checking status .status and to .close()/.aclose()

  • Tidier cache invalidation: All the cache files across all resource endpoints (e.g., MG.studies, MG.analysis, MG.biome) go to a consistent place. The MG.clear_subcaches() can then clear all the mgnipy cache files for all different requests made.

Quick to start#

You can create a single MGnipy() instance and then access resource proxies from it. Those resource proxies aka resource endpoint-specific MGnifier()s would then share the same configuration of MGnipy()

from mgnipy import MGnipy

# Create a default client (will pick up .env if present)
MG = MGnipy(cache_dir="temp_example")

# details
print(MG)

# check if there is an active session (shouldnt be one)
MG.status

MGnipy(config=api_version=<SupportedApiVersions.V2: 'v2'> base_url=HttpUrl('https://www.ebi.ac.uk/') cache_dir=PosixPath('temp_example'))
Client or AuthenticatedClient type: Client
HTTP client open: False
Async client open: False

<bound method ClientManagerMixin.status of MGnipy(config=api_version=<SupportedApiVersions.V2: 'v2'> base_url=HttpUrl('https://www.ebi.ac.uk/') cache_dir=PosixPath('temp_example'))>

We can then easily point to the different MGnify API endpoints

# for example we can access the samples MGnify resource
samples = MG.samples

# some info
print(samples)

# more info
samples.describe_endpoint()

<class 'mgnipy.V2.proxies.samples.Samples'> for 'samples' resource
- Endpoint: 'mgnipy.emgapi_v2_client.api.samples.list_mgnify_samples'
- Params: {}
- Child resource: 'sample' 
List all samples analysed by MGnify

MGnify samples inherit directly from samples (or BioSamples) in ENA.

Supported parameters:
- biome_lineage: None | str | Unset The lineage to match, including all descendant biomes
- search: None | str | Unset Search within sample titles and accessions
- order: ListMgnifySamplesOrderType0 | None | Unset
- page: int | Unset Default: 1.
- page_size: int | None | Unset

Client as Context Manager#

Context managers allow you to allocate and release resources precisely when you want to. The most widely used example of context managers is the with statement. … Read more here

MGnipy will take care of closing the clients if you use with blocks – alternatively you can .close() manually

For example:

# small query to get 3 per page
modified_search = samples.filter(page_size=3)

with MG:
    # within this client context, get 3 pages of samples resource
    modified_search.get_all(limit=2)

modified_search.metadata.to_pandas(expand_nested_dicts=True)

we can check the status of the client to be sure

MG.status

# also can manuallly close
# MG.close()

Client or AuthenticatedClient type: Client
HTTP client open: False
Async client open: False

<bound method ClientManagerMixin.status of MGnipy(config=api_version=<SupportedApiVersions.V2: 'v2'> base_url=HttpUrl('https://www.ebi.ac.uk/') cache_dir=PosixPath('temp_example'))>

API helpers#

We can also learn more about the MGnify API using the mgnipy.MGnipy client.

  • MG.list_resources() returns the available endpoint names.

  • MG.describe_resource() to read parameter docs extracted from the OpenAPI spec.

# List known resources (strings like 'samples', 'studies', 'analyses')
print(MG.list_resources())

# Describe a resource
MG.describe_resources(MG.list_resources()[0])

['analyses', 'analysis', 'assemblies', 'assembly', 'genomes', 'genome', 'publications', 'publication', 'samples', 'sample', 'studies', 'study', 'runs', 'run', 'biomes', 'biome', 'miscellaneous', 'catalogues', 'catalogue', 'private_studies']
List all analyses (MGYAs) available from MGnify

Each analysis is the result of a Pipeline execution on a reads dataset (either a raw read-run, or an
assembly).

Supported parameters:
- page: int | Unset Default: 1.
- page_size: int | None | Unset

Quick cleanup#

The MG.clear_subcaches() will clear all the mgnipy cache files, no matter if they were from MG.studies vs. MG.analysis vs. MG.biome etc, in the universal MG.cache_dir.

MG.clear_subcaches()
Contents