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: about 2 months ago
JSON representation

The tiny time series database optimized for your happiness.

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 50,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/