google-form-poster 0.1.1__tar.gz

google_form_poster-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+env/
+.env
+data/
+__pycache__/
+
+# build artifacts
+dist/
+*.egg-info/
+*.egg/
+build/
+
+# pytest
+.pytest_cache/
+.cache/

google_form_poster-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

google_form_poster-0.1.1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: google-form-poster
+Version: 0.1.1
+Summary: Submit data rows to Google Forms via POST requests
+Project-URL: Homepage, https://github.com/obabawale/google-form-poster.git
+Project-URL: Source, https://github.com/obabawale/google-form-poster.git
+Author-email: Olami <olami@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: automation,form-submission,google-forms
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: pandas>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Google Form Poster
+
+Submit data rows to a Google Form via POST requests.
+
+## Installation
+
+```bash
+pip install google-form-poster
+```
+
+## Usage — as a library
+
+```python
+from post_to_google_form import post_data
+
+url = "https://docs.google.com/forms/d/e/.../viewform"
+
+# Data keys match entry IDs directly
+data = [{"entry.12345": "Alice", "entry.67890": "alice@example.com"}]
+results = post_data(url, data)
+
+# Or use key_mappings to translate your keys
+key_mappings = {"name": "entry.12345", "email": "entry.67890"}
+data = [{"name": "Alice", "email": "alice@example.com"}]
+results = post_data(url, data, key_mappings)
+
+# results = [
+#   {"index": 0, "status_code": 200, "payload": {"entry.12345": "Alice", ...}},
+# ]
+```
+
+`forms.gle` short links are automatically resolved:
+
+```python
+post_data("https://forms.gle/abc123", data)
+```
+
+## Usage — CLI
+
+```bash
+post-to-google-form --file data.json --url https://forms.gle/abc123
+
+# With key mappings:
+post-to-google-form --file data.json --url https://forms.gle/abc123 \
+    --key-mappings mappings.json
+```
+
+All flags fall back to environment variables (`FILE_PATH`, `GOOGLE_FORM_URL`, `KEY_MAPPINGS`), loaded from `.env` if present.

google_form_poster-0.1.1/README.md

@@ -0,0 +1,48 @@
+# Google Form Poster
+
+Submit data rows to a Google Form via POST requests.
+
+## Installation
+
+```bash
+pip install google-form-poster
+```
+
+## Usage — as a library
+
+```python
+from post_to_google_form import post_data
+
+url = "https://docs.google.com/forms/d/e/.../viewform"
+
+# Data keys match entry IDs directly
+data = [{"entry.12345": "Alice", "entry.67890": "alice@example.com"}]
+results = post_data(url, data)
+
+# Or use key_mappings to translate your keys
+key_mappings = {"name": "entry.12345", "email": "entry.67890"}
+data = [{"name": "Alice", "email": "alice@example.com"}]
+results = post_data(url, data, key_mappings)
+
+# results = [
+#   {"index": 0, "status_code": 200, "payload": {"entry.12345": "Alice", ...}},
+# ]
+```
+
+`forms.gle` short links are automatically resolved:
+
+```python
+post_data("https://forms.gle/abc123", data)
+```
+
+## Usage — CLI
+
+```bash
+post-to-google-form --file data.json --url https://forms.gle/abc123
+
+# With key mappings:
+post-to-google-form --file data.json --url https://forms.gle/abc123 \
+    --key-mappings mappings.json
+```
+
+All flags fall back to environment variables (`FILE_PATH`, `GOOGLE_FORM_URL`, `KEY_MAPPINGS`), loaded from `.env` if present.

