Metadata-Version: 2.4
Name: wherobots-catalog
Version: 0.1.0a4
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: sedonadb>=0.5.0a266
Requires-Dist: pyarrow
Requires-Dist: geoarrow-pyarrow
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pandas ; extra == 'test'
Requires-Dist: apache-sedona[db] ; extra == 'test'
Requires-Dist: shapely ; extra == 'test'
Provides-Extra: test
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# wherobots-catalog

Python interface to the [Wherobots Havasu Catalog](https://wherobots.com/havasu/) using [SedonaDB](https://sedona.apache.org/sedonadb).

## Installation

SedonaDB and the wherobots-catalog Python package can both be installed from [PyPI](https://pypi.org/project/wherobots-catalog):

```shell
pip install "apache-sedona[db]" wherobots-catalog
```

## Example


```python
import sedona.db
import wherobots.catalog

sd = sedona.db.connect()
wbc = wherobots.catalog.login()
```

If running wherobots-catalog from a [Wherobots Cloud](https://cloud.wherobots.com) notebook, your credentials will be automatically discovered. For local development, you may provide an [API key](https://cloud.wherobots.com/settings#api-keys) to the `login()` function or via the `WHEROBOTS_API_KEY` environment variable.

You can use attributes or indexing to access catalogs, namespaces, and tables within your Wherobots catalog.


```python
wbc.wherobots_open_data.overture_maps_foundation.places_place
# Identical to
# wbc["wherobots_open_data.overture_maps_foundation.places_place"]
# or
# wbc["wherobots_open_data"]["overture_maps_foundation"]["places_place"]
```




    WherobotsTable(wherobots_open_data.overture_maps_foundation.places_place)
    ┌────────────────────────────┬───────────────────────────┬───┬─────────┬───────────────────────────┐
    │             id             ┆          geometry         ┆ … ┆ version ┆            bbox           │
    │            utf8            ┆          geometry         ┆   ┆  int32  ┆           struct          │
    ╞════════════════════════════╪═══════════════════════════╪═══╪═════════╪═══════════════════════════╡
    │ 83dcaa85-1797-4c6b-ab20-9… ┆ POINT(-42.37905094 -22.2… ┆ … ┆      12 ┆ {xmin: -42.3790512084960… │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ cf49ef40-3ff7-4453-bc91-0… ┆ POINT(-42.38782842646311… ┆ … ┆       4 ┆ {xmin: -42.3878288269043… │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ 59c80e33-8ba8-47e0-87ad-e… ┆ POINT(-42.38525390625 -2… ┆ … ┆       9 ┆ {xmin: -42.38525390625, … │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ b529ab6b-8275-4302-a6b0-2… ┆ POINT(-42.38494 -22.2912… ┆ … ┆       1 ┆ {xmin: -42.3849411010742… │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ 4cc0eb56-4a0d-4d7d-b8ba-3… ┆ POINT(-42.38494 -22.2912… ┆ … ┆       2 ┆ {xmin: -42.3849411010742… │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ 8e7c8a1d-621a-4129-a2d6-2… ┆ POINT(-42.38494 -22.2912… ┆ … ┆       1 ┆ {xmin: -42.3849411010742… │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ 92a53c29-fb7c-42ab-bcaa-e… ┆ POINT(-42.385597229004 -… ┆ … ┆       2 ┆ {xmin: -42.3856010437011… │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ 561e3be0-3a01-4798-9b0c-7… ┆ POINT(-42.385940551758 -… ┆ … ┆       9 ┆ {xmin: -42.3859443664550… │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ 1eeb59dd-f32a-4666-afc1-6… ┆ POINT(-42.385811805725 -… ┆ … ┆       2 ┆ {xmin: -42.3858184814453… │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ 2fa3e1fb-09fe-47f0-bc23-b… ┆ POINT(-42.394223213196 -… ┆ … ┆       9 ┆ {xmin: -42.3942298889160… │
    └────────────────────────────┴───────────────────────────┴───┴─────────┴───────────────────────────┘



Table objects are [SedonaDB](https://sedona.apache.org/sedonadb/) `DataFrame`s, which provide methods for column selection, filtering, and collection to various formats.


```python
places = wbc.wherobots_open_data.overture_maps_foundation.places_place
boston_bounds = sd.funcs.st_makeenvelope(-71.19, 42.22, -70.92, 42.40)
(
    places.filter(
        places.names["primary"].funcs.lower().funcs.contains("library"),
        places.geometry.geo.intersects(boston_bounds),
    )
    .select(name=places.names["primary"], geometry="geometry")
    .show(5)
)
```

    ┌─────────────────────────────────────────────────────────┬─────────────────────────────────┐
    │                           name                          ┆             geometry            │
    │                           utf8                          ┆             geometry            │
    ╞═════════════════════════════════════════════════════════╪═════════════════════════════════╡
    │ Archbishop Iakovos Library and Learning Resource Center ┆ POINT(-71.12908543 42.31708149) │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ Annenberg Library at Pine Manor College                 ┆ POINT(-71.15659546 42.32076095) │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ Social Work Library                                     ┆ POINT(-71.16972113 42.33383808) │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ Thomas P. O'Neill Jr. Library                           ┆ POINT(-71.169262 42.33612449)   │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ Theology and Ministry Library                           ┆ POINT(-71.16362 42.34288)       │
    └─────────────────────────────────────────────────────────┴─────────────────────────────────┘


To query your catalogs from your own SedonaDB context, register the catalog list with `sd.register(wbc)`:


```python
sd.register(wbc)
sd.sql("""
    SELECT names['primary'] AS name, geometry
    FROM wherobots_open_data.overture_maps_foundation.places_place
    WHERE contains(lower(names['primary']), 'library')
      AND ST_Intersects(
          geometry,
          ST_MakeEnvelope(-71.19, 42.22, -70.92, 42.40)
      )
""").show(5)
```

    ┌──────────────────────────────────────────────────┬─────────────────────────────────────────────┐
    │                       name                       ┆                   geometry                  │
    │                       utf8                       ┆                   geometry                  │
    ╞══════════════════════════════════════════════════╪═════════════════════════════════════════════╡
    │ Dedham Public Library                            ┆ POINT(-71.1761276 42.24775988)              │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ Norfolk Law Library                              ┆ POINT(-71.1757283 42.2493331)               │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ West Roxbury Branch of the Boston Public Library ┆ POINT(-71.15737399 42.28335741)             │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ Endicott Library                                 ┆ POINT(-71.16093651597511 42.23993011383171) │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ Dedham Library-Yendicott Branch                  ┆ POINT(-71.16129 42.24105)                   │
    └──────────────────────────────────────────────────┴─────────────────────────────────────────────┘


Browsing, table operations, and catalog-node `.sql()` use a private SedonaDB context. Registering `wbc` makes the catalogs available to `sd.sql()` without sharing session defaults or locally created tables with that private context. You can register the same catalog list in more than one SedonaDB context; however, if you register multiple catalog lists into the same context, names from the most recently registered catalog take precedence.

Catalog-node `.sql()` resolves table names relative to the selected node, without requiring registration in your own context. This can be useful for ad-hoc queries within a specific node of the catalog.


```python
places_namespace = wbc.wherobots_open_data.overture_maps_foundation
places_namespace.sql("""
    SELECT names['primary'] AS name, geometry
    FROM places_place
""").show(5)
```

    ┌──────────────────────────────────────┬───────────────────────────────────────────────┐
    │                 name                 ┆                    geometry                   │
    │                 utf8                 ┆                    geometry                   │
    ╞══════════════════════════════════════╪═══════════════════════════════════════════════╡
    │ Hospedaria Rancho Ferreira           ┆ POINT(-42.37905094 -22.28527906)              │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ Sao Jose Do Ribeirão Em Bomjardim Rj ┆ POINT(-42.38782842646311 -22.278430489228455) │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ Costuraria Uniformes                 ┆ POINT(-42.38525390625 -22.28591967928)        │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ TÁ MARA                              ┆ POINT(-42.38494 -22.29129)                    │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ Click Empório                        ┆ POINT(-42.38494 -22.29129)                    │
    └──────────────────────────────────────┴───────────────────────────────────────────────┘

