API Client Reference

Client

Client(api_key=None, base_url=None, timeout=10.0)

An asynchronous client for the Lean Explore backend API.

This client handles making HTTP requests to the API base URL, optionally authenticating with an API key, and parsing responses into Pydantic models.

The client supports three modes of operation: 1. API key only: Uses the default production API base URL with authentication. 2. Base URL only: Uses a custom base URL without authentication (for local servers). 3. Both API key and base URL: Uses a custom base URL with authentication.

Attributes:

Name	Type	Description
api_key	Optional[str]	The API key used for authenticating requests, if provided.
timeout	float	The timeout for HTTP requests in seconds.
base_url	str	The base URL for the API.

Initializes the API Client.

Parameters:

Name	Type	Description	Default
api_key	Optional[str]	Optional API key for authentication. If provided, requests will include an Authorization header. If not provided, requests will be made without authentication.	None
base_url	Optional[str]	Optional custom base URL for the API. If not provided, defaults to the production API base URL.	None
timeout	float	Default timeout for HTTP requests in seconds.	10.0

Source code in src/lean_explore/api/client.py

def __init__(
    self,
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    timeout: float = 10.0,
):
    """Initializes the API Client.

    Args:
        api_key: Optional API key for authentication. If provided, requests
            will include an Authorization header. If not provided, requests
            will be made without authentication.
        base_url: Optional custom base URL for the API. If not provided,
            defaults to the production API base URL.
        timeout: Default timeout for HTTP requests in seconds.
    """
    self.base_url: str = base_url if base_url is not None else _DEFAULT_API_BASE_URL
    self.api_key: Optional[str] = api_key
    self.timeout: float = timeout
    if api_key is not None:
        self._headers: dict = {"Authorization": f"Bearer {self.api_key}"}
    else:
        self._headers: dict = {}

Functions

get_by_id async

get_by_id(group_id: int) -> Optional[APISearchResultItem]

get_by_id(group_id: List[int]) -> List[Optional[APISearchResultItem]]

get_by_id(group_id)

Retrieves a specific statement group by its unique ID via the API.

Parameters:

Name	Type	Description	Default
group_id	Union[int, List[int]]	The unique identifier of the statement group, or a list of IDs.	required

Returns:

Type	Description
Union[Optional[APISearchResultItem], List[Optional[APISearchResultItem]]]	An APISearchResultItem object if a single ID was found, None if it was
Union[Optional[APISearchResultItem], List[Optional[APISearchResultItem]]]	not found. A list of Optional[APISearchResultItem] if a list of
Union[Optional[APISearchResultItem], List[Optional[APISearchResultItem]]]	IDs was provided.

Raises:

Type	Description
HTTPStatusError	If the API returns an HTTP error status other than 404 (e.g., 401, 403, 5xx).
RequestError	For network-related issues or other request errors.

Source code in src/lean_explore/api/client.py

async def get_by_id(
    self, group_id: Union[int, List[int]]
) -> Union[Optional[APISearchResultItem], List[Optional[APISearchResultItem]]]:
    """Retrieves a specific statement group by its unique ID via the API.

    Args:
        group_id: The unique identifier of the statement group, or a list of IDs.

    Returns:
        An APISearchResultItem object if a single ID was found, None if it was
        not found. A list of Optional[APISearchResultItem] if a list of
        IDs was provided.

    Raises:
        httpx.HTTPStatusError: If the API returns an HTTP error status
                            other than 404 (e.g., 401, 403, 5xx).
        httpx.RequestError: For network-related issues or other request errors.
    """
    was_single_id = isinstance(group_id, int)
    group_ids = [group_id] if was_single_id else group_id

    async with httpx.AsyncClient(timeout=self.timeout) as client:
        tasks = [self._fetch_one_by_id(client, g_id) for g_id in group_ids]
        results = await asyncio.gather(*tasks)

    if was_single_id:
        return results[0]
    return results

get_dependencies async

get_dependencies(group_id: int) -> Optional[APICitationsResponse]

get_dependencies(group_id: List[int]) -> List[Optional[APICitationsResponse]]

get_dependencies(group_id)

Retrieves the dependencies (citations) for a specific statement group.

