Time Series Peristence

This Python package provides Time Series storage in flat files according to the TeaFile file format.

In Use

>>> tf = TeaFile.create("acme.tea", "Time Price Volume", "qdq", "ACME at NYSE", {"decimals": 2, "url": "" })
>>> tf.write(DateTime(2011, 3, 4,  9, 0), 45.11, 4500)
>>> tf.write(DateTime(2011, 3, 4, 10, 0), 46.33, 1100)
>>> tf.close()
>>> tf = TeaFile.openread("acme.tea")
TPV(Time=2011-03-04 09:00:00:000, Price=45.11, Volume=4500)
TPV(Time=2011-03-04 10:00:00:000, Price=46.33, Volume=1100)
>>> tf.close()

Exchange Time Series between Apps / OS

You can create, read and write TeaFiles with

  • C++,
  • C#,
  • R or
  • other applications


  • Linux / Unix
  • Mac OS
  • Windows

Python API Examples


TeaFiles are a very simple, yet highly efficient, way to store time series data providing data exchange between programs written in C++, C# or applications like R, Octave, Matlab, running on Linux, Unix, Mac OS X or Windows.

  • Binary data composed from elementary data types signed and unsigned integers, double and float in IEEE 754 format is prefixed by a header holding a description of the item structure and the content.
  • Data can be directly accessed via memory mapping.
  • TeaFiles are self describing: Containing a description of the item structure they relieve opaqueness of straight binary files. Knowing that a file is a TeaFile is enough to access its data.

link to spec http://tbd

Scope of the Python API

The Python API makes TeaFiles accessible everywhere. It just needs a python installation on any OS to inspect the description and data of a TeaFile:

>>> # Show the decimals and displayname for all files in a folder:
>>> def showdecimals():
    ...     for filename in os.listdir('.'):
    ...         with TeaFile.openread(filename) as tf:
    ...             nvs = tf.description.namevalues
    ...             print('{} {} {}'.format(filename, nvs.get('Decimals'), nvs.get('DisplayName')))
    >>> showdecimals() 2 Alcoa, Inc.
    AA.tick.tea 2 Alcoa, Inc. 2 American Express Co.

Data download from web services is also a good fit. See the file in the package source for a Yahoo finance download function in about 30 lines.


When it comes to high performance processing of very large time series files, this API is currently not as fast as the C++ and C# APIs (Numbers coming soon on http://tbd). There are numerous ways to improve this if necessary, but no current plans at discretelogics to do so. Using the other languages/APIs is recommended. If you wish the Python API to be faster or want to work on that contact us.


$ pip install teafiles

package source with at


Run the unit tests from the package root by

$ python -m pytest .test

Python 2.7 / 3.2

Package tested under CPython 2.7. Python 3.2 planned


This API brought to you by discretelogics, company specialicing in time series analysis and event processing. http://tbd

Version 0.7

The current version is reasonably tested by doctests and some pytests. Better test coverage with unit tests (currently pytest is used) is desirable.

tbd towards version 1.0
  • enhance pytest coverage
  • consider api feedack
  • cleaner test runs, cleanup test files
  • enhance performance after measuring it in python 3 (maybe struct module plays a minor role there)


This package is released under the GNU GENERAL PUBLIC LICENSE, see License.txt.


Welcome at: