overture-schema-theme-places 0.1.1.dev0__tar.gz

overture_schema_theme_places-0.1.1.dev0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: overture-schema-theme-places
+Version: 0.1.1.dev0
+Summary: Overture Maps places theme with place type models
+License-Expression: MIT
+Requires-Dist: overture-schema-common>=0.1.1
+Requires-Dist: overture-schema-system>=0.1.1
+Requires-Dist: pydantic[email]>=2.13.0
+Maintainer: Overture Maps Schema Working Group
+Requires-Python: >=3.10
+Project-URL: Homepage, https://overturemaps.org
+Project-URL: Source, https://github.com/OvertureMaps/schema
+Project-URL: Issues, https://github.com/OvertureMaps/schema/issues
+Description-Content-Type: text/markdown
+
+# Overture Schema Places Theme
+
+Shared structures and validation logic for Overture Maps places theme.
+Contains common place categories, contact structures, and validation utilities.

overture_schema_theme_places-0.1.1.dev0/README.md

@@ -0,0 +1,4 @@
+# Overture Schema Places Theme
+
+Shared structures and validation logic for Overture Maps places theme.
+Contains common place categories, contact structures, and validation utilities.

overture_schema_theme_places-0.1.1.dev0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+dependencies = [
+    "overture-schema-common>=0.1.1",
+    "overture-schema-system>=0.1.1",
+    "pydantic[email]>=2.13.0",
+]
+description = "Overture Maps places theme with place type models"
+version = "0.1.1.dev0"
+license = "MIT"
+name = "overture-schema-theme-places"
+readme = "README.md"
+requires-python = ">=3.10"
+
+[[project.maintainers]]
+name = "Overture Maps Schema Working Group"
+
+[project.urls]
+Homepage = "https://overturemaps.org"
+Source = "https://github.com/OvertureMaps/schema"
+Issues = "https://github.com/OvertureMaps/schema/issues"
+
+[project.entry-points."overture.models"]
+place = "overture.schema.places:Place"
+
+[project.entry-points.pytest11]
+overture_baselines = "overture.schema.system.testing.plugin"
+
+[tool.uv.sources.overture-schema-common]
+workspace = true
+
+[tool.uv.sources.overture-schema-system]
+workspace = true
+
+[tool.uv.build-backend]
+module-name = "overture.schema.places"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.13"]
+build-backend = "uv_build"
+
+[[examples.Place]]
+id = "99003ee6-e75b-4dd6-8a8a-53a5a716c50d"
+geometry = "POINT (-150.46875 -79.1713346)"
+version = 1
+confidence = 0.7337175792507205
+websites = ["https://www.superhotel.co.jp/s_hotels/beppu/"]
+socials = ["https://www.facebook.com/107663894904826"]
+phones = ["+81977009000"]
+operating_status = "open"
+theme = "places"
+type = "place"
+
+[examples.Place.bbox]
+xmin = -150.46875
+xmax = -150.46875
+ymin = -79.17134094238281
+ymax = -79.17133331298828
+
+[[examples.Place.sources]]
+property = ""
+dataset = "meta"
+record_id = "107663894904826"
+update_time = "2025-06-30T07:00:00.000Z"
+confidence = 0.7337175792507205
+
+[examples.Place.names]
+primary = "スーパーホテル別府駅前"
+
+[examples.Place.categories]
+primary = "hotel"
+
+[examples.Place.brand.names]
+primary = "SUPER HOTEL"
+
+[[examples.Place.addresses]]
+freeform = "秋田県横手市駅前町１３−８"
+locality = "横手市"
+postcode = "013-0036"
+country = "JP"

overture_schema_theme_places-0.1.1.dev0/pyproject.toml.orig

@@ -0,0 +1,85 @@
+[project]
+maintainers = [
+    {name = "Overture Maps Schema Working Group"},
+]
+dependencies = [
+    "overture-schema-common>=0.1.1",
+    "overture-schema-system>=0.1.1",
+    "pydantic[email]>=2.13.0",
+]
+description = "Overture Maps places theme with place type models"
+version = "0.1.1.dev0"
+license = "MIT"
+name = "overture-schema-theme-places"
+readme = "README.md"
+requires-python = ">=3.10"
+
+[project.urls]
+Homepage = "https://overturemaps.org"
+Source = "https://github.com/OvertureMaps/schema"
+Issues = "https://github.com/OvertureMaps/schema/issues"
+
+[tool.uv.sources]
+overture-schema-common = { workspace = true }
+overture-schema-system = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "overture.schema.places"
+
+[project.entry-points."overture.models"]
+place = "overture.schema.places:Place"
+
+[project.entry-points.pytest11]
+overture_baselines = "overture.schema.system.testing.plugin"
+
+[[examples.Place]]
+id = "99003ee6-e75b-4dd6-8a8a-53a5a716c50d"
+geometry = "POINT (-150.46875 -79.1713346)"
+version = 1
+confidence = 0.7337175792507205
+websites = [
+  "https://www.superhotel.co.jp/s_hotels/beppu/"
+]
+socials = [
+  "https://www.facebook.com/107663894904826"
+]
+phones = [
+  "+81977009000"
+]
+operating_status = "open"
+theme = "places"
+type = "place"
+
+[examples.Place.bbox]
+xmin = -150.46875
+xmax = -150.46875
+ymin = -79.17134094238281
+ymax = -79.17133331298828
+
+[[examples.Place.sources]]
+property = ""
+dataset = "meta"
+record_id = "107663894904826"
+update_time = "2025-06-30T07:00:00.000Z"
+confidence = 0.7337175792507205
+
+[examples.Place.names]
+primary = "スーパーホテル別府駅前"
+
+[examples.Place.categories]
+primary = "hotel"
+
+[examples.Place.brand]
+
+[examples.Place.brand.names]
+primary = "SUPER HOTEL"
+
+[[examples.Place.addresses]]
+freeform = "秋田県横手市駅前町１３−８"
+locality = "横手市"
+postcode = "013-0036"
+country = "JP"

