Code

PLOD Library Reference

class PLOD.PLOD(table)

PLOD: Pythonic List of Dictionaries Handler

This is a class that allows you to manipulate lists of dictionaries in a clear and easy-to-interpret manner.

HOW TO USE

To use, create an instance of the PLOD class with the list of dictinoaries as it's parameter. For example, given the following list:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Jim",   "age": 29, "zim": {"zam": "99"}              },
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
You can 'load' PLOD with:
>>> my_list = PLOD(test)
Then, one can 'stack' various methods together to manipulate that list of dictinoaries and return a result. For example:
>>> print PLOD(test).gt("age", 18).sort("income").returnString()
[
    {age: 29, income: None , name: 'Jim' , wigs: None     , zim: {'zam': '99'}},
    {age: 20, income: 15000, name: 'Joe' , wigs: [1, 2, 3], zim: None         },
    {age: 19, income: 29000, name: 'Bill', wigs: None     , zim: None         }
]
PLOD is designed to be very forgiving and, as much as possible, very flexible.

addKey(key, value)
Insert a attribute/element/key-value pair to all the dictionaries.

The same value is added to all of the dictionaries.

Of note: the current version of this routine cannot handle subtending keys (dictionaries in dictionaries).

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Jim",   "age": 29, "zim": {"zam": "99"}              },
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).addKey("sp", 3).returnString()
[
    {age: 18, income: 93000, name: 'Jim'  , sp: 3, wigs:        68, zim: None         },
    {age: 18, income: None , name: 'Larry', sp: 3, wigs: [3, 2, 9], zim: None         },
    {age: 20, income: 15000, name: 'Joe'  , sp: 3, wigs: [1, 2, 3], zim: None         },
    {age: 29, income: None , name: 'Jim'  , sp: 3, wigs: None     , zim: {'zam': '99'}},
    {age: 19, income: 29000, name: 'Bill' , sp: 3, wigs: None     , zim: None         }
]
New in version 0.1.4: New in version 0.1.4.

Parameters:

key -- The dictionary key (or cascading list of keys point to final key) that should be removed.

value -- The value assigned to the key.

Returns:
self
contains(key, value, findAll=False, exclude=False, includeMissing=False)
Return entries that:

have the key

key points to a list, and

value is found in the list.

If value is also a list itself, then the list entry is selected if any of the values match. If findAll is set to True, then all the entries must be found.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": [9, 12]  },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).contains("wigs", [1, 12]).returnString()
[
    {age: 18, income: 93000, name: 'Jim', wigs: [9, 12]  },
    {age: 20, income: 15000, name: 'Joe', wigs: [1, 2, 3]}
]
New in version 0.1.3b: New in version 0.1.3b.

Parameters:

key -- The dictionary key (or cascading list of keys) that should point to a list.

value --

The value to locate in the list. This argument can be an immutable value such as a string, tuple, or number.

If this argument is a list of values instead, then this method will search for any of the values in that list. If the optional 'findAll' parameter is set to True, then all of the values in that list must be found.

Optional named arguments:

Parameters:

finalAll -- If True, then all the values in the 'value' parameter must be found.

exclude -- If 'exclude' is True, then the entries that do NOT match the above conditions are returned.

includeMissing -- If 'includeMissing' is True, then if the key is missing then that entry is included in the results. However, it does not include entries that have the key but its value is for a non-list or empty list.

Returns:
self
count()
Return an integer representing the number of items in the list.

It is the equivalent to:

len(PLOD(list).returnList())

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "order": 2},
...    {"name": "Larry", "age": 18,                  "order": 3},
...    {"name": "Joe",   "age": 20, "income": 15000, "order": 1},
...    {"name": "Bill",  "age": 19, "income": 29000, "order": 4},
... ]
>>> print PLOD(test).gte("age", 19).count()
2
Returns: Integer representing the number of items in the list.
deleteByOrigIndex(index)
Removes a single entry from the list given the index reference.

