scan-google-sheet 0.1.0__tar.gz

scan_google_sheet-0.1.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.3
+Name: scan-google-sheet
+Version: 0.1.0
+Summary: Read public Google Sheets into Polars LazyFrames — no auth required
+Keywords: polars,google-sheets,csv,dataframe,lazy
+Author: Attica-oss
+Author-email: Attica-oss <g.mounac@outlook.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Dist: duckdb>=1.5.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: polars>=1.39.3
+Requires-Dist: pyarrow>=23.0.1
+Requires-Dist: sqlglot>=30.2.1
+Requires-Python: >=3.13
+Project-URL: Documentation, https://github.com/Attica-oss/scan_google_sheet/blob/main/README.md
+Project-URL: Homepage, https://github.com/Attica-oss/scan_google_sheet
+Project-URL: Issues, https://github.com/Attica-oss/scan_google_sheet/issues
+Project-URL: Repository, https://github.com/Attica-oss/scan_google_sheet
+Description-Content-Type: text/markdown
+
+# read-sheet
+
+Read public Google Sheets into Polars DataFrames and LazyFrames — no auth, no service accounts, no API keys.
+
+[![PyPI](https://img.shields.io/pypi/v/scan-google-sheet)](https://pypi.org/project/scan-google-sheet/)
+[![Python](https://img.shields.io/pypi/pyversions/scan-google-sheet)](https://pypi.org/project/scan-google-sheet/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/Attica-oss/scan_google_sheet/actions/workflows/ci.yml/badge.svg)](https://github.com/Attica-oss/scan_google_sheet/actions/workflows/ci.yml)
+
+---
+
+## Requirements
+
+- Python ≥ 3.13
+- The spreadsheet must be set to **Anyone with the link can view**
+
+---
+
+## Installation
+
+```bash
+pip install scan-google-sheet
+# or
+uv add scan-google-sheet
+```
+
+---
+
+## Quick start
+
+```python
+from scan_google_sheet import read_google_sheet, scan_google_sheet
+```
+
+**Eager — returns a `DataFrame` immediately:**
+
+```python
+df = read_google_sheet("Sheet1", sheet_id="1BxiMVs0XRA5nFMdKvBdBZjgm...")
+```
+
+**Lazy — returns a `LazyFrame`, participates in Polars query optimisation:**
+
+```python
+lf = scan_google_sheet("Sheet1", sheet_id="1BxiMVs0XRA5nFMdKvBdBZjgm...")
+
+df = (
+    lf
+    .filter(pl.col("year") == 2025)
+    .select("vessel", "amount")
+    .collect()
+)
+```
+
+You can also pass a full Google Sheets URL instead of a bare sheet ID:
+
+```python
+df = read_google_sheet(
+    "Sheet1",
+    url="https://docs.google.com/spreadsheets/d/1BxiMVs0.../edit#gid=0",
+)
+```
+
+---
+
+## API
+
+### `read_google_sheet`
+
+```python
+def read_google_sheet(
+    sheet_name: str,
+    sheet_id: str | None = None,
+    url: str | None = None,
+    *,
+    timeout: int = 10,
+    parse_dates: bool = True,
+) -> pl.DataFrame
+```
+
+Fetches the sheet and returns a collected `DataFrame`. Use this when you want the data immediately and do not need lazy evaluation.
+
+### `scan_google_sheet`
+
+```python
+def scan_google_sheet(
+    sheet_name: str,
+    sheet_id: str | None = None,
+    url: str | None = None,
+    *,
+    timeout: int = 10,
+    parse_dates: bool = True,
+    batch_size: int = 1_000,
+) -> pl.LazyFrame
+```
+
+Returns a `LazyFrame` registered via the Polars IO plugin API. Projection pushdown, predicate pushdown, `head()`, and streaming are all supported.
+
+> **Note:** Google Sheets does not support partial HTTP reads. The full sheet is always downloaded in one request. Pushdowns reduce processing cost, not network cost.
+
+**Parameters shared by both functions:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `sheet_name` | `str` | — | Tab name as shown in Google Sheets |
+| `sheet_id` | `str \| None` | `None` | Spreadsheet ID from the URL |
+| `url` | `str \| None` | `None` | Full Google Sheets URL (ID extracted automatically) |
+| `timeout` | `int` | `10` | HTTP timeout in seconds |
+| `parse_dates` | `bool` | `True` | Attempt automatic date/datetime parsing |
+
+Provide either `sheet_id` or `url`, not both.
+
+---
+
+## URL utilities
+
+```python
+from scan_google_sheet import extract_sheet_id, build_gviz_url, from_url
+
+# Extract the sheet ID from any Google Sheets URL
+sheet_id = extract_sheet_id("https://docs.google.com/spreadsheets/d/ABC123/edit")
+# "ABC123"
+
+# Build a gviz CSV export URL from a sheet ID and tab name
+url = build_gviz_url("ABC123", "Sheet1")
+# "https://docs.google.com/spreadsheets/d/ABC123/gviz/tq?tqx=out:csv&sheet=Sheet1"
+
+# Build a gviz URL directly from a full Google Sheets URL
+url = from_url("https://docs.google.com/spreadsheets/d/ABC123/edit", "Sheet1")
+```
+
+---
+
+## Error handling
+
+All exceptions inherit from `ReadSheetError`, so you can catch everything with one handler or branch on specific types:
+
+```python
+from scan_google_sheet import (
+    read_google_sheet,
+    ReadSheetError,
+    SheetFetchError,
+    SheetURLError,
+    SheetParseError,
+    NetworkError,
+    ConfigurationError,
+)
+
+try:
+    df = read_google_sheet("Sheet1", sheet_id="...")
+except ReadSheetError as e:
+    match e:
+        case SheetFetchError() if e.is_auth_error:
+            print("Make the sheet public (Share → Anyone with the link)")
+        case SheetFetchError() if e.is_not_found:
+            print(f"Sheet not found — check the ID: {e.url}")
+        case NetworkError():
+            print(f"No connection: {e.cause}")
+        case SheetURLError(raw=r):
+            print(f"Could not parse URL: {r!r}")
+        case SheetParseError():
+            print(f"CSV parse failed: {e.cause}")
+        case ConfigurationError():
+            print(str(e))
+```
+
+### Exception hierarchy
+
+```
+ReadSheetError
+├── SheetURLError       malformed URL or unextractable sheet ID  (.raw)
+├── SheetFetchError     non-200 HTTP response                    (.url, .status_code)
+│                                                                (.is_auth_error, .is_not_found)
+├── SheetParseError     CSV or Polars parsing failure            (.column)
+├── NetworkError        transport failure, no response received  (.url)
+└── ConfigurationError  invalid argument combination
+```
+
+---
+
+## Making your sheet public
+
+In Google Sheets: **Share → Change to Anyone with the link → Viewer → Done.**
+
+The export URL used by this library (`gviz/tq?tqx=out:csv`) requires the sheet to be publicly readable. No data is ever written.
+
+---
+
+## How it works
+
+```
+Google Sheets URL / ID
+        │
+        ▼
+  build_gviz_url()          constructs the CSV export URL
+        │
+        ▼
+    fetch_raw()             httpx GET with follow_redirects=True
+        │
+        ▼
+  pl.scan_csv()             parsed into a Polars LazyFrame
+        │
+        ▼
+register_io_source()        registered as a Polars IO plugin
+        │
+        ▼
+  LazyFrame / DataFrame     ready for your pipeline
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Attica-oss/scan_google_sheet
+cd scan_google_sheet
+uv sync --group dev
+uv run pytest
+```
+
+Lint and format:
+
+```bash
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+uv run ty check src/
+```
+
+---
+
+## Changelog
+
+### 0.1.0 (2025)
+- Initial release
+- `read_google_sheet` and `scan_google_sheet`
+- Polars IO plugin for lazy evaluation
+- Structured exception hierarchy
+- Full test suite with `pytest-httpx`
+
+---
+
+## License
+
+[MIT](LICENSE) © 2025 Attica-oss

scan_google_sheet-0.1.0/README.md

@@ -0,0 +1,243 @@
+# read-sheet
+
+Read public Google Sheets into Polars DataFrames and LazyFrames — no auth, no service accounts, no API keys.
+
+[![PyPI](https://img.shields.io/pypi/v/scan-google-sheet)](https://pypi.org/project/scan-google-sheet/)
+[![Python](https://img.shields.io/pypi/pyversions/scan-google-sheet)](https://pypi.org/project/scan-google-sheet/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/Attica-oss/scan_google_sheet/actions/workflows/ci.yml/badge.svg)](https://github.com/Attica-oss/scan_google_sheet/actions/workflows/ci.yml)
+
+---
+
+## Requirements
+
+- Python ≥ 3.13
+- The spreadsheet must be set to **Anyone with the link can view**
+
+---
+
+## Installation
+
+```bash
+pip install scan-google-sheet
+# or
+uv add scan-google-sheet
+```
+
+---
+
+## Quick start
+
+```python
+from scan_google_sheet import read_google_sheet, scan_google_sheet
+```
+
+**Eager — returns a `DataFrame` immediately:**
+
+```python
+df = read_google_sheet("Sheet1", sheet_id="1BxiMVs0XRA5nFMdKvBdBZjgm...")
+```
+
+**Lazy — returns a `LazyFrame`, participates in Polars query optimisation:**
+
+```python
+lf = scan_google_sheet("Sheet1", sheet_id="1BxiMVs0XRA5nFMdKvBdBZjgm...")
+
+df = (
+    lf
+    .filter(pl.col("year") == 2025)
+    .select("vessel", "amount")
+    .collect()
+)
+```
+
+You can also pass a full Google Sheets URL instead of a bare sheet ID:
+
+```python
+df = read_google_sheet(
+    "Sheet1",
+    url="https://docs.google.com/spreadsheets/d/1BxiMVs0.../edit#gid=0",
+)
+```
+
+---
+
+## API
+
+### `read_google_sheet`
+
+```python
+def read_google_sheet(
+    sheet_name: str,
+    sheet_id: str | None = None,
+    url: str | None = None,
+    *,
+    timeout: int = 10,
+    parse_dates: bool = True,
+) -> pl.DataFrame
+```
+
+Fetches the sheet and returns a collected `DataFrame`. Use this when you want the data immediately and do not need lazy evaluation.
+
+### `scan_google_sheet`
+
+```python
+def scan_google_sheet(
+    sheet_name: str,
+    sheet_id: str | None = None,
+    url: str | None = None,
+    *,
+    timeout: int = 10,
+    parse_dates: bool = True,
+    batch_size: int = 1_000,
+) -> pl.LazyFrame
+```
+
+Returns a `LazyFrame` registered via the Polars IO plugin API. Projection pushdown, predicate pushdown, `head()`, and streaming are all supported.
+
+> **Note:** Google Sheets does not support partial HTTP reads. The full sheet is always downloaded in one request. Pushdowns reduce processing cost, not network cost.
+
+**Parameters shared by both functions:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `sheet_name` | `str` | — | Tab name as shown in Google Sheets |
+| `sheet_id` | `str \| None` | `None` | Spreadsheet ID from the URL |
+| `url` | `str \| None` | `None` | Full Google Sheets URL (ID extracted automatically) |
+| `timeout` | `int` | `10` | HTTP timeout in seconds |
+| `parse_dates` | `bool` | `True` | Attempt automatic date/datetime parsing |
+
+Provide either `sheet_id` or `url`, not both.
+
+---
+
+## URL utilities
+
+```python
+from scan_google_sheet import extract_sheet_id, build_gviz_url, from_url
+
+# Extract the sheet ID from any Google Sheets URL
+sheet_id = extract_sheet_id("https://docs.google.com/spreadsheets/d/ABC123/edit")
+# "ABC123"
+
+# Build a gviz CSV export URL from a sheet ID and tab name
+url = build_gviz_url("ABC123", "Sheet1")
+# "https://docs.google.com/spreadsheets/d/ABC123/gviz/tq?tqx=out:csv&sheet=Sheet1"
+
+# Build a gviz URL directly from a full Google Sheets URL
+url = from_url("https://docs.google.com/spreadsheets/d/ABC123/edit", "Sheet1")
+```
+
+---
+
+## Error handling
+
+All exceptions inherit from `ReadSheetError`, so you can catch everything with one handler or branch on specific types:
+
+```python
+from scan_google_sheet import (
+    read_google_sheet,
+    ReadSheetError,
+    SheetFetchError,
+    SheetURLError,
+    SheetParseError,
+    NetworkError,
+    ConfigurationError,
+)
+
+try:
+    df = read_google_sheet("Sheet1", sheet_id="...")
+except ReadSheetError as e:
+    match e:
+        case SheetFetchError() if e.is_auth_error:
+            print("Make the sheet public (Share → Anyone with the link)")
+        case SheetFetchError() if e.is_not_found:
+            print(f"Sheet not found — check the ID: {e.url}")
+        case NetworkError():
+            print(f"No connection: {e.cause}")
+        case SheetURLError(raw=r):
+            print(f"Could not parse URL: {r!r}")
+        case SheetParseError():
+            print(f"CSV parse failed: {e.cause}")
+        case ConfigurationError():
+            print(str(e))
+```
+
+### Exception hierarchy
+
+```
+ReadSheetError
+├── SheetURLError       malformed URL or unextractable sheet ID  (.raw)
+├── SheetFetchError     non-200 HTTP response                    (.url, .status_code)
+│                                                                (.is_auth_error, .is_not_found)
+├── SheetParseError     CSV or Polars parsing failure            (.column)
+├── NetworkError        transport failure, no response received  (.url)
+└── ConfigurationError  invalid argument combination
+```
+
+---
+
+## Making your sheet public
+
+In Google Sheets: **Share → Change to Anyone with the link → Viewer → Done.**
+
+The export URL used by this library (`gviz/tq?tqx=out:csv`) requires the sheet to be publicly readable. No data is ever written.
+
+---
+
+## How it works
+
+```
+Google Sheets URL / ID
+        │
+        ▼
+  build_gviz_url()          constructs the CSV export URL
+        │
+        ▼
+    fetch_raw()             httpx GET with follow_redirects=True
+        │
+        ▼
+  pl.scan_csv()             parsed into a Polars LazyFrame
+        │
+        ▼
+register_io_source()        registered as a Polars IO plugin
+        │
+        ▼
+  LazyFrame / DataFrame     ready for your pipeline
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Attica-oss/scan_google_sheet
+cd scan_google_sheet
+uv sync --group dev
+uv run pytest
+```
+
+Lint and format:
+
+```bash
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+uv run ty check src/
+```
+
+---
+
+## Changelog
+
+### 0.1.0 (2025)
+- Initial release
+- `read_google_sheet` and `scan_google_sheet`
+- Polars IO plugin for lazy evaluation
+- Structured exception hierarchy
+- Full test suite with `pytest-httpx`
+
+---
+
+## License
+
+[MIT](LICENSE) © 2025 Attica-oss

scan_google_sheet-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[project]
+name = "scan-google-sheet"
+version = "0.1.0"
+description = "Read public Google Sheets into Polars LazyFrames — no auth required"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Attica-oss", email = "g.mounac@outlook.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "duckdb>=1.5.1",
+    "httpx>=0.28.1",
+    "polars>=1.39.3",
+    "pyarrow>=23.0.1",
+    "sqlglot>=30.2.1",
+]
+keywords = ["polars", "google-sheets", "csv", "dataframe", "lazy"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+  "Typing :: Typed",
+]
+
+
+[project.urls]
+Repository = "https://github.com/Attica-oss/scan_google_sheet"
+Issues = "https://github.com/Attica-oss/scan_google_sheet/issues"
+Documentation = "https://github.com/Attica-oss/scan_google_sheet/blob/main/README.md"
+Homepage = "https://github.com/Attica-oss/scan_google_sheet"
+
+[build-system]
+requires = ["uv_build>=0.9.17,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scan_google_sheet"]
+
+# [build-system]
+# requires = ["hatchling"]
+# build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "marimo>=0.22.0",
+    "pytest>=9.0.2",
+    "pytest-httpx>=0.36.0",
+    "ruff>=0.15.9",
+    "ty>=0.0.28",
+]
+
+
+# ── Ruff ──────────────────────────────────────────────────────────────────────
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+  "E",   # pycodestyle errors
+  "F",   # pyflakes
+  "I",   # isort
+  "UP",  # pyupgrade
+  "B",   # flake8-bugbear
+  "SIM", # flake8-simplify
+  "TID", # flake8-tidy-imports
+  "ANN", # flake8-annotations
+]
+ignore = [
+  "ANN101", # missing type annotation for self
+  "ANN102", # missing type annotation for cls
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["scan_google_sheet"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+# ── ty ────────────────────────────────────────────────────────────────────────
+
+[tool.ty.rules]
+division-by-zero = "error"
+invalid-return-type = "error"
+
+# ── Pytest ────────────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"

scan_google_sheet-0.1.0/src/scan_google_sheet/__init__.py

@@ -0,0 +1,93 @@
+"""read_sheet — Read public Google Sheets into Polars DataFrames."""
+
+import polars as pl
+
+from .exceptions import (
+    ConfigurationError,
+    NetworkError,
+    ReadSheetError,
+    SheetFetchError,
+    SheetParseError,
+    SheetURLError,
+)
+from .fetch import fetch_raw
+from .parse import parse_csv
+from .scan import read_google_sheet, scan_google_sheet
+from .url import build_export_url, build_gviz_url, extract_gid, extract_sheet_id, from_url
+
+__all__ = [
+    # main API
+    "read_google_sheet",
+    "scan_google_sheet",
+    # exceptions
+    "ReadSheetError",
+    "SheetURLError",
+    "SheetFetchError",
+    "SheetParseError",
+    "NetworkError",
+    "ConfigurationError",
+    # url utilities
+    "extract_sheet_id",
+    "extract_gid",
+    "build_export_url",
+    "build_gviz_url",
+    "from_url",
+]
+
+
+def read_sheet(
+    url_or_id: str,
+    *,
+    gid: str | None = None,
+    timeout: int = 30,
+    infer_schema_length: int | None = 100,
+    null_values: list[str] | None = None,
+    try_parse_dates: bool = False,
+    schema_overrides: dict[str, pl.DataType] | None = None,
+) -> pl.DataFrame:
+    """Read a public Google Sheet into a Polars DataFrame.
+
+    Parameters
+    ----------
+    url_or_id:
+        Either a full Google Sheets URL or a bare spreadsheet ID.
+        If a URL is provided, the ``gid`` is extracted automatically
+        unless overridden by the ``gid`` parameter.
+    gid:
+        Tab/sheet index (gid). Overrides any gid found in ``url_or_id``.
+        Defaults to the first sheet if omitted.
+    timeout:
+        HTTP request timeout in seconds.
+    infer_schema_length:
+        Rows used to infer column types. ``None`` = all rows.
+    null_values:
+        Extra strings to treat as null (on top of the built-in defaults).
+    try_parse_dates:
+        Attempt automatic date parsing.
+    schema_overrides:
+        Override inferred dtypes per column.
+
+    Returns
+    -------
+    pl.DataFrame
+
+    Examples
+    --------
+    >>> df = read_sheet("https://docs.google.com/spreadsheets/d/SHEET_ID/edit#gid=0")
+    >>> df = read_sheet("SHEET_ID", gid="123456789")
+    """
+    sheet_id = extract_sheet_id(url_or_id)
+
+    # gid: explicit param wins, then try extracting from URL, then None (first sheet)
+    resolved_gid = gid or extract_gid(url_or_id)
+
+    export_url = build_export_url(sheet_id, resolved_gid)
+    csv_text = fetch_raw(export_url, timeout=timeout)
+
+    return parse_csv(
+        csv_text,
+        infer_schema_length=infer_schema_length,
+        null_values=null_values,
+        try_parse_dates=try_parse_dates,
+        schema_overrides=schema_overrides,
+    )

scan_google_sheet-0.1.0/src/scan_google_sheet/exceptions.py

@@ -0,0 +1,257 @@
+"""Custom exceptions for read-sheet.
+
+Three failure domains, one base:
+
+    ReadSheetError          ← base, always carries optional ``cause``
+    ├── SheetURLError       ← malformed URL or unextractable sheet ID
+    ├── SheetFetchError     ← HTTP / network failure, carries ``url`` + ``status_code``
+    └── SheetParseError     ← CSV or Polars schema/parse failure, carries ``column``
+
+All subclasses preserve the original exception via ``cause`` / ``__cause__``
+so tracebacks remain intact and ``match``/``case`` branches can inspect them.
+"""
+
+from __future__ import annotations
+
+from polars.exceptions import (
+    ColumnNotFoundError,
+    ComputeError,
+    DuplicateError,
+    InvalidOperationError,
+    NoDataError,
+    PolarsError,
+    SchemaError,
+    ShapeError,
+)
+
+__all__ = [
+    "ConfigurationError",
+    "NetworkError",
+    "ReadSheetError",
+    "SheetFetchError",
+    "SheetParseError",
+    "SheetURLError",
+]
+
+
+# ── Base ──────────────────────────────────────────────────────────────────────
+
+
+class ReadSheetError(Exception):
+    """Base exception for all read-sheet errors.
+
+    Every subclass carries an optional ``cause`` that preserves the original
+    exception, making it safe to use inside ``match``/``case`` without losing
+    the underlying traceback.
+
+    Examples:
+        >>> raise ReadSheetError("something went wrong")
+        ReadSheetError('something went wrong')
+
+        >>> try:
+        ...     int("bad")
+        ... except ValueError as e:
+        ...     raise ReadSheetError("unexpected value", cause=e) from e
+    """
+
+    def __init__(self, message: str, *, cause: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.cause = cause
+        if cause is not None:
+            self.__cause__ = cause
+
+    def __repr__(self) -> str:
+        if self.cause:
+            return f"{type(self).__name__}({self.args[0]!r}, cause={self.cause!r})"
+        return f"{type(self).__name__}({self.args[0]!r})"
+
+
+# ── Subclasses ────────────────────────────────────────────────────────────────
+
+
+class SheetURLError(ReadSheetError):
+    """Raised when a Google Sheets URL or ID cannot be parsed.
+
+    Carries the ``raw`` value that failed so callers can log or surface it
+    without reparsing the message string.
+
+    Examples:
+        >>> err = SheetURLError("No sheet ID found", raw="not-a-url")
+        >>> err.raw
+        'not-a-url'
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        raw: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message, cause=cause)
+        self.raw = raw
+
+    def __repr__(self) -> str:
+        parts = [repr(self.args[0])]
+        if self.raw is not None:
+            parts.append(f"raw={self.raw!r}")
+        if self.cause is not None:
+            parts.append(f"cause={self.cause!r}")
+        return f"SheetURLError({', '.join(parts)})"
+
+
+class SheetFetchError(ReadSheetError):
+    """Raised when the HTTP request to Google Sheets fails.
+
+    Carries the ``url`` that was requested and the HTTP ``status_code`` when
+    one is available (``None`` for pure network errors).
+
+    Examples:
+        >>> err = SheetFetchError("Sheet is not public", url="https://...", status_code=401)
+        >>> err.status_code
+        401
+        >>> err.is_auth_error
+        True
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        url: str | None = None,
+        status_code: int | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message, cause=cause)
+        self.url = url
+        self.status_code = status_code
+
+    @property
+    def is_auth_error(self) -> bool:
+        """True when the sheet is not publicly accessible (HTTP 401/403)."""
+        return self.status_code in (401, 403)
+
+    @property
+    def is_not_found(self) -> bool:
+        """True when the sheet ID does not exist (HTTP 404)."""
+        return self.status_code == 404
+
+    def __repr__(self) -> str:
+        parts = [repr(self.args[0])]
+        if self.url is not None:
+            parts.append(f"url={self.url!r}")
+        if self.status_code is not None:
+            parts.append(f"status_code={self.status_code!r}")
+        if self.cause is not None:
+            parts.append(f"cause={self.cause!r}")
+        return f"SheetFetchError({', '.join(parts)})"
+
+
+class SheetParseError(ReadSheetError):
+    """Raised when CSV or Polars parsing fails after a successful fetch.
+
+    Carries the ``column`` name when the failure can be attributed to a
+    specific field, and wraps Polars exceptions via ``from_polars()``.
+
+    Examples:
+        >>> err = SheetParseError("Type mismatch", column="amount")
+        >>> err.column
+        'amount'
+
+        >>> from polars.exceptions import SchemaError
+        >>> err = SheetParseError.from_polars(SchemaError("bad schema"), step="parse_csv")
+        >>> type(err)
+        <class 'SheetParseError'>
+        >>> err.cause
+        SchemaError('bad schema')
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        column: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message, cause=cause)
+        self.column = column
+
+    @classmethod
+    def from_polars(cls, error: PolarsError, step: str) -> SheetParseError:
+        """Wrap a raw Polars exception with step context.
+
+        Args:
+            error: The original Polars exception.
+            step:  Human-readable label for the pipeline step that failed.
+
+        Returns:
+            A ``SheetParseError`` with ``cause`` set to the original error.
+        """
+        return cls(f"{step}: {error}", cause=error)
+
+    def __repr__(self) -> str:
+        parts = [repr(self.args[0])]
+        if self.column is not None:
+            parts.append(f"column={self.column!r}")
+        if self.cause is not None:
+            parts.append(f"cause={self.cause!r}")
+        return f"SheetParseError({', '.join(parts)})"
+
+
+class NetworkError(ReadSheetError):
+    """Raised when a connection or transport-level failure occurs.
+
+    Distinct from ``SheetFetchError`` (which implies a completed HTTP round-trip
+    with a status code). ``NetworkError`` fires when no response is received at
+    all — DNS failure, refused connection, proxy error, etc.
+
+    Examples:
+        >>> err = NetworkError("DNS resolution failed", url="https://docs.google.com/...")
+        >>> err.url
+        'https://docs.google.com/...'
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        url: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message, cause=cause)
+        self.url = url
+
+    def __repr__(self) -> str:
+        parts = [repr(self.args[0])]
+        if self.url is not None:
+            parts.append(f"url={self.url!r}")
+        if self.cause is not None:
+            parts.append(f"cause={self.cause!r}")
+        return f"NetworkError({', '.join(parts)})"
+
+
+class ConfigurationError(ReadSheetError):
+    """Raised when ``scan_google_sheet`` is called with invalid arguments.
+
+    Typically fired when both ``sheet_id`` and ``url`` are provided, or
+    neither is provided.
+
+    Examples:
+        >>> raise ConfigurationError("Provide either sheet_id or url, not both")
+    """
+
+
+# ── Polars → SheetParseError mapping ─────────────────────────────────────────
+
+# Used internally by SheetParseError.from_polars() and parse.py.
+_POLARS_PARSE_ERRORS: frozenset[type[PolarsError]] = frozenset(
+    {
+        SchemaError,
+        ColumnNotFoundError,
+        DuplicateError,
+        ComputeError,
+        InvalidOperationError,
+        ShapeError,
+        NoDataError,
+    }
+)

scan_google_sheet-0.1.0/src/scan_google_sheet/fetch.py

@@ -0,0 +1,60 @@
+"""Fetch CSV data from a public Google Sheets export URL using httpx."""
+
+import httpx
+
+from . import exceptions
+
+
+def fetch_raw(url: str, *, timeout: int = 30, sheet_name: str = "") -> str:
+    """Fetch raw CSV text from a Google Sheets gviz export URL.
+
+    Parameters
+    ----------
+    url:
+        The full gviz CSV export URL (use ``build_gviz_url`` or ``from_url``).
+    timeout:
+        Request timeout in seconds.
+    sheet_name:
+        Used in error messages to identify which sheet failed.
+
+    Returns
+    -------
+    str
+        Raw CSV text.
+
+    Raises
+    ------
+    SheetFetchError
+        On non-200 HTTP status or timeout.
+    NetworkError
+        On connection/transport failure (no response received).
+    """
+    try:
+        response = httpx.get(
+            url,
+            timeout=timeout,
+            follow_redirects=True,
+            headers={"User-Agent": "read-sheet/0.1.0"},
+        )
+    except httpx.TimeoutException as e:
+        raise exceptions.SheetFetchError(
+            f"Request timed out after {timeout} seconds", url=url, cause=e
+        ) from e
+    except httpx.RequestError as e:
+        raise exceptions.NetworkError(f"Network error: {e}", url=url, cause=e) from e
+
+    if response.status_code != 200:
+        label = f"'{sheet_name}'" if sheet_name else url
+        raise exceptions.SheetFetchError(
+            f"Failed to fetch {label}. "
+            f"Status: {response.status_code}, Reason: {response.reason_phrase}",
+            url=url,
+            status_code=response.status_code,
+        )
+
+    return response.text
+
+
+# # Backwards-compatible alias used by read_sheet()
+# def fetch_csv(export_url: str, timeout: int = 30) -> str:
+#     return fetch_raw(export_url, timeout=timeout)

scan_google_sheet-0.1.0/src/scan_google_sheet/parse.py

@@ -0,0 +1,50 @@
+"""Parse raw CSV text into a Polars DataFrame."""
+
+import io
+
+import polars as pl
+
+from .exceptions import _POLARS_PARSE_ERRORS, SheetParseError
+
+
+def parse_csv(
+    csv_text: str,
+    *,
+    infer_schema_length: int | None = 100,
+    null_values: list[str] | None = None,
+    try_parse_dates: bool = False,
+    schema_overrides: dict[str, pl.DataType] | None = None,
+) -> pl.DataFrame:
+    """Parse CSV text into a Polars DataFrame.
+
+    Parameters
+    ----------
+    csv_text:
+        Raw CSV string fetched from Google Sheets export.
+    infer_schema_length:
+        Number of rows used to infer column types. Pass `None` to read all rows.
+    null_values:
+        Additional strings to treat as null (e.g. ``["N/A", "-"]``).
+    try_parse_dates:
+        Attempt to parse date-like strings automatically.
+    schema_overrides:
+        Map of column name → Polars dtype to override inferred types.
+
+    Returns
+    -------
+    pl.DataFrame
+    """
+    _null_values = ["", "NULL", "null", "None", "NA"] + (null_values or [])
+
+    try:
+        return pl.read_csv(
+            io.StringIO(csv_text),
+            infer_schema_length=infer_schema_length,
+            null_values=_null_values,
+            try_parse_dates=try_parse_dates,
+            schema_overrides=schema_overrides,
+        )
+    except tuple(_POLARS_PARSE_ERRORS) as e:
+        raise SheetParseError.from_polars(e, step="parse_csv") from e
+    except Exception as e:
+        raise SheetParseError(f"Unexpected error parsing CSV: {e}", cause=e) from e

scan_google_sheet-0.1.0/src/scan_google_sheet/scan.py

@@ -0,0 +1,178 @@
+"""Lazy Google Sheets reader via Polars IO plugin API."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from io import StringIO
+
+import polars as pl
+from polars.io.plugins import register_io_source
+
+from . import exceptions
+from .fetch import fetch_raw
+from .url import build_gviz_url, from_url
+
+
+def scan_google_sheet(
+    sheet_name: str,
+    sheet_id: str | None = None,
+    url: str | None = None,
+    *,
+    timeout: int = 10,
+    parse_dates: bool = True,
+    batch_size: int = 1_000,
+) -> pl.LazyFrame:
+    """Scan a public Google Sheet as a Polars LazyFrame via the IO plugin API.
+
+    Registered as a lazy source so it participates in Polars query
+    optimisation — projection pushdown, predicate pushdown, early stopping,
+    and streaming in batches are all supported.
+
+    Parameters
+    ----------
+    sheet_name:
+        The tab name to read (as shown on the sheet tab in Google Sheets).
+    sheet_id:
+        The spreadsheet ID from the URL. Mutually exclusive with ``url``.
+    url:
+        A full Google Sheets URL. The sheet ID is extracted automatically.
+        Mutually exclusive with ``sheet_id``.
+    timeout:
+        HTTP request timeout in seconds.
+    parse_dates:
+        Attempt automatic date/datetime parsing.
+    batch_size:
+        Number of rows per batch yielded to the Polars engine.
+
+    Returns
+    -------
+    pl.LazyFrame
+
+    Raises
+    ------
+    ConfigurationError
+        If neither or both of ``sheet_id`` / ``url`` are provided.
+    SheetFetchError
+        If the HTTP request fails or returns a non-200 status.
+    NetworkError
+        On connection or transport failure.
+
+    Notes
+    -----
+    Google Sheets CSV export does not support partial reads — the full sheet
+    is always downloaded in a single HTTP request. Projection and predicate
+    pushdown are applied in Python after the download, so they reduce
+    processing cost but not network cost.
+
+    Examples
+    --------
+    >>> lf = scan_google_sheet("Sheet1", sheet_id="1BxiMVs0XRA5nFMdKvBdBZjgm...")
+    >>> lf.filter(pl.col("year") == 2025).select("vessel", "amount").collect()
+
+    >>> lf = scan_google_sheet(
+    ...     "Sheet1",
+    ...     url="https://docs.google.com/spreadsheets/d/1BxiMVs0.../edit",
+    ... )
+    """
+    match (sheet_id, url):
+        case (None, None):
+            raise exceptions.ConfigurationError("Provide either sheet_id or url, not neither.")
+        case (_, None):
+            assert sheet_id is not None
+            resolved_url = build_gviz_url(sheet_id, sheet_name)
+        case (None, _):
+            assert url is not None
+            resolved_url = from_url(url, sheet_name)
+        case _:
+            raise exceptions.ConfigurationError("Provide either sheet_id or url, not both.")
+
+    # One upfront fetch to resolve the schema — unavoidable for CSV over HTTP.
+    raw_csv = fetch_raw(resolved_url, timeout=timeout, sheet_name=sheet_name)
+
+    schema = pl.read_csv(
+        StringIO(raw_csv),
+        try_parse_dates=parse_dates,
+        infer_schema_length=10_000,
+        n_rows=0,  # schema only, no data rows needed
+    ).schema
+
+    def source_generator(
+        with_columns: list[str] | None,
+        predicate: pl.Expr | None,
+        n_rows: int | None,
+        batch_size: int | None,
+    ) -> Iterator[pl.DataFrame]:
+        """Produce batches of rows, honouring pushdown hints from the engine."""
+        _batch = batch_size or 1_000
+
+        lf = pl.scan_csv(
+            StringIO(raw_csv),
+            try_parse_dates=parse_dates,
+            infer_schema_length=10_000,
+        )
+
+        # Apply pushdowns — filtering in Python, not at source (HTTP limitation)
+        if with_columns is not None:
+            lf = lf.select(with_columns)
+        if predicate is not None:
+            lf = lf.filter(predicate)
+        if n_rows is not None:
+            lf = lf.head(n_rows)
+
+        df = lf.collect()
+        assert isinstance(df, pl.DataFrame)
+
+        for offset in range(0, df.height, _batch):
+            yield df.slice(offset, _batch)
+
+    return register_io_source(io_source=source_generator, schema=schema)
+
+
+def read_google_sheet(
+    sheet_name: str,
+    sheet_id: str | None = None,
+    url: str | None = None,
+    *,
+    timeout: int = 10,
+    parse_dates: bool = True,
+) -> pl.DataFrame:
+    """Read a public Google Sheet into a Polars DataFrame.
+
+    Convenience wrapper around ``scan_google_sheet`` that collects immediately.
+    Prefer ``scan_google_sheet`` when chaining filters or projections before
+    collecting, to avoid loading unused columns into memory.
+
+    Parameters
+    ----------
+    sheet_name:
+        The tab name to read.
+    sheet_id:
+        The spreadsheet ID. Mutually exclusive with ``url``.
+    url:
+        A full Google Sheets URL. Mutually exclusive with ``sheet_id``.
+    timeout:
+        HTTP request timeout in seconds.
+    parse_dates:
+        Attempt automatic date/datetime parsing.
+
+    Returns
+    -------
+    pl.DataFrame
+
+    Examples
+    --------
+    >>> df = read_google_sheet("Sheet1", sheet_id="1BxiMVs0XRA5nFMdKvBdBZjgm...")
+    >>> df = read_google_sheet(
+    ...     "Sheet1",
+    ...     url="https://docs.google.com/spreadsheets/d/1BxiMVs0.../edit",
+    ... )
+    """
+    df = scan_google_sheet(
+        sheet_name,
+        sheet_id=sheet_id,
+        url=url,
+        timeout=timeout,
+        parse_dates=parse_dates,
+    ).collect()
+    assert isinstance(df, pl.DataFrame)
+    return df

scan_google_sheet-0.1.0/src/scan_google_sheet/url.py

@@ -0,0 +1,79 @@
+"""Utilities for parsing Google Sheets URLs."""
+
+import re
+from urllib.parse import parse_qs, urlparse
+
+from .exceptions import SheetURLError
+
+
+def extract_sheet_id(url: str) -> str:
+    """Extract the spreadsheet ID from a Google Sheets URL or return as-is if already an ID."""
+    pattern = r"/spreadsheets/d/([a-zA-Z0-9_-]+)"
+    match = re.search(pattern, url)
+    if match:
+        return match.group(1)
+    # Assume it's already a bare sheet ID
+    if re.fullmatch(r"[a-zA-Z0-9_-]+", url):
+        return url
+    raise SheetURLError(f"Could not extract sheet ID from: {url!r}", raw=url)
+
+
+def extract_gid(url: str) -> str | None:
+    """Extract the gid (tab/sheet index) from a Google Sheets URL, if present."""
+    parsed = urlparse(url)
+    # gid can appear in the fragment: #gid=123456
+    fragment_params = parse_qs(parsed.fragment)
+    if "gid" in fragment_params:
+        return fragment_params["gid"][0]
+    # or in the query string
+    query_params = parse_qs(parsed.query)
+    if "gid" in query_params:
+        return query_params["gid"][0]
+    return None
+
+
+def build_export_url(sheet_id: str, gid: str | None = None) -> str:
+    """Build the CSV export URL for a public Google Sheet (by gid/tab index)."""
+    base = f"https://docs.google.com/spreadsheets/d/{sheet_id}/export?format=csv"
+    if gid is not None:
+        base += f"&gid={gid}"
+    return base
+
+
+def build_gviz_url(sheet_id: str, sheet_name: str) -> str:
+    """Build the gviz CSV export URL for a public Google Sheet (by sheet name).
+
+    Preferred over the ``/export`` URL when the sheet name is known, as it
+    allows selecting a specific tab by name rather than numeric gid.
+
+    Examples:
+        >>> build_gviz_url("1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms", "Sheet1")
+        'https://docs.google.com/spreadsheets/d/1BxiMVs0.../gviz/tq?tqx=out:csv&sheet=Sheet1'
+    """
+    return (
+        f"https://docs.google.com/spreadsheets/d/{sheet_id}/gviz/tq?tqx=out:csv&sheet={sheet_name}"
+    )
+
+
+def from_url(url: str, sheet_name: str) -> str:
+    """Extract the sheet ID from a full Google Sheets URL and build a gviz export URL.
+
+    Parameters
+    ----------
+    url:
+        Any Google Sheets URL containing a spreadsheet ID.
+    sheet_name:
+        The tab name to export.
+
+    Returns
+    -------
+    str
+        A ready-to-fetch gviz CSV export URL.
+
+    Raises
+    ------
+    SheetURLError
+        If no sheet ID can be extracted from ``url``.
+    """
+    sheet_id = extract_sheet_id(url)
+    return build_gviz_url(sheet_id, sheet_name)