This method fetches the statement groups that the specified 'group_id'(s) depend on (i.e., cite).

Parameters:

Name	Type	Description	Default
group_id	Union[int, List[int]]	The unique identifier of the statement group, or a list of IDs.	required

Returns:

Type	Description
Union[Optional[APICitationsResponse], List[Optional[APICitationsResponse]]]	An APICitationsResponse object if a single ID was provided. A list
Union[Optional[APICitationsResponse], List[Optional[APICitationsResponse]]]	of Optional[APICitationsResponse] if a list of IDs was provided.
Union[Optional[APICitationsResponse], List[Optional[APICitationsResponse]]]	None is returned for IDs that are not found.

Raises:

Type	Description
HTTPStatusError	If the API returns an HTTP error status other than 404 (e.g., 401, 403, 5xx).
RequestError	For network-related issues or other request errors.

Source code in src/lean_explore/api/client.py

async def get_dependencies(
    self, group_id: Union[int, List[int]]
) -> Union[Optional[APICitationsResponse], List[Optional[APICitationsResponse]]]:
    """Retrieves the dependencies (citations) for a specific statement group.

    This method fetches the statement groups that the specified 'group_id'(s)
    depend on (i.e., cite).

    Args:
        group_id: The unique identifier of the statement group, or a list of IDs.

    Returns:
        An APICitationsResponse object if a single ID was provided. A list
        of Optional[APICitationsResponse] if a list of IDs was provided.
        None is returned for IDs that are not found.

    Raises:
        httpx.HTTPStatusError: If the API returns an HTTP error status
                            other than 404 (e.g., 401, 403, 5xx).
        httpx.RequestError: For network-related issues or other request errors.
    """
    was_single_id = isinstance(group_id, int)
    group_ids = [group_id] if was_single_id else group_id

    async with httpx.AsyncClient(timeout=self.timeout) as client:
        tasks = [self._fetch_one_dependencies(client, g_id) for g_id in group_ids]
        results = await asyncio.gather(*tasks)

    if was_single_id:
        return results[0]
    return results

search async

search(query: str, package_filters: Optional[List[str]] = None) -> APISearchResponse

search(query: List[str], package_filters: Optional[List[str]] = None) -> List[APISearchResponse]

search(query, package_filters=None)

Performs a search for statement groups via the API.

This method can handle a single query string or a list of query strings. When a list is provided, requests are sent concurrently.

Parameters:

Name	Type	Description	Default
query	Union[str, List[str]]	The search query string or a list of query strings.	required
package_filters	Optional[List[str]]	An optional list of package names to filter the search by. This filter is applied to all queries.	None

Returns:

Type	Description
Union[APISearchResponse, List[APISearchResponse]]	An APISearchResponse object if a single query was provided, or a
Union[APISearchResponse, List[APISearchResponse]]	list of APISearchResponse objects if a list of queries was provided.

Raises:

Type	Description
HTTPStatusError	If the API returns an HTTP error status (4xx or 5xx).
RequestError	For network-related issues or other request errors.

Source code in src/lean_explore/api/client.py

async def search(
    self,
    query: Union[str, List[str]],
    package_filters: Optional[List[str]] = None,
) -> Union[APISearchResponse, List[APISearchResponse]]:
    """Performs a search for statement groups via the API.

    This method can handle a single query string or a list of query strings.
    When a list is provided, requests are sent concurrently.

    Args:
        query: The search query string or a list of query strings.
        package_filters: An optional list of package names to filter the
            search by. This filter is applied to all queries.

    Returns:
        An APISearchResponse object if a single query was provided, or a
        list of APISearchResponse objects if a list of queries was provided.

    Raises:
        httpx.HTTPStatusError: If the API returns an HTTP error status (4xx or 5xx).
        httpx.RequestError: For network-related issues or other request errors.
    """
    was_single_query = isinstance(query, str)
    queries = [query] if was_single_query else query

    async with httpx.AsyncClient(timeout=self.timeout) as client:
        tasks = [
            self._fetch_one_search(client, q, package_filters) for q in queries
        ]
        results = await asyncio.gather(*tasks)

    if was_single_query:
        return results[0]
    return results