The index, in this instance, is a reference to the original list indexing as seen when the list was first inserted into PLOD.

An example:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> myPLOD = PLOD(test)
>>> print myPLOD.sort("name").returnString()
[
    {age: 19, income: 29000, name: 'Bill' , wigs: None     },
    {age: 18, income: 93000, name: 'Jim'  , wigs:        68},
    {age: 20, income: 15000, name: 'Joe'  , wigs: [1, 2, 3]},
    {age: 18, income: None , name: 'Larry', wigs: [3, 2, 9]}
]
>>> print myPLOD.deleteByOrigIndex(0).returnString()
[
    {age: 19, income: 29000, name: 'Bill' , wigs: None     },
    {age: 20, income: 15000, name: 'Joe'  , wigs: [1, 2, 3]},
    {age: 18, income: None , name: 'Larry', wigs: [3, 2, 9]}
]
As you can see in the example, the list was sorted by 'name', which placed 'Bill' as the first entry. Yet, when the deleteByOrigIndex was passed a zero (for the first entry), it removed 'Jim' instead since it was the original first entry.

Parameters: index -- An integer representing the place of entry in the original list of dictionaries.

Returns: self
deleteByOrigIndexList(indexList)
Remove entries from the list given the index references.

The index, in this instance, is a reference to the original list indexing as seen when the list was first inserted into PLOD.

An example:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> myPLOD = PLOD(test)
>>> print myPLOD.sort("name").returnString()
[
    {age: 19, income: 29000, name: 'Bill' , wigs: None     },
    {age: 18, income: 93000, name: 'Jim'  , wigs:        68},
    {age: 20, income: 15000, name: 'Joe'  , wigs: [1, 2, 3]},
    {age: 18, income: None , name: 'Larry', wigs: [3, 2, 9]}
]
>>> listA = [0, 1]
>>> print myPLOD.deleteByOrigIndexList(listA).returnString()
[
    {age: 20, income: 15000, name: 'Joe'  , wigs: [1, 2, 3]},
    {age: 18, income: None , name: 'Larry', wigs: [3, 2, 9]}
]
As you can see in the example, the list was sorted by 'name', which rearranged the entries. Yet, when the deleteByOrigIndexList was passed a [0, 1] (for the first and second entries), it removed 'Jim' and "Larry" since those were the original first and second entries.

Parameters: indexList -- A list of integer representing the places of entry in the original list of dictionaries.

Returns: self
dropKey(key)
Drop an attribute/element/key-value pair from all the dictionaries.

If the dictionary key does not exist in a particular dictionary, then that dictionary is left unchanged.

Side effect: if the key is a number and it matches a list (interpreted as a dictionary), it will cause the "keys" to shift just as a list would be expected to.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Jim",   "age": 29, "zim": {"zam": "99"}              },
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).dropKey("income").returnString()
[
    {age: 18, name: 'Jim'  , wigs:        68, zim: None         },
    {age: 18, name: 'Larry', wigs: [3, 2, 9], zim: None         },
    {age: 20, name: 'Joe'  , wigs: [1, 2, 3], zim: None         },
    {age: 29, name: 'Jim'  , wigs: None     , zim: {'zam': '99'}},
    {age: 19, name: 'Bill' , wigs: None     , zim: None         }
]
New in version 0.1.2: New in version 0.1.2.

Parameters: key -- The dictionary key (or cascading list of keys point to final key) that should be removed.

Returns: self
eq(key, value, includeMissing=False)
Return entries where the key's value is of equal (==) value.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).eq("name", "Larry").returnString()
[
    {age: 18, name: 'Larry', wigs: [3, 2, 9]}
]
>>> print PLOD(test).eq("income", 15000, includeMissing=True).returnString()
[
    {age: 18, income: None , name: 'Larry', wigs: [3, 2, 9]},
    {age: 20, income: 15000, name: 'Joe'  , wigs: [1, 2, 3]}
]
New in version 0.1.1: New in version 0.1.1.

