bookalimo 0.1.5__py3-none-any.whl → 1.0.1__py3-none-any.whl

bookalimo/schemas/places/common.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import re
+from enum import IntEnum
+from typing import Optional
+
+from pydantic import (
+    AnyUrl,
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_validator,
+    model_validator,
+)
+from typing_extensions import Self
+
+BCP47 = re.compile(
+    r"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$"
+)  # pragmatic, e.g., "en", "en-US", "zh-Hant"
+
+CLDR_REGION_2 = re.compile(r"^[A-Z]{2}$")  # e.g., "US", "GB"
+
+PLACE_ID = re.compile(
+    r"^[A-Za-z0-9_-]{10,}$"
+)  # pragmatic: real IDs are long base64url-ish e.g., "ChIJN1t_tDeuEmsRUsoyG83frY4"
+
+PLACE_RESOURCE = re.compile(
+    r"^places/[A-Za-z0-9_-]{10,}$"
+)  # e.g., "places/ChIJN1t_tDeuEmsRUsoyG83frY4"
+
+PLACE_TYPE = re.compile(r"^[a-z0-9_]+$")  # e.g., "gas_station", "restaurant"
+
+HEX_COLOR = re.compile(r"^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$")  # #abc, #a1b2c3
+
+PLUS_GLOBAL = re.compile(
+    r"^[23456789CFGHJMPQRVWX]{4,8}\+[23456789CFGHJMPQRVWX]{2,}$"
+)  # Open Location Code (Plus Code), pragmatic
+
+BASE64URL_36 = re.compile(
+    r"^[A-Za-z0-9_-]{1,36}$"
+)  # up to 36 chars, URL-safe base64-ish
+
+
+# ---------- Fundamental types ----------
+class LocalizedText(BaseModel):
+    """Localized text with language code."""
+
+    model_config = ConfigDict(extra="allow")
+
+    text: str
+    language_code: str
+
+    @field_validator("language_code")
+    @classmethod
+    def _language_code(cls, v: str) -> str:
+        if not BCP47.match(v):
+            raise ValueError("language_code must be a valid BCP-47 language tag")
+        return v
+
+
+# ---------- "External" Google message wrappers ----------
+class ExternalModel(BaseModel):
+    """Permissive wrapper for Google messages we don't model in detail."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class OpeningHours(ExternalModel): ...
+
+
+class PostalAddress(ExternalModel): ...
+
+
+class TimeZone(ExternalModel): ...
+
+
+class Timestamp(ExternalModel): ...
+
+
+class Date(ExternalModel): ...
+
+
+class ContentBlock(ExternalModel): ...
+
+
+class Photo(ExternalModel): ...
+
+
+class Review(ExternalModel): ...
+
+
+class FuelOptions(ExternalModel): ...
+
+
+class EVChargeOptions(ExternalModel): ...
+
+
+class AddressDescriptor(BaseModel):
+    """A relational description of a location with nearby landmarks and containing areas."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    class Landmark(BaseModel):
+        """Basic landmark information and relationship with target location."""
+
+        model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+        class SpatialRelationship(IntEnum):
+            """Spatial relationship between target location and landmark."""
+
+            NEAR = 0
+            WITHIN = 1
+            BESIDE = 2
+            ACROSS_THE_ROAD = 3
+            DOWN_THE_ROAD = 4
+            AROUND_THE_CORNER = 5
+            BEHIND = 6
+
+        name: str = Field(..., description="Landmark's resource name")
+        place_id: str = Field(..., description="Landmark's place ID")
+        display_name: LocalizedText = Field(..., description="Landmark's display name")
+        types: list[str] = Field(
+            default_factory=list, description="Type tags for landmark"
+        )
+        spatial_relationship: SpatialRelationship = Field(
+            default=SpatialRelationship.NEAR,
+            description="Spatial relationship to target",
+        )
+        straight_line_distance_meters: float = Field(
+            ..., ge=0.0, description="Straight line distance in meters"
+        )
+        travel_distance_meters: Optional[float] = Field(
+            default=None,
+            ge=0.0,
+            description="Travel distance in meters along road network",
+        )
+
+        @field_validator("name")
+        @classmethod
+        def _name(cls, v: str) -> str:
+            if not PLACE_RESOURCE.fullmatch(v):
+                raise ValueError("name must be in the form 'places/{place_id}'")
+            return v
+
+        @field_validator("place_id")
+        @classmethod
+        def _place_id(cls, v: str) -> str:
+            if not PLACE_ID.fullmatch(v):
+                raise ValueError("place_id must be a valid Place ID")
+            return v
+
+        @field_validator("types")
+        @classmethod
+        def _types(cls, v: list[str]) -> list[str]:
+            out, seen = [], set()
+            for raw in v:
+                t = raw.strip()
+                if not t:
+                    raise ValueError("types cannot contain empty strings")
+                if not PLACE_TYPE.fullmatch(t):
+                    raise ValueError(f"invalid place type '{t}'")
+                if t not in seen:
+                    out.append(t)
+                    seen.add(t)
+            return out
+
+        @model_validator(mode="after")
+        def _name_id_consistency(self) -> Self:
+            if self.name.split("/", 1)[1] != self.place_id:
+                raise ValueError("place_id must match the trailing component of name")
+            return self
+
+    class Area(BaseModel):
+        """Area information and relationship with target location."""
+
+        model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+        class Containment(IntEnum):
+            """Spatial relationship between target location and area."""
+
+            CONTAINMENT_UNSPECIFIED = 0
+            WITHIN = 1
+            OUTSKIRTS = 2
+            NEAR = 3
+
+        name: str = Field(..., description="Area's resource name")
+        place_id: str = Field(..., description="Area's place ID")
+        display_name: LocalizedText = Field(..., description="Area's display name")
+        containment: Containment = Field(
+            default=Containment.CONTAINMENT_UNSPECIFIED,
+            description="Spatial relationship to target",
+        )
+
+        @field_validator("name")
+        @classmethod
+        def _name(cls, v: str) -> str:
+            if not PLACE_RESOURCE.fullmatch(v):
+                raise ValueError("name must be in the form 'places/{place_id}'")
+            return v
+
+        @field_validator("place_id")
+        @classmethod
+        def _place_id(cls, v: str) -> str:
+            if not PLACE_ID.fullmatch(v):
+                raise ValueError("place_id must be a valid Place ID")
+            return v
+
+        @model_validator(mode="after")
+        def _name_id_consistency(self) -> Self:
+            if self.name.split("/", 1)[1] != self.place_id:
+                raise ValueError("place_id must match the trailing component of name")
+            return self
+
+    landmarks: list[Landmark] = Field(
+        default_factory=list, description="Ranked list of nearby landmarks"
+    )
+    areas: list[Area] = Field(
+        default_factory=list, description="Ranked list of containing or adjacent areas"
+    )
+
+    @field_validator("landmarks")
+    @classmethod
+    def _max_landmarks(cls, v: list[Landmark]) -> list[Landmark]:
+        if len(v) > 10:  # Reasonable limit for API responses
+            raise ValueError("landmarks can contain at most 10 items")
+        return v
+
+    @field_validator("areas")
+    @classmethod
+    def _max_areas(cls, v: list[Area]) -> list[Area]:
+        if len(v) > 10:  # Reasonable limit for API responses
+            raise ValueError("areas can contain at most 10 items")
+        return v
+
+
+class PriceRange(ExternalModel): ...
+
+
+# ---------- Geometry ----------
+class LatLng(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    latitude: float = Field(..., description="[-90, 90]")
+    longitude: float = Field(..., description="[-180, 180]")
+
+    @model_validator(mode="after")
+    def _check(self) -> Self:
+        if not (-90 <= self.latitude <= 90):
+            raise ValueError("latitude must be between -90 and 90")
+        if not (-180 <= self.longitude <= 180):
+            raise ValueError("longitude must be between -180 and 180")
+        return self
+
+
+class Viewport(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    high: LatLng
+    low: LatLng
+
+    @model_validator(mode="after")
+    def _lat_order(self) -> Self:
+        if self.high.latitude < self.low.latitude:
+            raise ValueError("high.latitude must be >= low.latitude")
+        return self
+
+
+# ---------- Simple shared types ----------
+class PlusCode(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    global_code: Optional[str] = Field(default=None, description="e.g., '9FWM33GV+HQ'")
+    compound_code: Optional[str] = Field(default=None)
+
+    @field_validator("global_code")
+    @classmethod
+    def _check_global(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        # Accept common formats; be permissive.
+        if not PLUS_GLOBAL.match(v):
+            # Let a variety of valid codes through without being too strict.
+            if "+" not in v or len(v) < 6:
+                raise ValueError(
+                    "global_code must look like a valid plus code (e.g., '9FWM33GV+HQ')."
+                )
+        return v
+
+
+class Attribution(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    provider: str
+    provider_uri: Optional[AnyUrl] = None
+
+
+class SubDestination(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    name: str = Field(..., description="places/{place_id}")
+    id: str = Field(..., description="{place_id}")
+
+    @field_validator("name")
+    @classmethod
+    def _name(cls, v: str) -> str:
+        if not PLACE_RESOURCE.fullmatch(v):
+            raise ValueError("name must be in the form 'places/{place_id}'")
+        return v
+
+    @field_validator("id")
+    @classmethod
+    def _id(cls, v: str) -> str:
+        if not PLACE_ID.fullmatch(v):
+            raise ValueError("id must be a base64url-like token (>=10 chars)")
+        return v
+
+    @model_validator(mode="after")
+    def _match(self) -> Self:
+        if self.name.split("/", 1)[1] != self.id:
+            raise ValueError("id must match the trailing component of name")
+        return self
+
+
+class AccessibilityOptions(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    wheelchair_accessible_parking: Optional[bool] = None
+    wheelchair_accessible_entrance: Optional[bool] = None
+    wheelchair_accessible_restroom: Optional[bool] = None
+    wheelchair_accessible_seating: Optional[bool] = None
+
+
+class PaymentOptions(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    accepts_credit_cards: Optional[bool] = None
+    accepts_debit_cards: Optional[bool] = None
+    accepts_cash_only: Optional[bool] = None
+    accepts_nfc: Optional[bool] = None
+
+
+class ParkingOptions(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    free_parking_lot: Optional[bool] = None
+    paid_parking_lot: Optional[bool] = None
+    free_street_parking: Optional[bool] = None
+    paid_street_parking: Optional[bool] = None
+    valet_parking: Optional[bool] = None
+    free_garage_parking: Optional[bool] = None
+    paid_garage_parking: Optional[bool] = None

bookalimo/schemas/places/field_mask.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import warnings
+from typing import (
+    Any,
+    Callable,
+    Iterable,
+    NewType,
+    Optional,
+    Type,
+    Union,
+    get_args,
+    get_origin,
+)
+
+from pydantic import BaseModel
+
+from .common import ExternalModel
+from .place import GooglePlace
+
+FieldMaskInput = Union[str, "FieldPath", Iterable[Union[str, "FieldPath"]]]
+FieldTreeType = NewType("FieldTreeType", dict[str, Any])
+
+# Sentinel meaning “anything under this node is allowed”
+ANY = object()
+
+
+def _unwrap(t: Any) -> Any:
+    """Unwrap Optional[T], list[T], etc. Return (base_type, is_list)."""
+    origin = get_origin(t)
+    args = get_args(t)
+    # Optional[T] is Union[T, NoneType]
+    if origin is Union and args:
+        non_none = [a for a in args if a is not type(None)]  # noqa: E721
+        if len(non_none) == 1:
+            return _unwrap(non_none[0])
+    if origin in (list, tuple, set):
+        inner = args[0] if args else Any
+        base, _ = _unwrap(inner)
+        return base, True
+    return t, False
+
+
+def _is_model(t: Any) -> bool:
+    try:
+        return issubclass(t, BaseModel)
+    except Exception:
+        return False
+
+
+def _is_external_model(t: Any) -> bool:
+    try:
+        return issubclass(t, ExternalModel)
+    except Exception:
+        return False
+
+
+def build_field_tree(root: Type[BaseModel]) -> FieldTreeType:
+    return _build_field_tree(root)
+
+
+def _build_field_tree(root: Type[BaseModel]) -> FieldTreeType:
+    """
+    Introspect a Pydantic v2 model into a nested dict:
+      { field_name: dict(...) | ANY | None }
+    - dict(...)  => we know nested fields (another BaseModel with declared fields)
+    - ANY        => ExternalModel (extra=allow) or otherwise permissive; allow any nested
+    - None       => leaf / scalar
+    """
+    tree = {}
+
+    # v2: model_fields holds FieldInfo by name
+    for name, fi in root.model_fields.items():
+        t, is_list = _unwrap(fi.annotation)
+        if _is_model(t):
+            if _is_external_model(t):
+                tree[name] = ANY
+            else:
+                # recurse into structured models
+                tree[name] = _build_field_tree(t)
+        else:
+            # Non-model (scalar or collection of scalars)
+            tree[name] = None
+    return FieldTreeType(tree)
+
+
+# Cache once
+_FIELD_TREE = build_field_tree(GooglePlace)
+
+
+def _validate_path(path: str, tree: FieldTreeType) -> Optional[tuple[str, str, str]]:
+    """
+    Validate a dotted path against the field tree.
+    Returns None if OK, else a human-friendly warning string.
+    """
+    parts = path.split(".")
+    node: Any = tree
+    for i, seg in enumerate(parts):
+        if not isinstance(node, dict):
+            warn = f"'{'.'.join(parts[:i])}' is not an object, cannot select '{seg}'"
+            return warn, path, seg
+        if seg not in node:
+            warn = f"Unknown field '{seg}' at '{'.'.join(parts[:i]) or '<root>'}'"
+            return warn, path, seg
+        node = node[seg]
+        if node is ANY:
+            # Wildcard subtree: allow anything under it
+            return None
+    return None  # fully validated
+
+
+def compile_field_mask(
+    fields: FieldMaskInput,
+    *,
+    prefix: str = "",
+    on_warning: Optional[Callable[[str, str, str], None]] = None,
+    allow_star: bool = True,
+    extra_allowed_fields: Optional[list[str]] = None,
+    field_tree: Optional[FieldTreeType] = _FIELD_TREE,
+) -> list[str]:
+    """
+    Normalize + validate a field mask against a Pydantic model.
+    (mirroring the Google Places API `Place` model).
+    - Accepts: iterable of strings or FieldPath objects, or a single string (comma-separated ok).
+    - Dedupes, preserves order.
+    - Prefixes each with 'prefix' unless it already starts with that.
+    - Emits warnings via on_warning(...) but never raises on unknown nested under ExternalModel.
+
+    Args:
+        fields: FieldMaskInput
+        prefix: Prefix to add to each field
+        on_warning: Optional callable on_warning(warn, path, seg) -> None. If not provided, uses the default warning handler.
+        allow_star: Whether to allow the star wildcard
+        extra_allowed_fields: Optional list of fields to allow even if they are not in the field tree.
+        field_tree: Optional field tree to use instead of the default one.
+    Usage:
+    >>> compile_field_mask(F.display_name)
+    ["display_name"]
+    >>> compile_field_mask(["reviews.text", "reviews.author_name"])
+    ["reviews.text"]
+    >>> compile_field_mask("photos.author_attributions,photos.author_attributions.text")
+    ["photos.author_attributions", "photos.author_attributions.text"]
+    """
+    if extra_allowed_fields is None:
+        extra_allowed_fields = []
+    # Flatten to a list of strings
+    if isinstance(fields, str):
+        items: Iterable[str] = sum((s.split(",") for s in fields.split()), [])
+        items = [s.strip() for s in items if s.strip()]
+    elif isinstance(fields, FieldPath):
+        items = [str(fields)]
+    else:
+        items = [str(x).strip() for x in fields if str(x).strip()]
+
+    if not items:
+        return ["*"] if allow_star else []
+
+    seen = set()
+    ordered: list[str] = []
+    for raw in items:
+        if raw == "*":
+            # Keep '*' as-is, but usually only as the sole field
+            if allow_star and "*" not in seen:
+                seen.add("*")
+                ordered = ["*"]  # star trumps everything else
+            continue
+
+        path = raw  # snake_case already; don't transform
+        not_valid = None
+        if path not in extra_allowed_fields:
+            not_valid = _validate_path(path, field_tree or _FIELD_TREE)
+        if not_valid:
+            warn, path, seg = not_valid
+            if on_warning:
+                on_warning(warn, path, seg)
+            else:
+                warnings.warn(warn, UserWarning, stacklevel=2)
+
+        if prefix and not path.startswith(prefix):
+            path = f"{prefix}.{path}"
+
+        if path not in seen:
+            seen.add(path)
+            ordered.append(path)
+
+    # If '*' was included alongside others, Google prefers just '*'
+    if "*" in seen:
+        return ["*"]
+
+    return ordered
+
+
+# ---- Tiny ergonomic builder for dotted paths ----
+class FieldPath:
+    __slots__ = ("path",)
+
+    def __init__(self, path: str):
+        self.path = path
+
+    def __getattr__(self, name: str) -> FieldPath:
+        return FieldPath(f"{self.path}.{name}")
+
+    def __str__(self) -> str:
+        return self.path
+
+
+class _Root:
+    def __getattr__(self, name: str) -> FieldPath:
+        return FieldPath(name)
+
+
+F = _Root()  # Usage: F.display_name, F.reviews.text, F.photos.author_attributions
+
+
+if __name__ == "__main__":
+    print(
+        compile_field_mask(
+            "photos.author_attributions,photos.author_attributions.textt",
+            prefix="places",
+        )
+    )