Modules

magic_dot. NOT_FOUND

Special instance variable returned when a attribute and key cannot be found.

class magic_dot.MagicDot(data: Any, exception: bool = False, iter_nf_as_empty: bool = False)

Bases: object

A wrapper that allows data extraction without all the try and except overhead.

Parameters:

• data – The data to be wrapped by MagicDot
• exception – Selects if a NotFound exception to be raised when NOT_FOUND happens during extraction.
• iter_nf_as_empty – Selects if iterating over NOT_FOUND should return an empty iterator.

Note

The MagicDot class has no public attributes. Any access to an attribute will be mapped to the underlying data and used to extract a new MagicDot structure.

exception(exception: bool = True) → magic_dot.MagicDot

Enable or disable exceptions when NOT_FOUND is encountered.

NOT_FOUND is encountered whenever code extracts additional data from the encapsulated data. Some examples would be: ::

>>> from magic_dot import MagicDot
>>> md = MagicDot([1])
>>> md = md.exception()
>>> md['nonexistent']
(raises magic_dot.exceptions.NotFound)
>>> md.nonexistent
(raises magic_dot.exceptions.NotFound)
>>> md.pluck('nonexistent')
(raises magic_dot.exceptions.NotFound)

Without exceptions enabled, the above would respectively return MagicDot(NOT_FOUND), MagicDot(NOT_FOUND) and MagicDot([NOT_FOUND]).

Parameters:exception – Enable or disable exceptions when NOT_FOUND is encountered. Returns:If the exception changes, a new MagicDot will be returned. Otherwise, this returns self.

get(not_found: Any = magic_dot.NOT_FOUND)

Gets the encapsulated data in this MagicDot.

This is either the encapsulated data or NOT_FOUND if extraction failed.

Parameters:default – Selects what to return if the encapsulated data was NOT_FOUND. Returns:The encaapsulated data in this MagicDot instance.

iter_nf_as_empty(iter_nf_as_empty: bool = True) → magic_dot.MagicDot

Enable or disable empty iterator support for NOT_FOUND data.

By default, if a request is made to iterate over a NOT_FOUND, a TypeError is raised. With this set, the iteration will act as if this was an empty array. ::

>>> from magic_dot import MagicDot
>>> x = MagicDot(1)
>>> for y in x.nonexistent:
>>>    ...
(Raises TypeError)
>>> x = MagicDot(1).iter_nf_as_empty()
>>> for y in x.nonexistent:
>>>    ...
(Skips the contents of the for loop.)

Parameters:iter_nf_as_empty – Enable or Disable Returns:If the iter_nf_as_empty changes, a new MagicDot will be returned. Otherwise, this returns self.

pluck(name: str)

Extracts name from an encapsulated data (which must be iterable) into an array.

For each item in the encapsulated data iterable, extract the named attribute or key. If they are not available, either extract NOT_FOUND or raise an exception depending on the current .exception() configuration.

If the encapsulated date is not iterable and not NOT_FOUND, a TypeError will be raised.

If the encapsulated data is NOT_FOUND, either raise a TypeError, or return an empty list depending on the .iter_nf_as_empty() setting.

Parameters:text – The attribute or key to pluck from the array. Returns:A new MagicDot containing the resulting array with plucked data.

exceptions Module

exception magic_dot.exceptions.NotFound

Bases: Exception

The requested data was not found during a call to .get().