Parameters:

key -- The dictionary key (or cascading list of keys) that should be the basis of comparison.

value -- The value to compare with.

includeMissing -- Defaults to False. If True, then entries missing the key are also included.

Returns:
self
found()
Return True if list has at least one entry; otherwise return False.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "order": 2},
...    {"name": "Larry", "age": 18,                  "order": 3},
...    {"name": "Joe",   "age": 20, "income": 15000, "order": 1},
...    {"name": "Bill",  "age": 19, "income": 29000, "order": 4},
... ]
>>> print PLOD(test).found()
True
>>> print PLOD(test).eq("name", "Simon").found()
False
Returns: True if list has at least one entry, else False.
gt(key, value, includeMissing=False)
Return entries where the key's value is greater (>).

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).gt("age", 19).returnString()
[
    {age: 20, income: 15000, name: 'Joe', wigs: [1, 2, 3]}
]
New in version 0.1.1: New in version 0.1.1.

Parameters:

key -- The dictionary key (or cascading list of keys) that should be the basis of comparison.

value -- The value to compare with.

includeMissing -- Defaults to False. If True, then entries missing the key are also included.

Returns:
self
gte(key, value, includeMissing=False)
Return entries where the key's value is greater or equal (>=).

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).gte("age", 19).returnString()
[
    {age: 20, income: 15000, name: 'Joe' , wigs: [1, 2, 3]},
    {age: 19, income: 29000, name: 'Bill', wigs: None     }
]
New in version 0.1.1: New in version 0.1.1.

Parameters:

key -- The dictionary key (or cascading list of keys) that should be the basis of comparison.

value -- The value to compare with.

includeMissing -- Defaults to False. If True, then entries missing the key are also included.

Returns:
self
hasKey(key, notNone=False)
Return entries where the key is present.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": None , "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).hasKey("income").returnString()
[
    {age: 18, income: 93000, name: 'Jim' , wigs:        68},
    {age: 20, income: None , name: 'Joe' , wigs: [1, 2, 3]},
    {age: 19, income: 29000, name: 'Bill', wigs: None     }
]
>>> print PLOD(test).hasKey("income", notNone=True).returnString()
[
    {age: 18, income: 93000, name: 'Jim' , wigs:   68},
    {age: 19, income: 29000, name: 'Bill', wigs: None}
]
New in version 0.1.2: New in version 0.1.2.

Parameters:

key -- The dictionary key (or cascading list of keys) to locate.

notNone -- If True, then None is the equivalent of a missing key. Otherwise, a key with a value of None is NOT considered missing.

Returns:
self
insert(new_entry)
Insert a new entry to the end of the list of dictionaries.

This entry retains the original index tracking but adds this entry incrementally at the end.
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> entryA = {"name": "Willie", "age": 77}
>>> print PLOD(test).insert(entryA).returnString()
[
    {age: 18, income: 93000, name: 'Jim'   , wigs:        68},
    {age: 18, income: None , name: 'Larry' , wigs: [3, 2, 9]},
    {age: 20, income: 15000, name: 'Joe'   , wigs: [1, 2, 3]},
    {age: 19, income: 29000, name: 'Bill'  , wigs: None     },
    {age: 77, income: None , name: 'Willie', wigs: None     }
]
Parameters: new_entry -- The new list entry to insert.
lt(key, value, includeMissing=False)
Return entries where the key's value is less (<).

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).lt("age", 19).returnString()
[
    {age: 18, income: 93000, name: 'Jim'  , wigs:        68},
    {age: 18, income: None , name: 'Larry', wigs: [3, 2, 9]}
]
New in version 0.1.1: New in version 0.1.1.

Parameters:

key -- The dictionary key (or cascading list of keys) that should be the basis of comparison.

value -- The value to compare with.

