tessl/pypi-absl-py

Abseil Python Common Libraries providing application startup utilities, command-line flag management, enhanced logging, and comprehensive testing utilities.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Command-Line Flags

Name: tessl/pypi-absl-py
Author: tessl

Distributed command-line flag system allowing any Python module to define flags that are automatically integrated into a global flag registry. Supports various flag types, validation, help generation, and complex flag relationships.

Global Flag Registry

FLAGS: FlagValues  # Global flag registry instance

The global FLAGS object contains all defined flags and their current values. Access flag values using dot notation: FLAGS.flag_name.

Capabilities

Basic Flag Definition

Core functions for defining different types of command-line flags.

def DEFINE_string(name, default, help, flag_values=FLAGS, **args):
    """
    Define a string flag.
    
    Args:
        name (str): Flag name
        default (str): Default value
        help (str): Help description
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments (required, short_name, etc.)
    """

def DEFINE_boolean(name, default, help, flag_values=FLAGS, **args):
    """
    Define a boolean flag.
    
    Args:
        name (str): Flag name  
        default (bool): Default value
        help (str): Help description
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments
    """

def DEFINE_bool(name, default, help, flag_values=FLAGS, **args):
    """Alias for DEFINE_boolean to match C++ API."""

def DEFINE_integer(name, default, help, flag_values=FLAGS, **args):
    """
    Define an integer flag.
    
    Args:
        name (str): Flag name
        default (int): Default value  
        help (str): Help description
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments (lower_bound, upper_bound, etc.)
    """

def DEFINE_float(name, default, help, flag_values=FLAGS, **args):
    """
    Define a float flag.
    
    Args:
        name (str): Flag name
        default (float): Default value
        help (str): Help description  
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments (lower_bound, upper_bound, etc.)
    """

def DEFINE_enum(name, default, enum_values, help, flag_values=FLAGS, **args):
    """
    Define an enum flag that accepts one of a predefined set of values.
    
    Args:
        name (str): Flag name
        default (str): Default value (must be in enum_values)
        enum_values (List[str]): List of allowed values
        help (str): Help description
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments
    """

def DEFINE_enum_class(name, default, enum_class, help, flag_values=FLAGS, **args):
    """
    Define an enum flag using a Python Enum class.
    
    Args:
        name (str): Flag name
        default: Default enum value or string name
        enum_class: Python Enum class
        help (str): Help description
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments
    """

List and Multi-Value Flags

Flags that accept multiple values or lists of values.

def DEFINE_list(name, default, help, flag_values=FLAGS, **args):
    """
    Define a flag that accepts a comma-separated list of strings.
    
    Args:
        name (str): Flag name
        default (List[str]): Default list value
        help (str): Help description
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments
    """

def DEFINE_spaceseplist(name, default, help, flag_values=FLAGS, **args):
    """
    Define a flag that accepts a space-separated list of strings.
    
    Args:
        name (str): Flag name
        default (List[str]): Default list value
        help (str): Help description
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments
    """

def DEFINE_multi_string(name, default, help, flag_values=FLAGS, **args):
    """
    Define a flag that can be specified multiple times to build a list.
    
    Example: --multi_flag=value1 --multi_flag=value2 results in ['value1', 'value2']
    
    Args:
        name (str): Flag name
        default (List[str]): Default list value
        help (str): Help description
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments
    """

def DEFINE_multi_integer(name, default, help, flag_values=FLAGS, **args):
    """Define a multi-value integer flag."""

def DEFINE_multi_float(name, default, help, flag_values=FLAGS, **args):
    """Define a multi-value float flag."""

def DEFINE_multi_enum(name, default, enum_values, help, flag_values=FLAGS, **args):
    """Define a multi-value enum flag."""

def DEFINE_multi_enum_class(name, default, enum_class, help, flag_values=FLAGS, **args):
    """Define a multi-value enum class flag."""

Advanced Flag Definition

More sophisticated flag definition capabilities.

def DEFINE_flag(flag, flag_values=FLAGS, **args):
    """
    Define a flag using a Flag object.
    
    Args:
        flag (Flag): Pre-constructed Flag instance
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments
    """

def DEFINE_alias(name, original_name, flag_values=FLAGS, **args):
    """
    Define an alias for an existing flag.
    
    Args:
        name (str): New alias name
        original_name (str): Original flag name
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        **args: Additional arguments
    """

