langgraph-checkpoint-objectstorage 0.1.7__tar.gz

langgraph_checkpoint_objectstorage-0.1.7/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Default owner for everything in the repo, unless a more specific
+# pattern below overrides it. See:
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+* @sergiommarcial

langgraph_checkpoint_objectstorage-0.1.7/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,51 @@
+name: Bug report
+description: Report a problem with langgraph-checkpoint-objectstorage
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: What did you expect instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: A minimal code snippet, if possible
+      render: python
+    validations:
+      required: false
+
+  - type: input
+    id: backend
+    attributes:
+      label: Backend
+      description: local filesystem / S3 / GCS (and fsspec/s3fs/gcsfs version, if relevant)
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: langgraph-checkpoint-objectstorage version
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Set `LANGGRAPH_CHECKPOINT_OBJECTSTORAGE_LOG_LEVEL=DEBUG` for detail (see the README's Logging section)
+      render: shell
+    validations:
+      required: false

langgraph_checkpoint_objectstorage-0.1.7/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Description
+
+<!-- What does this change do, and why? -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Docs / chore
+
+## Testing
+
+<!-- How did you verify this? -->
+
+## Checklist
+
+- [ ] `make test` passes (`make test-integration` too, if this touches backend I/O)
+- [ ] Added an entry under `## [Unreleased]` in `CHANGELOG.md` (if user-facing)

langgraph_checkpoint_objectstorage-0.1.7/.github/workflows/ci.yml

@@ -0,0 +1,112 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - run: make lint
+
+  test-unit:
+    runs-on: ubuntu-latest
+    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - run: make test-unit
+
+  test-integration:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - run: make test-integration
+      - if: always()
+        run: docker compose down
+
+  release:
+    needs: [lint, test-unit, test-integration]
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.RELEASE_PAT }}
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Bump version and update CHANGELOG.md
+        run: |
+          python3 - <<'EOF'
+          import os
+          import re
+          from datetime import datetime, timezone
+
+          # -- bump pyproject.toml --
+          pyproject_path = "pyproject.toml"
+          text = open(pyproject_path).read()
+          match = re.search(r'^version = "(\d+)\.(\d+)\.(\d+)"$', text, re.MULTILINE)
+          major, minor, patch = match.groups()
+          new_version = f"{major}.{minor}.{int(patch) + 1}"
+          text = text[: match.start()] + f'version = "{new_version}"' + text[match.end() :]
+          open(pyproject_path, "w").write(text)
+
+          # -- move [Unreleased]'s content into a new dated version section --
+          # Contributors add entries under "## [Unreleased]" as they work
+          # (Keep a Changelog convention); release just retitles that
+          # section with the version and date, and leaves a fresh empty
+          # Unreleased section above it.
+          changelog_path = "CHANGELOG.md"
+          changelog = open(changelog_path).read()
+          today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+          marker = "## [Unreleased]"
+          start = changelog.index(marker)
+          body_start = start + len(marker)
+          next_heading = changelog.find("\n## [", body_start)
+          body = changelog[body_start:next_heading].strip("\n")
+          if not body:
+              body = "### Changed\n\n- No changelog entries were added for this release."
+          new_section = f"{marker}\n\n## [{new_version}] - {today}\n\n{body}\n\n"
+          changelog = changelog[:start] + new_section + changelog[next_heading + 1 :]
+          open(changelog_path, "w").write(changelog)
+
+          with open(os.environ["GITHUB_ENV"], "a") as f:
+              f.write(f"NEW_VERSION={new_version}\n")
+          EOF
+      - name: Commit version bump
+        run: |
+          git add pyproject.toml CHANGELOG.md
+          git commit -m "chore(release): v${NEW_VERSION}"
+      - name: Push version bump
+        run: git push origin main

langgraph_checkpoint_objectstorage-0.1.7/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

langgraph_checkpoint_objectstorage-0.1.7/.gitignore

@@ -0,0 +1,219 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+CLAUDE.md

langgraph_checkpoint_objectstorage-0.1.7/.python-version

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

