#!/usr/bin/env python
# -*- coding: utf-8 -*
"""
:description:
constant related module
*test-case-name: twisted.python.test.test_constants*
Copyright (c) Twisted Matrix Laboratories.
See LICENSE for details.
:license:
CUP dev team modified and redistrbuted this module,
according to MIT license
(http://opensource.org/licenses/mit-license.php)
that Twisted lib obeys.
If any concern, plz contact mythmgn@gmail.com.
Mit License applied for twisted
http://www.opensource.org/licenses/mit-license.php
Permission is hereby granted, free of charge,
to any person obtaining a copy of this software and associated
documentation files (the "Software"),
to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"""
from __future__ import division
__all__ = [
'NamedConstant', 'ValueConstant', 'FlagConstant',
'Names', 'Values', 'Flags']
import functools
import itertools
import operator
_UNSPECIFIED = None
_CONSTANT_ORDER = functools.partial(next, itertools.count())
class _Constant(object): # pylint: disable=R0903
"""
:ivar _index: A C{int} allocated from a shared itertools.counter in order
to keep track of the order in which L{_Constant}s are instantiated.
:ivar name: A C{str} giving the name of this constant; only set once the
constant is initialized by L{_ConstantsContainer}.
:ivar _container: The L{_ConstantsContainer} subclass this constant belongs
to; C{None} until the constant is initialized by that subclass.
"""
def __init__(self):
self._container = None
self._index = _CONSTANT_ORDER()
self.name = None
def __repr__(self):
"""
Return text identifying both which constant this is and
which collection it belongs to.
"""
return "<%s=%s>" % (self._container.__name__, self.name)
def _realize(self, container, name, value):
"""
Complete the initialization of this L{_Constant}.
:param container: The L{_ConstantsContainer} subclass this constant is
part of.
:param name: The name of this constant in its container.
:param value: The value of this constant; not used, as named constants
have no value apart from their identity.
"""
self._container = container
self.name = name
class _ConstantsContainerType(type):
"""
L{_ConstantsContainerType} is a metaclass for creating constants container
classes.
"""
def __new__(self, name, bases, attributes):
"""
Create a new constants container class.
If C{attributes} includes a value of C{None} for the C{"_constantType"}
key, the new class will not be initialized as a constants container and
it will behave as a normal class.
:param name: The name of the container class.
:type name: L{str}
:param bases: A tuple of the base classes for the new container class.
:type bases: L{tuple} of L{_ConstantsContainerType} instances
:param attributes: The attributes of the new container class, including
any constants it is to contain.
:type attributes: L{dict}
"""
cls = super(_ConstantsContainerType, self).__new__(
self, name, bases, attributes)
# Only realize constants in concrete _ConstantsContainer subclasses.
# Ignore intermediate base classes.
constantType = getattr(cls, '_constantType', None)
if constantType is None:
return cls
constants = []
for (name, descriptor) in attributes.items():
if isinstance(descriptor, cls._constantType):
if descriptor._container is not None:
raise ValueError(
"Cannot use %s as the value of an attribute on %s" % (
descriptor, cls.__name__))
constants.append((descriptor._index, name, descriptor))
enumerants = {}
for (index, enumerant, descriptor) in sorted(constants):
value = cls._constantFactory(enumerant, descriptor)
descriptor._realize(cls, enumerant, value)
enumerants[enumerant] = descriptor
# Save the dictionary which contains *only* constants (distinct from
# any
# other attributes the application may have given the container) where
# the class can use it later (eg for lookupByName).
cls._enumerants = enumerants
return cls
# In Python3 metaclasses are defined using a C{metaclass} keyword argument in
# the class definition. This would cause a syntax error in Python2.
# So we use L{type} to introduce an intermediate base class with the desired
# metaclass.
# See:
# * http://docs.python.org/2/library/functions.html# type
# * http://docs.python.org/3/reference/datamodel.html#
# customizing-class-creation
class _ConstantsContainer(_ConstantsContainerType('', (object, ), {})):
"""
L{_ConstantsContainer} is a class with attributes used as symbolic
constants. It is up to subclasses to specify what kind of constants are
allowed.
:cvar _constantType: Specified by a L{_ConstantsContainer} subclass to
specify the type of constants allowed by that subclass.
:cvar _enumerants: A C{dict} mapping the names of constants (eg
L{NamedConstant} instances) found in the class definition to those
instances.
"""
_constantType = None
def __new__(cls):
"""
Classes representing constants containers are not intended to be
instantiated.
The class object itself is used directly.
"""
raise TypeError("%s may not be instantiated." % (cls.__name__, ))
@classmethod
def _constantFactory(cls, name, descriptor):
"""
Construct the value for a new constant to add to this container.
:param name: The name of the constant to create.
:param descriptor: An instance of a L{_Constant} subclass (eg
L{NamedConstant}) which is assigned to C{name}.
:return: L{NamedConstant} instances have no value apart from identity,
so return a meaningless dummy value.
"""
return _UNSPECIFIED
@classmethod
def lookupByName(cls, name):
"""
Retrieve a constant by its name or raise a C{ValueError} if there is no
constant associated with that name.
:param name: A C{str} giving the name of one of the constants defined
by C{cls}.
:raise ValueError: If C{name} is not the name of one of the constants
defined by C{cls}.
:return: The L{NamedConstant} associated with C{name}.
"""
if name in cls._enumerants:
return getattr(cls, name)
raise ValueError(name)
@classmethod
def iterconstants(cls):
"""
Iteration over a L{Names} subclass results in all of the constants it
contains.
@return: an iterator the elements of which are the L{NamedConstant}
instances defined in the body of this L{Names} subclass.
"""
constants = cls._enumerants.values()
return iter(
sorted(constants, key=lambda descriptor: descriptor._index))
[docs]class NamedConstant(_Constant):
"""
L{NamedConstant} defines an attribute to be a named constant within a
collection defined by a L{Names} subclass.
L{NamedConstant} is only for use in the definition of L{Names}
subclasses. Do not instantiate L{NamedConstant} elsewhere and do not
subclass it.
"""
[docs]class Names(_ConstantsContainer):
"""
A L{Names} subclass contains constants which differ only in their names and
identities.
"""
_constantType = NamedConstant
[docs]class ValueConstant(_Constant):
"""
L{ValueConstant} defines an attribute to be a named constant within a
collection defined by a L{Values} subclass.
L{ValueConstant} is only for use in the definition of L{Values} subclasses.
Do not instantiate L{ValueConstant} elsewhere and do not subclass it.
"""
def __init__(self, value):
_Constant.__init__(self)
self.value = value
[docs]class Values(_ConstantsContainer):
"""
A L{Values} subclass contains constants which are associated with arbitrary
values.
"""
_constantType = ValueConstant
[docs] @classmethod
def lookupByValue(cls, value):
"""
Retrieve a constant by its value or raise a C{ValueError} if there is
no constant associated with that value.
:param value: The value of one of the constants defined by C{cls}.
:raise ValueError: If C{value} is not the value of one of the constants
defined by C{cls}.
:return: The L{ValueConstant} associated with C{value}.
"""
for constant in cls.iterconstants():
if constant.value == value:
return constant
raise ValueError(value)
def _flagOp(op, left, right):
"""
Implement a binary operator for a L{FlagConstant} instance.
:param op: A two-argument callable implementing the binary operation. For
example, C{operator.operator.or_}.
:param left: The left-hand L{FlagConstant} instance.
:param right: The right-hand L{FlagConstant} instance.
:return: A new L{FlagConstant} instance representing the result of the
operation.
"""
value = op(left.value, right.value)
names = op(left.names, right.names)
result = FlagConstant()
result._realize(left._container, names, value)
return result
[docs]class FlagConstant(_Constant):
"""
L{FlagConstant} defines an attribute to be a flag constant within a
collection defined by a L{Flags} subclass.
L{FlagConstant} is only for use in the definition of L{Flags} subclasses.
Do not instantiate L{FlagConstant} elsewhere and do not subclass it.
"""
def __init__(self, value=_UNSPECIFIED):
_Constant.__init__(self)
self.value = value
def _realize(self, container, names, value):
"""
Complete the initialization of this L{FlagConstant}.
This implementation differs from other C{_realize} implementations in
that a L{FlagConstant} may have several names which apply to it, due to
flags being combined with various operators.
:param container: The L{Flags} subclass this constant is part of.
:param names: When a single-flag value is being initialized, a C{str}
giving the name of that flag. This is the case which happens when
a L{Flags} subclass is being initialized and L{FlagConstant}
instances from its body are being realized.
Otherwise, a C{set} of C{str}
giving names of all the flags set on this L{FlagConstant} instance.
This is the case when two flags are combined using C{|}, for
example.
"""
if isinstance(names, str):
name = names
names = set([names])
elif len(names) == 1:
(name, ) = names
else:
name = "{" + ",".join(sorted(names)) + "}"
_Constant._realize(self, container, name, value)
self.value = value
self.names = names
def __or__(self, other):
"""
Define C{|} on two L{FlagConstant} instances to create a new
L{FlagConstant} instance with all flags set in either instance set.
"""
return _flagOp(operator.or_, self, other)
def __and__(self, other):
"""
Define C{&} on two L{FlagConstant} instances to create a new
L{FlagConstant} instance with only flags set in both instances set.
"""
return _flagOp(operator.and_, self, other)
def __xor__(self, other):
"""
Define C{^} on two L{FlagConstant} instances to create a new
L{FlagConstant} instance with only flags set on exactly one instance
set.
"""
return _flagOp(operator.xor, self, other)
def __invert__(self):
"""
Define C{~} on a L{FlagConstant} instance to create a new
L{FlagConstant} instance with all flags not set on this instance set.
"""
result = FlagConstant()
result._realize(self._container, set(), 0)
for flag in self._container.iterconstants():
if flag.value & self.value == 0:
result |= flag
return result
def __iter__(self):
"""
:return: An iterator of flags set on this instance set.
"""
return (self._container.lookupByName(name) for name in self.names)
def __contains__(self, flag):
"""
:param flag: The flag to test for membership in this instance
set.
:return: C{True} if C{flag} is in this instance set, else
C{False}.
"""
# Optimization for testing membership without iteration.
return bool(flag & self)
def __nonzero__(self):
"""
:return: C{False} if this flag's value is 0, else C{True}.
"""
return bool(self.value)
__bool__ = __nonzero__
[docs]class Flags(Values):
"""
A L{Flags} subclass contains constants which can be combined using the
common bitwise operators (C{|}, C{&}, etc) similar to a I{bitvector} from a
language like C.
"""
_constantType = FlagConstant
_value = 1
@classmethod
def _constantFactory(cls, name, descriptor):
"""
For L{FlagConstant} instances with no explicitly defined value, assign
the next power of two as its value.
:param name: The name of the constant to create.
:param descriptor: An instance of a L{FlagConstant}
which is assigned to
C{name}.
:return: Either the value passed to the C{descriptor} constructor, or
the next power of 2 value which will be assigned to C{descriptor},
relative to the value of the last defined L{FlagConstant}.
"""
if descriptor.value is _UNSPECIFIED:
value = cls._value
cls._value <<= 1
else:
value = descriptor.value
cls._value = value << 1
return value