tinyshed-tinystore 0.1.0rc2__tar.gz

tinyshed_tinystore-0.1.0rc2/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: tinyshed-tinystore
+Version: 0.1.0rc2
+Summary: TinyStore for Python: kv, jobs, blobs, SQL, records and metrics in one directory, served by a sidecar
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/tinyshed/tinystore
+Description-Content-Type: text/markdown
+
+<!--
+This is the page PyPI shows. The headline, the sample and the engines are the
+landing page's: task readme writes them between the landing: markers from
+web/landing.md. Every link is absolute, because PyPI cannot follow a relative
+one. Every call, by engine, is in docs/reference/python.md.
+-->
+
+# TinyStore for Python
+
+<!-- landing:headline -->
+
+**A small storage runtime for applications.** SQL, key-value state, durable jobs, files, metrics and logs in one directory, with one lifecycle, one memory budget and one backup.
+
+<!-- /landing:headline -->
+
+> **Release candidates first.** Until `v0.1.0`, the API may still change, and
+> a file written by one release may not open in the next.
+
+The SDK starts a small `tinystore` server next to your program, called the
+sidecar, and talks to it over a local connection. The server binary comes with the
+wheel, so there is nothing else to install. Go programs embed the same
+engines, and every client of one directory sees the same data.
+
+<!-- landing:sample -->
+
+```python
+import asyncio
+import logging
+from pathlib import Path
+
+import tinystore
+
+
+async def main() -> None:
+    async with tinystore.open("./data") as store:
+        db = await store.sql("app")
+        await db.exec("insert into users (id, name) values (?, ?)", 42, "Ada")
+
+        sessions = store.kv.bucket("sessions", str, sliding="30d")
+        await sessions.of("42").set("token", "abc123")
+
+        emails = store.jobs.queue("emails", dict[str, str])
+        await emails.enqueue({"to": "ada@example.com"})
+
+        files = store.blobs.bucket("files")
+        await files.put("avatars/42.png", Path("avatar.png").read_bytes())
+
+        logging.getLogger().addHandler(store.records.handler("api"))
+        logging.info("user created", extra={"user_id": 42})
+
+        store.metrics.counter("signups_total").inc()
+
+
+asyncio.run(main())
+```
+
+```sh
+pip install tinyshed-tinystore
+```
+
+<!-- /landing:sample -->
+
+It needs Python 3.12 or later and runs on asyncio. The package installs as
+`tinyshed-tinystore` and imports as `tinystore`.
+
+## Engines
+
+<!-- landing:engines -->
+
+| | | |
+|---|---|---|
+| [SQL](https://github.com/tinyshed/tinystore/blob/main/docs/sql/README.md) | Relational state | The application's own SQL databases: tables from structs, checked migrations. |
+| [KV](https://github.com/tinyshed/tinystore/blob/main/docs/kv/README.md) | Application state | Current state: typed buckets, counters, expiry, versions. |
+| [Jobs](https://github.com/tinyshed/tinystore/blob/main/docs/jobs/README.md) | Durable background work | Work that runs at its time: retries, leases, repeats. |
+| [Blobs](https://github.com/tinyshed/tinystore/blob/main/docs/blobs/README.md) | Files and objects | Files by path, checked when read whole. |
+| [Records](https://github.com/tinyshed/tinystore/blob/main/docs/records/README.md) | Logs and events | Read by time, level and keys. |
+| [Metrics](https://github.com/tinyshed/tinystore/blob/main/docs/metrics/README.md) | Time series | Samples kept bit for bit, answered exactly. |
+
+<!-- /landing:engines -->
+
+## Three ways to connect
+
+```python
+async with tinystore.open("./data") as store:  # the directory's sidecar, shared with other processes
+    ...
+async with tinystore.open("./data", private=True) as store:  # a server for this process alone, for tests and scripts
+    ...
+async with tinystore.connect("tls://db.internal:7070", token=token) as store:
+    ...
+```
+
+[The sidecar](https://github.com/tinyshed/tinystore/blob/main/docs/running/sidecar.md)
+and [A remote server](https://github.com/tinyshed/tinystore/blob/main/docs/running/server.md)
+explain each one.
+
+## The command line
+
+The wheel also installs the `tinystore` command. It shows what a store
+contains and follows its logs while your program runs. `uvx` runs it without
+installing anything:
+
+```sh
+uvx --from tinyshed-tinystore tinystore status ./data                          # each engine's size, and who serves the directory
+tinystore logs ./data -f                                                       # the application's logs, as they arrive
+claude mcp add tinystore -- uvx --from tinyshed-tinystore tinystore mcp ./data # read-only access for an AI agent
+```
+
+See [The command line](https://github.com/tinyshed/tinystore/blob/main/docs/running/cli.md)
+for every command.
+
+## Documentation
+
+- [Getting started](https://github.com/tinyshed/tinystore/blob/main/docs/getting-started.md): install it and write a first program
+- [A tour](https://github.com/tinyshed/tinystore/blob/main/docs/tour.md): every engine on one page
+- [The guides](https://github.com/tinyshed/tinystore/blob/main/docs/README.md): a page per feature, each example in Bun, Python and Go
+- [Python API](https://github.com/tinyshed/tinystore/blob/main/docs/reference/python.md): every call, by engine
+
+## License
+
+Apache-2.0.

tinyshed_tinystore-0.1.0rc2/README.md

@@ -0,0 +1,120 @@
+<!--
+This is the page PyPI shows. The headline, the sample and the engines are the
+landing page's: task readme writes them between the landing: markers from
+web/landing.md. Every link is absolute, because PyPI cannot follow a relative
+one. Every call, by engine, is in docs/reference/python.md.
+-->
+
+# TinyStore for Python
+
+<!-- landing:headline -->
+
+**A small storage runtime for applications.** SQL, key-value state, durable jobs, files, metrics and logs in one directory, with one lifecycle, one memory budget and one backup.
+
+<!-- /landing:headline -->
+
+> **Release candidates first.** Until `v0.1.0`, the API may still change, and
+> a file written by one release may not open in the next.
+
+The SDK starts a small `tinystore` server next to your program, called the
+sidecar, and talks to it over a local connection. The server binary comes with the
+wheel, so there is nothing else to install. Go programs embed the same
+engines, and every client of one directory sees the same data.
+
+<!-- landing:sample -->
+
+```python
+import asyncio
+import logging
+from pathlib import Path
+
+import tinystore
+
+
+async def main() -> None:
+    async with tinystore.open("./data") as store:
+        db = await store.sql("app")
+        await db.exec("insert into users (id, name) values (?, ?)", 42, "Ada")
+
+        sessions = store.kv.bucket("sessions", str, sliding="30d")
+        await sessions.of("42").set("token", "abc123")
+
+        emails = store.jobs.queue("emails", dict[str, str])
+        await emails.enqueue({"to": "ada@example.com"})
+
+        files = store.blobs.bucket("files")
+        await files.put("avatars/42.png", Path("avatar.png").read_bytes())
+
+        logging.getLogger().addHandler(store.records.handler("api"))
+        logging.info("user created", extra={"user_id": 42})
+
+        store.metrics.counter("signups_total").inc()
+
+
+asyncio.run(main())
+```
+
+```sh
+pip install tinyshed-tinystore
+```
+
+<!-- /landing:sample -->
+
+It needs Python 3.12 or later and runs on asyncio. The package installs as
+`tinyshed-tinystore` and imports as `tinystore`.
+
+## Engines
+
+<!-- landing:engines -->
+
+| | | |
+|---|---|---|
+| [SQL](https://github.com/tinyshed/tinystore/blob/main/docs/sql/README.md) | Relational state | The application's own SQL databases: tables from structs, checked migrations. |
+| [KV](https://github.com/tinyshed/tinystore/blob/main/docs/kv/README.md) | Application state | Current state: typed buckets, counters, expiry, versions. |
+| [Jobs](https://github.com/tinyshed/tinystore/blob/main/docs/jobs/README.md) | Durable background work | Work that runs at its time: retries, leases, repeats. |
+| [Blobs](https://github.com/tinyshed/tinystore/blob/main/docs/blobs/README.md) | Files and objects | Files by path, checked when read whole. |
+| [Records](https://github.com/tinyshed/tinystore/blob/main/docs/records/README.md) | Logs and events | Read by time, level and keys. |
+| [Metrics](https://github.com/tinyshed/tinystore/blob/main/docs/metrics/README.md) | Time series | Samples kept bit for bit, answered exactly. |
+
+<!-- /landing:engines -->
+
+## Three ways to connect
+
+```python
+async with tinystore.open("./data") as store:  # the directory's sidecar, shared with other processes
+    ...
+async with tinystore.open("./data", private=True) as store:  # a server for this process alone, for tests and scripts
+    ...
+async with tinystore.connect("tls://db.internal:7070", token=token) as store:
+    ...
+```
+
+[The sidecar](https://github.com/tinyshed/tinystore/blob/main/docs/running/sidecar.md)
+and [A remote server](https://github.com/tinyshed/tinystore/blob/main/docs/running/server.md)
+explain each one.
+
+## The command line
+
+The wheel also installs the `tinystore` command. It shows what a store
+contains and follows its logs while your program runs. `uvx` runs it without
+installing anything:
+
+```sh
+uvx --from tinyshed-tinystore tinystore status ./data                          # each engine's size, and who serves the directory
+tinystore logs ./data -f                                                       # the application's logs, as they arrive
+claude mcp add tinystore -- uvx --from tinyshed-tinystore tinystore mcp ./data # read-only access for an AI agent
+```
+
+See [The command line](https://github.com/tinyshed/tinystore/blob/main/docs/running/cli.md)
+for every command.
+
+## Documentation
+
+- [Getting started](https://github.com/tinyshed/tinystore/blob/main/docs/getting-started.md): install it and write a first program
+- [A tour](https://github.com/tinyshed/tinystore/blob/main/docs/tour.md): every engine on one page
+- [The guides](https://github.com/tinyshed/tinystore/blob/main/docs/README.md): a page per feature, each example in Bun, Python and Go
+- [Python API](https://github.com/tinyshed/tinystore/blob/main/docs/reference/python.md): every call, by engine
+
+## License
+
+Apache-2.0.

tinyshed_tinystore-0.1.0rc2/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "tinyshed-tinystore"
+version = "0.1.0rc2"
+description = "TinyStore for Python: kv, jobs, blobs, SQL, records and metrics in one directory, served by a sidecar"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/tinyshed/tinystore"
+
+[project.scripts]
+tinystore = "tinystore._cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "tinystore"
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "RUF",
+    "ASYNC",
+    "PT",
+    "N",
+    "C4",
+    "PERF",
+    "PIE",
+    "RET",
+    "TC",
+]
+ignore = [
+    "RUF001",
+    "RUF002",
+    "RUF003",
+    "ASYNC109",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "PT018",
+    "PT012",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"
+include = [
+    "src",
+    "tests",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["tinystore"]
+
+[tool.coverage.report]
+fail_under = 85
+show_missing = true
+skip_covered = true
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1",
+    "pytest-asyncio>=1.4",
+    "pytest-cov>=7.1",
+    "ruff>=0.16",
+    "pyright>=1.1.414",
+]

tinyshed_tinystore-0.1.0rc2/pyproject.toml.orig

@@ -0,0 +1,78 @@
+[project]
+name = "tinyshed-tinystore"
+version = "0.1.0rc2"
+description = "TinyStore for Python: kv, jobs, blobs, SQL, records and metrics in one directory, served by a sidecar"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/tinyshed/tinystore"
+
+[project.scripts]
+tinystore = "tinystore._cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "tinystore"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1",
+    "pytest-asyncio>=1.4",
+    "pytest-cov>=7.1",
+    "ruff>=0.16",
+    "pyright>=1.1.414",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I", "B", "UP", "SIM", "RUF", "ASYNC", "PT", "N", "C4", "PERF", "PIE", "RET", "TC",
+]
+ignore = [
+    "RUF001",  # an en dash or a multiplication sign in prose is what it says
+    "RUF002",
+    "RUF003",
+    "ASYNC109",  # a job's timeout is the handler's, not the call's
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["PT018", "PT012"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"
+include = ["src", "tests"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["tinystore"]
+
+[tool.coverage.report]
+fail_under = 85
+show_missing = true
+skip_covered = true

tinyshed_tinystore-0.1.0rc2/src/tinystore/__init__.py

@@ -0,0 +1,111 @@
+"""TinyStore for Python: kv, jobs, blobs, SQL, records and metrics in one directory, served by a sidecar.
+
+::
+
+    async with tinystore.open("./data") as store:
+        sessions = store.kv.bucket("sessions", Session, sliding=timedelta(days=30))
+        await sessions.of(user_id).set(token, session)
+"""
+
+from ._console import ConsoleHandler, handler
+from ._page import Page
+from .blobs import BlobBucket, BlobObject, Download, Usage
+from .clock import Clock
+from .config import Config, Source
+from .errors import (
+    CallCancelledError,
+    ClosedError,
+    ConflictError,
+    CorruptError,
+    InternalError,
+    InUseError,
+    InvalidError,
+    LimitError,
+    OutcomeUnknownError,
+    PermissionDeniedError,
+    ProtocolError,
+    SuspendedError,
+    TinystoreError,
+    TooNewError,
+    TooOldError,
+    UnauthenticatedError,
+    UnavailableError,
+    UnimplementedError,
+)
+from .jobs import ClaimedJob, Enqueue, Job, JobEntry, Queue, Repeat, cron, daily, every
+from .kv import Batch, Bucket, Counters, Entry, Once, Tx
+from .limiter import Allowance, Limiter
+from .metrics import Aggregate, Condition, Plan, Series, none_of, one_of, prefix
+from .quota import Quota, QuotaUsage, WindowUsage
+from .records import Cursor, Record, context, fields, trace
+from .sql import Database, Done
+from .store import Status, Store, connect, open
+
+__all__ = [
+    "Aggregate",
+    "Allowance",
+    "Batch",
+    "BlobBucket",
+    "BlobObject",
+    "Bucket",
+    "CallCancelledError",
+    "ClaimedJob",
+    "Clock",
+    "ClosedError",
+    "Condition",
+    "Config",
+    "ConflictError",
+    "ConsoleHandler",
+    "CorruptError",
+    "Counters",
+    "Cursor",
+    "Database",
+    "Done",
+    "Download",
+    "Enqueue",
+    "Entry",
+    "InUseError",
+    "InternalError",
+    "InvalidError",
+    "Job",
+    "JobEntry",
+    "LimitError",
+    "Limiter",
+    "Once",
+    "OutcomeUnknownError",
+    "Page",
+    "PermissionDeniedError",
+    "Plan",
+    "ProtocolError",
+    "Queue",
+    "Quota",
+    "QuotaUsage",
+    "Record",
+    "Repeat",
+    "Series",
+    "Source",
+    "Status",
+    "Store",
+    "SuspendedError",
+    "TinystoreError",
+    "TooNewError",
+    "TooOldError",
+    "Tx",
+    "UnauthenticatedError",
+    "UnavailableError",
+    "UnimplementedError",
+    "Usage",
+    "WindowUsage",
+    "connect",
+    "context",
+    "cron",
+    "daily",
+    "every",
+    "fields",
+    "handler",
+    "none_of",
+    "one_of",
+    "open",
+    "prefix",
+    "trace",
+]

tinyshed_tinystore-0.1.0rc2/src/tinystore/_background.py

@@ -0,0 +1,107 @@
+"""What the SDK does in the background, an instrument's flush or a handler's write.
+
+It has no caller to tell when it fails, so it says so as Go's tinystore.Store
+does, in TinyStore's own lines: once, again when the failure changes or ten
+minutes on, and once more when the work recovers.
+"""
+
+from __future__ import annotations
+
+import functools
+import threading
+import time
+from typing import TYPE_CHECKING, Any, Literal
+
+from ._console import ConsoleHandler, Line, encode_fields
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+_QUIET = 600.0
+"""A failure repeated within this many seconds is counted rather than said again."""
+
+type Level = Literal["info", "warn"]
+type Say = Callable[[Level, str, dict[str, Any]], None]
+"""Where TinyStore's own lines go: the console of a handler of stream tinystore, or a test's."""
+
+_LEVELS: dict[Level, int] = {"info": 0, "warn": 4}
+
+
+class _Own(ConsoleHandler):
+    """TinyStore's own lines, written as a handler of the console alone writes its own."""
+
+    def say(self, level: Level, message: str, fields: dict[str, Any]) -> None:
+        line = Line(
+            at=time.time_ns(),
+            stream="tinystore",
+            level=_LEVELS[level],
+            msg=message,
+            attrs=encode_fields(fields.items(), None),
+        )
+        self._print(line)
+
+
+@functools.cache
+def _own() -> _Own:
+    return _Own("tinystore")
+
+
+def say_own(level: Level, message: str, fields: dict[str, Any]) -> None:
+    """Says one of TinyStore's own lines, on stderr as the console of a handler of stream tinystore."""
+    _own().say(level, message, fields)
+
+
+class FailureLog:
+    """A background work's failures, said as Go's failureLog logs them::
+
+    00:00  disk full        → warn "background work failed" failures=1
+    00:01…00:09 the same    → counted
+    00:10  disk full        → warn failures=11
+    00:11  success          → info "background work recovered" failures=11
+    """
+
+    def __init__(self, work: str, say: Say = say_own, now: Callable[[], float] = time.monotonic) -> None:
+        self._work, self._say, self._now = work, say, now
+        self._last = ""
+        self._said_at = 0.0
+        self._failures = 0
+
+    def failed(self, err: BaseException) -> None:
+        self._failures += 1
+        error = str(err)
+        if error == self._last and self._now() - self._said_at < _QUIET:
+            return
+        self._say("warn", "background work failed", {"work": self._work, "error": error, "failures": self._failures})
+        self._last, self._said_at = error, self._now()
+
+    def succeeded(self) -> None:
+        if self._failures > 0:
+            self._say("info", "background work recovered", {"work": self._work, "failures": self._failures})
+        self._last, self._failures = "", 0
+
+
+class DropNotice:
+    """The lines a handler dropped for want of room, said at a flush and at most once in a quiet period.
+
+    A burst is one line, and a handler that keeps dropping says how many every
+    ten minutes rather than every second. A line is dropped on whichever
+    thread logged it and said on the loop's, so the count has a lock of its own.
+    """
+
+    def __init__(self, logger: str, buffer: int, say: Say = say_own, now: Callable[[], float] = time.monotonic) -> None:
+        self._logger, self._buffer, self._say, self._now = logger, buffer, say, now
+        self._counting = threading.Lock()
+        self._unsaid = 0
+        self._said_at: float | None = None
+
+    def dropped(self) -> None:
+        with self._counting:
+            self._unsaid += 1
+
+    def say_if_due(self) -> None:
+        with self._counting:
+            if self._unsaid == 0 or (self._said_at is not None and self._now() - self._said_at < _QUIET):
+                return
+            dropped, self._unsaid, self._said_at = self._unsaid, 0, self._now()
+        # logger, since a console line's own stream is tinystore's
+        self._say("warn", "log lines dropped", {"logger": self._logger, "dropped": dropped, "buffer": self._buffer})

tinyshed_tinystore-0.1.0rc2/src/tinystore/_cli.py

@@ -0,0 +1,42 @@
+"""The tinystore command, as this wheel installs it: the binary it carries, run
+with these arguments on this console, its exit code this process's.
+
+`uvx --from tinyshed-tinystore tinystore status ./data` needs nothing else
+installed, and after `pip install tinyshed-tinystore` it is `tinystore`.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+from ._runtime import WINDOWS, packaged_binary
+
+
+def main() -> None:
+    # Not PATH's tinystore: that may be this very command, which would run itself.
+    binary = os.environ.get("TINYSTORE_BIN") or packaged_binary()
+    if binary is None:
+        sys.exit(
+            "tinystore: this wheel carries no binary for this platform; install a platform's wheel, "
+            "put the binary of a release on PATH, or set TINYSTORE_BIN"
+        )
+    argv = [binary, *sys.argv[1:]]
+    if not WINDOWS:
+        os.execv(binary, argv)  # the binary in this process's place, its signals its own
+    sys.exit(_wait(subprocess.Popen(argv)))
+
+
+def _wait(child: subprocess.Popen[bytes]) -> int:
+    """The child's exit code. A Ctrl+C reaches it as it reaches this process, and the child ends on its own,
+    letting its SERVE and its lock go, so this one waits rather than end it."""
+    while True:
+        try:
+            return child.wait()
+        except KeyboardInterrupt:
+            continue
+
+
+if __name__ == "__main__":
+    main()