gps_tracker.client package

Submodules

gps_tracker.client.asynchronous module

Asynchronous client for Invoxia API.

class gps_tracker.client.asynchronous.AsyncClient(config: Config, session: aiohttp.ClientSession | None = None)[source]

Bases: object

Asynchronous client for Invoxia API.

async close()[source]: Close current session.

classmethod get_auth(config: Config) → aiohttp.BasicAuth[source]: Form the authentication instance associated to a config.

async get_device(device_id: int) → Device[source]

Return a device referenced by its id.

Parameters:: device_id (int) – Unique identifier of a device
Returns:: Device instance of given id
Return type:: Device

async get_devices(kind: str | None = None) → List[Device][source]

Return devices associated to credentials.

By default, all devices (included associated smartphones) are returned. The kind parameter allows to filter only devices of a given type (‘android’, ‘iphone’ or ‘tracker’).

Parameters:: kind (str, optional) – kind of devices to retrieve
Returns:: List of retrieved devices
Return type:: List[Device]

async get_locations(device: Tracker, not_before: datetime | None = None, not_after: datetime | None = None, max_count: int = 20) → List[TrackerData][source]

Extract the list of tracker locations.

Parameters:

device (Tracker) – The tracker instance whose locations must be extracted.
not_before (datetime.datetime, optional) – Minimum date-time of the locations to extract.
not_after (datetime.datetime, optional) – Maximum date-time of the locations to extract.
max_count (int, optional) – Maximum count of position to extract. Note that one API query yields 20 locations.

Returns:

List of extracted locations

Return type:

List[TrackerData]

async get_tracker_config(device: Tracker) → TrackerConfig[source]

Get the current configuration of a given tracker.

Parameters:: device (Tracker) – The tracker instance whose configuration is queried.
Returns:: Current config of the tracker
Return type:: TrackerConfig

async get_tracker_status(device: Tracker) → TrackerStatus[source]

Get the current status of a given tracker.

Parameters:: device (Tracker) – The tracker instance whose status is queried.
Returns:: Current status of the tracker
Return type:: TrackerStatus

async get_trackers() → List[Tracker][source]

Query API for the list of trackers associated to credentials.

Returns:: Tracker devices associated to current account
Return type:: List[Tracker]

async get_user(user_id: int) → User[source]

Return a user referenced by its id.

Parameters:: user_id (int) – ID of the user to retrieve
Returns:: User instance associated to given ID
Return type:: User

async get_users() → List[User][source]

Return all users associated to credentials.

The API definition seems to indicate that multiple users can be associated to a single account (probably for pro subscriptions). For public consumers, this methods will return a single user.

Returns:: List of User instances associated to account
Return type:: List[User]

gps_tracker.client.config module

Definition of Client configuration.

class gps_tracker.client.config.Config(username: str, password: str, api_url: str = 'https://labs.invoxia.io')[source]

Bases: object

Configuration for API Clients.

api_url: str: Invoxia API URL.

classmethod default_api_url() → str[source]: Return the default API URL.

password: str: Password used as credentials on Invoxia account.

username: str: Username used as credentials on Invoxia account.

gps_tracker.client.datatypes module

Data-types returned by Invoxia API.

class gps_tracker.client.datatypes.Android(id, created: str | None, name, version, serial, *, timezone=None)[source]

Bases: Device

Definition of devices of type ‘android’.

created: datetime: Datetime of device registration.

id: int: Device unique identifier.

name: str: Device name.

serial: UUID: Device Universally Unique Identifier

timezone: str | None: Timezone associated to device.

version: str: Device version.

class gps_tracker.client.datatypes.Device(id, created: str | None, name, version, *, timezone=None)[source]

Bases: object

Base class for devices.

created: datetime: Datetime of device registration.

static get(device_data: dict[str, Any]) → Device[source]: Generate a Device object based on its type.

classmethod get_types() → Iterable[str][source]: Return list of registered device types.

id: int: Device unique identifier.

name: str: Device name.

timezone: str | None: Timezone associated to device.

version: str: Device version.

