Package: magic-dot
Magic DotLibrary that allows deep extraction of layered data structures (like JSON).Free software: BSD licenseDocumentation:https://magic-dot.readthedocs.io.IntroductionMagic Dot encapsulates data to allow the versatile extraction of its contents.
It is easier to use thansetdefaultortry:exceptthat typical
extraction from a structured like JSON.  Consider the following simplified JSON
snipppet curlhttps://api.github.com/events:import json
data = json.loads("""
  [
    {
      "type": "PushEvent",
      "payload": {
        "commits": [
          {
            "author": {
              "name": "Bubba"
  }}]}}]
""")magic_dotcan retrieve the first name of the first commit, with a default of “nobody” if any
part of that chain is missing with the the following:from magic_dot import MagicDot, NOT_FOUND
name = MagicDot(data)[0].payload.commits[0].author.name.get("nobody")Since the incoming JSON can’t be trusted, without magic_dot, you have to verify that
each layer is there.  This can be done with atry:except, nearly as
efficiently, but it is more verbose.try:
  name = data[0]['payload']['commits'][0]['author']['name']
except (IndexError, KeyError):
  name = "nobody"Other features, like pluck, selective exceptions,
attribute support, and iteration can lead to cleaner code.FeaturesForgiving NOT_FOUND HandlingManipulations of the MagicDot structure will raise no exceptions
when one of the attributes or keys are not found.  Instead it delays
this until theget()call that extracts the data at the end.
When theget()is called, there are three ways of handling
missing data:Default is to return magic_dot.NOT_FOUND>>> md.nonexistent.get()
magic_dot.NOT_FOUNDYou can request a default value for magic_dot.NOT_FOUND>>> md.nonexistent.get('bubba')
'bubba'Or you can enable exceptions when referencing the nonexistent data>>> md.exception().nonexistent
---------------------------------------------------------------------------
NotFound                                  Traceback (most recent call last)Exceptions are not enabled by default.  They can be enabled during creation
I.EMagicDot(data, exception=True)and switched on and off with theMagicDot::exception(exception=False)method.Dict and List Item HandlingWhen amd[item]is encountered, data will be extracted as follows:Ifmd.__data[item]exists, that is used.Ifmd.__data.itemattribute exists it is used.If.exception()is enabled, a NotFound exception is raised.Otherwisemd.NOT_FOUNDis assigned to the resulting encapsulated data.Attribute HandlingWhen amd.keyis supplied data will be extracted as follows:Ifmd.__data.keyattribute exists it is used.Ifmd.__data[key]item exists, it is used.If.exception()is enabled, a NotFound exception is raised.Otherwisemd.NOT_FOUNDis assigned to the resultingmd.__data.Iteration SupportIf the currently encapsulated data is an iterable, MagicDot supports iterating
over the contained data with the resulting iteration being a MagicDot wrapper
around the iterated data.>>> from collections import namedtuple
>>> data = [1, {'x': 2}, namedtuple('x', 'x')(3)]
>>> for md in MagicDot(data):
...   print(md.get())
1
{'x': 2}
x(x=3)By default, if an attempt is made to iterate overNOT_FOUNDdata, aTypeErrorwill be raised.  The iteration code can be changed to instead return an empty list. ::>> md = MagicDot(1, iter_nf_as_empty=True)
>> for x in md.nonexistent:
..   print(md.get())
(prints nothing)Other OperatorsCurrently, there is one additional operator,MagicDot::pluck(), which if
the encapsulated data is a list, it will attempt to extract a named attribute
or key from the entire list.  The returned value is a MagicDot with the new plucked list.Future EnhancementFuture enhancements will be to support many of theUnderscore jsarray and collection capabilities
likecompact,reject, andcount.CreditsThis package was created withCookiecutterand theaudreyr/cookiecutter-pypackageproject template.History0.2.0 (2020-04-30)This contains some modifications that are not backwards compatible.Remove .lists() support.Add .pluck() support.Change exception() to be raised when NOT_FOUND is generated instead of at the .get()Make documentation changes to reflect the above.0.1.1 (2020-03-19)No significant chagnes.  Testing github release automations.0.1.0 (2020-03-19)First release on PyPI.