google_form_poster-0.1.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "google-form-poster"
+version = "0.1.1"
+description = "Submit data rows to Google Forms via POST requests"
+license = { text = "MIT" }
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "Olami", email = "olami@example.com" },
+]
+keywords = ["google-forms", "automation", "form-submission"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "pandas>=2.0",
+  "requests>=2.31",
+  "python-dotenv>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/obabawale/google-form-poster.git"
+Source = "https://github.com/obabawale/google-form-poster.git"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+post-to-google-form = "post_to_google_form.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/post_to_google_form"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

google_form_poster-0.1.1/src/post_to_google_form/__init__.py

@@ -0,0 +1,8 @@
+from post_to_google_form._submit import build_payload, post_data
+from post_to_google_form._url import get_form_response_url
+
+__all__ = [
+    "build_payload",
+    "get_form_response_url",
+    "post_data",
+]

google_form_poster-0.1.1/src/post_to_google_form/_submit.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+import requests
+
+from post_to_google_form._url import get_form_response_url
+
+
+def build_payload(
+    row: dict[str, Any],
+    key_mappings: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Map a row's keys to Google Form entry IDs.
+
+    If *key_mappings* is provided, only mapped keys are kept and renamed.
+    Otherwise the row is returned as-is (keys are assumed to be entry IDs).
+    """
+    if key_mappings is None:
+        return {k: str(v) for k, v in row.items()}
+
+    return {key_mappings[k]: str(v) for k, v in row.items() if k in key_mappings}
+
+
+def post_data(
+    url: str,
+    data: list[dict[str, Any]] | pd.DataFrame,
+    key_mappings: dict[str, str] | None = None,
+) -> list[dict[str, Any]]:
+    """Submit data rows to a Google Form.
+
+    Parameters
+    ----------
+    url:
+        Google Form URL — a ``viewform``, ``formResponse``, or ``forms.gle``
+        short link.  It will be resolved to the correct endpoint automatically.
+    data:
+        Rows to submit.  Each dict's keys should match the keys in
+        *key_mappings* (or be entry IDs directly if no mappings are given).
+    key_mappings:
+        Optional mapping from your data keys to Google Form entry IDs.
+        ``{"name": "entry.12345", "email": "entry.67890"}``
+
+    Returns
+    -------
+    list[dict[str, Any]]
+        One dict per row with keys ``"index"``, ``"status_code"``, and
+        ``"payload"`` (the data that was actually POSTed).
+    """
+    submit_url = get_form_response_url(url)
+
+    if isinstance(data, pd.DataFrame):
+        data = data.to_dict(orient="records")
+
+    results: list[dict[str, Any]] = []
+    for i, row in enumerate(data):
+        payload = build_payload(row, key_mappings)
+        resp = requests.post(submit_url, data=payload, timeout=20)
+        results.append({
+            "index": i,
+            "status_code": resp.status_code,
+            "payload": payload,
+        })
+
+    return results

google_form_poster-0.1.1/src/post_to_google_form/_url.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import requests
+
+
+def get_form_response_url(url: str) -> str:
+    """Resolve a Google Forms view URL to its formResponse endpoint."""
+    parsed = urlparse(url)
+
+    if "forms.gle" in parsed.netloc:
+        resolved = requests.get(url, allow_redirects=True, timeout=15).url
+        parsed = urlparse(resolved)
+
+    if parsed.path.endswith("/viewform"):
+        return f"{parsed.scheme}://{parsed.netloc}{parsed.path.replace('/viewform', '/formResponse')}"
+
+    if parsed.path.endswith("/formResponse"):
+        return url
+
+    return f"{parsed.scheme}://{parsed.netloc}{parsed.path.rstrip('/')}/formResponse"

google_form_poster-0.1.1/src/post_to_google_form/cli.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+import pandas as pd
+from dotenv import load_dotenv
+
+from post_to_google_form._submit import build_payload, post_data
+from post_to_google_form._url import get_form_response_url
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Submit data rows from a JSON file to a Google Form."
+    )
+    parser.add_argument(
+        "--file",
+        help="Path to the JSON data file (default: $FILE_PATH)",
+    )
+    parser.add_argument(
+        "--url",
+        help="Google Form URL (default: $GOOGLE_FORM_URL)",
+    )
+    parser.add_argument(
+        "--key-mappings",
+        help="Path to a JSON file mapping your data keys to entry IDs "
+             "(default: $KEY_MAPPINGS)",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = parse_args(argv)
+    load_dotenv()
+
+    file_path = args.file or os.getenv("FILE_PATH", "")
+    form_url = args.url or os.getenv("GOOGLE_FORM_URL", "")
+    mappings_path = args.key_mappings or os.getenv("KEY_MAPPINGS", "")
+
+    if not file_path:
+        print("Error: FILE_PATH is required")
+        sys.exit(1)
+
+    if not form_url:
+        print("Error: GOOGLE_FORM_URL is required")
+        sys.exit(1)
+
+    try:
+        df = pd.read_json(file_path)
+    except (FileNotFoundError, ValueError) as e:
+        print(f"Error reading {file_path}: {e}")
+        sys.exit(1)
+
+    key_mappings: dict[str, str] | None = None
+    if mappings_path:
+        with open(mappings_path) as f:
+            key_mappings = json.load(f)
+
+    submit_url = get_form_response_url(form_url)
+    print(f"Submit URL: {submit_url}")
+
+    results = post_data(submit_url, df, key_mappings)
+    for r in results:
+        status = r["status_code"]
+        payload = r["payload"]
+        if status >= 400:
+            print(f"Submission failed for row {r['index'] + 1}.")
+            print(f"Failed payload: {payload}")
+        print(f"Row {r['index'] + 1}: payload={payload}, status={status}")
+
+    print("Done!")
+
+
+if __name__ == "__main__":
+    main()

google_form_poster-0.1.1/tests/test_main.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pandas as pd
+import pytest
+
+from post_to_google_form._submit import build_payload, post_data
+from post_to_google_form._url import get_form_response_url
+from post_to_google_form.cli import main, parse_args
+
+
+class TestBuildPayload:
+    def test_no_mappings_passes_row_through(self) -> None:
+        row = {"entry.1": "Mr", "entry.2": "Alice"}
+        result = build_payload(row)
+        assert result == {"entry.1": "Mr", "entry.2": "Alice"}
+
+    def test_with_mappings_renames_keys(self) -> None:
+        mappings = {"title": "entry.1", "name": "entry.2"}
+        row = {"title": "Mr", "name": "Alice", "extra": "ignored"}
+        result = build_payload(row, mappings)
+        assert result == {"entry.1": "Mr", "entry.2": "Alice"}
+
+    def test_unmapped_keys_are_omitted(self) -> None:
+        mappings = {"title": "entry.1"}
+        row = {"title": "Mr", "name": "Alice"}
+        result = build_payload(row, mappings)
+        assert result == {"entry.1": "Mr"}
+
+    def test_coerces_values_to_strings(self) -> None:
+        row = {"entry.1": 42, "entry.2": None}
+        result = build_payload(row)
+        assert result == {"entry.1": "42", "entry.2": "None"}
+
+
+class TestPostData:
+    @patch("post_to_google_form._submit.requests.post")
+    def test_direct_keys(self, mock_post: MagicMock) -> None:
+        mock_post.return_value.status_code = 200
+        data = [{"entry.1": "Mr"}, {"entry.1": "Ms"}]
+        results = post_data("https://example.com/formResponse", data)
+        assert len(results) == 2
+        assert results[0]["index"] == 0
+        assert results[0]["status_code"] == 200
+        assert results[0]["payload"] == {"entry.1": "Mr"}
+
+    @patch("post_to_google_form._submit.requests.post")
+    def test_with_mappings(self, mock_post: MagicMock) -> None:
+        mock_post.return_value.status_code = 200
+        key_mappings = {"title": "entry.1", "name": "entry.2"}
+        data = [{"title": "Mr", "name": "Alice"}, {"title": "Ms", "name": "Bob"}]
+        results = post_data("https://example.com/formResponse", data, key_mappings)
+        assert len(results) == 2
+        assert results[0]["payload"] == {"entry.1": "Mr", "entry.2": "Alice"}
+        assert results[1]["payload"] == {"entry.1": "Ms", "entry.2": "Bob"}
+
+    @patch("post_to_google_form._submit.requests.post")
+    def test_with_dataframe(self, mock_post: MagicMock) -> None:
+        mock_post.return_value.status_code = 200
+        df = pd.DataFrame([{"entry.1": "A"}])
+        results = post_data("https://example.com/formResponse", df)
+        assert len(results) == 1
+
+    @patch("post_to_google_form._submit.get_form_response_url")
+    @patch("post_to_google_form._submit.requests.post")
+    def test_resolves_url(
+        self, mock_post: MagicMock, mock_resolve: MagicMock
+    ) -> None:
+        mock_resolve.return_value = "https://example.com/formResponse"
+        mock_post.return_value.status_code = 200
+        post_data("https://forms.gle/abc", [{"e.1": "v"}])
+        mock_resolve.assert_called_once_with("https://forms.gle/abc")
+        mock_post.assert_called_once_with(
+            "https://example.com/formResponse",
+            data={"e.1": "v"},
+            timeout=20,
+        )
+
+
+class TestGetFormResponseUrl:
+    def test_already_form_response(self) -> None:
+        url = "https://docs.google.com/forms/d/e/ID/formResponse"
+        assert get_form_response_url(url) == url
+
+    def test_viewform_to_form_response(self) -> None:
+        url = "https://docs.google.com/forms/d/e/ID/viewform"
+        expected = "https://docs.google.com/forms/d/e/ID/formResponse"
+        assert get_form_response_url(url) == expected
+
+    def test_bare_path_appends_form_response(self) -> None:
+        url = "https://docs.google.com/forms/d/e/ID"
+        expected = "https://docs.google.com/forms/d/e/ID/formResponse"
+        assert get_form_response_url(url) == expected
+
+    @patch("requests.get")
+    def test_forms_gle_resolved(self, mock_get: MagicMock) -> None:
+        mock_get.return_value.url = "https://docs.google.com/forms/d/e/ID/viewform"
+        short = "https://forms.gle/abc123"
+        expected = "https://docs.google.com/forms/d/e/ID/formResponse"
+        assert get_form_response_url(short) == expected
+        mock_get.assert_called_once_with(short, allow_redirects=True, timeout=15)
+
+
+class TestParseArgs:
+    def test_defaults(self) -> None:
+        args = parse_args([])
+        assert args.file is None
+        assert args.url is None
+        assert args.key_mappings is None
+
+    def test_with_flags(self) -> None:
+        args = parse_args([
+            "--file", "data.json",
+            "--url", "https://example.com",
+            "--key-mappings", "mapping.json",
+        ])
+        assert args.file == "data.json"
+        assert args.url == "https://example.com"
+        assert args.key_mappings == "mapping.json"
+
+
+class TestMain:
+    def test_missing_file_exits(self) -> None:
+        with pytest.raises(SystemExit):
+            main(["--url", "https://example.com/formResponse"])
+
+    @patch("post_to_google_form.cli.load_dotenv")
+    def test_missing_url_exits(
+        self, mock_load_dotenv: MagicMock, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv("GOOGLE_FORM_URL", "")
+        data_file = Path(__file__).parent / "test_data.json"
+        json.dump([{"entry.1": "Test"}], data_file.open("w"))
+        try:
+            with pytest.raises(SystemExit):
+                main(["--file", str(data_file)])
+        finally:
+            data_file.unlink(missing_ok=True)
+
+    @patch("post_to_google_form._submit.requests.post")
+    def test_submits_rows(self, mock_post: MagicMock) -> None:
+        mock_post.return_value.status_code = 200
+        rows = [{"entry.1": "Alice"}, {"entry.1": "Bob"}]
+        data_file = Path(__file__).parent / "test_data.json"
+        json.dump(rows, data_file.open("w"))
+        try:
+            main(["--file", str(data_file), "--url", "https://example.com/formResponse"])
+        finally:
+            data_file.unlink(missing_ok=True)
+        assert mock_post.call_count == 2
+
+    @patch("post_to_google_form._submit.requests.post")
+    def test_reports_failure(self, mock_post: MagicMock) -> None:
+        mock_post.return_value.status_code = 400
+        rows = [{"entry.1": "Carol"}]
+        data_file = Path(__file__).parent / "test_data.json"
+        json.dump(rows, data_file.open("w"))
+        try:
+            main(["--file", str(data_file), "--url", "https://example.com/formResponse"])
+        finally:
+            data_file.unlink(missing_ok=True)
+        mock_post.assert_called_once()
+
+    def test_read_error_exits(self) -> None:
+        with pytest.raises(SystemExit):
+            main(["--file", "/nonexistent/path.json", "--url", "https://example.com/formResponse"])