def DEFINE(parser, name, default, help, flag_values=FLAGS, serializer=None, **args):
    """
    Generic flag definition using a custom parser.
    
    Args:
        parser (ArgumentParser): Parser for the flag value
        name (str): Flag name
        default: Default value
        help (str): Help description
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
        serializer (ArgumentSerializer): Custom serializer for the flag
        **args: Additional arguments
    """

Flag Validation

Functions for validating flag values and relationships between multiple flags.

def register_validator(flag_name, checker, message='Flag validation failed', flag_values=FLAGS):
    """
    Register a validator function for a flag.
    
    Args:
        flag_name (str): Name of flag to validate
        checker (callable): Function that takes flag value and returns bool
        message (str): Error message for validation failure
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
    """

def validator(flag_name, message='Flag validation failed', flag_values=FLAGS):
    """
    Decorator to register a flag validator.
    
    Args:
        flag_name (str): Name of flag to validate
        message (str): Error message for validation failure
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
    
    Returns:
        Decorator function
    """

def register_multi_flags_validator(flag_names, multi_flags_checker, message='Flags validation failed'):
    """
    Register a validator for multiple flags.
    
    Args:
        flag_names (List[str]): Names of flags to validate together
        multi_flags_checker (callable): Function that takes flag dict and returns bool
        message (str): Error message for validation failure
    """

def multi_flags_validator(flag_names, message='Flags validation failed'):
    """
    Decorator to register a multi-flag validator.
    
    Args:
        flag_names (List[str]): Names of flags to validate together
        message (str): Error message for validation failure
        
    Returns:
        Decorator function
    """

def mark_flag_as_required(flag_name, flag_values=FLAGS):
    """
    Mark a flag as required.
    
    Args:
        flag_name (str): Name of flag to mark as required
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
    """

def mark_flags_as_required(flag_names, flag_values=FLAGS):
    """
    Mark multiple flags as required.
    
    Args:
        flag_names (List[str]): Names of flags to mark as required
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
    """

def mark_flags_as_mutual_exclusive(flag_names, required=False, flag_values=FLAGS):
    """
    Mark flags as mutually exclusive.
    
    Args:
        flag_names (List[str]): Names of flags that are mutually exclusive
        required (bool): If True, exactly one flag must be specified
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
    """

def mark_bool_flags_as_mutual_exclusive(flag_names, required=True, flag_values=FLAGS):
    """
    Mark boolean flags as mutually exclusive.
    
    Args:
        flag_names (List[str]): Names of boolean flags that are mutually exclusive
        required (bool): If True, exactly one flag must be True
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
    """

Flag Modification

Functions to modify flag defaults and values at runtime.

def set_default(flag_holder, value):
    """
    Set the default value for a flag.
    
    Args:
        flag_holder (FlagHolder): Flag holder returned by DEFINE_*
        value: New default value
    """

def override_value(flag_holder, value):
    """
    Override the current value of a flag.
    
    Args:
        flag_holder (FlagHolder): Flag holder returned by DEFINE_*
        value: New value to set
    """

Key Flags

System for managing key flags that are adopted across modules.

def declare_key_flag(flag_name, flag_values=FLAGS):
    """
    Declare a flag as a key flag for the current module.
    
    Args:
        flag_name (str): Name of flag to declare as key
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
    """

def adopt_module_key_flags(module, flag_values=FLAGS):
    """
    Adopt key flags from another module.
    
    Args:
        module: Module to adopt key flags from
        flag_values (FlagValues): Flag registry (defaults to global FLAGS)
    """

def disclaim_key_flags():
    """Disclaim key flags for the current module."""

Exception Classes

Exception types for flag-related errors.

class Error(Exception):
    """Base exception for flag errors."""

class CantOpenFlagFileError(Error):
    """Exception when flag file cannot be opened."""

class DuplicateFlagError(Error):
    """Exception when a flag is defined multiple times."""

class IllegalFlagValueError(Error):
    """Exception when a flag is given an illegal value."""

class UnrecognizedFlagError(Error):
    """Exception when an unrecognized flag is encountered."""

class UnparsedFlagAccessError(Error):
    """Exception when accessing flag before parsing."""

class ValidationError(Error):
    """Exception for flag validation failures."""

