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[source]¶

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)[source]¶

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)[source]¶

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[source]¶

Bases: object

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

Raises TypeError:
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`
	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()[source]¶

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)[source]¶

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)[source]¶

Try to get constant by it’s name.

Raises KeyError:
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
	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()[source]¶

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()[source]¶: Same as constants() but returns an interator.

classmethod iteritems()[source]¶: Same as items() but returns an interator.

classmethod iternames()[source]¶: Same as names() but returns an interator.

classmethod names()[source]¶

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']

Module contents¶

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

class candv.Choices[source]¶

Bases: candv.base.ConstantsContainer

Container of instances of VerboseConstant and it’s subclasses.

Provides support for building Django-compatible choices.

classmethod choices()[source]¶

Get a tuple of tuples representing constant’s name and its verbose name.

Returns:	a tuple of constant’s names and their verbose names in order they were defined.

Example:

>>> from candv import Choices, VerboseConstant
>>> class FOO(Choices):
...     ONE = VerboseConstant("first", help_text="first choice")
...     FOUR = VerboseConstant("fourth")
...     THREE = VerboseConstant("third")
...
>>> FOO.choices()
(('ONE', 'first'), ('FOUR', 'fourth'), ('THREE', 'third'))
>>> FOO.get_by_name('ONE').help_text
'first choice'

constant_class¶

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

alias of VerboseConstant

class candv.Constants[source]¶

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)[source]¶

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)[source]¶: Redefines merge_into_group() and adds value attribute to the target group.

class candv.Values[source]¶

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)[source]¶

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)[source]¶

Get constant by its value.

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

classmethod itervalues()[source]¶: Same as values() but returns an interator.

classmethod values()[source]¶

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']

class candv.VerboseConstant(verbose_name=None, help_text=None)[source]¶

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)[source]¶

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)[source]¶: 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)[source]¶

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`