class gps_tracker.client.datatypes.Iphone(id, created: str | None, name, version, serial, *, timezone=None)[source]

Bases: Device

Definition of devices of type ‘iphone’.

created: datetime: Datetime of device registration.

id: int: Device unique identifier.

name: str: Device name.

serial: UUID: Device Universally Unique Identifier

timezone: str | None: Timezone associated to device.

version: str: Device version.

class gps_tracker.client.datatypes.Tracker(id, created: str | None, name, version, *, timezone=None)[source]

Bases: Device

Base class for trackers.

created: datetime: Datetime of device registration.

id: int: Device unique identifier.

name: str: Device name.

timezone: str | None: Timezone associated to device.

version: str: Device version.

class gps_tracker.client.datatypes.Tracker01(id, created: str | None, name, version, serial, version_build, tracker_config: Dict[str, Any], tracker_status: Dict[str, Any], model: str | None = None, *, timezone=None)[source]

Bases: Tracker

Definition of devices of type ‘tracker_01’.

created: datetime: Datetime of device registration.

id: int: Device unique identifier.

model: str | None: Tracker model.

name: str: Device name.

serial: str: Tracker serial number.

timezone: str | None: Timezone associated to device.

tracker_config: TrackerConfig: Tracker configuration data.

tracker_status: TrackerStatus: Tracker current status.

version: str: Device version.

version_build: str: Firmware build reference (To be confirmed).

class gps_tracker.client.datatypes.Tracker03(id, created: str | None, name, version, serial, version_build, tracker_config: Dict[str, Any], tracker_status: Dict[str, Any], model: str | None = None, *, timezone=None)[source]

Bases: Tracker01

Definition of devices of type ‘tracker_03’.

created: datetime: Datetime of device registration.

id: int: Device unique identifier.

name: str: Device name.

timezone: str | None: Timezone associated to device.

version: str: Device version.

class gps_tracker.client.datatypes.Tracker04(id, created: str | None, name, version, serial, version_build, tracker_config: Dict[str, Any], tracker_status: Dict[str, Any], model: str | None = None, *, timezone=None)[source]

Bases: Tracker01

Definition of devices of type ‘tracker_04’.

created: datetime: Datetime of device registration.

id: int: Device unique identifier.

name: str: Device name.

timezone: str | None: Timezone associated to device.

version: str: Device version.

class gps_tracker.client.datatypes.TrackerConfig(color, firmware_path, icon: int, mode: int | str, network, network_region, notify_position, notify_long_walk, usage: str = TrackerUsage.UND, board_name: str | None = None, image: str | None = None, network_config=None, weight=None)[source]

Bases: object

Definition of tracker config data.

board_name: str | None: Tracker board-model reference.

color: int: Icon color.

firmware_path: str: URL to firmware update (To be confirmed).

icon: TrackerIcon: ID of the icon selected for this tracker.

image: str | None: Image reference when icon as been replaced by a user-defined image.

mode: TrackerMode: Operating mode of the tracker.

network: str: Network used by tracker (LoRa/SigFox).

network_config: int | None: To be determined.

network_region: str: Region configured for the network (To be confirmed).

notify_long_walk: bool: To be determined. Probably related to pet mode.

notify_position: bool: Whether notifications must be send when tracker position changes.

usage: TrackerUsage: Tracker usage defined during device setup.

weight: float | None: To be determined. Probably weight of object to which tracker is attached.

class gps_tracker.client.datatypes.TrackerData(datetime: str | None, lat, lng, method, pkt_drop, precision, uuid)[source]

Bases: object

Definition of tracker location data.

datetime: datetime: Datetime of location measurement.

lat: float: Device latitude.

lng: float: Device longitude.

method: TrackerMethod: Method used for location acquisition.

pkt_drop: int: To be determined. (Probably number of packet drop since last location).

precision: int: Precision of location measurement (To be confirmed).

uuid: UUID: Universally unique identifier of location data.

class gps_tracker.client.datatypes.TrackerIcon(*values)[source]

Bases: Enum

Enumeration of tracker icons.