class FlagNameConflictsWithMethodError(Error):
    """Exception when flag name conflicts with FlagValues method."""

Core Classes

Core classes for flag system implementation.

class FlagValues:
    """Container for all flag values and parsing state."""
    
    def __getattr__(self, name):
        """Get flag value by name."""
    
    def __setattr__(self, name, value):
        """Set flag value by name."""

class Flag:
    """Base class for all flag types."""

class FlagHolder:
    """Holder object returned by DEFINE_* functions."""

class ArgumentParser:
    """Base class for flag argument parsers."""

class ArgumentSerializer:
    """Base class for flag argument serializers."""

class BooleanParser(ArgumentParser):
    """Parser for boolean flag values."""

class EnumParser(ArgumentParser):
    """Parser for enum flag values."""

class EnumClassParser(ArgumentParser):
    """Parser for enum class flag values."""

class FloatParser(ArgumentParser):
    """Parser for float flag values."""

class IntegerParser(ArgumentParser):
    """Parser for integer flag values."""

class ListParser(ArgumentParser):
    """Parser for list flag values."""

class WhitespaceSeparatedListParser(ArgumentParser):
    """Parser for whitespace-separated list values."""

Utility Functions

Utility functions for help generation and text formatting.

def get_help_width():
    """Get the width for help text formatting."""

def text_wrap(text, length=None, indent='', firstline_indent=None):
    """
    Wrap text to specified width with indentation.
    
    Args:
        text (str): Text to wrap
        length (int): Maximum line length
        indent (str): Indentation for continuation lines
        firstline_indent (str): Indentation for first line
    """

def flag_dict_to_args(flag_map, multi_flags=None):
    """
    Convert flag dictionary to command line arguments.
    
    Args:
        flag_map (dict): Dictionary of flag names to values
        multi_flags (set): Set of flag names that are multi-valued
        
    Returns:
        List[str]: Command line arguments
    """

def doc_to_help(doc):
    """
    Convert docstring to help text.
    
    Args:
        doc (str): Docstring to convert
        
    Returns:
        str: Formatted help text
    """

Usage Examples

Basic Flag Usage

from absl import app
from absl import flags

FLAGS = flags.FLAGS

# Define flags
flags.DEFINE_string('input_file', None, 'Path to input file.')
flags.DEFINE_integer('max_items', 100, 'Maximum number of items to process.')
flags.DEFINE_boolean('verbose', False, 'Enable verbose output.')

def main(argv):
    # Access flag values
    print(f'Processing file: {FLAGS.input_file}')
    print(f'Max items: {FLAGS.max_items}')
    print(f'Verbose mode: {FLAGS.verbose}')

if __name__ == '__main__':
    app.run(main)

Flag Validation

from absl import flags
import os

FLAGS = flags.FLAGS

flags.DEFINE_string('input_file', None, 'Input file path.')
flags.DEFINE_integer('threads', 1, 'Number of threads.')

# Simple validator
@flags.validator('input_file', 'Input file must exist')
def validate_input_file(value):
    return value is None or os.path.exists(value)

# Multi-flag validator
@flags.multi_flags_validator(['threads', 'input_file'], 'Thread count must be 1 when no input file')
def validate_threads_and_file(flags_dict):
    if flags_dict['input_file'] is None and flags_dict['threads'] > 1:
        return False
    return True

# Mark flags as required
flags.mark_flag_as_required('input_file')

Enum Flags

from absl import flags
from enum import Enum

FLAGS = flags.FLAGS

# String enum
flags.DEFINE_enum('mode', 'dev', ['dev', 'test', 'prod'], 'Deployment mode.')

# Enum class
class LogLevel(Enum):
    DEBUG = 'debug'
    INFO = 'info'  
    WARNING = 'warning'
    ERROR = 'error'

flags.DEFINE_enum_class('log_level', LogLevel.INFO, LogLevel, 'Logging level.')

Multi-Value Flags

from absl import flags

FLAGS = flags.FLAGS

# Comma-separated list
flags.DEFINE_list('files', [], 'List of files to process.')

# Multi-occurrence flag
flags.DEFINE_multi_string('tag', [], 'Tags to apply (can be specified multiple times).')

# Usage: --files=file1,file2,file3 --tag=important --tag=urgent

Install with Tessl CLI