littletable.Table

Module littletable :: Class Table |
[frames] | no frames]

# Class Table

source code

    object --+
             |
            Table

Known Subclasses:
  - PivotTable

Table is the main class in `littletable`, for representing a collection of DataObjects or user-defined objects with publicly accessible attributes or properties. Tables can be:

- created, with an optional name, using standard Python `Table() constructor`
- indexed, with multiple indexes, with unique or non-unique values, see create_index
- queried, specifying values to exact match in the desired records, see where
- filtered (using where), using a simple predicate function to match desired records; useful for selecting using inequalities or compound conditions
- accessed directly for keyed values, using `table.indexattribute[key]` - see __getattr__
- joined, using join_on to identify attribute to be used for joining with another table, and join or operator '+' to perform the actual join
- pivoted, using pivot to create a nested structure of sub-tables grouping objects by attribute values
- grouped, using groupby to create a summary table of computed values, grouped by a key attribute
- imported/exported to CSV-format files

Queries and joins return their results as new Table objects, so that queries and joins can be easily performed as a succession of operations.

Instance Methods
__init__(self, table_name=`'````'`) Create a new, empty Table. | source code
__len__(self) Return the number of objects in the Table. | source code
__iter__(self) Create an iterator over the objects in the Table. | source code
__getitem__(self, i) Provides direct indexed/sliced access to the Table's underlying list of objects. | source code
__getattr__(self, attr) A quick way to query for matching records using their indexed attributes. | source code
__bool__(self) | source code
__nonzero__(self) | source code
__add__(self, other) Support UNION of 2 tables using "+" operator. | source code
__iadd__(self, other) Support UNION of 2 tables using "+=" operator. | source code
union(self, other) | source code
__call__(self, table_name) A simple way to assign a name to a table, such as those dynamically created by joins and queries. | source code
copy_template(self, name=None) Create empty copy of the current table, with copies of all index definitions. | source code
clone(self, name=None) Create full copy of the current table, including table contents and index definitions. | source code
create_index(self, attr, unique=False, accept_none=False) Create a new index on a given attribute. | source code
delete_index(self, attr) Deletes an index from the Table. | source code
insert(self, obj) Insert a new object into this Table. | source code
insert_many(self, it) Inserts a collection of objects into the table. | source code
remove(self, ob) Removes an object from the table. | source code
remove_many(self, it) Removes a collection of objects from the table. | source code
where(self, wherefn=None, **kwargs) Retrieves matching objects from the table, based on given named parameters. | source code
delete(self, **kwargs) Deletes matching objects from the table, based on given named parameters. | source code
sort(self, key, reverse=False) Sort Table in place, using given fields as sort key. | source code
select(self, fields, **exprs) Create a new table containing a subset of attributes, with optionally newly-added fields computed from each rec in the original table. | source code
format(self, *fields, **exprs) Create a new table with all string formatted attribute values, typically in preparation for formatted output. | source code
join(self, other, attrlist=None, auto_create_indexes=True, **kwargs) Join the objects of one table with the objects of another, based on the given matching attributes in the named arguments. | source code
join_on(self, attr) Creates a JoinTerm in preparation for joining with another table, to indicate what attribute should be used in the join. | source code
pivot(self, attrlist) Pivots the data using the given attributes, returning a PivotTable. | source code
csv_import(self, csv_source, encoding=`'``UTF-8``'`, transforms=None) Imports the contents of a CSV-formatted file into this table. | source code
tsv_import(self, xsv_source, transforms=None) Imports the contents of a tab-separated data file into this table. | source code
csv_export(self, csv_dest, fieldnames=None) Exports the contents of the table to a CSV-formatted file. | source code
json_import(self, source, transforms=None) Imports the contents of a JSON data file into this table. | source code
json_export(self, dest, fieldnames=None) Exports the contents of the table to a JSON-formatted file. | source code
add_field(self, attrname, fn, default=None) Computes a new attribute for each object in table, or replaces an existing attribute in each record with a computed value | source code
addfield(self, attrname, fn, default=None) | source code
groupby(self, keyexpr, **outexprs) simple prototype of group by, with support for expressions in the group-by clause and outputs | source code
run(self) | source code
unique(self) | source code
Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__sizeof__`, `__str__`, `__subclasshook__`

Properties
Inherited from `object`: `__class__`

Method Details

### __init__(self, table_name=`'````'`) (Constructor) | source code
Create a new, empty Table. Parameters: `table_name` (string (optional)) - name for Table Overrides: object.__init__

### __getattr__(self, attr) (Qualification operator) | source code
A quick way to query for matching records using their indexed attributes. The attribute name is used to locate the index, and returns a wrapper on the index. This wrapper provides dict-like access to the underlying records in the table, as in:
      employees.by.socsecnum["000-00-0000"]
      customers.by.zipcode["12345"]
(`'by'` is added as a pseudo-attribute on tables, to help indicate that the indexed attributes are not attributes of the table, but of items in the table.) The behavior differs slightly for unique and non-unique indexes: if the index is unique, then retrieving a matching object, will return just the object; if there is no matching object, `KeyError` is raised (making a table with a unique index behave very much like a Python dict) if the index is non-unique, then all matching objects will be returned in a new Table, just as if a regular query had been performed; if no objects match the key value, an empty Table is returned and no exception is raised. If there is no index defined for the given attribute, then `AttributeError` is raised.

### __call__(self, table_name) (Call operator) | source code
A simple way to assign a name to a table, such as those dynamically created by joins and queries. Parameters: `table_name` (string) - name for Table

### create_index(self, attr, unique=False, accept_none=False) | source code
Create a new index on a given attribute. If `unique` is True and records are found in the table with duplicate attribute values, the index is deleted and `KeyError` is raised. If the table already has an index on the given attribute, then no action is taken and no exception is raised. Parameters: `attr` (string) - the attribute to be used for indexed access and joins `unique` (boolean) - flag indicating whether the indexed field values are expected to be unique across table entries `accept_none` (boolean) - flag indicating whether None is an acceptable unique key value for this attribute

### delete_index(self, attr) | source code
Deletes an index from the Table. Can be used to drop and rebuild an index, or to convert a non-unique index to a unique index, or vice versa. Parameters: `attr` (string) - name of an indexed attribute

### insert(self, obj) | source code
Insert a new object into this Table. Parameters: `obj` - any Python object Objects can be constructed using the defined DataObject type, or they can be any Python object that does not use the Python `__slots__` feature; `littletable` introspect's the object's `__dict__` or `_fields` attributes to obtain join and index attributes and values. If the table contains a unique index, and the record to be inserted would add a duplicate value for the indexed attribute, then `KeyError` is raised, and the object is not inserted. If the table has no unique indexes, then it is possible to insert duplicate objects into the table.

### remove(self, ob) | source code
Removes an object from the table. If object is not in the table, then no action is taken and no exception is raised.

### where(self, wherefn=None, **kwargs) | source code
  - Retrieves matching objects from the table, based on given named parameters. If multiple named parameters are given, then only objects that satisfy all of the query criteria will be returned. Special named args: `_orderby="attr,..."` - (Deprecated) resulting table should sort content objects by the `attr`s given in a comma-separated string; to sort in descending order, reference the attribute as `attr desc`. `_limit` - maximum number of records to return Parameters: `wherefn` (callable(object) returning boolean) - a method or lambda that returns a boolean result, as in:
          lambda ob : ob.unitprice > 10
`kwargs` - attributes for selecting records, given as additional named arguments of the form `attrname="attrvalue"`. Returns: a new Table containing the matching objects

### delete(self, **kwargs) | source code
Deletes matching objects from the table, based on given named parameters. If multiple named parameters are given, then only objects that satisfy all of the query criteria will be removed. Parameters: `kwargs` - attributes for selecting records, given as additional named arguments of the form `attrname="attrvalue"`. Returns: the number of objects removed from the table

### sort(self, key, reverse=False) | source code
Sort Table in place, using given fields as sort key. Parameters: `key` - if this is a string, it is a comma-separated list of field names, optionally followed by 'desc' to indicate descending sort instead of the default ascending sort; if a list or tuple, it is a list or tuple of field names or field names with ' desc' appended; if it is a function, then it is the function to be used as the sort key function Returns: self

### select(self, fields, **exprs) | source code
Create a new table containing a subset of attributes, with optionally newly-added fields computed from each rec in the original table. Special kwargs: `_unique=True` - (Deprecated) only return a set of unique rows Parameters: `fields` (list, or space-delimited string) - list of strings, or single space-delimited string, listing attribute name to be included in the output `exprs` (`name=callable`, callable takes the record as an argument, and returns the new attribute value If a string is passed as a callable, this string will be used using string formatting, given the record as a source of interpolation values. For instance, `fullName = '%(lastName)s, %(firstName)s'`) - one or more named callable arguments, to compute additional fields using the given function

### format(self, *fields, **exprs) | source code
Create a new table with all string formatted attribute values, typically in preparation for formatted output. Parameters: `fields` (string (multiple)) - one or more strings, each string is an attribute name to be included in the output `exprs` (name=string) - one or more named string arguments, to format the given attribute with a formatting string

### join(self, other, attrlist=None, auto_create_indexes=True, **kwargs) | source code
Join the objects of one table with the objects of another, based on the given matching attributes in the named arguments. The attrlist specifies the attributes to be copied from the source tables - if omitted, all attributes will be copied. Entries in the attrlist may be single attribute names, or if there are duplicate names in both tables, then a `(table,attributename)` tuple can be given to disambiguate which attribute is desired. A `(table,attributename,alias)` tuple can also be passed, to rename an attribute from a source table. This method may be called directly, or can be constructed using the join_on method and the '+' operator. Using this syntax, the join is specified using `table.join_on("xyz")` to create a JoinTerm containing both table and joining attribute. Multiple JoinTerm or tables can be added to construct a compound join expression. When complete, the join expression gets executed by calling the resulting join definition, using `join_expression([attrlist])`. Parameters: `other` - other table to join to `attrlist` (string, or list of strings or `(table,attribute[,alias])` tuples (list may contain both strings and tuples)) - list of attributes to be copied to the new joined table; if none provided, all attributes of both tables will be used (taken from the first object in each table) `kwargs` - attributes to join on, given as additional named arguments of the form `table1attr="table2attr"`, or a dict mapping attribute names. Returns: a new Table containing the joined data as new DataObjects

### join_on(self, attr) | source code
Creates a JoinTerm in preparation for joining with another table, to indicate what attribute should be used in the join. Only indexed attributes may be used in a join. Parameters: `attr` (string) - attribute name to join from this table (may be different from the attribute name in the table being joined to) Returns: JoinTerm

### pivot(self, attrlist) | source code
Pivots the data using the given attributes, returning a PivotTable. Parameters: `attrlist` (list of strings, or string of space-delimited attribute names) - list of attributes to be used to construct the pivot table

### csv_import(self, csv_source, encoding=`'``UTF-8``'`, transforms=None) | source code
Imports the contents of a CSV-formatted file into this table. Parameters: `csv_source` (string or file) - CSV file - if a string is given, the file with that name will be opened, read, and closed; if a file object is given, then that object will be read as-is, and left for the caller to be closed. `transforms` (dict (optional)) - dict of functions by attribute name; if given, each attribute will be transformed using the corresponding transform; if there is no matching transform, the attribute will be read as a string (default); the transform function can also be defined as a (function, default-value) tuple; if there is an Exception raised by the transform function, then the attribute will be set to the given default value

### tsv_import(self, xsv_source, transforms=None) | source code
Imports the contents of a tab-separated data file into this table. Parameters: `xsv_source` (string or file) - tab-separated data file - if a string is given, the file with that name will be opened, read, and closed; if a file object is given, then that object will be read as-is, and left for the caller to be closed. `transforms` (dict (optional)) - dict of functions by attribute name; if given, each attribute will be transformed using the corresponding transform; if there is no matching transform, the attribute will be read as a string (default); the transform function can also be defined as a (function, default-value) tuple; if there is an Exception raised by the transform function, then the attribute will be set to the given default value

### csv_export(self, csv_dest, fieldnames=None) | source code
Exports the contents of the table to a CSV-formatted file. Parameters: `csv_dest` (string or file) - CSV file - if a string is given, the file with that name will be opened, written, and closed; if a file object is given, then that object will be written as-is, and left for the caller to be closed. `fieldnames` - attribute names to be exported; can be given as a single string with space-delimited names, or as a list of attribute names

### json_import(self, source, transforms=None) | source code
Imports the contents of a JSON data file into this table. Parameters: `source` (string or file) - JSON data file - if a string is given, the file with that name will be opened, read, and closed; if a file object is given, then that object will be read as-is, and left for the caller to be closed. `transforms` (dict (optional)) - dict of functions by attribute name; if given, each attribute will be transformed using the corresponding transform; if there is no matching transform, the attribute will be read as a string (default); the transform function can also be defined as a (function, default-value) tuple; if there is an Exception raised by the transform function, then the attribute will be set to the given default value

### json_export(self, dest, fieldnames=None) | source code
Exports the contents of the table to a JSON-formatted file. Parameters: `dest` (string or file) - output file - if a string is given, the file with that name will be opened, written, and closed; if a file object is given, then that object will be written as-is, and left for the caller to be closed. `fieldnames` - attribute names to be exported; can be given as a single string with space-delimited names, or as a list of attribute names

### add_field(self, attrname, fn, default=None) | source code
  - Computes a new attribute for each object in table, or replaces an existing attribute in each record with a computed value Parameters: `attrname` (string) - attribute to compute for each object `fn` (function(obj) returns value) - function used to compute new attribute value, based on other values in the object, as in:
           lambda ob : ob.commission_pct/100.0 * ob.gross_sales
`default` - value to use if an exception is raised while trying to evaluate fn

### groupby(self, keyexpr, **outexprs) | source code
simple prototype of group by, with support for expressions in the group-by clause and outputs Parameters: `keyexpr` (string or tuple) - grouping field and optional expression for computing the key value; if a string is passed `outexprs` (callable, taking a sequence of objects as input and returning a single summary value) - named arguments describing one or more summary values to compute per key