Skip to content

Data types

Data types

This SDK uses strong typing for request inputs and helpers. API responses are JSON and are returned as JSON-like dictionaries/lists.

JSON typing

The SDK defines JSON type aliases used across the codebase:

Shared type aliases for Hovercode.

The Hovercode API returns JSON. These type aliases describe JSON values without using Any, which helps keep mypy --strict useful for API client code.

Enums

Enums help you avoid typos when passing common “choice” parameters (like qr_type or pattern). All enum values are sent to the API as their .value string.

Shared enums for the Hovercode API client.

ErrorCorrection

Bases: str, Enum

QR code error correction level.

The API documentation lists these options: - L - M - Q - H

EyeStyle

Bases: str, Enum

QR code eye style.

Frame

Bases: str, Enum

QR code frame name.

Pattern

Bases: str, Enum

QR code pattern style.

QrType

Bases: str, Enum

QR code type.

The API documentation currently lists: - Link: A URL QR code (default). - Text: A plain text QR code (static only).

Models

Models are small dataclasses that help structure request inputs and common response patterns. For example, TagInput helps build payloads for adding tags.

Example: building tag payloads

from hovercode.models import TagInput

tag_1 = TagInput(title="marketing").to_request_dict()
tag_2 = TagInput(id="TAG-ID").to_request_dict()

print(tag_1)  # {"title": "marketing"}
print(tag_2)  # {"id": "TAG-ID"}

Example: parsing paginated responses

from hovercode.models import PaginatedResponse

payload = {
    "count": 2,
    "next": None,
    "previous": None,
    "results": [{"id": "1"}, {"id": "2"}],
}

parsed = PaginatedResponse.from_dict(payload)
print(parsed.count)
print(parsed.results)

Models and helpers for Hovercode requests/responses.

PaginatedResponse dataclass

Pagination wrapper returned by list endpoints.

The Hovercode API includes: - count: total number of results - next: URL for next page (or null) - previous: URL for previous page (or null) - results: list of result objects

Parameters:

Name Type Description Default
count int

Total number of items across all pages.

 required
next Optional[str]

URL of the next page, if any.

 required
previous Optional[str]

URL of the previous page, if any.

 required
results JsonArray

List of result objects.

 required

from_dict(data: Mapping[str, JsonValue]) -> 'PaginatedResponse' classmethod

Parse a paginated API response.

Parameters:

Name Type Description Default
data Mapping[str, JsonValue]

Parsed JSON response from the API.

 required

Returns:

Type Description
'PaginatedResponse'

A PaginatedResponse instance.

Raises:

Type Description
ValidationError

If required keys are missing or have unexpected types.

to_dict() -> JsonObject

Convert this pagination wrapper back to a JSON object.

TagInput dataclass

Tag input for HovercodesClient.add_tags.

The Hovercode API supports adding tags by title or by ID.

Parameters:

Name Type Description Default
title Optional[str]

Tag title. If the tag does not exist, it may be created and added by the API.

 None
id Optional[str]

Tag ID. The tag is only added if it exists.

 None

Raises:

Type Description
ValidationError

If neither title nor id are provided.

to_request_dict() -> JsonObject

Convert to a request payload dictionary.

Returns:

Type Description
JsonObject

A JSON object suitable for the Hovercode API.

Raises:

Type Description
ValidationError

If neither title nor id are provided.