modulector-sdk 2.3.0__py3-none-any.whl

modulector_sdk/__init__.py

@@ -0,0 +1,69 @@
+"""Convenience SDK helpers for Modulector API clients."""
+
+from .services import (
+    API_BASE_URL,
+    MODULECTOR_API_BASE_URL,
+    MethylationDetailsResponse,
+    MirnaAlias,
+    MirnaDetailsResponse,
+    MirnaDisease,
+    MirnaDrug,
+    MirnaTargetInteraction,
+    SourceLink,
+    SubscribePubmedsResponse,
+    UcscCpgIsland,
+    find_methylation_sites,
+    find_mirna_codes,
+    get_diseases,
+    get_drugs,
+    get_methylation_details,
+    get_methylation_site_genes,
+    get_methylation_sites,
+    get_mirna_aliases,
+    get_mirna_codes,
+    get_mirna_details,
+    get_mirna_target_interactions,
+    subscribe_pubmeds,
+    unsubscribe_pubmeds,
+)
+from .utils import (
+    PaginatedResponse,
+    get_all_paginated_results,
+    get_paginated_response,
+    get_simple_response,
+    iter_paginated_results,
+    request_url,
+)
+
+__all__ = [
+    "API_BASE_URL",
+    "MODULECTOR_API_BASE_URL",
+    "MethylationDetailsResponse",
+    "MirnaAlias",
+    "MirnaDetailsResponse",
+    "MirnaDisease",
+    "MirnaDrug",
+    "MirnaTargetInteraction",
+    "PaginatedResponse",
+    "SourceLink",
+    "SubscribePubmedsResponse",
+    "UcscCpgIsland",
+    "find_methylation_sites",
+    "find_mirna_codes",
+    "get_all_paginated_results",
+    "get_diseases",
+    "get_drugs",
+    "get_methylation_details",
+    "get_methylation_site_genes",
+    "get_methylation_sites",
+    "get_mirna_aliases",
+    "get_mirna_codes",
+    "get_mirna_details",
+    "get_mirna_target_interactions",
+    "get_paginated_response",
+    "get_simple_response",
+    "iter_paginated_results",
+    "request_url",
+    "subscribe_pubmeds",
+    "unsubscribe_pubmeds",
+]

modulector_sdk/py.typed

@@ -0,0 +1 @@
+

modulector_sdk/services.py

