sheetdiff 0.1.0__tar.gz

sheetdiff-0.1.0/LICENSE

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

sheetdiff-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: sheetdiff
+Version: 0.1.0
+Summary: Concise spreadsheet diff utility (CSV/XLSX) with an optional GitHub/VS Code-style web UI
+Author-email: Muhammad Umer <muhammadumer0266@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Muhammad Umer
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/muhammadumer0266/xl-diff
+Project-URL: Repository, https://github.com/muhammadumer0266/xl-diff
+Project-URL: Issues, https://github.com/muhammadumer0266/xl-diff/issues
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: openpyxl>=3.0
+Provides-Extra: web
+Requires-Dist: flask>=2.0; extra == "web"
+Provides-Extra: remote
+Requires-Dist: fsspec>=2023.1; extra == "remote"
+Requires-Dist: s3fs>=2023.1; extra == "remote"
+Requires-Dist: adlfs>=2023.1; extra == "remote"
+Provides-Extra: all
+Requires-Dist: sheetdiff[remote,web]; extra == "all"
+Dynamic: license-file
+
+
+# xl-diff (sheetdiff)
+
+Minimal, efficient spreadsheet diff tool. Load CSV/XLSX and produce unified +/- row and cell diffs.
+
+## Run locally from a clone (web UI)
+
+If you just want to clone the repo and use the web UI on your own machine, without publishing to PyPI:
+
+```bash
+git clone https://github.com/muhammadumer0266/xl-diff.git
+cd xl-diff
+
+# Create and activate a virtualenv
+python -m venv .venv
+# macOS/Linux:
+source .venv/bin/activate
+# Windows (PowerShell):
+.venv\Scripts\Activate.ps1
+
+# Install the package in editable mode with the web extra
+pip install -e ".[web]"
+
+# Start the web server
+xldiff-web
+```
+
+Then open http://localhost:5000, upload two spreadsheets (optionally a key column), and view a GitHub-style row/cell diff (green = added, red = removed, yellow = modified with old value struck through above the new one).
+
+The pure-Python (pandas-based) diff engine works out of the box after `pip install -e ".[web]"`. If you also want the faster Rust-backed engine, additionally run `maturin develop --release` (see "Building the Rust extension" below) before starting `xldiff-web`.
+
+## Install from PyPI (distributed as `sheetdiff`)
+
+```
+pip install sheetdiff
+```
+
+Quick CLI
+
+```
+python -m sheetdiff.cli left.xlsx right.xlsx --key id
+```
+
+Web UI (GitHub-style diff viewer)
+
+```
+pip install sheetdiff[web]
+xldiff-web
+```
+
+Open http://localhost:5000, upload two spreadsheets (optionally a key column), and view a GitHub-style row/cell diff (green = added, red = removed, yellow = modified with old value struck through above the new one).
+
+Remote storage (S3, MinIO, Cloudflare R2, Garage, Azure Blob)
+
+```
+pip install sheetdiff[remote]
+sheetdiff s3://my-bucket/left.xlsx s3://my-bucket/right.xlsx --key id
+```
+
+Files can also be referenced by URI in the web UI (each row accepts an upload *or* a URI) and from the Python API via `sheetdiff.resolve_source`. Credentials and per-backend endpoints are configured once via environment variables, never through the web form — see [docs/REMOTE_STORAGE.md](docs/REMOTE_STORAGE.md) for the full list, plus how to configure upload/remote size limits (`SHEETDIFF_MAX_UPLOAD_MB`, `SHEETDIFF_MAX_REMOTE_MB`, `SHEETDIFF_MAX_FILES`).
+
+Python API
+
+```
+from sheetdiff.core import diff_sheets, format_unified
+
+changes = diff_sheets('left.csv','right.csv', key='id')
+print(format_unified(changes))
+```
+
+Functions
+
+- `diff_sheets(left, right, key=None, sheet_name=None)` — compare two files; if `key` provided, rows are matched by that column, otherwise by position. Returns list of tuples `(type, row_key_or_index, column, old, new)`.
+- `format_unified(changes)` — render a compact unified +/- text view.
+
+Integration notes
+
+- For web backends (Django/Celery), call `diff_sheets` or `compare_workbooks` inside a worker and serialize `changes` to JSON for paginated display.
+- The package will prefer a Rust-backed binary extension `xl_diff` when available (faster, memory-efficient). If the Rust extension is not installed, the pure-Python fallback (`pandas` based) is used.
+- For very large files implement the Rust core (see `RUST_INTEGRATION.md`) and build wheels via `maturin` for best performance.
+
+# xl-diff
+
+[![CI](https://github.com/muhammadumer0266/xl-diff/actions/workflows/CI.yml/badge.svg)](https://github.com/muhammadumer0266/xl-diff/actions/workflows/CI.yml)
+[![crates.io](https://img.shields.io/crates/v/xl_diff.svg)](https://crates.io/crates/xl_diff)
+[![PyPI](https://img.shields.io/pypi/v/sheetdiff.svg)](https://pypi.org/project/sheetdiff/)
+[![Language](https://img.shields.io/badge/Language-Rust%20%2F%20Python-orange.svg)](https://www.rust-lang.org/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+xl-diff is a high-performance, memory-safe Excel comparison engine written in Rust and exposed as a Python extension via PyO3. It is designed to integrate into Django/Celery pipelines and produce cell-level semantic diffs between spreadsheet versions.
+
+Features
+- Fast, zero-copy reading of XLSX using `calamine`.
+- Parallel diff computation using `rayon`.
+- Row alignment using an optional key column or positional fallback.
+- Python bindings (PyO3) for seamless integration.
+- Cross-platform packaging with `maturin` and GitHub Actions.
+
+## Building the Rust extension
+
+The package prefers a Rust-backed binary extension (`xl_diff`, faster and more memory-efficient) when available, falling back to the pure-Python implementation otherwise. To build it in-place inside your virtualenv:
+
+```bash
+pip install maturin
+maturin develop --release
+```
+
+Python usage
+
+```python
+import xl_diff
+
+# List sheets
+sheets = xl_diff.get_sheet_names("/path/to/file.xlsx")
+
+# Diff two sheets by key column 0
+deltas = xl_diff.diff_sheets(
+    "/path/to/old.xlsx",
+    "Sheet1",
+    "/path/to/new.xlsx",
+    "Sheet1",
+    0,
+)
+
+for d in deltas:
+    print(d.row_idx_old, d.row_idx_new, d.col_idx, d.status, d.old_value, d.new_value)
+```
+
+Badge & CI
+
+This repository includes GitHub Actions workflows to build manylinux/musllinux and wheels for Windows/macOS, along with an sdist job. The CI badge above links to the main workflow.
+
+Contributing
+
+Please open issues for bugs and feature requests. Pull requests should target the `main` branch; the `issue/traceability-phase2` branch contains traceability and test improvements.
+
+License
+
+MIT

sheetdiff-0.1.0/README.md

@@ -0,0 +1,139 @@
+
+# xl-diff (sheetdiff)
+
+Minimal, efficient spreadsheet diff tool. Load CSV/XLSX and produce unified +/- row and cell diffs.
+
+## Run locally from a clone (web UI)
+
+If you just want to clone the repo and use the web UI on your own machine, without publishing to PyPI:
+
+```bash
+git clone https://github.com/muhammadumer0266/xl-diff.git
+cd xl-diff
+
+# Create and activate a virtualenv
+python -m venv .venv
+# macOS/Linux:
+source .venv/bin/activate
+# Windows (PowerShell):
+.venv\Scripts\Activate.ps1
+
+# Install the package in editable mode with the web extra
+pip install -e ".[web]"
+
+# Start the web server
+xldiff-web
+```
+
+Then open http://localhost:5000, upload two spreadsheets (optionally a key column), and view a GitHub-style row/cell diff (green = added, red = removed, yellow = modified with old value struck through above the new one).
+
+The pure-Python (pandas-based) diff engine works out of the box after `pip install -e ".[web]"`. If you also want the faster Rust-backed engine, additionally run `maturin develop --release` (see "Building the Rust extension" below) before starting `xldiff-web`.
+
+## Install from PyPI (distributed as `sheetdiff`)
+
+```
+pip install sheetdiff
+```
+
+Quick CLI
+
+```
+python -m sheetdiff.cli left.xlsx right.xlsx --key id
+```
+
+Web UI (GitHub-style diff viewer)
+
+```
+pip install sheetdiff[web]
+xldiff-web
+```
+
+Open http://localhost:5000, upload two spreadsheets (optionally a key column), and view a GitHub-style row/cell diff (green = added, red = removed, yellow = modified with old value struck through above the new one).
+
+Remote storage (S3, MinIO, Cloudflare R2, Garage, Azure Blob)
+
+```
+pip install sheetdiff[remote]
+sheetdiff s3://my-bucket/left.xlsx s3://my-bucket/right.xlsx --key id
+```
+
+Files can also be referenced by URI in the web UI (each row accepts an upload *or* a URI) and from the Python API via `sheetdiff.resolve_source`. Credentials and per-backend endpoints are configured once via environment variables, never through the web form — see [docs/REMOTE_STORAGE.md](docs/REMOTE_STORAGE.md) for the full list, plus how to configure upload/remote size limits (`SHEETDIFF_MAX_UPLOAD_MB`, `SHEETDIFF_MAX_REMOTE_MB`, `SHEETDIFF_MAX_FILES`).
+
+Python API
+
+```
+from sheetdiff.core import diff_sheets, format_unified
+
+changes = diff_sheets('left.csv','right.csv', key='id')
+print(format_unified(changes))
+```
+
+Functions
+
+- `diff_sheets(left, right, key=None, sheet_name=None)` — compare two files; if `key` provided, rows are matched by that column, otherwise by position. Returns list of tuples `(type, row_key_or_index, column, old, new)`.
+- `format_unified(changes)` — render a compact unified +/- text view.
+
+Integration notes
+
+- For web backends (Django/Celery), call `diff_sheets` or `compare_workbooks` inside a worker and serialize `changes` to JSON for paginated display.
+- The package will prefer a Rust-backed binary extension `xl_diff` when available (faster, memory-efficient). If the Rust extension is not installed, the pure-Python fallback (`pandas` based) is used.
+- For very large files implement the Rust core (see `RUST_INTEGRATION.md`) and build wheels via `maturin` for best performance.
+
+# xl-diff
+
+[![CI](https://github.com/muhammadumer0266/xl-diff/actions/workflows/CI.yml/badge.svg)](https://github.com/muhammadumer0266/xl-diff/actions/workflows/CI.yml)
+[![crates.io](https://img.shields.io/crates/v/xl_diff.svg)](https://crates.io/crates/xl_diff)
+[![PyPI](https://img.shields.io/pypi/v/sheetdiff.svg)](https://pypi.org/project/sheetdiff/)
+[![Language](https://img.shields.io/badge/Language-Rust%20%2F%20Python-orange.svg)](https://www.rust-lang.org/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+xl-diff is a high-performance, memory-safe Excel comparison engine written in Rust and exposed as a Python extension via PyO3. It is designed to integrate into Django/Celery pipelines and produce cell-level semantic diffs between spreadsheet versions.
+
+Features
+- Fast, zero-copy reading of XLSX using `calamine`.
+- Parallel diff computation using `rayon`.
+- Row alignment using an optional key column or positional fallback.
+- Python bindings (PyO3) for seamless integration.
+- Cross-platform packaging with `maturin` and GitHub Actions.
+
+## Building the Rust extension
+
+The package prefers a Rust-backed binary extension (`xl_diff`, faster and more memory-efficient) when available, falling back to the pure-Python implementation otherwise. To build it in-place inside your virtualenv:
+
+```bash
+pip install maturin
+maturin develop --release
+```
+
+Python usage
+
+```python
+import xl_diff
+
+# List sheets
+sheets = xl_diff.get_sheet_names("/path/to/file.xlsx")
+
+# Diff two sheets by key column 0
+deltas = xl_diff.diff_sheets(
+    "/path/to/old.xlsx",
+    "Sheet1",
+    "/path/to/new.xlsx",
+    "Sheet1",
+    0,
+)
+
+for d in deltas:
+    print(d.row_idx_old, d.row_idx_new, d.col_idx, d.status, d.old_value, d.new_value)
+```
+
+Badge & CI
+
+This repository includes GitHub Actions workflows to build manylinux/musllinux and wheels for Windows/macOS, along with an sdist job. The CI badge above links to the main workflow.
+
+Contributing
+
+Please open issues for bugs and feature requests. Pull requests should target the `main` branch; the `issue/traceability-phase2` branch contains traceability and test improvements.
+
+License
+
+MIT

sheetdiff-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sheetdiff"
+version = "0.1.0"
+description = "Concise spreadsheet diff utility (CSV/XLSX) with an optional GitHub/VS Code-style web UI"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [ { name = "Muhammad Umer", email = "muhammadumer0266@gmail.com" } ]
+license = { file = "LICENSE" }
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business",
+    "Topic :: Utilities",
+]
+dependencies = ["pandas>=1.5", "openpyxl>=3.0"]
+
+[project.optional-dependencies]
+web = ["flask>=2.0"]
+remote = ["fsspec>=2023.1", "s3fs>=2023.1", "adlfs>=2023.1"]
+all = ["sheetdiff[web,remote]"]
+
+[project.urls]
+Homepage = "https://github.com/muhammadumer0266/xl-diff"
+Repository = "https://github.com/muhammadumer0266/xl-diff"
+Issues = "https://github.com/muhammadumer0266/xl-diff/issues"
+
+[project.scripts]
+xldiff-web = "sheetdiff.webapp:main"
+
+[tool.setuptools.packages.find]
+include = ["sheetdiff", "sheetdiff.*"]
+
+[tool.setuptools.package-data]
+sheetdiff = ["templates/*.html"]

sheetdiff-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sheetdiff-0.1.0/sheetdiff/__init__.py

@@ -0,0 +1,8 @@
+from .core import diff_sheets, format_unified, diff_rows_full, diff_multi_grid, compare_workbooks
+from . import config
+from .storage import resolve as resolve_source, resolve_many as resolve_sources, StorageError
+
+__all__ = [
+    "diff_sheets", "format_unified", "diff_rows_full", "diff_multi_grid", "compare_workbooks",
+    "config", "resolve_source", "resolve_sources", "StorageError",
+]

sheetdiff-0.1.0/sheetdiff/cli.py

@@ -0,0 +1,42 @@
+import argparse
+import sys
+import tempfile
+
+from . import config, storage
+from .core import diff_sheets, format_unified, diff_workbook, format_workbook
+
+def main():
+    p = argparse.ArgumentParser(prog="sheetdiff")
+    p.add_argument("left", help="local path or remote URI (s3://, minio://, r2://, garage://, az://)")
+    p.add_argument("right", help="local path or remote URI (s3://, minio://, r2://, garage://, az://)")
+    p.add_argument("--key", help="column name to use as row key")
+    p.add_argument("--sheet", help="sheet name for Excel files")
+    p.add_argument("--all-sheets", action="store_true", help="compare all sheets in workbooks")
+    p.add_argument(
+        "--max-remote-mb", type=int, default=None,
+        help=f"override the remote download size cap (default: {config.MAX_REMOTE_MB} MB, "
+             "also settable via SHEETDIFF_MAX_REMOTE_MB)",
+    )
+    args = p.parse_args()
+
+    max_bytes = args.max_remote_mb * 1024 * 1024 if args.max_remote_mb else None
+
+    with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as tmp:
+        try:
+            left_path = storage.resolve(args.left, tmp, max_bytes=max_bytes)
+            right_path = storage.resolve(args.right, tmp, max_bytes=max_bytes)
+        except storage.StorageError as e:
+            print(f"error: {e}", file=sys.stderr)
+            raise SystemExit(1)
+
+        if args.all_sheets:
+            from .core import compare_workbooks
+            wb = compare_workbooks(left_path, right_path, key=args.key)
+            print(format_workbook(wb))
+        else:
+            changes = diff_sheets(left_path, right_path, key=args.key, sheet_name=args.sheet)
+            print(format_unified(changes))
+
+
+if __name__ == "__main__":
+    main()

sheetdiff-0.1.0/sheetdiff/config.py

@@ -0,0 +1,127 @@
+"""Central, environment-driven configuration for sheetdiff.
+
+Every knob here can be overridden with an environment variable so a
+deployment can tune limits and remote-storage credentials without touching
+code. Nothing here reads a hardcoded secret — credentials only ever come
+from the environment (or a `.env` loaded by the process before start-up),
+never from user-submitted form fields, so a web UI cannot be used to smuggle
+credentials for a backend the operator didn't configure.
+"""
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or raw.strip() == "":
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        raise ValueError(f"{name}={raw!r} is not a valid integer") from None
+    if value <= 0:
+        raise ValueError(f"{name}={raw!r} must be a positive integer")
+    return value
+
+
+def _env_list(name: str, default: str) -> list:
+    raw = os.environ.get(name, default)
+    return [x.strip().lower() for x in raw.split(",") if x.strip()]
+
+
+# --- Upload / download size limits -----------------------------------------
+# All expressed in MB for readability at the env-var layer; converted to
+# bytes for use. Change per-deployment via env vars, e.g.:
+#   SHEETDIFF_MAX_UPLOAD_MB=250
+#   SHEETDIFF_MAX_REMOTE_MB=500
+#   SHEETDIFF_MAX_FILES=6
+MAX_UPLOAD_MB = _env_int("SHEETDIFF_MAX_UPLOAD_MB", 100)
+MAX_REMOTE_MB = _env_int("SHEETDIFF_MAX_REMOTE_MB", MAX_UPLOAD_MB)
+MAX_UPLOAD_BYTES = MAX_UPLOAD_MB * 1024 * 1024
+MAX_REMOTE_BYTES = MAX_REMOTE_MB * 1024 * 1024
+
+# Hard ceiling on how many files can be compared in one request (web UI and
+# CLI --all-sheets multi-file mode), to bound memory/CPU on shared servers.
+MAX_FILES = _env_int("SHEETDIFF_MAX_FILES", 8)
+
+# Network timeouts for remote storage reads (seconds).
+REMOTE_CONNECT_TIMEOUT = _env_int("SHEETDIFF_REMOTE_CONNECT_TIMEOUT", 10)
+REMOTE_READ_TIMEOUT = _env_int("SHEETDIFF_REMOTE_READ_TIMEOUT", 60)
+
+# Which remote URI schemes are enabled at all. Empty by default in the sense
+# that only schemes listed here are ever dispatched to fsspec; anything else
+# (including http/https, to avoid turning the diff endpoint into an SSRF
+# proxy) is rejected outright.
+ALLOWED_REMOTE_SCHEMES = set(
+    _env_list("SHEETDIFF_ALLOWED_SCHEMES", "s3,minio,r2,garage,az,azure,gs")
+)
+
+
+@dataclass
+class BackendConfig:
+    protocol: str  # fsspec protocol, e.g. "s3" or "az"
+    storage_options: Dict[str, str] = field(default_factory=dict)
+
+
+def _s3_backend(scheme: str) -> BackendConfig:
+    prefix = f"SHEETDIFF_STORAGE_{scheme.upper()}_"
+    opts: Dict[str, str] = {}
+    endpoint = os.environ.get(prefix + "ENDPOINT_URL")
+    if endpoint:
+        opts["client_kwargs"] = {"endpoint_url": endpoint}
+    key = os.environ.get(prefix + "KEY") or os.environ.get("AWS_ACCESS_KEY_ID")
+    secret = os.environ.get(prefix + "SECRET") or os.environ.get("AWS_SECRET_ACCESS_KEY")
+    region = os.environ.get(prefix + "REGION") or os.environ.get("AWS_DEFAULT_REGION")
+    if key:
+        opts["key"] = key
+    if secret:
+        opts["secret"] = secret
+    if region:
+        opts.setdefault("client_kwargs", {})["region_name"] = region
+    return BackendConfig(protocol="s3", storage_options=opts)
+
+
+def _azure_backend() -> BackendConfig:
+    prefix = "SHEETDIFF_STORAGE_AZ_"
+    opts: Dict[str, str] = {}
+    conn_str = os.environ.get(prefix + "CONNECTION_STRING")
+    if conn_str:
+        opts["connection_string"] = conn_str
+    else:
+        account = os.environ.get(prefix + "ACCOUNT_NAME")
+        account_key = os.environ.get(prefix + "ACCOUNT_KEY")
+        sas_token = os.environ.get(prefix + "SAS_TOKEN")
+        if account:
+            opts["account_name"] = account
+        if account_key:
+            opts["account_key"] = account_key
+        if sas_token:
+            opts["sas_token"] = sas_token
+    return BackendConfig(protocol="az", storage_options=opts)
+
+
+def _gcs_backend() -> BackendConfig:
+    opts: Dict[str, str] = {}
+    creds = os.environ.get("SHEETDIFF_STORAGE_GS_TOKEN")
+    if creds:
+        opts["token"] = creds
+    return BackendConfig(protocol="gcs", storage_options=opts)
+
+
+def backend_for_scheme(scheme: str) -> Optional[BackendConfig]:
+    """Map a URI scheme (e.g. 'minio', 'r2', 'az') to an fsspec backend.
+
+    Returns None if the scheme isn't recognized/enabled, so callers can
+    reject it instead of silently falling through to some default.
+    """
+    scheme = scheme.lower()
+    if scheme not in ALLOWED_REMOTE_SCHEMES:
+        return None
+    if scheme in ("s3", "minio", "r2", "garage"):
+        return _s3_backend(scheme)
+    if scheme in ("az", "azure"):
+        return _azure_backend()
+    if scheme == "gs":
+        return _gcs_backend()
+    return None