examine

####A simple library for examining complex data structures

The main component of this library is the structure parser that allows you to easily see the resulting structure of python object:

>>> import examine
>>> mock_api_response = {
...   'name': 'username',
...   'interests': ['coding', 'snowboarding'],
...   'location': {'country': 'USA', 'state': 'MN'}}
>>> print(examine.Structure(mock_api_response))
dict
  interests - [str]
  location - dict
    country - str
    state - str
  name - str

###Installation pip install examine

###Usage To use this library, you simply pass any object to the Structure(obj) constructor. This gives you a Structure object. While not terribly interesting on it's own, it can be passed to the str function (or simply passed to print) to return an easy-to-interpret layout of the object hierarchy.

>>> print(examine.Structure('string'))
str
>>> print(examine.Structure([1, 2, 3]))
[int]
>>> print(examine.Structure([{'key1': 'val1'}, {'key2': 'val2'}]))
[dict]
  *key1 - str
  *key2 - str
>>> print(examine.Structure({'key1': {'subkey1': 'subvalue'}}))
dict
  key1 - dict
    subkey1 - str
>>> examine.Structure('string')
<examine.examine.Structure object at ...>

###Display Format #####Simple cases The format is pretty simple. The type of the root object used to create the Structure will be the first line (usually a dict or array of dicts):

>>> print(examine.Structure({}))
dict

Following that, there will be all of the keys present in the dict, or in the case of a list of dicts, any key present:

>>> print(examine.Structure({'key1': 'val', 'key2': 2.0}))
dict
  key1 - str
  key2 - float

#####Common dict structure When dealing with a list of dicts, any key found in any of the dicts will be listed as keys. If a key is not found in every dict in the list, it is denoted with an asterisk indicating that the key is not always present:

>>> print(examine.Structure([
...   {'key1': 'val1', 'key2': 'val2'},
...   {'key1': 'val1'}]))
[dict]
  key1 - str
  *key2 - str

When you are inspecting the common structure of multiple dicts in a list, and the underlying value for a key is sometimes None, there will be an asterisk for that key's value type indicating that the underlying value for that key may sometimes be None.

>>> print(examine.Structure([{'key': 'val'}, {'key': None}]))
[dict]
  key - *str

#####More on lists When looking at a list of a type that sometimes has a None value, the value type will have an asterisk in front of it, indicating that some of the values in the list may be None.

>>> print(examine.Structure([1, 2, None]))
[*int]

When dealing with a list containing mixed types, it will be indicated with the type <mixed-type>:

>>> print(examine.Structure([1, 'str', {'key': 'val'}]))
[<mixed-type>]

#####Tuples Tuples are typically used with non-homogeneous values, and as such, this library tries to give you useful information about the contents of tuples. Here is a simple example of a tuple.

>>> print(examine.Structure(('string', 1)))
(str, int)

Since a tuple may contain multiple dicts, and each may have it's own structure, this library does not automatically give you the structure of dicts that are part of a tuple. If you want to find out those structures, you must do so manually.

>>> atuple = ({'key': 'val'}, {'anotherkey': 'anotherval'})
>>> print(examine.Structure(atuple))
(dict, dict)

>>> print(examine.Structure(atuple[0]))
dict
  key - str
  
>>> print(examine.Structure(atuple[1]))
dict
  anotherkey - str

#####Putting things together Here is an example result of a more complicated structure:

>>> print(examine.Structure({
...   'key1': 'val1',
...   'key2': [1, 2, 3],
...   'key3': [{
...     'sub1': 'subval1',
...     'sub2': 1},{
...     'sub1': 'subval1',
...     'sub2': 'str',
...     'sub3': 3}],
...   'key4': {'subkey': 'val'},
...   'key5': [1, 'str', {'key': 'val'}]}))
dict
  key1 - str
  key2 - [int]
  key3 - [dict]
    sub1 - str
    sub2 - <mixed-type>
    *sub3 - int
  key4 - dict
    subkey - str
  key5 - [<mixed-type>]

In this case we can determine the following:

• root object is a dict
• root object has the keys: key1, key2, key3, key4, key5
• key1 on root is a string
• key2 on root is an array of ints
• key3 on root is an array of dicts
• key4 on root is a dict
• for the dict held by key4, subkey is a string
• key5 on root is a list of mixed types

For the list of dicts held by key3:

• sub1 is always a string for dicts in that list
• sub2 is always an unknown type for dicts in that list
• sub3 is SOMETIMES an int for dicts in that list