Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/citrusvanilla/tinyflux

The tiny time series database optimized for your happiness.
https://github.com/citrusvanilla/tinyflux

database iot time-series time-series-database

Last synced: 3 months ago
JSON representation

The tiny time series database optimized for your happiness.

Host: GitHub
URL: https://github.com/citrusvanilla/tinyflux
Owner: citrusvanilla
License: mit
Created: 2022-04-30T21:40:11.000Z (over 2 years ago)
Default Branch: master
Last Pushed: 2024-04-14T00:07:37.000Z (9 months ago)
Last Synced: 2024-04-14T12:16:34.284Z (9 months ago)
Topics: database, iot, time-series, time-series-database
Language: Python
Homepage:
Size: 1.99 MB
Stars: 158
Watchers: 7
Forks: 7
Open Issues: 0
Metadata Files:
- Readme: README.rst
- License: LICENSE

Awesome Lists containing this project

README

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

    :width: 500px

   

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

    :width: 500px

TinyFlux is the tiny time series database optimized for your happiness 😎

TinyFlux is the time series version of `TinyDB `__ that is 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 60,000 downloads, and no open issues.

|Version| |Downloads| |Coverage| |Build Status|

Quick Links

***********

- `Example Code Snippets`_

- `Full Example Notebooks and Scripts `__

- `Documentation `__

- `Changelog `__

- `Contributing`_

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.

.. code-block:: bash

    $ pip install tinyflux

Introduction

************

TinyFlux is:

- **optimized for your happiness:** TinyFlux is designed to be simple and fun to use by providing a clean API that can be learned in about 90 seconds.

- **time-centric:** Python datetime objects are first-class citizens, and both the storage and queries are optimized for time above all else.

- **human-friendly:** The primary datastore is a CSV, making your database human-readable from the very first write. No need to use SQL to investigate your data, just open the DB file in any tabular-friendly application.

- **pure Python:** TinyFlux needs neither an external server nor any dependencies.

- **tiny:** TinyFlux is about 150kb, unzipped. The current source code has 4,000 lines of code (with about 50% documentation) and 4,000 lines of tests.  

- **developed for modern Python:** TinyFlux works on all modern versions of Python (3.7 - 3.12) and PyPy (3.9).

- **100% covered by tests:** 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

===================

.. code-block:: python

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

=================

.. code-block:: python

    >>> 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 four 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 in the wild:

- `"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

- `"KaiCode 2024 Shortlist" `__: TinyFlux came in 10th place out of 412 entrants in the 7th edition of this open-source festival, a festival dedicated to recognizing projects with high-quality open-source principles.

Contributing

************

New ideas, 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.

.. |Build Status| image:: https://github.com/citrusvanilla/tinyflux/actions/workflows/build.yml/badge.svg

   :target: https://github.com/citrusvanilla/tinyflux/actions

.. |Coverage| image:: https://codecov.io/gh/citrusvanilla/tinyflux/branch/master/graph/badge.svg?token=IEGQ4E57VA

   :target: https://app.codecov.io/gh/citrusvanilla/tinyflux

.. |Version| image:: http://img.shields.io/pypi/v/tinyflux.svg

   :target: https://pypi.python.org/pypi/tinyflux/

.. |Downloads| image:: https://img.shields.io/pepy/dt/tinyflux

   :target: https://pypi.python.org/pypi/tinyflux/