langgraph_checkpoint_objectstorage-0.1.7/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning is `MAJOR.MINOR.PATCH`; the patch number bumps automatically on
+every merge to `main` (see the `release` job in `.github/workflows/ci.yml`,
+which also updates this file).
+
+## [Unreleased]
+
+## [0.1.7] - 2026-08-30
+
+### Changed
+
+- No changelog entries were added for this release.
+
+## [0.1.6] - 2026-08-30
+
+### Changed
+
+- No changelog entries were added for this release.
+
+## [0.1.5] - 2026-08-16
+
+### Changed
+
+- No changelog entries were added for this release.
+
+## [0.1.4] - 2026-08-16
+
+### Changed
+
+- No changelog entries were added for this release.
+
+## [0.1.3] - 2026-08-16
+
+### Added
+
+- Usage examples for `pip`, `uv`, and `poetry` (`examples/`): a minimal
+  local-filesystem quickstart for each, plus multi-session S3 (`uv`) and
+  GCS (`poetry`) examples demonstrating sequential sessions with resume,
+  and the same pattern run concurrently via the async API.
+
+### Fixed
+
+- The sync API (`put`, `get_tuple`, `list`, `put_writes`, `delete_thread`)
+  could break on the second call against S3/GCS with `RuntimeError: Event
+  loop is closed`. `asyncio.run()` opened a fresh event loop per call, but
+  `s3fs`/`gcsfs` bind their session to whichever loop is running at first
+  use. Fixed by routing sync calls through the filesystem's own persistent
+  background loop, and giving every `ObjectStorageSaver` its own
+  filesystem instance (`skip_instance_cache=True`) so separate savers can
+  no longer share (and cross-contaminate) a session.
+
+## [0.1.2] - 2026-08-16
+
+### Fixed
+
+- The automated release job's version tag never reached the remote:
+  `git push --follow-tags` only pushes *annotated* tags, and the tag was
+  created lightweight. Switched to an annotated tag pushed explicitly.
+
+## [0.1.1] - 2026-08-16
+
+### Added
+
+- GitHub Actions CI (`.github/workflows/ci.yml`): lint, unit tests across
+  Python 3.11/3.12/3.13, integration tests against docker-compose S3/GCS
+  emulators, and an automated release job that bumps the patch version,
+  tags, and publishes a GitHub Release with the built wheel/sdist attached.
+- `LICENSE` (MIT).
+
+## [0.1.0] - 2026-08-16
+
+### Added
+
+- Initial release: `ObjectStorageSaver`, a LangGraph `BaseCheckpointSaver`
+  backed by local filesystem, Google Cloud Storage, or AWS S3 through a
+  single fsspec-backed class, chosen by connection string.
+- Full sync and async API (`get_tuple`/`aget_tuple`, `put`/`aput`,
+  `list`/`alist`, `put_writes`/`aput_writes`, `delete_thread`/`adelete_thread`),
+  validated against the official `langgraph-checkpoint-conformance` suite
+  on all three backends.
+- Runtime type checking on the public API via `typeguard`.
+- `py.typed` static type coverage.
+- `Makefile` (`lint`, `test`, `test-unit`, `test-integration`, `compose-up`/
+  `compose-down`, `build`) and a `docker-compose.yaml` for local S3/GCS
+  emulators (`moto-server`, `fake-gcs-server`).

langgraph_checkpoint_objectstorage-0.1.7/LICENSE

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

langgraph_checkpoint_objectstorage-0.1.7/Makefile