includeMissing -- Defaults to False. If True, then entries missing the key are also included.

Returns:
self
lte(key, value, includeMissing=False)
Return entries where the key's value is less or equal (=<).

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).lte("age", 19).returnString()
[
    {age: 18, income: 93000, name: 'Jim'  , wigs:        68},
    {age: 18, income: None , name: 'Larry', wigs: [3, 2, 9]},
    {age: 19, income: 29000, name: 'Bill' , wigs: None     }
]
New in version 0.1.1: New in version 0.1.1.

Parameters:

key -- The dictionary key (or cascading list of keys) that should be the basis of comparison.

value -- The value to compare with.

includeMissing -- Defaults to False. If True, then entries missing the key are also included.

Returns:
self
missing()
Return True if list is empty; otherwise return False.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "order": 2},
...    {"name": "Larry", "age": 18,                  "order": 3},
...    {"name": "Joe",   "age": 20, "income": 15000, "order": 1},
...    {"name": "Bill",  "age": 19, "income": 29000, "order": 4},
... ]
>>> print PLOD(test).missing()
False
>>> if PLOD(test).eq("name", "Simon").missing():
...    print "Simon not found"
Simon not found
Returns: False if list has one ore more entries, else True.
missingKey(key, notNone=False)
Return entries where the key is NOT present.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": None,  "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).missingKey("income").returnString()
[
    {age: 18, name: 'Larry', wigs: [3, 2, 9]}
]
>>> print PLOD(test).missingKey("income", notNone=True).returnString()
[
    {age: 18, income: None, name: 'Larry', wigs: [3, 2, 9]},
    {age: 20, income: None, name: 'Joe'  , wigs: [1, 2, 3]}
]
New in version 0.1.2: New in version 0.1.2.

Parameters:

key -- The dictionary key (or cascading list of keys) to locate.

notNone -- If True, then None is the equivalent of a missing key. Otherwise, a key with a value of None is NOT considered missing.

Returns:
self
ne(key, value, includeMissing=False)
Return entries where the key's value is NOT of equal (!=) value.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).ne("name", "Larry").returnString()
[
    {age: 18, income: 93000, name: 'Jim' , wigs:        68},
    {age: 20, income: 15000, name: 'Joe' , wigs: [1, 2, 3]},
    {age: 19, income: 29000, name: 'Bill', wigs: None     }
]
>>> print PLOD(test).ne("income", 15000, includeMissing=True).returnString()
[
    {age: 18, income: 93000, name: 'Jim'  , wigs:        68},
    {age: 18, income: None , name: 'Larry', wigs: [3, 2, 9]},
    {age: 19, income: 29000, name: 'Bill' , wigs: None     }
]
New in version 0.1.1: New in version 0.1.1.

Parameters:

key -- The dictionary key (or cascading list of keys) that should be the basis of comparison.

value -- The value to compare with.

includeMissing -- Defaults to False. If True, then entries missing the key are also included.

Returns:
self
renumber(key, start=1, increment=1, insert=False)
Incrementally number a key based on the current order of the list.

Please note that if an entry in the list does not have the specified key, it is NOT created (unless insert=True is passed). The entry is, however, still counted.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "order": 2},
...    {"name": "Larry", "age": 18,                  "order": 3},
...    {"name": "Joe",   "age": 20, "income": 15000, "order": 1},
...    {"name": "Bill",  "age": 19, "income": 29000},
... ]
>>> print PLOD(test).renumber("order", start=10).returnString(honorMissing=True)
[
    {age: 18, income: 93000, name: 'Jim'  , order: 10},
    {age: 18,                name: 'Larry', order: 11},
    {age: 20, income: 15000, name: 'Joe'  , order: 12},
    {age: 19, income: 29000, name: 'Bill'            }
]
>>> print PLOD(test).renumber("order", increment=2, insert=True).returnString(honorMissing=True)
[
    {age: 18, income: 93000, name: 'Jim'  , order: 1},
    {age: 18,                name: 'Larry', order: 3},
    {age: 20, income: 15000, name: 'Joe'  , order: 5},
    {age: 19, income: 29000, name: 'Bill' , order: 7}
]
New in version 0.1.2: New in version 0.1.2.

