Welcome to collectionish’s documentation!

collectionish

pypi version travis build documentation status coverage hypothesis tested

Collectionish is a pure python library extending the basic collection data types and operations for working with them.

Getting Started:

Install the latest stable version with pip:

$ pip install collectionish

A quick note about python version support:

collectionish works with python 3 and has been fully tested with python 3.7 and 3.8. There is no plan to support backwards compatability for python 2 or 3.5.

Checkout the docs:

It’s best to checkout the docs. There you’ll find detailed documentation of collectionish’s features and lots of examples of how to use them.

What’s is it?

Python is a wonderful language when it comes to extending inbuilt types and making things that quack. collectionish subscribes to the ideology that the behaviour of data structures belongs in data structures and that it’s better and more graceful to bake the behavior into a type than to complicate surrounding business logic creating many more wtf moments and room for bugs to sneak in.

Python’s own collections module is a great example. take defaultdict, how many times have you seen something like this?

pets = [('cat', 'tabby'),
        ('cat', 'ginger'),
        ('dog', 'beagle'),
        ('dog', 'poodle'),
        ('lizard', 'gecko')
       ]

pet_dict = {}
for typ, subtyp in pets:
    try:
        pet_dict[typ].append(subtyp)
    except KeyError:
        # now we'll need to make an comment to explain...
        # if the key doesn't exist pet_dict we make a new
        # list containing the pet's subtype
        pet_dict[typ] = [subtyp]

vs:

from collections import defaultdict

pet_dict = defaultdict(list)
for typ, subtyp in pets:
    pet_dict[typ].append(subtyp)

collectionish adds some extra collections such like AttyDict (a straightforward recursive dot access dict ) and UniqueTuple ( a tuple of unique items that remembers insertion order). New collections will be added fairly regularly on the basis that they are generic enough and useful enough that i find myself repeating them in other projects.

In addition to data structures collectionish also provides some operations for working with data structures (from both standard python and collections) like the recursive getters and setters collectionish.ops.

Principles:

useful enough:
Inspirations for data structures should come from stuff we’ve written or needed before at some point.
generic enough:
To be extended within reason.
specific enough:
To be clear about what things do. We don’t aim to make the data structure or stand in for a pandas dataframe that does everything.
intuitive enough:
type hinting should generally work the same as it does with parent types, signatures should not be wildly different, obvious magic methods or such as __iter__ should not generally be missing from data types.
documented enough:
All public structures and ops should be documented and have doctest examples so we know its correct and It should be fairly obvious from somethings name what it is.
tested more than enough:
we test with the excellent hypothesis library wherever possible. We do doctests to keep documentation correct.
ops
AttyDict(**kwargs) A lightweight dictionary with dot access.
UniqueTuple An immutable sequence of unique and hashable items ordered by first appearance.
Sentry A Basic falsey singleton type useful for when None actually means something.

Indices and tables