tessl/pypi-traitlets

A pure Python library providing typed attributes with validation, change notifications, and configuration management for the IPython/Jupyter ecosystem.

Overview

Eval results

Files

Basic Trait Types

Name: tessl/pypi-traitlets
Author: tessl

Fundamental trait types for common Python data types including integers, floats, strings, booleans, and complex numbers. These types provide validation, coercion, and constraint checking for basic Python values.

Capabilities

Numeric Types

Integer Types

Integer trait types with optional bounds validation.

class Int(TraitType):
    """
    Integer trait type with optional min/max bounds.
    
    Validates that values are integers within specified range.
    Default value is 0.
    """
    
    def __init__(self, default_value=0, min=None, max=None, **kwargs):
        """
        Initialize integer trait.
        
        Parameters:
        - default_value: int - Default integer value
        - min: int|None - Minimum allowed value
        - max: int|None - Maximum allowed value  
        - **kwargs: Additional TraitType parameters
        """

class CInt(Int):
    """
    Casting version of Int that attempts to convert values to integers.
    
    Tries to cast values to int before validation, allowing for
    automatic conversion from compatible types.
    """
    
    def __init__(self, default_value=0, min=None, max=None, **kwargs):
        """
        Initialize casting integer trait.
        
        Parameters:
        - default_value: int - Default integer value
        - min: int|None - Minimum allowed value
        - max: int|None - Maximum allowed value
        - **kwargs: Additional TraitType parameters
        """

Python 2 long integer support:

class Long(TraitType):
    """
    Long integer trait type (Python 2 only).
    
    Validates long integers with optional bounds.
    Default value is 0L.
    """
    
    def __init__(self, default_value=0, min=None, max=None, **kwargs):
        """
        Initialize long integer trait.
        
        Parameters:
        - default_value: long - Default long value
        - min: long|None - Minimum allowed value
        - max: long|None - Maximum allowed value
        - **kwargs: Additional TraitType parameters
        """

class CLong(Long):
    """
    Casting version of Long (Python 2 only).
    """
    
    def __init__(self, default_value=0, min=None, max=None, **kwargs):
        """
        Initialize casting long trait.
        
        Parameters:
        - default_value: long - Default long value  
        - min: long|None - Minimum allowed value
        - max: long|None - Maximum allowed value
        - **kwargs: Additional TraitType parameters
        """

class Integer(TraitType):
    """
    Integer trait that casts longs to ints when possible (Python 2 only).
    
    Handles both int and long types, converting longs to ints
    when they fit in int range.
    """
    
    def __init__(self, default_value=0, **kwargs):
        """
        Initialize integer trait.
        
        Parameters:
        - default_value: int|long - Default value
        - **kwargs: Additional TraitType parameters
        """

Float Types

Floating-point trait types with optional bounds validation.

class Float(TraitType):
    """
    Float trait type with optional min/max bounds.
    
    Validates that values are floats within specified range.
    Default value is 0.0.
    """
    
    def __init__(self, default_value=0.0, min=None, max=None, **kwargs):
        """
        Initialize float trait.
        
        Parameters:
        - default_value: float - Default float value
        - min: float|None - Minimum allowed value
        - max: float|None - Maximum allowed value
        - **kwargs: Additional TraitType parameters
        """

class CFloat(Float):
    """
    Casting version of Float that attempts to convert values to floats.
    
    Tries to cast values to float before validation.
    """
    
    def __init__(self, default_value=0.0, min=None, max=None, **kwargs):
        """
        Initialize casting float trait.
        
        Parameters:
        - default_value: float - Default float value
        - min: float|None - Minimum allowed value  
        - max: float|None - Maximum allowed value
        - **kwargs: Additional TraitType parameters
        """

Complex Number Types

Complex number trait types for mathematical computations.

class Complex(TraitType):
    """
    Complex number trait type.
    
    Validates complex number values.
    Default value is 0.0+0.0j.
    """
    
    def __init__(self, default_value=0.0+0.0j, **kwargs):
        """
        Initialize complex trait.
        
        Parameters:
        - default_value: complex - Default complex value
        - **kwargs: Additional TraitType parameters
        """

class CComplex(Complex):
    """
    Casting version of Complex that attempts to convert values to complex.
    
    Tries to cast values to complex before validation.
    """
    
    def __init__(self, default_value=0.0+0.0j, **kwargs):
        """
        Initialize casting complex trait.
        
        Parameters: 
        - default_value: complex - Default complex value
        - **kwargs: Additional TraitType parameters
        """

String Types

String trait types for text data with encoding handling.

class Bytes(TraitType):
    """
    Byte string trait type.
    
    Validates byte string (str in Python 2, bytes in Python 3).
    Default value is b''.
    """
    
    def __init__(self, default_value=b'', **kwargs):
        """
        Initialize bytes trait.
        
        Parameters:
        - default_value: bytes - Default bytes value
        - **kwargs: Additional TraitType parameters
        """

