s3fs-access-grants 0.2.0__tar.gz

s3fs_access_grants-0.2.0/.changeset/README.md

@@ -0,0 +1,11 @@
+# Changesets
+
+This folder is managed by [@changesets/cli](https://github.com/changesets/changesets).
+
+It holds `.md` changeset files — each one describes a change that should appear in the changelog and bump the package version. Add a new changeset with:
+
+```bash
+bun run changeset:add
+```
+
+Changeset files are consumed when `changeset version` runs (in CI) — they update `CHANGELOG.md`, bump `package.json` version, sync that version into `pyproject.toml`/`uv.lock`, and are then deleted.

s3fs_access_grants-0.2.0/.changeset/config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@latest/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "privatePackages": {
+    "version": true,
+    "tag": true
+  }
+}

s3fs_access_grants-0.2.0/.editorconfig

@@ -0,0 +1,20 @@
+root = true
+
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{md,markdown}]
+indent_size = 1
+trim_trailing_whitespace = true
+
+[*.{yml,yaml,json,toml,js,mjs,cjs,ts}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

s3fs_access_grants-0.2.0/.github/actions/setup/action.yaml

@@ -0,0 +1,41 @@
+name: Setup build environment
+description: Setup Bun, Python, install dependencies, and configure caching
+
+inputs:
+  scope:
+    description: '"all" installs everything; "js" skips Python/uv (for jobs that only need JS tooling)'
+    required: false
+    default: all
+
+# Set an empty permissions block to enforce least privilege
+permissions: {}
+
+runs:
+  using: composite
+
+  steps:
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+      with:
+        bun-version: 1.3.14
+
+    - name: Install uv
+      if: inputs.scope == 'all'
+      uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      with:
+        version: "0.11.23"
+        enable-cache: true
+
+    - name: Install Python
+      if: inputs.scope == 'all'
+      shell: bash
+      run: uv python install
+
+    - name: Install JS dependencies
+      shell: bash
+      run: bun install --frozen-lockfile --ignore-scripts
+
+    - name: Install Python dependencies
+      if: inputs.scope == 'all'
+      shell: bash
+      run: uv sync --frozen

s3fs_access_grants-0.2.0/.github/workflows/lint-and-test.yaml

@@ -0,0 +1,71 @@
+name: lint-and-test
+
+# Prevent multiple workflows from running simultaneously
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Set minimal permissions for security
+permissions:
+  contents: read
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup
+
+      - name: Check code
+        run: bun run check
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup
+
+      - name: Run tests
+        run: bun run test
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+  check-pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup
+        with:
+          scope: js
+
+      - name: Check PR title
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: echo "$PR_TITLE" | bunx commitlint

s3fs_access_grants-0.2.0/.github/workflows/release.yaml

@@ -0,0 +1,70 @@
+name: release
+
+on:
+  push:
+    branches: [main]
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # changesets/action needs contents:write (push the version branch) and
+    # pull-requests:write (open the "version packages" PR) via the default
+    # GITHUB_TOKEN — this works because the repo allows Actions to create PRs.
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      published: ${{ steps.changesets.outputs.published }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - uses: ./.github/actions/setup
+
+      # While changesets are pending, opens/updates the "version packages" PR
+      # and does nothing else. Once that PR merges, the changeset files are gone,
+      # so this run instead executes `publish` (changeset tag) and reports
+      # published=true. NOTE: a routine push to main with no pending changesets
+      # ALSO has no changeset files, so it takes the same branch — the publish
+      # job below is therefore made idempotent (skip-existing) so it can only
+      # ever upload a genuinely new version.
+      - id: changesets
+        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
+        with:
+          version: node scripts/ci-bump-versions.js
+          publish: bunx changeset tag
+          title: "chore: version packages"
+          commit: "chore: version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: release
+    if: needs.release.outputs.published == 'true'
+    runs-on: ubuntu-latest
+    # id-token:write is for PyPI trusted publishing (OIDC); scoped to this job
+    # so the changesets job above runs with no token-minting permission.
+    permissions:
+      contents: read
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - uses: ./.github/actions/setup
+
+      - name: Build distribution
+        run: uv build
+
+      # Trusted publishing (OIDC): no API token. Configure a PyPI publisher
+      # for this repo + the "pypi" environment first.
+      # skip-existing makes this a no-op when the version is already on PyPI, so
+      # only a real version bump (from a merged version-packages PR) publishes.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          skip-existing: true

s3fs_access_grants-0.2.0/.gitignore

@@ -0,0 +1,30 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Test / coverage artifacts
+.pytest_cache/
+.ruff_cache/
+.ty_cache/
+.coverage
+coverage.xml
+htmlcov/
+test-results.xml
+test-report.html
+
+# Node / changesets tooling
+node_modules/
+
+# OS / editor
+.DS_Store
+
+# direnv (local env pinning; may resolve secrets)
+.envrc
+.direnv/

s3fs_access_grants-0.2.0/.python-version

@@ -0,0 +1 @@
+3.14

s3fs_access_grants-0.2.0/AGENTS.md

@@ -0,0 +1,157 @@
+# AGENTS.md
+
+> Instructions for AI coding assistants working on this project.
+>
+> **Note**: `CLAUDE.md` is a symlink to this file. Edit `AGENTS.md`; both reflect the change.
+
+## Purpose
+
+`s3fs-access-grants` is a published library that makes [S3 Access Grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants.html)
+transparent to [fsspec](https://filesystem-spec.readthedocs.io/) / [s3fs](https://s3fs.readthedocs.io/).
+`register()` installs `ScopedS3FileSystem` for `s3://`; every fsspec consumer
+(pandas, polars, universal-pathlib, `fsspec.open`) then routes each call through
+a credential scoped to the matching grant.
+
+All code lives in `src/s3fs_access_grants/`:
+
+- `__init__.py` — public API. Exposes exactly three names: `register()` (the only
+  entry point — resolves account/region via the private `_resolve_account_id` /
+  `_resolve_region`, then registers the handler bound to those values via
+  `functools.partial`; returns `None`), `ScopedS3FileSystem` (for advanced/manual
+  construction; requires `grants_account_id`/`grants_region`), and
+  `CrossScopeCopyError`. **No AWS I/O on import** — registration is explicit.
+- `filesystem.py` — the filesystem itself: `ScopedS3FileSystem` (the s3fs
+  subclass), the `enumerate_scopes` helper (module-internal: called by both
+  `register()` and the FS constructor; not in `__all__`), longest-prefix routing,
+  per-scope auto-refreshing clients, and the cross-scope copy guard. There are no
+  override globals: resolved values are bound into the handler at registration
+  time, not stashed.
+
+Imports are always absolute (`from s3fs_access_grants.filesystem import ...`),
+never relative, and import individual names, not the module.
+
+See [README.md](./README.md) for end-to-end behaviour.
+
+## Tech stack
+
+- Python 3.11+ (dev interpreter pinned to 3.14 via `.python-version`)
+- uv (package + venv management), bun (task runner + changesets/lefthook tooling)
+- boto3 / aiobotocore (AWS), s3fs + fsspec (filesystem layer)
+- ruff (lint + format), ty (type check), pytest (test)
+- hatchling (build backend), changesets (release/version management)
+
+## Essential commands
+
+Use `bun` commands, not raw tool invocations:
+
+```bash
+bun install          # uv sync + lefthook install
+bun run check        # lefthook pre-commit on all files (ruff, ty, editorconfig)
+bun run test         # pytest with inline coverage (term-missing)
+bun run build        # uv build (wheel + sdist)
+uv run pytest tests/test_filesystem.py   # single test file
+uv build && uvx twine check dist/*       # verify the package is publishable
+```
+
+`bun run check` runs lefthook's `pre-commit`, whose per-tool globs operate on
+`{staged_files}`. **Stage your changes (`git add -A`) before running it** — new,
+unstaged files are invisible to ruff/ty/editorconfig and produce a false-green
+that pre-commit will reject at commit time.
+
+## Development workflow
+
+1. **Read** the existing code in `filesystem.py` before changing it. Match the
+   style you find there.
+2. **Implement** the smallest change that does the job. No abstractions for
+   hypothetical future needs.
+3. **Test** — add/adjust tests, run `bun run test`.
+4. **Verify** — `git add -A`, then `bun run check` → `bun run test`. Fix every
+   issue.
+5. **Changeset** — for any user-facing change, `bun run changeset:add` (`patch`
+   for fixes, `minor` for features, `major` for breaking). The summary becomes
+   the CHANGELOG entry. Pure chore/CI changes skip this.
+
+## Python conventions
+
+### Style and typing
+
+- Modern syntax only: `str | None` not `Optional`; `list[str]`/`dict[str, X]`
+  not `List`/`Dict`; f-strings not `%`/`.format()`.
+- Annotate every function's parameters and return type. Return concrete types
+  (`list[X]`), accept abstract ones (`Sequence[X]`) only where it broadens usable
+  input.
+- Module-level logger: `logger = logging.getLogger(__name__)`. Use `%s`/`%r`
+  formatting in log calls, not f-strings, so formatting is deferred.
+- Google-style docstrings on public functions/classes/methods. First line is an
+  imperative summary of *what*, not *how*. Skip `Args`/`Returns` that merely echo
+  the signature. `_`-prefixed helpers get a one-liner at most. No docstrings in
+  test bodies (file-level only).
+- Imports at the top of the file, always.
+
+### Error handling
+
+- Hard-fail: raise, don't return error dicts or result objects.
+- Catch specific exception types, not bare `except`. Use `raise ... from e` to
+  preserve the chain. Broad suppression is confined to one place: the
+  best-effort teardown in `_close_scopes` uses `contextlib.suppress(Exception)`
+  so a failing client close can't abort the rest of the cleanup.
+
+### Tooling compliance
+
+- `ruff` and `ty` must both pass with zero warnings before commit.
+
+### Documented exceptions (this is a library on top of s3fs internals)
+
+The general rule is **no suppressions and no `Any`** — fix the underlying issue.
+This project has a few unavoidable, deliberate exceptions, each carrying an
+inline comment explaining why. Do not remove them, and match the pattern if you
+add genuinely analogous code:
+
+- **`# noqa: SLF001`** on the calls into `S3FileSystem._call_s3` / `_iterdir` and
+  on `session._credentials`. The entire design is driving s3fs/aiobotocore
+  internals; the docstring at the top of `filesystem.py` documents the seam.
+- **`# ty: ignore[invalid-argument-type]`** on the `_ClientOverride(...)`
+  arguments. The proxy is a structural stand-in for the filesystem; ty can't see
+  the duck-typing.
+- **`Any`** for the per-scope client dict — aiobotocore clients are untyped.
+- **`_SCOPE_CACHE`** — a module-level dict caching the grant routing table per
+  `(account, region)`. It's a process-wide perf cache (enumeration is
+  identity-global), not state-passing, and the one place module-level mutable
+  state is allowed. `register()` binds account/region into the handler via
+  `functools.partial`, so there are deliberately **no** override globals.
+
+Anything beyond these requires a comment justifying it. Don't reach for a new
+suppression to make a check pass — fix the code first.
+
+### Compatibility seam
+
+`ScopedS3FileSystem` depends on `s3fs` internals (`_call_s3` and `_iterdir`
+resolving their client via `get_s3()`). The module docstring records the exact
+versions it was validated against. **On any `s3fs` bump, re-verify that seam**
+and update the docstring + the README compatibility note.
+
+## Testing
+
+- Mirror `src/` layout under `tests/`.
+- Prefer inline data and pure-logic tests. The routing logic (`_parse_grant`,
+  `_scope_for`, longest-prefix ordering) is testable without AWS — keep it that
+  way; use a `SimpleNamespace` stand-in rather than constructing a real
+  filesystem (which makes live AWS calls).
+- Mock external services (boto3/aiobotocore); never hit real AWS in tests.
+- Naming: `test_{behavior}` inside `class Test{Unit}:`. Plain `assert`,
+  `pytest.raises` for exceptions. One behavior per test. `_make_{object}()` for
+  builders.
+
+## Non-negotiable rules
+
+- **Use `bun` commands** for check/test/build — not raw tool invocations.
+- **Conventional commits** (commitlint-enforced): `feat:`, `fix:`, `docs:`,
+  `refactor:`, `test:`, `chore:`.
+- **No secrets committed**: never commit `.env`, API keys, AWS credentials, or
+  account-specific connection strings.
+- **No AI authorship anywhere**: in commit messages, PRs, or any text, never
+  refer to yourself as an assistant / Claude / AI, and never add "generated by"
+  or "co-authored by AI" lines. Write as a human developer would.
+- **Releases go through changesets**: never hand-edit the version in
+  `pyproject.toml` / `package.json`. CI bumps it from changeset files via
+  `scripts/ci-bump-versions.js` and publishes to PyPI.

s3fs_access_grants-0.2.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# s3fs-access-grants
+
+## 0.2.0
+
+### Minor Changes
+
+- f497575: First version: transparent S3 Access Grants for fsspec/s3fs. Call `register()`
+  once and every fsspec consumer (pandas, polars, universal-pathlib, `fsspec.open`)
+  routes each `s3://` call through a credential scoped to the matching grant, with
+  no Access Grants logic in application code.
+
+### Patch Changes
+
+- bfa95f3: Widen dependency bounds: `s3fs`/`fsspec` to `>=2026,<2027`, `boto3` to
+  `>=1.34,<2`. Add `aiobotocore>=2.22,<4` as a direct dependency (it is imported
+  directly) and drop the unused `aioboto3`.
+- 72648d6: Fix `register()` breaking URL-based reads (e.g. `pandas.read_json("s3://...")`).
+  It registered a `functools.partial`, but fsspec resolves `s3://` URLs by calling
+  classmethods (`_get_kwargs_from_urls`, `_strip_protocol`, ...) on the registered
+  object, which a partial lacks. Register a dynamically-created `ScopedS3FileSystem`
+  subclass instead, with the resolved account/region as class-level defaults.

s3fs_access_grants-0.2.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

s3fs_access_grants-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josep Arús Pous
+
+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.

s3fs_access_grants-0.2.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: s3fs-access-grants
+Version: 0.2.0
+Summary: Transparent S3 Access Grants for fsspec/s3fs — per-grant scoped credentials, no Access Grants logic in application code.
+Project-URL: repository, https://github.com/undeadpixel/s3fs-access-grants
+Author: Josep Arus Pous
+License-Expression: MIT
+License-File: LICENSE
+Keywords: access-grants,aws,fsspec,s3,s3control,s3fs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Filesystems
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiobotocore<4,>=2.22
+Requires-Dist: boto3<2,>=1.34
+Requires-Dist: fsspec<2027,>=2026
+Requires-Dist: s3fs<2027,>=2026
+Description-Content-Type: text/markdown
+
+# s3fs-access-grants
+
+Transparent [S3 Access Grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants.html)
+for [fsspec](https://filesystem-spec.readthedocs.io/) / [s3fs](https://s3fs.readthedocs.io/).
+
+Register the implementation for `s3://` once and every fsspec consumer —
+`pandas`, `polars`, `universal-pathlib`, `fsspec.open`, ... — routes each call
+through a credential scoped to the matching grant. No Access Grants logic leaks
+into application code.
+
+## How it works
+
+`ScopedS3FileSystem` subclasses `s3fs.S3FileSystem`. On construction it
+enumerates the caller's grants (`ListCallerAccessGrants`) and builds a
+longest-prefix routing table. Each S3 operation is matched to a grant scope and
+served by a per-scope `aiobotocore` client whose credentials come from
+`GetDataAccess` and auto-refresh on expiry. Calls that match no grant fall
+through to the default IAM client (fail-closed), and cross-scope copies are
+rejected.
+
+If the caller has no grants (or no permission to list them), `register()`
+installs nothing and plain `s3fs` handles `s3://` with zero added overhead.
+
+## Install
+
+```bash
+pip install s3fs-access-grants
+# or
+uv add s3fs-access-grants
+```
+
+## Usage
+
+Registration is explicit — importing the package does no AWS I/O.
+
+```python
+import s3fs_access_grants
+
+# Install the s3:// handler for the calling identity's grants.
+s3fs_access_grants.register()
+
+import polars as pl
+df = pl.read_parquet("s3://bucket/teamA/data.parquet")  # scoped automatically
+```
+
+Pass the grants-instance account/region explicitly (e.g. in a notebook, or when
+the grants instance lives in a different account than your role):
+
+```python
+import s3fs_access_grants
+
+s3fs_access_grants.register(account_id="767546672094", region="eu-west-1")
+```
+
+`register()` is the only entry point and returns nothing — it's a one-time setup
+call. It resolves the account/region, then binds them into the handler it
+registers, so a later argless `fsspec.filesystem("s3")` (what pandas / polars use
+under the hood) builds the filesystem with the right values. After calling it,
+just use fsspec / pandas / polars as normal.
+
+### Configuration
+
+`register()` resolves the grants-instance account and region in this order:
+
+| Setting    | Resolution order                                                |
+| ---------- | --------------------------------------------------------------- |
+| Account ID | explicit arg → `S3FS_ACCESS_GRANTS_ACCOUNT_ID` → STS caller      |
+| Region     | explicit arg → `S3FS_ACCESS_GRANTS_REGION` → session default     |
+
+The grants instance may live in a different account than the caller's role, so
+the explicit arg / env is authoritative; the STS caller account is only a
+same-account fallback.
+
+### Advanced: manual construction
+
+`register()` covers the common case. To build a scoped filesystem by hand —
+e.g. pointing at a different grants account without touching the global s3://
+registration — construct `ScopedS3FileSystem` directly:
+
+```python
+from s3fs_access_grants import ScopedS3FileSystem
+
+fs = ScopedS3FileSystem(grants_account_id="767546672094", grants_region="eu-west-1")
+```
+
+## Compatibility
+
+This subclass depends on `s3fs` internals (`_call_s3` and `_iterdir` resolving
+their client via `get_s3()`). Validated against s3fs 2026.6.0 / aiobotocore
+2.25.1. Re-check on any `s3fs` major bump.
+
+## Development
+
+```bash
+bun install          # installs JS tooling + runs uv sync + lefthook install
+bun run check        # lint + typecheck (ruff, ty, editorconfig)
+bun run test         # pytest with coverage
+bun run build        # uv build (wheel + sdist)
+```
+
+Releases are managed with [changesets](https://github.com/changesets/changesets):
+add one with `bun run changeset:add`, and merging the generated "version
+packages" PR bumps the version, syncs it into `pyproject.toml`, and publishes to
+PyPI.
+
+## License
+
+MIT