Parameters:

key -- The dictionary key (or cascading list of keys) that should receive the numbering. The previous value is replaced, regardles of type or content. Every entry is still counted; even if the key is missing.

start -- Defaults to 1. The starting number to begin counting with.

increment -- Defaults to 1. The amount to increment by for each entry in the list.

insert -- If True, then the key is inserted if missing. Else, the key is not inserted. Defaults to False.

Returns:
self
returnCSV(keys=None, limit=False, omitHeaderLine=False, quoteChar=None, eolChars='rn')
Return a list of dictionaries formated as a comma seperated values (CSV) list in a string.

Each entry is on one line. By default, each value is seperated by commas and each entry is followed by a newline ('n').

By default, RFC4180 is followed. See:

http://tools.ietf.org/html/rfc4180

The RFC has considerable detail describing the format.

Note regarding certain RFC section 2 sub 4: there is no default behavior specified if the last field on a line is empty and thus creating a 'trailing comma'. This routine handles it by quoting the final field. The first example below demonstrates this for the entry with 'name' of 'Larry' and a missing 'income' field. The missing field is shown as "" at the end of the line.

Missing keys and/or values of None are simply blank.

Example of use:
>>> test = [
...    {"name": "Jim, Phd",         "age": 18  , "income": 93000, "order": 2},
...    {"name": "Larry",            "age": None,                  "order": 3},
...    {"name": "Joe",              "age": 20  , "income": 15000, "order": 1},
...    {"name": "B \"Zip\" O'Tool", "age": 19  , "income": 29000, "order": 4},
... ]
>>> print PLOD(test).returnCSV()   # doctest: +NORMALIZE_WHITESPACE
age,order,name,income
18,2,"Jim, Phd",93000
,3,Larry,""
20,1,Joe,15000
19,4,"B ""Zip"" O'Tool",29000
<BLANKLINE>
>>> print PLOD(test).returnCSV(limit=3, omitHeaderLine=True, quoteChar="'", eolChars='\n')
'18','2','Jim, Phd','93000'
'','3','Larry',''
'20','1','Joe','15000'
<BLANKLINE>
>>> print PLOD(test).returnCSV(keys=["name", "age"], quoteChar='"', eolChars='\n')
"name","age"
"Jim, Phd","18"
"Larry",""
"Joe","20"
"B ""Zip"" O'Tool","19"
<BLANKLINE>
Parameters:

keys --

If the 'keys' parameter is passed a list of keys, then only those keys are returned. The order of keys in the list is retained. If a key is not found in an entry (or in any entry), that is not an error condition. Those entries simply have an empty value for that position.

NOTE: use this parameter if the order of the keys is critical. Order is not guaranteed otherwise.

limit -- A number limiting the quantity of entries to return. Defaults to False, which means that the full list is returned.

omitHeaderLine -- If set to True, the initial line of text listing the keys is not included. Defaults to False.

quoteChar -- If set to anything (including a single quote), then all fields will be surrounded by the quote character.

eolChars -- These are the characters inserted at the end of each line. By default they are CRLF ('rn') as specified in RFC4180. To be more pythonic you could change it to 'n'.

Returns:
A string containing a formatted textual representation of the list of dictionaries.
returnIndexList(limit=False)
Return a list of integers that are list-index references to the original list of dictionaries."

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "order": 2},
...    {"name": "Larry", "age": 18,                  "order": 3},
...    {"name": "Joe",   "age": 20, "income": 15000, "order": 1},
...    {"name": "Bill",  "age": 19, "income": 29000, "order": 4},
... ]
>>> print PLOD(test).returnIndexList()
[0, 1, 2, 3]
>>> print PLOD(test).sort("name").returnIndexList()
[3, 0, 2, 1]
Parameters: limit -- A number limiting the quantity of entries to return. Defaults to False, which means that the full list is returned.

