candv package

candv.base module

This module defines base constant and base container for constants. All other stuff must be derived from them.

Each container has constant_class attribute. It specifies class of constants which will be defined within contaner.

class candv.base.Constant

Bases: object

Base class for all constants. Can be merged into a container instance.

Variables:name (str) – constant’s name. Is set up automatically and is equal to the name of container’s attribute

merge_into_group(group)

Called automatically by container after group construction.

Note

Redefine this method in all derived classes. Attach all custom attributes and methods to the group here.

Parameters:group – an instance of ConstantsContainer or it’s subclass this constant will be merged into Returns:None

to_group(group_class, **group_members)

Convert a constant into a constants group.

Parameters:

• group_class (class) – a class of group container which will be created
• group_members – unpacked dict which defines group members.

Returns:

a lazy constants group which will be evaluated by container. During group evaluation merge_into_group() will be called.

Example:

from candv import Constants, SimpleConstant

class FOO(Constants):
    A = SimpleConstant()
    B = SimpleConstant().to_group(Constants,
        B2=SimpleConstant(),
        B0=SimpleConstant(),
        B1=SimpleConstant(),
)

class candv.base.ConstantsContainer

Bases: object

Base class for creating constants containers. Each constant defined within container will remember it’s creation order. See an example in constants().

Variables:constant_class – stores a class of constants which can be stored by container. This attribute MUST be set up manually when you define a new container type. Otherwise container will not be initialized. Default: None Raises TypeError:  if you try to create an instance of container. Containers are singletons and they cannot be instantiated. Their attributes must be used directly.

constant_class = None

Defines a top-level class of constants which can be stored by container

classmethod constants()

List all constants in container.

Returns:list of constants in order they were defined Return type:list

Example:

>>> from candv import Constants, SimpleConstant
>>> class FOO(Constants):
...     foo = SimpleConstant()
...     bar = SimpleConstant()
...
>>> [x.name for x in FOO.constants()]
['foo', 'bar']

classmethod contains(name)

Check if container has a constant with a given name.

Parameters:name (str) – a constant’s name to check Returns:True if given name belongs to container, False otherwise Return type:bool

classmethod get_by_name(name)

Try to get constant by it’s name.

Parameters:name (str) – name of constant to search for Returns:a constant Return type:a class specified by constant_class which is Constant or it’s subclass Raises KeyError:  if constant name name is not present in container

Example:

>>> from candv import Constants, SimpleConstant
>>> class FOO(Constants):
...     foo = SimpleConstant()
...     bar = SimpleConstant()
...
>>> FOO.get_by_name('foo')
<constant 'FOO.foo'>

classmethod items()

Get list of constants with their names.

Returns:list of constants with their names in order they were defined. Each element in list is a tuple in format (name, constant). Return type:list

Example:

>>> from candv import Constants, SimpleConstant
>>> class FOO(Constants):
...     foo = SimpleConstant()
...     bar = SimpleConstant()
...
>>> FOO.items()
[('foo', <constant 'FOO.foo'>), ('bar', <constant 'FOO.bar'>)]

classmethod iterconstants()

Same as constants() but returns an interator.

classmethod iteritems()

Same as items() but returns an interator.

classmethod iternames()

Same as names() but returns an interator.

classmethod itervalues()

New since 1.1.2.

Alias for iterconstants(). Added for consistency with dictionaries. Use Values and itervalues() if you need to have constants with real values.

classmethod names()

List all names of constants within container.

Returns:a list of constant names in order constants were defined Return type:list of strings

Example:

>>> from candv import Constants, SimpleConstant
>>> class FOO(Constants):
...     foo = SimpleConstant()
...     bar = SimpleConstant()
...
>>> FOO.names()
['foo', 'bar']

classmethod values()

New since 1.1.2.

Alias for constants(). Added for consistency with dictionaries. Use Values and values() if you need to have constants with real values.

Module contents

This module provides ready-to-use classes for constructing custom constants.

class candv.Constants

Bases: candv.base.ConstantsContainer

Simple container for any Constant or it’s subclass. This container can be used as enumeration.

Example:

>>> from candv import Constants, SimpleConstant
>>> class USER_ROLES(Constants):
...     ADMIN = SimpleConstant()
...     ANONYMOUS = SimpleConstant()
...
>>> USER_ROLES.ADMIN
<constant 'USER_ROLES.ADMIN'>
>>> USER_ROLES.get_by_name('ANONYMOUS')
<constant 'USER_ROLES.ANONYMOUS'>

constant_class

Set Constant as top-level class for this container. See constant_class.

alias of Constant

class candv.ValueConstant(value)

Bases: candv.base.Constant

Extended version of SimpleConstant which provides support for storing values of constants.

Parameters:value – a value to attach to constant Variables:value – constant’s value

merge_into_group(group)

Redefines merge_into_group() and adds value attribute to the target group.

class candv.Values

Bases: candv.base.ConstantsContainer

Constants container which supports getting and filtering constants by their values, listing values of all constants in container.

constant_class

Set ValueConstant as top-level class for this container. See constant_class.

alias of ValueConstant

classmethod filter_by_value(value)

Get all constants which have given value.

Parameters:value – value of the constants to look for Returns:list of all found constants with given value

classmethod get_by_value(value)

Get constant by its value.

Parameters:value – value of the constant to look for Returns:first found constant with given value Raises ValueError:  if no constant in container has given value

classmethod itervalues()

Same as values() but returns an interator.

Note

Overrides itervalues() since 1.1.2.

classmethod values()

List values of all constants in the order they were defined.

Returns:list of values

Example:

>>> from candv import Values, ValueConstant
>>> class FOO(Values):
...     TWO = ValueConstant(2)
...     ONE = ValueConstant(1)
...     SOME = ValueConstant("some string")
...
>>> FOO.values()
[2, 1, 'some string']

Note

Overrides values() since 1.1.2.

class candv.VerboseConstant(verbose_name=None, help_text=None)

Bases: candv.VerboseMixin, candv.base.Constant

Constant with optional verbose name and optional description.

Parameters:

• verbose_name (str) – optional verbose name of the constant
• help_text (str) – optional description of the constant

Variables:

• verbose_name (str) – verbose name of the constant. Default: None
• help_text (str) – verbose description of the constant. Default: None

class candv.VerboseMixin(*args, **kwargs)

Bases: object

Provides support of verbose names and help texts. Must be placed at the left side of non-mixin base classes due to Python’s MRO. Arguments must be passed as kwargs.

Parameters:

• verbose_name (str) – optional verbose name
• help_text (str) – optional description

Example:

class Foo(object):

    def __init__(self, arg1, arg2, kwarg1=None):
        pass


class Bar(VerboseMixin, Foo):

    def __init__(self, arg1, arg2, verbose_name=None, help_text=None, kwarg1=None):
        super(Bar, self).__init__(arg1, arg2, verbose_name=verbose_name, help_text=help_text, kwarg1=kwarg1)

merge_into_group(group)

Redefines merge_into_group() and adds verbose_name and help_text attributes to the target group.

class candv.VerboseValueConstant(value, verbose_name=None, help_text=None)

Bases: candv.VerboseMixin, candv.ValueConstant

A constant which can have both verbose name, help text and a value.

Parameters:

• value – a value to attach to the constant
• verbose_name (str) – optional verbose name of the constant
• help_text (str) – optional description of the constant

Variables:

• value – constant’s value
• verbose_name (str) – verbose name of the constant. Default: None
• help_text (str) – verbose description of the constant. Default: None