ANIMAL = 37

ANTENNA = 43

BACKHOE_LOADER = 36

BACKPACK = 5

BEEHIVE = 41

BIKE = 7

BOAT = 8

BRIEFCASE = 2

CAR = 10

CARAVAN = 12

CARPARK = 42

CART = 13

CAT = 31

DOG = 14

EBIKE = 40

GIRL = 34

HANDBAG = 1

HEALTH = 44

HELICOPTER = 18

KAYAK = 15

KEYS = 46

LAPTOP = 16

MAN = 39

MOTO = 17

OTHER = 0

PERSON = 32

PHONE = 48

PLANE = 19

SCOOTER = 21

SUITCASE = 3

TENT = 23

TRACTOR = 26

TRUCK = 24

TV = 47

UNKNOWN = -1

WASHER = 45

WOMAN = 38

static from_value(value: int) → TrackerIcon[source]: Convert an int value to class instance.

class gps_tracker.client.datatypes.TrackerMethod(*values)[source]

Bases: Enum

Enumeration of tracking methods.

BLE_NEIGHBOR = 13

BSSID = 3

BSSID2 = 9

BSSID3 = 10

BSSID4 = 11

BSSID_TGU = 7

FLEET_CORRECTION = 12

GPS = 2

GPS_BLE = 14

NETWORK = 1

PHONE = 6

PHONE2 = 15

PLACE = 4

SERVER = 8

UBISCALE = 5

UNKNOWN = 0

class gps_tracker.client.datatypes.TrackerMode(*values)[source]

Bases: Enum

Enumeration of possible tracker modes.

AIRPLANE = 6

CHILD = 3

CHILD_PET = 23

DAILY = 1

DAILY_PET = 21

INTENSE = 2

INTENSE_PET = 22

KEEP_ALIVE = 4

LOST = 7

LOST_PET = 27

LOST_PET_DEBUG = 24

LWT3 = 235

UNKNOWN = -1

VEHICLE_S1 = 8

VEHICLE_S2 = 9

VEHICLE_S3 = 10

static from_value(value: int | str) → TrackerMode[source]: Convert a value to class instance.

class gps_tracker.client.datatypes.TrackerStatus(battery, begin_date: str | None, network_operator, state, stationary, sub_state, last_event: str | None = None, last_loc_latitude=None, last_loc_longitude=None, last_location: str | None = None, lost_pending=False, sub_end_date=None)[source]

Bases: object

Definition of tracker status data.

battery: int

begin_date: datetime

last_event: datetime | None

last_loc_latitude: float | None

last_loc_longitude: float | None

last_location: datetime | None

lost_pending: bool | None: To be determined. Probably whether device is considered as probably lost.

network_operator: str

state: str

stationary: int

sub_end_date: str | None

sub_state: str

class gps_tracker.client.datatypes.TrackerUsage(*values)[source]

Bases: Enum

Enumeration of possible tracker usages.

BIKE = 'bike'

CAT = 'cat'

CHILD = 'child'

DOG = 'dog'

MOTO = 'moto'

OTHER = 'other'

PERSON = 'person'

PET = 'pet'

TOOL = 'tool'

UND = ''

UNKNOWN = 'unknown'

VEHICLE = 'vehicle'

static from_value(value: str) → TrackerUsage[source]: Convert a str value to class instance.

class gps_tracker.client.datatypes.User(id, username, profiles)[source]

Bases: object

User definition as returned by Invoxia API.

id: int: User unique identifier.

profiles: List[int]: List of profile ids associated to user.

username: str: User name.

gps_tracker.client.datatypes.form(cls: Type[T], data: Mapping[str, Any]) → T[source]: Form an object based on arguments given in mapping.

gps_tracker.client.exceptions module

Definition of exceptions possibly raised by the Client.

exception gps_tracker.client.exceptions.ApiConnectionError[source]

Bases: GpsTrackerException

Exception raised if connection error occurs during API call.

exception gps_tracker.client.exceptions.FailedQuery(msg: str | None = None, json_answer: Dict | List | None = None)[source]

