mrv.enum

Epydoc: mrv.enum

This module is designed to be the equivalent of the enum type in other languages. An enumeration object is created at run time, and contains named members that are the enumeration elements.

The enumeration is also a tuple of all of the values in it. You can iterate through the values, perform ‘in’ tests, slicing, etc. It also includes functions to lookup specific values by name, or names by value.

You can specify your own element values, or use the create factory method to create default Elements. These elements are unique system wide, and are ordered based on the order of the elements in the enumeration. They also are _repr_’d by the name of the element, which is convenient for testing, debugging, and generation text output.

Example Code:

>>>     # Using Element values
>>> Colors = Enumeration.create('red', 'green', 'blue')

>>> # Using explicitly specified values
>>>Borders = Enumeration.create(('SUNKEN', 1),
>>>                                                             ('RAISED', 32),
>>>                                                             ('FLAT', 2))

>>> x = Colors.red
>>> y = Colors.blue

>>> assert x < y
>>> assert x == Colors('red')
>>> assert Borders.FLAT == 2:
>>> assert 1 in Borders

note:slightly modified by Sebastian Thiel to be more flexible and suitable as base class

Functions

mrv.enum.create(*elements, **kwargs)

Factory method for Enumerations. Accepts of list of values that can either be strings or (name, value) tuple pairs. Strings will have an Element created for use as their value. If you provide elements, the member returned when you access the enumeration will be the element itself.

Example: Enumeration.create(‘fred’, ‘bob’, (‘joe’, 42)) Example: Enumeration.create(‘fred’, cls = EnumerationSubClass ) Example: Enumeration.create(Element(‘fred’, Marge), ...)

Parameter:kwargs –

• cls: The class to create an enumeration with, must be an instance of Enumeration
• elmcls: The class to create elements from, must be instance of Element

• bitflag: if True, default False, the values created will be suitable as bitflags.

  This will fail if you passed more items in than supported by the OS ( 32 , 64, etc ) or if you pass in tuples and thus define the values yourself.

Raises TypeError,ValueError:  if bitflags cannot be supported in your case

Classes

Epydoc: mrv.enum.Element

class mrv.enum.Element(name, value)

Bases: object

Internal helper class used to represent an ordered abstract value.

The values have string representations, have strictly defined ordering (inside the set) and are never equal to anything but themselves.

They are usually created through the create factory method as values for Enumerations.

They assume that the enumeration member will be filled in before any comparisons are used. This is done by the Enumeration constructor.

name()

Returns:name of the element

value()

Returns:own value

Epydoc: mrv.enum.Enumeration

class mrv.enum.Enumeration(names, values, **kwargs)

Bases: tuple

This class represents an enumeration. You should not normally create multiple instances of the same enumeration, instead create one with however many references are convenient.

The enumeration is a tuple of all of the values in it. You can iterate through the values, perform ‘in’ tests, slicing, etc. It also includes functions to lookup specific values by name, or names by value.

You can specify your own element values, or use the create factory method to create default Elements. These elements are unique system wide, and are ordered based on the order of the elements in the enumeration. They also are _repr_’d by the name of the element, which is convenient for testing, debugging, and generation text output.

Note:pickling this class with Elements will fail as they contain cyclic references that it cannot deal with Todo:implement proper pickle __getstate__ and __setstate__ that deal with that problem

count

T.count(value) -> integer – return number of occurrences of value

index

T.index(value, [start, [stop]]) -> integer – return first index of value. Raises ValueError if the value is not present.

nameFromValue(value)

Look up the name of an enumeration element, given it’s value.

If there are multiple elements with the same value, you will only get a single matching name back. Which name is undefined.

Raises ValueError:  if value is not a part of our enumeration

next(element, wrap_around=False)

Returns:

element following after given element

Parameters:

• element – element whose successor to return
• wrap_around – if True, the first Element will be returned if there is no next element

Raises ValueError:  

if wrap_around is False and there is no next element

previous(element, wrap_around=False)

Returns:

element coming before the given element

Parameters:

• element – element whose predecessor to return
• wrap_around – see next

Raises ValueError:  

if wrap_around is False and there is no previous element

valueFromName(name)

Look up the enumeration value for a given element name.

Raises ValueError: