gpf.common.containers module¶

This module holds a couple of data structure types (or “containers”) that can be used to store all kinds of data in a memory-efficient and object-oriented manner.

class gpf.common.containers.BucketFactory(*attributes)[source]¶

Bases: object

Factory class to create FrozenBucket or Bucket classes.

Params:

attributes (str, unicode):

The property names to define in the FrozenBucket or Bucket. Note that all names are transformed to lowercase and that non-alphanumeric characters are replaced by underscores to ensure valid Python attribute names.

See also

Bucket, FrozenBucket

fields¶

Returns the current FrozenBucket or Bucket attribute names in their initial order.

Return type:	tuple

get_bucket_class(writable=True)[source]¶

Returns a bucket class type with the BucketFactory input fields as predefined slots. For better performance, do not immediately instantiate the returned class on the same line, but store it in a variable first and use this as an object initializer.

Parameters:	writable (bool) – When `True` (default), a `Bucket` type is returned. Otherwise, a `FrozenBucket` type is returned.
Return type:	type

class gpf.common.containers.FrozenBucket(*values, **pairs)[source]¶

Bases: tuple

Immutable container class for storing user-defined attributes (properties). Because FrozenBucket is a namedtuple, it is very memory-efficient and can safely be used in loops.

This class can’t be instantiated directly and must be obtained via the get_bucket_class() factory function. Since the class is dynamically created, the user-defined properties are only exposed at runtime.

Examples:

>>> bucket = get_bucket_class(['a', 'b'], writable=False)  # using the factory function
>>> bucket('test', 3.14)
FrozenBucket(a='test', b=3.14)

>>> bucket_factory = BucketFactory('a', 'b')               # using the BucketFactory class
>>> bucket = bucket_factory.get_bucket_class(writable=False)
>>> my_bucket = bucket('test', 3.14)
>>> my_bucket.a
test
>>> my_bucket.b
3.14

See also

BucketFactory, Bucket

class gpf.common.containers.Bucket(*values, **pairs)[source]¶

Bases: object

Mutable container class for storing user-defined attributes (properties). Bucket uses __slots__, which makes it relatively memory-efficient. It can safely be used in loops. However, if the data stored in it remains static, it’s better to use a FrozenBucket instead.

This class can’t be instantiated directly and must be obtained via the get_bucket_class() factory function. Since the class is dynamically created, the user-defined properties are only exposed at runtime.

Examples:

>>> bucket = get_bucket_class(['a', 'b'])     # using the factory function
>>> my_bucket = bucket('test', 3.14)
>>> my_bucket.a
test
>>> my_bucket.a = my_bucket.b
>>> my_bucket.a
3.14

>>> bucket_factory = BucketFactory('a', 'b')   # using the BucketFactory class
>>> bucket = bucket_factory.get_bucket_class()
>>> bucket('test', 3.14)
Bucket(a='test', b=3.14)

See also

BucketFactory, FrozenBucket

items()[source]¶

Returns a generator of the stored key-value pairs.

Return type:	generator

Example:

>>> bucket = get_bucket_class(['a', 'b'])
>>> my_bucket = bucket('test', 3.14)
>>> for k, v in my_bucket.items():
>>>     print(k, v)
('a', 'test')
('b', 3.14)

update(*values, **pairs)[source]¶

Updates all Bucket values using positional and/or keyword arguments.

Example:

>>> bucket = get_bucket_class(['a', 'b'])
>>> my_bucket = bucket('test', 3.14)
>>> my_bucket.update('hello', b='world')
>>> print(my_bucket)
Bucket(a='hello', b='world')

gpf.common.containers.get_bucket_class(field_names, writable=True)[source]¶

Factory function to obtain a FrozenBucket or a Bucket container class.

The function instantiates a BucketFactory and calls its get_bucket_class method.

Parameters:	field_names (iterable) – An iterable of field names for which to create a bucket class. writable (bool) – If `False` (default = `True`), a `FrozenBucket` type will be returned. By default, a `Bucket` type will be returned.
Return type:	type

In theory, you could immediately instantiate the returned bucket class. This is okay for a single bucket, but considered bad practice if you do this consecutively (e.g. in a loop). For example, it’s fine if you do this once:

>>> my_bucket = get_bucket_class(['field1', 'field2'])(1, 2)
>>> print(my_bucket)
Bucket(field1=1, field2=2)

However, if you need to reuse the bucket class to instantiate multiple buckets, this is better:

>>> fields = ('Field-With-Dash', 'UPPERCASE_FIELD')
>>> bucket_cls = get_bucket_class(fields, writable=False)
>>> for i in range(3):
>>>     print(bucket_cls(i, i+1))
FrozenBucket(field_with_dash=0, uppercase_field=1)
FrozenBucket(field_with_dash=1, uppercase_field=2)
FrozenBucket(field_with_dash=2, uppercase_field=3)