dnastack-client-library 3.1.139__py3-none-any.whl → 3.1.145__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
@@ -70,12 +71,30 @@ def version():
             type=bool,
             required=False,
             hidden=True,
+        ),
+        ArgumentSpec(
+            name='platform_credentials',
+            arg_names=['--platform-credentials'],
+            help='Use platform-specific credentials (IMDS) for authentication',
+            type=bool,
+            required=False,
+            hidden=True,
+        ),
+        ArgumentSpec(
+            name='subject_token',
+            arg_names=['--subject-token'],
+            help='Subject token for token exchange authentication',
+            type=str,
+            required=False,
+            hidden=True,
         )
     ]
 )
 def use(registry_hostname_or_url: str,
         context_name: Optional[str] = None,
-        no_auth: bool = False):
+        no_auth: bool = False,
+        platform_credentials: bool = False,
+        subject_token: Optional[str] = None):
     """
     Import a configuration from host's service registry (if available) or the corresponding public configuration from
     cloud storage. If "--no-auth" is not defined, it will automatically initiate all authentication.
@@ -84,7 +103,7 @@ def use(registry_hostname_or_url: str,
 
     This is a shortcut to dnastack config contexts use".
     """
-    _context_command_handler.use(registry_hostname_or_url, context_name=context_name, no_auth=no_auth)
+    _context_command_handler.use(registry_hostname_or_url, context_name=context_name, no_auth=no_auth, platform_credentials=platform_credentials, subject_token=subject_token)
 
 
 # noinspection PyTypeChecker
@@ -106,6 +125,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/auth/commands.py

@@ -50,8 +50,7 @@ def init_auth_commands(group: Group):
         handler.initiate_authentications(endpoint_ids=[endpoint_id] if endpoint_id else [],
                                          force_refresh=force_refresh,
                                          revoke_existing=revoke_existing)
-    
-    
+
     @formatted_command(
         group=group,
         name='status',
@@ -94,6 +93,8 @@ def init_auth_commands(group: Group):
         handler.revoke([endpoint_id] if endpoint_id else [], force)
     
     
+
+    
 class AuthCommandHandler:
     def __init__(self, context_name: Optional[str] = None):
         self._logger = get_logger(type(self).__name__)
@@ -126,7 +127,7 @@ class AuthCommandHandler:
         echo_header('Summary')
 
         if affected_endpoint_ids:
-            echo_list('The client is no longer authenticated to the follow endpoints:',
+            echo_list('The client is no longer authenticated to the following endpoints:',
                       affected_endpoint_ids)
         else:
             click.echo('No changes')
@@ -158,3 +159,4 @@ class AuthCommandHandler:
         auth_manager.events.on('refresh-skipped', handle_refresh_skipped)
 
         auth_manager.initiate_authentications(endpoint_ids, force_refresh, revoke_existing)
+

dnastack/cli/commands/config/contexts.py

@@ -170,9 +170,9 @@ class ContextCommandHandler:
     def manager(self):
         return self._context_manager
 
-    def use(self, registry_hostname_or_url: str, context_name: Optional[str] = None, no_auth: bool = False):
+    def use(self, registry_hostname_or_url: str, context_name: Optional[str] = None, no_auth: bool = False, platform_credentials: bool = False, subject_token: Optional[str] = None):
         echo_result('Context', 'blue', 'syncing', registry_hostname_or_url)
-        self._context_manager.use(registry_hostname_or_url, context_name=context_name, no_auth=no_auth)
+        self._context_manager.use(registry_hostname_or_url, context_name=context_name, no_auth=no_auth, platform_credentials=platform_credentials, subject_token=subject_token)
         echo_result('Context', 'green', 'use', registry_hostname_or_url)
 
     def __handle_sync_event(self, event: Event):

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)