class CBytes(Bytes):
    """
    Casting version of Bytes that attempts to convert values to bytes.
    
    Tries to encode strings to bytes using utf-8.
    """
    
    def __init__(self, default_value=b'', **kwargs):
        """
        Initialize casting bytes trait.
        
        Parameters:
        - default_value: bytes - Default bytes value
        - **kwargs: Additional TraitType parameters
        """

class Unicode(TraitType):
    """
    Unicode string trait type.
    
    Validates unicode strings (unicode in Python 2, str in Python 3).
    Default value is u''.
    """
    
    def __init__(self, default_value=u'', **kwargs):
        """
        Initialize unicode trait.
        
        Parameters:
        - default_value: unicode|str - Default unicode value
        - **kwargs: Additional TraitType parameters
        """

class CUnicode(Unicode):
    """
    Casting version of Unicode that attempts to convert values to unicode.
    
    Tries to decode bytes to unicode using utf-8.
    """
    
    def __init__(self, default_value=u'', **kwargs):
        """
        Initialize casting unicode trait.
        
        Parameters:
        - default_value: unicode|str - Default unicode value
        - **kwargs: Additional TraitType parameters
        """

String Validation Types

Specialized string types with validation rules.

class ObjectName(TraitType):
    """
    String trait holding a valid Python object name.
    
    Validates that the string is a valid Python identifier.
    """
    
    def __init__(self, default_value=u'', **kwargs):
        """
        Initialize object name trait.
        
        Parameters:
        - default_value: str - Default identifier name
        - **kwargs: Additional TraitType parameters
        """

class DottedObjectName(TraitType):
    """
    String trait holding a valid dotted object name.
    
    Validates dotted names like "A.b3._c" where each component
    is a valid Python identifier.
    """
    
    def __init__(self, default_value=u'', **kwargs):
        """
        Initialize dotted object name trait.
        
        Parameters:
        - default_value: str - Default dotted name
        - **kwargs: Additional TraitType parameters  
        """

Boolean Types

Boolean trait types for true/false values.

class Bool(TraitType):
    """
    Boolean trait type.
    
    Validates boolean values (True/False).
    Default value is False.
    """
    
    def __init__(self, default_value=False, **kwargs):
        """
        Initialize boolean trait.
        
        Parameters:
        - default_value: bool - Default boolean value
        - **kwargs: Additional TraitType parameters
        """

class CBool(Bool):
    """
    Casting version of Bool that attempts to convert values to boolean.
    
    Casts values to bool using Python's truth testing.
    """
    
    def __init__(self, default_value=False, **kwargs):
        """
        Initialize casting boolean trait.
        
        Parameters:
        - default_value: bool - Default boolean value
        - **kwargs: Additional TraitType parameters
        """

Universal Type

Type that accepts any value without validation.

class Any(TraitType):
    """
    Trait type that allows any value.
    
    No validation is performed - accepts any Python value.
    Default value is None.
    """
    
    def __init__(self, default_value=None, **kwargs):
        """
        Initialize any-type trait.
        
        Parameters:
        - default_value: any - Default value (typically None)
        - **kwargs: Additional TraitType parameters
        """

Usage Examples

Numeric Constraints

from traitlets import HasTraits, Int, Float

class Rectangle(HasTraits):
    width = Int(min=1, max=1000)      # Width between 1-1000
    height = Int(min=1, max=1000)     # Height between 1-1000  
    area = Float(min=0.0)             # Non-negative area

rect = Rectangle(width=10, height=20)
rect.area = rect.width * rect.height  # 200.0
# rect.width = 0      # Would raise TraitError (below minimum)
# rect.height = 1500  # Would raise TraitError (above maximum)

String Validation

from traitlets import HasTraits, Unicode, ObjectName, DottedObjectName

class ClassDefinition(HasTraits):
    name = ObjectName()              # Valid Python identifier
    module = DottedObjectName()      # Valid dotted module name
    docstring = Unicode()            # Any unicode string

cls_def = ClassDefinition(
    name="MyClass",
    module="my.package.module", 
    docstring="A sample class"
)

# cls_def.name = "123invalid"     # Would raise TraitError (invalid identifier)
# cls_def.module = "my..invalid"  # Would raise TraitError (invalid dotted name)

Type Casting

from traitlets import HasTraits, CInt, CFloat, CBool

class FlexibleTypes(HasTraits):
    count = CInt()       # Casts to int
    ratio = CFloat()     # Casts to float  
    enabled = CBool()    # Casts to bool

obj = FlexibleTypes()
obj.count = "42"        # Automatically converts to 42
obj.ratio = "3.14"      # Automatically converts to 3.14
obj.enabled = "yes"     # Automatically converts to True

Default Values

from traitlets import HasTraits, Unicode, Int, Bool

class Configuration(HasTraits):
    host = Unicode(u"localhost")     # Default host
    port = Int(8080)                 # Default port
    debug = Bool(False)              # Default debug off
    name = Unicode()                 # Default empty string u''

config = Configuration()
print(config.host)   # "localhost"
print(config.port)   # 8080  
print(config.debug)  # False
print(config.name)   # u''

Install with Tessl CLI