tha-google-runner 0.1.0__py3-none-any.whl

tha_google_runner/__init__.py

@@ -0,0 +1,10 @@
+"""tha-google-runner: typed gspread wrapper for Google Sheets."""
+
+from tha_google_runner.errors import GoogleError
+from tha_google_runner.sheets import ThaSheets
+
+__version__ = "0.1.0"
+__all__ = [
+    "GoogleError",
+    "ThaSheets",
+]

tha_google_runner/auth.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import google.auth
+import google.auth.exceptions
+import gspread
+
+from tha_google_runner.errors import GoogleError
+
+_SCOPES = [
+    "https://www.googleapis.com/auth/spreadsheets",
+    "https://www.googleapis.com/auth/drive",
+]
+
+_DEFAULT_TOKEN = Path.home() / ".config" / "tha-google-runner" / "token.json"
+
+
+def build_client(
+    credentials_file: str | None,
+    token_file: str | None,
+) -> gspread.Client:
+    """Build a gspread client using ADC or an OAuth2 client_secrets.json file.
+
+    Auth priority:
+    1. Application Default Credentials (ADC) — if credentials_file is None.
+       Run `gcloud auth application-default login` once to set this up.
+    2. OAuth2 user flow — if credentials_file points to a client_secrets.json.
+       A browser window opens on first run; the token is cached for subsequent runs.
+    """
+    if credentials_file is None:
+        try:
+            creds, _ = google.auth.default(scopes=_SCOPES)
+            return gspread.Client(auth=creds)
+        except google.auth.exceptions.DefaultCredentialsError:
+            raise GoogleError(
+                "No Google credentials found. Either:\n"
+                "  1. Run: gcloud auth application-default login\n"
+                "  2. Pass credentials_file= pointing to your client_secrets.json\n"
+                "See the tha-google-runner README for setup instructions."
+            ) from None
+
+    token = token_file or str(_DEFAULT_TOKEN)
+    Path(token).parent.mkdir(parents=True, exist_ok=True)
+    return gspread.oauth(
+        credentials_filename=credentials_file,
+        authorized_user_filename=token,
+    )

tha_google_runner/errors.py

@@ -0,0 +1,2 @@
+class GoogleError(Exception):
+    """Raised for tha-google-runner errors."""

tha_google_runner/sheets.py

