tooluniverse.rcsb_pdb_tool module

class tooluniverse.rcsb_pdb_tool.DataQuery(input_type: str, input_ids: List[str] | Dict[str, str] | Dict[str, List[str]] | List[int], return_data_list: List[str], add_rcsb_id: bool = True, suppress_autocomplete_warning: bool = False)

Bases: object

Class for Data API queries.

__init__(input_type: str, input_ids: List[str] | Dict[str, str] | Dict[str, List[str]] | List[int], return_data_list: List[str], add_rcsb_id: bool = True, suppress_autocomplete_warning: bool = False)

Query object for Data API requests.

Parameters:

• input_type (str) – query input type (e.g., “entry”, “polymer_entity_instance”, etc.)

• input_ids (list or dict) – list (or singular dict) of ids for which to request information (e.g., [“4HHB”, “2LGI”])

• return_data_list (list) – list of data to return (field names) (e.g., [“rcsb_id”, “exptl.method”])

• add_rcsb_id (bool, optional) – whether to automatically add <input_type>.rcsb_id to queries. Defaults to True.

get_input_ids() → List[str]

get input_ids used to make query

Returns:

input id list or dictionary

Return type:

Union[List[str], Dict[str, List[str]], Dict[str, str]]

get_input_type() → str

get input_type used to make query

Returns:

input_type

(e.g., “entry”, “polymer_entity_instance”, etc.)

Return type:

str

get_return_data_list() → List[str]

get return_data_list used to make query

Returns:

return_data_list

(e.g., [“rcsb_id”, “exptl.method”])

Return type:

List[str]

get_query() → str

get GraphQL query

Returns:

query in GraphQL syntax

Return type:

str

get_response() → None | Dict[str, Any]

get JSON response to executed query

Returns:

JSON object

Return type:

Dict[str, Any]

get_editor_link() → str

get url to interactive GraphiQL editor

Returns:

GraphiQL url

Return type:

str

exec(batch_size: int | None = None, progress_bar: bool = False, max_retries: int | None = None, retry_backoff: int | None = None, max_concurrency: int | None = None) → Dict[str, Any]

POST a GraphQL query and get response concurrently using httpx

Parameters:

• batch_size (int, optional) – size of ID batches to split up input ID list into and perform sub-requests. Defaults to config.DATA_API_BATCH_ID_SIZE.

• progress_bar (bool, optional) – display a progress bar when executing query. Defaults to False.

• max_retries (int, optional) – maximum number of retries to attempt for each individual sub-request (in case of timeouts or errors). Defaults to config.MAX_RETRIES.

• retry_backoff (int, optional) – delay in seconds to wait for each retry. Defaults to config.RETRY_BACKOFF.

• max_concurrency (int, optional) – maximum number of sub-requests to run concurrently. Defaults to config.DATA_API_MAX_CONCURRENT_REQUESTS.

Returns:

JSON object containing the compiled query result (aggregated across all sub-requests)

Return type:

Dict[str, Any]

class tooluniverse.rcsb_pdb_tool.BaseTool(tool_config)

Bases: object

__init__(tool_config)

classmethod get_default_config_file()

Get the path to the default configuration file for this tool type.

This method uses a robust path resolution strategy that works across different installation scenarios:

1. Installed packages: Uses importlib.resources for proper package resource access

2. Development mode: Falls back to file-based path resolution

3. Legacy Python: Handles importlib.resources and importlib_resources

Override this method in subclasses to specify a custom defaults file.

Returns:

Path or resource object pointing to the defaults file

classmethod load_defaults_from_file()

Load defaults from the configuration file

run(arguments=None)

Execute the tool.

The default BaseTool implementation accepts an optional arguments mapping to align with most concrete tool implementations which expect a dictionary of inputs.

check_function_call(function_call_json)

get_required_parameters()

Retrieve required parameters from the endpoint definition. Returns: list: List of required parameters for the given endpoint.

tooluniverse.rcsb_pdb_tool.register_tool(tool_type_name=None, config=None)

Decorator to automatically register tool classes and their configs.

Usage:

@register_tool(‘CustomToolName’, config={…}) class MyTool:

pass

class tooluniverse.rcsb_pdb_tool.RCSBTool(tool_config)

Bases: BaseTool

__init__(tool_config)

validate_params(params: dict)

prepare_input_ids(params: dict)

run(params: dict)

Execute the tool.

The default BaseTool implementation accepts an optional arguments mapping to align with most concrete tool implementations which expect a dictionary of inputs.