fromscratch-pytsdb 0.4.0__tar.gz

fromscratch_pytsdb-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: robcox2910/robcox2910.github.io/.github/workflows/python-ci.yml@v1

fromscratch_pytsdb-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,16 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+jobs:
+  docs:
+    uses: robcox2910/robcox2910.github.io/.github/workflows/docs.yml@v1
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      coverage-report: false

fromscratch_pytsdb-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/fromscratch-pytsdb/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fromscratch_pytsdb-0.4.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.ruff_cache/
+_version.py
+.hypothesis/

fromscratch_pytsdb-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,56 @@
+default_language_version:
+  python: python3.14
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # Pages paste real pytest output, trailing spaces included.
+      - id: trailing-whitespace
+        exclude: ^docs/property-testing\.md$
+      - id: end-of-file-fixer
+        exclude: ^docs/property-testing\.md$
+      - id: check-yaml
+        args: ['--unsafe']
+      - id: check-added-large-files
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.4
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.408
+    hooks:
+      - id: pyright
+
+  - repo: local
+    hooks:
+      - id: pip-audit
+        name: pip-audit
+        language: system
+        pass_filenames: false
+        files: ^(pyproject\.toml|uv\.lock)$
+        entry: >-
+          bash -c 'f=$(mktemp) &&
+          uv export --frozen --no-emit-project --all-extras --no-hashes -o "$f" >/dev/null &&
+          uvx pip-audit==2.10.0 -r "$f" --disable-pip --no-deps;
+          status=$?; rm -f "$f"; exit $status'
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.7
+    hooks:
+      - id: actionlint
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.13.8
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+        additional_dependencies: [typing_extensions]

fromscratch_pytsdb-0.4.0/CLAUDE.md

