Implement write operations

.devcontainer/devcontainer.json

@@ -11,12 +11,7 @@
   "postCreateCommand": "pipx install poetry",
   "customizations": {
     "vscode": {
-      "extensions": [
-        "charliermarsh.ruff",
-        "ms-python.python",
-        "ms-python.isort",
-        "ms-python.black-formatter"
-      ]
+      "extensions": ["charliermarsh.ruff", "ms-python.python"]
     }
   }
 }

.prettierrc

@@ -1,4 +1,5 @@
 {
   "tabWidth": 2,
-  "useTabs": false
+  "useTabs": false,
+  "proseWrap": "always"
 }

CHANGELOG.md

@@ -8,12 +8,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
-- Support closing `Kv` client's `session` via: ([#20](https://github.com/h4l/denokv-python/pull/20))
+- Support writing to KV databases with `Kv.set()`, `Kv.delete()`, `Kv.sum()`,
+  `Kv.min()`, `Kv.max()`, `Kv.enqueue()` and `Kv.check()`.
+  ([#16](https://github.com/h4l/denokv-python/pull/16))
+
+  - These methods are available on `Kv` itself for one-off operations, and
+    `Kv.atomic()` can chain these methods to group write operations to apply
+    together in a transaction.
+
+- Support closing `Kv` client's `session` via:
+  ([#20](https://github.com/h4l/denokv-python/pull/20))
   - `Kv.aclose()`
   - async context manager
   - At interpreter exit / garbage collection via `Kv.create_finalizer()`
   - Automatically when an interactive console exists:
-    - `Kv` objects created by `open_kv()` from an interactive console/REPL automatically close at exit.
+    - `Kv` objects created by `open_kv()` from an interactive console/REPL
+      automatically close at exit.
     - The `open_kv()` function has a `finalize` option that controls this.
 
 [unreleased]: https://github.com/h4l/denokv-python/commits/main/

README.md

@@ -6,21 +6,31 @@ _Connect to [Deno KV] cloud and [self-hosted] databases from Python._
 [self-hosted]: https://deno.com/blog/kv-is-open-source-with-continuous-backup
 [denokv server]: https://github.com/denoland/denokv
 
-The `denokv` package is an unofficial Python client for the Deno KV database. It can connect to
-both the distributed cloud KV service, or self-hosted [denokv server] (which can be a replica of a cloud KV database, or standalone).
+The `denokv` package is an unofficial Python client for the Deno KV database. It
+can connect to both the distributed cloud KV service, or self-hosted [denokv
+server] (which can be a replica of a cloud KV database, or standalone).
 
-It implements version 3 of the [KV Connect protocol spec, published by Deno](https://github.com/denoland/denokv/blob/main/proto/kv-connect.md).
+It implements version 3 of the
+[KV Connect protocol spec, published by Deno](https://github.com/denoland/denokv/blob/main/proto/kv-connect.md).
 
 ## Status
 
-The package is under active development and is not yet stable or feature-complete.
+The package is under active development and is not yet stable or
+feature-complete.
 
 **Working**:
 
-- [x] Reading data with kv.get(), kv.list()
+- [x] Reading data with `Kv.get()`, `Kv.list()`
+  - The read APIs are being reworked to improve ergonomics and functionality
+- [x] Writing data with with `Kv.set()`, `Kv.delete()`, `Kv.sum()`, `Kv.min()`,
+      `Kv.max()`, `Kv.enqueue()` and `Kv.check()`.
+  - These methods are available on `Kv` itself for one-off operations, and
+    `Kv.atomic()` can chain these methods to group write operations to apply
+    together in a transaction.
 
 **To-do**:
 
-- [ ] [Writing data / transactions](https://docs.deno.com/deploy/kv/manual/transactions/)
 - [ ] [Watching for changes](https://docs.deno.com/deploy/kv/manual/operations/#watch)
 - [ ] [Queues](https://deno.com/blog/queues)
+  - This is uncertain: The KV Connect protocol does not support Queues, but they
+    could be implemented using watching in theory.

docker-bake.hcl

@@ -30,6 +30,20 @@ function "get_py_image_tag" {
 
 py_versions = ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
+target "dev" {
+    name = "dev_py${replace(py, ".", "")}"
+    matrix = {
+        py = py_versions,
+    }
+    args = {
+        PYTHON_VER = get_py_image_tag(py)
+        REPORT_CODE_COVERAGE = REPORT_CODE_COVERAGE
+        REPORT_CODE_BRANCH_COVERAGE = REPORT_CODE_BRANCH_COVERAGE
+    }
+    target = "poetry"
+    tags = ["ghcr.io/h4l/denokv-python/dev:py${replace(py, ".", "")}"]
+}
+
 target "test" {
     name = "test_py${replace(py, ".", "")}"
     matrix = {

docker-compose.yml

@@ -11,6 +11,19 @@ services:
     networks:
       - devcontainer_denokv_python
 
+  dev-py39:
+    profiles: [dev-py39]
+    image: ghcr.io/h4l/denokv-python/dev:py39
+    volumes:
+      - workspace:/workspaces
+    working_dir: /workspaces/denokv-python
+    environment:
+      PYTHONPATH: /workspaces/denokv-python/src
+    command: poetry run ipython
+    networks:
+      - devcontainer_denokv_python
+
+
 networks:
   devcontainer_denokv_python:
     external: true

pyproject.toml

@@ -25,7 +25,7 @@ protobuf = ">=4.22.0,<6"
 # change was in 6.2.4 (which is late 2019)
 # https://github.com/apple/foundationdb/commits/main/bindings/python/fdb/tuple.py
 foundationdb = ">=6.2.4,<8"
-v8serialize = "^0.1.0"
+v8serialize = "^0.2.0-alpha.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.2"
@@ -57,6 +57,9 @@ extra_standard_library = ["typing_extensions"]
 
 [tool.mypy]
 strict = true
+enable_error_code = [
+  'possibly-undefined'
+]
 mypy_path = "./stubs"
 
 [[tool.mypy.overrides]]
@@ -84,6 +87,7 @@ select = [
   "FA",  # flake8-future-annotations
   "PYI", # flake8-pyi
   "I",
+  "TID", # flake8-tidy-imports
 ]
 
 ignore = [
@@ -99,6 +103,10 @@ ignore = [
   "PYI041",
 ]
 
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"typing_extensions".msg = "use denokv._pycompat.typing instead, typing_extensions is not a runtime dependency."
+"typing".msg = "Use denokv._pycompat.typing instead (apart from overload and Literal), using typing is error-prone as it has many differences between python versions."
+
 [tool.ruff.lint.pydocstyle]
 convention = "numpy"
 
@@ -114,6 +122,7 @@ filterwarnings = [
 ]
 
 [tool.coverage.run]
+source = ["denokv"]
 omit = [
     # generated Protocol Buffers module
     "*/denokv/_datapath_pb2.py",

src/denokv/__init__.py

@@ -1,5 +1,8 @@
 from __future__ import annotations
 
+from denokv._kv_values import KvEntry as KvEntry
+from denokv._kv_values import KvU64 as KvU64
+from denokv._kv_values import VersionStamp as VersionStamp
 from denokv.auth import ConsistencyLevel as ConsistencyLevel
 from denokv.auth import MetadataExchangeDenoKvError as MetadataExchangeDenoKvError
 from denokv.datapath import AnyKvKey as AnyKvKey
@@ -13,10 +16,7 @@
 from denokv.kv import CursorFormatType as CursorFormatType
 from denokv.kv import Kv as Kv
 from denokv.kv import KvCredentials as KvCredentials
-from denokv.kv import KvEntry as KvEntry
 from denokv.kv import KvListOptions as KvListOptions
-from denokv.kv import KvU64 as KvU64
 from denokv.kv import ListKvEntry as ListKvEntry
-from denokv.kv import VersionStamp as VersionStamp
 from denokv.kv import open_kv as open_kv
 from denokv.kv_keys import KvKey as KvKey

src/denokv/_kv_types.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+
+from google.protobuf.message import Message
+from v8serialize import Encoder
+
+from denokv._datapath_pb2 import AtomicWrite
+from denokv._kv_values import VersionStamp
+from denokv._pycompat.typing import Generic
+from denokv._pycompat.typing import Protocol
+from denokv._pycompat.typing import Sequence
+from denokv._pycompat.typing import TypeAlias
+from denokv._pycompat.typing import TypeGuard
+from denokv._pycompat.typing import TypeVar
+from denokv._pycompat.typing import Union
+from denokv.auth import EndpointInfo
+from denokv.datapath import CheckFailure
+from denokv.datapath import DataPathError
+from denokv.result import Nothing
+from denokv.result import Option
+from denokv.result import Result
+from denokv.result import Some
+
+WriteResultT = TypeVar("WriteResultT")
+WriteResultT_co = TypeVar("WriteResultT_co", covariant=True)
+MessageT_co = TypeVar("MessageT_co", bound=Message, covariant=True)
+
+
+class ProtobufMessageRepresentation(Generic[MessageT_co], ABC):
+    """An object that can represent itself as a protobuf Messages."""
+
+    __slots__ = ()
+
+    @abstractmethod
+    def as_protobuf(self, *, v8_encoder: Encoder) -> Sequence[MessageT_co]: ...
+
+
+class SingleProtobufMessageRepresentation(ProtobufMessageRepresentation[MessageT_co]):
+    """An object that can represent itself as a single protobuf Message."""
+
+    __slots__ = ()
+
+    @abstractmethod
+    def as_protobuf(self, *, v8_encoder: Encoder) -> tuple[MessageT_co]: ...
+
+
+class AtomicWriteRepresentation(SingleProtobufMessageRepresentation[AtomicWrite]):
+    __slots__ = ()
+
+
+class AtomicWriteRepresentationWriter(
+    AtomicWriteRepresentation, Generic[WriteResultT_co]
+):
+    __slots__ = ()
+
+    @abstractmethod
+    async def write(self, kv: KvWriter, *, v8_encoder: Encoder) -> WriteResultT_co: ...
+
+
+KvWriterWriteResult: TypeAlias = Result[
+    tuple[VersionStamp, EndpointInfo], Union[CheckFailure, DataPathError]
+]
+
+
+class KvWriter(ABC):
+    """A low-level interface for objects that can perform KV writes."""
+
+    @abstractmethod
+    async def write(self, *, protobuf_atomic_write: AtomicWrite) -> KvWriterWriteResult:
+        """Write a protobuf AtomicWrite message to the database."""
+
+
+class V8EncoderProvider(Protocol):
+    @property
+    def v8_encoder(self) -> Encoder: ...
+
+
+def is_v8_encoder_provider(obj: object) -> TypeGuard[V8EncoderProvider]:
+    return isinstance(getattr(obj, "v8_encoder", None), Encoder)
+
+
+def get_v8_encoder(maybe_v8_encoder_provider: object) -> Option[Encoder]:
+    if is_v8_encoder_provider(maybe_v8_encoder_provider):
+        return Some(maybe_v8_encoder_provider.v8_encoder)
+    return Nothing()