tessl/pypi-awscli

Universal Command Line Environment for AWS.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Argument Processing

Name: tessl/pypi-awscli
Author: tessl

Advanced argument parsing, validation, and transformation system that handles complex AWS parameter structures, shorthand syntax, file-based parameter input, and type conversion. The argument processing system bridges CLI input to AWS service parameters.

Capabilities

Base Argument Interface

The foundational interface for all CLI arguments, providing the contract for argument registration, parsing, and parameter generation.

class BaseCLIArgument:
    def __init__(self, name):
        """
        Initialize base CLI argument.
        
        Parameters:
            name: str, argument name
        """
    
    @property
    def name(self) -> str:
        """Argument name."""
    
    @property
    def cli_name(self) -> str:
        """CLI argument name (e.g., '--instance-ids')."""
    
    @property
    def cli_type_name(self) -> str:
        """CLI type name for help documentation."""
    
    @property
    def required(self) -> bool:
        """Whether argument is required."""
    
    @property
    def documentation(self) -> str:
        """Argument documentation for help."""
    
    @property
    def cli_type(self) -> type:
        """Python type for argument value."""
    
    @property
    def py_name(self) -> str:
        """Python parameter name for AWS API."""
    
    @property
    def choices(self) -> list:
        """Valid choices for argument value."""
    
    @property
    def synopsis(self) -> str:
        """Argument synopsis for help."""
    
    @property
    def positional_arg(self) -> bool:
        """Whether argument is positional."""
    
    @property
    def nargs(self):
        """Number of arguments consumed."""
    
    @property
    def group_name(self) -> str:
        """Argument group name for help organization."""
    
    def add_to_arg_table(self):
        """Add argument to command's argument table."""
    
    def add_to_parser(self):
        """Add argument to argument parser."""
    
    def add_to_params(self):
        """Add processed argument to parameter dictionary."""

Custom Argument Implementation

Configurable CLI argument for custom commands with extensive customization options.

class CustomArgument(BaseCLIArgument):
    def __init__(self, name, help_text='', dest=None, default=None, 
                 action=None, required=None, choices=None, nargs=None,
                 cli_type_name=None, group_name=None, positional_arg=False,
                 no_paramfile=False, argument_model=None, synopsis='', const=None):
        """
        Initialize custom CLI argument with full configuration options.
        
        Parameters:
            name: str, argument name
            help_text: str, help text for argument
            dest: str, destination variable name
            default: any, default value
            action: str, argparse action ('store', 'store_true', etc.)
            required: bool, whether argument is required
            choices: list, valid choices for argument
            nargs: str|int, number of arguments ('?', '*', '+', or integer)
            cli_type_name: str, type name for help display
            group_name: str, argument group for help organization
            positional_arg: bool, whether argument is positional
            no_paramfile: bool, exclude from parameter file processing
            argument_model: argument model for advanced configuration
            synopsis: str, synopsis for help
            const: any, constant value for certain actions
        """

Usage Example:

from awscli.arguments import CustomArgument

# Create custom arguments for a command
args = [
    CustomArgument(
        'instance-id',
        help_text='EC2 instance ID to operate on',
        required=True,
        cli_type_name='string'
    ),
    CustomArgument(
        'dry-run',
        help_text='Perform a dry run without making changes',
        action='store_true',
        default=False
    ),
    CustomArgument(
        'tags',
        help_text='Instance tags in key=value format',
        nargs='*',
        cli_type_name='list'
    )
]

Service Argument Implementation

CLI argument mapped from AWS service parameters with automatic type conversion and validation.

class CLIArgument(BaseCLIArgument):
    TYPE_MAP: dict  # Class attribute mapping AWS types to Python types
    
    def __init__(self, name, argument_model, operation_model, event_emitter, 
                 is_required=False, serialized_name=None):
        """
        Initialize CLI argument from AWS service parameter.
        
        Parameters:
            name: str, argument name
            argument_model: botocore argument model
            operation_model: botocore operation model
            event_emitter: botocore event emitter
            is_required: bool, whether argument is required
            serialized_name: str, AWS API parameter name
        """

Specialized Argument Types

Specific argument implementations for common AWS parameter patterns.

