Metadata-Version: 2.1
Name: tinyflux
Version: 0.3.1
Summary: The Tiny Time-Series Database Optimized for Your Happiness
Home-page: https://github.com/citrusvanilla/tinyflux
Author: Justin Fung
Author-email: justincaseyfung@gmail.com
Project-URL: Documentation, https://tinyflux.readthedocs.io/en/latest/
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE

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

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

Quick Links
***********

- `Example Code Snippets`_
- `Full Example Notebooks and Scripts <https://github.com/citrusvanilla/tinyflux/tree/master/examples>`__
- `Documentation <http://tinyflux.readthedocs.org/>`__
- `Changelog <https://tinyflux.readthedocs.io/en/latest/changelog.html>`__
- `Contributing`_


Recent Updates
**************

v0.3.1 - March 27, 2023
=========================

* Fixed bug that allowed user to delete key/field tags with `.update()` and `.update_all()` (resolves issue #36).

v0.3.0 - March 23, 2023
=========================

* Tag and field keys can be compacted when using CSVStorage, saving potentially many bytes per Point (resolves issue #32).
* Fixed bug that causes tag values of `""` to be serialized as `"_none"` (resolves issue #33).

See the `Changelog <https://tinyflux.readthedocs.io/en/latest/changelog.html>`__ for more.


Installation
************

.. code-block:: bash

    $ pip install tinyflux

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

.. code-block:: bash

    $ pip install .


Introduction
************

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

TinyFlux is a time series version of `TinyDB <https://tinydb.readthedocs.io/en/latest/index.html>`__ 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 <https://tinyflux.readthedocs.io/>`__.  Examples can be found in the `examples directory <https://github.com/citrusvanilla/tinyflux/tree/master/examples>`__.  You can also discuss topics related to TinyFlux including general development, extensions, or showcase your TinyFlux-based projects on the `GitHub discussion forum <https://github.com/citrusvanilla/tinyflux/discussions>`__.

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

.. 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 <https://github.com/citrusvanilla/tinyflux/tree/master/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 <https://github.com/citrusvanilla/tinyflux/blob/master/examples/1_initializing_and_loading_new_db.ipynb>`__
2. `Local Analytics Workflow with a TinyFlux Database <https://github.com/citrusvanilla/tinyflux/blob/master/examples/2_analytics_workflow.ipynb>`__
3. `TinyFlux as a MQTT Datastore for IoT Devices <https://github.com/citrusvanilla/tinyflux/blob/master/examples/3_iot_datastore_with_mqtt.py>`__

Tips
****

Checkout some tips for working with TinyFlux `here <https://tinyflux.readthedocs.io/en/latest/tips.html>`__.


TinyFlux Across the Internet
****************************

Articles, tutorials, and other instances of TinyFlux:

- `"Introducing TinyFlux: The Tiny Time Series Database for Python-based IoT & Analytics Applications" <https://citrusvanilla.medium.com/introducing-tinyflux-the-tiny-time-series-database-for-python-based-iot-analytics-applications-c3ef3c3bedf>`__: A Medium.com article announcing the release of TinyFlux
- `"Storing Time Series Data in Python Using TinyFluxDB" <http://www.steves-internet-guide.com/storing-time-series-data-python-using-tinyflux-db/>`__: A tutorial from `Steve's Internet Guide <http://www.steves-internet-guide.com/>`__, 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 <https://tinyflux.readthedocs.io/en/latest/getting-started.html>`__ and the `Contributing Tooling and Conventions <https://tinyflux.readthedocs.io/en/latest/contributing-tooling.html>`__ section of the documentation.
2. Check GitHub for `existing open issues <https://github.com/citrusvanilla/tinyflux/issues>`__, `open a new issue <https://github.com/citrusvanilla/tinyflux/issues/new>`__ or `start a new discussion <https://github.com/citrusvanilla/tinyflux/discussions/new>`__.
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
.. |Coverage| image:: https://codecov.io/gh/citrusvanilla/tinyflux/branch/master/graph/badge.svg?token=IEGQ4E57VA
   :target: https://app.codecov.io/gh/citrusvanilla
.. |Version| image:: http://img.shields.io/pypi/v/tinyflux.svg
   :target: https://pypi.python.org/pypi/tinyflux/
.. |Downloads| image:: https://img.shields.io/pypi/dm/tinyflux.svg
   :target: https://pypi.python.org/pypi/tinyflux/
