dnastack-client-library 3.1.139__py3-none-any.whl → 3.1.144__py3-none-any.whl

dnastack/__main__.py

@@ -10,6 +10,7 @@ from dnastack.cli.commands.config import config_command_group
 from dnastack.cli.commands.config.contexts import contexts_command_group, ContextCommandHandler
 from dnastack.cli.commands.dataconnect import data_connect_command_group
 from dnastack.cli.commands.drs import drs_command_group
+from dnastack.cli.commands.explorer.commands import explorer_command_group
 from dnastack.cli.commands.publisher import publisher_command_group
 from dnastack.cli.commands.workbench import workbench_command_group
 from dnastack.cli.core.command import formatted_command
@@ -106,6 +107,9 @@ dnastack.add_command(publisher_command_group)
 # noinspection PyTypeChecker
 dnastack.add_command(workbench_command_group)
 
+# noinspection PyTypeChecker
+dnastack.add_command(explorer_command_group)
+
 
 if __name__ == "__main__":
     dnastack.main(prog_name=APP_NAME)

dnastack/cli/commands/explorer/commands.py

@@ -0,0 +1,21 @@
+from dnastack.cli.commands.explorer.questions.commands import init_questions_commands
+from dnastack.cli.core.group import formatted_group
+
+
+@formatted_group("explorer")
+def explorer_command_group():
+    """Commands for working with Explorer federated questions"""
+    pass
+
+
+@formatted_group("questions")
+def questions_command_group():
+    """Commands for working with federated questions"""
+    pass
+
+
+# Initialize questions subcommands
+init_questions_commands(questions_command_group)
+
+# Register questions group under explorer
+explorer_command_group.add_command(questions_command_group)

dnastack/cli/commands/explorer/questions/commands.py

@@ -0,0 +1,168 @@
+from typing import Optional
+
+import click
+from click import Group
+
+from dnastack.cli.commands.explorer.questions.utils import (
+    get_explorer_client,
+    parse_collections_argument,
+    validate_question_parameters,
+    handle_question_results_output
+)
+from dnastack.cli.core.command import formatted_command
+from dnastack.cli.core.command_spec import ArgumentSpec, CONTEXT_ARG, SINGLE_ENDPOINT_ID_ARG, ArgumentType, RESOURCE_OUTPUT_ARG, DATA_OUTPUT_ARG
+from dnastack.cli.helpers.iterator_printer import show_iterator
+from dnastack.common.json_argument_parser import JsonLike, parse_and_merge_arguments
+from dnastack.common.logger import get_logger
+from dnastack.common.tracing import Span
+
+logger = get_logger(__name__)
+
+
+def init_questions_commands(group: Group):
+    @formatted_command(
+        group=group,
+        name='list',
+        specs=[
+            RESOURCE_OUTPUT_ARG,
+            CONTEXT_ARG,
+            SINGLE_ENDPOINT_ID_ARG,
+        ]
+    )
+    def list_questions(output: str, context: Optional[str], endpoint_id: Optional[str]):
+        """List all available federated questions"""
+        trace = Span()
+        client = get_explorer_client(context=context, endpoint_id=endpoint_id, trace=trace)
+        questions_iter = client.list_federated_questions(trace=trace)
+        
+        # Convert to list and pass to show_iterator
+        questions = list(questions_iter)
+        
+        # For JSON/YAML output, show the raw question objects
+        # No need for table formatting as show_iterator handles it
+        show_iterator(
+            output_format=output,
+            iterator=questions,
+            transform=lambda q: q.dict()
+        )
+
+    @formatted_command(
+        group=group,
+        name='describe',
+        specs=[
+            ArgumentSpec(
+                name='question_id',
+                arg_type=ArgumentType.POSITIONAL,
+                help='The ID of the question to describe',
+                required=True
+            ),
+            RESOURCE_OUTPUT_ARG,
+            CONTEXT_ARG,
+            SINGLE_ENDPOINT_ID_ARG,
+        ]
+    )
+    def describe_question(question_id: str, output: str, context: Optional[str], endpoint_id: Optional[str]):
+        """Get detailed information about a federated question"""
+        trace = Span()
+        client = get_explorer_client(context=context, endpoint_id=endpoint_id, trace=trace)
+        question = client.describe_federated_question(question_id, trace=trace)
+        
+        # Use show_iterator for consistent output handling
+        show_iterator(
+            output_format=output,
+            iterator=[question],  # Single item as list
+            transform=lambda q: q.dict()
+        )
+
+    @formatted_command(
+        group=group,
+        name='ask',
+        specs=[
+            ArgumentSpec(
+                name='question_name',
+                arg_names=['--question-name'],
+                help='The name/ID of the question to ask',
+                required=True
+            ),
+            ArgumentSpec(
+                name='args',
+                arg_names=['--param'],
+                help='Question parameters in key=value format (can be used multiple times)',
+                type=JsonLike,
+                multiple=True
+            ),
+            ArgumentSpec(
+                name='collections',
+                arg_names=['--collections'],
+                help='Comma-separated list of collection IDs to query (default: all collections for the question)'
+            ),
+            ArgumentSpec(
+                name='output_file',
+                arg_names=['--output-file'],
+                help='Output file path for results'
+            ),
+            DATA_OUTPUT_ARG,
+            CONTEXT_ARG,
+            SINGLE_ENDPOINT_ID_ARG,
+        ]
+    )
+    def ask_question(
+        question_name: str,
+        args: tuple,
+        collections: Optional[str],
+        output_file: Optional[str],
+        output: str,
+        context: Optional[str],
+        endpoint_id: Optional[str]
+    ):
+        """Ask a federated question with the provided parameters"""
+        trace = Span()
+        client = get_explorer_client(context=context, endpoint_id=endpoint_id, trace=trace)
+        
+        # Parse collections if provided
+        collection_ids = parse_collections_argument(collections)
+        
+        # Parse arguments
+        inputs = {}
+        if args:
+            # When multiple=True with JsonLike, we get a tuple of JsonLike objects
+            if isinstance(args, tuple):
+                for arg in args:
+                    parsed_args = arg.parsed_value() if hasattr(arg, 'parsed_value') else parse_and_merge_arguments(arg)
+                    inputs.update(parsed_args)
+            else:
+                # Single JsonLike object
+                parsed_args = args.parsed_value() if hasattr(args, 'parsed_value') else parse_and_merge_arguments(args)
+                inputs.update(parsed_args)
+        
+        # Get question details for validation
+        question = client.describe_federated_question(question_name, trace=trace)
+        
+        # Validate parameters
+        try:
+            inputs = validate_question_parameters(inputs, question)
+        except ValueError as e:
+            click.echo(f"Error: {e}", err=True)
+            raise click.Abort()
+        
+        if collection_ids is not None:
+            # Validate collection IDs exist in question
+            available_ids = {col.id for col in question.collections}
+            invalid_ids = [cid for cid in collection_ids if cid not in available_ids]
+            if invalid_ids:
+                click.echo(f"Error: Invalid collection IDs for this question: {', '.join(invalid_ids)}", err=True)
+                raise click.Abort()
+        
+        # Execute the question
+        results_iter = client.ask_federated_question(
+            question_id=question_name,
+            inputs=inputs,
+            collections=collection_ids,
+            trace=trace
+        )
+        
+        # Collect results
+        results = list(results_iter)
+        
+        # Output results
+        handle_question_results_output(results, output_file, output)