Returns: A list of integers representing the original indices.
returnList(limit=False)
Return a true list of dictionaries (and not a PLOD class).

The list returned maintains the 'types' of the original entries unless another operation has explicity change them. For example, an 'upsert' replacement of an entry.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": [9, 12]  },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> my_list = PLOD(test).sort("age").returnList()
>>> print my_list
[{'age': 18, 'name': 'Jim', 'wigs': [9, 12], 'income': 93000}, {'age': 18, 'name': 'Larry', 'wigs': [3, 2, 9]}, {'age': 19, 'name': 'Bill', 'income': 29000}, {'age': 20, 'name': 'Joe', 'wigs': [1, 2, 3], 'income': 15000}]
>>> print my_list[2]["age"]
19
Parameters: limit -- A number limiting the quantity of entries to return. Defaults to False, which means that the full list is returned.

Returns: the list of dictionaries
returnOneEntry(last=False)
Return the first entry in the current list. If 'last=True', then the last entry is returned."

Returns None is the list is empty.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "order": 2},
...    {"name": "Larry", "age": 18,                  "order": 3},
...    {"name": "Joe",   "age": 20, "income": 15000, "order": 1},
...    {"name": "Bill",  "age": 19, "income": 29000, "order": 4},
... ]
>>> print PLOD(test).returnOneEntry()
{'age': 18, 'order': 2, 'name': 'Jim', 'income': 93000}
>>> print PLOD(test).returnOneEntry(last=True)
{'age': 19, 'order': 4, 'name': 'Bill', 'income': 29000}
Parameters: last -- If True, the last entry is returned rather than the first.

Returns: A list entry, or None if the list is empty.
returnOneIndex(last=False)
Return the first origin index (integer) of the current list. That index refers to it's placement in the original list of dictionaries."

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "order": 2},
...    {"name": "Larry", "age": 18,                  "order": 3},
...    {"name": "Joe",   "age": 20, "income": 15000, "order": 1},
...    {"name": "Bill",  "age": 19, "income": 29000, "order": 4},
... ]
>>> print PLOD(test).returnOneIndex()
0
>>> print PLOD(test).sort("name").returnOneIndex()
3
Parameters: last -- The last origin of the current list is returned rather than the first.

Returns: An integer representing the original placement of the first item in the list.
returnString(limit=False, omitBrackets=False, executable=False, honorMissing=False)
Return a string containing the list of dictionaries in easy human-readable read format.

Each entry is on one line. Key/value pairs are 'spaced' in such a way as to have them all line up vertically if using a monospace font. The fields are normalized to alphabetical order. Missing keys in a dictionary are inserted with a value of 'None' unless honorMissing is set to True.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "order": 2},
...    {"name": "Larry", "age": 18,                  "order": 3},
...    {"name": "Joe",   "age": 20, "income": 15000, "order": 1},
...    {"name": "Bill",  "age": 19, "income": 29000, "order": 4},
... ]
>>> print PLOD(test).returnString()
[
    {age: 18, income: 93000, name: 'Jim'  , order: 2},
    {age: 18, income: None , name: 'Larry', order: 3},
    {age: 20, income: 15000, name: 'Joe'  , order: 1},
    {age: 19, income: 29000, name: 'Bill' , order: 4}
]
>>> print PLOD(test).returnString(limit=3, omitBrackets=True, executable=True)
{'age': 18, 'income': 93000, 'name': 'Jim'  , 'order': 2},
{'age': 18, 'income': None , 'name': 'Larry', 'order': 3},
{'age': 20, 'income': 15000, 'name': 'Joe'  , 'order': 1}
>>> print PLOD(test).returnString(honorMissing=True)
[
    {age: 18, income: 93000, name: 'Jim'  , order: 2},
    {age: 18,                name: 'Larry', order: 3},
    {age: 20, income: 15000, name: 'Joe'  , order: 1},
    {age: 19, income: 29000, name: 'Bill' , order: 4}
]
Parameters:

