juno.location

Location services and geocoding via CoreLocation.

Wraps CLLocationManager for one-shot and continuous location queries, plus CLGeocoder for forward and reverse geocoding.

Authorization is requested lazily by get_current() and updates() when needed. The first call from a fresh install presents the system prompt; subsequent calls reuse the granted (or denied) status. On denial / restriction these helpers raise PermissionError so user scripts can fall back gracefully.

Typical usage:

from juno import location

here = location.get_current()
print(here.latitude, here.longitude)

with location.updates():
    for _ in range(10):
        sample = location.get_latest()
        if sample is not None:
            print(sample.latitude, sample.longitude)
        time.sleep(1)

matches = location.geocode("1 Infinite Loop, Cupertino")
place = location.reverse_geocode(37.3318, -122.0312)[0]
print(place.country, place.locality)
class juno.location.Location(latitude, longitude, altitude, horizontal_accuracy, vertical_accuracy, speed, course, timestamp)

Bases: object

A point-in-time location reading.

Negative horizontal_accuracy / vertical_accuracy indicate that the dimension is unavailable. timestamp is seconds since the Unix epoch.

Parameters:
class juno.location.Placemark(latitude, longitude, name, country, country_code, administrative_area, sub_administrative_area, locality, sub_locality, thoroughfare, sub_thoroughfare, postal_code, timezone)

Bases: object

A geocoded address record returned by geocode() / reverse_geocode(). All string fields may be None when the underlying CLPlacemark did not provide them.

Parameters:

  • latitude (float | None)

  • longitude (float | None)

  • name (str | None)

  • country (str | None)

  • country_code (str | None)

  • administrative_area (str | None)

  • sub_administrative_area (str | None)

  • locality (str | None)

  • sub_locality (str | None)

  • thoroughfare (str | None)

  • sub_thoroughfare (str | None)

  • postal_code (str | None)

  • timezone (str | None)

class juno.location.AuthorizationStatus

Bases: object

String constants returned by authorization_status().

juno.location.authorization_status()

Return the current location authorization status.

Returns:

One of the AuthorizationStatus string constants.

Return type:

str

juno.location.is_authorized()

Return True if the app has any location authorization.

Return type:

bool

juno.location.request_authorization()

Request “when in use” authorization if status is undetermined.

If the status is already determined, returns immediately with the existing value. Otherwise this triggers the system permission prompt and polls authorization_status() until the user makes a choice — that polling is in Python so Juno’s Stop button can interrupt the wait via a normal KeyboardInterrupt.

Returns:

Resolved authorization status, one of the AuthorizationStatus constants.

Return type:

str

juno.location.get_current(timeout=30.0)

Request a single fresh location.

Parameters:

timeout (float) – Maximum wait in seconds before raising TimeoutError. Must be positive.

Returns:

A Location snapshot.

Raises:
Return type:

Location

juno.location.updates()

Context manager that starts and stops continuous location updates.

Inside the with block get_latest() returns the most recently delivered location. When the block exits, updates are stopped and the cached value is cleared.

Raises:

PermissionError – If location authorization is denied or restricted when the block is entered.

Return type:

Iterator[None]

juno.location.is_updating()

Return whether a continuous-updates session is currently active.

Mirrors whether the most recent updates() context manager is still running. Independent of whether a reading has been received yet — use get_latest() to check for that.

Return type:

bool

juno.location.get_latest()

Return the latest continuous-update location, or None if none has been received yet.

Return type:

Location | None

juno.location.geocode(address)

Forward geocode an address string to one or more placemarks.

Parameters:

address (str) – Free-form address (e.g. "1 Infinite Loop, Cupertino").

Returns:

A list of Placemark matches, possibly empty.

Raises:

  • TypeError – If address is not a string.

  • RuntimeError – If the geocoder failed (network unavailable, rate-limited, or unsupported address).

Return type:

list[Placemark]

juno.location.reverse_geocode(latitude, longitude)

Reverse geocode a coordinate pair to one or more placemarks.

Parameters:

  • latitude (float) – Latitude in decimal degrees.

  • longitude (float) – Longitude in decimal degrees.

Returns:

A list of Placemark matches, possibly empty.

Raises:
Return type:

list[Placemark]