@@ -0,0 +1,118 @@
+.DEFAULT_GOAL := help
+SHELL := /bin/bash
+
+# Every target runs through `uv` -- never assumes an activated venv or a
+# particular shell state. `uv run`/`uv sync` manage an isolated .venv
+# regardless of what's on the caller's PATH.
+UV := uv
+REQUIRED_PYTHON := $(shell cat .python-version 2>/dev/null)
+
+BOLD := \033[1m
+GREEN := \033[32m
+YELLOW := \033[33m
+RED := \033[31m
+CYAN := \033[36m
+RESET := \033[0m
+
+.PHONY: help
+help: ## Show this help
+	@echo -e "$(BOLD)langgraph-checkpoint-objectstorage$(RESET)"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  $(CYAN)%-18s$(RESET) %s\n", $$1, $$2}'
+
+.PHONY: check-uv
+check-uv: ## Verify uv is installed (prompts to install if missing)
+	@if command -v uv >/dev/null 2>&1; then \
+		echo -e "$(GREEN)uv found:$(RESET) $$(uv --version)"; \
+	else \
+		echo -e "$(YELLOW)uv not found on PATH.$(RESET)"; \
+		read -p "Install uv now via the official installer (curl | sh)? [y/N] " ans; \
+		if [ "$$ans" = "y" ] || [ "$$ans" = "Y" ]; then \
+			curl -LsSf https://astral.sh/uv/install.sh | sh; \
+			echo -e "$(YELLOW)uv installed -- open a new shell (or re-source your profile) so it's on PATH, then re-run make.$(RESET)"; \
+			exit 1; \
+		else \
+			echo -e "$(RED)uv is required. Install manually: https://docs.astral.sh/uv/getting-started/installation/$(RESET)"; \
+			exit 1; \
+		fi; \
+	fi
+
+.PHONY: check-python
+check-python: check-uv ## Verify a valid Python toolchain is resolvable for this repo
+	@echo "Required Python (.python-version): $(REQUIRED_PYTHON)"
+	@if resolved=$$(uv python find $(REQUIRED_PYTHON) 2>/dev/null); then \
+		echo -e "$(GREEN)Resolved:$(RESET) $$resolved"; \
+	else \
+		echo -e "$(YELLOW)Python $(REQUIRED_PYTHON) not installed locally -- uv will download it automatically on the next sync.$(RESET)"; \
+	fi
+
+.PHONY: install
+install: check-python ## Install package + s3/gcs extras + dev/test toolchain into an isolated .venv
+	@$(UV) sync --all-extras --group dev
+
+.PHONY: lint
+lint: install ## Static analysis: black --check, pyflakes, bandit, vulture (runs before test/build)
+	@status=0; \
+	echo "-- black --check --"; \
+	$(UV) run black --check src tests vulture_whitelist.py || status=1; \
+	echo "-- pyflakes --"; \
+	$(UV) run pyflakes src tests || status=1; \
+	echo "-- bandit (src only -- tests use intentional fake credentials/asserts) --"; \
+	$(UV) run bandit -r -q src || status=1; \
+	echo "-- vulture (whitelisted for public API -- see vulture_whitelist.py) --"; \
+	$(UV) run vulture src vulture_whitelist.py || status=1; \
+	if [ $$status -eq 0 ]; then \
+		echo -e "$(GREEN)Lint clean.$(RESET)"; \
+	else \
+		echo -e "$(RED)Lint failed.$(RESET) See above. \`make format\` fixes black issues automatically."; \
+		exit 1; \
+	fi
+
+.PHONY: format
+format: install ## Apply black formatting in place
+	@$(UV) run black src tests vulture_whitelist.py
+
+.PHONY: test
+test: lint ## Run the full test suite (integration tests auto-skip without `make compose-up`)
+	@$(UV) run pytest
+
+.PHONY: test-unit
+test-unit: lint ## Run only unit tests (tests/unit -- no external services)
+	@$(UV) run pytest tests/unit
+
+.PHONY: test-integration
+test-integration: lint compose-up ## Run integration tests (starts docker-compose emulators first)
+	@$(UV) run pytest tests/integration
+
+.PHONY: check-docker
+check-docker: ## Verify the Docker daemon is reachable
+	@if docker info >/dev/null 2>&1; then \
+		echo -e "$(GREEN)Docker daemon reachable.$(RESET)"; \
+	else \
+		echo -e "$(RED)Docker daemon not reachable.$(RESET) Start Docker (e.g. Docker Desktop) and retry."; \
+		exit 1; \
+	fi
+
+.PHONY: compose-up
+compose-up: check-docker ## Start local S3/GCS emulators (moto-server, fake-gcs-server)
+	@docker compose up -d
+	@echo -e "$(GREEN)Emulators up.$(RESET) moto-server on :5001, fake-gcs-server on :4443."
+
+.PHONY: compose-down
+compose-down: check-docker ## Stop local S3/GCS emulators
+	@docker compose down
+
+.PHONY: compose-logs
+compose-logs: ## Tail logs from the emulator containers
+	@docker compose logs -f
+
+.PHONY: build
+build: lint ## Build the wheel/sdist into dist/
+	@$(UV) build
+
+.PHONY: clean
+clean: ## Remove the venv, caches, and build artifacts
+	@rm -rf .venv .pytest_cache dist build *.egg-info
+	@find . -name "__pycache__" -type d -prune -exec rm -rf {} +
+	@echo -e "$(GREEN)Cleaned.$(RESET)"