limit -- A number limiting the quantity of entries to return. Defaults to False, which means that the full list is returned.

omitBrackets -- If set to True, the outer square brackets representing the entire list are omitted. Defaults to False.

executable -- If set to True, the string is formatted in such a way that it conforms to Python syntax. Defaults to False.

honorMissing -- If set to True, keys that are missing in a dictionary are simply skipped with spaces. If False, then the key is display and given a value of None. Defaults to False.

Returns:
A string containing a formatted textual representation of the list of dictionaries.
returnValue(key, last=False)
Return the key's value for the first entry in the current list. If 'last=True', then the last entry is referenced."

Returns None is the list is empty or the key is missing.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "order": 2},
...    {"name": "Larry", "age": 18,                  "order": 3},
...    {"name": "Joe",   "age": 20, "income": 15000, "order": 1},
...    {"name": "Bill",  "age": 19, "income": 29000, "order": 4},
... ]
>>> print PLOD(test).returnValue("name")
Jim
>>> print PLOD(test).sort("name").returnValue("name", last=True)
Larry
>>> print PLOD(test).sort("name").returnValue("income", last=True)
None
Parameters: last -- If True, the last entry is used rather than the first.

Returns: A value, or None if the list is empty or the key is missing.
returnValueList(key_list, last=False)
Return a list of key values for the first entry in the current list. If 'last=True', then the last entry is referenced."

Returns None is the list is empty. If a key is missing, then that entry in the list is None.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "order": 2},
...    {"name": "Larry", "age": 18,                  "order": 3},
...    {"name": "Joe",   "age": 20, "income": 15000, "order": 1},
...    {"name": "Bill",  "age": 19, "income": 29000, "order": 4},
... ]
>>> print PLOD(test).returnValueList(["name", "income"])
['Jim', 93000]
>>> print PLOD(test).sort("name").returnValueList(["name", "income"], last=True)
['Larry', None]
Parameters: last -- If True, the last entry is used rather than the first.

Returns: A value, or None if the list is empty.
sort(key, reverse=False, none_greater=False)
Sort the list in the order of the dictionary key.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> print PLOD(test).sort("name").returnString()
[
    {age: 19, income: 29000, name: 'Bill' , wigs: None     },
    {age: 18, income: 93000, name: 'Jim'  , wigs:        68},
    {age: 20, income: 15000, name: 'Joe'  , wigs: [1, 2, 3]},
    {age: 18, income: None , name: 'Larry', wigs: [3, 2, 9]}
]
>>> print PLOD(test).sort("income").returnString()
[
    {age: 18, income: None , name: 'Larry', wigs: [3, 2, 9]},
    {age: 20, income: 15000, name: 'Joe'  , wigs: [1, 2, 3]},
    {age: 19, income: 29000, name: 'Bill' , wigs: None     },
    {age: 18, income: 93000, name: 'Jim'  , wigs:        68}
]
New in version 0.0.2: New in version 0.0.2.

Parameters:

key -- The dictionary key (or cascading list of keys) that should be the bassis of the sorting.

reverse -- Defaults to False. If True, then list is sorted decrementally.

none_greater -- Defaults to False. If True, then entries missing the key/value pair are considered be of greater value than the non-missing values.

Returns:
self
upsert(key, value, entry)
Update or Insert an entry into the list of dictionaries.

If a dictionary in the list is found where key matches the value, then

the FIRST matching list entry is replaced with entry

else

the entry is appended to the end of the list.

The new entry is not examined in any way. It is, in fact, possible to upsert an entry that does not match the supplied key/value.