@@ -0,0 +1,337 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Literal, cast
+
+import gspread
+import gspread.exceptions
+from gspread.utils import rowcol_to_a1
+
+from tha_google_runner.auth import build_client
+from tha_google_runner.errors import GoogleError
+
+OnConflict = Literal["update_all", "update_first", "update_last", "raise", "skip"]
+
+_URL_RE = re.compile(r"/spreadsheets/d/([a-zA-Z0-9_-]+)")
+
+
+class ThaSheets:
+    def __init__(
+        self,
+        *,
+        credentials_file: str | None = None,
+        token_file: str | None = None,
+    ) -> None:
+        self._credentials_file = credentials_file
+        self._token_file = token_file
+        self._client: gspread.Client | None = None
+        self.rows: list[dict[str, Any]] = []
+
+    def _get_client(self) -> gspread.Client:
+        if self._client is None:
+            self._client = build_client(self._credentials_file, self._token_file)
+        return self._client
+
+    def _resolve_id(self, spreadsheet_id: str | None, url: str | None) -> str:
+        if url is not None:
+            m = _URL_RE.search(url)
+            if not m:
+                raise GoogleError(f"Could not parse spreadsheet ID from URL: {url}")
+            return m.group(1)
+        if spreadsheet_id is not None:
+            return spreadsheet_id
+        raise GoogleError("Provide either spreadsheet_id= or url=")
+
+    def _get_spreadsheet(self, sid: str) -> gspread.Spreadsheet:
+        client = self._get_client()
+        try:
+            return client.open_by_key(sid)
+        except gspread.exceptions.SpreadsheetNotFound:
+            raise GoogleError(f"Spreadsheet not found: {sid}") from None
+
+    def _get_worksheet(self, sid: str, sheet_name: str | None) -> gspread.Worksheet:
+        spreadsheet = self._get_spreadsheet(sid)
+        if sheet_name is None:
+            return spreadsheet.sheet1
+        try:
+            return spreadsheet.worksheet(sheet_name)
+        except gspread.exceptions.WorksheetNotFound:
+            raise GoogleError(f"Sheet '{sheet_name}' not found in {sid}") from None
+
+    def _normalize_rows(
+        self,
+        rows: list[dict[str, Any]] | list[list[Any]],
+        existing_headers: list[str],
+    ) -> tuple[list[str], list[dict[str, Any]]]:
+        """Convert rows to list[dict] and detect/drop an included header row.
+
+        For list[dict] input, keys become headers (unchanged behavior).
+        For list[list] input, auto-detects if rows[0] is a header row by comparing
+        it against existing_headers. If they match exactly, the header row is dropped.
+        When existing_headers is empty (new/replaced sheet), rows[0] is always headers.
+        """
+        if not rows:
+            return existing_headers, []
+        if isinstance(rows[0], dict):
+            dict_rows = cast(list[dict[str, Any]], rows)
+            headers = existing_headers if existing_headers else list(dict_rows[0].keys())
+            return headers, dict_rows
+        list_rows = cast(list[list[Any]], rows)
+        first_as_strs = [str(v) for v in list_rows[0]]
+        if existing_headers:
+            if first_as_strs == existing_headers:
+                headers = existing_headers
+                data = list_rows[1:]
+            else:
+                headers = existing_headers
+                data = list_rows
+        else:
+            headers = first_as_strs
+            data = list_rows[1:]
+        return headers, [dict(zip(headers, row, strict=False)) for row in data]
+
+    def read(
+        self,
+        *,
+        spreadsheet_id: str | None = None,
+        url: str | None = None,
+        sheet_name: str | None = None,
+    ) -> list[dict[str, Any]]:
+        sid = self._resolve_id(spreadsheet_id, url)
+        ws = self._get_worksheet(sid, sheet_name)
+        self.rows = ws.get_all_records()
+        return self.rows
+
+    def append_rows(
+        self,
+        rows: list[dict[str, Any]] | list[list[Any]],
+        *,
+        spreadsheet_id: str | None = None,
+        url: str | None = None,
+        sheet_name: str | None = None,
+    ) -> int:
+        if not rows:
+            return 0
+        sid = self._resolve_id(spreadsheet_id, url)
+        ws = self._get_worksheet(sid, sheet_name)
+        existing_headers = ws.row_values(1)
+        headers, dict_rows = self._normalize_rows(rows, existing_headers)
+        if not existing_headers:
+            ws.append_row(headers)
+        values = [[row.get(h, "") for h in headers] for row in dict_rows]
+        ws.append_rows(values)
+        self.rows = dict_rows
+        return len(dict_rows)
+
+    def update_rows(
+        self,
+        rows: list[dict[str, Any]] | list[list[Any]],
+        *,
+        spreadsheet_id: str | None = None,
+        url: str | None = None,
+        sheet_name: str | None = None,
+    ) -> int:
+        sid = self._resolve_id(spreadsheet_id, url)
+        ws = self._get_worksheet(sid, sheet_name)
+        ws.clear()
+        if not rows:
+            self.rows = []
+            return 0
+        headers, dict_rows = self._normalize_rows(rows, [])
+        values = [headers] + [[row.get(h, "") for h in headers] for row in dict_rows]
+        ws.update("A1", values)  # type: ignore[arg-type]
+        self.rows = dict_rows
+        return len(dict_rows)
+
+    def create(
+        self,
+        title: str,
+        *,
+        rows: list[dict[str, Any]] | list[list[Any]] | None = None,
+        sheet_name: str = "Sheet1",
+    ) -> str:
+        client = self._get_client()
+        spreadsheet = client.create(title)
+        ws = spreadsheet.sheet1
+        ws.update_title(sheet_name)
+        if rows:
+            headers, dict_rows = self._normalize_rows(rows, [])
+            values = [headers] + [[row.get(h, "") for h in headers] for row in dict_rows]
+            ws.update("A1", values)  # type: ignore[arg-type]
+            self.rows = dict_rows
+        return spreadsheet.id
+
+    def delete(
+        self,
+        *,
+        spreadsheet_id: str | None = None,
+        url: str | None = None,
+    ) -> None:
+        sid = self._resolve_id(spreadsheet_id, url)
+        self._get_client().del_spreadsheet(sid)
+        self.rows = []
+
+    def list_sheets(
+        self,
+        *,
+        spreadsheet_id: str | None = None,
+        url: str | None = None,
+    ) -> list[str]:
+        sid = self._resolve_id(spreadsheet_id, url)
+        spreadsheet = self._get_spreadsheet(sid)
+        return [ws.title for ws in spreadsheet.worksheets()]
+
+    def add_sheet(
+        self,
+        sheet_name: str,
+        *,
+        spreadsheet_id: str | None = None,
+        url: str | None = None,
+        rows: list[dict[str, Any]] | list[list[Any]] | None = None,
+    ) -> None:
+        sid = self._resolve_id(spreadsheet_id, url)
+        spreadsheet = self._get_spreadsheet(sid)
+        ws = spreadsheet.add_worksheet(title=sheet_name, rows=1000, cols=26)
+        if rows:
+            headers, dict_rows = self._normalize_rows(rows, [])
+            values = [headers] + [[row.get(h, "") for h in headers] for row in dict_rows]
+            ws.update("A1", values)  # type: ignore[arg-type]
+            self.rows = dict_rows
+
+    def delete_sheet(
+        self,
+        sheet_name: str,
+        *,
+        spreadsheet_id: str | None = None,
+        url: str | None = None,
+    ) -> None:
+        sid = self._resolve_id(spreadsheet_id, url)
+        spreadsheet = self._get_spreadsheet(sid)
+        try:
+            ws = spreadsheet.worksheet(sheet_name)
+        except gspread.exceptions.WorksheetNotFound:
+            raise GoogleError(f"Sheet '{sheet_name}' not found in {sid}") from None
+        spreadsheet.del_worksheet(ws)
+
+    def share(
+        self,
+        email: str,
+        *,
+        spreadsheet_id: str | None = None,
+        url: str | None = None,
+        role: str = "reader",
+    ) -> None:
+        sid = self._resolve_id(spreadsheet_id, url)
+        spreadsheet = self._get_spreadsheet(sid)
+        spreadsheet.share(email, perm_type="user", role=role)
+
+    def upsert_rows(
+        self,
+        rows: list[dict[str, Any]] | list[list[Any]],
+        *,
+        key: str | list[str],
+        spreadsheet_id: str | None = None,
+        url: str | None = None,
+        sheet_name: str | None = None,
+        on_conflict: OnConflict = "update_all",
+    ) -> int:
+        if not rows:
+            return 0
+
+        sid = self._resolve_id(spreadsheet_id, url)
+        ws = self._get_worksheet(sid, sheet_name)
+        keys = [key] if isinstance(key, str) else list(key)
+
+        existing = ws.get_all_values()
+        existing_hdrs: list[str] = list(existing[0]) if existing else []
+        norm_hdrs, dict_rows = self._normalize_rows(rows, existing_hdrs)
+
+        # Empty sheet — write everything fresh
+        if not existing:
+            values = [norm_hdrs] + [[row.get(h, "") for h in norm_hdrs] for row in dict_rows]
+            ws.update("A1", values)  # type: ignore[arg-type]
+            self.rows = dict_rows
+            return len(dict_rows)
+
+        headers = list(existing[0])
+        data_rows = existing[1:]
+
+        missing_keys = [k for k in keys if k not in headers]
+        if missing_keys:
+            raise GoogleError(f"Key column(s) not found in sheet headers: {missing_keys}")
+
+        # Collect new columns from incoming rows, preserving order
+        seen: set[str] = set(headers)
+        new_cols: list[str] = []
+        for row in dict_rows:
+            for col in row:
+                if col not in seen:
+                    new_cols.append(col)
+                    seen.add(col)
+        if new_cols:
+            headers = headers + new_cols
+            ws.update("A1", [headers])  # type: ignore[arg-type]
+
+        col_index = {h: i for i, h in enumerate(headers)}
+        key_col_indices = [col_index[k] for k in keys]
+
+        # Build key → list of sheet row numbers (1-indexed, data starts at row 2)
+        index: dict[tuple[str, ...], list[int]] = {}
+        for i, row_vals in enumerate(data_rows):
+            row_key = tuple(
+                str(row_vals[c]) if c < len(row_vals) else "" for c in key_col_indices
+            )
+            index.setdefault(row_key, []).append(i + 2)
+
+        cell_updates: list[dict[str, Any]] = []
+        rows_to_append: list[list[Any]] = []
+        upserted = 0
+
+        for row in dict_rows:
+            row_key = tuple(str(row.get(k, "")) for k in keys)
+            matches = index.get(row_key, [])
+
+            if not matches:
+                rows_to_append.append([row.get(h, "") for h in headers])
+                upserted += 1
+                continue
+
+            if len(matches) > 1:
+                if on_conflict == "raise":
+                    raise GoogleError(
+                        f"Duplicate rows found for key {dict(zip(keys, row_key, strict=True))}"
+                    )
+                elif on_conflict == "skip":
+                    continue
+                elif on_conflict == "update_first":
+                    matches = [matches[0]]
+                elif on_conflict == "update_last":
+                    matches = [matches[-1]]
+                # update_all: use all matches as-is
+
+            for sheet_row in matches:
+                for col_name, val in row.items():
+                    if col_name in col_index:
+                        cell = rowcol_to_a1(sheet_row, col_index[col_name] + 1)
+                        cell_updates.append({"range": cell, "values": [[val]]})
+            upserted += 1
+
+        if cell_updates:
+            ws.batch_update(cell_updates)
+        if rows_to_append:
+            ws.append_rows(rows_to_append)
+
+        self.rows = dict_rows
+        return upserted
+
+    def clear(
+        self,
+        *,
+        spreadsheet_id: str | None = None,
+        url: str | None = None,
+        sheet_name: str | None = None,
+    ) -> None:
+        sid = self._resolve_id(spreadsheet_id, url)
+        ws = self._get_worksheet(sid, sheet_name)
+        ws.clear()
+        self.rows = []