@@ -0,0 +1,758 @@
+"""Typed service functions for Modulector API endpoints."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from typing import Any, Final, Literal, TypedDict, cast
+
+import requests
+
+from .utils import (
+    Headers,
+    PaginatedResponse,
+    get_paginated_response,
+    get_simple_response,
+)
+
+MODULECTOR_API_BASE_URL: Final[str] = os.getenv(
+    "MODULECTOR_API_BASE_URL",
+    "https://modulector.multiomix.org",
+)
+API_BASE_URL: Final[str] = MODULECTOR_API_BASE_URL
+FINDER_LIMIT_MAX: Final[int] = 3000
+
+Ordering = str | Sequence[str]
+ScoreClass = Literal["V", "H", "M", "L"]
+
+
+class SourceLink(TypedDict):
+    """External source link returned by detail endpoints."""
+
+    source: str
+    """Name of the external database that contains related information."""
+
+    url: str
+    """URL to access the external database entry."""
+
+
+class MirnaDetailsResponse(TypedDict):
+    """Response returned by the miRNA details service."""
+
+    aliases: list[str]
+    """miRNA aliases, including previous IDs according to miRBase."""
+
+    mirna_sequence: str | None
+    """miRNA nucleotide sequence."""
+
+    mirbase_accession_id: str
+    """miRNA accession ID according to miRBase."""
+
+    links: list[SourceLink]
+    """External database links for the miRNA of interest."""
+
+
+class MirnaAlias(TypedDict):
+    """One miRBase accession to mature miRNA alias record."""
+
+    mirbase_accession_id: str
+    """miRBase accession ID for the miRNA."""
+
+    mature_mirna: str
+    """Mature miRNA ID in the miRBase database."""
+
+    previous_mature_mirna: str | None
+    """Previous mature miRNA identifier associated with the same accession ID."""
+
+
+class MirnaTargetInteraction(TypedDict):
+    """One miRNA target interaction record."""
+
+    id: int
+    """Record identifier in MirDIP."""
+
+    mirna: str
+    """Standardized miRNA ID used by the interaction record."""
+
+    mirna_aliases: list[str]
+    """Aliases and identifiers used to resolve the searched miRNA."""
+
+    gene: str
+    """Target gene symbol."""
+
+    gene_aliases: list[str]
+    """Aliases and symbols associated with the searched gene."""
+
+    score: str
+    """MirDIP interaction score, with values between 0 and 1."""
+
+    source_name: str
+    """Database from which the interaction was extracted."""
+
+    pubmeds: list[str]
+    """PubMed URLs for the miRNA-gene interaction."""
+
+    sources: list[str]
+    """Source database names used to calculate the MirDIP interaction score."""
+
+    score_class: ScoreClass | None
+    """MirDIP score class for the interaction."""
+
+
+class MirnaDisease(TypedDict):
+    """One miRNA disease association record."""
+
+    id: int
+    """Internal ID of the record in the HMDD database."""
+
+    category: str
+    """HMDD category code assigned to classify the disease association."""
+
+    disease: str
+    """Name of the disease associated with the miRNA."""
+
+    pubmed: str
+    """PubMed URL for the scientific article supporting the association."""
+
+    description: str
+    """Short description of why the miRNA is related to the disease."""
+
+
+class MirnaDrug(TypedDict):
+    """One miRNA drug association record."""
+
+    id: int
+    """Internal ID of the record in the SM2miR database."""
+
+    small_molecule: str
+    """Small molecule or drug name."""
+
+    fda_approved: bool
+    """Whether the small molecule or drug is FDA approved."""
+
+    detection_method: str
+    """Experimental method used to detect the miRNA expression effect."""
+
+    condition: str
+    """Tissue or condition used for detection."""
+
+    pubmed: str
+    """PubMed URL for the scientific article supporting the relationship."""
+
+    reference: str
+    """Title of the scientific article supporting the relationship."""
+
+    expression_pattern: str
+    """Expression pattern of the miRNA in the drug relationship."""
+
+    support: str
+    """Supporting text for the drug-miRNA relationship."""
+
+
+class UcscCpgIsland(TypedDict):
+    """UCSC CpG island relation for a methylation site."""
+
+    cpg_island: str
+    """Chromosomal coordinates of the CpG island."""
+
+    relation: str
+    """Relation of the methylation site to the CpG island."""
+
+
+class MethylationDetailsResponse(TypedDict):
+    """Response returned by the methylation site details service."""
+
+    name: str
+    """Methylation site name according to the Illumina Infinium MethylationEPIC
+    2.0 array.
+    """
+
+    aliases: list[str]
+    """Other names for the same methylation site on Illumina arrays."""
+
+    chromosome_position: str
+    """Chromosome, position, and strand where the methylation site is located."""
+
+    ucsc_cpg_islands: list[UcscCpgIsland]
+    """CpG islands related to the methylation site according to UCSC."""
+
+    genes: dict[str, list[str]]
+    """Genes related to the methylation site and their affected regions."""
+
+
+class SubscribePubmedsResponse(TypedDict):
+    """Response returned after creating a PubMed news subscription."""
+
+    token: str
+    """Subscription token."""
+
+
+def get_mirna_target_interactions(
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    mirna: str | None = None,
+    gene: str | None = None,
+    score: float | None = None,
+    include_pubmeds: bool | None = None,
+    ordering: Ordering | None = None,
+    search: str | None = None,
+    page: int | None = None,
+    page_size: int | None = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> PaginatedResponse[MirnaTargetInteraction]:
+    """Return miRNA-gene target interactions.
+
+    :param base_url: Base URL of the Modulector API.
+    :param mirna: miRNA accession ID or miRBase name.
+    :param gene: Gene symbol.
+    :param score: Minimum mirDIP interaction score. Valid values are between
+        ``0`` and ``1``.
+    :param include_pubmeds: Whether PubMed links should be included.
+    :param ordering: Ordering field or comma-separated fields. Prefix a field
+        with ``-`` for descending order.
+    :param search: Search term for supported server-side search fields.
+    :param page: Page number to request.
+    :param page_size: Number of records per page.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :raises ValueError: If neither ``mirna`` nor ``gene`` is provided, or if
+        ``score`` is outside the accepted range.
+    :return: Paginated miRNA target interaction records.
+    """
+
+    if mirna is None and gene is None:
+        raise ValueError("mirna or gene is required")
+    if score is not None and not 0 <= score <= 1:
+        raise ValueError("score must be between 0 and 1")
+
+    params = _request_params(
+        mirna=mirna,
+        gene=gene,
+        score=score,
+        include_pubmeds=_bool_param(include_pubmeds),
+        ordering=_format_ordering(ordering),
+        search=search,
+    )
+    response = get_paginated_response(
+        _build_url(base_url, "mirna-target-interactions"),
+        params=params,
+        page=page,
+        page_size=page_size,
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(PaginatedResponse[MirnaTargetInteraction], response)
+
+
+def get_mirna_details(
+    mirna: str,
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> MirnaDetailsResponse:
+    """Return details for one miRNA.
+
+    :param mirna: miRNA identifier, such as a miRNA code or accession ID.
+    :param base_url: Base URL of the Modulector API.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :return: miRNA aliases, sequence, accession ID, and source links.
+    """
+
+    payload = get_simple_response(
+        _build_url(base_url, "mirna"),
+        params={"mirna": mirna},
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(MirnaDetailsResponse, payload)
+
+
+def get_mirna_aliases(
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    mature_mirna: str | None = None,
+    mirbase_accession_id: str | None = None,
+    previous_mature_mirna: str | None = None,
+    search: str | None = None,
+    ordering: Ordering | None = None,
+    page: int | None = None,
+    page_size: int | None = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> PaginatedResponse[MirnaAlias]:
+    """Return miRNA accession and mature ID alias records.
+
+    :param base_url: Base URL of the Modulector API.
+    :param mature_mirna: Exact mature miRNA filter.
+    :param mirbase_accession_id: Exact miRBase accession ID filter.
+    :param previous_mature_mirna: Exact previous mature miRNA filter.
+    :param search: Case-insensitive search across identifier fields.
+    :param ordering: Ordering field or comma-separated fields. Prefix a field
+        with ``-`` for descending order.
+    :param page: Page number to request.
+    :param page_size: Number of records per page.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :return: Paginated miRNA alias records.
+    """
+
+    params = _request_params(
+        mature_mirna=mature_mirna,
+        mirbase_accession_id=mirbase_accession_id,
+        previous_mature_mirna=previous_mature_mirna,
+        search=search,
+        ordering=_format_ordering(ordering),
+    )
+    response = get_paginated_response(
+        _build_url(base_url, "mirna-aliases"),
+        params=params,
+        page=page,
+        page_size=page_size,
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(PaginatedResponse[MirnaAlias], response)
+
+
+def find_mirna_codes(
+    query: str,
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    limit: int | None = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> list[str]:
+    """Return miRNA identifiers matching a search string.
+
+    :param query: miRNA search string.
+    :param base_url: Base URL of the Modulector API.
+    :param limit: Maximum number of returned values. The API accepts values up
+        to ``3000``.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :raises ValueError: If ``limit`` is less than ``1`` or greater than
+        ``3000``.
+    :return: Matching miRNA IDs or accession IDs.
+    """
+
+    _validate_limit(limit)
+    payload = get_simple_response(
+        _build_url(base_url, "mirna-codes-finder"),
+        params=_request_params(query=query, limit=limit),
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(list[str], payload)
+
+
+def get_mirna_codes(
+    mirna_codes: Sequence[str],
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> dict[str, str | None]:
+    """Return approved miRBase accessions for miRNA identifiers.
+
+    :param mirna_codes: miRNA identifiers to resolve.
+    :param base_url: Base URL of the Modulector API.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :return: Mapping from each requested identifier to its accession ID, or
+        ``None`` when no accession ID is found.
+    """
+
+    payload = get_simple_response(
+        _build_url(base_url, "mirna-codes"),
+        method="POST",
+        json={"mirna_codes": list(mirna_codes)},
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(dict[str, str | None], payload)
+
+
+def find_methylation_sites(
+    query: str,
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    limit: int | None = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> list[str]:
+    """Return methylation site names matching a search string.
+
+    :param query: Methylation site search string.
+    :param base_url: Base URL of the Modulector API.
+    :param limit: Maximum number of returned values. The API accepts values up
+        to ``3000``.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :raises ValueError: If ``limit`` is less than ``1`` or greater than
+        ``3000``.
+    :return: Matching methylation site names.
+    """
+
+    _validate_limit(limit)
+    payload = get_simple_response(
+        _build_url(base_url, "methylation-sites-finder"),
+        params=_request_params(query=query, limit=limit),
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(list[str], payload)
+
+
+def get_methylation_sites(
+    methylation_sites: Sequence[str],
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> dict[str, list[str]]:
+    """Return current EPIC 2.0 names for methylation site identifiers.
+
+    :param methylation_sites: Illumina methylation site names or identifiers.
+    :param base_url: Base URL of the Modulector API.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :return: Mapping from each requested identifier to matching EPIC 2.0 site
+        names.
+    """
+
+    payload = get_simple_response(
+        _build_url(base_url, "methylation-sites"),
+        method="POST",
+        json={"methylation_sites": list(methylation_sites)},
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(dict[str, list[str]], payload)
+
+
+def get_methylation_site_genes(
+    methylation_sites: Sequence[str],
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> dict[str, list[str]]:
+    """Return genes associated with methylation site identifiers.
+
+    :param methylation_sites: Illumina methylation site names or identifiers.
+    :param base_url: Base URL of the Modulector API.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :return: Mapping from each requested identifier to associated genes.
+    """
+
+    payload = get_simple_response(
+        _build_url(base_url, "methylation-sites-genes"),
+        method="POST",
+        json={"methylation_sites": list(methylation_sites)},
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(dict[str, list[str]], payload)
+
+
+def get_methylation_details(
+    methylation_site: str,
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> MethylationDetailsResponse:
+    """Return details for one methylation site.
+
+    :param methylation_site: Methylation site name from the Infinium
+        MethylationEPIC 2.0 array.
+    :param base_url: Base URL of the Modulector API.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :return: Methylation site details, aliases, CpG island relations, and genes.
+    """
+
+    payload = get_simple_response(
+        _build_url(base_url, "methylation"),
+        params={"methylation_site": methylation_site},
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(MethylationDetailsResponse, payload)
+
+
+def get_diseases(
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    mirna: str | None = None,
+    search: str | None = None,
+    ordering: Ordering | None = None,
+    page: int | None = None,
+    page_size: int | None = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> PaginatedResponse[MirnaDisease]:
+    """Return miRNA and human disease association records.
+
+    :param base_url: Base URL of the Modulector API.
+    :param mirna: miRNA code or accession ID. If omitted, all records are
+        returned page by page.
+    :param search: Case-insensitive search term for disease names.
+    :param ordering: Ordering field or comma-separated fields. Prefix a field
+        with ``-`` for descending order.
+    :param page: Page number to request.
+    :param page_size: Number of records per page.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :return: Paginated miRNA disease association records.
+    """
+
+    params = _request_params(
+        mirna=mirna,
+        search=search,
+        ordering=_format_ordering(ordering),
+    )
+    response = get_paginated_response(
+        _build_url(base_url, "diseases"),
+        params=params,
+        page=page,
+        page_size=page_size,
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(PaginatedResponse[MirnaDisease], response)
+
+
+def get_drugs(
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    mirna: str | None = None,
+    fda_approved: bool | None = None,
+    search: str | None = None,
+    ordering: Ordering | None = None,
+    page: int | None = None,
+    page_size: int | None = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> PaginatedResponse[MirnaDrug]:
+    """Return drug or small molecule records affecting miRNA expression.
+
+    :param base_url: Base URL of the Modulector API.
+    :param mirna: miRNA code or accession ID. If omitted, all records are
+        returned page by page.
+    :param fda_approved: Optional FDA approval filter.
+    :param search: Case-insensitive search term for condition, small molecule,
+        and expression pattern fields.
+    :param ordering: Ordering field or comma-separated fields. Prefix a field
+        with ``-`` for descending order.
+    :param page: Page number to request.
+    :param page_size: Number of records per page.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :return: Paginated miRNA drug association records.
+    """
+
+    params = _request_params(
+        mirna=mirna,
+        fda_approved=_bool_param(fda_approved),
+        search=search,
+        ordering=_format_ordering(ordering),
+    )
+    response = get_paginated_response(
+        _build_url(base_url, "drugs"),
+        params=params,
+        page=page,
+        page_size=page_size,
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(PaginatedResponse[MirnaDrug], response)
+
+
+def subscribe_pubmeds(
+    mirna: str,
+    email: str,
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    gene: str | None = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> SubscribePubmedsResponse:
+    """Subscribe an email address to PubMed news for a miRNA.
+
+    :param mirna: miRNA code or accession ID.
+    :param email: Email address to subscribe.
+    :param base_url: Base URL of the Modulector API.
+    :param gene: Optional gene symbol filter for the subscription.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :return: Subscription token response.
+    """
+
+    payload = get_simple_response(
+        _build_url(base_url, "subscribe-pubmeds"),
+        params=_request_params(mirna=mirna, email=email, gene=gene),
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(SubscribePubmedsResponse, payload)
+
+
+def unsubscribe_pubmeds(
+    token: str,
+    *,
+    base_url: str = MODULECTOR_API_BASE_URL,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> str:
+    """Unsubscribe from PubMed news.
+
+    :param token: Subscription token returned by ``subscribe_pubmeds``.
+    :param base_url: Base URL of the Modulector API.
+    :param headers: Optional HTTP headers.
+    :param timeout: Request timeout in seconds.
+    :param session: Optional ``requests.Session`` to use for the request.
+    :return: API confirmation message.
+    """
+
+    payload = get_simple_response(
+        _build_url(base_url, "unsubscribe-pubmeds"),
+        params={"token": token},
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return cast(str, payload)
+
+
+def _build_url(base_url: str, endpoint: str) -> str:
+    """Build an absolute endpoint URL with a trailing slash.
+
+    :param base_url: Base URL of the Modulector API.
+    :param endpoint: Endpoint path with or without leading or trailing slashes.
+    :return: Absolute URL for the endpoint.
+    """
+
+    return f"{base_url.rstrip('/')}/{endpoint.strip('/')}/"
+
+
+def _request_params(**params: Any) -> dict[str, Any]:
+    """Return request parameters without ``None`` values.
+
+    :param params: Query parameters keyed by API parameter name.
+    :return: A dictionary containing only parameters with non-``None`` values.
+    """
+
+    return {key: value for key, value in params.items() if value is not None}
+
+
+def _bool_param(value: bool | None) -> str | None:
+    """Convert an optional boolean to the API's lowercase string form.
+
+    :param value: Boolean value to convert.
+    :return: ``"true"``, ``"false"``, or ``None``.
+    """
+
+    if value is None:
+        return None
+    return "true" if value else "false"
+
+
+def _format_ordering(ordering: Ordering | None) -> str | None:
+    """Format an ordering value for Django REST Framework query parameters.
+
+    :param ordering: A comma-separated ordering string or a sequence of ordering
+        fields.
+    :return: A comma-separated ordering string, or ``None``.
+    """
+
+    if ordering is None:
+        return None
+    if isinstance(ordering, str):
+        return ordering
+
+    ordering_fields = [field for field in ordering if field]
+    if not ordering_fields:
+        return None
+    return ",".join(ordering_fields)
+
+
+def _validate_limit(limit: int | None) -> None:
+    """Validate finder service limit parameters.
+
+    :param limit: Limit value to validate.
+    :raises ValueError: If ``limit`` is outside the API's accepted range.
+    :return: ``None``.
+    """
+
+    if limit is not None and not 1 <= limit <= FINDER_LIMIT_MAX:
+        raise ValueError(f"limit must be between 1 and {FINDER_LIMIT_MAX}")
+
+
+__all__ = [
+    "API_BASE_URL",
+    "MODULECTOR_API_BASE_URL",
+    "MethylationDetailsResponse",
+    "MirnaAlias",
+    "MirnaDetailsResponse",
+    "MirnaDisease",
+    "MirnaDrug",
+    "MirnaTargetInteraction",
+    "SourceLink",
+    "SubscribePubmedsResponse",
+    "UcscCpgIsland",
+    "find_methylation_sites",
+    "find_mirna_codes",
+    "get_diseases",
+    "get_drugs",
+    "get_methylation_details",
+    "get_methylation_site_genes",
+    "get_methylation_sites",
+    "get_mirna_aliases",
+    "get_mirna_codes",
+    "get_mirna_details",
+    "get_mirna_target_interactions",
+    "subscribe_pubmeds",
+    "unsubscribe_pubmeds",
+]

modulector_sdk/utils.py

@@ -0,0 +1,237 @@
+"""Utilities for calling Modulector API endpoints.
+
+The public API returns either a plain JSON payload or a paginated payload with
+``count``, ``next``, ``previous``, and ``results`` fields.
+"""
+
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+import requests
+
+JSON = dict[str, Any] | list[Any] | str | int | float | bool | None
+Params = Mapping[str, Any] | None
+Headers = Mapping[str, str] | None
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class PaginatedResponse(Generic[T]):
+    """Representation of a Modulector paginated response."""
+
+    count: int
+    next: str | None
+    previous: str | None
+    results: list[T]
+
+
+def request_url(
+    url: str,
+    *,
+    method: str = "GET",
+    params: Params = None,
+    json: Any = None,
+    data: Any = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> JSON:
+    """Make an HTTP request and return the decoded JSON response.
+
+    HTTP errors are raised with ``requests.Response.raise_for_status()``.
+    JSON decoding errors are propagated from ``requests``.
+    """
+
+    client = session or requests
+    response = client.request(
+        method.upper(),
+        url,
+        params=params,
+        json=json,
+        data=data,
+        headers=headers,
+        timeout=timeout,
+    )
+    response.raise_for_status()
+    return response.json()
+
+
+def get_simple_response(
+    url: str,
+    *,
+    method: str = "GET",
+    params: Params = None,
+    json: Any = None,
+    data: Any = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> JSON:
+    """Return a non-paginated JSON response from an API endpoint."""
+
+    return request_url(
+        url,
+        method=method,
+        params=params,
+        json=json,
+        data=data,
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+
+
+def get_paginated_response(
+    url: str,
+    *,
+    method: str = "GET",
+    params: Params = None,
+    page: int | None = None,
+    page_size: int | None = None,
+    json: Any = None,
+    data: Any = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> PaginatedResponse[Any]:
+    """Return one page from an endpoint using Modulector pagination."""
+
+    request_params = _with_pagination_params(params, page=page, page_size=page_size)
+    payload = request_url(
+        url,
+        method=method,
+        params=request_params,
+        json=json,
+        data=data,
+        headers=headers,
+        timeout=timeout,
+        session=session,
+    )
+    return _parse_paginated_response(payload)
+
+
+def iter_paginated_results(
+    url: str,
+    *,
+    method: str = "GET",
+    params: Params = None,
+    page_size: int | None = None,
+    max_pages: int | None = None,
+    json: Any = None,
+    data: Any = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> Iterator[Any]:
+    """Yield every result by following each paginated response's ``next`` URL."""
+
+    if max_pages is not None and max_pages < 1:
+        raise ValueError("max_pages must be greater than 0")
+
+    next_url: str | None = url
+    request_params = _with_pagination_params(params, page=None, page_size=page_size)
+    pages_read = 0
+
+    while next_url is not None:
+        page = get_paginated_response(
+            next_url,
+            method=method,
+            params=request_params,
+            json=json,
+            data=data,
+            headers=headers,
+            timeout=timeout,
+            session=session,
+        )
+        yield from page.results
+
+        pages_read += 1
+        if max_pages is not None and pages_read >= max_pages:
+            break
+
+        next_url = page.next
+        request_params = None
+
+
+def get_all_paginated_results(
+    url: str,
+    *,
+    method: str = "GET",
+    params: Params = None,
+    page_size: int | None = None,
+    max_pages: int | None = None,
+    json: Any = None,
+    data: Any = None,
+    headers: Headers = None,
+    timeout: float = 30.0,
+    session: requests.Session | None = None,
+) -> list[Any]:
+    """Return all results from a paginated endpoint as a list."""
+
+    return list(
+        iter_paginated_results(
+            url,
+            method=method,
+            params=params,
+            page_size=page_size,
+            max_pages=max_pages,
+            json=json,
+            data=data,
+            headers=headers,
+            timeout=timeout,
+            session=session,
+        )
+    )
+
+
+def _with_pagination_params(
+    params: Params,
+    *,
+    page: int | None,
+    page_size: int | None,
+) -> dict[str, Any] | None:
+    if page is not None and page < 1:
+        raise ValueError("page must be greater than 0")
+    if page_size is not None and not 1 <= page_size <= 1000:
+        raise ValueError("page_size must be between 1 and 1000")
+
+    if params is None and page is None and page_size is None:
+        return None
+
+    request_params = dict(params or {})
+    if page is not None:
+        request_params["page"] = page
+    if page_size is not None:
+        request_params["page_size"] = page_size
+    return request_params
+
+
+def _parse_paginated_response(payload: JSON) -> PaginatedResponse[Any]:
+    if not isinstance(payload, Mapping):
+        raise ValueError("paginated response must be a JSON object")
+
+    missing_fields = {"count", "next", "previous", "results"} - payload.keys()
+    if missing_fields:
+        missing = ", ".join(sorted(missing_fields))
+        raise ValueError(f"paginated response is missing fields: {missing}")
+
+    results = payload["results"]
+    if not isinstance(results, list):
+        raise ValueError("paginated response field 'results' must be a list")
+
+    next_url = payload["next"]
+    previous_url = payload["previous"]
+    if next_url is not None and not isinstance(next_url, str):
+        raise ValueError("paginated response field 'next' must be a string or null")
+    if previous_url is not None and not isinstance(previous_url, str):
+        raise ValueError(
+            "paginated response field 'previous' must be a string or null"
+        )
+
+    return PaginatedResponse(
+        count=int(payload["count"]),
+        next=next_url,
+        previous=previous_url,
+        results=results,
+    )

