typekit2 1.0.0__py3-none-any.whl

typekit2/__init__.py

@@ -0,0 +1,14 @@
+# this_file: typekit2/__init__.py
+"""Public API for the typekit2 package."""
+
+from .__version__ import __version__
+from .client import Typekit
+from .exceptions import TypekitAPIError, TypekitConfigurationError, TypekitError
+
+__all__ = [
+    "Typekit",
+    "TypekitAPIError",
+    "TypekitConfigurationError",
+    "TypekitError",
+    "__version__",
+]

typekit2/__main__.py

@@ -0,0 +1,144 @@
+# this_file: typekit2/__main__.py
+"""Fire-powered command-line interface for typekit2."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Sequence
+from typing import Any
+
+import fire
+from dotenv import load_dotenv
+
+from .client import Typekit
+
+
+def parse_csv(value: str | Sequence[str]) -> list[str]:
+    """Parse a comma-separated Fire argument or an existing sequence."""
+    items = value.split(",") if isinstance(value, str) else list(value)
+    parsed = [str(item).strip() for item in items if str(item).strip()]
+    if not parsed:
+        raise ValueError("expected at least one value")
+    return parsed
+
+
+def parse_families(value: str | list[dict[str, Any]] | None) -> list[dict[str, Any]] | None:
+    """Parse a JSON list accepted by create-kit and update-kit."""
+    if value is None or isinstance(value, list):
+        return value
+    parsed = json.loads(value)
+    if not isinstance(parsed, list) or not all(isinstance(item, dict) for item in parsed):
+        raise ValueError("families must be a JSON list of objects")
+    return parsed
+
+
+class TypekitCLI:
+    """Read and manage Adobe Fonts kits and font metadata."""
+
+    @property
+    def client(self) -> Typekit:
+        """Create the API client lazily so help and doctor work without credentials."""
+        return Typekit()
+
+    def doctor(self) -> dict[str, str]:
+        """Check whether TYPEKIT_API_KEY is available without revealing it."""
+        load_dotenv()
+        configured = bool(os.getenv("TYPEKIT_API_KEY", "").strip())
+        return {
+            "api_key": "configured" if configured else "missing",
+            "source": "environment-or-dotenv" if configured else "none",
+        }
+
+    def kits(self) -> list[dict[str, Any]]:
+        """List kits owned by the authenticated user."""
+        return self.client.list_kits()
+
+    def kit(self, kit_id: str, published: bool = False) -> dict[str, Any]:
+        """Get a draft kit or its published version."""
+        return self.client.get_kit(kit_id, published=published)
+
+    def family(self, family: str) -> dict[str, Any]:
+        """Get a font family by ID or slug."""
+        return self.client.get_font_family(family)
+
+    def variations(self, family: str) -> list[str]:
+        """List FVD variation codes for a font family."""
+        return self.client.get_font_variations(family)
+
+    def libraries(self) -> list[dict[str, Any]]:
+        """List font libraries."""
+        return self.client.list_libraries()
+
+    def library(self, library: str, page: int = 1, per_page: int = 100) -> dict[str, Any]:
+        """Get one paginated font library."""
+        return self.client.get_library(library, page=page, per_page=per_page)
+
+    def create_kit(
+        self,
+        name: str,
+        domains: str,
+        families: str | None = None,
+        segmented_css_names: bool | None = None,
+    ) -> dict[str, Any]:
+        """Create a draft kit; domains are CSV and families are a JSON list."""
+        return self.client.create_kit(
+            name,
+            parse_csv(domains),
+            parse_families(families),
+            segmented_css_names,
+        )
+
+    def update_kit(
+        self,
+        kit_id: str,
+        name: str | None = None,
+        domains: str | None = None,
+        families: str | None = None,
+        segmented_css_names: bool | None = None,
+    ) -> dict[str, Any]:
+        """Update supplied draft-kit fields."""
+        return self.client.update_kit(
+            kit_id,
+            name=name,
+            domains=parse_csv(domains) if domains is not None else None,
+            families=parse_families(families),
+            segmented_css_names=segmented_css_names,
+        )
+
+    def remove_kit(self, kit_id: str) -> dict[str, Any]:
+        """Delete a kit. This is a live destructive action."""
+        return self.client.remove_kit(kit_id)
+
+    def publish_kit(self, kit_id: str) -> dict[str, Any]:
+        """Publish the current draft kit to the CDN."""
+        return self.client.publish_kit(kit_id)
+
+    def add_font(
+        self,
+        kit_id: str,
+        family: str,
+        variations: str | None = None,
+        subset: str = "default",
+    ) -> dict[str, Any]:
+        """Add or replace one font family in a draft kit."""
+        parsed = parse_csv(variations) if variations is not None else None
+        return self.client.add_font(kit_id, family, parsed, subset)
+
+    def remove_font(self, kit_id: str, family: str) -> dict[str, Any]:
+        """Remove one font family from a draft kit."""
+        return self.client.remove_font(kit_id, family)
+
+
+def _serialize(value: Any) -> str:
+    """Produce stable JSON for command results."""
+    return json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True)
+
+
+def main() -> None:
+    """Run the typekit2 CLI."""
+    fire.Fire(TypekitCLI, name="typekit2", serialize=_serialize)
+
+
+if __name__ == "__main__":
+    main()

typekit2/__version__.py

@@ -0,0 +1,3 @@
+# this_file: typekit2/__version__.py
+# Generated by hatch-vcs. Do not edit or commit.
+__version__ = version = '1.0.0'

typekit2/client.py

@@ -0,0 +1,246 @@
+# this_file: typekit2/client.py
+"""Adobe Fonts (Typekit) API client."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping, Sequence
+from typing import Any
+from urllib.parse import quote
+
+import requests
+from dotenv import load_dotenv
+
+from .__version__ import __version__
+from .exceptions import TypekitAPIError, TypekitConfigurationError
+
+DEFAULT_BASE_URL = "https://typekit.com/api/v1/json"
+DEFAULT_TIMEOUT = 30.0
+
+FormData = list[tuple[str, str]]
+Family = Mapping[str, Any]
+
+
+def _as_list(value: str | Sequence[str], field: str) -> list[str]:
+    """Parse a non-empty string or sequence at the public API boundary."""
+    values = [value] if isinstance(value, str) else list(value)
+    if not values or not all(isinstance(item, str) and item.strip() for item in values):
+        raise ValueError(f"{field} must contain at least one non-empty string")
+    return [item.strip() for item in values]
+
+
+def _kit_form(
+    *,
+    name: str | None = None,
+    domains: str | Sequence[str] | None = None,
+    families: Sequence[Family] | None = None,
+    segmented_css_names: bool | None = None,
+) -> FormData:
+    """Encode documented Rails-style kit form parameters."""
+    data: FormData = []
+    if name is not None:
+        if not name.strip():
+            raise ValueError("name must not be empty")
+        data.append(("name", name))
+    if domains is not None:
+        data.extend(("domains[]", domain) for domain in _as_list(domains, "domains"))
+    if families is not None:
+        for index, family in enumerate(families):
+            family_id = family.get("id")
+            if not isinstance(family_id, str) or not family_id.strip():
+                raise ValueError(f"families[{index}].id must be a non-empty string")
+            prefix = f"families[{index}]"
+            data.append((f"{prefix}[id]", family_id.strip()))
+            subset = family.get("subset")
+            if subset is not None:
+                if subset not in {"default", "all"}:
+                    raise ValueError(f"families[{index}].subset must be 'default' or 'all'")
+                data.append((f"{prefix}[subset]", subset))
+            variations = family.get("variations")
+            if variations is not None:
+                data.append((f"{prefix}[variations]", ",".join(_as_list(variations, "variations"))))
+    if segmented_css_names is not None:
+        data.append(("segmented_css_names", str(segmented_css_names).lower()))
+    return data
+
+
+class Typekit:
+    """Client for the Adobe Fonts API documented at fonts.adobe.com/docs/api."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        api_token: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: requests.Session | Any | None = None,
+    ) -> None:
+        load_dotenv()
+        key = api_key or api_token or os.getenv("TYPEKIT_API_KEY")
+        if not key or not key.strip():
+            raise TypekitConfigurationError(
+                "Set TYPEKIT_API_KEY in the environment or .env, or pass api_key explicitly"
+            )
+        if not base_url.startswith("https://"):
+            raise TypekitConfigurationError("Authenticated API requests require an HTTPS base URL")
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+        self.api_key = key.strip()
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        data: FormData | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make an authenticated request and return the decoded JSON object."""
+        kwargs: dict[str, Any] = {
+            "headers": {
+                "User-Agent": f"typekit2/{__version__}",
+                "X-Typekit-Token": self.api_key,
+            },
+            "timeout": self.timeout,
+        }
+        if data is not None:
+            kwargs["data"] = data
+        if params is not None:
+            kwargs["params"] = dict(params)
+        try:
+            response = self.session.request(
+                method.upper(), f"{self.base_url}/{path.lstrip('/')}", **kwargs
+            )
+            response.raise_for_status()
+            payload = response.json()
+        except requests.RequestException as error:
+            status = getattr(getattr(error, "response", None), "status_code", None)
+            raise TypekitAPIError(
+                f"Adobe Fonts request failed: {error}", status_code=status
+            ) from error
+        except ValueError as error:
+            raise TypekitAPIError("Adobe Fonts returned invalid JSON") from error
+        if not isinstance(payload, dict):
+            raise TypekitAPIError("Adobe Fonts returned a non-object JSON response")
+        errors = payload.get("errors")
+        if errors:
+            normalized = errors if isinstance(errors, list) else [errors]
+            raise TypekitAPIError("Adobe Fonts API returned errors", errors=normalized)
+        return payload
+
+    def list_kits(self) -> list[dict[str, Any]]:
+        """Return kits owned by the authenticated user."""
+        return self.request("GET", "kits").get("kits", [])
+
+    def get_kit(self, kit_id: str, *, published: bool = False) -> dict[str, Any]:
+        """Return a draft kit, or its published version when requested."""
+        suffix = "/published" if published else ""
+        return self.request("GET", f"kits/{quote(kit_id, safe='')}{suffix}")
+
+    def get_published_kit(self, kit_id: str) -> dict[str, Any]:
+        """Return the version of a kit currently published to the CDN."""
+        return self.get_kit(kit_id, published=True)
+
+    def create_kit(
+        self,
+        name: str,
+        domains: str | Sequence[str],
+        families: Sequence[Family] | None = None,
+        segmented_css_names: bool | None = None,
+    ) -> dict[str, Any]:
+        """Create a draft kit."""
+        data = _kit_form(
+            name=name,
+            domains=domains,
+            families=families,
+            segmented_css_names=segmented_css_names,
+        )
+        return self.request("POST", "kits", data=data)
+
+    def update_kit(
+        self,
+        kit_id: str,
+        name: str | None = None,
+        domains: str | Sequence[str] | None = None,
+        families: Sequence[Family] | None = None,
+        segmented_css_names: bool | None = None,
+    ) -> dict[str, Any]:
+        """Replace only the supplied draft-kit attributes."""
+        data = _kit_form(
+            name=name,
+            domains=domains,
+            families=families,
+            segmented_css_names=segmented_css_names,
+        )
+        if not data:
+            raise ValueError("update_kit requires at least one field")
+        return self.request("POST", f"kits/{quote(kit_id, safe='')}", data=data)
+
+    def remove_kit(self, kit_id: str) -> dict[str, Any]:
+        """Delete a kit."""
+        return self.request("DELETE", f"kits/{quote(kit_id, safe='')}")
+
+    def publish_kit(self, kit_id: str) -> dict[str, Any]:
+        """Publish the current draft kit asynchronously."""
+        return self.request("POST", f"kits/{quote(kit_id, safe='')}/publish")
+
+    def get_font_family(self, family: str) -> dict[str, Any]:
+        """Return a font family by ID or slug."""
+        return self.request("GET", f"families/{quote(family, safe='')}")
+
+    def get_font_variations(self, family: str) -> list[str]:
+        """Return Font Variation Description values for a family."""
+        variations = self.get_font_family(family).get("family", {}).get("variations", [])
+        return [item["fvd"] for item in variations if isinstance(item, dict) and "fvd" in item]
+
+    def list_libraries(self) -> list[dict[str, Any]]:
+        """Return available Adobe Fonts libraries."""
+        return self.request("GET", "libraries").get("libraries", [])
+
+    def get_library(self, library: str, *, page: int = 1, per_page: int = 100) -> dict[str, Any]:
+        """Return a paginated font library."""
+        if page < 1 or per_page < 1:
+            raise ValueError("page and per_page must be positive integers")
+        return self.request(
+            "GET",
+            f"libraries/{quote(library, safe='')}",
+            params={"page": page, "per_page": per_page},
+        )
+
+    def add_font(
+        self,
+        kit_id: str,
+        family: str,
+        variations: str | Sequence[str] | None = None,
+        subset: str = "default",
+    ) -> dict[str, Any]:
+        """Add or replace one font family in a draft kit."""
+        if subset not in {"default", "all"}:
+            raise ValueError("subset must be 'default' or 'all'")
+        data: FormData = [("subset", subset)]
+        if variations is not None:
+            data.append(("variations", ",".join(_as_list(variations, "variations"))))
+        path = f"kits/{quote(kit_id, safe='')}/families/{quote(family, safe='')}"
+        return self.request("POST", path, data=data)
+
+    def remove_font(self, kit_id: str, family: str) -> dict[str, Any]:
+        """Remove one font family from a draft kit."""
+        path = f"kits/{quote(kit_id, safe='')}/families/{quote(family, safe='')}"
+        return self.request("DELETE", path)
+
+    def kit_contains_font(self, kit_id: str, family: str) -> bool:
+        """Return whether the draft kit contains the resolved family ID."""
+        family_id = self.get_font_family(family).get("family", {}).get("id")
+        return family_id in self.get_kit_fonts(kit_id)
+
+    def get_kit_fonts(self, kit_id: str) -> list[str]:
+        """Return family IDs in a draft kit."""
+        families = self.get_kit(kit_id).get("kit", {}).get("families", [])
+        return [item["id"] for item in families if isinstance(item, dict) and "id" in item]
+
+    kit_add_font = add_font
+    kit_remove_font = remove_font

