s2-sdk 0.1.0__tar.gz

s2_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+# NOTE: keep UV_VERSION in sync with uv-version in s2-lite-integration-tests sdks JSON below.
+env:
+  UV_VERSION: "0.11.3"
+
+on:
+  pull_request:
+    types:
+      [
+        opened,
+        synchronize,
+        ready_for_review,
+        reopened,
+      ]
+jobs:
+  local-checks:
+    name: Local Checks (code quality, unit tests, docs build)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: ${{ env.UV_VERSION }}
+      - name: Sync dependencies
+        run: |
+          uv sync --all-groups
+      - name: Static code check
+        run: uv run poe ci_checker
+      - name: Unit tests
+        run: uv run pytest tests/ -v -m 'not (account or basin or stream or metrics)'
+      - name: Check docs build
+        working-directory: ./docs
+        run: |
+          make html
+  s2-cloud-integration-tests:
+    name: s2-cloud integration tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: ${{ env.UV_VERSION }}
+      - name: Sync dependencies
+        run: uv sync --group test
+      - name: Run integration tests
+        env:
+          S2_ACCESS_TOKEN: ${{ secrets.S2_ACCESS_TOKEN }}
+        run: uv run pytest tests/ -v -s -m 'account or basin or stream or metrics'
+
+  build-s2-lite:
+    name: Build s2-lite
+    uses: s2-streamstore/s2/.github/workflows/build-s2-lite.yml@main
+
+  s2-lite-integration-tests:
+    name: s2-lite integration tests
+    needs: build-s2-lite
+    uses: s2-streamstore/s2/.github/workflows/sdk-tests.yml@main
+    with:
+      server-binary: server
+      server-args: "--port 8080"
+      server-port: 8080
+      sdks: |
+        [
+          {
+            "name": "python",
+            "repo": "${{ github.repository }}",
+            "ref": "${{ github.ref }}",
+            "lang": "python",
+            "uv-version": "0.11.3",
+            "test_cmd": "uv run pytest tests/ -v -s -m '(account or basin or stream) and not cloud_only'"
+          }
+        ]

s2_sdk-0.1.0/.github/workflows/pr-title.yml

@@ -0,0 +1,34 @@
+name: PR Title
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  validate:
+    name: Validate PR Title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            perf
+            refactor
+            style
+            test
+            chore
+            ci
+            revert
+          requireScope: false
+          subjectPattern: ^.+$
+          subjectPatternError: |
+            The subject "{subject}" is not valid.
+            Please use a non-empty subject after the type/scope.

s2_sdk-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,29 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ secrets.RELEASE_PLZ_APP_ID }}
+          private-key: ${{ secrets.RELEASE_PLZ_APP_PRIVATE_KEY }}
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+          token: ${{ steps.app-token.outputs.token }}

s2_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: Release
+
+on:
+  push:
+    tags: ["v[0-9]+.[0-9]+.[0-9]+*"]
+
+jobs:
+  pypi-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Build package
+        run: uv build
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

s2_sdk-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Sphinx
+docs/build
+
+# Claude Code
+.claude/

s2_sdk-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "s2-specs"]
+	path = s2-specs
+	url = https://github.com/s2-streamstore/s2-specs.git

s2_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

s2_sdk-0.1.0/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv 0.8.2
+      - asdf global uv 0.8.2
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --group docs
+    install:
+      - "true"
+
+sphinx:
+  configuration: docs/source/conf.py

s2_sdk-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

