overturetoosm.objects

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