fromscratch-pytsdb 0.4.0__py3-none-any.whl

fromscratch_pytsdb-0.4.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: fromscratch-pytsdb
+Version: 0.4.0
+Summary: An educational time-series database library built from scratch in Python
+Project-URL: Homepage, https://github.com/robcox2910/pytsdb
+Project-URL: Repository, https://github.com/robcox2910/pytsdb
+Project-URL: Issues, https://github.com/robcox2910/pytsdb/issues
+Project-URL: Documentation, https://robcox2910.github.io/pytsdb/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: database,education,metrics,time-series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: commitizen>=4.4.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.170; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytsdb
+
+An educational time-series database built from scratch in Python. Part of the **PyLearn** platform for kids aged 12+.
+
+A time-series database stores data points that each have a **timestamp**, a **value**, and optional **tags** -- like a weather station logbook that records temperature readings throughout the day.
+
+## Features
+
+- **DataPoint** -- timestamped values with optional tags (e.g. sensor="kitchen")
+- **TimeSeries** -- ordered collection of data points for one metric
+- **TimeSeriesDB** -- container managing multiple named series with full CRUD
+- **Time Range Queries** -- efficient binary-search lookups between two timestamps
+- **Tag Filtering** -- filter data points by tag key-value pairs
+- **Aggregation** -- compute avg, min, max, sum, count over configurable time windows
+- **Downsampling** -- reduce resolution (e.g. minute data to hourly averages)
+- **Retention Policies** -- auto-delete data older than N days
+- **Persistence** -- save/load the entire database to JSON files
+- **Rate of Change** -- compute how fast a value is changing over time
+
+## Quick Start
+
+```python
+from datetime import datetime, timedelta, timezone
+from pytsdb import AggFunc, TimeSeriesDB
+
+# Create a database and a series
+db = TimeSeriesDB()
+db.create_series("temperature")
+
+# Add some readings
+db.add_point("temperature", value=68.0,
+             timestamp=datetime(2024, 7, 4, 8, 0, tzinfo=timezone.utc),
+             tags={"sensor": "kitchen"})
+db.add_point("temperature", value=72.5,
+             timestamp=datetime(2024, 7, 4, 10, 0, tzinfo=timezone.utc),
+             tags={"sensor": "kitchen"})
+db.add_point("temperature", value=75.0,
+             timestamp=datetime(2024, 7, 4, 12, 0, tzinfo=timezone.utc),
+             tags={"sensor": "bedroom"})
+
+# Query by time range and tags
+kitchen = db.query("temperature", tags={"sensor": "kitchen"})
+print(f"Kitchen readings: {len(kitchen)}")  # 2
+
+# Aggregate: hourly averages
+hourly = db.aggregate("temperature", window=timedelta(hours=1), func=AggFunc.AVG)
+
+# Downsample to 2-hour buckets
+coarse = db.downsample("temperature", target_interval=timedelta(hours=2))
+
+# Auto-expire old data
+db.set_retention("temperature", max_age=timedelta(days=30))
+db.apply_retention()
+
+# Save to disk
+from pytsdb import save, load
+save(db, "my_data.json")
+db2 = load("my_data.json")
+```
+
+## Concepts
+
+See the [docs/](docs/) folder for kid-friendly explanations with real-world analogies:
+
+- [What is a Time-Series DB?](docs/index.md) -- weather station logbook analogy
+- [Data Points](docs/concepts/datapoints.md) -- thermometer readings
+- [Time Series](docs/concepts/series.md) -- a week of readings
+- [Queries](docs/concepts/queries.md) -- checking yesterday's weather
+- [Aggregation](docs/concepts/aggregation.md) -- weekly average temperature
+- [Downsampling](docs/concepts/downsampling.md) -- monthly summaries
+- [Retention](docs/concepts/retention.md) -- throwing away old newspapers
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pytsdb/
+<!-- docs:end -->
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+uv run pyright src tests
+uv run pytest
+```
+
+## Releasing
+
+Other projects in the series ([PyStack](https://github.com/robcox2910/pystack)) use a pinned release of this one,
+not whatever is on `main`. To publish a change for them:
+
+1. Merge the change to `main`.
+2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+   A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
+   anything else bumps the patch (`v0.1.0` → `v0.1.1`).
+3. In each project that uses it, edit the tag in `[tool.uv.sources]`, run
+   `uv lock --upgrade-package <name>`, and open a pull request so CI checks
+   the pair together.
+
+<!-- series:start -->
+## Related Projects
+
+This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
+
+| Project | What it teaches | Repository | Docs |
+| --- | --- | --- | --- |
+| PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
+| Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
+| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
+| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
+| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
+| PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
+| **PyTSDB** | **Time-series databases** | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
+| PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
+| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
+| PyCrypt | Cryptography | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
+| PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
+| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
+| PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
+| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
+| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
+| PyLLM | Language models (the brain) | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
+| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
+| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
+<!-- series:end -->

fromscratch_pytsdb-0.4.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+pytsdb/__init__.py,sha256=iYrRS4Y8YvmyHUIx77XP2KvYbHG8KLPEt-OMt6aVExg,2035
+pytsdb/_version.py,sha256=HGBlVvZpQ8N2kh1n_LY5PM4s9ljcIgdbOCgXN-uFje4,520
+pytsdb/aggregation.py,sha256=b1I8_tmJKQL3uUahlnRF0aEu8p758NexhXPcCVvrLdM,4432
+pytsdb/atomic.py,sha256=QLLPGZqpA-TgVV5lDEKCLB7vVr05bxj97_Fwykz_gi4,2345
+pytsdb/database.py,sha256=AqbVEPj4TBkNQSsGzKtfsnwtzZrJUBXYN1tSI76p9e8,11868
+pytsdb/datapoint.py,sha256=6XprVlSwZdVreeqbaoakUXbQifWbYM28JgNY4IPVQ5k,5254
+pytsdb/downsampling.py,sha256=PkWmXCZDyWfirfOWJnKjRZpccVJe-3MaSjhZf7XzDzA,1614
+pytsdb/errors.py,sha256=AQI2DMqCJxUYmmFlYXDe45jvVGsl0JPt27tAykOf-Hs,1726
+pytsdb/persistence.py,sha256=IpIyCw98xyWnFkTN0afIBNn49InCWxltd16jwle7eSM,3031
+pytsdb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytsdb/query.py,sha256=wY8tZZSoFXR46CaGIUBrkIhuN0J4b3uL9cYBO03kuEk,2590
+pytsdb/retention.py,sha256=JFObJg5xgu-YQoOZcRZImGchZx3S6Sj6ofpCqKLv-dI,3181
+pytsdb/series.py,sha256=f5gFbOao-7KWflQQ7LVknzZrPwPKSrxWN8HED5MZaTg,6231
+fromscratch_pytsdb-0.4.0.dist-info/METADATA,sha256=xW1m8v1s6lxHuM4ZGiG0A_YGXLIxITTm7sxopaR4r0M,7821
+fromscratch_pytsdb-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pytsdb-0.4.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pytsdb-0.4.0.dist-info/RECORD,,

fromscratch_pytsdb-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fromscratch_pytsdb-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Cox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytsdb/__init__.py

@@ -0,0 +1,69 @@
+"""pytsdb -- an educational time-series database.
+
+A time-series database stores data points that each have a **timestamp**,
+a **value**, and optional **tags**.  Think of it like a weather station's
+logbook: every few minutes you jot down the temperature, humidity, and
+wind speed along with the current time.
+
+Quick start::
+
+    from pytsdb import TimeSeriesDB
+
+    db = TimeSeriesDB()
+    db.create_series("temperature")
+    db.add_point("temperature", value=72.5, tags={"sensor": "kitchen"})
+
+    points = db.query("temperature")
+    print(points)
+
+Modules:
+    datapoint    -- A single timestamped reading.
+    series       -- An ordered collection of readings for one metric.
+    database     -- A container that manages multiple series.
+    query        -- Time-range and tag-based lookups.
+    aggregation  -- Windowed summaries (avg, min, max, sum, count).
+    downsampling -- Resolution reduction (e.g. minutes to hours).
+    retention    -- Auto-expiry of old data.
+    persistence  -- Save / load the database to JSON files.
+    errors       -- Custom exception classes.
+"""
+
+from pytsdb.aggregation import AggFunc, aggregate
+from pytsdb.database import TimeSeriesDB
+from pytsdb.datapoint import DataPoint
+from pytsdb.downsampling import downsample
+from pytsdb.errors import (
+    DuplicateSeriesError,
+    EmptySeriesError,
+    InvalidRetentionError,
+    InvalidWindowError,
+    PersistenceError,
+    PyTSDBError,
+    SeriesNotFoundError,
+)
+from pytsdb.persistence import load, save
+from pytsdb.query import filter_by_tags, query, query_range
+from pytsdb.retention import RetentionPolicy
+from pytsdb.series import TimeSeries
+
+__all__ = [
+    "AggFunc",
+    "DataPoint",
+    "DuplicateSeriesError",
+    "EmptySeriesError",
+    "InvalidRetentionError",
+    "InvalidWindowError",
+    "PersistenceError",
+    "PyTSDBError",
+    "RetentionPolicy",
+    "SeriesNotFoundError",
+    "TimeSeries",
+    "TimeSeriesDB",
+    "aggregate",
+    "downsample",
+    "filter_by_tags",
+    "load",
+    "query",
+    "query_range",
+    "save",
+]

pytsdb/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
+
+__commit_id__ = commit_id = None

pytsdb/aggregation.py

@@ -0,0 +1,140 @@
+"""Windowed aggregation functions.
+
+Suppose you recorded the temperature every minute for a whole day.
+That's 1,440 readings!  Aggregation lets you *summarise* them:
+
+  - "What was the **average** temperature each hour?"
+  - "What was the **highest** reading today?"
+
+You pick a *window* (like one hour) and a *function* (like average),
+and the aggregator crunches the numbers for you.
+"""
+
+from collections import defaultdict
+from datetime import UTC, datetime, timedelta
+from enum import Enum
+
+from pytsdb.datapoint import DataPoint
+from pytsdb.errors import EmptySeriesError, InvalidWindowError
+
+
+class AggFunc(Enum):
+    """Supported aggregation functions.
+
+    Each value names a way to summarise a group of numbers.
+    """
+
+    AVG = "avg"
+    MIN = "min"
+    MAX = "max"
+    SUM = "sum"
+    COUNT = "count"
+
+
+def _bucket_key(timestamp: datetime, window: timedelta) -> datetime:
+    """Return the start of the time bucket that *timestamp* falls into.
+
+    Args:
+        timestamp: The point in time to bucket.
+        window: The size of each bucket.
+
+    Returns:
+        A UTC datetime representing the start of the bucket.
+
+    Raises:
+        InvalidWindowError: If the bucket would start before year 1.
+
+    """
+    epoch = datetime(1970, 1, 1, tzinfo=UTC)
+    # Count whole windows with timedelta arithmetic, which is exact to the
+    # microsecond. Going through float seconds rounded, and could label a
+    # bucket a hair *after* its first reading -- or put a reading that sits
+    # exactly on a boundary into the bucket before it.
+    windows_since_epoch = (timestamp - epoch) // window
+    try:
+        return epoch + windows_since_epoch * window
+    except OverflowError:
+        # Buckets line up with 1970-01-01, so a reading in the first window
+        # of the calendar can need a bucket starting before 0001-01-01, the
+        # earliest moment a datetime can hold.
+        msg = (
+            f"A {window} window puts the bucket for {timestamp.isoformat()} "
+            "before year 1, which a datetime can't hold -- use a smaller window"
+        )
+        raise InvalidWindowError(msg) from None
+
+
+def aggregate(
+    points: list[DataPoint],
+    window: timedelta,
+    func: AggFunc = AggFunc.AVG,
+) -> list[DataPoint]:
+    """Group points into time windows and compute a summary value.
+
+    Think of it like sorting your marbles into jars by colour
+    and then counting how many are in each jar.
+
+    Buckets line up with midnight on 1 January 1970, counting whole
+    windows forwards or backwards from there.
+
+    Args:
+        points: Sorted data points to aggregate.
+        window: The size of each time bucket (e.g. ``timedelta(hours=1)``).
+        func: Which summary to compute (avg, min, max, sum, count).
+
+    Returns:
+        One :class:`~pytsdb.datapoint.DataPoint` per bucket, timestamped
+        at the bucket start, with the aggregated value.
+
+    Raises:
+        EmptySeriesError: If *points* is empty.
+        InvalidWindowError: If *window* is zero or negative, or if a
+            point's bucket would start before year 1 (only possible for a
+            point less than one window after 0001-01-01 00:00).
+
+    """
+    if not points:
+        msg = "Cannot aggregate an empty list of points"
+        raise EmptySeriesError(msg)
+
+    if window.total_seconds() <= 0:
+        msg = "Window must be a positive duration"
+        raise InvalidWindowError(msg)
+
+    # Group points by bucket
+    buckets: dict[datetime, list[float]] = defaultdict(list)
+    for point in points:
+        key = _bucket_key(point.timestamp, window)
+        buckets[key].append(point.value)
+
+    # Compute aggregate per bucket
+    result: list[DataPoint] = []
+    for bucket_ts in sorted(buckets):
+        values = buckets[bucket_ts]
+        agg_value = _compute(values, func)
+        result.append(DataPoint(timestamp=bucket_ts, value=agg_value))
+
+    return result
+
+
+def _compute(values: list[float], func: AggFunc) -> float:
+    """Apply an aggregation function to a list of numbers.
+
+    Args:
+        values: Non-empty list of floats.
+        func: Which aggregation to apply.
+
+    Returns:
+        The aggregated result.
+
+    """
+    if func is AggFunc.AVG:
+        return sum(values) / len(values)
+    if func is AggFunc.MIN:
+        return min(values)
+    if func is AggFunc.MAX:
+        return max(values)
+    if func is AggFunc.SUM:
+        return sum(values)
+    # COUNT
+    return float(len(values))

pytsdb/atomic.py

@@ -0,0 +1,66 @@
+"""Safe saving -- never leave a half-written file behind.
+
+The usual way to save a file is: open it, wipe it, write the new
+contents. If the computer crashes after the wipe but before the writing
+finishes, your data is gone -- the old version was wiped and the new one
+never arrived.
+
+So we save like a careful student copying out their homework:
+
+1. Write the new version on a **fresh sheet** (a temporary file sitting
+   right next to the real one).
+2. Make sure the **ink is dry** -- ``fsync`` forces the bytes out of the
+   computer's memory and onto the disk.
+3. **Swap** the fresh sheet in for the old one in a single instant step
+   (``Path.replace``). There is never a moment with no complete file: you
+   see either the old version or the new one, never half of each.
+
+Real databases (SQLite, PostgreSQL, Redis) all use this same trick.
+"""
+
+import contextlib
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+# Permissions for a brand-new file: owner can read/write, others can read.
+_NEW_FILE_MODE = 0o644
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Replace the file at *path* with *text*, so a crash can never leave it half-written.
+
+    Args:
+        path: The file to create or replace (its folder must already exist).
+        text: The new contents, saved as UTF-8.
+
+    """
+    mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else _NEW_FILE_MODE
+    fd, temp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    temp_path = Path(temp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as temp_file:
+            temp_file.write(text)
+            temp_file.flush()
+            os.fsync(temp_file.fileno())
+        temp_path.chmod(mode)
+        temp_path.replace(path)
+    except BaseException:
+        temp_path.unlink(missing_ok=True)  # don't leave the scrap sheet lying around
+        raise
+    _sync_folder(path.parent)
+
+
+def _sync_folder(folder: Path) -> None:
+    """Make the swap itself durable by syncing the folder's list of files.
+
+    Some systems (like Windows) can't sync a folder; there the swap is
+    still safe, just not guaranteed to survive a power cut.
+    """
+    with contextlib.suppress(OSError):
+        fd = os.open(folder, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)