Return to index

Module rstdoc.misclibs.util


Module util

Utility methods and classes.

Imports:
rstdoc.misclibs.functional, sys, types, unittest
Classes:
Enum(object): Defines an object with attributes that enumerate a sequence of values:
Once(Property): Creates a property that is calculated at most 1 time. This idea was borrowed from the PEAK package. In the following example, note that the 'getValue' method is only executed once:
Property(object): Creates a descripter class (property).
PropertyClass(type): Meta class for Property class.
UNDEFINED(object): A unique value for keyword argument defaults.
Methods:
Constant(value, doc=None): Returns a property that returns a constant value.
DefaultProperty(default=UNDEFINED): Creates a Property instance with an optional default value.
abstractMethod(fn): The method decorated by the function will raise a NotImplementedError if called:
initAttrs(instance, **attrs):
printable(s):
testSuite(): Returns doctest testsuite for module.
toString(s, encoding='iso-8859-1', errors='replace'):
toUnicode(s, encoding='iso-8859-1', errors='replace'):
Attributes:
UNDEFINED = UNDEFINED()
__all__ = ['UNDEFINED', 'Enum', 'Once', 'Property', 'Constant', 'DefaultProperty', 'abstractMethod', 'initAttrs', 'toUnicode', 'toString']

Class util.Enum

Back to util

Bases:
object

Defines an object with attributes that enumerate a sequence of values:

>>> class SomeClass(object):
...     enum = Enum("zero", "one", "two")
>>> SomeClass().enum.zero
0
>>> SomeClass().enum.one
1
>>> SomeClass().enum.two
2
>>> SomeClass().enum.oops
Traceback (most recent call last):
    ...
AttributeError: Invalid attribute for Enum: 'oops'

The starting value can also be set:

>>> class SomeClass(object):
...     enum = Enum("zero", "one", "two",
...         start = 1000)
>>> SomeClass().enum.zero
1000
>>> SomeClass().enum.one
1001
>>> SomeClass().enum.two
1002

The Enum class can also be used outside a class definition:

>>> test = Enum("zero", "one", "two")
>>> test.zero
0

Enum values can be iterated over as follows (producing a series of (attr, value) pairs):

>>> [v for v in test]
[('zero', 0), ('one', 1), ('two', 2)]

The index operator will return the string value of the Enum:

>>> test[test.zero]
'zero'
Methods:
__getattr__(self, attr):
__getitem__(self, item):
__init__(self, *values, **kw):
__iter__(self):

Class util.Once

Back to util

Bases:
Property

Creates a property that is calculated at most 1 time. This idea was borrowed from the PEAK package. In the following example, note that the 'getValue' method is only executed once:

>>> import inspect
>>> class SomeClass(object):
...     class aProp(Once):
...         "Some Doc String"
...
...         def value(self, instance):
...             print "This is executed once"
...             return "Some Value"
>>> test = SomeClass()
>>> test.aProp
This is executed once
'Some Value'
>>> test.aProp
'Some Value'
>>> inspect.getdoc(SomeClass.aProp)
'Some Doc String'

If the attribute is deleted, then the getValue method will be executed again:

>>> del test.aProp
>>> test.aProp
This is executed once
'Some Value'
>>> test.aProp
'Some Value'

The value method or class attribute must be defined:

>>> class SomeClass(object):
...     class aProp(Once):
...         pass
Traceback (most recent call last):
    ...
AttributeError: A class attribute or method
    'value' must be declared for the Once
    attribute 'aProp'

The Once class is a subclass of Property, however, the fget, fset, fdel, and default methods/attributes must not be defined:

>>> class SomeClass(object):
...     class aProp(Once):
...         def value(self, instance): pass
...         def fget(self, instance): pass
Traceback (most recent call last):
    ...
AttributeError: The Once attribute 'aProp'
    cannot define fget/fset/fdel/default
    methods or attributes
>>> class SomeClass(object):
...     class aProp(Once):
...         def value(self, instance): pass
...         def fset(self, instance): pass
Traceback (most recent call last):
    ...
AttributeError: The Once attribute 'aProp'
    cannot define fget/fset/fdel/default
    methods or attributes
>>> class SomeClass(object):
...     class aProp(Once):
...         def value(self, instance): pass
...         def fdel(self, instance): pass
Traceback (most recent call last):
    ...
AttributeError: The Once attribute 'aProp'
    cannot define fget/fset/fdel/default
    methods or attributes
>>> class SomeClass(object):
...     class aProp(Once):
...         def value(self, instance): pass
...         def default(self, instance): pass
Traceback (most recent call last):
    ...
AttributeError: The Once attribute 'aProp'
    cannot define fget/fset/fdel/default
    methods or attributes

Attribute assignment is not allowed:

>>> test.aProp = "Oops"
Traceback (most recent call last):
    ...
AttributeError: Can't set attribute
Methods:
__delete__(self, instance):
__get__(self, instance, owner):
__init__(self):
Attributes:
fget = fset = fdel = default = None
isClass = True

Class util.Property

Back to util

Bases:
object

Creates a descripter class (property).

To create a attribute with default fget, fset, and fdel methods simply subclass Property:

>>> import inspect
>>> class SomeClass(object):
...     class aProp(Property):
...         "My Property"
>>> test = SomeClass()
>>> test.aProp = 1
>>> test.aProp
1
>>> inspect.getdoc(SomeClass.aProp)
'My Property'