dnastack/cli/commands/explorer/questions/tables.py

@@ -0,0 +1,142 @@
+from typing import List, Dict, Any
+from dnastack.client.explorer.models import FederatedQuestion
+
+
+def format_question_list_table(questions: List[FederatedQuestion]) -> List[Dict[str, Any]]:
+    """
+    Format a list of federated questions for table display.
+    
+    Args:
+        questions: List of FederatedQuestion objects
+        
+    Returns:
+        List[Dict[str, Any]]: Formatted table data
+    """
+    table_data = []
+    
+    for question in questions:
+        row = {
+            'ID': question.id,
+            'Name': question.name,
+            'Description': question.description,
+            'Parameters': len(question.params),
+            'Collections': len(question.collections),
+            'Required Params': len([p for p in question.params if p.required])
+        }
+        table_data.append(row)
+    
+    return table_data
+
+
+def format_question_detail_table(question: FederatedQuestion) -> Dict[str, Any]:
+    """
+    Format a single federated question for detailed display.
+    
+    Args:
+        question: FederatedQuestion object
+        
+    Returns:
+        Dict[str, Any]: Formatted question details
+    """
+    # Format parameters
+    params_info = []
+    for param in question.params:
+        param_info = {
+            'Name': param.name,
+            'Type': param.input_type,
+            'Required': 'Yes' if param.required else 'No',
+            'Description': param.description or '',
+            'Default': param.default_value or ''
+        }
+        
+        # Add dropdown values if available
+        if param.values and param.input_subtype == "DROPDOWN":
+            values_list = param.values.split('\n')
+            param_info['Choices'] = ', '.join(values_list[:3]) + ('...' if len(values_list) > 3 else '')
+        
+        params_info.append(param_info)
+    
+    # Format collections
+    collections_info = []
+    for col in question.collections:
+        col_info = {
+            'ID': col.id,
+            'Name': col.name,
+            'Slug': col.slug,
+            'Question ID': col.question_id
+        }
+        collections_info.append(col_info)
+    
+    return {
+        'question': {
+            'ID': question.id,
+            'Name': question.name,
+            'Description': question.description
+        },
+        'parameters': params_info,
+        'collections': collections_info
+    }
+
+
+def format_question_results_table(results: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """
+    Format question query results for table display.
+    
+    Args:
+        results: List of result dictionaries
+        
+    Returns:
+        List[Dict[str, Any]]: Formatted table data
+    """
+    if not results:
+        return []
+    
+    # For complex nested results, we'll flatten them
+    formatted_results = []
+    
+    for result in results:
+        # If result is already flat, use as-is
+        if all(not isinstance(v, (dict, list)) for v in result.values()):
+            formatted_results.append(result)
+        else:
+            # Flatten complex nested structures
+            flattened = _flatten_dict(result)
+            formatted_results.append(flattened)
+    
+    return formatted_results
+
+
+def _flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '.') -> Dict[str, Any]:
+    """
+    Flatten a nested dictionary.
+    
+    Args:
+        d: Dictionary to flatten
+        parent_key: Parent key prefix
+        sep: Separator for nested keys
+        
+    Returns:
+        Dict[str, Any]: Flattened dictionary
+    """
+    items = []
+    
+    for k, v in d.items():
+        new_key = f"{parent_key}{sep}{k}" if parent_key else k
+        
+        if isinstance(v, dict):
+            items.extend(_flatten_dict(v, new_key, sep=sep).items())
+        elif isinstance(v, list):
+            if v and isinstance(v[0], dict):
+                # For lists of dicts, create separate entries
+                for i, item in enumerate(v):
+                    if isinstance(item, dict):
+                        items.extend(_flatten_dict(item, f"{new_key}[{i}]", sep=sep).items())
+                    else:
+                        items.append((f"{new_key}[{i}]", item))
+            else:
+                # For simple lists, join with commas
+                items.append((new_key, ', '.join(str(x) for x in v)))
+        else:
+            items.append((new_key, v))
+    
+    return dict(items)

