skip to navigation
skip to content

Not Logged In

fields 2.4.0

A totally different take on container boilerplate.

Container class boilerplate killer.


  • Human-readable __repr__
  • Complete set of comparison methods
  • Keyword and positional argument support. Works like a normal class - you can override just about anything in the subclass (eg: a custom __init__). In contrast, hynek/characteristic forces different call schematics and calls your __init__ with different arguments.


pip install fields

Usage & examples

A class that has 2 attributes, a and b:

>>> from fields import Fields
>>> class Pair(Fields.a.b):
...     pass
>>> p = Pair(1, 2)
>>> p.a
>>> p.b
>>> Pair(a=1, b=2)
Pair(a=1, b=2)

A class that has one required attribute value and two attributes (left and right) with default value None:

>>> class Node(Fields.value.left[None].right[None]):
...     pass
>>> Node(1, Node(2), Node(3, Node(4)))
Node(value=1, left=Node(value=2, left=None, right=None), right=Node(value=3, left=Node(value=4, left=None, right=None), right=None))
>>> Node(1, right=Node(2))
Node(value=1, left=None, right=Node(value=2, left=None, right=None))

Want tuples?

An alternative to namedtuple:

>>> from fields import Tuple
>>> class Pair(Tuple.a.b):
...     pass
>>> p = Pair(1, 2)
>>> p.a
>>> p.b
>>> tuple(p)
(1, 2)
>>> a, b = p
>>> a
>>> b


To run all the tests run tox in your shell (pip install tox if you don’t have it):



Why should I use this?

It’s less to type, why have quotes around when the names need to be valid symbols anyway. In fact, this is one of the shortest forms possible to specify a container with fields.

But you’re abusing a very well known syntax. You’re using attribute access instead of a list of strings. Why?

Symbols should be symbols. Why validate strings so they are valid symbols when you can avoid that? Just use symbols. Save on both typing and validation code.

The use of language constructs is not that surprising or confusing in the sense that semantics precede conventional syntax use. For example, if we have class Person(Fields.first_name.last_name.height.weight): pass then it’s going to be clear we’re talking about a Person object with first_name, last_name, height and width fields: the words have clear meaning.

Again, you should not name your varibles as f1, f2 or any other non-semantic symbols anyway.

Semantics precede syntax: it’s like looking at a cake resembling a dog, you won’t expect the cake to bark and run around.

Is this stable? Is it tested?

Yes. Mercilessly tested on Travis and AppVeyor.

Is the API stable?

Yes, ofcourse.

Why not namedtuple?

It’s ugly, repetivive and unflexible. Compare this:

>>> from collections import namedtuple
>>> class MyContainer(namedtuple("MyContainer", ["field1", "field2"])):
...     pass
>>> MyContainer(1, 2)
MyContainer(field1=1, field2=2)

To this:

>>> class MyContainer(Tuple.field1.field2):
...     pass
>>> MyContainer(1, 2)
MyContainer(field1=1, field2=2)

Why not characteristic?

Ugly, inconsistent - you don’t own the class:

Lets try this:

>>> import characteristic
>>> @characteristic.attributes(["field1", "field2"])
... class MyContainer(object):
...     def __init__(self, a, b):
...         if a > b:
...             raise ValueError("Expected %s < %s" % (a, b))
>>> MyContainer(1, 2)
Traceback (most recent call last):
ValueError: Missing keyword value for 'field1'.

WHAT !? Ok, lets write some more code:

>>> MyContainer(field1=1, field2=2)
Traceback (most recent call last):
TypeError: __init__() ... arguments...

This is bananas. You have to write your class around these quirks.

Lets try this:

>>> class MyContainer(Fields.field1.field2):
...     def __init__(self, a, b):
...         if a > b:
...             raise ValueError("Expected %s < %s" % (a, b))
...         super(MyContainer, self).__init__(a, b)

Just like a normal class, works as expected:

>>> MyContainer(1, 2)
MyContainer(field1=1, field2=2)

Won’t this confuse pylint?

Normaly it would, but there’s a plugin that makes pylint understand it, just like any other class: pylint-fields.


2.4.0 (2015-06-13)

  • Similarly to fields.Fields, added three new bases:
    • fields.BareFields (implements __init__).
    • fields.ComparableMixin (implements __eq__, __ne__, __lt__, __gt__, __le__, __ge__ and __hash__).
    • fields.PrintableMixin (implements __repr__).
  • Improved reference section in the docs.
  • Added fields.ConvertibleFields and fields.ConvertibleMixin. They have two convenience properties: as_dict and as_tuple`.

2.3.0 (2015-01-20)

  • Allowed overriding __slots__ in SlotsFields subclasses.

2.2.0 (2015-01-19)

  • Added make_init_func as an optional argument to class_sealer. Rename the __base__ option to just base.

2.1.1 (2015-01-19)

  • Removed bogus console_scripts entrypoint.

2.1.0 (2015-01-09)

  • Added SlotsFields (same as Fields but automatically adds __slots__ for memory efficiency on CPython).
  • Added support for default argument to Tuple.

2.0.0 (2014-10-16)

  • Made the __init__ in the FieldsBase way faster (used for fields.Fields).
  • Moved RegexValidate in fields.extras.

1.0.0 (2014-10-05)

  • Lots of internal changes, the metaclass is not created in a closure anymore. No more closures.
  • Added RegexValidate container creator (should be taken as an example on using the Factory metaclass).
  • Added support for using multiple containers as baseclasses.
  • Added a super() sink so that super().__init__(*args, **kwargs) always works. Everything inherits from a baseclass that has an __init__ that can take any argument (unlike object.__init__). This allows for flexible usage.
  • Added validation so that you can’t use conflicting field layout when using multiple containers as the baseclass.
  • Changed the __init__ function in the class container so it works like a python function w.r.t. positional and keyword arguments. Example: class MyContainer(Fields.a.b.c[1].d[2]) will function the same way as def func(a, b, c=1, d=2) would when arguments are passed in. You can now use MyContainer(1, 2, 3, 4) (everything positional) or MyContainer(1, 2, 3, d=4) (mixed).

0.3.0 (2014-07-19)

  • Corrected string repr.

0.2.0 (2014-06-28)

  • Lots of breaking changes. Switched from __call__ to __getitem__ for default value assignment.

0.1.0 (2014-06-27)

  • Alpha release.
File Type Py Version Uploaded on Size
fields-2.4.0-py2.py3-none-any.whl (md5) Python Wheel py2.py3 2015-06-13 14KB
fields-2.4.0.tar.gz (md5) Source 2015-06-13 25KB
  • Downloads (All Versions):
  • 21 downloads in the last day
  • 593 downloads in the last week
  • 2486 downloads in the last month