s2_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2026-04-07)
+
+
+### Features
+
+* add initial version of `s2-sdk` ([#1](https://github.com/s2-streamstore/s2-sdk-python/issues/1)) ([3dc9795](https://github.com/s2-streamstore/s2-sdk-python/commit/3dc979596b10db0881dd3132165467a227ad79d3))

s2_sdk-0.1.0/CODEOWNERS

@@ -0,0 +1 @@
+*	@s2-streamstore/dev

s2_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bandar Systems Inc. and 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.

s2_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: s2-sdk
+Version: 0.1.0
+Summary: Python SDK for s2.dev
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: h2>=4.1.0
+Requires-Dist: protobuf>=5.29.0
+Requires-Dist: zstandard>=0.23.0
+Description-Content-Type: text/markdown
+
+# s2-sdk
+<div>
+  <p>
+    <!-- PyPI -->
+    <a href="https://pypi.org/project/s2-sdk/"><img src="https://img.shields.io/pypi/v/s2-sdk" /></a>
+    <!-- Read the docs -->
+    <a href="https://s2-sdk.readthedocs.io/"><img src="https://img.shields.io/readthedocs/s2-sdk/latest" /></a>
+    <!-- Discord -->
+    <a href="https://discord.gg/vTCs7kMkAf"><img src="https://img.shields.io/discord/1209937852528599092?logo=discord" /></a>
+    <!-- LICENSE -->
+    <a href="https://github.com/s2-streamstore/s2-sdk-python/blob/main/LICENSE"><img src="https://img.shields.io/github/license/s2-streamstore/s2-sdk-python" /></a>
+  </p>
+</div>
+
+`s2-sdk` is the Python SDK for [S2](https://s2.dev/).
+
+## Project links
+
+- [PyPI](https://pypi.org/project/s2-sdk/)
+- [Documentation](https://s2-sdk.readthedocs.io/)
+- [GitHub](https://github.com/s2-streamstore/s2-sdk-python)
+
+## Requirements
+
+Python >= 3.11
+
+## Installation
+
+You can install the package from the [Python Package Index](https://pypi.org/project/s2-sdk) using the package manager of your choice. E.g., with `pip`:
+
+```bash
+pip install s2-sdk
+```
+
+## Get in touch
+
+Join our [Discord](https://discord.gg/vTCs7kMkAf) server. We would love to hear
+from you.
+
+You can also email us at [hi@s2.dev](mailto:hi@s2.dev).

s2_sdk-0.1.0/README.md

@@ -0,0 +1,40 @@
+# s2-sdk
+<div>
+  <p>
+    <!-- PyPI -->
+    <a href="https://pypi.org/project/s2-sdk/"><img src="https://img.shields.io/pypi/v/s2-sdk" /></a>
+    <!-- Read the docs -->
+    <a href="https://s2-sdk.readthedocs.io/"><img src="https://img.shields.io/readthedocs/s2-sdk/latest" /></a>
+    <!-- Discord -->
+    <a href="https://discord.gg/vTCs7kMkAf"><img src="https://img.shields.io/discord/1209937852528599092?logo=discord" /></a>
+    <!-- LICENSE -->
+    <a href="https://github.com/s2-streamstore/s2-sdk-python/blob/main/LICENSE"><img src="https://img.shields.io/github/license/s2-streamstore/s2-sdk-python" /></a>
+  </p>
+</div>
+
+`s2-sdk` is the Python SDK for [S2](https://s2.dev/).
+
+## Project links
+
+- [PyPI](https://pypi.org/project/s2-sdk/)
+- [Documentation](https://s2-sdk.readthedocs.io/)
+- [GitHub](https://github.com/s2-streamstore/s2-sdk-python)
+
+## Requirements
+
+Python >= 3.11
+
+## Installation
+
+You can install the package from the [Python Package Index](https://pypi.org/project/s2-sdk) using the package manager of your choice. E.g., with `pip`:
+
+```bash
+pip install s2-sdk
+```
+
+## Get in touch
+
+Join our [Discord](https://discord.gg/vTCs7kMkAf) server. We would love to hear
+from you.
+
+You can also email us at [hi@s2.dev](mailto:hi@s2.dev).

s2_sdk-0.1.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= uv run sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

s2_sdk-0.1.0/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

s2_sdk-0.1.0/docs/source/api-reference.md

@@ -0,0 +1,183 @@
+# API Reference
+
+```{eval-rst}
+.. module:: s2_sdk
+
+.. autoclass:: S2
+    :members:
+
+
+.. autoclass:: S2Basin()
+    :members:
+
+
+.. autoclass:: S2Stream()
+    :members:
+
+
+.. autoclass:: AppendSession()
+    :members:
+
+
+.. autoclass:: BatchSubmitTicket()
+    :members:
+
+.. autoclass:: Producer()
+    :members:
+
+
+.. autoclass:: RecordSubmitTicket()
+    :members:
+
+.. autoclass:: Endpoints
+    :members:
+
+
+.. autoclass:: Timeout(request: timedelta = timedelta(seconds=5), connection: timedelta = timedelta(seconds=3))
+    :members:
+
+.. autoclass:: Retry(max_attempts: int = 3, min_base_delay: timedelta = timedelta(milliseconds=100), max_base_delay: timedelta = timedelta(seconds=1), append_retry_policy: AppendRetryPolicy = AppendRetryPolicy.ALL)
+    :members:
+
+.. autoclass:: Batching(max_records: int = 1000, max_bytes: int = 1048576, linger: timedelta = timedelta(milliseconds=5))
+    :members:
+
+.. autoclass:: Record(body: bytes, headers: list[tuple[bytes, bytes]] = [], timestamp: int | None = None)
+    :members:
+
+.. autoclass:: AppendInput
+    :members:
+
+.. autoclass:: AppendAck()
+    :members:
+
+.. autoclass:: IndexedAppendAck()
+    :members:
+
+.. autoclass:: StreamPosition()
+    :members:
+
+.. autoclass:: ReadLimit
+    :members:
+
+.. autoclass:: ReadBatch()
+    :members:
+
+.. autoclass:: SequencedRecord()
+    :members:
+
+.. autoclass:: SeqNum
+    :members:
+
+.. autoclass:: Timestamp
+    :members:
+
+.. autoclass:: TailOffset
+    :members:
+
+.. autoclass:: Page()
+    :members:
+
+.. autoclass:: CommandRecord()
+    :members:
+
+
+.. autofunction:: metered_bytes
+
+.. autofunction:: append_record_batches
+
+.. autofunction:: append_inputs
+
+.. autoenum:: Compression
+
+.. autoenum:: AppendRetryPolicy
+
+.. autoenum:: StorageClass
+
+.. autoenum:: TimestampingMode
+
+.. autoclass:: Timestamping
+    :members:
+
+.. autoclass:: StreamConfig
+    :members:
+
+.. autoclass:: BasinConfig
+    :members:
+
+.. autoenum:: BasinScope
+
+.. autoclass:: BasinInfo()
+    :members:
+
+.. autoclass:: StreamInfo()
+    :members:
+
+.. autoclass:: ExactMatch
+    :members:
+
+.. autoclass:: PrefixMatch
+    :members:
+
+.. autoenum:: Permission
+
+.. autoenum:: Operation
+
+.. autoclass:: OperationGroupPermissions
+    :members:
+
+.. autoclass:: AccessTokenScope(basins: ExactMatch | PrefixMatch | None = None, streams: ExactMatch | PrefixMatch | None = None, access_tokens: ExactMatch | PrefixMatch | None = None, op_groups: OperationGroupPermissions | None = None, ops: list[Operation] = [])
+    :members:
+
+.. autoclass:: AccessTokenInfo()
+    :members:
+
+.. autoenum:: MetricUnit
+
+.. autoenum:: TimeseriesInterval
+
+.. autoenum:: AccountMetricSet
+
+.. autoenum:: BasinMetricSet
+
+.. autoenum:: StreamMetricSet
+
+.. autoclass:: Scalar()
+    :members:
+
+.. autoclass:: Accumulation()
+    :members:
+
+.. autoclass:: Gauge()
+    :members:
+
+.. autoclass:: Label()
+    :members:
+
+.. autoclass:: S2Error()
+    :members:
+
+.. autoclass:: S2ClientError()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: S2ServerError()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: AppendConditionError()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: FencingTokenMismatchError()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: SeqNumMismatchError()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: ReadUnwrittenError()
+    :members:
+    :show-inheritance:
+```

s2_sdk-0.1.0/docs/source/conf.py

@@ -0,0 +1,46 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+from datetime import date
+
+project = "s2-sdk"
+copyright = f"{date.today().year}, Bandar Systems Inc"
+release = "0.1.0"  # x-release-please-version
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autodoc.typehints",
+    "sphinx.ext.intersphinx",
+    "enum_tools.autoenum",
+    "sphinx.ext.viewcode",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+autodoc_member_order = "bysource"
+autodoc_typehints_format = "short"
+python_use_unqualified_type_names = True
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]
+html_theme_options = {
+    "light_logo": "s2-logo-black.png",
+    "dark_logo": "s2-logo-white.png",
+}

s2_sdk-0.1.0/docs/source/index.md

@@ -0,0 +1,8 @@
+```{include} ../../README.md
+```
+
+```{toctree}
+:hidden:
+
+api-reference
+```

s2_sdk-0.1.0/examples/consumer.py

@@ -0,0 +1,37 @@
+import asyncio
+import logging
+import os
+
+from s2_sdk import S2, Endpoints, SeqNum
+
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("s2_sdk").setLevel(
+    getattr(logging, os.getenv("S2_LOG_LEVEL", "INFO").upper(), logging.INFO)
+)
+logger = logging.getLogger(__name__)
+
+ACCESS_TOKEN = os.environ["S2_ACCESS_TOKEN"]
+BASIN = os.environ["S2_BASIN"]
+STREAM = os.environ["S2_STREAM"]
+ACCOUNT_ENDPOINT = os.getenv("S2_ACCOUNT_ENDPOINT")
+BASIN_ENDPOINT = os.getenv("S2_BASIN_ENDPOINT")
+
+
+async def consumer():
+    endpoints = (
+        Endpoints(account=ACCOUNT_ENDPOINT, basin=BASIN_ENDPOINT)
+        if ACCOUNT_ENDPOINT and BASIN_ENDPOINT
+        else None
+    )
+    async with S2(ACCESS_TOKEN, endpoints=endpoints) as s2:
+        stream = s2[BASIN][STREAM]
+        tail = await stream.check_tail()
+        logger.info("reading from tail: %s", tail)
+        total_num_records = 0
+        async for batch in stream.read_session(start=SeqNum(tail.seq_num)):
+            total_num_records += len(batch.records)
+            logger.info("read %d now, %d so far", len(batch.records), total_num_records)
+
+
+if __name__ == "__main__":
+    asyncio.run(consumer())