tessl/pypi-clint

Python Command Line Interface Tools for colored output, progress bars, text formatting, and argument handling

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Command Line Arguments

Name: tessl/pypi-clint
Author: tessl

Comprehensive command-line argument parsing with filtering, grouping, and file/flag detection. The Args class provides chainable methods for finding, filtering, and extracting arguments with support for complex argument patterns and intelligent file/flag separation.

Capabilities

Basic Argument Access

Access arguments by index, check for existence, and retrieve argument values with safe fallbacks to None for missing arguments.

class Args:
    def __init__(self, args=None, no_argv=False):
        """
        Initialize Args object.
        
        Parameters:
        - args: list, optional custom argument list (defaults to sys.argv[1:])
        - no_argv: bool, if True creates empty Args object
        """
    
    def get(self, x):
        """
        Returns argument at given index, else None.
        
        Parameters:
        - x: int, index of argument to retrieve
        
        Returns:
        str or None: argument at index or None if not found
        """
    
    def __getitem__(self, i):
        """Get argument by index, returns None if not found."""
    
    def __len__(self):
        """Return number of arguments."""
    
    def __contains__(self, x):
        """Check if argument exists in argument list."""
    
    def __repr__(self):
        """Return string representation of Args object."""

Argument Search and Filtering

Find arguments by value, search for arguments containing specific strings, and filter arguments based on various criteria.

def contains(self, x):
    """
    Tests if given object is in arguments list.
    
    Parameters:
    - x: str or list, value(s) to search for
    
    Returns:
    bool: True if found
    """

def first(self, x):
    """
    Returns first found index of given value (or list of values).
    
    Parameters:
    - x: str or list, value(s) to find
    
    Returns:
    int or None: index of first match or None
    """

def first_with(self, x):
    """
    Returns first found index containing value (or list of values).
    
    Parameters:
    - x: str or list, substring(s) to search for
    
    Returns:
    int or None: index of first containing match or None
    """

def first_without(self, x):
    """
    Returns first found index not containing value (or list of values).
    
    Parameters:
    - x: str or list, substring(s) to exclude
    
    Returns:
    int or None: index of first non-matching argument or None
    """

def any_contain(self, x):
    """
    Tests if given string is contained in any stored argument.
    
    Parameters:
    - x: str, substring to search for
    
    Returns:
    bool: True if substring found in any argument
    """

Argument Retrieval and Collection

Retrieve multiple arguments based on search criteria and get related argument values.

def get_with(self, x):
    """
    Returns first argument that contains given string.
    
    Parameters:
    - x: str, substring to search for
    
    Returns:
    str: first argument containing substring
    """

def all_with(self, x):
    """
    Returns all arguments containing given string (or list thereof).
    
    Parameters:
    - x: str or list, substring(s) to search for
    
    Returns:
    Args: new Args object with matching arguments
    """

def all_without(self, x):
    """
    Returns all arguments not containing given string (or list thereof).
    
    Parameters:
    - x: str or list, substring(s) to exclude
    
    Returns:
    Args: new Args object with non-matching arguments
    """

def start_with(self, x):
    """
    Returns all arguments beginning with given string (or list thereof).
    
    Parameters:
    - x: str or list, prefix(es) to match
    
    Returns:
    Args: new Args object with matching arguments
    """

def value_after(self, x):
    """
    Returns value of argument after given found argument (or list thereof).
    
    Parameters:
    - x: str, argument to find
    
    Returns:
    str or None: argument following the found argument or None
    """

Argument Modification

Remove arguments from the Args object and manipulate the argument list.

def remove(self, x):
    """
    Removes given arg (or list thereof) from Args object.
    
    Parameters:
    - x: str or list, argument(s) to remove
    """

def pop(self, x):
    """
    Removes and returns value at given index, else None.
    
    Parameters:
    - x: int, index of argument to remove
    
    Returns:
    str or None: removed argument or None
    """

Argument Properties and Grouping

Access collections of arguments with special properties and group arguments by flags.

@property
def all(self):
    """
    Returns all arguments.
    
    Returns:
    list: all arguments as list
    """

@property
def last(self):
    """
    Returns last argument.
    
    Returns:
    str or None: last argument or None if empty
    """

@property
def flags(self):
    """
    Returns Args object including only flagged arguments (starting with '-').
    
    Returns:
    Args: new Args object with only flag arguments
    """

@property
def not_flags(self):
    """
    Returns Args object excluding flagged arguments.
    
    Returns:
    Args: new Args object without flag arguments
    """

@property
def grouped(self):
    """
    Extracts --flag groups from argument list.
    
    Returns:
    OrderedDict: {flag: Args, '_': Args} mapping flags to their arguments
    """

File and Path Handling

Intelligent file path detection and expansion with glob pattern support.

@property
def files(self):
    """
    Returns an expanded list of all valid paths that were passed in.
    
    Returns:
    list: list of valid file paths (relative paths as provided)
    """

@property
def not_files(self):
    """
    Returns a list of all arguments that aren't files/globs.
    
    Returns:
    Args: new Args object with non-file arguments
    """

Position and Context Testing

Test arguments at specific positions and check for contextual relationships.

def contains_at(self, x, index):
    """
    Tests if given [list of] string is at given index.
    
    Parameters:
    - x: str or list, value(s) to test
    - index: int, position to check
    
    Returns:
    bool: True if value found at index
    """

def has(self, x):
    """
    Returns true if argument exists at given index.
    
    Parameters:
    - x: int, index to check
    
    Returns:
    bool: True if argument exists at index
    """

@property
def copy(self):
    """
    Returns a copy of Args object for temporary manipulation.
    
    Returns:
    Args: independent copy of current Args object
    """

Usage Examples

from clint.arguments import Args

# Basic usage
args = Args()
first_arg = args.get(0)
if first_arg:
    print(f"First argument: {first_arg}")

# Check for flags
if '--verbose' in args:
    print("Verbose mode enabled")

# Get all Python files
python_files = args.all_with('.py').files
print(f"Python files: {python_files}")

# Group arguments by flags
grouped = args.grouped
for flag, flag_args in grouped.items():
    if flag != '_':
        print(f"Flag {flag}: {flag_args.all}")

# Get value after a flag
output_file = args.value_after('--output')
if output_file:
    print(f"Output file: {output_file}")

# Work with file arguments only
file_args = args.files
non_file_args = args.not_files.all
print(f"Files: {file_args}")
print(f"Other args: {non_file_args}")

Install with Tessl CLI