typekit2/exceptions.py

@@ -0,0 +1,29 @@
+# this_file: typekit2/exceptions.py
+"""Typed errors raised by typekit2."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class TypekitError(Exception):
+    """Base class for all package errors."""
+
+
+class TypekitConfigurationError(TypekitError):
+    """The client cannot be configured from explicit arguments or the environment."""
+
+
+class TypekitAPIError(TypekitError):
+    """Adobe Fonts rejected a request or returned an invalid response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        errors: list[Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.errors = errors or []

typekit2-1.0.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: typekit2
+Version: 1.0.0
+Summary: Modern Python client and CLI for the Adobe Fonts (Typekit) API
+Project-URL: Documentation, https://fonts.adobe.com/docs/api
+Project-URL: Repository, https://github.com/fontlaborg/typekit-python
+Author-email: Suchan Lee <lee.suchan@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adobe-fonts,api,cli,typekit
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: fire>=0.7.1
+Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: requests>=2.32.5
+Description-Content-Type: text/markdown
+
+---
+this_file: README.md
+---
+
+# typekit2
+
+`typekit2` is a modern Python client and Fire CLI for the Adobe Fonts API formerly known as the Typekit API.
+
+It replaces the abandoned `typekit` package’s Python 2 code and `setup.py` packaging with Python 3.10+, `pyproject.toml`, HTTPS header authentication, `.env` support, offline tests, and Git-tag-derived versions.
+
+## Install
+
+```bash
+uv add typekit2
+```
+
+For local development:
+
+```bash
+uv sync
+```
+
+Create `.env` from the supplied example, or export the key directly:
+
+```bash
+cp .env.example .env
+export TYPEKIT_API_KEY='your-token'
+```
+
+`python-dotenv` loads `.env` without overriding an existing environment variable. Never commit `.env`; it is ignored.
+
+## Python API
+
+```python
+from typekit2 import Typekit
+
+client = Typekit()  # reads TYPEKIT_API_KEY
+
+kits = client.list_kits()
+family = client.get_font_family("pcpv")
+variations = client.get_font_variations("pcpv")
+library = client.get_library("full", page=1, per_page=50)
+```
+
+An explicit key is also supported:
+
+```python
+client = Typekit(api_key="...")
+```
+
+The compatibility keyword `api_token=` is accepted, but new code should use `api_key=` or `TYPEKIT_API_KEY`.
+
+### Kit workflow
+
+```python
+created = client.create_kit(
+    "Example",
+    ["example.com", "www.example.com"],
+    [{"id": "pcpv", "subset": "all", "variations": ["n4", "i4"]}],
+)
+kit_id = created["kit"]["id"]
+
+client.update_kit(kit_id, name="Example renamed")
+client.add_font(kit_id, "gkmg", variations=["n4", "n7"])
+client.publish_kit(kit_id)
+```
+
+Publishing is asynchronous. Adobe documents that CDN propagation may take several minutes.
+
+## CLI
+
+The installed `typekit2` command and `python -m typekit2` expose the same Fire CLI. Results are stable JSON.
+
+```bash
+typekit2 doctor
+typekit2 kits
+typekit2 kit abc123
+typekit2 kit abc123 --published=true
+typekit2 family pcpv
+typekit2 variations pcpv
+typekit2 libraries
+typekit2 library full --page=1 --per-page=50
+```
+
+Mutating commands are explicit:
+
+```bash
+typekit2 create-kit Example --domains=example.com,www.example.com
+typekit2 add-font abc123 pcpv --variations=n4,i4 --subset=all
+typekit2 update-kit abc123 --name='Renamed kit'
+typekit2 publish-kit abc123
+typekit2 remove-font abc123 pcpv
+typekit2 remove-kit abc123
+```
+
+For `--families`, pass a JSON list:
+
+```bash
+typekit2 create-kit Example \
+  --domains=example.com \
+  --families='[{"id":"pcpv","subset":"all","variations":["n4","i4"]}]'
+```
+
+Run `typekit2 --help` or `python -m typekit2 --help` for generated Fire help.
+
+## API behavior
+
+- Requests use `https://typekit.com/api/v1/json`.
+- Authentication uses the documented `X-Typekit-Token` header; keys never enter URLs or CLI output.
+- Kit writes use URL-encoded Rails-style nested parameters.
+- A 30-second timeout is applied by default and can be changed with `Typekit(timeout=...)`.
+- HTTP, JSON, and documented API errors raise `TypekitAPIError`.
+- `update_kit` sends only supplied fields; omitted fields are not replaced accidentally.
+
+See [docs/API.md](docs/API.md) for the method-to-endpoint map and links to Adobe’s authoritative documentation.
+
+## Development
+
+```bash
+./test.sh
+```
+
+The suite is offline: it uses request doubles and never creates, publishes, or deletes a real kit.
+
+## Releases
+
+Versions come from Git tags through `hatch-vcs`; generated `typekit2/__version__.py` is explicitly ignored. To validate, commit/tag/push the next semantic version, build fresh distributions, and publish with `uv`:
+
+```bash
+./publish.sh
+```
+
+Set `PUBLISH_SKIP_UPLOAD=1` to exercise the Git release and artifact verification flow without uploading to PyPI. `UV_PUBLISH_TOKEN` supplies a PyPI token when Trusted Publishing is unavailable.
+
+## License and provenance
+
+MIT. The project began as `typekit-python` by Suchan Lee; `typekit2` is its Python 3 modernization.

typekit2-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+typekit2/__init__.py,sha256=pJjFbgyNBw5vE-83-36wJQPdqMWpSYJPNYalbHbDHgU,349
+typekit2/__main__.py,sha256=q4VYnA9fEmmaYdZ9RZ9ZLfW0BkPwwW45f_HV4pvl7J4,4904
+typekit2/__version__.py,sha256=i42Ptxf7aHcFJy2doJ2pAQfHslrfyjzIcTX5tyWcfaE,118
+typekit2/client.py,sha256=od7tiryCLyhBDISVYbvOEOdKq1UTfOoluB2Tm_dNMHM,9934
+typekit2/exceptions.py,sha256=iZ7vu7fPMrkD6jzLgChKFPIsLryvmzUm7zlV_Ud0i30,731
+typekit2-1.0.0.dist-info/METADATA,sha256=eJ3FysEWM89r0upfhj6OVqDuU_Hpcg9e5b9yDt0dG1I,4776
+typekit2-1.0.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+typekit2-1.0.0.dist-info/entry_points.txt,sha256=qKLBuYUeWOtjEZrnpzWCGf4zrIvewpclMF_Bo9nrtR0,52
+typekit2-1.0.0.dist-info/licenses/LICENSE,sha256=k5N3-GTdfsQxacdzsWbI7KNg2rhUyX77tELdYpwdrOI,1076
+typekit2-1.0.0.dist-info/RECORD,,

typekit2-1.0.0.dist-info/WHEEL

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

typekit2-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+typekit2 = typekit2.__main__:main

typekit2-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Suchan Lee
+
+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.