modulector_sdk-2.3.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: modulector-sdk
+Version: 2.3.0
+Summary: Typed Python SDK for the Modulector API.
+Author: omicsdatascience
+License-Expression: MIT
+Project-URL: API, https://modulector.multiomix.org/
+Project-URL: Homepage, https://modulector.multiomix.org/
+Project-URL: Issues, https://github.com/omics-datascience/modulector/issues
+Project-URL: Repository, https://github.com/omics-datascience/modulector
+Keywords: api-client,bioinformatics,methylation,mirna,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests==2.31.0
+Dynamic: license-file
+
+# Modulector SDK
+
+Typed Python SDK for the Modulector API. The package contains client helpers for
+querying miRNA target interactions, miRNA aliases, methylation sites, disease
+associations, drug associations, and PubMed subscriptions without installing the
+Django backend dependencies.
+
+## Installation
+
+```bash
+pip install modulector-sdk
+```
+
+## Usage
+
+```python
+from modulector_sdk import get_mirna_details, get_mirna_target_interactions
+
+details = get_mirna_details("hsa-miR-21-5p")
+interactions = get_mirna_target_interactions(
+    mirna="hsa-miR-21-5p",
+    gene="PTEN",
+    include_pubmeds=True,
+)
+```
+
+Set `MODULECTOR_API_BASE_URL` to target a different Modulector deployment:
+
+```bash
+MODULECTOR_API_BASE_URL=https://your-modulector.example.org python script.py
+```
+
+Every service function also accepts a `base_url` keyword argument for
+per-request overrides.
+
+## Development
+
+Build this SDK from the `sdk/` directory:
+
+```bash
+uv build
+```
+
+The generated source distribution and wheel are written to `sdk/dist/`.