class ListArgument(CLIArgument):
    """
    CLI argument for list-type parameters.
    Handles comma-separated values and JSON arrays.
    """

class BooleanArgument(CLIArgument):
    """
    CLI argument for boolean parameters.
    Handles --flag and --no-flag patterns.
    """

Argument Processing Functions

Core functions for processing and transforming CLI arguments into AWS service parameters.

def unpack_argument(session, service_name, operation_name, cli_argument, value):
    """
    Unpack CLI argument value to AWS service parameter format.
    
    Parameters:
        session: botocore.session.Session, AWS session
        service_name: str, AWS service name
        operation_name: str, operation name
        cli_argument: CLI argument instance
        value: argument value from command line
        
    Returns:
        Processed parameter value
    """

def unpack_cli_arg(cli_argument, value):
    """
    Unpack CLI argument value based on argument type.
    
    Parameters:
        cli_argument: CLI argument instance
        value: raw argument value
        
    Returns:
        Processed argument value
    """

def create_argument_model_from_schema(schema):
    """
    Create argument model from JSON schema.
    
    Parameters:
        schema: dict, JSON schema definition
        
    Returns:
        Argument model instance
    """

Usage Example:

from awscli.argprocess import unpack_argument
import botocore.session

# Process CLI argument for AWS API
session = botocore.session.Session()
processed_value = unpack_argument(
    session=session,
    service_name='ec2',
    operation_name='describe-instances',
    cli_argument=instance_ids_arg,
    value=['i-1234567890abcdef0', 'i-0987654321fedcba0']
)

Argument Processing Exceptions

Specialized exceptions for argument processing errors.

class UnknownArgumentError(Exception):
    """Raised when an unknown argument is encountered."""

class ParamError(Exception):
    """Base exception for parameter processing errors."""

class ParamSyntaxError(Exception):
    """Raised when parameter syntax is invalid."""

class ParamUnknownKeyError(Exception):
    """Raised when an unknown parameter key is encountered."""

Advanced Argument Processing

Shorthand Syntax Processing

AWS CLI supports shorthand syntax for complex parameters:

# Shorthand for complex structures
aws ec2 run-instances --block-device-mappings DeviceName=/dev/sda1,Ebs='{VolumeSize=20}'

# Equivalent to JSON
aws ec2 run-instances --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20}}]'

Parameter File Support

Arguments can be loaded from files using the file:// prefix:

# Command line usage
aws ec2 run-instances --cli-input-json file://instance-config.json

# Programmatic equivalent
with open('instance-config.json') as f:
    config = json.load(f)
    # Process config through argument system

Type Conversion and Validation

The argument system handles automatic type conversion:

# String to appropriate AWS type conversion
TYPE_CONVERSIONS = {
    'string': str,
    'integer': int,
    'long': int,
    'boolean': bool,
    'double': float,
    'float': float,
    'blob': bytes,
    'timestamp': datetime,
    'structure': dict,
    'list': list,
    'map': dict
}

Argument Table Construction

Arguments are organized in argument tables for commands:

def build_argument_table(operation_model):
    """Build argument table from operation model."""
    arg_table = {}
    
    for param_name, param_model in operation_model.input_shape.members.items():
        cli_name = param_name.replace('_', '-').lower()
        arg_table[cli_name] = CLIArgument(
            name=cli_name,
            argument_model=param_model,
            operation_model=operation_model,
            event_emitter=session.get_component('event_emitter')
        )
    
    return arg_table

Custom Argument Integration

Custom commands can define their own argument processing:

from awscli.arguments import CustomArgument
from awscli.customizations.commands import BasicCommand

class MyCommand(BasicCommand):
    NAME = 'my-command'
    ARG_TABLE = [
        CustomArgument(
            'input-file',
            help_text='Input file path',
            required=True,
            cli_type_name='string'
        ),
        CustomArgument(
            'output-format',
            help_text='Output format',
            choices=['json', 'yaml', 'text'],
            default='json'
        )
    ]
    
    def _run_main(self, parsed_args, parsed_globals):
        input_file = parsed_args.input_file
        output_format = parsed_args.output_format
        # Process arguments and execute command

Install with Tessl CLI