Pytile 2023.12.0

Description:

pytile 2023.12.0

📡 pytile: A simple Python API for Tile® Bluetooth trackers

pytile is a simple Python library for retrieving information on
Tile® Bluetooth trackers (including last location and more).
This library is built on an unpublished, unofficial Tile API; it may alter or
cease operation at any point.

Python Versions
Installation
Usage
Contributing

NOTE: Version 5.0.0
Version 5.0.0 is a complete re-architecture of pytile – as such, the API has changed.
Please read the documentation carefully!
Python Versions
pytile is currently supported on:

Python 3.10
Python 3.11
Python 3.12

Installation
pip install pytile

Usage
Getting an API Object
pytile usage starts with an aiohttp ClientSession – note that this
ClientSession is required to properly authenticate the library:
import asyncio

from aiohttp import ClientSession

from pytile import async_login

async def main() -> None:
"""Run!"""
async with ClientSession() as session:
api = await async_login("<EMAIL>", "<PASSWORD>", session)

asyncio.run(main())

If for some reason you need to use a specific client UUID (to, say, ensure that the
Tile API sees you as a client it's seen before) or a specific locale, you can do
so easily:
import asyncio

from aiohttp import ClientSession

from pytile import async_login

async def main() -> None:
"""Run!"""
async with ClientSession() as session:
api = await async_login(
"<EMAIL>", "<PASSWORD>", session, client_uuid="MY_UUID", locale="en-GB"
)

asyncio.run(main())

Getting Tiles
Tile Premium Required: No
import asyncio

from aiohttp import ClientSession

from pytile import async_login

async def main() -> None:
"""Run!"""
async with ClientSession() as session:
api = await async_login("<EMAIL>", "<PASSWORD>", session)

tiles = await api.async_get_tiles()

asyncio.run(main())

The async_get_tiles coroutine returns a dict with Tile UUIDs as the keys and Tile
objects as the values.
The Tile Object
The Tile object comes with several properties:

accuracy: the location accuracy of the Tile
altitude: the altitude of the Tile
archetype: the internal reference string that describes the Tile's "family"
dead: whether the Tile is inactive
firmware_version: the Tile's firmware version
hardware_version: the Tile's hardware version
kind: the kind of Tile (e.g., TILE, PHONE)
last_timestamp: the timestamp at which the current attributes were received
latitude: the latitude of the Tile
longitude: the latitude of the Tile
lost: whether the Tile has been marked as "lost"
lost_timestamp: the timestamp at which the Tile was last marked as "lost"
name: the name of the Tile
uuid: the Tile UUID
visible: whether the Tile is visible in the mobile app

import asyncio

from aiohttp import ClientSession

from pytile import async_login

async def main() -> None:
"""Run!"""
async with ClientSession() as session:
api = await async_login("<EMAIL>", "<PASSWORD>", session)

tiles = await api.async_get_tiles()

for tile_uuid, tile in tiles.items():
print(f"The Tile's name is {tile.name}")
# ...

asyncio.run(main())

In addition to these properties, the Tile object comes with an async_update coroutine
which requests new data from the Tile cloud API for this Tile:
import asyncio

from aiohttp import ClientSession

from pytile import async_login

async def main() -> None:
"""Run!"""
async with ClientSession() as session:
api = await async_login("<EMAIL>", "<PASSWORD>", session)

tiles = await api.async_get_tiles()

for tile_uuid, tile in tiles.items():
await tile.async_update()

asyncio.run(main())

Getting Premium Tile's History
Tile Premium Required: Yes
You can retrieve a Tile's history by calling its async_history coroutine:
import asyncio
from datetime import datetime

from aiohttp import ClientSession

from pytile import async_login

async def main() -> None:
"""Run!"""
async with ClientSession() as session:
api = await async_login("<EMAIL>", "<PASSWORD>", session)

tiles = await api.async_get_tiles()

for tile_uuid, tile in tiles.items():
# Define a start and end datetime to get history for:
start = datetime(2023, 1, 1, 0, 0, 0)
end = datetime(2023, 1, 31, 0, 0, 0)
history = await tile.async_history(start, end)
# >>> { "version": 1, "revision": 1, ... }

asyncio.run(main())

Contributing
Thanks to all of our contributors so far!

Check for open features/bugs or initiate a discussion on one.
Fork the repository.
(optional, but highly recommended) Create a virtual environment: python3 -m venv .venv
(optional, but highly recommended) Enter the virtual environment: source ./.venv/bin/activate
Install the dev environment: script/setup
Code your new feature or bug fix on a new branch.
Write tests that cover your new functionality.
Run tests and ensure 100% code coverage: poetry run pytest --cov pytile tests
Update README.md with any new documentation.
Submit a pull request!