overturetoosm.objects

  1"""Pydantic models needed throughout the project."""
  2
  3# ruff: noqa: D415
  4
  5from enum import Enum
  6
  7try:
  8    from typing import Annotated
  9except ImportError:
 10    from typing import Annotated
 11
 12from pydantic import BaseModel, ConfigDict, Field, RootModel, field_validator
 13
 14from .resources import places_tags
 15
 16
 17class OvertureBaseModel(BaseModel):
 18    """Base model for Overture features."""
 19
 20    model_config = ConfigDict(extra="forbid")
 21
 22    version: int = Field(ge=0)
 23    theme: str | None = None
 24    type: str | None = None
 25    id: str | None = Field(None, pattern=r"^(\S.*)?\S$")
 26
 27
 28class Wikidata(RootModel):
 29    """Model for transportation segment wikidata."""
 30
 31    root: str = Field(description="Wikidata ID.", pattern=r"^Q\d+")
 32
 33
 34class Sources(BaseModel):
 35    """Overture sources model."""
 36
 37    property: str
 38    dataset: str
 39    record_id: str | None = None
 40    confidence: float | None = Field(ge=0.0, le=1.0)
 41    update_time: str | None = None
 42
 43    @field_validator("confidence")
 44    @classmethod
 45    def set_default_if_none(cls, v: float) -> float:
 46        """@private"""
 47        return v if v is not None else 0.0
 48
 49    def get_osm_link(self) -> str | None:
 50        """Return the OSM link for the source."""
 51        if (
 52            self.record_id
 53            and self.record_id.startswith(("n", "w", "r"))
 54            and self.dataset == "OpenStreetMap"
 55        ):
 56            type_dict = {"n": "node", "w": "way", "r": "relation"}
 57            return f"https://www.openstreetmap.org/{type_dict[self.record_id[0]]}/{self.record_id[1:]}"
 58
 59
 60class RulesVariant(str, Enum):
 61    """Overture name rules variant model."""
 62
 63    alternate = "alternate"
 64    common = "common"
 65    official = "official"
 66    short = "short"
 67
 68
 69class Between(RootModel):
 70    """Model for transportation segment between."""
 71
 72    root: Annotated[list, Field(float, min_length=2, max_length=2)]
 73
 74
 75class Rules(BaseModel):
 76    """Overture name rules model."""
 77
 78    variant: RulesVariant
 79    language: str | None = None
 80    value: str
 81    between: Between | None = None
 82    side: str | None = None
 83
 84
 85class Names(BaseModel):
 86    """Overture names model."""
 87
 88    primary: str
 89    common: dict[str, str] | None
 90    rules: list[Rules] | None
 91
 92
 93class PlaceAddress(BaseModel):
 94    """Overture addresses model."""
 95
 96    freeform: str | None
 97    locality: str | None
 98    postcode: str | None
 99    region: str | None
