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

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 has 100% test coverage, over 50,000 downloads, and no open issues.

Build Status Coverage Version Downloads

Installation

TinyFlux is hosted at PyPI and is easily downloadable with pip. TinyFlux has been tested with Python 3.7 - 3.12 and PyPy-3.9 on Linux and Windows platforms.

$ pip install tinyflux

Introduction

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.

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

  4. TinyFlux at the Edge (with Backup Strategy)

Tips

Checkout some tips for working with TinyFlux here.

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

Project details


Download files

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

Source Distribution

tinyflux-1.0.0.tar.gz (56.0 kB view details)

Uploaded Source

Built Distribution

tinyflux-1.0.0-py3-none-any.whl (35.9 kB view details)

Uploaded Python 3

File details

Details for the file tinyflux-1.0.0.tar.gz.

File metadata

  • Download URL: tinyflux-1.0.0.tar.gz
  • Upload date:
  • Size: 56.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.12.3

File hashes

Hashes for tinyflux-1.0.0.tar.gz
Algorithm Hash digest
SHA256 a7aea4648d50cdcee4bb7904c37b2eedf27df39a3eb68f1ff22b77e9c30f1447
MD5 333291ab8e5760b971266e03760d4c09
BLAKE2b-256 c79fe47b2b293ce41b29ddc78f712b84d30bd463fe3427cb6eb0e39b6fd478be

See more details on using hashes here.

File details

Details for the file tinyflux-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: tinyflux-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 35.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.12.3

File hashes

Hashes for tinyflux-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 0d191d5a11bb86f01d3b015ccc3130713abaa21cbc8f85d79066cd34a3650490
MD5 624b9c7031fc6f7256ede8a818bad3cc
BLAKE2b-256 80c13a266c9dd902116d3cd46391dbe8d14f62bb0e3ec9b5c6f788b8b0e847bd

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page