citrusvanilla/tinyflux

Quick Links

• Example Code Snippets
• Full Example Notebooks and Scripts
• Documentation
• Changelog
• Contributing

Recent Updates

v0.4.0 - March 27, 2023

• Tags and Fields can be removed from individual points. See the documentation for details (issue #27).
• Bugfixes (issue #36).

v0.3.0 - March 23, 2023

• Tag and field keys can be compacted when using CSVStorage, saving potentially many bytes per Point (issue #32).
• Bugfixes (issue #33).

See the Changelog for more.

Installation

TinyFlux is hosted at PyPI and is easily downloadable with pip:

$ pip install tinyflux

Introduction

TinyFlux is the tiny time series database optimized for your happiness :)

TinyFlux is a time series version of TinyDB that is also written in Python and has no external dependencies. It's a great companion for small analytics workflows and apps, as well as at-home IOT data stores.

TinyFlux is:

• time-centric: Python datetime objects are first-class citizens and queries are optimized for time, above all else.
• optimized for your happiness: TinyFlux is designed to be simple and fun to use by providing a simple and clean API that can be learned in 5 minutes.
• tiny: The current source code has 4,000 lines of code (with about 50% documentation) and 4,000 lines of tests. TinyFlux is about 150kb, unzipped.
• written in pure Python: TinyFlux needs neither an external server nor any dependencies.
• works on Python 3.7+ and PyPy-3.9: TinyFlux works on all modern versions of Python and PyPy.
• 100% test coverage: No explanation needed.

To get started, head over to the TinyFlux docs. Examples can be found in the examples directory. You can also discuss topics related to TinyFlux including general development, extensions, or showcase your TinyFlux-based projects on the GitHub discussion forum.

Supported Python Versions

TinyFlux has been tested with Python 3.7 - 3.11 and PyPy-3.9 on Linux and Windows platforms.

Example Code Snippets

Writing to TinyFlux

>>> from datetime import datetime, timezone
>>> from tinyflux import TinyFlux, Point

>>> db = TinyFlux('/path/to/db.csv')

>>> p = Point(
...     time=datetime(2022, 5, 1, 16, 0, tzinfo=timezone.utc),
...     tags={"room": "bedroom"},
...     fields={"temp": 72.0}
... )
>>> db.insert(p, compact_key_prefixes=True)

Querying TinyFlux

>>> from tinyflux import FieldQuery, TagQuery, TimeQuery

>>> # Search for a tag value.
>>> Tag = TagQuery()
>>> db.search(Tag.room == 'bedroom')
[Point(time=2022-05-01T16:00:00+00:00, measurement=_default, tags=room:bedroom, fields=temp:72.0)]

>>> # Search for a field value.
>>> Field = FieldQuery()
>>> db.select("tag.room", Field.temp > 60.0)
["bedroom"]

>>> # Search for a time value.
>>> Time = TimeQuery()
>>> time_start = Time >= datetime(2019, 1, 1, tzinfo=timezone.utc)
>>> time_end = Time < datetime(2023, 1, 1, tzinfo=timezone.utc)
>>> db.count(time_start & time_end)
1

Full Example Notebooks and Workflows

The examples directory of this repository contains three common uses cases for TinyFlux and the associated boilerplate to get you started:

1. Loading a TinyFlux DB from a CSV
2. Local Analytics Workflow with a TinyFlux Database
3. TinyFlux as a MQTT Datastore for IoT Devices

Tips

Checkout some tips for working with TinyFlux here.

TinyFlux Across the Internet

Articles, tutorials, and other instances of TinyFlux:

• "Introducing TinyFlux: The Tiny Time Series Database for Python-based IoT & Analytics Applications": A Medium.com article announcing the release of TinyFlux
• "Storing Time Series Data in Python Using TinyFluxDB": A tutorial from Steve's Internet Guide, a portal for learning MQTT and IoT development for Python

Contributing

New ideas, new developer tools, improvements, and bugfixes are always welcome. Follow these guidelines before getting started:

1. Make sure to read Getting Started and the Contributing Tooling and Conventions section of the documentation.
2. Check GitHub for existing open issues, open a new issue or start a new discussion.
3. To get started on a pull request, fork the repository on GitHub, create a new branch, and make updates.
4. Write unit tests, ensure the code is 100% covered, update documentation where necessary, and format and style the code correctly.
5. Send a pull request.