It is also possible to assign a default value:

>>> class SomeClass(object):
...     class aProp(Property):
...         default = "Default Value"
>>> test = SomeClass()
>>> test.aProp
'Default Value'
>>> test.aProp = "Assigned Value"
>>> test.aProp
'Assigned Value'

If the attribute is deleted then the attribute reverts to the default value (if any):

>>> del test.aProp
>>> test.aProp
'Default Value'

The default can also be defined as a 2-argument callable:

>>> class SomeClass(object):
...     class aProp(Property):
...         fset = fget = fdel = True
...         def default(self, instance):
...             return instance
>>> SomeClass.aProp
<...util.aProp object at 0x...>

If no default value is given, and no assignment to the attribute is perfomed, then an AttributeError is raised:

>>> class SomeClass(object):
...     class aProp(Property):
...         "My Property"
...         fset = fget = fdel = True
>>> SomeClass().aProp
Traceback (most recent call last):
    ...
AttributeError: Undefined attribute 'aProp'
        with no default given

Custom fget, fset, and fdel methods can also be provided:

>>> class SomeClass(object):
...     class aProp(Property):
...         default = "Default Value"
...         fset = fget = fdel = True
...         def fget(self, instance):
...             return ('custom: ' +
...                 self.getDefault(instance))
>>> SomeClass().aProp
'custom: Default Value'

When defining a custom method, the getValue, getDefault, and setValue methods can be used to assign values to a unique attribute of the 'instance'. The method argument 'self' refers to the Property instance, the argument 'instance' refers to the containing class:

>>> class SomeClass(object):
...     class aProp(Property):
...         fset = fget = fdel = True
...         def fget(self, instance):
...             print "Self:", self
...             print "Instance:", instance
>>> SomeClass().aProp
Self: <...util.aProp object at 0x...>
Instance: <...util.SomeClass object at 0x...>

Therefore, values assigned to self will be shared among all instances of the containing class:

>>> class SomeClass(object):
...     class aProp(Property):
...         fset = fget = fdel = True
...         def fset(self, instance, value):
...             self.test = value
...         def fget(self, instance):
...             return self.test
>>> test1 = SomeClass()
>>> test2 = SomeClass()
>>> test1.aProp = 1
>>> test2.aProp = 2
>>> test1.aProp
2

Each subclass of Property is assigned two special attributes which can be used to create unique variables in the instance's dictionary:

>>> class SomeClass(object):
...     class aProp(Property):
...         def fget(self, instance):
...             print '__name__ = ', self.__name__
...             print '__varname__ = ', self.__varname__
>>> SomeClass().aProp
__name__ =  aProp
__varname__ =  __aProp_000...

The Property.getValue, Property.getDefault, and Property.setValue methods can be used to assign and retrieve values from the instance's dictionary.

If fget, fset, fdel are assigned the value None then the corosponding attribute access is not possible:

>>> class SomeClass(object):
...     class aProp(Property):
...         fget = fset = fdel = None
>>> SomeClass().aProp
Traceback (most recent call last):
    ...
AttributeError: Can't get attribute
Methods:
__delete__(self, instance):
__get__(self, instance, owner):
__init__(self):
__set__(self, instance, value):
delValue(self, instance):
getDefault(self, instance):
getValue(self, instance):
setValue(self, instance, value):
Attributes:
__metaclass__ = PropertyClass
default = UNDEFINED
fget = fset = fdel = True
isClass = True

Class util.PropertyClass

Back to util

Bases:
type

Meta class for Property class.

Methods:
__new__(klass, name, bases, cdict):
Attributes:
nextId = count().next

Method util.Constant

Back to util

Arguments:
value, doc=None

Returns a property that returns a constant value.

>>> import inspect
>>> class SomeClass(object):
...     aProp = Constant(5, doc = "Some Doc String")
>>> SomeClass().aProp
5
>>> inspect.getdoc(SomeClass.aProp)
'Some Doc String'

Method util.DefaultProperty

Back to util

Arguments:
default=UNDEFINED

Creates a Property instance with an optional default value.

If a default is given, then it used as the initial value of the attribute:

>>> class SomeClass(object):
...     aProp = DefaultProperty(5)
>>> test = SomeClass()
>>> test.aProp
5

The attribute can be set normally:

>>> test.aProp = 1
>>> test.aProp
1

If no default is given then the value of the property must be set before it is accessed:

>>> class SomeClass(object):
...     aProp = DefaultProperty()
>>> test = SomeClass()
>>> test.aProp
Traceback (most recent call last):
    ...
AttributeError: Undefined attribute 'Property'
    with no default given

Once the attribute has been set then it can be accessed normally:

>>> test.aProp = 1
>>> test.aProp
1

Method util.abstractMethod

Back to util

Arguments:
fn

The method decorated by the function will raise a NotImplementedError if called:

>>> class Test:
...     @abstractMethod
...     def test(*args, **kw):
...         " Override me "
...         pass
>>> Test().test()
Traceback (most recent call last):
    ...
NotImplementedError: Call of abstract method: 'test'
>>> print Test().test.__doc__
Override me
Methods:
abstractMethod(self, *args, **kw):

Method util.testSuite

Back to util

Arguments:

Returns doctest testsuite for module.

Imports:
doctest, util