tha_google_runner-0.1.0.dist-info/METADATA

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: tha-google-runner
+Version: 0.1.0
+Summary: A Tabular Helper API library that wraps Google Sheets with a typed, consistent interface built on gspread.
+Project-URL: Homepage, https://github.com/tha-guy-nate/tha-google-runner
+Project-URL: Issues, https://github.com/tha-guy-nate/tha-google-runner/issues
+Author: Nate Wright
+License: MIT
+License-File: LICENSE
+Keywords: google,gspread,helper,sheets,tabular
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: google-auth-oauthlib>=1.0
+Requires-Dist: google-auth>=2.0
+Requires-Dist: gspread>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tha-google-runner
+
+[![CI](https://github.com/tha-guy-nate/tha-google-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/tha-guy-nate/tha-google-runner/actions/workflows/ci.yml)
+
+A Tabular Helper API library that wraps Google Sheets with a typed, consistent interface built on gspread.
+
+## Install
+
+```bash
+pip install tha-google-runner
+```
+
+## Authentication setup
+
+`tha-google-runner` uses your **personal Google account** — not a service account. There are two ways to authenticate. Option 1 is recommended if you have the Google Cloud SDK installed.
+
+> **Cost note:** This package is free and open source. The Google APIs it uses (Google Sheets API, Google Drive API) are also free for normal scripting workloads — Google provides a generous free tier (300 reads/min, 60 writes/min) that the vast majority of users will never exceed. Google Cloud Console may ask for a credit card when you first create a project to verify your identity, but **Google does not charge you** for the APIs used here. Any billing questions are between you and Google — not this package.
+
+### Option 1 — Application Default Credentials (ADC)
+
+This is the zero-config path. Run once in your terminal:
+
+```bash
+gcloud auth application-default login
+```
+
+A browser window opens, you sign in with your Google account, and credentials are saved to your machine. After that, `ThaSheets()` works with no arguments.
+
+> Don't have `gcloud`? Install the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install) — it's a standalone CLI tool, roughly similar in spirit to the AWS CLI or the Azure CLI. It is not heavy and not venv-specific; install it once at the system level and every Python project on your machine can use ADC. Or skip it entirely and use Option 2.
+
+### Option 2 — OAuth2 client secrets
+
+Use this if you don't have `gcloud` or prefer not to install it.
+
+**Step 1 — Create a Google Cloud project**
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com/)
+2. Click the project dropdown → **New Project** → give it any name → **Create**
+
+**Step 2 — Enable the required APIs**
+
+In your new project, go to **APIs & Services** → **Enable APIs and Services** and enable both:
+- **Google Sheets API**
+- **Google Drive API**
+
+**Step 3 — Create OAuth2 credentials**
+
+1. Go to **APIs & Services** → **Credentials** → **Create Credentials** → **OAuth 2.0 Client ID**
+2. If prompted, configure the **OAuth consent screen** first:
+   - User type: **External** → fill in app name and your email → save
+3. Application type: **Desktop app** → give it a name → **Create**
+4. Click **Download JSON** and save the file (e.g., `client_secrets.json`)
+
+**Step 4 — Use the credentials file**
+
+```python
+sheets = ThaSheets(credentials_file="client_secrets.json")
+```
+
+On the **first run**, a browser window opens for you to grant access. After that, the token is cached at `~/.config/tha-google-runner/token.json` and no browser is needed.
+
+---
+
+## Quick start
+
+```python
+from tha_google_runner import ThaSheets
+
+sheets = ThaSheets()  # uses ADC; or pass credentials_file="client_secrets.json"
+
+# Read all rows (first row is headers)
+rows = sheets.read(spreadsheet_id="your-spreadsheet-id")
+
+# Append new rows (writes headers automatically if the sheet is empty)
+sheets.append_rows(
+    [{"name": "Alice", "score": 95}, {"name": "Bob", "score": 82}],
+    spreadsheet_id="your-spreadsheet-id",
+)
+
+# Append using raw lists — header row auto-detected and dropped if it matches the sheet
+sheets.append_rows(
+    [["name", "score"], ["Alice", 95]],
+    spreadsheet_id="your-spreadsheet-id",
+)
+
+# Overwrite the entire sheet
+sheets.update_rows(
+    [{"name": "Alice", "score": 95}],
+    spreadsheet_id="your-spreadsheet-id",
+)
+
+# Upsert by key — inserts new rows, updates existing ones
+sheets.upsert_rows(
+    [{"id": "1", "name": "Alice", "score": 99}],
+    key="id",
+    spreadsheet_id="your-spreadsheet-id",
+)
+
+# Create a new spreadsheet and get its ID
+spreadsheet_id = sheets.create("My Report", rows=[{"col": "val"}])
+
+# Clear a sheet
+sheets.clear(spreadsheet_id="your-spreadsheet-id")
+```
+
+> **Finding your spreadsheet ID:** It's the long string in the URL between `/d/` and `/edit`.
+> `https://docs.google.com/spreadsheets/d/<spreadsheet-id>/edit`
+>
+> You can also pass `url=` instead of `spreadsheet_id=` to any method and the ID will be extracted automatically.
+
+---
+
+## Row input formats
+
+All write methods (`append_rows`, `update_rows`, `upsert_rows`, `create`, `add_sheet`) accept either format:
+
+**`list[dict]`** — keys are column headers:
+```python
+[{"name": "Alice", "score": 95}, {"name": "Bob", "score": 82}]
+```
+
+**`list[list]`** — raw rows with automatic header detection:
+```python
+[["name", "score"], ["Alice", 95], ["Bob", 82]]
+```
+
+Header detection for `list[list]` input:
+
+| Sheet state | First row matches existing headers? | Result |
+|---|---|---|
+| Has data | Yes | Header row dropped, rest appended as data |
+| Has data | No | All rows treated as data |
+| Empty / being replaced | — | First row always becomes headers |
+
+---
+
+## API
+
+### `ThaSheets(*, credentials_file=None, token_file=None)`
+
+```python
+ThaSheets(
+    credentials_file: str | None = None,  # path to client_secrets.json; None uses ADC
+    token_file: str | None = None,         # override token cache path (OAuth2 only)
+)
+```
+
+The Google client is built lazily on first use and cached for the lifetime of the instance.
+After any write, `sheets.rows` is set to the data rows that were written (as `list[dict]`).
+
+---
+
+### `read(*, spreadsheet_id=None, url=None, sheet_name=None) -> list[dict]`
+
+Read all rows. The first row is treated as headers; each subsequent row becomes a `dict`.
+
+```python
+rows = sheets.read(spreadsheet_id="spreadsheet-id")
+rows = sheets.read(url="https://docs.google.com/spreadsheets/d/.../edit")
+rows = sheets.read(spreadsheet_id="spreadsheet-id", sheet_name="Q1 Data")
+```
+
+---
+
+### `append_rows(rows, *, spreadsheet_id=None, url=None, sheet_name=None) -> int`
+
+Append rows to an existing sheet. Returns the number of rows appended.
+
+- If the sheet is empty, the headers are written first.
+- Missing keys in a row are filled with `""`.
+
+```python
+count = sheets.append_rows(
+    [{"name": "Alice", "score": 95}],
+    spreadsheet_id="spreadsheet-id",
+)
+```
+
+---
+
+### `update_rows(rows, *, spreadsheet_id=None, url=None, sheet_name=None) -> int`
+
+Overwrite all data in a sheet. Clears the sheet first, then writes headers + rows. Returns the number of rows written. Passing an empty list clears the sheet and returns `0`.
+
+```python
+count = sheets.update_rows(
+    [{"name": "Alice", "score": 95}],
+    spreadsheet_id="spreadsheet-id",
+)
+```
+
+---
+
+### `upsert_rows(rows, *, key, spreadsheet_id=None, url=None, sheet_name=None, on_conflict="update_all") -> int`
+
+Insert new rows and update existing ones matched by key. Returns the number of rows upserted.
+
+- `key` — column name (str) or list of column names for composite keys
+- New columns in incoming rows are appended to the sheet automatically
+- `on_conflict` controls what happens when multiple existing rows match the same key:
+  - `"update_all"` (default) — update every matching row
+  - `"update_first"` — update only the first match
+  - `"update_last"` — update only the last match
+  - `"skip"` — leave duplicates untouched
+  - `"raise"` — raise `GoogleError`
+
+```python
+count = sheets.upsert_rows(
+    [{"id": "1", "name": "Alice", "score": 99}],
+    key="id",
+    spreadsheet_id="spreadsheet-id",
+)
+
+# Composite key
+count = sheets.upsert_rows(rows, key=["year", "month"], spreadsheet_id="spreadsheet-id")
+```
+
+---
+
+### `create(title, *, rows=None, sheet_name="Sheet1") -> str`
+
+Create a new spreadsheet. Returns the new spreadsheet's ID.
+
+```python
+sid = sheets.create("My Report")
+sid = sheets.create("My Report", rows=[{"col": "val"}], sheet_name="Data")
+```
+
+---
+
+### `delete(*, spreadsheet_id=None, url=None) -> None`
+
+Permanently delete a spreadsheet.
+
+```python
+sheets.delete(spreadsheet_id="spreadsheet-id")
+```
+
+---
+
+### `list_sheets(*, spreadsheet_id=None, url=None) -> list[str]`
+
+Return the names of all worksheets in a spreadsheet.
+
+```python
+names = sheets.list_sheets(spreadsheet_id="spreadsheet-id")
+# ["Sheet1", "Q1 Data", "Archive"]
+```
+
+---
+
+### `add_sheet(sheet_name, *, spreadsheet_id=None, url=None, rows=None) -> None`
+
+Add a new worksheet to an existing spreadsheet. Optionally write initial rows.
+
+```python
+sheets.add_sheet("Q2 Data", spreadsheet_id="spreadsheet-id")
+sheets.add_sheet("Q2 Data", spreadsheet_id="spreadsheet-id", rows=[{"col": "val"}])
+```
+
+---
+
+### `delete_sheet(sheet_name, *, spreadsheet_id=None, url=None) -> None`
+
+Delete a worksheet from a spreadsheet.
+
+```python
+sheets.delete_sheet("Archive", spreadsheet_id="spreadsheet-id")
+```
+
+---
+
+### `share(email, *, spreadsheet_id=None, url=None, role="reader") -> None`
+
+Share a spreadsheet with a user. `role` can be `"reader"`, `"writer"`, or `"owner"`.
+
+```python
+sheets.share("colleague@example.com", spreadsheet_id="spreadsheet-id", role="writer")
+```
+
+---
+
+### `clear(*, spreadsheet_id=None, url=None, sheet_name=None) -> None`
+
+Clear all data in a sheet. Resets `sheets.rows` to `[]`.
+
+```python
+sheets.clear(spreadsheet_id="spreadsheet-id")
+sheets.clear(spreadsheet_id="spreadsheet-id", sheet_name="Archive")
+```
+
+---
+
+## License
+
+MIT

tha_google_runner-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+tha_google_runner/__init__.py,sha256=hE41klzEkb99ONiaYx8YRkKYPgnMJKDntar5YsckplE,236
+tha_google_runner/auth.py,sha256=KfBYMUZA2avjhTh59FjO90yn2uwXTrlS4yuHKFrJJZY,1671
+tha_google_runner/errors.py,sha256=IGT5dUKAxGxlknlMJCHAIfJQXAgcZNQK4RvnmgBrdk4,77
+tha_google_runner/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tha_google_runner/sheets.py,sha256=Mft1HFR0E2NUPgj0TWu76EvTOQ67yT8rvsYGqoDW24Q,11877
+tha_google_runner-0.1.0.dist-info/METADATA,sha256=31HrYZj_Uw1uxAzQWhgDvN9vPNFPIe3bYq4q6Wn8pKU,10512
+tha_google_runner-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tha_google_runner-0.1.0.dist-info/licenses/LICENSE,sha256=bCtVwn7MJmnj7wfasPJG_OXozVSo1RGg1FXERKSv6ps,1070
+tha_google_runner-0.1.0.dist-info/RECORD,,

tha_google_runner-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

tha_google_runner-0.1.0.dist-info/licenses/LICENSE

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