calendardb 0.1.0__tar.gz

calendardb-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Test
+on:
+  push:
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python: ['3.10', '3.14']
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e '.[dev,otel]'
+      - run: ruff check .
+      - run: python -m pytest -q
+      - run: python examples/seed_database.py --dry-run
+      - run: python -m build

calendardb-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.env*
+*.local.*
+credentials*.json
+client_secret*.json
+token*.json
+docs/plans/

calendardb-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 CalendarDB contributors
+Copyright (c) 2026 GranolaDB contributors
+
+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.

calendardb-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: calendardb
+Version: 0.1.0
+Summary: Store your logs and agent traces in Google Calendar. Your database has a day view.
+Project-URL: Homepage, https://github.com/that-guy-wade/calendardb
+Project-URL: Repository, https://github.com/that-guy-wade/calendardb
+Author: CalendarDB
+License: MIT
+License-File: LICENSE
+Keywords: calendar,database,logging,observability,satire
+Requires-Python: >=3.10
+Requires-Dist: google-auth-oauthlib>=1
+Requires-Dist: google-auth>=2
+Requires-Dist: keyring>=24
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: radon>=6; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# CalendarDB
+
+CalendarDB is a tiny time-series store with a day view. It writes each record as a private, transparent one-second event in a dedicated Google Calendar, then reads the event description back as JSON. Your latency graph is now something you can scroll past on the way to lunch.
+
+## Install
+
+```sh
+pip install 'calendardb[otel]'
+```
+
+## Run the synthetic demo from a source checkout
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+pip install -e '.[otel]'
+python examples/seed_database.py --dry-run
+```
+
+The dry run uses the same `Client` and seed path as live mode, backed by an in-memory fake. It writes 12 synthetic API measurements for the current UTC day and verifies the complete readback. No Google account or network access is used.
+
+For live storage, create an OAuth desktop client in Google Cloud, enable the Google Calendar API, download the desktop OAuth JSON outside this repository, and authorize CalendarDB:
+
+```sh
+calendardb login --client-secrets /path/outside/repository/client_secret.json
+python examples/seed_database.py
+```
+
+The OAuth flow requests `calendar.app.created` and `calendar.calendarlist.readonly`. CalendarDB creates a separate `CalendarDB Demo` calendar and does not use your primary calendar. Keep the OAuth JSON out of source control; the refresh token is saved in your operating system keychain. `calendardb logout` removes that saved authorization.
+
+## Use it
+
+```python
+from datetime import datetime, timedelta, timezone
+
+from calendardb import Client
+
+db = Client(calendar="CalendarDB Demo")
+now = datetime.now(timezone.utc)
+db.put({"service": "api", "series": "latency_ms", "value": 95, "_ts": now})
+rows = db.query(after=now, before=now + timedelta(seconds=1), series="latency_ms")
+print(rows[0]["value"])
+```
+
+`put` adds an aware UTC `_ts` timestamp and UUID `_id` when they are missing. `query` returns records in timestamp order; `after` includes its timestamp and `before` excludes its timestamp. `contains` searches serialized record text with a case-sensitive local match. `calendar_query` passes a text search to Google Calendar, and `series` matches the `series` field exactly. Buffered writes flush at 50 records or after five seconds by default, with one Calendar event per record. IDs are immutable: retrying the same ID and payload is safe; writing different data under an existing ID fails. `get(id)` reads a record and `delete(id)` removes only a verified CalendarDB event.
+
+For standard Python logging, use `CalendarHandler` from `calendardb.logging_handler`. For OpenTelemetry, install the `otel` extra and configure `CalendarSpanExporter` from `calendardb.otel` as a span exporter. These are ordinary records under the same timestamp and event model; the Calendar UI does not become an observability dashboard by wishing very hard.
+
+## What the calendar means
+
+The event start time is the record timestamp. Each event description contains the record, and each summary is a short readable preview. The `series` field is just a record dimension. Calendar labels are not used, and CalendarDB does not create a database index: the event start time is the timestamp index, the event rows are the records, and the dedicated calendar is the collection.
+
+Google's published account storage allowance lists Gmail, Drive, and Photos; Calendar is not listed there. The careful reading is that event text is outside that listed allowance, not that CalendarDB has unlimited storage. Attachments stored in Drive still count toward Drive storage. Calendar API quotas, general usage limits, and operational limits still apply. Google's current published API quotas for projects created on or after May 1, 2026 are 10,000 requests per minute per project and 600 per minute per user per project; the page describes a 1,000,000-request daily threshold before charges and says further billing details are planned for later in 2026. Google also applies undisclosed single-calendar write limits. Its [paid Workspace guidance](https://knowledge.workspace.google.com/admin/calendar/avoid-calendar-use-limits) warns about creating over 100,000 events or more than 60 calendars in a short period; stricter account limits are not fully public. These are activity limits, not a published total storage capacity.
+
+CalendarDB is a satire/demo project. Google Calendar is a calendar, and event-based storage inherits calendar-shaped limits and ergonomics. A day view is not a query planner.
+
+## Project
+
+Adapted from [GranolaDB](https://github.com/that-guy-wade/granoladb), with Google Calendar events as the storage backend.
+
+See [the demo walkthrough](docs/demo.md) and [launch copy](launch-thread.md). The demo values are synthetic and marked `calendardb-demo-v1`; they are not captured from a real service.
+
+References: [Calendar API quotas and usage limits](https://developers.google.com/workspace/calendar/api/guides/quota), [Google storage policy](https://support.google.com/googleone/answer/6374270), [Gemini Apps and Google Calendar](https://support.google.com/gemini/answer/15305236).

calendardb-0.1.0/README.md

@@ -0,0 +1,63 @@
+# CalendarDB
+
+CalendarDB is a tiny time-series store with a day view. It writes each record as a private, transparent one-second event in a dedicated Google Calendar, then reads the event description back as JSON. Your latency graph is now something you can scroll past on the way to lunch.
+
+## Install
+
+```sh
+pip install 'calendardb[otel]'
+```
+
+## Run the synthetic demo from a source checkout
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+pip install -e '.[otel]'
+python examples/seed_database.py --dry-run
+```
+
+The dry run uses the same `Client` and seed path as live mode, backed by an in-memory fake. It writes 12 synthetic API measurements for the current UTC day and verifies the complete readback. No Google account or network access is used.
+
+For live storage, create an OAuth desktop client in Google Cloud, enable the Google Calendar API, download the desktop OAuth JSON outside this repository, and authorize CalendarDB:
+
+```sh
+calendardb login --client-secrets /path/outside/repository/client_secret.json
+python examples/seed_database.py
+```
+
+The OAuth flow requests `calendar.app.created` and `calendar.calendarlist.readonly`. CalendarDB creates a separate `CalendarDB Demo` calendar and does not use your primary calendar. Keep the OAuth JSON out of source control; the refresh token is saved in your operating system keychain. `calendardb logout` removes that saved authorization.
+
+## Use it
+
+```python
+from datetime import datetime, timedelta, timezone
+
+from calendardb import Client
+
+db = Client(calendar="CalendarDB Demo")
+now = datetime.now(timezone.utc)
+db.put({"service": "api", "series": "latency_ms", "value": 95, "_ts": now})
+rows = db.query(after=now, before=now + timedelta(seconds=1), series="latency_ms")
+print(rows[0]["value"])
+```
+
+`put` adds an aware UTC `_ts` timestamp and UUID `_id` when they are missing. `query` returns records in timestamp order; `after` includes its timestamp and `before` excludes its timestamp. `contains` searches serialized record text with a case-sensitive local match. `calendar_query` passes a text search to Google Calendar, and `series` matches the `series` field exactly. Buffered writes flush at 50 records or after five seconds by default, with one Calendar event per record. IDs are immutable: retrying the same ID and payload is safe; writing different data under an existing ID fails. `get(id)` reads a record and `delete(id)` removes only a verified CalendarDB event.
+
+For standard Python logging, use `CalendarHandler` from `calendardb.logging_handler`. For OpenTelemetry, install the `otel` extra and configure `CalendarSpanExporter` from `calendardb.otel` as a span exporter. These are ordinary records under the same timestamp and event model; the Calendar UI does not become an observability dashboard by wishing very hard.
+
+## What the calendar means
+
+The event start time is the record timestamp. Each event description contains the record, and each summary is a short readable preview. The `series` field is just a record dimension. Calendar labels are not used, and CalendarDB does not create a database index: the event start time is the timestamp index, the event rows are the records, and the dedicated calendar is the collection.
+
+Google's published account storage allowance lists Gmail, Drive, and Photos; Calendar is not listed there. The careful reading is that event text is outside that listed allowance, not that CalendarDB has unlimited storage. Attachments stored in Drive still count toward Drive storage. Calendar API quotas, general usage limits, and operational limits still apply. Google's current published API quotas for projects created on or after May 1, 2026 are 10,000 requests per minute per project and 600 per minute per user per project; the page describes a 1,000,000-request daily threshold before charges and says further billing details are planned for later in 2026. Google also applies undisclosed single-calendar write limits. Its [paid Workspace guidance](https://knowledge.workspace.google.com/admin/calendar/avoid-calendar-use-limits) warns about creating over 100,000 events or more than 60 calendars in a short period; stricter account limits are not fully public. These are activity limits, not a published total storage capacity.
+
+CalendarDB is a satire/demo project. Google Calendar is a calendar, and event-based storage inherits calendar-shaped limits and ergonomics. A day view is not a query planner.
+
+## Project
+
+Adapted from [GranolaDB](https://github.com/that-guy-wade/granoladb), with Google Calendar events as the storage backend.
+
+See [the demo walkthrough](docs/demo.md) and [launch copy](launch-thread.md). The demo values are synthetic and marked `calendardb-demo-v1`; they are not captured from a real service.
+
+References: [Calendar API quotas and usage limits](https://developers.google.com/workspace/calendar/api/guides/quota), [Google storage policy](https://support.google.com/googleone/answer/6374270), [Gemini Apps and Google Calendar](https://support.google.com/gemini/answer/15305236).

calendardb-0.1.0/docs/demo.md

@@ -0,0 +1,62 @@
+# CalendarDB demo: the incident has a day view
+
+This demo writes twelve clearly marked, synthetic API measurements to a dedicated Google Calendar. Six `latency_ms` events and six `errors` events share the same timestamps at ten-minute intervals from 09:00 through 09:50 UTC. The latency values are `90, 95, 110, 480, 120, 100`; the error values are `0, 0, 1, 12, 1, 0`. Every record carries `_demo: calendardb-demo-v1`, `service: api`, a `series` name, and a deterministic `_id` derived from the UTC date, series, and time.
+
+Run the local version first:
+
+```sh
+pip install -e '.[otel]'
+python examples/seed_database.py --dry-run
+```
+
+Dry-run follows the same seed and query path as live mode, using an in-memory `FakeBackend`. It checks that the backend contains exactly the 12 expected rows for today's demo, that every record matches the expected payload, and that unrelated pre-existing records survive. Re-running the seed uses the same IDs and accepts an existing event only when its complete payload matches. A conflicting payload stops the seed rather than overwriting existing calendar data.
+
+For a live Calendar run, create a Google Cloud project and enable **Google Calendar API** from **APIs & Services → Library**. Open **Google Auth Platform → Audience**, choose **External** for a personal test account, and keep the app in **Testing**. Add the Google account you will use under **Test users**. In **Data Access**, add these scopes:
+
+- `https://www.googleapis.com/auth/calendar.app.created`
+- `https://www.googleapis.com/auth/calendar.calendarlist.readonly`
+
+Save the consent-screen changes. Open **Clients → Create client**, choose **Desktop app**, create the OAuth client, and download its JSON to a location outside the repository. This test project is limited to its listed test users; Google's current help says Testing projects allow up to 100 listed users and test-user authorizations expire after seven days. Then:
+
+```sh
+calendardb login --client-secrets /path/to/client_secret.json
+python examples/seed_database.py
+```
+
+The consent flow requests `https://www.googleapis.com/auth/calendar.app.created` and `https://www.googleapis.com/auth/calendar.calendarlist.readonly`. These let CalendarDB create and manage the app-created demo calendar and find it again. The tool writes only to `CalendarDB Demo`, a secondary calendar. The refresh token goes into the OS keychain; `CALENDARDB_TOKEN` can supply a short-lived token for controlled automation. To remove keychain authorization, run `calendardb logout`.
+
+Google's [OAuth setup guide](https://support.google.com/cloud/answer/13461325) documents External testing, adding test users, and creating credentials. Google's [OAuth audience guide](https://support.google.com/cloud/answer/15549945) documents the Testing user limit and seven-day test-user authorization lifetime. Console navigation labels can change; use the linked instructions if the labels differ.
+
+## Record a 60-second demo
+
+Use a Google account already added as a test user. Record the terminal and Calendar browser window; do not show OAuth client JSON or keychain contents. The demo writes only synthetic records to `CalendarDB Demo`.
+
+| Time | Screen and action | Narration |
+| --- | --- | --- |
+| 0–6s | Terminal: run `python examples/seed_database.py --dry-run`. Keep the verification line visible. | “CalendarDB stores time-series records as calendar events. This dry run uses synthetic data and verifies the query.” |
+| 6–14s | Show the current code/example with `_demo`, `service`, `series`, `_ts`, and `value` fields. | “Each event carries a timestamp, a series name, and a value. These measurements are invented for the demo.” |
+| 14–24s | Switch to Google Calendar Schedule view. Select `CalendarDB Demo`, navigate to the current UTC date, and show all twelve entries from 09:00 through 09:50 UTC. | “There are twelve one-second events: six latency samples and six error counts. The event start is the timestamp index.” |
+| 24–34s | Point to the 09:30 events. Open one latency event to show its JSON description, then show the 09:30 error event. | “At 09:30 the synthetic latency is 480 milliseconds, alongside 12 errors. This is a crafted example, not a real incident.” |
+| 34–44s | Terminal: run the live readback snippet or show the script output for the `[09:20, 09:40)` range. Keep its four matching synthetic records visible. | “The range query includes 09:20 and excludes 09:40. It returns four measurements.” |
+| 44–52s | Return to Schedule view. Zoom out enough to show the complete timeline. | “The collection is a dedicated calendar. Rows are events. Calendar labels and database indexes are not involved.” |
+| 52–60s | Show the dry-run success and this README's quota note. | “CalendarDB is satire: the day view is real, while Calendar quotas and usage limits still apply.” |
+
+Optional Gemini shot: only record it after confirming the app is connected and an authorized test account can read `CalendarDB Demo`. Ask `@Google Calendar` to show events around 09:30. Do not narrate series grouping, peak calculation, or cross-event analytics as demonstrated; those behaviors are unverified. If authorization is missing, leave this shot out and keep the demo pending rather than depicting a successful result.
+
+## Verify the timeline
+
+Open Google Calendar's **Schedule** view, select `CalendarDB Demo`, and inspect the twelve one-second events from 09:00 to 09:50 UTC. The event rows are the records; their start times are the timestamp index. There are no labels or separate database indexes. The calendar itself is the collection, and `series` is a field in each record.
+
+The script verifies the range `09:20 <= _ts < 09:40` returns four records: latency 110 and 480, and errors 1 and 12. The highest latency is 480 ms at 09:30; the matching 09:30 error count is 12. CalendarDB is not claiming that a real incident happened. These are fabricated measurements designed to make the query visible in Calendar.
+
+Optional: if Google Calendar is connected in Gemini Apps, try asking `@Google Calendar` to show the events in the `CalendarDB Demo` calendar around 09:30 UTC. Google's Gemini help documents finding events and requesting counts for date ranges. It does not establish that this setup will reliably group these records by `series`, compare values across events, or calculate the peak; those analytics remain unverified. Check the returned Calendar events before relying on a response.
+
+## Operational notes
+
+CalendarDB buffers writes and creates one Calendar event for each record when it flushes. The default is 50 records or five seconds. Small batches are useful for a demo, while every event still consumes a Calendar API request. Google's quota page currently lists, for projects created on or after May 1, 2026, 10,000 API requests per minute per project and 600 per minute per user per project. It also lists a 1,000,000-request daily threshold before charges and says fuller billing details are planned for later in 2026. Existing projects may retain older quotas, and general Calendar usage and operational limits also apply. Do not read this as a no-quota or unlimited-storage promise.
+
+Google's listed shared storage allowance covers Gmail, Drive, and Photos, not Calendar. Event text is outside that listed Gmail/Drive/Photos storage allowance. This is a narrow statement about the published list, not a claim that Calendar accepts unlimited data. If an event references an attachment stored in Drive, that attachment counts toward Drive storage.
+
+The project includes a standard-library logging handler and an optional OpenTelemetry span exporter (`pip install -e '.[otel]'`). Both use the same record writer, so event volume and Calendar API limits apply to telemetry too.
+
+References: [Calendar API quotas and usage limits](https://developers.google.com/workspace/calendar/api/guides/quota), [Google storage policy](https://support.google.com/googleone/answer/6374270), [Gemini Apps: create and manage Calendar events](https://support.google.com/gemini/answer/15305236).

calendardb-0.1.0/examples/seed_database.py

@@ -0,0 +1,142 @@
+"""Seed and verify twelve synthetic CalendarDB API measurements."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import date, datetime, time, timezone
+import hashlib
+
+from calendardb import Client, FakeBackend
+
+DEMO_MARKER = "calendardb-demo-v1"
+CALENDAR = "CalendarDB Demo"
+TIMES = tuple(time(9, minute, tzinfo=timezone.utc) for minute in range(0, 60, 10))
+SERIES = {"latency_ms": (90, 95, 110, 480, 120, 100), "errors": (0, 0, 1, 12, 1, 0)}
+
+
+def records_for_demo(day: date | str | None = None) -> list[dict]:
+    if day is None:
+        day = datetime.now(timezone.utc).date()
+    if isinstance(day, str):
+        day = date.fromisoformat(day)
+    records = []
+    for series, values in SERIES.items():
+        for at, value in zip(TIMES, values, strict=True):
+            timestamp = datetime.combine(day, at)
+            stamp = timestamp.isoformat().replace("+00:00", "Z")
+            record_id = hashlib.sha256(f"{day.isoformat()}:{series}:{stamp}".encode()).hexdigest()
+            records.append(
+                {
+                    "_id": record_id,
+                    "_ts": stamp,
+                    "_demo": DEMO_MARKER,
+                    "service": "api",
+                    "series": series,
+                    "value": value,
+                }
+            )
+    return sorted(records, key=lambda record: (record["_ts"], record["series"]))
+
+
+def seed(client: Client, day: date | str | None = None) -> dict:
+    expected = records_for_demo(day)
+    previous = {record["_id"]: record for record in client.query()}
+    for record in expected:
+        existing = previous.get(record["_id"])
+        if existing is not None and existing != record:
+            raise RuntimeError(f"Existing record conflicts with demo ID {record['_id']}.")
+        if existing is None:
+            client.put(record)
+    client.flush()
+    actual = client.query()
+    return verify(client, expected, actual, previous)
+
+
+def _record_order(record: dict) -> tuple:
+    return record["_ts"], record["series"]
+
+
+def _verify_demo_rows(expected: list[dict], actual: list[dict]) -> list[dict]:
+    day_key = expected[0]["_ts"][:10]
+    demo_today = sorted(
+        (
+            row
+            for row in actual
+            if row.get("_demo") == DEMO_MARKER and row["_ts"].startswith(day_key)
+        ),
+        key=_record_order,
+    )
+    if demo_today != expected:
+        raise RuntimeError("Seed readback mismatch: expected exactly twelve matching demo records.")
+    return demo_today
+
+
+def _verify_window(client: Client, expected: list[dict], day_key: str) -> list[dict]:
+    start = f"{day_key}T09:20:00Z"
+    end = f"{day_key}T09:40:00Z"
+    window = client.query(after=start, before=end)
+    demo_window = sorted(
+        (row for row in window if row.get("_demo") == DEMO_MARKER), key=_record_order
+    )
+    expected_window = [row for row in expected if start <= row["_ts"] < end]
+    if demo_window != expected_window:
+        raise RuntimeError(
+            "Seed readback mismatch: expected four records in the 09:20–09:40 range."
+        )
+    return demo_window
+
+
+def _verify_peak(demo_today: list[dict], day_key: str) -> dict:
+    latency_peak = max(
+        (row for row in demo_today if row["series"] == "latency_ms"), key=lambda row: row["value"]
+    )
+    paired_errors = next(
+        row for row in demo_today if row["series"] == "errors" and row["_ts"] == latency_peak["_ts"]
+    )
+    if (
+        latency_peak["value"] != 480
+        or latency_peak["_ts"] != f"{day_key}T09:30:00Z"
+        or paired_errors["value"] != 12
+    ):
+        raise RuntimeError(
+            "Seed readback mismatch: expected the 480 ms peak and 12 errors at 09:30."
+        )
+    return latency_peak
+
+
+def verify(client: Client, expected: list[dict], actual: list[dict], previous: dict) -> dict:
+    day_key = expected[0]["_ts"][:10]
+    demo_today = _verify_demo_rows(expected, actual)
+    current = {row["_id"]: row for row in actual}
+    if any(current.get(record_id) != record for record_id, record in previous.items()):
+        raise RuntimeError("Seed readback mismatch: pre-existing records were not preserved.")
+    window = _verify_window(client, expected, day_key)
+    latency_peak = _verify_peak(demo_today, day_key)
+    return {
+        "records": expected,
+        "all_records": actual,
+        "window": window,
+        "latency_peak": latency_peak,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--dry-run", action="store_true", help="seed and verify with an offline FakeBackend"
+    )
+    args = parser.parse_args(argv)
+    backend = FakeBackend() if args.dry_run else None
+    client = Client(backend=backend, calendar=CALENDAR)
+    result = seed(client)
+    mode = "offline FakeBackend" if args.dry_run else CALENDAR
+    print(
+        f"verified 12 synthetic records in {mode}; "
+        f"range=4 peak={result['latency_peak']['value']}ms at {result['latency_peak']['_ts']} "
+        f"errors=12"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

calendardb-0.1.0/launch-thread.md

@@ -0,0 +1,9 @@
+1/5 CalendarDB: a time-series database with a day view. It stores each record as a private, transparent one-second Google Calendar event. Your query planner is a calendar.
+
+2/5 The timestamp is the event start; the record is in the description. The calendar is the collection, event rows are records, and `series` is a field. No labels or database index required. (Because, technically, a calendar already has time.)
+
+3/5 The synthetic demo seeds 12 API measurements. At 09:30, latency reaches 480 ms and errors hit 12. Query `[09:20, 09:40)` returns four rows. Then open Schedule view to admire the timestamp index.
+
+4/5 Try it offline: `pip install -e '.[otel]'` then `python examples/seed_database.py --dry-run`. Live mode uses a dedicated app-created calendar after Google OAuth. The seed is deterministic and safe to rerun.
+
+5/5 CalendarDB is satire, not unlimited storage or quota-free analytics. Calendar API limits still apply. Gemini can find Calendar events; grouping this demo by series or calculating its peak is unverified.

calendardb-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "calendardb"
+version = "0.1.0"
+description = "Store your logs and agent traces in Google Calendar. Your database has a day view."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "CalendarDB" }]
+keywords = ["observability", "logging", "database", "calendar", "satire"]
+dependencies = ["google-auth>=2", "google-auth-oauthlib>=1", "keyring>=24"]
+
+[project.urls]
+Homepage = "https://github.com/that-guy-wade/calendardb"
+Repository = "https://github.com/that-guy-wade/calendardb"
+
+[project.optional-dependencies]
+otel = ["opentelemetry-sdk>=1.20"]
+dev = ["pytest>=8", "ruff>=0.9", "radon>=6", "build>=1"]
+
+[project.scripts]
+calendardb = "calendardb.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/calendardb"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "C901"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10

calendardb-0.1.0/src/calendardb/__init__.py

@@ -0,0 +1,13 @@
+from .backend import FakeBackend
+from .client import Client
+from .logging_handler import CalendarHandler
+
+__all__ = ["Client", "FakeBackend", "CalendarHandler"]
+
+
+def __getattr__(name):
+    if name == "CalendarSpanExporter":
+        from .otel import CalendarSpanExporter
+
+        return CalendarSpanExporter
+    raise AttributeError(name)

calendardb-0.1.0/src/calendardb/auth.py

@@ -0,0 +1,113 @@
+"""Google OAuth credentials for CalendarDB."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import keyring
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+SERVICE_NAME = "calendardb"
+KEYRING_ACCOUNT = "oauth"
+TOKEN_ENV = "CALENDARDB_TOKEN"
+SCOPES = [
+    "https://www.googleapis.com/auth/calendar.app.created",
+    "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
+]
+
+
+class CalendarAuthError(Exception):
+    """Safe-to-display authentication error."""
+
+
+def _store(credentials: Credentials) -> None:
+    try:
+        keyring.set_password(SERVICE_NAME, KEYRING_ACCOUNT, credentials.to_json())
+    except Exception:
+        raise CalendarAuthError(
+            "Could not save CalendarDB authorization in the system keychain."
+        ) from None
+
+
+def login(client_secrets: str) -> None:
+    """Run Google's installed-app consent flow and save credentials securely."""
+    try:
+        flow = InstalledAppFlow.from_client_secrets_file(client_secrets, SCOPES)
+        credentials = flow.run_local_server(
+            host="localhost",
+            port=0,
+            authorization_prompt_message="",
+            success_message="CalendarDB authorization complete. You can close this window.",
+            prompt="consent",
+        )
+    except Exception:
+        raise CalendarAuthError(
+            "Google authorization failed. Check the client-secrets file and try again."
+        ) from None
+    if not credentials.refresh_token:
+        raise CalendarAuthError(
+            "Google did not grant a refresh token; authorize CalendarDB again with offline access."
+        )
+    _store(credentials)
+
+
+def logout() -> None:
+    """Remove CalendarDB's saved OAuth credentials from the system keychain."""
+    try:
+        keyring.delete_password(SERVICE_NAME, KEYRING_ACCOUNT)
+    except keyring.errors.PasswordDeleteError:
+        pass
+    except Exception:
+        raise CalendarAuthError(
+            "Could not remove CalendarDB authorization from the system keychain."
+        ) from None
+
+
+def _cached_credentials() -> Credentials:
+    try:
+        serialized = keyring.get_password(SERVICE_NAME, KEYRING_ACCOUNT)
+    except Exception:
+        raise CalendarAuthError(
+            "Could not read CalendarDB authorization from the system keychain."
+        ) from None
+    if not serialized:
+        raise CalendarAuthError(
+            "CalendarDB is not logged in. Run `calendardb login --client-secrets PATH`."
+        )
+    try:
+        info = json.loads(serialized)
+        if not isinstance(info, dict):
+            raise ValueError
+        return Credentials.from_authorized_user_info(info, SCOPES)
+    except Exception:
+        raise CalendarAuthError(
+            "Saved CalendarDB authorization is invalid. Run `calendardb login --client-secrets PATH`."
+        ) from None
+
+
+def get_access_token() -> str:
+    """Return a bearer token, refreshing and securely persisting OAuth as needed."""
+    token = os.environ.get(TOKEN_ENV)
+    if token:
+        return token
+    credentials = _cached_credentials()
+    if credentials.expired or not credentials.token:
+        if not credentials.refresh_token:
+            raise CalendarAuthError(
+                "Saved CalendarDB authorization expired. Run `calendardb login --client-secrets PATH`."
+            )
+        try:
+            credentials.refresh(Request())
+        except Exception:
+            raise CalendarAuthError(
+                "Could not refresh CalendarDB authorization. Run `calendardb login --client-secrets PATH`."
+            ) from None
+        _store(credentials)
+    if not credentials.valid:
+        raise CalendarAuthError(
+            "Saved CalendarDB authorization is unusable. Run `calendardb login --client-secrets PATH`."
+        )
+    return credentials.token

calendardb-0.1.0/src/calendardb/backend.py

@@ -0,0 +1,35 @@
+"""An offline backend for examples and tests."""
+
+import copy
+
+from .timestamps import in_range, parse_timestamp
+
+
+class FakeBackend:
+    def __init__(self):
+        self._records = {}
+
+    def create_record(self, record):
+        record_id = record["_id"]
+        if record_id in self._records and self._records[record_id] != record:
+            raise ValueError("Record ID already exists with different data")
+        self._records[record_id] = copy.deepcopy(record)
+        return record_id
+
+    def get_records(self, after=None, before=None, q=None):
+        if q:
+            raise NotImplementedError("Native Calendar search requires CalendarBackend")
+        start, end = [
+            None if value is None else parse_timestamp(value) for value in (after, before)
+        ]
+        return [
+            copy.deepcopy(record)
+            for record in self._records.values()
+            if in_range(parse_timestamp(record["_ts"]), start, end)
+        ]
+
+    def get_record(self, record_id):
+        return copy.deepcopy(self._records.get(record_id))
+
+    def delete_record(self, record_id):
+        self._records.pop(record_id, None)