Metadata-Version: 2.1
Name: editabletuple
Version: 1.3.1
Summary: Provides the editabletuple function for creating classes with a fixed sequence of fields, similar to a namedtuple, except editable
Home-page: https://github.com/mark-summerfield/editabletuple
Author: Mark Summerfield
Author-email: mark@qtrac.eu
License: GPLv3
Description: # editabletuple
        
        This module provides the editabletuple() and editableobject() functions.
        
        The editabletuple() function is used tor creating classes with a fixed
        sequence of fields, similar to a namedtuple, except editable.
        
        Each instance of a class created by the `editabletuple()` function's fields
        can be accessed by index `et[i]` (or by slice), or by fieldname `et.name`.
        Although fields can be read and written, they cannot be added or deleted.
        Since instances are mutable they can't be used in sets or as dict keys.
        
        If you provide a validator, it will be used when new instances are created
        and updated.
        
        The editableobject() function creates classes very similar to those created
        by editabletuple(). The essential difference is that editableobject()'s
        class's instances don't support indexing or iteration, so support only
        fieldname access. They also have an addtional totuple property (not needed
        for editabletuple()s since tuple(et) is sufficient due to their iteration
        support).
        
        See the function docstrings for examples and more about the editabletuple
        and editableobject APIs.
        
        To install just use `python3 -m pip install editabletuple`.
        
        Or just copy the `editabletuple.py` file which is self-contained and depends
        only on the standard library.
        
        ## Example #1: no defaults; no validator
        
            >>> Options = editabletuple('Options', 'maxcolors shape zoom restore')
            >>> options = Options(5, 'square', 0.9, True)
            >>> options
            Options(maxcolors=5, shape='square', zoom=0.9, restore=True)
            >>> options.maxcolors = 7
            >>> options[-1] = False
            >>> options[2] -= 0.1
            >>> options
            Options(maxcolors=7, shape='square', zoom=0.8, restore=False)
        
        ## Example #2: with defaults but no validator
        
            >>> Rgb = editabletuple('Rgb', 'red green blue', defaults=(0, 0, 0))
            >>> black = Rgb()
            >>> black
            Rgb(red=0, green=0, blue=0)
            >>> navy = Rgb(blue=128)
            >>> navy
            Rgb(red=0, green=0, blue=128)
            >>> violet = Rgb(238, 130, 238)
            >>> violet
            Rgb(red=238, green=130, blue=238)
        
        ## Example #3: with defaults and a validator
        
        If you provide a validator function, it will be called whenever an attempt
        is made to set a value, whether at construction time or later by `et[i] =
        value` or `et.fieldname = value`. It is passed an attribute `name` and an
        attribute `value`. It should check the value and either return the value (or
        an acceptable alternative value) which will be the one actually set, or
        raise a `ValueError`.
        
            >>> def validate_rgba(name, value):
            ...     if name == 'alpha':
            ...         if not (0.0 <= value <= 1.0):
            ...             return 1.0 # silently default to opaque
            ...     elif not (0 <= value <= 255):
            ...         raise ValueError(f'color value must be 0-255, got {value}')
            ...     return value # must return a valid value or raise ValueError
            >>>
            >>> Rgba = editabletuple('Rgba', 'red', 'green', 'blue', 'alpha',
            ...                      defaults=(0, 0, 0, 1.0), validator=validate_rgba)
            >>> black = Rgba()
            >>> black
            Rgba(red=0, green=0, blue=0, alpha=1.0)
            >>> seminavy = Rgba(blue=128, alpha=0.5)
            >>> seminavy
            Rgba(red=0, green=0, blue=128, alpha=0.5)
            >>> violet = Rgba(238, 130, 238, alpha=2.5) # alpha too big
            >>> violet
            Rgba(red=238, green=130, blue=238, alpha=1.0)
            >>>
            >>> color = Rgba(green=99)
            >>> color
            Rgba(red=0, green=99, blue=0, alpha=1.0)
            >>> assert color.green == 99
            >>> color.red = 128
            >>> assert color[2] == 0
            >>> color[2] = 240
            >>> assert color[2] == 240
            >>> color[-1] = 0.5
            >>> color
            Rgba(red=128, green=99, blue=240, alpha=0.5)
            >>> color[1] = 299
            Traceback (most recent call last):
                ...
            ValueError: color value must be 0-255, got 299
            >>> color.blue = -65
            Traceback (most recent call last):
                ...
            ValueError: color value must be 0-255, got -65
        
        These examples—and some others—are in the module's function's docstrings.
        
        **License: GPLv3**
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
