Metadata-Version: 1.1
Name: enumr
Version: 1.0
Summary: Ranged enumeration data type
Home-page: https://github.com/xoiss/python-enumr
Author: Alexander A. Strelets
Author-email: StreletsAA@gmail.com
License: Public Domain
Download-URL: https://github.com/xoiss/python-enumr
Description: This package provides a base class `enumr` for ranged enumerations
        with reach annotation and formatting capabilities.
        
        If you are new to this package, study also the `subrange` package as it
        is used here as the class for ranged item instances. Reach annotation
        and formatting capabilities are strongly based on the `subrange` class.
        
        Define your custom ranged enum as a subclass of `enumr`. Provide item
        descriptors as described below. Then use class items freely as separate
        instances of `subrangef` class. Here is a basic example of ranged enum
        (this one does not use reach annotation and formatting)::
        
            from enumr import enumr
        
            class Devices(enumr):
                PRIMARY = 1                     # value 1
                SECONDARY = 2
                USER_DEFINED = (3, 10)          # subrange 3..10
                RESERVED = (11, 14)
                INVALID = 15
        
            print Devices.USER_DEFINED          # 3..10
            print Devices.USER_DEFINED.min      # 3
            print Devices.USER_DEFINED.max      # 10
            print 7 in Devices.USER_DEFINED     # True
            print 11 > Devices.USER_DEFINED     # True
            print 2 in Devices.SECONDARY        # True
            print 2 == Devices.SECONDARY        # True
            print "0x{:02X}".format(Devices.RESERVED)             # 0x0B..0E
            print "{0.value} {0.name!r}".format(Devices.INVALID)  # 15 'INVALID'
        
        See documentation to `subrange` package on which operations are
        supported by ranged items (that are instances of `subrangef` class).
        
        To use reach annotation and formatting capabilities add ``_ant_spec``
        and ``_str_spec`` to your subclass definition. This will change the
        default formatting of items::
        
            class Devices(enumr):
                _ant_spec = 'brief', 'ref'
                _str_spec = "{value} {brief!r}"
                PRIMARY = 1, "Primary device", "sub.10.2.1"
                USER_DEFINED = (3, 10), "User defined device", "sub.10.2.3"
        
            print Devices.PRIMARY           # 1 'Primary device'
            print Devices.USER_DEFINED      # 3..10 'User defined device'
        
            print Devices.PRIMARY.brief     # Primary device
            print Devices.PRIMARY.ref       # sub.10.2.1
        
            print "{0.value}: {0.brief!r}".format(Devices.USER_DEFINED)
            # 3..10: 'User defined device'
        
        Here are some more examples. Call to ``print Devices.USER_DEFINED`` will
        produce different output depending on ``_str_spec``::
        
            _str_spec = "0x{value:02X}"             # 0x03..0A
            _str_spec = "0x{min:02X}-{max:02X}"     # 0x03-0A
            _str_spec = "{name} = {value}"          # USER_DEFINED = 3..10
            _str_spec = "{brief!r}"                 # 'User defined device'
        
        See documentation to `enumr` class for more details on how to use reach
        annotation and formatting capabilities.
        
        Enumeration class also provides a facility to resolve arbitrary integer
        values to enumeration items::
        
            print Devices(1)            # 1 'Primary device'
            print Devices(7)            # 3..10 'User defined device'
            print Devices(20, None)     # None
            print Devices(20)       # raises ValueError: 20 is not in Devices
        
        Integer values are resolved in O(lb(m)) in the worst case, where m is
        the number of ranged items (i.e., items containing more than one
        value), lb(n) is the binary logarithm. If all items in the enum are
        single-value ranges, the given integer is resolved in O(1).
        
        There are different implementations of enum data type in Python. Some of
        them provide one-to-one relation between items and their values (and
        values must be integers), some allow multiple items to have the same
        value. Yet they support only one value per an item, but not a range (or
        set) of values.
        
        However, in some cases it might be very useful to consolidate a whole
        subrange of integer values under the same identifier, define a number of
        such subranges if needed, and be able to resolve the correct subrange (a
        ranged enum item) given an integer value. Such things may be met if we
        talk about classifiers, decoding tasks, etc. Covering a wide range of
        integer codes they may have very limited sets of fully defined items and
        a number of huge continuous ranges of values under names like
        'user_defined' or 'reserved'. Obviously, if it's not a tiny set of 8-bit
        codes, it would not be a good idea to put all the 'reserved' codes into
        a dictionary to be able to resolve arbitrary code. On the other hand
        constructing long if-else matchers is error-prone and not elegant (and
        also they consume O(n) to find the match, where n is the number of
        items). So, a ready-to-use data structure able to keep ranged enums and
        resolve codes to items might help. And now you have it.
        
Platform: Linux
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