Bases: HttpException

Exception raised for any erroneous status code.

exception gps_tracker.client.exceptions.ForbiddenQuery(msg: str | None = None, json_answer: Dict | List | None = None)[source]

Bases: HttpException

Exception raised when an API query is forbidden with current credentials.

exception gps_tracker.client.exceptions.GpsTrackerException[source]

Bases: Exception

Base class for gps-tracker exceptions.

exception gps_tracker.client.exceptions.HttpException(msg: str | None = None, json_answer: Dict | List | None = None)[source]

Bases: GpsTrackerException

Base class for HTTP exceptions.

static get(code: int) → Type[HttpException] | None[source]

Return the subclass associated to code if it exists.

Parameters:: code (int) – HTTP code returned by the API call
Returns:: SubClass of HttpException with correct code if it exists
Return type:: Type[HttpException]

static get_default() → Type[HttpException] | None[source]: Return the subclass declared as default.

exception gps_tracker.client.exceptions.NoContentQuery(msg: str | None = None, json_answer: Dict | List | None = None)[source]

Bases: HttpException

Exception raised when API has no content to return.

exception gps_tracker.client.exceptions.UnauthorizedQuery(msg: str | None = None, json_answer: Dict | List | None = None)[source]

Bases: HttpException

Exception raised if credentials are incorrect.

exception gps_tracker.client.exceptions.UnknownAnswerScheme(json_data, message, cls)[source]

Bases: GpsTrackerException

Exception raised when API answer cannot be interpreted.

exception gps_tracker.client.exceptions.UnknownDeviceType(device_data: Dict[str, Any])[source]

Bases: GpsTrackerException

Exception raised when a device of unknown type is found.

gps_tracker.client.synchronous module

Synchronous client for Invoxia API.

class gps_tracker.client.synchronous.Client(config: Config)[source]

Bases: object

Synchronous client for Invoxia API.

get_device(device_id: int) → Device[source]

Return a device referenced by its id.

Parameters:: device_id (int) – Unique identifier of a device
Returns:: Device instance of given id
Return type:: Device

get_devices(kind: str | None = None) → List[Device][source]

Return devices associated to credentials.

By default, all devices (included associated smartphones) are returned. The kind parameter allows to filter only devices of a given type (‘android’, ‘iphone’ or ‘tracker’).

Parameters:: kind (str, optional) – kind of devices to retrieve
Returns:: List of retrieved devices
Return type:: List[Device]

get_locations(device: Tracker, not_before: datetime | None = None, not_after: datetime | None = None, max_count: int = 20) → List[TrackerData][source]

Extract the list of tracker locations.

Parameters:

device (Tracker) – The tracker instance whose locations must be extracted.
not_before (datetime.datetime, optional) – Minimum date-time of the locations to extract.
not_after (datetime.datetime, optional) – Maximum date-time of the locations to extract.
max_count (int, optional) – Maximum count of position to extract. Note that one API query yields 20 locations.

Returns:

List of extracted locations

Return type:

List[TrackerData]

get_tracker_config(device: Tracker) → TrackerConfig[source]

Get the current configuration of a given tracker.

Parameters:: device (Tracker) – The tracker instance whose configuration is queried.
Returns:: Current config of the tracker
Return type:: TrackerConfig

get_tracker_status(device: Tracker) → TrackerStatus[source]

Get the current status of a given tracker.

Parameters:: device (Tracker) – The tracker instance whose status is queried.
Returns:: Current status of the tracker
Return type:: TrackerStatus

get_trackers() → List[Tracker][source]

Query API for the list of trackers associated to credentials.

Returns:: Tracker devices associated to current account
Return type:: List[Tracker]

get_user(user_id: int) → User[source]

Return a user referenced by its id.

Parameters:: user_id (int) – ID of the user to retrieve
Returns:: User instance associated to given ID
Return type:: User

get_users() → List[User][source]

Return all users associated to credentials.

The API definition seems to indicate that multiple users can be associated to a single account (probably for pro subscriptions). For public consumers, this methods will return a single user.

