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

Class Table

source code

object --+
         |
        Table
Known Subclasses:

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:

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, *args, **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, 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.socsecnum["000-00-0000"]
  customers.zipcode["12345"]

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, *args, **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,..." - resulting table should sort content objects by the attrs 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 - 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, 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