100    country: str | None = Field(pattern=r"^[A-Z]{2}$")
101
102
103class Categories(BaseModel):
104    """Overture categories model."""
105
106    primary: str
107    alternate: list[str] | None
108
109
110class Brand(BaseModel):
111    """Overture brand model."""
112
113    wikidata: Wikidata | None = None
114    names: Names
115
116    def to_osm(self) -> dict[str, str]:
117        """Convert brand properties to OSM tags."""
118        osm = {"brand": self.names.primary}
119        if self.wikidata:
120            osm.update({"brand:wikidata": str(self.wikidata.root)})
121        return osm
122
123
124class Socials(RootModel):
125    """Overture socials model."""
126
127    root: list[str]
128
129    def to_osm(self) -> dict[str, str]:
130        """Convert socials properties to OSM tags."""
131        new_props = {}
132        for social in self.root:
133            if "facebook" in social:
134                new_props["contact:facebook"] = social
135            elif "twitter" in str(social):
136                new_props["contact:twitter"] = social
137        return new_props
138
139
140class PlaceProps(OvertureBaseModel):
141    """Overture properties model.
142
143    Use this model directly if you want to manipulate the `place` properties yourself.
144    """
145
146    sources: list[Sources]
147    names: Names
148    brand: Brand | None = None
149    categories: Categories | None = None
150    confidence: float = Field(ge=0.0, le=1.0)
151    websites: list[str] | None = None
152    socials: Socials | None = None
153    emails: list[str] | None = None
154    phones: list[str] | None = None
155    addresses: list[PlaceAddress]
156
157    def to_osm(
158        self, confidence: float, region_tag: str, unmatched: str
159    ) -> dict[str, str]:
160        """Convert Overture's place properties to OSM tags.
161
162        Used internally by the `overturetoosm.process_place` function.
163        """
164        new_props = {}
165        if self.confidence < confidence:
166            raise ConfidenceError(confidence, self.confidence)
167
168        if self.categories:
169            prim = places_tags.get(self.categories.primary)
170            if prim:
171                new_props = {**new_props, **prim}
172            elif unmatched == "force":
173                new_props["type"] = self.categories.primary
174            elif unmatched == "error":
175                raise UnmatchedError(self.categories.primary)
176
177        if self.names.primary:
178            new_props["name"] = self.names.primary
179
180        if self.phones is not None:
181            new_props["phone"] = self.phones[0]
182
183        if self.websites is not None and self.websites[0]:
184            new_props["website"] = str(self.websites[0])
185
186        if add := self.addresses[0]:
187            if add.freeform:
188                new_props["addr:street_address"] = add.freeform
189            if add.country:
190                new_props["addr:country"] = add.country
191            if add.postcode:
192                new_props["addr:postcode"] = add.postcode
193            if add.locality:
194                new_props["addr:city"] = add.locality
195            if add.region:
196                new_props[region_tag] = add.region
197
198        if self.sources:
199            new_props["source"] = source_statement(self.sources)
200
201        if self.socials:
202            new_props.update(self.socials.to_osm())
203
204        if self.brand:
205            new_props.update(self.brand.to_osm())
206
207        return new_props
208
209
210class ConfidenceError(Exception):
211    """Confidence error exception.
212
213    This exception is raised when the confidence level of an item is below the
214    user-defined level. It contains the original confidence level and the confidence
215    level of the item.
216
217    Attributes:
218        confidence_level (float): The set confidence level.
219        confidence_item (float): The confidence of the item.
220        message (str): The error message.
221    """
222
223    def __init__(
224        self,
225        confidence_level: float,
226        confidence_item: float,
227        message: str = "Confidence in this item is too low.",
228    ) -> None:
229        """@private"""
230        self.confidence_level = confidence_level
231        self.confidence_item = confidence_item
232        self.message = message
233        super().__init__(message)
234
235    def __str__(self) -> str:
236        """@private"""
237        lev = f"confidence_level={self.confidence_level}"
238        item = f"confidence_item={self.confidence_item}"
239        return f"""{self.message} {lev}, {item}"""
240
241
242class UnmatchedError(Exception):
243    """Unmatched category error.
244
245    This exception is raised when an item's Overture category does not have a
246    corresponding OSM definition. Edit
247    [the OSM Wiki page](https://wiki.openstreetmap.org/wiki/Overture_categories)
248    to add a definition to this category.
249
250    Attributes:
251        category (str): The Overture category that is unmatched.
252        message (str): The error message.
253    """
254
255    def __init__(
256        self, category: str, message: str = "Overture category is unmatched."
257    ) -> None:
258        """@private"""
259        self.category = category
260        self.message = message
261        super().__init__(message)
262
263    def __str__(self) -> str:
264        """@private"""
265        return f"{self.message} {{category={self.category}}}"
266
267
268class BuildingProps(OvertureBaseModel):
269    """Overture building properties.
270
271    Use this model if you want to manipulate the `building` properties yourself.
272    """
273
274    has_parts: bool
275    sources: list[Sources]
276    class_: str | None = Field(alias="class", default=None)
277    subtype: str | None = None
278    names: Names | None = None
279    level: int | None = None
280    height: float | None = None
281    is_underground: bool | None = None
282    num_floors: int | None = Field(serialization_alias="building:levels", default=None)
283    num_floors_underground: int | None = Field(
284        serialization_alias="building:levels:underground", default=None
285    )
286    min_height: float | None = None
287    min_floor: int | None = Field(
288        serialization_alias="building:min_level", default=None
289    )
290    facade_color: str | None = Field(
291        serialization_alias="building:colour", default=None
292    )
293    facade_material: str | None = Field(
294        serialization_alias="building:material", default=None
295    )
296    roof_material: str | None = Field(serialization_alias="roof:material", default=None)
297    roof_shape: str | None = Field(serialization_alias="roof:shape", default=None)
298    roof_direction: str | None = Field(
299        serialization_alias="roof:direction", default=None
300    )
301    roof_orientation: str | None = Field(
302        serialization_alias="roof:orientation", default=None
303    )
304    roof_color: str | None = Field(serialization_alias="roof:colour", default=None)
305    roof_height: float | None = Field(serialization_alias="roof:height", default=None)
306
307    def to_osm(self, confidence: float) -> dict[str, str]:
308        """Convert properties to OSM tags.
309
310        Used internally by`overturetoosm.process_building` function.
311        """
312        new_props = {}
313        confidences = {source.confidence for source in self.sources}
314        if any(conf and conf < confidence for conf in confidences):
315            raise ConfidenceError(confidence, max({i for i in confidences if i}))
316
317        new_props["building"] = self.class_ if self.class_ else "yes"
318
319        new_props["source"] = source_statement(self.sources)
320
321        prop_obj = self.model_dump(exclude_none=True, by_alias=True).items()
322        new_props.update(
323            {k: v for k, v in prop_obj if k.startswith(("roof", "building"))}
324        )
325        new_props.update({k: round(v, 2) for k, v in prop_obj if k.endswith("height")})
326
327        if self.is_underground:
328            new_props["location"] = "underground"
329        if self.names:
330            new_props["name"] = self.names.primary
331        return new_props
332
333
334class AddressLevel(BaseModel):
335    """Overture address level model."""
336
337    value: str
338
339
340class AddressProps(OvertureBaseModel):
341    """Overture address properties.
342
343    Use this model directly if you want to manipulate the `address` properties yourself.
344    """
345
346    number: str | None = Field(serialization_alias="addr:housenumber")
347    street: str | None = Field(serialization_alias="addr:street")
348    postcode: str | None = Field(serialization_alias="addr:postcode")
349    country: str | None = Field(serialization_alias="addr:country")
350    address_levels: (
351        None | (Annotated[list[AddressLevel], Field(min_length=1, max_length=5)])
352    ) = Field(default_factory=list)
353    sources: list[Sources]
354
355    def to_osm(self, style: str) -> dict[str, str]:
356        """Convert properties to OSM tags.
357
358        Used internally by `overturetoosm.process_address`.
359        """
360        obj_dict = {
361            k: v
362            for k, v in self.model_dump(exclude_none=True, by_alias=True).items()
363            if k.startswith("addr:")
364        }
365        obj_dict["source"] = source_statement(self.sources)
366
367        if self.address_levels and len(self.address_levels) > 0 and style == "US":
368            obj_dict["addr:state"] = str(self.address_levels[0].value)
369
370        return obj_dict
371
372
373def source_statement(source: list[Sources]) -> str:
374    """Return a source statement from a list of sources."""
375    return (
376        ", ".join(sorted({i.dataset.strip(", ") for i in source}))
377        + " via overturetoosm"
378    )