Returns:: List of User instances associated to account
Return type:: List[User]

gps_tracker.client.url_provider module

URL provider for specific Invoxia API queries.

class gps_tracker.client.url_provider.UrlProvider(api_url: str = 'https://labs.invoxia.io')[source]

Bases: object

URL provider generates the API urls used to access user data.

device(device_id: int) → str[source]

Form the URL to access a specific device by its id.

Parameters:: device_id (int) – device unique identifier
Returns:: API URL
Return type:: str

devices(kind: str | None = None) → str[source]

Form the URL to access all devices associated with current credentials.

Parameters:: kind (str, optional) – Kind of device to list (tracker, android, iphone)
Returns:: API URL
Return type:: str

locations(device_id: int, not_before: int | None = None, not_after: int | None = None) → str[source]

Form the URL to access tracker locations in a given time-range.

Parameters:

device_id (int) – tracker device unique identifier
not_before (int, optional) – timestamp of the minimum datetime to consider
not_after (int, optional) – timestamp of the maximum datetime to consider

Returns:

API URL

Return type:

str

tracker_config(device_id: int) → str[source]: Form the URL to get the current tracker config.

tracker_status(device_id: int) → str[source]: Form the URL to get the current tracker status.

user(user_id: int) → str[source]

Form the URL to access a specific user by its id.

Parameters:: user_id (int) – user unique identifier
Returns:: API URL
Return type:: str

users() → str[source]

Form the URL to access list of users associated with credentials.

Returns:: API URL
Return type:: str

Module contents

Definitions of subpackage gps_tracker.client.

class gps_tracker.client.AsyncClient(config: Config, session: aiohttp.ClientSession | None = None)[source]

Bases: object

Asynchronous client for Invoxia API.

async close()[source]: Close current session.

classmethod get_auth(config: Config) → aiohttp.BasicAuth[source]: Form the authentication instance associated to a config.

async get_device(device_id: int) → Device[source]

Return a device referenced by its id.

Parameters:: device_id (int) – Unique identifier of a device
Returns:: Device instance of given id
Return type:: Device

async get_devices(kind: str | None = None) → List[Device][source]

Return devices associated to credentials.

By default, all devices (included associated smartphones) are returned. The kind parameter allows to filter only devices of a given type (‘android’, ‘iphone’ or ‘tracker’).

Parameters:: kind (str, optional) – kind of devices to retrieve
Returns:: List of retrieved devices
Return type:: List[Device]

async get_locations(device: Tracker, not_before: datetime | None = None, not_after: datetime | None = None, max_count: int = 20) → List[TrackerData][source]

Extract the list of tracker locations.

Parameters:

device (Tracker) – The tracker instance whose locations must be extracted.
not_before (datetime.datetime, optional) – Minimum date-time of the locations to extract.
not_after (datetime.datetime, optional) – Maximum date-time of the locations to extract.
max_count (int, optional) – Maximum count of position to extract. Note that one API query yields 20 locations.

Returns:

List of extracted locations

Return type:

List[TrackerData]

async get_tracker_config(device: Tracker) → TrackerConfig[source]

Get the current configuration of a given tracker.

Parameters:: device (Tracker) – The tracker instance whose configuration is queried.
Returns:: Current config of the tracker
Return type:: TrackerConfig

async get_tracker_status(device: Tracker) → TrackerStatus[source]

Get the current status of a given tracker.

Parameters:: device (Tracker) – The tracker instance whose status is queried.
Returns:: Current status of the tracker
Return type:: TrackerStatus

async get_trackers() → List[Tracker][source]

Query API for the list of trackers associated to credentials.

Returns:: Tracker devices associated to current account
Return type:: List[Tracker]

async get_user(user_id: int) → User[source]

Return a user referenced by its id.

Parameters:: user_id (int) – ID of the user to retrieve
Returns:: User instance associated to given ID
Return type:: User

async get_users() → List[User][source]

Return all users associated to credentials.

The API definition seems to indicate that multiple users can be associated to a single account (probably for pro subscriptions). For public consumers, this methods will return a single user.

