Skip to main content

The Tiny Time-Series Database Optimized for Your Happiness

Project description

https://github.com/citrusvanilla/tinyflux/blob/master/artwork/tinyfluxdb-light.png?raw=true#gh-dark-mode-only https://github.com/citrusvanilla/tinyflux/blob/master/artwork/tinyfluxdb-dark.png?raw=true#gh-light-mode-only

Build Status Coverage Version

Installation

$ pip install tinyflux

Or, download this repository, cd into it, and:

$ pip install .

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 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 (rc2) and PyPy-3.9.

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)

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

TinyFlux Across the Internet

Articles, tutorials, and other instances of TinyFlux.

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tinyflux-0.1.0.tar.gz (53.6 kB view hashes)

Uploaded source

Built Distribution

tinyflux-0.1.0-py3-none-any.whl (34.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page