remote-store 0.4.0__tar.gz

remote_store-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ tests/ examples/
+      - run: ruff format --check src/ tests/ examples/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov=remote_store --cov-report=term-missing --cov-fail-under=95
+
+  examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: python examples/quickstart.py
+      - run: python examples/file_operations.py
+      - run: python examples/streaming_io.py
+      - run: python examples/atomic_writes.py
+      - run: python examples/configuration.py
+      - run: python examples/error_handling.py
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[docs]"
+      - run: mkdocs build --strict
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - run: pip install dist/*.whl
+      - run: python -c "import remote_store; print(remote_store.__version__)"

remote_store-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Docs
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[docs]"
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+      - id: deploy
+        uses: actions/deploy-pages@v4

remote_store-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+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.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

remote_store-0.4.0/.gitignore

@@ -0,0 +1,24 @@
+# IDEs & tools
+.venv/
+.vscode/
+.claude/
+
+# Caching
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Building
+dist/
+build/
+*.egg-info/
+*.whl
+*.tar.gz
+
+# Testing & Coverage
+.coverage
+htmlcov/
+
+# Documentation
+site/

remote_store-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [s3fs, paramiko, tenacity, types-paramiko, pyarrow]
+        args: [--config-file=pyproject.toml]
+        files: ^src/

remote_store-0.4.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

remote_store-0.4.0/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/). Pre-1.0, minor bumps may contain breaking changes.
+
+## [Unreleased]
+
+---
+
+## [0.4.0] - 2026-02-19
+
+### Added
+
+- **S3-PyArrow hybrid backend** -- uses PyArrow's C++ S3 filesystem for reads/writes/copies (higher throughput for large files) and s3fs for listing/metadata/deletion. Drop-in alternative to `S3Backend` with the same constructor signature.
+  - Install via `pip install remote-store[s3-pyarrow]`
+  - Spec: `sdd/specs/011-s3-pyarrow-backend.md`
+- New optional extra: `s3-pyarrow` (requires `s3fs>=2024.2.0` and `pyarrow>=14.0.0`)
+- Dual `unwrap()` support: returns either `pyarrow.fs.S3FileSystem` or `s3fs.S3FileSystem`
+
+---
+
+## [0.3.0] - 2026-02-18
+
+### Added
+
+- **`Store.to_key(path)`** — public method to convert backend-native paths to store-relative keys
+- **`Backend.to_key()`** — backend-level native-path-to-key conversion
+- Python 3.14 support — added to CI test matrix and PyPI classifiers
+- **PyPI publish workflow** — trusted publishing (OIDC) via GitHub Actions on `v*` tags (BL-001)
+- **SFTP backend documentation** — `docs/backends/sftp.md` with installation, usage, and API reference (BL-002)
+- **CITATION.cff** — enables GitHub's "Cite this repository" button (BL-005)
+- **Development backlog** — `sdd/BACKLOG.md` for tracking release blockers, prioritized work, and ideas
+- Versioning policy added to SDD process doc (`sdd/000-process.md`)
+- Set up GitHub Pages docs hosting via `actions/deploy-pages` (BL-008)
+
+### Fixed
+
+- Store round-trip bug: `list()` returned backend-relative paths that included `root_path`, breaking re-use as input to `read()`/`delete()`
+- CI: fixed cross-platform `type: ignore` comments for S3 backend
+
+### Changed
+
+- **README rewritten** — approachable, dev-friendly tone with scannable layout (BL-003, BL-004)
+- Pinned minimum versions on public extras: `s3fs>=2024.2.0`, `paramiko>=2.2`, `tenacity>=4.0`
+- Removed `typing-extensions` from core dependencies (unused -- Python 3.10+ covers all needs)
+- Removed `azure` extra (`adlfs`) -- no Azure backend exists yet; will be re-added with the backend
+
+---
+
+## [0.2.0] - 2026-02-17
+
+### Added
+
+- **SFTP backend** via pure paramiko with host key policies (STRICT / TOFU / AUTO_ADD), PEM key sanitization, and tenacity retry on transient SSH errors
+- Simulated atomic writes (temp file + rename) with documented orphan-file caveat
+- `HostKeyPolicy` enum and `load_private_key()` utility for key management
+- `_sanitize_pem()` for Azure Key Vault PEM compatibility
+
+### Changed
+
+- `sftp` optional dependency changed from `paramiko + sshfs` to `paramiko + tenacity`
+- Version bumped to 0.2.0
+
+---
+
+## [0.1.0] - 2026-02-14
+
+### Added
+
+- **Store** — primary user-facing abstraction for folder-scoped file operations
+- **Registry** — backend lifecycle management with lazy instantiation and context manager support
+- **RegistryConfig / BackendConfig / StoreProfile** — declarative, immutable configuration with `from_dict()` for TOML/JSON parsing
+- **RemotePath** — immutable, validated path value object with normalization and safety checks
+- **Local backend** — stdlib-only reference implementation with full capability support
+- **Capability system** — backends declare supported features; unsupported operations fail explicitly
+- **Normalized error hierarchy** — `NotFound`, `AlreadyExists`, `InvalidPath`, `PermissionDenied`, `CapabilityNotSupported`, `BackendUnavailable`
+- **Streaming-first I/O** — `read()` returns `BinaryIO`, `write()` accepts `bytes | BinaryIO`
+- **Atomic writes** — `write_atomic()` via temp-file-and-rename
+- **Empty path support** — `""` resolves to store root for folder/query operations (see ADR-0004)
+- **Full type safety** — mypy strict mode, `py.typed` marker
+- **Spec-driven development** — 7 specifications, 4 ADRs, full test traceability with `@pytest.mark.spec`
+- **Examples** — 6 runnable Python scripts and 3 Jupyter notebooks
+- **CI** — ruff, mypy, pytest (Python 3.10–3.13), example validation
+
+### Known Limitations
+
+- Only the local filesystem backend is implemented. S3, Azure, and SFTP backends are planned.
+- No glob/pattern matching support yet (`Capability.GLOB` is declared but unused).
+- No async API (sync-only by design; compatible with structured concurrency).

remote_store-0.4.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "remote-store"
+abstract: >-
+  One simple API for file storage. Local, S3, SFTP, Azure.
+  Same methods, swappable backends, zero reinvention.
+type: software
+version: 0.4.0
+date-released: 2026-02-19
+license: MIT
+repository-code: https://github.com/haalfi/remote-store
+url: https://haalfi.github.io/remote-store/
+authors:
+  - family-names: Alferi
+    given-names: Harald
+keywords:
+  - file-storage
+  - object-storage
+  - storage-abstraction
+  - python
+  - s3
+  - sftp

remote_store-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to Remote Store
+
+Thank you for your interest in contributing! This project follows **Spec-Driven Development (SDD)**: every feature starts as a specification before any code is written. See [`sdd/000-process.md`](sdd/000-process.md) for the full methodology.
+
+## Spec-First Workflow
+
+1. **Propose** — Open a PR with an RFC in `sdd/rfcs/` (see [`rfc-template.md`](sdd/rfcs/rfc-template.md)). No code yet.
+2. **Review** — Maintainers and community review for design fit and completeness.
+3. **Accept** — The RFC graduates to a spec in `sdd/specs/`. It now defines the contract.
+4. **Implement** — Open a follow-up PR with tests (referencing spec IDs) and implementation.
+
+## Repository Structure
+
+```
+sdd/
+  000-process.md              # How specs work in this repo
+  specs/                      # Accepted specifications (source of truth)
+    001-store-api.md
+    002-registry-config.md
+    003-backend-adapter-contract.md
+    004-path-model.md
+    005-error-model.md
+    006-streaming-io.md
+    007-atomic-writes.md
+  adrs/                       # Architecture Decision Records (immutable)
+  rfcs/                       # Proposals under discussion
+```
+
+## Spec Format
+
+Each spec uses numbered section IDs with a module prefix:
+
+```markdown
+## <PREFIX>-NNN: <Rule Title>
+**Invariant:** <what must always be true>
+**Preconditions:** <what the caller must ensure>
+**Postconditions:** <what the callee guarantees>
+**Raises:** <error conditions>
+**Example:**
+    <short code example>
+```
+
+Prefixes: `STORE`, `MOD` (models), `CFG` (config), `REG` (registry), `BE` (backend), `CAP` (capabilities), `PATH`, `ERR`, `SIO` (streaming I/O), `AW` (atomic writes).
+
+## Adding a New Backend
+
+1. Write a spec in `sdd/specs/` or as an addendum in `sdd/specs/backends/<name>.md`
+2. Implement `Backend` ABC in `src/remote_store/backends/_<name>.py`
+3. Add a conformance fixture in `tests/backends/conftest.py`
+4. The entire conformance suite (`tests/backends/test_conformance.py`) runs automatically
+
+## Adding an Extension
+
+1. Write an RFC in `sdd/rfcs/`, get it accepted as a spec
+2. Implement in `src/remote_store/ext/<name>.py`
+3. Add tests in `tests/ext/test_<name>.py`
+4. Use `unwrap()` for native backend access when needed
+
+## Third-Party Extensions
+
+External packages should:
+
+- Use naming convention: `remote-store-<name>`
+- Use `register_backend()` for backend registration
+- Use `unwrap()` for native handle access
+- Reuse the conformance test suite by importing and parameterizing it
+
+## Development Setup
+
+```bash
+# Clone and enter the repo
+git clone https://github.com/haalfi/remote-store.git
+cd remote-store
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Verify everything works
+hatch run all    # or run individual steps:
+hatch run lint
+hatch run typecheck
+hatch run test-cov
+hatch run examples
+```
+
+All dev scripts are defined in `pyproject.toml` under `[tool.hatch.envs.default.scripts]`. Run `hatch run` to see available commands.
+
+## Code Style
+
+See [`sdd/DESIGN.md` Section 11](sdd/DESIGN.md#11-code-style) for the full code style conventions.
+
+- **Formatter/linter:** ruff (line-length 120)
+- **Type checking:** mypy strict mode
+- **Tests:** pytest with `@pytest.mark.spec("ID")` markers for spec traceability
+- **Coverage:** Target >= 95%
+
+## Test Requirements
+
+- Every spec section must have at least one test with `@pytest.mark.spec("ID")`
+- Run `pytest -m spec` to verify all spec-derived tests pass
+- Run `pytest --cov=remote_store` for coverage reports
+
+## Examples and Notebooks
+
+The `examples/` directory contains runnable Python scripts that are validated in CI. Example scripts must remain self-contained and use `tempfile.TemporaryDirectory` for cleanup.
+
+Jupyter notebooks in `examples/notebooks/` are for interactive exploration and are **not** run in CI. They require manual testing when the API changes. This is intentional: notebooks depend on visual output and interactive workflows that don't translate well to automated checks.
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/). Pre-1.0, minor bumps may contain breaking changes. The public API surface is everything in `remote_store.__init__.__all__`.