Returns:: List of User instances associated to account
Return type:: List[User]

class gps_tracker.client.Client(config: Config)[source]

Bases: object

Synchronous client for Invoxia API.

get_device(device_id: int) → Device[source]

Return a device referenced by its id.

Parameters:: device_id (int) – Unique identifier of a device
Returns:: Device instance of given id
Return type:: Device

get_devices(kind: str | None = None) → List[Device][source]

Return devices associated to credentials.

By default, all devices (included associated smartphones) are returned. The kind parameter allows to filter only devices of a given type (‘android’, ‘iphone’ or ‘tracker’).

Parameters:: kind (str, optional) – kind of devices to retrieve
Returns:: List of retrieved devices
Return type:: List[Device]

get_locations(device: Tracker, not_before: datetime | None = None, not_after: datetime | None = None, max_count: int = 20) → List[TrackerData][source]

Extract the list of tracker locations.

Parameters:

device (Tracker) – The tracker instance whose locations must be extracted.
not_before (datetime.datetime, optional) – Minimum date-time of the locations to extract.
not_after (datetime.datetime, optional) – Maximum date-time of the locations to extract.
max_count (int, optional) – Maximum count of position to extract. Note that one API query yields 20 locations.

Returns:

List of extracted locations

Return type:

List[TrackerData]

get_tracker_config(device: Tracker) → TrackerConfig[source]

Get the current configuration of a given tracker.

Parameters:: device (Tracker) – The tracker instance whose configuration is queried.
Returns:: Current config of the tracker
Return type:: TrackerConfig

get_tracker_status(device: Tracker) → TrackerStatus[source]

Get the current status of a given tracker.

Parameters:: device (Tracker) – The tracker instance whose status is queried.
Returns:: Current status of the tracker
Return type:: TrackerStatus

get_trackers() → List[Tracker][source]

Query API for the list of trackers associated to credentials.

Returns:: Tracker devices associated to current account
Return type:: List[Tracker]

get_user(user_id: int) → User[source]

Return a user referenced by its id.

Parameters:: user_id (int) – ID of the user to retrieve
Returns:: User instance associated to given ID
Return type:: User

get_users() → List[User][source]

Return all users associated to credentials.

The API definition seems to indicate that multiple users can be associated to a single account (probably for pro subscriptions). For public consumers, this methods will return a single user.

Returns:: List of User instances associated to account
Return type:: List[User]

class gps_tracker.client.Config(username: str, password: str, api_url: str = 'https://labs.invoxia.io')[source]

Bases: object

Configuration for API Clients.

api_url: str: Invoxia API URL.

classmethod default_api_url() → str[source]: Return the default API URL.

password: str: Password used as credentials on Invoxia account.

username: str: Username used as credentials on Invoxia account.

class gps_tracker.client.Device(id, created: str | None, name, version, *, timezone=None)[source]

Bases: object

Base class for devices.

created: datetime: Datetime of device registration.

static get(device_data: dict[str, Any]) → Device[source]: Generate a Device object based on its type.

classmethod get_types() → Iterable[str][source]: Return list of registered device types.

id: int: Device unique identifier.

name: str: Device name.

timezone: str | None: Timezone associated to device.

version: str: Device version.

class gps_tracker.client.Tracker(id, created: str | None, name, version, *, timezone=None)[source]

Bases: Device

Base class for trackers.

created: datetime: Datetime of device registration.

id: int: Device unique identifier.

name: str: Device name.

timezone: str | None: Timezone associated to device.

version: str: Device version.

class gps_tracker.client.TrackerData(datetime: str | None, lat, lng, method, pkt_drop, precision, uuid)[source]

Bases: object

Definition of tracker location data.

datetime: datetime: Datetime of location measurement.

lat: float: Device latitude.

lng: float: Device longitude.

method: TrackerMethod: Method used for location acquisition.

pkt_drop: int: To be determined. (Probably number of packet drop since last location).

precision: int: Precision of location measurement (To be confirmed).

uuid: UUID: Universally unique identifier of location data.