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
 
__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)
Create empty copy of the current table, with copies of all index definitions.
source code
 
clone(self)
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
 
query(self, **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
 
where(self, wherefn, maxrecs=0)
An alternative to query, using a matching predicate function to determine whether a given object matches the query or not.
source code
 
join(self, other, attrlist=None, **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)
Imports the contents of a CSV-formatted 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

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __str__

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
  • 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 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.

query(self, **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 kwargs:

  • _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.
Parameters:
  • **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

where(self, wherefn, maxrecs=0)

source code 

An alternative to query, using a matching predicate function to determine whether a given object matches the query or not. You must use where in place of query if you want to query using inequalities or more complex matching criteria than simple attribute=value.

Parameters:
  • wherefn (callable(object) returning boolean) - a method or lambda that returns a boolean result, as in:
       lambda ob : ob.unitprice > 10
    
  • maxrecs (int) - if only the first 'n' records are needed, then where will stop after locating 'n' matching records
Returns:
a new Table containing the matching records

join(self, other, attrlist=None, **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)

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.

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