modulector_sdk-2.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+modulector_sdk/__init__.py,sha256=Wd7CZv_8iYI5az_YoJlVsi2O5y_6SdvCSuPfQPHlpaI,1692
+modulector_sdk/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+modulector_sdk/services.py,sha256=XQus8xrRUv6NSjIIm28QGAA7foqCJA2c8c1t6VTWplg,24516
+modulector_sdk/utils.py,sha256=0R8L_zXcdx9canOQj30SBDOQUyMIELWz0ksJn2S1Og0,6614
+modulector_sdk-2.3.0.dist-info/licenses/LICENSE,sha256=rXNUFK1gna2amPRzSGZWLgKN7iM1pGsFBHJFT09MkOE,1094
+modulector_sdk-2.3.0.dist-info/METADATA,sha256=mCuaZ8QQY61eLfLed66sH1ryNOk-3e4B3DjK7i4kais,2331
+modulector_sdk-2.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+modulector_sdk-2.3.0.dist-info/top_level.txt,sha256=F-TA89bFrqt1LGOVZZHuVMknvKWvAU70aTzN-Vj1pcA,15
+modulector_sdk-2.3.0.dist-info/RECORD,,

modulector_sdk-2.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

modulector_sdk-2.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 omicsdatascience
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modulector_sdk-2.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+modulector_sdk