{"id":13473043,"url":"https://github.com/citrusvanilla/tinyflux","last_synced_at":"2025-12-30T00:09:29.535Z","repository":{"id":39788943,"uuid":"487386961","full_name":"citrusvanilla/tinyflux","owner":"citrusvanilla","description":"The tiny time series database optimized for your happiness.","archived":false,"fork":false,"pushed_at":"2024-08-13T16:35:28.000Z","size":2114,"stargazers_count":176,"open_issues_count":1,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-30T05:26:27.464Z","etag":null,"topics":["database","iot","time-series","time-series-database"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/citrusvanilla.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-30T21:40:11.000Z","updated_at":"2024-10-20T06:36:29.000Z","dependencies_parsed_at":"2024-05-31T21:07:51.424Z","dependency_job_id":"1a0a2d17-5c19-443b-8594-12426e540137","html_url":"https://github.com/citrusvanilla/tinyflux","commit_stats":{"total_commits":142,"total_committers":5,"mean_commits":28.4,"dds":"0.028169014084507005","last_synced_commit":"f226fbf1ca69b0815c452bdc1af4c27e92462890"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citrusvanilla%2Ftinyflux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citrusvanilla%2Ftinyflux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citrusvanilla%2Ftinyflux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citrusvanilla%2Ftinyflux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/citrusvanilla","download_url":"https://codeload.github.com/citrusvanilla/tinyflux/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245702342,"owners_count":20658597,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","iot","time-series","time-series-database"],"created_at":"2024-07-31T16:01:00.176Z","updated_at":"2025-12-30T00:09:29.489Z","avatar_url":"https://github.com/citrusvanilla.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":".. image:: https://github.com/citrusvanilla/tinyflux/blob/master/artwork/tinyfluxdb-light.png?raw=true#gh-dark-mode-only\n    :width: 500px\n   \n.. image:: https://github.com/citrusvanilla/tinyflux/blob/master/artwork/tinyfluxdb-dark.png?raw=true#gh-light-mode-only\n    :width: 500px\n\nTinyFlux is the tiny time series database optimized for your happiness 😎\n\nTinyFlux is the time series version of `TinyDB \u003chttps://tinydb.readthedocs.io/en/latest/index.html\u003e`__ 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 75,000 downloads, and no open issues.\n\n|Docs| |Version| |Downloads| |Coverage| |Build Status|\n\n\nQuick Links\n***********\n\n- `Example Code Snippets`_\n- `Full Example Notebooks and Scripts \u003chttps://github.com/citrusvanilla/tinyflux/tree/master/examples\u003e`__\n- `Documentation \u003chttp://tinyflux.readthedocs.org/\u003e`__\n- `Changelog \u003chttps://tinyflux.readthedocs.io/en/latest/changelog.html\u003e`__\n- `Contributing`_\n\n\nInstallation\n************\n\nTinyFlux is hosted at `PyPI \u003chttps://pypi.org/project/tinyflux/\u003e`__ 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.\n\n.. code-block:: bash\n\n    $ pip install tinyflux\n\n\nIntroduction\n************\n\nTinyFlux is:\n\n- **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.\n\n- **time-centric:** Python datetime objects are first-class citizens, and both the storage and queries are optimized for time above all else.\n\n- **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.\n\n- **pure Python:** TinyFlux needs neither an external server nor any dependencies.\n\n- **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.  \n\n- **developed for modern Python:** TinyFlux works on all modern versions of Python (3.7 - 3.12) and PyPy (3.9).\n\n- **100% covered by tests:** No explanation needed.\n\nTo get started, head over to the `TinyFlux docs \u003chttps://tinyflux.readthedocs.io/\u003e`__.  Examples can be found in the `examples directory \u003chttps://github.com/citrusvanilla/tinyflux/tree/master/examples\u003e`__.  You can also discuss topics related to TinyFlux including general development, extensions, or showcase your TinyFlux-based projects on the `GitHub discussion forum \u003chttps://github.com/citrusvanilla/tinyflux/discussions\u003e`__.\n\n\nExample Code Snippets\n*********************\n\nWriting to TinyFlux\n===================\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from datetime import datetime, timezone\n    \u003e\u003e\u003e from tinyflux import TinyFlux, Point\n\n    \u003e\u003e\u003e db = TinyFlux('/path/to/db.csv')\n\n    \u003e\u003e\u003e p = Point(\n    ...     time=datetime(2022, 5, 1, 16, 0, tzinfo=timezone.utc),\n    ...     tags={\"room\": \"bedroom\"},\n    ...     fields={\"temp\": 72.0}\n    ... )\n    \u003e\u003e\u003e db.insert(p, compact_key_prefixes=True)\n\n\nQuerying TinyFlux\n=================\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from tinyflux import FieldQuery, TagQuery, TimeQuery\n\n    \u003e\u003e\u003e # Search for a tag value.\n    \u003e\u003e\u003e Tag = TagQuery()\n    \u003e\u003e\u003e db.search(Tag.room == 'bedroom')\n    [Point(time=2022-05-01T16:00:00+00:00, measurement=_default, tags=room:bedroom, fields=temp:72.0)]\n\n    \u003e\u003e\u003e # Search for a field value.\n    \u003e\u003e\u003e Field = FieldQuery()\n    \u003e\u003e\u003e db.select(\"tag.room\", Field.temp \u003e 60.0)\n    [\"bedroom\"]\n\n    \u003e\u003e\u003e # Search for a time value.\n    \u003e\u003e\u003e Time = TimeQuery()\n    \u003e\u003e\u003e time_start = Time \u003e= datetime(2019, 1, 1, tzinfo=timezone.utc)\n    \u003e\u003e\u003e time_end = Time \u003c datetime(2023, 1, 1, tzinfo=timezone.utc)\n    \u003e\u003e\u003e db.count(time_start \u0026 time_end)\n    1\n\n\nFull Example Notebooks and Workflows\n************************************\n\nThe `examples \u003chttps://github.com/citrusvanilla/tinyflux/tree/master/examples\u003e`__ directory of this repository contains four common uses cases for TinyFlux and the associated boilerplate to get you started:\n\n1. `Loading a TinyFlux DB from a CSV \u003chttps://github.com/citrusvanilla/tinyflux/blob/master/examples/1_initializing_and_loading_new_db.ipynb\u003e`__\n2. `Local Analytics Workflow with a TinyFlux Database \u003chttps://github.com/citrusvanilla/tinyflux/blob/master/examples/2_analytics_workflow.ipynb\u003e`__\n3. `TinyFlux as a MQTT Datastore for IoT Devices \u003chttps://github.com/citrusvanilla/tinyflux/blob/master/examples/3_iot_datastore_with_mqtt.py\u003e`__\n4. `TinyFlux at the Edge (with Backup Strategy) \u003chttps://github.com/citrusvanilla/tinyflux/blob/master/examples/4_backing_up_tinyflux_at_the_edge.py\u003e`__\n\nTips\n****\n\nCheckout some tips for working with TinyFlux `here \u003chttps://tinyflux.readthedocs.io/en/latest/tips.html\u003e`__.\n\n\nTinyFlux Across the Internet\n****************************\n\nArticles, tutorials, and other instances of TinyFlux in the wild:\n\n- `\"Introducing TinyFlux: The Tiny Time Series Database for Python-based IoT \u0026 Analytics Applications\" \u003chttps://citrusvanilla.medium.com/introducing-tinyflux-the-tiny-time-series-database-for-python-based-iot-analytics-applications-c3ef3c3bedf\u003e`__: A Medium.com article announcing the release of TinyFlux\n- `\"Storing Time Series Data in Python Using TinyFluxDB\" \u003chttp://www.steves-internet-guide.com/storing-time-series-data-python-using-tinyflux-db/\u003e`__: A tutorial from `Steve's Internet Guide \u003chttp://www.steves-internet-guide.com/\u003e`__, a portal for learning MQTT and IoT development for Python\n- `\"KaiCode 2024 Shortlist\" \u003chttps://www.kaicode.org/2024.html\u003e`__: 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.\n\nContributing\n************\n\nNew ideas, developer tools, improvements, and bugfixes are always welcome.  Follow these guidelines before getting started:\n\n1. Make sure to read `Getting Started \u003chttps://tinyflux.readthedocs.io/en/latest/getting-started.html\u003e`__ and the `Contributing Tooling and Conventions \u003chttps://tinyflux.readthedocs.io/en/latest/contributing-tooling.html\u003e`__ section of the documentation.\n2. Check GitHub for `existing open issues \u003chttps://github.com/citrusvanilla/tinyflux/issues\u003e`__, `open a new issue \u003chttps://github.com/citrusvanilla/tinyflux/issues/new\u003e`__ or `start a new discussion \u003chttps://github.com/citrusvanilla/tinyflux/discussions/new\u003e`__.\n3. To get started on a pull request, fork the repository on GitHub, create a new branch, and make updates.\n4. Write unit tests, ensure the code is 100% covered, update documentation where necessary, and format and style the code correctly.\n5. Send a pull request.\n\n.. |Docs| image:: https://img.shields.io/readthedocs/docs\n   :target: https://tinyflux.readthedocs.io/en/latest/\n.. |Build Status| image:: https://github.com/citrusvanilla/tinyflux/actions/workflows/build.yml/badge.svg\n   :target: https://github.com/citrusvanilla/tinyflux/actions\n.. |Coverage| image:: https://codecov.io/gh/citrusvanilla/tinyflux/branch/master/graph/badge.svg?token=IEGQ4E57VA\n   :target: https://app.codecov.io/gh/citrusvanilla/tinyflux\n.. |Version| image:: http://img.shields.io/pypi/v/tinyflux.svg\n   :target: https://pypi.python.org/pypi/tinyflux/\n.. |Downloads| image:: https://img.shields.io/pepy/dt/tinyflux\n   :target: https://pypi.python.org/pypi/tinyflux/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitrusvanilla%2Ftinyflux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcitrusvanilla%2Ftinyflux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitrusvanilla%2Ftinyflux/lists"}