Add helpers for creating and retrieving GitHub gists

Author: beauagainagainagainagainagain

web_programming/github_gist.py

@@ -0,0 +1,118 @@
+"""Utilities for creating and retrieving GitHub gists."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import requests
+
+BASE_URL = "https://api.github.com"
+CREATE_GIST_ENDPOINT = f"{BASE_URL}/gists"
+
+# GitHub recommends using personal access tokens to authenticate requests.
+# The tests patch the network calls so the token can be left empty when running
+# locally, but an actual token will be required when using the module for real
+# interactions with the GitHub API.
+GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")
+
+
+class GitHubAPIError(RuntimeError):
+    """Raised when the GitHub API returns an error response."""
+
+
+def _build_headers(auth_token: str | None) -> dict[str, str]:
+    headers: dict[str, str] = {"Accept": "application/vnd.github.v3+json"}
+    if auth_token:
+        headers["Authorization"] = f"token {auth_token}"
+    return headers
+
+
+def create_gist(
+    description: str,
+    files: dict[str, dict[str, str]],
+    *,
+    public: bool = True,
+    auth_token: str | None = None,
+) -> dict[str, Any]:
+    """Create a GitHub gist.
+
+    Parameters
+    ----------
+    description:
+        A short description that appears above the gist files.
+    files:
+        Mapping of file names to dictionaries containing a ``content`` key with
+        the file contents.
+    public:
+        Set to ``True`` to create a public gist, otherwise the gist will be
+        secret.
+    auth_token:
+        Optional personal access token. If not supplied, the function will fall
+        back to the value of ``GITHUB_TOKEN`` from the environment.
+
+    Returns
+    -------
+    dict
+        The JSON response from the GitHub API describing the newly created
+        gist.
+
+    Raises
+    ------
+    GitHubAPIError
+        If the API returns a non-success status code.
+    """
+
+    token = auth_token if auth_token is not None else GITHUB_TOKEN
+    headers = _build_headers(token)
+    payload = {"description": description, "public": public, "files": files}
+
+    response = requests.post(CREATE_GIST_ENDPOINT, json=payload, headers=headers, timeout=10)
+    if response.status_code >= 400:
+        raise GitHubAPIError(response.text)
+    return response.json()
+
+
+def get_gist(gist_id: str, auth_token: str | None = None) -> dict[str, Any]:
+    """Retrieve a gist by its identifier.
+
+    Parameters
+    ----------
+    gist_id:
+        Unique identifier of the gist returned by :func:`create_gist`.
+    auth_token:
+        Optional personal access token. If omitted the ``GITHUB_TOKEN``
+        environment variable will be used.
+
+    Returns
+    -------
+    dict
+        Parsed JSON describing the gist.
+
+    Raises
+    ------
+    GitHubAPIError
+        If the API returns a non-success status code.
+    """
+
+    token = auth_token if auth_token is not None else GITHUB_TOKEN
+    headers = _build_headers(token)
+    endpoint = f"{CREATE_GIST_ENDPOINT}/{gist_id}"
+    response = requests.get(endpoint, headers=headers, timeout=10)
+    if response.status_code >= 400:
+        raise GitHubAPIError(response.text)
+    return response.json()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    if not GITHUB_TOKEN:
+        raise ValueError("'GITHUB_TOKEN' field cannot be empty.")
+
+    example_files = {"file1.txt": {"content": "Aren't gists great!"}}
+    gist_data = create_gist("Example gist created from Python", example_files)
+    gist_id = gist_data.get("id", "")
+    if gist_id:
+        retrieved = get_gist(gist_id)
+        print(f"Created gist {gist_id} containing {len(retrieved.get('files', {}))} file(s).")
+    else:
+        print("Failed to create gist.")

web_programming/test_github_gist.py

@@ -0,0 +1,71 @@
+import json
+from typing import Any
+
+import pytest
+import requests
+
+from .github_gist import CREATE_GIST_ENDPOINT, GitHubAPIError, create_gist, get_gist
+
+
+class FakeResponse:
+    def __init__(self, status_code: int, data: dict[str, Any] | None = None, text: str = "") -> None:
+        self.status_code = status_code
+        self._data = data or {}
+        self.text = text
+
+    def json(self) -> dict[str, Any]:
+        return json.loads(json.dumps(self._data))
+
+
+def test_create_gist(monkeypatch):
+    expected_payload = {
+        "description": "My first gist",
+        "public": True,
+        "files": {"file1.txt": {"content": "Aren't gists great!"}},
+    }
+
+    def mock_post(url, *, json, headers, timeout):  # noqa: A002 - required signature
+        assert url == CREATE_GIST_ENDPOINT
+        assert json == expected_payload
+        assert headers["Accept"] == "application/vnd.github.v3+json"
+        assert headers["Authorization"].startswith("token ")
+        assert timeout == 10
+        data = {"id": "example-id", "files": expected_payload["files"]}
+        return FakeResponse(201, data)
+
+    monkeypatch.setattr(requests, "post", mock_post)
+
+    response = create_gist(
+        description="My first gist",
+        files={"file1.txt": {"content": "Aren't gists great!"}},
+        auth_token="abc123",
+    )
+    assert response["id"] == "example-id"
+    assert "file1.txt" in response["files"]
+
+
+def test_get_gist(monkeypatch):
+    gist_id = "example-id"
+    expected = {"id": gist_id, "files": {"file1.txt": {"content": "data"}}}
+
+    def mock_get(url, *, headers, timeout):
+        assert url == f"{CREATE_GIST_ENDPOINT}/{gist_id}"
+        assert headers["Accept"] == "application/vnd.github.v3+json"
+        assert headers["Authorization"].startswith("token ")
+        assert timeout == 10
+        return FakeResponse(200, expected)
+
+    monkeypatch.setattr(requests, "get", mock_get)
+
+    response = get_gist(gist_id, auth_token="abc123")
+    assert response == expected
+
+
+def test_error_is_raised_on_failure(monkeypatch):
+    def mock_post(url, *, json, headers, timeout):  # noqa: A002 - required signature
+        return FakeResponse(422, text="unprocessable")
+
+    monkeypatch.setattr(requests, "post", mock_post)
+
+    with pytest.raises(GitHubAPIError):
+        create_gist("desc", {"file.txt": {"content": "data"}}, auth_token="token")