Location

See the Location guide.

Device location: one fix, or a stream of them.

Enable it in pythonnative.toml:

[plugins]
use = ["location"]

[permissions]
location_when_in_use = "Show nearby stores."

Example

from pythonnative.location import Location

async def show_position() -> None:
    position = await Location.get_current()
    if position is not None:
        print(position.latitude, position.longitude)

async def follow() -> None:
    async for position in Location.watch(distance=10):
        move_marker(position)

Classes:

Name	Description
Position	One location fix.
Location	Location services.

Attributes:

Name	Type	Description
Accuracy		Balanced accuracy saves power; high asks for the best the device can do.

Accuracy module-attribute

Accuracy = Literal['balanced', 'high']

Balanced accuracy saves power; high asks for the best the device can do.

Position dataclass

Position(
    latitude: float,
    longitude: float,
    accuracy: Optional[float] = None,
    altitude: Optional[float] = None,
    speed: Optional[float] = None,
    heading: Optional[float] = None,
    timestamp: Optional[float] = None,
)

One location fix.

Attributes:

Name	Type	Description
latitude	float	Degrees north.
longitude	float	Degrees east.
accuracy	Optional[float]	Horizontal accuracy in meters, when reported.
altitude	Optional[float]	Meters above sea level, when reported.
speed	Optional[float]	Meters per second, when reported.
heading	Optional[float]	Degrees clockwise from north, when reported.
timestamp	Optional[float]	Unix seconds, when reported.

Location

Location services.

Raises:

Type	Description
NativeModuleError	If the native module fails, or with the code plugin_not_enabled when location isn't in the build.

Methods:

Name	Description
get_current	Request the device's current location, prompting for permission if needed.
watch	Yield positions as the device moves, until the iteration ends.

get_current async staticmethod

get_current(
    *,
    accuracy: Accuracy = "balanced",
    timeout: float = 10.0
) -> Optional[Position]

Request the device's current location, prompting for permission if needed.

Parameters:

Name	Type	Description	Default
accuracy	Accuracy	How hard to try for a precise fix.	'balanced'
timeout	float	Maximum seconds to wait.	10.0

Returns:

Type	Description
Optional[Position]	The position, or None when permission was denied, location
Optional[Position]	services are off, or the request timed out.

watch async staticmethod

watch(
    *,
    accuracy: Accuracy = "balanced",
    distance: float = 0.0
) -> AsyncGenerator[Position, None]

Yield positions as the device moves, until the iteration ends.

Prompts for permission when needed. Leaving the async for (or canceling its task) stops the updates, so this is safe to run from use_effect. The iterator ends only when the caller stops it.

Parameters:

Name	Type	Description	Default
accuracy	Accuracy	How hard to try for a precise fix.	'balanced'
distance	float	Meters the device must move between updates.	0.0

Raises:

Type	Description
NativeModuleError	With the code permission_denied when the user refuses.