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 Mode(str, Enum):
 76    """Model for political perspectives from which a named feature is viewed."""
 77
 78    accepted_by = "accepted_by"
 79    disputed_by = "disputed_by"
 80
 81
 82class Perspectives(BaseModel):
 83    """Model for political perspectives from which a named feature is viewed."""
 84
 85    mode: Mode
 86    countries: list[str] = Field(min_length=1)
 87
 88
 89class Rules(BaseModel):
 90    """Overture name rules model."""
 91
 92    variant: RulesVariant
 93    language: str | None = None
 94    value: str
 95    between: Between | None = None
 96    side: str | None = None
 97    perspectives: Perspectives | None = None
 98
 99
100class Names(BaseModel):
101    """Overture names model."""
102
103    primary: str
104    common: list[tuple[str, str]] | None
105    rules: list[Rules] | None
106
107    def to_osm(self) -> dict[str, str]:
108        """Convert names to OSM tags."""
109        names = {}
110        if self.primary:
111            names["name"] = self.primary
112
113        return names
114
115
116class PlaceAddress(BaseModel):
117    """Overture addresses model."""
118
119    freeform: str | None
120    locality: str | None
121    postcode: str | None
122    region: str | None
123    country: str | None = Field(pattern=r"^[A-Z]{2}$")
124
125    def to_osm(self, region_tag: str) -> dict[str, str]:
126        """Convert address to OSM tags."""
127        address_info = {}
128        if self.freeform:
129            address_info["addr:street_address"] = self.freeform
130        if self.country:
131            address_info["addr:country"] = self.country
132        if self.postcode:
133            address_info["addr:postcode"] = self.postcode
134        if self.locality:
135            address_info["addr:city"] = self.locality
136        if self.region:
137            address_info[region_tag] = self.region
138
139        return address_info
140
141
142class Categories(BaseModel):
143    """Overture categories model."""
144
145    primary: str
146    alternate: list[str] | None
147
148    def to_osm(self, unmatched: str) -> dict[str, str]:
149        """Convert categories to OSM tags."""
150        prim = places_tags.get(self.primary)
151        if prim:
152            return prim
153        elif unmatched == "force":
154            return {"type": self.primary}
155        elif unmatched == "error":
156            raise UnmatchedError(self.primary)
157        return {}
158
159
160class Brand(BaseModel):
161    """Overture brand model."""
162
163    wikidata: Wikidata | None = None
164    names: Names
165
166    def to_osm(self) -> dict[str, str]:
167        """Convert brand properties to OSM tags."""
168        osm = {"brand": self.names.primary}
169        if self.wikidata:
170            osm.update({"brand:wikidata": str(self.wikidata.root)})
171        return osm
172
173
174class Socials(RootModel):
175    """Overture socials model."""
176
177    root: list[str]
178
179    def to_osm(self) -> dict[str, str]:
180        """Convert socials properties to OSM tags."""
181        new_props = {}
182        for social in self.root:
183            if "facebook" in social:
184                new_props["contact:facebook"] = social
185            elif "twitter" in str(social):
186                new_props["contact:twitter"] = social
187        return new_props
188
189
190class PlaceProps(OvertureBaseModel):
191    """Overture properties model.
192
193    Use this model directly if you want to manipulate the `place` properties yourself.
194    """
195
196    sources: list[Sources]
197    names: Names
198    brand: Brand | None = None
199    categories: Categories | None = None
200    confidence: float = Field(ge=0.0, le=1.0)
201    websites: list[str] | None = None
202    socials: Socials | None = None
203    emails: list[str] | None = None
204    phones: list[str] | None = None
205    addresses: list[PlaceAddress]
206
207    def to_osm(
208        self, confidence: float, region_tag: str, unmatched: str
209    ) -> dict[str, str]:
210        """Convert Overture's place properties to OSM tags.
211
212        Used internally by the `overturetoosm.process_place` function.
213        """
214        if self.confidence < confidence:
215            raise ConfidenceError(confidence, self.confidence)
216
217        new_props = {}
218
219        # Categories
220        if self.categories:
221            new_props.update(self.categories.to_osm(unmatched))
222
223        # Names
224        if self.names:
225            new_props.update(self.names.to_osm())
226
227        # Contact information
228        new_props.update(self._process_contact_info())
229
230        # Addresses
231        if self.addresses:
232            new_props.update(self.addresses[0].to_osm(region_tag))
233
234        # Sources
235        new_props["source"] = source_statement(self.sources)
236
237        # Socials and Brand
238        if self.socials:
239            new_props.update(self.socials.to_osm())
240        if self.brand:
241            new_props.update(self.brand.to_osm())
242
243        return new_props
244
245    def _process_contact_info(self) -> dict[str, str]:
246        """Process contact information."""
247        contact_info = {}
248        if self.phones is not None:
249            contact_info["phone"] = self.phones[0]
250        if self.websites is not None and self.websites[0]:
251            contact_info["website"] = str(self.websites[0])
252        return contact_info
253
254
255class ConfidenceError(Exception):
256    """Confidence error exception.
257
258    This exception is raised when the confidence level of an item is below the
259    user-defined level. It contains the original confidence level and the confidence
260    level of the item.
261
262    Attributes:
263        confidence_level (float): The set confidence level.
264        confidence_item (float): The confidence of the item.
265        message (str): The error message.
266    """
267
268    def __init__(
269        self,
270        confidence_level: float,
271        confidence_item: float,
272        message: str = "Confidence in this item is too low.",
273    ) -> None:
274        """@private"""
275        self.confidence_level = confidence_level
276        self.confidence_item = confidence_item
277        self.message = message
278        super().__init__(message)
279
280    def __str__(self) -> str:
281        """@private"""
282        lev = f"confidence_level={self.confidence_level}"
283        item = f"confidence_item={self.confidence_item}"
284        return f"""{self.message} {lev}, {item}"""
285
286
287class UnmatchedError(Exception):
288    """Unmatched category error.
289
290    This exception is raised when an item's Overture category does not have a
291    corresponding OSM definition. Edit
292    [the OSM Wiki page](https://wiki.openstreetmap.org/wiki/Overture_categories)
293    to add a definition to this category.
294
295    Attributes:
296        category (str): The Overture category that is unmatched.
297        message (str): The error message.
298    """
299
300    def __init__(
301        self, category: str, message: str = "Overture category is unmatched."
302    ) -> None:
303        """@private"""
304        self.category = category
305        self.message = message
306        super().__init__(message)
307
308    def __str__(self) -> str:
309        """@private"""
310        return f"{self.message} {{category={self.category}}}"
311
312
313class BuildingProps(OvertureBaseModel):
314    """Overture building properties.
315
316    Use this model if you want to manipulate the `building` properties yourself.
317    """
318
319    has_parts: bool
320    sources: list[Sources]
321    class_: str | None = Field(alias="class", default=None)
322    subtype: str | None = None
323    names: Names | None = None
324    level: int | None = None
325    height: float | None = None
326    is_underground: bool | None = None
327    num_floors: int | None = Field(serialization_alias="building:levels", default=None)
328    num_floors_underground: int | None = Field(
329        serialization_alias="building:levels:underground", default=None
330    )
331    min_height: float | None = None
332    min_floor: int | None = Field(
333        serialization_alias="building:min_level", default=None
334    )
335    facade_color: str | None = Field(
336        serialization_alias="building:colour", default=None
337    )
338    facade_material: str | None = Field(
339        serialization_alias="building:material", default=None
340    )
341    roof_material: str | None = Field(serialization_alias="roof:material", default=None)
342    roof_shape: str | None = Field(serialization_alias="roof:shape", default=None)
343    roof_direction: str | None = Field(
344        serialization_alias="roof:direction", default=None
345    )
346    roof_orientation: str | None = Field(
347        serialization_alias="roof:orientation", default=None
348    )
349    roof_color: str | None = Field(serialization_alias="roof:colour", default=None)
350    roof_height: float | None = Field(serialization_alias="roof:height", default=None)
351
352    def to_osm(self, confidence: float) -> dict[str, str]:
353        """Convert properties to OSM tags.
354
355        Used internally by`overturetoosm.process_building` function.
356        """
357        new_props = {}
358        confidences = {source.confidence for source in self.sources}
359        if any(conf and conf < confidence for conf in confidences):
360            raise ConfidenceError(confidence, max({i for i in confidences if i}))
361
362        new_props["building"] = self.class_ if self.class_ else "yes"
363
364        new_props["source"] = source_statement(self.sources)
365
366        prop_obj = self.model_dump(exclude_none=True, by_alias=True).items()
367        new_props.update(
368            {k: v for k, v in prop_obj if k.startswith(("roof", "building"))}
369        )
370        new_props.update({k: round(v, 2) for k, v in prop_obj if k.endswith("height")})
371
372        if self.is_underground:
373            new_props["location"] = "underground"
374        if self.names:
375            new_props["name"] = self.names.primary
376        return new_props
377
378
379class AddressLevel(BaseModel):
380    """Overture address level model."""
381
382    value: str
383
384
385class AddressProps(OvertureBaseModel):
386    """Overture address properties.
387
388    Use this model directly if you want to manipulate the `address` properties yourself.
389    """
390
391    number: str | None = Field(serialization_alias="addr:housenumber", default=None)
392    street: str | None = Field(serialization_alias="addr:street", default=None)
393    unit: str | None = Field(serialization_alias="addr:unit", default=None)
394    postcode: str | None = Field(serialization_alias="addr:postcode", default=None)
395    postal_city: str | None = Field(serialization_alias="addr:city", default=None)
396    country: str | None = Field(serialization_alias="addr:country", default=None)
397    address_levels: (
398        None | (Annotated[list[AddressLevel], Field(min_length=1, max_length=5)])
399    ) = Field(default_factory=list)
400    sources: list[Sources]
401
402    def to_osm(self, style: str) -> dict[str, str]:
403        """Convert properties to OSM tags.
404
405        Used internally by `overturetoosm.process_address`.
406        """
407        obj_dict = {
408            k: v
409            for k, v in self.model_dump(exclude_none=True, by_alias=True).items()
410            if k.startswith("addr:")
411        }
412        obj_dict["source"] = source_statement(self.sources)
413
414        if self.address_levels and len(self.address_levels) > 0 and style == "US":
415            obj_dict["addr:state"] = str(self.address_levels[0].value)
416
417        return obj_dict
418
419
420def source_statement(source: list[Sources]) -> str:
421    """Return a source statement from a list of sources."""
422    return (
423        ", ".join(sorted({i.dataset.strip(", ") for i in source}))
424        + " via overturetoosm"
425    )