.. 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 是为您的幸福而优化的微型时间序列数据库 😎

TinyFlux 是 TinyDB <https://tinydb.readthedocs.io/en/latest/index.html>__ 的时间序列版本，使用 Python 编写，无外部依赖。它非常适合小型分析工作流和应用程序，以及家庭物联网数据存储。TinyFlux 拥有 100% 的测试覆盖率，超过 60,000 次下载，并且没有未解决的问题。

|版本| |下载量| |覆盖率| |构建状态|

快速链接

---

• 示例代码片段_
• 完整示例笔记本和脚本 <https://github.com/citrusvanilla/tinyflux/tree/master/examples>__
• 文档 <http://tinyflux.readthedocs.org/>__
• 更新日志 <https://tinyflux.readthedocs.io/en/latest/changelog.html>__
• 贡献_

安装

---

TinyFlux 托管在 PyPI <https://pypi.org/project/tinyflux/>__ 上，可以使用 pip 轻松下载。TinyFlux 已在 Linux 和 Windows 平台上使用 Python 3.7 - 3.12 和 PyPy-3.9 进行了测试。

.. code-block:: bash

$ pip install tinyflux

简介

---

TinyFlux 是：

• 为您的幸福而优化： TinyFlux 旨在通过提供简洁的 API 使用起来简单有趣，只需约 90 秒即可学会。

• 以时间为中心： Python datetime 对象是一等公民，存储和查询都优先考虑时间。

• 人性化： 主要数据存储为 CSV 格式，使您的数据库从第一次写入就具有人类可读性。无需使用 SQL 来调查数据，只需在任何支持表格的应用程序中打开数据库文件即可。

• 纯 Python： TinyFlux 既不需要外部服务器，也不需要任何依赖项。

• 微型： TinyFlux 解压后约 150kb。当前源代码有 4,000 行代码（约 50% 是文档）和 4,000 行测试。

• 为现代 Python 开发： TinyFlux 适用于所有现代版本的 Python（3.7 - 3.12）和 PyPy（3.9）。

• 100% 测试覆盖： 无需解释。

要开始使用，请前往 TinyFlux 文档 <https://tinyflux.readthedocs.io/>。示例可以在 examples 目录 <https://github.com/citrusvanilla/tinyflux/tree/master/examples> 中找到。您还可以在 GitHub 讨论论坛 <https://github.com/citrusvanilla/tinyflux/discussions>__ 上讨论与 TinyFlux 相关的主题，包括一般开发、扩展或展示您基于 TinyFlux 的项目。

示例代码片段

---

写入 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)

查询 TinyFlux

.. code-block:: python

>>> from tinyflux import FieldQuery, TagQuery, TimeQuery

>>> # 搜索标签值
>>> 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)]

>>> # 搜索字段值
>>> Field = FieldQuery()
>>> db.select("tag.room", Field.temp > 60.0)
["bedroom"]

>>> # 搜索时间值
>>> 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

完整示例笔记本和工作流程

---

本仓库的 examples <https://github.com/citrusvanilla/tinyflux/tree/master/examples>__ 目录包含了 TinyFlux 的四个常见用例及相关的样板代码，可以帮助您快速入门：

1. 从CSV加载TinyFlux数据库 <https://github.com/citrusvanilla/tinyflux/blob/master/examples/1_initializing_and_loading_new_db.ipynb>__
2. 使用TinyFlux数据库进行本地分析工作流 <https://github.com/citrusvanilla/tinyflux/blob/master/examples/2_analytics_workflow.ipynb>__
3. TinyFlux作为物联网设备的MQTT数据存储 <https://github.com/citrusvanilla/tinyflux/blob/master/examples/3_iot_datastore_with_mqtt.py>__
4. 边缘设备上的TinyFlux（包含备份策略） <https://github.com/citrusvanilla/tinyflux/blob/master/examples/4_backing_up_tinyflux_at_the_edge.py>__

小贴士

---

查看一些使用TinyFlux的小贴士 点击这里 <https://tinyflux.readthedocs.io/en/latest/tips.html>__。

TinyFlux在互联网上的应用

---

关于TinyFlux的文章、教程和其他实例：

• "介绍TinyFlux：为Python基础的物联网和分析应用设计的小型时间序列数据库" <https://citrusvanilla.medium.com/introducing-tinyflux-the-tiny-time-series-database-for-python-based-iot-analytics-applications-c3ef3c3bedf>__：在Medium.com上发布的宣布TinyFlux发布的文章
• "使用TinyFluxDB在Python中存储时间序列数据" <http://www.steves-internet-guide.com/storing-time-series-data-python-using-tinyflux-db/>：来自 Steve的互联网指南 <http://www.steves-internet-guide.com/> 的教程，这是一个学习Python MQTT和物联网开发的门户网站
• "KaiCode 2024入围名单" <https://www.kaicode.org/2024.html>__：TinyFlux在第七届开源节中从412个参赛项目中脱颖而出，位列第10名。这个节日致力于表彰遵循高质量开源原则的项目。

贡献

---

我们始终欢迎新的想法、开发者工具、改进和错误修复。在开始之前，请遵循以下指南：

1. 务必阅读 入门指南 <https://tinyflux.readthedocs.io/en/latest/getting-started.html>__ 和文档中的 贡献工具和约定 <https://tinyflux.readthedocs.io/en/latest/contributing-tooling.html>__ 部分。
2. 查看GitHub上的 现有未解决问题 <https://github.com/citrusvanilla/tinyflux/issues>，提出新问题 <https://github.com/citrusvanilla/tinyflux/issues/new> 或 开始新的讨论 <https://github.com/citrusvanilla/tinyflux/discussions/new>__。
3. 要开始提交拉取请求，请在GitHub上fork仓库，创建新分支，并进行更新。
4. 编写单元测试，确保代码100%覆盖，必要时更新文档，并正确格式化和样式化代码。
5. 发送拉取请求。

.. |构建状态| image:: https://github.com/citrusvanilla/tinyflux/actions/workflows/build.yml/badge.svg :target: https://github.com/citrusvanilla/tinyflux/actions .. |覆盖率| image:: https://codecov.io/gh/citrusvanilla/tinyflux/branch/master/graph/badge.svg?token=IEGQ4E57VA :target: https://app.codecov.io/gh/citrusvanilla/tinyflux .. |版本| image:: http://img.shields.io/pypi/v/tinyflux.svg :target: https://pypi.python.org/pypi/tinyflux/ .. |下载量| image:: https://img.shields.io/pepy/dt/tinyflux :target: https://pypi.python.org/pypi/tinyflux/