overture_schema_theme_places-0.1.1.dev0/src/overture/schema/places/__init__.py

@@ -0,0 +1,11 @@
+"""Places theme.
+
+Point-based representations of real-world facilities, services, and amenities with
+category classifications and metadata.
+"""
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+
+from .place import Address, Brand, Categories, OperatingStatus, Place
+
+__all__ = ["Address", "Brand", "Categories", "OperatingStatus", "Place"]

overture_schema_theme_places-0.1.1.dev0/src/overture/schema/places/place.py

@@ -0,0 +1,305 @@
+"""
+The `Place` feature type model and supporting types.
+"""
+
+import textwrap
+from enum import Enum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, HttpUrl
+
+from overture.schema.common import (
+    OvertureFeature,
+)
+from overture.schema.common.confidence import (
+    ConfidenceScore,
+)
+from overture.schema.common.names import (
+    Named,
+)
+from overture.schema.system.field_constraint import (
+    UniqueItemsConstraint,
+)
+from overture.schema.system.geometric import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
+from overture.schema.system.model_constraint import no_extra_fields
+from overture.schema.system.string import (
+    CountryCodeAlpha2,
+    PhoneNumber,
+    RegionCode,
+    SnakeCaseString,
+    WikidataId,
+)
+
+
+class OperatingStatus(str, Enum):
+    """
+    General indication of whether a place is: in continued operation, in a temporary operating
+    hiatus, or closed permanently.
+
+    Operating status should not be confused with opening hours or operating hours. In particular,
+    the status `"open"` does not mean the place is open *right now*, it means that in general the
+    place is continuing to operate normally, as opposed to being in an operating hiatus
+    (`"temporarily_closed"`) or shuttered (`"permanently_closed"`).
+    """
+
+    OPEN = "open"
+    PERMANENTLY_CLOSED = "permanently_closed"
+    TEMPORARILY_CLOSED = "temporarily_closed"
+
+
+@no_extra_fields
+class Categories(BaseModel):
+    """
+    Categories a place belongs to.
+
+    Complete list is available on GitHub: https://github.com/OvertureMaps/schema/blob/main/docs/schema/concepts/by-theme/places/overture_categories.csv
+    """
+
+    # Required
+
+    primary: Annotated[
+        SnakeCaseString,
+        Field(description="The primary or main category of the place."),
+    ]
+
+    # Optional
+
+    alternate: Annotated[
+        list[SnakeCaseString] | None,
+        Field(
+            description=textwrap.dedent("""
+                Alternate categories of the place.
+
+                Some places might fit into two categories, e.g., a book store and a coffee shop. In
+                these cases, the primary category can be augmented with additional categories.
+            """).strip(),
+        ),
+        UniqueItemsConstraint(),
+    ] = None
+
+
+@no_extra_fields
+class Taxonomy(BaseModel):
+    """
+    A structured representation of the place's category within the Overture taxonomy.
+
+    Provides the primary classification, full hierarchy path, and alternate categories.
+    """
+
+    # Required
+
+    primary: Annotated[
+        SnakeCaseString,
+        Field(
+            description=textwrap.dedent("""
+            The primary, or most specific, category known about this place.
+
+            The `primary` category value must always equal the last or rightmost entry in the `hierarchy` field.
+            """)
+        ),
+    ]
+
+    hierarchy: Annotated[
+        list[SnakeCaseString],
+        Field(
+            min_length=1,
+            description=textwrap.dedent("""
+                The full primary hierarchy of categories known for this place, ordered from most general to most specific.
+                An example hierarchy might be: `["food_and_drink", "restaurant", "casual_eatery", "gas_station_sushi"]`.
+
+                The rightmost, or most specific, value in the `hierarchy` must always be equal to the `primary` field.
+                The basic level category of the place will typically be found in the middle of the primary hierarchy.
+                The primary hierarchy does not include any of the alternate categories found in the `alternates` field.
+                """).strip(),
+        ),
+        UniqueItemsConstraint(),
+    ]
+
+    # Optional
+
+    alternates: Annotated[
+        list[SnakeCaseString] | None,
+        Field(
+            min_length=1,
+            description=textwrap.dedent("""
+                Unordered list of additional categories that are known for this
+                place but that are not part of the primary category hierarchy.
+
+                Alternate categories allow a more complete picture of the place
+                to be surfaced when it fits multiple unconnected branches in the
+                taxonomy. For example a gas station that also sells groceries
+                might have primary category of "gas_station" with an alternate
+                of "grocery_store".
+
+                Alternate categories are not part of the primary hierarchy or
+                another alternate category's hierarchy.
+                In other words, if a category is a parent in the hierarchy of another category,
+                that category can't be a primary or alternate category itself.
+
+                Note as well that this field is an unordered list of extra
+                categories and does not represent a hierarchy.
+            """).strip(),
+        ),
+        UniqueItemsConstraint(),
+    ] = None
+
+
+@no_extra_fields
+class Brand(Named):
+    """
+    A brand associated with a place.
+
+    A location with multiple brands is modeled as multiple separate places, each with its own brand.
+    """
+
+    # Optional
+
+    wikidata: WikidataId | None = None
+
+
+@no_extra_fields
+class Address(BaseModel):
+    """
+    An address associated with a place.
+    """
+
+    # Optional
+
+    freeform: Annotated[
+        str | None,
+        Field(
+            description="Free-form address that contains street name, house number and other address info",
+        ),
+    ] = None
+    locality: Annotated[
+        str | None,
+        Field(
+            description="City, town, or neighborhood component of the place address",
+        ),
+    ] = None
+    postcode: Annotated[
+        str | None, Field(description="Postal code component of the place address")
+    ] = None
+    region: RegionCode | None = None
+    country: CountryCodeAlpha2 | None = None
+
+
+class Place(OvertureFeature[Literal["places"], Literal["place"]], Named):
+    """
+    Places are point representations of real-world facilities, businesses, services, or amenities.
+    """
+
+    model_config = ConfigDict(title="place")
+
+    # Overture Feature
+
+    geometry: Annotated[
+        Geometry,
+        GeometryTypeConstraint(GeometryType.POINT),
+        Field(
+            description="Position of the place. Places are point geometries.",
+        ),
+    ]
+
+    # Optional
+
+    operating_status: Annotated[
+        OperatingStatus | None,
+        Field(
+            description=textwrap.dedent("""
+                An indication of whether a place is: in continued operation, in a temporary
+                operating hiatus, or closed permanently.
+
+                This is not an indication of opening hours or that the place is open/closed at the
+                current time-of-day or day-of-week.
+
+                When `operating_status` is `"permanently_closed"`, the `confidence` field will be
+                set to 0.
+            """).strip(),
+        ),
+    ] = None
+
+    categories: Categories | None = None
+    basic_category: Annotated[
+        SnakeCaseString | None,
+        Field(
+            description=textwrap.dedent(
+                """
+                The basic level category of a place.
+
+                This field classifies places into categories at a level that most people find
+                intuitive. The full list of possible values it may hold can be found at (TODO).
+
+                The basic level category, or simply basic category, is based on a cognitive science
+                model use in taxonomy and ontology development. The idea is to provide the category
+                name at the level of generality that is preferred by humans in learning and memory
+                tasks. This category to be roughly in the middle of the general-to-specific category
+                hierarchy.
+
+                The full list of basic level categories is available at https://docs.overturemaps.org/guides/places/
+                """
+            ).strip()
+        ),
+    ] = None
+    taxonomy: Annotated[
+        Taxonomy | None,
+        Field(
+            description=textwrap.dedent(
+                """
+                A structured representation of the place's category within the Overture taxonomy.
+
+                Provides the primary classification, full hierarchy path, and alternate categories.
+                """
+            ).strip()
+        ),
+    ] = None
+    confidence: Annotated[
+        ConfidenceScore | None,
+        Field(
+            description=textwrap.dedent(
+                """
+                A score between 0 and 1 indicating how confident we are that the place exists.
+
+                A confidence score of 0 indicates that we are certain the place doesn't exist
+                anymore and will always be paired with an `operating_status` of
+                `"permanently_closed"`.
+
+                A confidence score of 1 indicates that we are certain the place does exist.
+
+                If there is no value for confidence, it means we don't have enough information on
+                which to estimate our confidence level.
+                """
+            ).strip(),
+        ),
+    ] = None
+    websites: Annotated[
+        list[HttpUrl] | None,
+        Field(min_length=1, description="The websites of the place."),
+        UniqueItemsConstraint(),
+    ] = None
+    socials: Annotated[
+        list[HttpUrl] | None,
+        Field(min_length=1, description="The social media URLs of the place."),
+        UniqueItemsConstraint(),
+    ] = None
+    emails: Annotated[
+        list[EmailStr] | None,
+        Field(min_length=1, description="The email addresses of the place."),
+        UniqueItemsConstraint(),
+    ] = None
+    phones: Annotated[
+        list[PhoneNumber] | None,
+        Field(min_length=1, description="The phone numbers of the place."),
+        UniqueItemsConstraint(),
+    ] = None
+    brand: Annotated[
+        Brand | None, Field(description="The brand associated with the place.")
+    ] = None
+    addresses: Annotated[
+        list[Address] | None,
+        Field(min_length=1, description="The address or addresses of the place"),
+    ] = None