Example of use:
>>> test = [
...    {"name": "Jim",   "age": 18, "income": 93000, "wigs": 68       },
...    {"name": "Larry", "age": 18,                  "wigs": [3, 2, 9]},
...    {"name": "Joe",   "age": 20, "income": 15000, "wigs": [1, 2, 3]},
...    {"name": "Bill",  "age": 19, "income": 29000                   },
... ]
>>> entryA = {"name": "Willie", "age": 77}
>>> myPLOD = PLOD(test)
>>> print myPLOD.upsert("name", "Willie", entryA).returnString()
[
    {age: 18, income: 93000, name: 'Jim'   , wigs:        68},
    {age: 18, income: None , name: 'Larry' , wigs: [3, 2, 9]},
    {age: 20, income: 15000, name: 'Joe'   , wigs: [1, 2, 3]},
    {age: 19, income: 29000, name: 'Bill'  , wigs: None     },
    {age: 77, income: None , name: 'Willie', wigs: None     }
]
>>> entryB = {"name": "Joe", "age": 20, "income": 30, "wigs": [3, 2, 9]}
>>> print myPLOD.upsert("name", "Joe", entryB).returnString()
[
    {age: 18, income: 93000, name: 'Jim'   , wigs:        68},
    {age: 18, income: None , name: 'Larry' , wigs: [3, 2, 9]},
    {age: 20, income:    30, name: 'Joe'   , wigs: [3, 2, 9]},
    {age: 19, income: 29000, name: 'Bill'  , wigs: None     },
    {age: 77, income: None , name: 'Willie', wigs: None     }
]
Parameters:

key -- The dictionary key to examine.

value -- The value to search for as referenced by the key.

entry -- The replacement (or new) entry for the list.

Returns:
class

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Code

PLOD Library Reference

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Parameters:	key -- The dictionary key (or cascading list of keys point to final key) that should be removed. value -- The value assigned to the key.
Returns:	self

Parameters:	finalAll -- If True, then all the values in the 'value' parameter must be found. exclude -- If 'exclude' is True, then the entries that do NOT match the above conditions are returned. includeMissing -- If 'includeMissing' is True, then if the key is missing then that entry is included in the results. However, it does not include entries that have the key but its value is for a non-list or empty list.
Returns:	self

Parameters:	index -- An integer representing the place of entry in the original list of dictionaries.
Returns:	self

Parameters:	indexList -- A list of integer representing the places of entry in the original list of dictionaries.
Returns:	self

Parameters:	keys -- If the 'keys' parameter is passed a list of keys, then only those keys are returned. The order of keys in the list is retained. If a key is not found in an entry (or in any entry), that is not an error condition. Those entries simply have an empty value for that position. NOTE: use this parameter if the order of the keys is critical. Order is not guaranteed otherwise. limit -- A number limiting the quantity of entries to return. Defaults to False, which means that the full list is returned. omitHeaderLine -- If set to True, the initial line of text listing the keys is not included. Defaults to False. quoteChar -- If set to anything (including a single quote), then all fields will be surrounded by the quote character. eolChars -- These are the characters inserted at the end of each line. By default they are CRLF ('rn') as specified in RFC4180. To be more pythonic you could change it to 'n'.
Returns:	A string containing a formatted textual representation of the list of dictionaries.

Parameters:	limit -- A number limiting the quantity of entries to return. Defaults to False, which means that the full list is returned.
Returns:	A list of integers representing the original indices.

Parameters:	last -- If True, the last entry is returned rather than the first.
Returns:	A list entry, or None if the list is empty.

Parameters:	last -- The last origin of the current list is returned rather than the first.
Returns:	An integer representing the original placement of the first item in the list.

Parameters:	last -- If True, the last entry is used rather than the first.
Returns:	A value, or None if the list is empty or the key is missing.

Parameters:	key -- The dictionary key to examine. value -- The value to search for as referenced by the key. entry -- The replacement (or new) entry for the list.
Returns:	class