API Reference¶
-
class
cherrypicker.
CherryPicker
(obj, on_missing='ignore', on_error='ignore', on_leaf='raise', leaf_types=(<class 'str'>, <class 'bytes'>), default=None, n_jobs=None)[source]¶ Reduces nestings of iterable and mappable objects into flat tables.
The CherryPicker class allows you to apply chained filter and extract operations to an object with complex structure. All the cherry picker uses to navigate your object is iterable and mapping interfaces. Anything without either of those interfaces (or a string) is treated as a leaf node.
Each chained operation will return a new
CherryPicker
which wraps the resulting data from that operation. To get the wrapped data back, use theCherryPicker.get()
method.Parameters: - obj (object.) – The data to operate on.
- on_missing (str, default =
ignore
.) – Action to perform when trying to get an attribute that doesn’t exist from an object with a Mapping interface.ignore
will do nothing,raise
will raise anAttributeError
. - on_error (str, default =
ignore
) – Action to perform if an error occurs during filtering.ignore
will just mean the filter operation returns False, andraise
will mean the error is raised. - on_leaf (str, default =
raise
.) – Action to perform when calling__getitem__()
on a leaf node.raise
will cause acherrypicker.exceptions.LeafError`
to be raised.get
will return the result of__getitem__()
on the wrapped item. - leaf_types – By default, anything doesn’t have an Iterable or
Mapping interface will be treated as a leaf. Any classes specifed
in this parameter will also be treated as leaves regardless of any
interfaces they conform to.
leaf_types
may be a class, a method that resolves to True if an object passed to it should be treated as a leaf, or a tuple of classes/methods. - default (object, default = None) – The item to return when extracting an attribute that does not exist from an object.
- n_jobs (int, default = None) – The maximum number of parallel processes to run when
performing operations on iterable objects. If n_jobs > 1 then the
iterable will be processed in parallel batches. If n_jobs = -1, all
the CPUs are used. For n_jobs below -1, (n_cpus + 1 + n_jobs) are
used. Thus for n_jobs = -2, all CPUs but one are used. See
joblib.Parallel
for more details on this parameter.
Examples: Data extraction may be done with the getitem interface. Let’s say we have a list of objects and we want to get a flat list of the
name
attributes for each item in the list:>>> data = [ { 'name': 'Alice', 'age': 20}, { 'name': 'Bob', 'age': 30 } ] >>> picker = CherryPicker(data) >>> picker['name'].get() ['Alice', 'Bob']
We can also request multiple attributes for each item to produce a flat table:
>>> data = [ { 'name': 'Alice', 'age': 20}, { 'name': 'Bob', 'age': 30 } ] >>> picker = CherryPicker(data) >>> picker['name', 'age'].get() [['Alice', 20], ['Bob', 30]]
Filter operations are applied with parentheses. For example, to get every
name
attribute from each item in a list calleddata
:>>> data = [ { 'name': 'Alice', 'age': 20}, { 'name': 'Bob', 'age': 30 } ] >>> picker = CherryPicker(data) >>> picker(name='Alice')['age'].get() [30]
Multiple filters may be provided:
>>> data = [ { 'name': 'Alice', 'age': 20}, { 'name': 'Bob', 'age': 30 } ] >>> picker = CherryPicker(data) >>> picker(name='Alice' age=lambda x: x>10, how='any').get() [{'name': 'Alice', 'age': 20}, {'name': 'Bob', 'age': 30}]
Filters can also be chained:
>>> data = [ { 'name': 'Alice', 'age': 20}, { 'name': 'Bob', 'age': 30 } ] >>> picker = CherryPicker(data) >>> picker(age=lambda x: x>10)(name='B*')['name'].get() ['Bob']
See
CherryPicker.filter()
for more filtering options.-
parent
¶ Get the parent or iterable of parents.
-
parents
¶ Alias for
parent()
.
-
class
cherrypicker.
CherryPickerTraversable
(obj, on_missing='ignore', on_error='ignore', on_leaf='raise', leaf_types=(<class 'str'>, <class 'bytes'>), default=None, n_jobs=None)[source]¶ Abstract class for traversable (mappable and/or iterable) nodes.
-
filter
(how='all', allow_wildcards=True, case_sensitive=True, regex=False, opts=None, **predicates)[source]¶ Return a filtered view of the child nodes. This method is usually accessed via
CherryPicker.__call__()
For an object with a mappable interface, this will return the object itself if it matches the predicates according to the rules specified.
For an object with an iterable but not a mappable interface, a collection of child objects matching the predicates according to the rules specified will be returned.
This method is not implemented for leaf nodes and will cause an error to be raised.
Example: Find any items with a name of
Alice
:>>> picker(name='Alice')
Find any items with a name of
Alice
and an age of 20:>>> picker(name='Alice', age=20)
Find any items with a name of
Alice
or an age of 20:>>> picker(name='Alice', age=20, how='any')
Find any items with a name of
Alice
and an age of 20 or more:>>> picker(name='Alice', age=lambda a: a >= 20)
Find any items with a name beginning with
Al
:>>> picker(name='Al*')
Find any items with a name beginning with
Al
oral
:>>> picker(name='Al*', case_sensitive=False)
Find any items with a name of
Al*
:>>> picker(name='Al*', allow_wildcards=False)
Find any items with a name matching a particular pattern (these two lines are equivalent):
>>> picker(name=r'^(?:Alice|Bob)$', regex=True, case_sensitive=False) >>> picker(name=re.compile(r'^(?:Alice|Bob)$', re.I))
Parameters: - how (str.) – The rule to be applied to predicate matching. May be one of (‘all’, ‘any’).
- allow_wildcards (bool, default = True.) – If True, special characters
(
*
,?
,[]
) in any string predicate values will be treated as wildcards according tofnmatch.fnmatchcase()
. - case_sensitive (bool, default = True.) – If True, any comparisons to strings or uncompiled regular expressions will be case sensitive.
- regex (bool, default = False.) – If True, any string comparisons will be reinterpreted as
regular expressions. If
case_sensitive
is False, they will be case-insensitive patterns. For more complex regex options, omit this parameter and provide pre-compiled regular expression patterns in your predicates instead. All regular expressions will be compared to string values using a full match. - predicates (str, regular expression or Callable.) – Keyword arguments where the keys are the object keys used to get the comparison value, and the values are either a value to compare, a regular expression to perform a full match against, or a callable function that takes a single value as input and returns something that evaluates to True if the value passes the predicate, or False if it does not.
Returns: If this is a mappable object, the object itself if it passes the predicates. If not and this is an iterable object, a collection of children that pass the predicates.
Return type:
-
-
class
cherrypicker.
CherryPickerIterable
(obj, on_missing='ignore', on_error='ignore', on_leaf='raise', leaf_types=(<class 'str'>, <class 'bytes'>), default=None, n_jobs=None)[source]¶ A collection of objects to be cherry picked.
-
keys
(peek=5)[source]¶ Parameters: peek (int, optional) – The maximum number of items in the iterable to inspect in order to ascertain what all possible keys are. If None, all items are inspected. Returns: A view of the keys that exist in all items that were previewed. Individual items may have other keys, but they will not be returned unless all the other items inspected also have those keys. Return type: list
-
-
class
cherrypicker.
CherryPickerMapping
(obj, on_missing='ignore', on_error='ignore', on_leaf='raise', leaf_types=(<class 'str'>, <class 'bytes'>), default=None, n_jobs=None)[source]¶ A mappable (key->value pairs) object to be cherry picked from.
-
flatten
¶ Flatten down the object so that all of its values are leaf nodes.
-
items
(peek=None)[source]¶ Parameters: peek (object, optional) – Not used. Returns: A view of the object’s items. Return type: list
-
-
class
cherrypicker.
CherryPickerLeaf
(obj, on_missing='ignore', on_error='ignore', on_leaf='raise', leaf_types=(<class 'str'>, <class 'bytes'>), default=None, n_jobs=None)[source]¶ A non-traversable node (an end-point).
This class cannot perform filter or extract operations; it only exists to return a result (with
get()
).