Source code for smarter.apps.doodle.contract.models

"""
The response of the doodle of the day, ``GET /api/v1/doodles/today/``.

The sign-in page's React app, ``@smarter/doodle``, reads it. Its fields are camelCase.
"""

from typing import Optional

from pydantic import BaseModel, ConfigDict, Field
from pydantic.alias_generators import to_camel

from smarter.apps.doodle.const import LEARN_HOW_URL, DoodleAiCredit
from smarter.lib.typing import SmarterDictType


class DoodleApiModel(BaseModel):
    """The base class of the doodle api's models: camelCase JSON, and no undeclared fields."""

    model_config = ConfigDict(
        extra="forbid",
        alias_generator=to_camel,
        validate_by_name=True,
        validate_by_alias=True,
        serialize_by_alias=True,
    )

    def to_json(self) -> SmarterDictType:
        """The model as the api returns it."""
        return self.model_dump(mode="json")


[docs] class DoodleOfTheDay(DoodleApiModel): """The doodle of a day in a region, as it is planned, before the switches apply.""" date: str = Field(description="The visitor's local date, e.g. 2026-11-08.") region: str = Field(description="The visitor's region, e.g. south-asia.") theme: str = Field(description="The theme's slug, e.g. diwali, or default.") title: str = Field(description="What the doodle celebrates, e.g. Diwali.") caption: str = Field(description="The caption below the artwork, e.g. Happy Diwali! Empty for none.") alt_text: str = Field(description="The artwork's description, for screen readers.") link_url: str = Field(description="Where the caption links to. Empty for nowhere.") image_url: str = Field(description="The artwork's url. It never changes, and may be cached forever.") is_default: bool = Field(description="Whether it is the plain default doodle, which celebrates nothing.") ai_credit: DoodleAiCredit = Field( default="", description=( "What a Smarter AI application did: chosen, the Smarter Doodle Editor chose it; drawn, the " "Smarter Doodle Artist drew it too. Empty when a person or the calendar chose it." ), )
[docs] class DoodleApiResponse(DoodleOfTheDay): """The response of ``GET /api/v1/doodles/today/``: the doodle, and how to show it.""" animated: bool = Field(description="Whether the artwork is animated.") show_caption: bool = Field(description="Whether to show the caption below the artwork.") learn_how_url: str = Field( description="Where the AI credit's Learn how links to: how the doodle is chosen and drawn." ) # pylint: disable=too-many-arguments
[docs] @classmethod def from_doodle( cls, doodle: DoodleOfTheDay, animated: bool, show_caption: bool, show_ai_credit: bool = True, ) -> "DoodleApiResponse": """ Build the response from a planned doodle and the switches. :param doodle: The doodle of the day. :param animated: Whether the artwork may be animated. :param show_caption: Whether the caption may be shown. :param show_ai_credit: Whether the credit of a Smarter AI application may be shown. :returns: The response. :rtype: DoodleApiResponse """ image_url = doodle.image_url if not animated: image_url = with_query(image_url, "still=1") caption_shown = show_caption and bool(doodle.caption) and not doodle.is_default fields = doodle.model_dump(by_alias=False) fields["image_url"] = image_url if not show_ai_credit: fields["ai_credit"] = "" response = cls(**fields, animated=animated, show_caption=caption_shown, learn_how_url=LEARN_HOW_URL) return response
def with_query(url: str, query: Optional[str]) -> str: """ Add a query to a url. :param url: The url. :param query: The query, e.g. ``still=1``. :returns: The url with the query. :rtype: str """ if not query: return url separator = "&" if "?" in url else "?" return f"{url}{separator}{query}" __all__ = ["DoodleApiResponse", "DoodleOfTheDay"]