findmy.reports.reports

Module providing functionality to look up location reports.

Attributes

logger
LocationReportMapping

Classes

LocationReportEncryptedMapping	JSON mapping representing an encrypted location report.
LocationReportDecryptedMapping	JSON mapping representing a decrypted location report.
LocationReport	Location report corresponding to a certain HasHashedPublicKey().
LocationReportsFetcher	Fetcher class to retrieve location reports.

Module Contents

findmy.reports.reports.logger

class findmy.reports.reports.LocationReportEncryptedMapping

Bases: TypedDict

JSON mapping representing an encrypted location report.

type: Literal['locReportEncrypted']

payload: str

hashed_adv_key: str

class findmy.reports.reports.LocationReportDecryptedMapping

Bases: TypedDict

JSON mapping representing a decrypted location report.

type: Literal['locReportDecrypted']

payload: str

hashed_adv_key: str

key: findmy.keys.KeyPairMapping

findmy.reports.reports.LocationReportMapping

class findmy.reports.reports.LocationReport(payload: bytes, hashed_adv_key: bytes)

Bases: findmy.keys.HasHashedPublicKey, findmy.util.abc.Serializable[LocationReportMapping]

Location report corresponding to a certain HasHashedPublicKey().

property hashed_adv_key_bytes: bytes

See HasHashedPublicKey.hashed_adv_key_bytes().

property key: findmy.keys.KeyPair

KeyPair using which this report was decrypted.

property payload: bytes

Full (partially encrypted) payload of the report, as retrieved from Apple.

property is_decrypted: bool

Whether the report is currently decrypted.

can_decrypt(key: findmy.keys.KeyPair, /) → bool

Whether the report can be decrypted using the given key.

decrypt(key: findmy.keys.KeyPair) → None

Decrypt the report using its corresponding KeyPair().

property timestamp: datetime.datetime

The datetime() when this report was recorded by a device.

property confidence: int

Confidence of the location of this report. Int between 1 and 3.

property latitude: float

Latitude of the location of this report.

property longitude: float

Longitude of the location of this report.

property horizontal_accuracy: int

Horizontal accuracy of the location of this report.

property status: int

Status byte of the accessory as recorded by a device, as an integer.

to_json(dst: str | pathlib.Path | io.TextIOBase | None = None, /, *, include_key: Literal[True]) → LocationReportEncryptedMapping

to_json(dst: str | pathlib.Path | io.TextIOBase | None = None, /, *, include_key: Literal[False]) → LocationReportDecryptedMapping

to_json(dst: str | pathlib.Path | io.TextIOBase | None = None, /, *, include_key: None = None) → LocationReportMapping

Export the current state of the object as a JSON-serializable dictionary.

If an argument is provided, the output will also be written to that file.

The output of this method is guaranteed to be JSON-serializable, and passing the return value of this function as an argument to Serializable.from_json() will always result in an exact copy of the internal state as it was when exported.

You are encouraged to save and load object states to and from disk whenever possible, to prevent unnecessary API calls or otherwise unexpected behavior.

classmethod from_json(val: str | pathlib.Path | io.TextIOBase | io.BufferedIOBase | LocationReportMapping, /) → LocationReport

Restore state from a previous Closable.to_json() export.

If given a str or Path, it must point to a json file from Serializable.to_json(). Otherwise, it should be the Mapping itself.

See Serializable.to_json() for more information.

__eq__(other: object) → bool

Compare two report instances.

Two reports are considered equal iff they correspond to the same key, were reported at the same timestamp and represent the same physical location.

__hash__() → int

Get the hash of this instance.

Two instances will have the same hash iff they correspond to the same key, were reported at the same timestamp and represent the same physical location.

__lt__(other: LocationReport) → bool

Compare against another LocationReport().

A LocationReport() is said to be “less than” another LocationReport() iff its recorded timestamp is strictly less than the other report.

__repr__() → str

Human-readable string representation of the location report.

class findmy.reports.reports.LocationReportsFetcher(account: findmy.reports.account.AsyncAppleAccount)

Fetcher class to retrieve location reports.

async fetch_location_history(device: findmy.keys.HasHashedPublicKey) → list[LocationReport]

async fetch_location_history(device: findmy.accessory.RollingKeyPairSource) → list[LocationReport]

async fetch_location_history(device: collections.abc.Sequence[findmy.keys.HasHashedPublicKey | findmy.accessory.RollingKeyPairSource]) → dict[findmy.keys.HasHashedPublicKey | findmy.accessory.RollingKeyPairSource, list[LocationReport]]

Fetch location history for a certain device or multiple devices.

When device is a single HasHashedPublicKey, this method will return a list of location reports corresponding to that key. When device is a RollingKeyPairSource, it will return a list of location reports corresponding to that source. When device is a sequence of :class:`HasHashedPublicKey`s or RollingKeyPairSource’s, it will return a dictionary with the provided objects as keys, and a list of location reports as value.

Note that the location history of RollingKeyPairSource devices is not guaranteed to be complete, and may be missing certain historical reports. The most recent report is however guaranteed to be in line with what Apple reports.