Why?¶

The difference between namedtuples and classes decorated by characteristic is that the latter are type-sensitive and less typing aside regular classes:

>>> from characteristic import attributes
>>> @attributes(["a",])
... class C1(object):
...     def __init__(self):
...         if not isinstance(self.a, int):
...             raise ValueError("'a' must be an integer.")
...     def print_a(self):
...         print self.a
>>> @attributes(["a",])
... class C2(object):
...     pass
>>> c1 = C1(a=1)
>>> c2 = C2(a=1)
>>> c1 == c2
False
>>> c1.print_a()
1
>>> C1(a="hello")
Traceback (most recent call last):
   ...
ValueError: 'a' must be an integer.

…while namedtuple’s purpose is explicitly to behave like tuples:

>>> from collections import namedtuple
>>> NT1 = namedtuple("NT1", "a")
>>> NT2 = namedtuple("NT2", "b")
>>> t1 = NT1._make([1,])
>>> t2 = NT2._make([1,])
>>> t1 == t2 == (1,)
True

This can easily lead to surprising and unintended behaviors.

API¶

characteristic consists of class decorators that add features to your classes.. There are three that start with @with_ that add one feature to your class based on a list of attributes. Then there’s the helper @attributes that combines them all into one decorator so you don’t have to repeat the attribute list multiple times.

@characteristic.with_repr(attrs)¶

A class decorator that adds a human readable __repr__ method to your class using attrs.

>>> from characteristic import with_repr
>>> @with_repr(["a", "b"])
... class RClass(object):
...     def __init__(self, a, b):
...         self.a = a
...         self.b = b
>>> c = RClass(42, "abc")
>>> print c
<RClass(a=42, b='abc')>

Parameters:	attrs (list of native strings) – Attributes to work with.

@characteristic.with_cmp(attrs)¶

A class decorator that adds comparison methods based on attrs.

For that, each class is treated like a tuple of the values of attrs.

>>> from characteristic import with_cmp
>>> @with_cmp(["a", "b"])
... class CClass(object):
...     def __init__(self, a, b):
...         self.a = a
...         self.b = b
>>> o1 = CClass(1, "abc")
>>> o2 = CClass(1, "abc")
>>> o1 == o2  # o1.a == o2.a and o1.b == o2.b
True
>>> o1.c = 23
>>> o2.c = 42
>>> o1 == o2  # attributes that are not passed to with_cmp are ignored
True
>>> o3 = CClass(2, "abc")
>>> o1 < o3  # because 1 < 2
True
>>> o4 = CClass(1, "bca")
>>> o1 < o4  # o1.a == o4.a, but o1.b < o4.b
True

Parameters:	attrs (list of native strings) – Attributes to work with.

@characteristic.with_init(attrs, defaults=None)¶

A class decorator that wraps the __init__ method of a class and sets attrs using passed keyword arguments before calling the original __init__.

Those keyword arguments that are used, are removed from the kwargs that is passed into your original __init__. Optionally, a dictionary of default values for some of attrs can be passed too.

>>> from characteristic import with_init
>>> @with_init(["a", "b"], defaults={"b": 2})
... class IClass(object):
...     def __init__(self):
...         if self.b != 2:
...             raise ValueError("'b' must be 2!")
>>> o1 = IClass(a=1, b=2)
>>> o2 = IClass(a=1)
>>> o1.a == o2.a
True
>>> o1.b == o2.b
True
>>> IClass()
Traceback (most recent call last):
  ...
ValueError: Missing value for 'a'.
>>> IClass(a=1, b=3)  # the custom __init__ is called after the attributes are initialized
Traceback (most recent call last):
  ...
ValueError: 'b' must be 2!

Parameters:	attrs (list of native strings) – Attributes to work with. defaults (dict or None) – Default values if attributes are omitted on instantiation.
Raises ValueError:
	If the value for a non-optional attribute hasn’t been passed.

@characteristic.attributes(attrs, defaults=None, create_init=True)¶

A convenience class decorator that combines with_cmp(), with_repr(), and optionally with_init() to avoid code duplication.

See Examples for @attributes in action!

Parameters:	attrs (Iterable of native strings.) – Attributes to work with. defaults (dict or None) – Default values if attributes are omitted on instantiation. create_init (bool) – Also apply with_init() (default: True)
Raises ValueError:
	If the value for a non-optional attribute hasn’t been passed.

Examples¶

@attributes([attr1, attr2, …]) enhances your class by:

• a nice __repr__,
• comparison methods that compare instances as if they were tuples of their attributes,
• and – optionally but by default – an initializer that uses the keyword arguments to initialize the specified attributes before running the class’ own initializer (you just write the validator!).

>>> from characteristic import attributes
>>> @attributes(["a", "b",])
... class C(object):
...     pass
>>> obj1 = C(a=1, b="abc")
>>> obj1
<C(a=1, b='abc')>
>>> obj2 = C(a=2, b="abc")
>>> obj1 == obj2
False
>>> obj1 < obj2
True
>>> obj3 = C(a=1, b="bca")
>>> obj3 > obj1
True
>>> @attributes(["a", "b", "c",], defaults={"c": 3})
... class CWithDefaults(object):
...     pass
>>> obj4 = CWithDefaults(a=1, b=2)
>>> obj5 = CWithDefaults(a=1, b=2, c=3)
>>> obj4 == obj5
True