python/lib/deprecated_enum/deprecated_enum/__init__.py

   1 # -*- coding: utf-8 -*-
   2
   3 # enum.py
   4 # Part of enum, a package providing enumerated types for Python.
   5 #
   6 # Copyright © 2007–2009 Ben Finney <ben+python@benfinney.id.au>
   7 # This is free software; you may copy, modify and/or distribute this work
   8 # under the terms of the GNU General Public License, version 2 or later
   9 # or, at your option, the terms of the Python license.
  10
  11 """ Robust enumerated type support in Python.
  12
  13 This package provides a module for robust enumerations in Python.
  14
  15 An enumeration object is created with a sequence of string arguments
  16 to the Enum() constructor::
  17
  18     >>> from enum import Enum
  19     >>> Colours = Enum('red', 'blue', 'green')
  20     >>> Weekdays = Enum('mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun')
  21
  22 The return value is an immutable sequence object with a value for each
  23 of the string arguments. Each value is also available as an attribute
  24 named from the corresponding string argument::
  25
  26     >>> pizza_night = Weekdays[4]
  27     >>> shirt_colour = Colours.green
  28
  29 The values are constants that can be compared only with values from
  30 the same enumeration; comparison with other values will invoke
  31 Python's fallback comparisons::
  32
  33     >>> pizza_night == Weekdays.fri
  34     True
  35     >>> shirt_colour > Colours.red
  36     True
  37     >>> shirt_colour == "green"
  38     False
  39
  40 Each value from an enumeration exports its sequence index
  41 as an integer, and can be coerced to a simple string matching the
  42 original arguments used to create the enumeration::
  43
  44     >>> str(pizza_night)
  45     'fri'
  46     >>> shirt_colour.index
  47     2
  48 """
  49
  50 \f
  51 __author_name__ = "Ben Finney"
  52 __author_email__ = "ben+python@benfinney.id.au"
  53 __author__ = "%(__author_name__)s <%(__author_email__)s>" % vars()
  54
  55 _copyright_year_begin = "2007"
  56 __date__ = "2009-08-26"
  57 _copyright_year_latest = __date__.split('-')[0]
  58 _copyright_year_range = _copyright_year_begin
  59 if _copyright_year_latest > _copyright_year_begin:
  60     _copyright_year_range += "–%(_copyright_year_latest)s" % vars()
  61 __copyright__ = (
  62     "Copyright © %(_copyright_year_range)s"
  63     " %(__author_name__)s") % vars()
  64 __license__ = "Choice of GPL or Python license"
  65
  66 __url__ = "http://pypi.python.org/pypi/enum/"
  67 __version__ = "0.4.4"
  68
  69 \f
  70 class EnumException(Exception):
  71     """ Base class for all exceptions in this module. """
  72
  73     def __init__(self, *args, **kwargs):
  74         if self.__class__ is EnumException:
  75             class_name = self.__class__.__name__
  76             raise NotImplementedError(
  77                 "%(class_name)s is an abstract base class" % vars())
  78         super(EnumException, self).__init__(*args, **kwargs)
  79
  80
  81 class EnumEmptyError(AssertionError, EnumException):
  82     """ Raised when attempting to create an empty enumeration. """
  83
  84     def __str__(self):
  85         return "Enumerations cannot be empty"
  86
  87
  88 class EnumBadKeyError(TypeError, EnumException):
  89     """ Raised when creating an Enum with non-string keys. """
  90
  91     def __init__(self, key):
  92         self.key = key
  93
  94     def __str__(self):
  95         return "Enumeration keys must be strings: %(key)r" % vars(self)
  96
  97
  98 class EnumImmutableError(TypeError, EnumException):
  99     """ Raised when attempting to modify an Enum. """
 100
 101     def __init__(self, *args):
 102         self.args = args
 103
 104     def __str__(self):
 105         return "Enumeration does not allow modification"
 106
 107 \f
 108 def _comparator(func):
 109     """ Decorator for EnumValue rich comparison methods. """
 110     def comparator_wrapper(self, other):
 111         try:
 112             assert self.enumtype == other.enumtype
 113             result = func(self.index, other.index)
 114         except (AssertionError, AttributeError):
 115             result = NotImplemented
 116
 117         return result
 118     comparator_wrapper.__name__ = func.__name__
 119     comparator_wrapper.__doc__ = getattr(float, func.__name__).__doc__
 120     return comparator_wrapper
 121
 122 class EnumValue(object):
 123     """ A specific value of an enumerated type. """
 124
 125     def __init__(self, enumtype, index, key):
 126         """ Set up a new instance. """
 127         self._enumtype = enumtype
 128         self._index = index
 129         self._key = key
 130
 131     @property
 132     def enumtype(self):
 133         return self._enumtype
 134
 135     @property
 136     def key(self):
 137         return self._key
 138
 139     def __str__(self):
 140         return str(self.key)
 141
 142     @property
 143     def index(self):
 144         return self._index
 145
 146     def __repr__(self):
 147         return "EnumValue(%(_enumtype)r, %(_index)r, %(_key)r)" % vars(self)
 148
 149     def __hash__(self):
 150         return hash(self._index)
 151
 152     @_comparator
 153     def __eq__(self, other):
 154         return (self == other)
 155
 156     @_comparator
 157     def __ne__(self, other):
 158         return (self != other)
 159
 160     @_comparator
 161     def __lt__(self, other):
 162         return (self < other)
 163
 164     @_comparator
 165     def __le__(self, other):
 166         return (self <= other)
 167
 168     @_comparator
 169     def __gt__(self, other):
 170         return (self > other)
 171
 172     @_comparator
 173     def __ge__(self, other):
 174         return (self >= other)
 175
 176 \f
 177 class Enum(object):
 178     """ Enumerated type. """
 179
 180     def __init__(self, *keys, **kwargs):
 181         """ Create an enumeration instance. """
 182
 183         value_type = kwargs.get('value_type', EnumValue)
 184
 185         if not keys:
 186             raise EnumEmptyError()
 187
 188         keys = tuple(keys)
 189         values = [None] * len(keys)
 190
 191         for i, key in enumerate(keys):
 192             value = value_type(self, i, key)
 193             values[i] = value
 194             try:
 195                 super(Enum, self).__setattr__(key, value)
 196             except TypeError:
 197                 raise EnumBadKeyError(key)
 198
 199         self.__dict__['_keys'] = keys
 200         self.__dict__['_values'] = values
 201
 202     def __setattr__(self, name, value):
 203         raise EnumImmutableError(name)
 204
 205     def __delattr__(self, name):
 206         raise EnumImmutableError(name)
 207
 208     def __len__(self):
 209         return len(self._values)
 210
 211     def __getitem__(self, index):
 212         return self._values[index]
 213
 214     def __setitem__(self, index, value):
 215         raise EnumImmutableError(index)
 216
 217     def __delitem__(self, index):
 218         raise EnumImmutableError(index)
 219
 220     def __iter__(self):
 221         return iter(self._values)
 222
 223     def __contains__(self, value):
 224         is_member = False
 225         if isinstance(value, basestring):
 226             is_member = (value in self._keys)
 227         else:
 228             is_member = (value in self._values)
 229         return is_member
 230
 231 \f
 232 # Local variables:
 233 # mode: python
 234 # time-stamp-format: "%:y-%02m-%02d"
 235 # time-stamp-start: "__date__ = \""
 236 # time-stamp-end: "\"$"
 237 # time-stamp-line-limit: 200
 238 # End:
 239 # vim: filetype=python fileencoding=utf-8 :