gformlib 0.1.1__tar.gz

gformlib-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Andhitia Rama
+
+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.

gformlib-0.1.1/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: gformlib
+Version: 0.1.1
+Summary: Create and manage Google Forms from JSON using the official Google Forms API.
+Author-email: Andhitia Rama <andhitia.r@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Andhitia Rama
+        
+        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/andhit-r/gformlib
+Project-URL: Documentation, https://gformlib.readthedocs.io
+Project-URL: Repository, https://github.com/andhit-r/gformlib
+Project-URL: Bug Tracker, https://github.com/andhit-r/gformlib/issues
+Project-URL: Changelog, https://github.com/andhit-r/gformlib/blob/main/CHANGELOG.md
+Keywords: google,forms,api,survey,automation
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-api-python-client>=2.100.0
+Requires-Dist: google-auth>=2.23.0
+Requires-Dist: google-auth-oauthlib>=1.1.0
+Requires-Dist: google-auth-httplib2>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: pytest-mock>=3.11; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.12; extra == "dev"
+Requires-Dist: mypy>=1.5; extra == "dev"
+Requires-Dist: types-google-cloud-ndb; extra == "dev"
+Requires-Dist: flake8>=6.1; extra == "dev"
+Requires-Dist: tox>=4.11; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.1; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3; extra == "docs"
+Requires-Dist: sphinxcontrib-httpdomain>=1.8; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Dynamic: license-file
+
+# gformlib
+
+[![PyPI version](https://badge.fury.io/py/gformlib.svg)](https://pypi.org/project/gformlib/)
+[![Python versions](https://img.shields.io/pypi/pyversions/gformlib.svg)](https://pypi.org/project/gformlib/)
+[![CI](https://github.com/andhit-r/gformlib/actions/workflows/test.yml/badge.svg)](https://github.com/andhit-r/gformlib/actions/workflows/test.yml)
+[![Documentation Status](https://readthedocs.org/projects/gformlib/badge/?version=latest)](https://gformlib.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![codecov](https://codecov.io/gh/andhit-r/gformlib/branch/main/graph/badge.svg)](https://codecov.io/gh/andhit-r/gformlib)
+
+**gformlib** is a Python library for creating and managing Google Forms programmatically from JSON configurations. It is a high-level wrapper around the official [Google Forms API v1](https://developers.google.com/forms/api/reference/rest).
+
+## Features
+
+- Create Google Forms from a simple Python dict / JSON file
+- All question types supported: short answer, paragraph, multiple choice, checkboxes, dropdown, scale, date, time, file upload
+- Service-account and OAuth 2.0 authentication
+- Full type annotations (PEP 561 compliant)
+- Retrieve form responses with automatic pagination
+- Professional project structure, ready to publish to PyPI
+
+## Installation
+
+```bash
+pip install gformlib
+```
+
+## Quickstart
+
+### 1. Authenticate with a Service Account (recommended for servers)
+
+```python
+from gformlib import GoogleFormsClient
+
+client = GoogleFormsClient.from_service_account("path/to/service_account.json")
+```
+
+### 2. Authenticate with OAuth 2.0 (desktop / installed apps)
+
+```python
+client = GoogleFormsClient.from_oauth_credentials(
+    "client_secrets.json",
+    token_file="token.json",
+)
+```
+
+### 3. Create a form from a dict
+
+```python
+info = client.create_form(
+    {
+        "title": "Customer Satisfaction Survey",
+        "description": "Tell us how we're doing.",
+        "questions": [
+            {
+                "title": "Your name",
+                "type": "short_answer",
+                "required": True,
+            },
+            {
+                "title": "Overall rating",
+                "type": "scale",
+                "low": 1,
+                "high": 5,
+                "low_label": "Poor",
+                "high_label": "Excellent",
+                "required": True,
+            },
+            {
+                "title": "Which features do you use?",
+                "type": "checkboxes",
+                "options": ["Dashboard", "Reports", "API", "Integrations"],
+            },
+            {
+                "title": "Any other comments?",
+                "type": "paragraph",
+            },
+        ],
+    }
+)
+
+print(f"Form ID   : {info.form_id}")
+print(f"Share URL : {info.responder_uri}")
+```
+
+### 4. Read responses
+
+```python
+responses = client.list_responses(info.form_id)
+for r in responses:
+    print(r["responseId"], r.get("answers"))
+```
+
+## Supported question types
+
+| `type` value      | Google Forms equivalent      |
+|-------------------|------------------------------|
+| `short_answer`    | Short answer (single line)   |
+| `paragraph`       | Paragraph (multi-line)       |
+| `multiple_choice` | Multiple choice (radio)      |
+| `checkboxes`      | Checkboxes                   |
+| `dropdown`        | Dropdown                     |
+| `scale`           | Linear scale                 |
+| `date`            | Date                         |
+| `time`            | Time                         |
+| `file_upload`     | File upload                  |
+
+## Authentication setup
+
+### Service Account
+
+1. Create a Service Account in [Google Cloud Console](https://console.cloud.google.com/).
+2. Enable the **Google Forms API** and **Google Drive API**.
+3. Download the JSON key file.
+4. Share the target Google Drive folder with the service account email.
+
+### OAuth 2.0
+
+1. Create an OAuth 2.0 **Desktop app** client in Google Cloud Console.
+2. Download `client_secrets.json`.
+3. On first run, a browser window opens to authorise access.
+4. The token is cached in `token.json` for subsequent runs.
+
+## Development
+
+```bash
+git clone https://github.com/andhit-r/gformlib.git
+cd gformlib
+pip install -e ".[dev]"
+pytest
+```
+
+### Running the full test matrix with tox
+
+```bash
+tox
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

gformlib-0.1.1/README.md

@@ -0,0 +1,144 @@
+# gformlib
+
+[![PyPI version](https://badge.fury.io/py/gformlib.svg)](https://pypi.org/project/gformlib/)
+[![Python versions](https://img.shields.io/pypi/pyversions/gformlib.svg)](https://pypi.org/project/gformlib/)
+[![CI](https://github.com/andhit-r/gformlib/actions/workflows/test.yml/badge.svg)](https://github.com/andhit-r/gformlib/actions/workflows/test.yml)
+[![Documentation Status](https://readthedocs.org/projects/gformlib/badge/?version=latest)](https://gformlib.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![codecov](https://codecov.io/gh/andhit-r/gformlib/branch/main/graph/badge.svg)](https://codecov.io/gh/andhit-r/gformlib)
+
+**gformlib** is a Python library for creating and managing Google Forms programmatically from JSON configurations. It is a high-level wrapper around the official [Google Forms API v1](https://developers.google.com/forms/api/reference/rest).
+
+## Features
+
+- Create Google Forms from a simple Python dict / JSON file
+- All question types supported: short answer, paragraph, multiple choice, checkboxes, dropdown, scale, date, time, file upload
+- Service-account and OAuth 2.0 authentication
+- Full type annotations (PEP 561 compliant)
+- Retrieve form responses with automatic pagination
+- Professional project structure, ready to publish to PyPI
+
+## Installation
+
+```bash
+pip install gformlib
+```
+
+## Quickstart
+
+### 1. Authenticate with a Service Account (recommended for servers)
+
+```python
+from gformlib import GoogleFormsClient
+
+client = GoogleFormsClient.from_service_account("path/to/service_account.json")
+```
+
+### 2. Authenticate with OAuth 2.0 (desktop / installed apps)
+
+```python
+client = GoogleFormsClient.from_oauth_credentials(
+    "client_secrets.json",
+    token_file="token.json",
+)
+```
+
+### 3. Create a form from a dict
+
+```python
+info = client.create_form(
+    {
+        "title": "Customer Satisfaction Survey",
+        "description": "Tell us how we're doing.",
+        "questions": [
+            {
+                "title": "Your name",
+                "type": "short_answer",
+                "required": True,
+            },
+            {
+                "title": "Overall rating",
+                "type": "scale",
+                "low": 1,
+                "high": 5,
+                "low_label": "Poor",
+                "high_label": "Excellent",
+                "required": True,
+            },
+            {
+                "title": "Which features do you use?",
+                "type": "checkboxes",
+                "options": ["Dashboard", "Reports", "API", "Integrations"],
+            },
+            {
+                "title": "Any other comments?",
+                "type": "paragraph",
+            },
+        ],
+    }
+)
+
+print(f"Form ID   : {info.form_id}")
+print(f"Share URL : {info.responder_uri}")
+```
+
+### 4. Read responses
+
+```python
+responses = client.list_responses(info.form_id)
+for r in responses:
+    print(r["responseId"], r.get("answers"))
+```
+
+## Supported question types
+
+| `type` value      | Google Forms equivalent      |
+|-------------------|------------------------------|
+| `short_answer`    | Short answer (single line)   |
+| `paragraph`       | Paragraph (multi-line)       |
+| `multiple_choice` | Multiple choice (radio)      |
+| `checkboxes`      | Checkboxes                   |
+| `dropdown`        | Dropdown                     |
+| `scale`           | Linear scale                 |
+| `date`            | Date                         |
+| `time`            | Time                         |
+| `file_upload`     | File upload                  |
+
+## Authentication setup
+
+### Service Account
+
+1. Create a Service Account in [Google Cloud Console](https://console.cloud.google.com/).
+2. Enable the **Google Forms API** and **Google Drive API**.
+3. Download the JSON key file.
+4. Share the target Google Drive folder with the service account email.
+
+### OAuth 2.0
+
+1. Create an OAuth 2.0 **Desktop app** client in Google Cloud Console.
+2. Download `client_secrets.json`.
+3. On first run, a browser window opens to authorise access.
+4. The token is cached in `token.json` for subsequent runs.
+
+## Development
+
+```bash
+git clone https://github.com/andhit-r/gformlib.git
+cd gformlib
+pip install -e ".[dev]"
+pytest
+```
+
+### Running the full test matrix with tox
+
+```bash
+tox
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

gformlib-0.1.1/pyproject.toml

@@ -0,0 +1,102 @@
+[build-system]
+requires = ["setuptools>=65", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gformlib"
+version = "0.1.1"
+description = "Create and manage Google Forms from JSON using the official Google Forms API."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Andhitia Rama", email = "andhitia.r@gmail.com" }]
+keywords = ["google", "forms", "api", "survey", "automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "google-api-python-client>=2.100.0",
+    "google-auth>=2.23.0",
+    "google-auth-oauthlib>=1.1.0",
+    "google-auth-httplib2>=0.2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "pytest-mock>=3.11",
+    "black>=23.0",
+    "isort>=5.12",
+    "mypy>=1.5",
+    "types-google-cloud-ndb",
+    "flake8>=6.1",
+    "tox>=4.11",
+]
+docs = [
+    "sphinx>=7.1",
+    "sphinx-rtd-theme>=1.3",
+    "sphinxcontrib-httpdomain>=1.8",
+    "myst-parser>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/andhit-r/gformlib"
+Documentation = "https://gformlib.readthedocs.io"
+Repository = "https://github.com/andhit-r/gformlib"
+"Bug Tracker" = "https://github.com/andhit-r/gformlib/issues"
+Changelog = "https://github.com/andhit-r/gformlib/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+gformlib = ["py.typed"]
+
+# ── Black ────────────────────────────────────────────────────────────────────
+[tool.black]
+line-length = 99
+target-version = ["py39", "py310", "py311", "py312"]
+
+# ── isort ────────────────────────────────────────────────────────────────────
+[tool.isort]
+profile = "black"
+line_length = 99
+src_paths = ["src", "tests"]
+
+# ── pytest ───────────────────────────────────────────────────────────────────
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+# ── coverage ─────────────────────────────────────────────────────────────────
+[tool.coverage.run]
+source = ["src/gformlib"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+fail_under = 80
+
+# ── mypy ─────────────────────────────────────────────────────────────────────
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "gformlib.client"
+# google-auth and google-api-python-client lack complete type stubs;
+# all 4 mypy errors in this module originate from their untyped APIs.
+ignore_errors = true

gformlib-0.1.1/setup.cfg

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

gformlib-0.1.1/src/gformlib/__init__.py

@@ -0,0 +1,70 @@
+"""gformlib – Google Forms from JSON.
+
+A Python library for creating and managing Google Forms programmatically,
+wrapping the official `Google Forms API v1`_.
+
+.. _Google Forms API v1: https://developers.google.com/forms/api/reference/rest
+
+Quickstart::
+
+    from gformlib import GoogleFormsClient
+
+    client = GoogleFormsClient.from_service_account("service_account.json")
+    info = client.create_form(
+        {
+            "title": "My Survey",
+            "questions": [
+                {"title": "Your name", "type": "short_answer", "required": True},
+                {
+                    "title": "Rating",
+                    "type": "scale",
+                    "low": 1,
+                    "high": 5,
+                    "low_label": "Poor",
+                    "high_label": "Excellent",
+                },
+            ],
+        }
+    )
+    print(info.responder_uri)
+"""
+
+from .builder import FormBuilder
+from .client import DEFAULT_SCOPES, GoogleFormsClient
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    FormCreationError,
+    FormUpdateError,
+    GFormLibError,
+    InvalidConfigError,
+)
+from .models import FormConfig, FormInfo, QuestionConfig, QuestionType
+from .utils import parse_form_config, parse_question
+
+__all__ = [
+    # Client
+    "GoogleFormsClient",
+    "DEFAULT_SCOPES",
+    # Builder
+    "FormBuilder",
+    # Models
+    "FormConfig",
+    "FormInfo",
+    "QuestionConfig",
+    "QuestionType",
+    # Utils
+    "parse_form_config",
+    "parse_question",
+    # Exceptions
+    "GFormLibError",
+    "AuthenticationError",
+    "FormCreationError",
+    "FormUpdateError",
+    "InvalidConfigError",
+    "APIError",
+]
+
+__version__ = "0.1.0"
+__author__ = "Andhitia Rama"
+__email__ = "andhitia.r@gmail.com"