@@ -0,0 +1,52 @@
+# Claude Code Instructions
+
+<!-- standard:start -->
+## Code Style
+
+- All public functions, methods, classes, and modules **must** have a docstring
+- Use imperative mood: "Return the result." not "Returns the result."
+- One-line docstrings for simple functions; multi-line with summary + details for complex ones
+- Follow the Google docstring convention (D211, D212 selected via ruff)
+
+## Linting
+
+- Ruff enforces a comprehensive rule set -- run `uv run ruff check .` before committing
+- Pyright runs in strict mode -- run `uv run pyright src tests` before committing
+- All violations must be fixed, not ignored. Exceptions are the repo-owned `ignore` and `per-file-ignores` lists in `pyproject.toml`, which belong to this repo; the series sync never edits them
+
+## Testing
+
+- TDD workflow: Red-Green-Refactor
+- Coverage is enforced by pytest-cov; the floor in `pyproject.toml` is repo-owned
+- Test classes and methods also require docstrings
+- Use named constants instead of magic values (PLR2004)
+- Run `uv run pytest` before committing
+- Property-based tests (Hypothesis) live in `tests/test_properties.py` and `tests/test_model.py`; the shared profiles are in the root `conftest.py` (owned by `series sync`). Run `uv run pytest --hypothesis-profile=thorough` before a release.
+
+## Commits
+
+- Use conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`
+- All changes go via PR from a feature branch (main is protected); merge when CI is green
+
+## Dependencies
+
+- Package manager: uv
+- Run `uv sync --all-extras` after modifying dependencies
+- `uv.lock` is committed; CI and pre-commit audit it with pip-audit through `uvx`, so pip-audit is not a project dependency
+- Sibling projects, where used, are pinned release tags in `[tool.uv.sources]` (git + tag); never use `path` sources
+
+## Releasing
+
+- A release is a `vX.Y.Z` tag on main after the PR is merged
+- Docs-only and tooling-only changes do not get a release tag
+- Docs are built with `mkdocs build --strict` and deployed to GitHub Pages by the docs workflow
+<!-- standard:end -->
+
+## Project notes
+
+- Pyright in strict mode -- run `uv run pyright src tests` before committing
+- All violations must be fixed, not ignored (except D203/D213 incompatible pair)
+- Minimum 90% coverage enforced by pytest-cov
+- Use conventional commits (enforced by commitizen): `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`
+- All changes go via PR from a feature branch (main is protected)
+- Add production deps to `[project.dependencies]`

fromscratch_pytsdb-0.4.0/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.

fromscratch_pytsdb-0.4.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,127 @@
+# 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/conftest.py

@@ -0,0 +1,21 @@
+"""Shared Hypothesis profiles for the series.
+
+Two profiles are registered, and ``ci`` is loaded by default:
+
+- ``ci`` runs 100 examples with no deadline, a fixed seed and no example
+  database, so the same code gives the same result on every machine and a
+  green build can be trusted.
+- ``thorough`` runs 2000 examples with a random seed, to hunt for the rare
+  counterexample before a release.
+
+Run the long one with ``uv run pytest --hypothesis-profile=thorough``.
+
+This file is owned by ``series sync``. Edit it in the series home repo
+(robcox2910.github.io), not here, or the next sync will put it back.
+"""
+
+from hypothesis import settings
+
+settings.register_profile("ci", max_examples=100, deadline=None, derandomize=True, database=None)
+settings.register_profile("thorough", max_examples=2000, deadline=None, derandomize=False)
+settings.load_profile("ci")

fromscratch_pytsdb-0.4.0/docs/concepts/aggregation.md

@@ -0,0 +1,42 @@
+# Aggregation -- Weekly Average Temperature
+
+## The Analogy
+
+You recorded the temperature every hour for a whole week. That's 168 readings! Your teacher asks: "What was the average temperature each day?"
+
+Instead of reading all 168 numbers, you:
+1. **Group** them by day (7 groups of 24 readings)
+2. **Summarise** each group (add them up and divide by 24)
+
+That's aggregation! You pick a **window** (one day) and a **function** (average) and let the computer crunch the numbers.
+
+## Available Functions
+
+| Function | What it does                  | Example                          |
+|----------|-------------------------------|----------------------------------|
+| AVG      | Average of all values         | "Average temperature this hour"  |
+| MIN      | Smallest value                | "Coldest reading today"          |
+| MAX      | Largest value                 | "Hottest reading today"          |
+| SUM      | Total of all values           | "Total rainfall this week"       |
+| COUNT    | Number of readings            | "How many readings per hour?"    |
+
+## In Code
+
+```python
+from datetime import timedelta
+from pytsdb import TimeSeriesDB, AggFunc
+
+db = TimeSeriesDB()
+db.create_series("temp")
+# ... add hourly readings ...
+
+# Get the average temperature per hour
+hourly_avg = db.aggregate("temp", window=timedelta(hours=1), func=AggFunc.AVG)
+
+# Get the max temperature per day
+daily_max = db.aggregate("temp", window=timedelta(days=1), func=AggFunc.MAX)
+```
+
+## How Time Buckets Work
+
+Every data point's timestamp is mapped to a **bucket**. For a 1-hour window, all points between 10:00 and 10:59 go into the "10:00" bucket. The function is then applied to each bucket independently.

fromscratch_pytsdb-0.4.0/docs/concepts/datapoints.md

@@ -0,0 +1,73 @@
+# Data Points -- Thermometer Readings
+
+## The Analogy
+
+Every time you check a thermometer and write down the number, you're creating a **data point**. A data point is the smallest unit of information in a time-series database.
+
+It has three parts:
+
+1. **Timestamp** -- *When* did you look at the thermometer? (e.g. "July 4, 2024 at 2:00 PM")
+2. **Value** -- *What* did it read? (e.g. 72.5°F)
+3. **Tags** -- *Extra labels* that help you find it later (e.g. sensor="kitchen", floor="1")
+
+## In Code
+
+```python
+from datetime import datetime, timezone
+from pytsdb import DataPoint
+
+reading = DataPoint(
+    timestamp=datetime(2024, 7, 4, 14, 0, tzinfo=timezone.utc),
+    value=72.5,
+    tags={"sensor": "kitchen", "floor": "1"},
+)
+
+print(reading.value)       # 72.5
+print(reading.tags)        # {'sensor': 'kitchen', 'floor': '1'}
+```
+
+## Why Are Tags Useful?
+
+Imagine you have 10 temperature sensors around your house. Without tags, you'd need 10 separate series. With tags, you can store everything in one series and filter:
+
+```python
+# "Show me only the kitchen readings"
+reading.matches_tags({"sensor": "kitchen"})  # True
+reading.matches_tags({"sensor": "garage"})   # False
+```
+
+## Fun Fact
+
+Data points in pytsdb are **frozen** (immutable) -- once created, you can't change them. This is like writing in pen instead of pencil. It keeps your data trustworthy!
+
+This even applies to the tags. When you create a data point, it takes its own private copy of the tags dictionary, so editing the dict you passed in later can't sneak in and change the point:
+
+```python
+labels = {"sensor": "kitchen"}
+reading = DataPoint(value=72.5, tags=labels)
+
+labels["sensor"] = "garage"   # edit the original dict
+print(reading.tags)           # {'sensor': 'kitchen'}  -- still in pen!
+```
+
+A series works the same way in the other direction. Every point it hands back -- from `query`, `first`, `last` or looping over it -- is a fresh copy, so scribbling on a returned point's tags can't change what the database has stored.
+
+## Watch Out: Timestamps Need a Timezone
+
+A data point's timestamp must be **timezone-aware** so pytsdb always knows *which* clock you mean. A bare `datetime(2024, 1, 1)` has no timezone, so pytsdb raises a friendly error instead of letting it cause confusing crashes later:
+
+```python
+from datetime import datetime, timezone
+
+DataPoint(timestamp=datetime(2024, 1, 1))                       # ValueError!
+DataPoint(timestamp=datetime(2024, 1, 1, tzinfo=timezone.utc))  # works
+```
+
+## Watch Out: NaN Isn't a Reading
+
+`float("nan")` means "not a number". It isn't bigger, smaller or equal to anything -- not even itself -- so a NaN reading would make "the highest reading" and "in time order" meaningless. pytsdb refuses it with a `ValueError`. So is anything that isn't a real number (a string, `None`, `True`). Infinity is fine.
+
+```python
+DataPoint(value=float("nan"))  # ValueError!
+DataPoint(value=float("inf"))  # works
+```