dnastack/cli/commands/explorer/questions/utils.py

@@ -0,0 +1,242 @@
+import csv
+import json
+import os
+from typing import Optional, Dict, Any, List
+
+import click
+from imagination import container
+
+from dnastack.client.explorer.client import ExplorerClient
+from dnastack.cli.helpers.client_factory import ConfigurationBasedClientFactory
+from dnastack.cli.helpers.exporter import normalize
+from dnastack.cli.helpers.iterator_printer import show_iterator
+from dnastack.common.tracing import Span
+
+
+def get_explorer_client(context: Optional[str] = None, 
+                       endpoint_id: Optional[str] = None,
+                       trace: Optional[Span] = None) -> ExplorerClient:
+    """
+    Get an Explorer client instance.
+    
+    Args:
+        context: Optional context name
+        endpoint_id: Optional endpoint ID
+        trace: Optional tracing span
+        
+    Returns:
+        ExplorerClient: Configured explorer client
+    """
+    factory: ConfigurationBasedClientFactory = container.get(ConfigurationBasedClientFactory)
+    return factory.get(ExplorerClient, context_name=context, endpoint_id=endpoint_id)
+
+
+def parse_collections_argument(collections_str: Optional[str]) -> Optional[List[str]]:
+    """
+    Parse a comma-separated collections string into a list.
+    
+    Args:
+        collections_str: Comma-separated collection IDs (e.g., "id1,id2,id3")
+        
+    Returns:
+        List[str] or None: List of collection IDs or None if input is None/empty
+    """
+    if not collections_str:
+        return None
+    
+    # Split by comma and strip whitespace
+    collections = [col.strip() for col in collections_str.split(',')]
+    # Filter out empty strings
+    return [col for col in collections if col]
+
+
+def format_question_parameters(params) -> str:
+    """
+    Format question parameters for display.
+    
+    Args:
+        params: List of QuestionParam objects
+        
+    Returns:
+        str: Formatted parameter description
+    """
+    if not params:
+        return "No parameters"
+    
+    lines = []
+    for param in params:
+        required_marker = " (required)" if param.required else " (optional)"
+        param_line = f"  {param.name}: {param.input_type}{required_marker}"
+        
+        if param.description:
+            param_line += f" - {param.description}"
+            
+        if param.default_value:
+            param_line += f" [default: {param.default_value}]"
+            
+        # Handle dropdown values
+        if param.values and param.input_subtype == "DROPDOWN":
+            values_list = param.values.split('\n')
+            if values_list:
+                param_line += f" [choices: {', '.join(values_list[:5])}{'...' if len(values_list) > 5 else ''}]"
+        
+        lines.append(param_line)
+    
+    return "\n".join(lines)
+
+
+def format_question_collections(collections) -> str:
+    """
+    Format question collections for display.
+    
+    Args:
+        collections: List of QuestionCollection objects
+        
+    Returns:
+        str: Formatted collections description
+    """
+    if not collections:
+        return "No collections"
+    
+    lines = []
+    for col in collections:
+        lines.append(f"  {col.name} ({col.slug}) - ID: {col.id}")
+    
+    return "\n".join(lines)
+
+
+def validate_question_parameters(inputs: Dict[str, str], question) -> Dict[str, str]:
+    """
+    Basic validation of question parameters.
+    
+    Args:
+        inputs: Dictionary of parameter values
+        question: FederatedQuestion object with parameter definitions
+        
+    Returns:
+        Dict[str, str]: Validated inputs
+        
+    Raises:
+        ValueError: If required parameters are missing
+    """
+    # Check for required parameters
+    required_params = [p.name for p in question.params if p.required]
+    missing_params = [p for p in required_params if p not in inputs]
+    
+    if missing_params:
+        raise ValueError(f"Missing required parameters: {', '.join(missing_params)}")
+    
+    return inputs
+
+
+def flatten_result_for_export(result: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Flatten a nested result dictionary for CSV/TSV export.
+    
+    Args:
+        result: Nested dictionary result
+        
+    Returns:
+        Dict[str, Any]: Flattened dictionary
+    """
+    flattened = {}
+    
+    def _flatten(obj, prefix=''):
+        if isinstance(obj, dict):
+            for key, value in obj.items():
+                new_key = f"{prefix}.{key}" if prefix else key
+                _flatten(value, new_key)
+        elif isinstance(obj, list):
+            for i, item in enumerate(obj):
+                new_key = f"{prefix}[{i}]" if prefix else f"item_{i}"
+                _flatten(item, new_key)
+        else:
+            flattened[prefix] = obj
+    
+    _flatten(result)
+    return flattened
+
+
+def handle_question_results_output(results: List[Dict[str, Any]], output_file: Optional[str], output_format: str):
+    """
+    Handle output of question results to file or stdout.
+    
+    Args:
+        results: List of result dictionaries
+        output_file: Optional file path to write to
+        output_format: Output format (json, csv, yaml, etc.)
+    """
+    if output_file:
+        write_results_to_file(results, output_file, output_format)
+        click.echo(f"Results written to {output_file}")
+    else:
+        # Use show_iterator for consistent output handling
+        show_iterator(
+            output_format=output_format,
+            iterator=results
+        )
+
+
+def write_results_to_file(results: List[Dict[str, Any]], output_file: str, output_format: str):
+    """
+    Write results to file in the specified format.
+    
+    Args:
+        results: List of result dictionaries
+        output_file: File path to write to
+        output_format: Output format (json, csv, yaml)
+    """
+    # Ensure output directory exists
+    output_dir = os.path.dirname(output_file)
+    if output_dir and not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+    
+    if output_format == 'json':
+        _write_json_results(results, output_file)
+    elif output_format == 'csv':
+        _write_csv_results(results, output_file)
+    elif output_format == 'yaml':
+        _write_yaml_results(results, output_file)
+
+
+def _write_json_results(results: List[Dict[str, Any]], output_file: str):
+    """Write results as JSON."""
+    with open(output_file, 'w') as f:
+        json.dump(results, f, indent=2, default=str)
+
+
+def _write_csv_results(results: List[Dict[str, Any]], output_file: str):
+    """Write results as CSV with flattened structure."""
+    # Flatten all results
+    flattened_results = [flatten_result_for_export(result) for result in results]
+    
+    if not flattened_results:
+        # Write empty file
+        with open(output_file, 'w') as f:
+            pass
+        return
+    
+    # Get all possible column headers
+    all_headers = set()
+    for result in flattened_results:
+        all_headers.update(result.keys())
+    
+    headers = sorted(all_headers)
+    
+    with open(output_file, 'w', newline='') as f:
+        writer = csv.DictWriter(f, fieldnames=headers)
+        writer.writeheader()
+        
+        for result in flattened_results:
+            # Fill missing keys with empty strings
+            row = {header: result.get(header, '') for header in headers}
+            writer.writerow(row)
+
+
+def _write_yaml_results(results: List[Dict[str, Any]], output_file: str):
+    """Write results as YAML."""
+    with open(output_file, 'w') as f:
+        normalized_results = [normalize(result) for result in results]
+        from yaml import dump as to_yaml_string, SafeDumper
+        yaml_content = to_yaml_string(normalized_results, Dumper=SafeDumper, sort_keys=False)
+        f.write(yaml_content)

dnastack/client/constants.py

@@ -5,6 +5,7 @@ from dnastack.client.collections.client import CollectionServiceClient
 from dnastack.client.data_connect import DataConnectClient
 from dnastack.client.datasources.client import DataSourceServiceClient
 from dnastack.client.drs import DrsClient
+from dnastack.client.explorer.client import ExplorerClient
 from dnastack.client.service_registry.client import ServiceRegistry
 from dnastack.client.workbench.ewes.client import EWesClient
 from dnastack.client.workbench.samples.client import SamplesClient
@@ -14,13 +15,13 @@ from dnastack.client.workbench.workflow.client import WorkflowClient
 
 # All known client classes
 ALL_SERVICE_CLIENT_CLASSES = (
-    CollectionServiceClient, DataConnectClient, DrsClient, ServiceRegistry, EWesClient, StorageClient, SamplesClient,
+    CollectionServiceClient, DataConnectClient, DrsClient, ExplorerClient, ServiceRegistry, EWesClient, StorageClient, SamplesClient,
     WorkflowClient,
     WorkbenchUserClient, DataSourceServiceClient)
 
 # All client classes for data access
 DATA_SERVICE_CLIENT_CLASSES = (
-    CollectionServiceClient, DataConnectClient, DrsClient, EWesClient, StorageClient, WorkflowClient,
+    CollectionServiceClient, DataConnectClient, DrsClient, ExplorerClient, EWesClient, StorageClient, WorkflowClient,
     WorkbenchUserClient, DataSourceServiceClient)
 
 # Type variable for the service client
@@ -33,6 +34,7 @@ SERVICE_CLIENT_CLASS = TypeVar('SERVICE_CLIENT_CLASS',
                                CollectionServiceClient,
                                DataConnectClient,
                                DrsClient,
+                               ExplorerClient,
                                SamplesClient,
                                ServiceRegistry,
                                DataSourceServiceClient)

dnastack/client/explorer/client.py

@@ -0,0 +1,256 @@
+from typing import List, Optional, Dict, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dnastack.client.explorer.models import FederatedQuestion
+from urllib.parse import urljoin
+
+from dnastack.client.base_client import BaseServiceClient
+from dnastack.client.base_exceptions import UnauthenticatedApiAccessError, UnauthorizedApiAccessError
+from dnastack.client.models import ServiceEndpoint
+from dnastack.client.explorer.models import (
+    FederatedQuestion,
+    FederatedQuestionListResponse,
+    FederatedQuestionQueryRequest
+)
+from dnastack.client.result_iterator import ResultLoader, InactiveLoaderError, ResultIterator
+from dnastack.client.service_registry.models import ServiceType
+from dnastack.common.tracing import Span
+from dnastack.http.session import ClientError, HttpSession, HttpError
+
+
+EXPLORER_SERVICE_TYPE_V1_0 = ServiceType(
+    group='com.dnastack.explorer',
+    artifact='collection-service',
+    version='1.0.0'
+)
+
+
+class ExplorerClient(BaseServiceClient):
+    """
+    Client for Explorer services supporting federated questions.
+    
+    This client provides access to federated questions that can be asked
+    across multiple collections in the Explorer network.
+    """
+
+    def __init__(self, endpoint: ServiceEndpoint):
+        super().__init__(endpoint)
+        self._session = self.create_http_session()
+
+    @staticmethod
+    def get_supported_service_types() -> List[ServiceType]:
+        return [EXPLORER_SERVICE_TYPE_V1_0]
+
+    @staticmethod
+    def get_adapter_type() -> str:
+        return "com.dnastack.explorer:questions:1.0.0"
+
+    def list_federated_questions(self, trace: Optional[Span] = None) -> 'ResultIterator[FederatedQuestion]':
+        """
+        List all available federated questions.
+        
+        Returns:
+            ResultIterator[FederatedQuestion]: Iterator over federated questions
+        """
+        return ResultIterator(
+            loader=FederatedQuestionListResultLoader(
+                service_url=urljoin(self.url, "questions"),
+                http_session=self._session,
+                trace=trace
+            )
+        )
+
+    def describe_federated_question(self, question_id: str, trace: Optional[Span] = None) -> 'FederatedQuestion':
+        """
+        Get detailed information about a specific federated question.
+        
+        Args:
+            question_id: The ID of the question to describe
+            trace: Optional tracing span
+            
+        Returns:
+            FederatedQuestion: The question details including parameters and collections
+            
+        Raises:
+            ClientError: If the question is not found or access is denied
+        """
+        url = urljoin(self.url, f"questions/{question_id}")
+        
+        with self._session as session:
+            try:
+                response = session.get(url, trace_context=trace)
+                return FederatedQuestion(**response.json())
+            except HttpError as e:
+                status_code = e.response.status_code
+                if status_code == 401:
+                    raise UnauthenticatedApiAccessError(
+                        f"Authentication required to access question '{question_id}'"
+                    )
+                elif status_code == 403:
+                    raise UnauthorizedApiAccessError(
+                        f"Not authorized to access question '{question_id}'"
+                    )
+                elif status_code == 404:
+                    raise ClientError(f"Question '{question_id}' not found")
+                else:
+                    raise ClientError(
+                        f"Failed to retrieve question '{question_id}': {e.response.text}"
+                    )
+
+    def ask_federated_question(
+        self,
+        question_id: str,
+        inputs: Dict[str, str],
+        collections: Optional[List[str]] = None,
+        trace: Optional[Span] = None
+    ) -> 'ResultIterator[Dict[str, Any]]':
+        """
+        Ask a federated question with the provided parameters.
+        
+        Args:
+            question_id: The ID of the question to ask
+            inputs: Dictionary of parameter name -> value mappings
+            collections: Optional list of collection IDs to query. If None, all collections are used.
+            trace: Optional tracing span
+            
+        Returns:
+            ResultIterator[Dict[str, Any]]: Iterator over query results
+            
+        Raises:
+            ClientError: If the request fails or parameters are invalid
+        """
+        # If no collections specified, get all collections from question metadata
+        if collections is None:
+            question = self.describe_federated_question(question_id, trace=trace)
+            collections = [col.id for col in question.collections]
+        
+        request_payload = FederatedQuestionQueryRequest(
+            inputs=inputs,
+            collections=collections
+        )
+        
+        return ResultIterator(
+            loader=FederatedQuestionQueryResultLoader(
+                service_url=urljoin(self.url, f"questions/{question_id}/query"),
+                http_session=self._session,
+                request_payload=request_payload,
+                trace=trace
+            )
+        )
+
+
+class FederatedQuestionListResultLoader(ResultLoader):
+    """
+    Result loader for listing federated questions.
+    """
+    
+    def __init__(self, service_url: str, http_session: HttpSession, trace: Optional[Span] = None):
+        self.__http_session = http_session
+        self.__service_url = service_url
+        self.__trace = trace
+        self.__loaded = False
+
+    def has_more(self) -> bool:
+        return not self.__loaded
+
+    def load(self) -> 'List[FederatedQuestion]':
+        if self.__loaded:
+            raise InactiveLoaderError(self.__service_url)
+        
+        with self.__http_session as session:
+            try:
+                response = session.get(self.__service_url, trace_context=self.__trace)
+                response_data = response.json()
+                
+                # Parse the response
+                question_list = FederatedQuestionListResponse(**response_data)
+                self.__loaded = True
+                
+                return question_list.questions
+                
+            except HttpError as e:
+                status_code = e.response.status_code
+                if status_code == 401:
+                    raise UnauthenticatedApiAccessError(
+                        "Authentication required to list federated questions"
+                    )
+                elif status_code == 403:
+                    raise UnauthorizedApiAccessError(
+                        "Not authorized to list federated questions"
+                    )
+                else:
+                    raise ClientError(
+                        f"Failed to load federated questions: {e.response.text}"
+                    )
+
+
+class FederatedQuestionQueryResultLoader(ResultLoader):
+    """
+    Result loader for federated question query results.
+    """
+    
+    def __init__(
+        self, 
+        service_url: str, 
+        http_session: HttpSession, 
+        request_payload: FederatedQuestionQueryRequest,
+        trace: Optional[Span] = None
+    ):
+        self.__http_session = http_session
+        self.__service_url = service_url
+        self.__request_payload = request_payload
+        self.__trace = trace
+        self.__loaded = False
+
+    def has_more(self) -> bool:
+        return not self.__loaded
+
+    def load(self) -> List[Dict[str, Any]]:
+        if self.__loaded:
+            raise InactiveLoaderError(self.__service_url)
+        
+        with self.__http_session as session:
+            try:
+                response = session.post(
+                    self.__service_url,
+                    json=self.__request_payload.dict(),
+                    trace_context=self.__trace
+                )
+                
+                response_data = response.json()
+                self.__loaded = True
+                
+                # Handle different response formats
+                if isinstance(response_data, list):
+                    # Direct list of results
+                    return response_data
+                elif isinstance(response_data, dict):
+                    # Check for common pagination patterns
+                    if 'data' in response_data:
+                        return response_data['data']
+                    elif 'results' in response_data:
+                        return response_data['results']
+                    else:
+                        # Single result object
+                        return [response_data]
+                else:
+                    return [response_data]
+                    
+            except HttpError as e:
+                status_code = e.response.status_code
+                if status_code == 401:
+                    raise UnauthenticatedApiAccessError(
+                        "Authentication required to ask federated questions"
+                    )
+                elif status_code == 403:
+                    raise UnauthorizedApiAccessError(
+                        "Not authorized to ask federated questions"
+                    )
+                elif status_code == 400:
+                    raise ClientError(
+                        f"Invalid question parameters: {e.response.text}"
+                    )
+                else:
+                    raise ClientError(
+                        f"Failed to execute federated question: {e.response.text}"
+                    )

dnastack/client/explorer/models.py

@@ -0,0 +1,117 @@
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel, Field
+
+
+class QuestionParam(BaseModel):
+    """
+    A parameter definition for a question.
+    
+    Based on the Java QuestionParam class from the Explorer service.
+    """
+    id: str
+    name: str
+    label: str
+    input_type: str = Field(alias="inputType")
+    description: Optional[str] = None
+    required: bool = False
+    default_value: Optional[str] = Field(default=None, alias="defaultValue")
+    test_value: Optional[str] = Field(default=None, alias="testValue")
+    input_subtype: Optional[str] = Field(default=None, alias="inputSubtype")
+    allowed_values: Optional[str] = Field(default=None, alias="allowedValues")
+    table: Optional[str] = None
+    column: Optional[str] = None
+    values: Optional[str] = None
+
+    class Config:
+        allow_population_by_field_name = True
+
+
+class QuestionCollection(BaseModel):
+    """
+    A collection reference within a federated question.
+    """
+    id: str
+    slug: str
+    name: str
+    question_id: str = Field(alias="questionId")
+
+    class Config:
+        allow_population_by_field_name = True
+
+
+class FederatedQuestion(BaseModel):
+    """
+    A federated question that can be asked across multiple collections.
+    
+    Based on the Java FederatedQuestion record from the Explorer service.
+    """
+    id: str
+    name: str
+    description: str
+    params: List[QuestionParam]
+    collections: List[QuestionCollection]
+
+
+class FederatedQuestionListResponse(BaseModel):
+    """
+    Response containing a list of federated questions.
+    """
+    questions: List[FederatedQuestion]
+
+
+class FederatedQuestionQueryRequest(BaseModel):
+    """
+    Request payload for asking a federated question.
+    
+    Based on the Java FederatedQuestionQueryRequest record.
+    """
+    inputs: Dict[str, str]
+    collections: List[str]
+
+
+class FederatedQuestionQueryResponse(BaseModel):
+    """
+    Response from asking a federated question.
+    
+    This is a flexible model to handle various response formats.
+    The actual structure depends on the question being asked.
+    """
+    # This will contain the actual query results
+    # Structure varies based on the question type
+    data: Any = None
+    
+    def __init__(self, **data):
+        # Handle raw response data
+        super().__init__(data=data)
+
+
+class QuestionQueryResult(BaseModel):
+    """
+    A single result item from a question query.
+    
+    This is a flexible model to handle different result structures
+    depending on the question type.
+    """
+    # Dynamic content - structure varies by question
+    content: Dict[str, Any] = Field(default_factory=dict)
+
+    def __init__(self, **data):
+        super().__init__(content=data)
+
+    def __getitem__(self, key):
+        return self.content[key]
+
+    def __setitem__(self, key, value):
+        self.content[key] = value
+
+    def get(self, key, default=None):
+        return self.content.get(key, default)
+
+    def keys(self):
+        return self.content.keys()
+
+    def values(self):
+        return self.content.values()
+
+    def items(self):
+        return self.content.items()

dnastack/constants.py

@@ -1,5 +1,5 @@
 import os
 
-__version__ = "v3.1.139"
+__version__ = "v3.1.144"
 
 LOCAL_STORAGE_DIRECTORY = os.path.join(os.path.expanduser("~"), '.dnastack')

dnastack_client_library-3.1.144.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: dnastack-client-library
+Version: 3.1.144
+Summary: DNAstack's GA4GH library and CLI
+Author-email: DNAstack <devs@dnastack.com>
+License: Apache License, Version 2.0
+Project-URL: Homepage, https://www.dnastack.com
+Project-URL: Documentation, https://docs.omics.ai/products/analysis/python-library
+Project-URL: Repository, https://github.com/DNAstack/dnastack-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<8.2,>=8.0.3
+Requires-Dist: pydantic<2,>=1.9.0
+Requires-Dist: pyjwt<3,>=2.1.0
+Requires-Dist: pyyaml>=5.4.1
+Requires-Dist: requests<3,>=2.23.0
+Requires-Dist: urllib3<2,>=1.25.11
+Requires-Dist: kotoba
+Requires-Dist: imagination>=3.3.1
+Requires-Dist: requests-toolbelt<1,>=0.9.1
+Requires-Dist: httpie>=3.2.1
+Provides-Extra: test
+Requires-Dist: selenium>=3.141.0; extra == "test"
+Requires-Dist: pyjwt>=2.1.0; extra == "test"
+Requires-Dist: jsonpath-ng>=1.5.3; extra == "test"
+Dynamic: license-file
+
+GA4GH API client and command line tool. Please check out [the documentation](https://docs.omics.ai/products/analysis/python-library) for more details.

{dnastack_client_library-3.1.139.dist-info → dnastack_client_library-3.1.144.dist-info}/RECORD

@@ -1,6 +1,6 @@
 dnastack/__init__.py,sha256=mslf7se8vBSK_HkqWTGPdibeVhT4xyKXgzQBV7dEK1M,333
-dnastack/__main__.py,sha256=3rydT8oj5G1IN0asiqv9oaQw2xmyIlVge8c8wUjo0HA,3532
-dnastack/constants.py,sha256=lXEVuXC5TIWYQas0joLaIRApFzO_g0nDo9tZuDQw-WA,114
+dnastack/__main__.py,sha256=0R4pq-kVx2TjcGT_bUXiqKj91ba3Op8I6w1pqiaxR10,3682
+dnastack/constants.py,sha256=jaK6QFWKaJVTqeMQ6KIkcEk6jNZF9eYkteiTPeHFOXA,114
 dnastack/feature_flags.py,sha256=RK_V_Ovncoe6NeTheAA_frP-kYkZC1fDlTbbup2KYG4,1419
 dnastack/json_path.py,sha256=TyghhDf7nGQmnsUWBhenU_fKsE_Ez-HLVER6HgH5-hU,2700
 dnastack/omics_cli.py,sha256=ZppKZTHv_XjUUZyRIzSkx0Ug5ODAYrCOTsU0ezCOVrA,3694
@@ -49,6 +49,12 @@ dnastack/cli/commands/dataconnect/utils.py,sha256=7psRouHUsg2QEemZAhzHVsjy1rza63
 dnastack/cli/commands/drs/__init__.py,sha256=XGPfCsdOyZyc67ptYmM903US741hDCKaTowVtysC6H8,325
 dnastack/cli/commands/drs/commands.py,sha256=637is2PLyBnER9rjPlYd_QjKO4jEmlR_Uh_vLe_dCLs,5470
 dnastack/cli/commands/drs/utils.py,sha256=tGogaIlXKnk03GqitzeDfo893JlP7Nc_X28sH-yQUrI,427
+dnastack/cli/commands/explorer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dnastack/cli/commands/explorer/commands.py,sha256=X1gvnH3TPoE4BIVBBVA2BMRQpA4qT3XhcjxsfRftMoI,589
+dnastack/cli/commands/explorer/questions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dnastack/cli/commands/explorer/questions/commands.py,sha256=37-BnAxCh0dEPe5BpBh06esMdtfoF73xL5zhQ2aLK5w,6129
+dnastack/cli/commands/explorer/questions/tables.py,sha256=cb8YKqY7Qxrm2ROz7z8H6bGp964BNEipuX8KaThTveo,4337
+dnastack/cli/commands/explorer/questions/utils.py,sha256=HNBHEV_F-41IyfnG1ZfxMnacp11UvhwnH4Z2DKgxPZs,7634
 dnastack/cli/commands/publisher/__init__.py,sha256=G8WNdx1UwanoA4X349ghv8Zyv5YizB8ryeJmwu9px8o,443
 dnastack/cli/commands/publisher/collections/__init__.py,sha256=KmclN_KY3ctVhtv-i8rxXpWTshPCj1tY6yhud4vrXYQ,636
 dnastack/cli/commands/publisher/collections/commands.py,sha256=A82NphvnD-9JuN2dVU_07EbAvB1NE7Em07IU7eDhagc,9454
@@ -106,7 +112,7 @@ dnastack/cli/helpers/printer.py,sha256=IdGoEnBWtzgPAE2KLoZEfwshn0tkrTu-XXtN-KXj8
 dnastack/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dnastack/client/base_client.py,sha256=ZhaWHHTQcuPun6RdrtCdShGRYoY18hEKAIHmr8Z728M,3730
 dnastack/client/base_exceptions.py,sha256=bNplPuE5wHxIbMI10wk6uk2aFhYub0KT2dcPC8HqbSM,2887
-dnastack/client/constants.py,sha256=6nB1QKz-GEx8BSnPLFafKGG1WDF3l0P0_HlC01FSvwc,1849
+dnastack/client/constants.py,sha256=-X7EYSLha7ZSbEjQmPvM_R7yyDHuPuVjNZCNotfzSj0,1987
 dnastack/client/data_connect.py,sha256=6qDx6-dl-fmakEMYK_jfTgUcYe1yl8eTCMPI_8tRUwg,26211
 dnastack/client/drs.py,sha256=geLN7jTurC4K-XtwSgGD19HoEeOe1EIopX9znc_Wpb4,21224
 dnastack/client/factory.py,sha256=PQGYUGhKeqyJtEtc-bZM5OlEup9K7lB-qwmNiII_4HU,6288
@@ -118,6 +124,9 @@ dnastack/client/collections/model.py,sha256=JO-eC_jc7hY9PBvST3x1vkmJE0LPDAbcUq5V
 dnastack/client/datasources/__init__.py,sha256=HxDIHuQX8KMWr3o70ucL3x79pXKaIHbBq7JqmyoRGxM,179
 dnastack/client/datasources/client.py,sha256=jfVzCSKuQJsggbvfJVbftYJ0hd6gAPsBZMgvINOgjRE,4671
 dnastack/client/datasources/model.py,sha256=dV9Sf05ivIq0ubwIIYK3kSv1xJ_TtjxvVp_ddI9aHEk,214
+dnastack/client/explorer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dnastack/client/explorer/client.py,sha256=A_C2YN5rLc-KqOBxmYHvLcq1tbRrRwRdfmV8DwcQAuQ,9511
+dnastack/client/explorer/models.py,sha256=vrltbcb4qAx6z1oGXG8ufw2kZ36dDiwU5QGqOomYp6c,3126
 dnastack/client/service_registry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dnastack/client/service_registry/client.py,sha256=r7D8CnPJLbNkc03g2PYHt880Ba1oPW2d8B0ShP0p4Eo,1131
 dnastack/client/service_registry/factory.py,sha256=MKidmvDuIdnz9jsqm6yDjImldcNajKxopwmKFFCTN4U,10751
@@ -183,9 +192,9 @@ dnastack/http/authenticators/oauth2_adapter/client_credential.py,sha256=Lu22mTT1
 dnastack/http/authenticators/oauth2_adapter/device_code_flow.py,sha256=j0EODp-O8DCCqh9kOGi5MDOdVXkQO14Q7ZJe4ZrzPCY,6527
 dnastack/http/authenticators/oauth2_adapter/factory.py,sha256=r8K6swt5zhraP74KhTL2K4sQ71HWAMLM0oHg8qQT4BA,965
 dnastack/http/authenticators/oauth2_adapter/models.py,sha256=U11r8DZsWvjIRNCJE1mmQMuprZw3fpFwFBg7vmI5w48,660
-dnastack_client_library-3.1.139.dist-info/licenses/LICENSE,sha256=uwybO-wUbQhxkosgjhJlxmYATMy-AzoULFO9FUedE34,11580
-dnastack_client_library-3.1.139.dist-info/METADATA,sha256=v-G603s54oznNVCJd_7L8zk8ci9WUVPyfWOqhovlPYA,988
-dnastack_client_library-3.1.139.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dnastack_client_library-3.1.139.dist-info/entry_points.txt,sha256=Y6OeicsiyGn3-8D-SiV4NiKlJgXfkSqK88kFBR6R1rY,89
-dnastack_client_library-3.1.139.dist-info/top_level.txt,sha256=P2RgRyqJ7hfNy1wLVRoVLJYEppUVkCX3syGK9zBqkt8,9
-dnastack_client_library-3.1.139.dist-info/RECORD,,
+dnastack_client_library-3.1.144.dist-info/licenses/LICENSE,sha256=uwybO-wUbQhxkosgjhJlxmYATMy-AzoULFO9FUedE34,11580
+dnastack_client_library-3.1.144.dist-info/METADATA,sha256=VGEBV4ScOMv2xQbFzn8Pp0Ejo2d3DeOGJuf6W26Mu90,1490
+dnastack_client_library-3.1.144.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dnastack_client_library-3.1.144.dist-info/entry_points.txt,sha256=Y6OeicsiyGn3-8D-SiV4NiKlJgXfkSqK88kFBR6R1rY,89
+dnastack_client_library-3.1.144.dist-info/top_level.txt,sha256=P2RgRyqJ7hfNy1wLVRoVLJYEppUVkCX3syGK9zBqkt8,9
+dnastack_client_library-3.1.144.dist-info/RECORD,,

dnastack_client_library-3.1.139.dist-info/METADATA

@@ -1,28 +0,0 @@
-Metadata-Version: 2.4
-Name: dnastack-client-library
-Version: 3.1.139
-Summary: "DNAstack's GA4GH library and CLI"
-Home-page: https://www.dnastack.com
-Author: DNAstack
-Author-email: devs@dnastack.com
-License: Apache License, Version 2.0
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: click<8.2,>=8.0.3
-Requires-Dist: pydantic<2,>=1.9.0
-Requires-Dist: pyjwt<3,>=2.1.0
-Requires-Dist: pyyaml>=5.4.1
-Requires-Dist: requests<3,>=2.23.0
-Requires-Dist: urllib3<2,>=1.25.11
-Requires-Dist: kotoba
-Requires-Dist: imagination>=3.3.1
-Requires-Dist: requests-toolbelt<1,>=0.9.1
-Requires-Dist: httpie>=3.2.1
-Provides-Extra: test
-Requires-Dist: selenium>=3.141.0; extra == "test"
-Requires-Dist: pyjwt>=2.1.0; extra == "test"
-Requires-Dist: jsonpath-ng>=1.5.3; extra == "test"
-Dynamic: license-file
-
-"GA4GH API client and command line tool. Please check out [the documentation](https://docs.omics.ai/products/analysis/python-library) for more details."