| Name | pytile JSON |
| Version |
2023.12.0
JSON |
| download |
| home_page | https://github.com/bachya/pytile |
| Summary | A simple Python API for Tile® Bluetooth trackers |
| upload_time | 2023-12-18 02:11:51 |
| maintainer | |
| docs_url | None |
| author | Aaron Bach |
| requires_python | >=3.10,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 📡 pytile: A simple Python API for Tile® Bluetooth trackers
[![CI][ci-badge]][ci]
[![PyPI][pypi-badge]][pypi]
[![Version][version-badge]][version]
[![License][license-badge]][license]
[![Code Coverage][codecov-badge]][codecov]
[![Maintainability][maintainability-badge]][maintainability]
<a href="https://www.buymeacoffee.com/bachya1208P" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
`pytile` is a simple Python library for retrieving information on
[Tile® Bluetooth trackers][tile] (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](#python-versions)
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#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
```bash
pip install pytile
```
# Usage
## Getting an API Object
`pytile` usage starts with an [`aiohttp`][aiohttp] `ClientSession` – note that this
ClientSession is required to properly authenticate the library:
```python
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:
```python
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**
```python
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
```python
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:
```python
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:
```python
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][contributors] so far!
1. [Check for open features/bugs][issues] or [initiate a discussion on one][new-issue].
2. [Fork the repository][fork].
3. (_optional, but highly recommended_) Create a virtual environment: `python3 -m venv .venv`
4. (_optional, but highly recommended_) Enter the virtual environment: `source ./.venv/bin/activate`
5. Install the dev environment: `script/setup`
6. Code your new feature or bug fix on a new branch.
7. Write tests that cover your new functionality.
8. Run tests and ensure 100% code coverage: `poetry run pytest --cov pytile tests`
9. Update `README.md` with any new documentation.
10. Submit a pull request!
[aiohttp]: https://github.com/aio-libs/aiohttp
[ci-badge]: https://github.com/bachya/pytile/workflows/CI/badge.svg
[ci]: https://github.com/bachya/pytile/actions
[codecov-badge]: https://codecov.io/gh/bachya/pytile/branch/dev/graph/badge.svg
[codecov]: https://codecov.io/gh/bachya/pytile
[contributors]: https://github.com/bachya/pytile/graphs/contributors
[fork]: https://github.com/bachya/pytile/fork
[issues]: https://github.com/bachya/pytile/issues
[license-badge]: https://img.shields.io/pypi/l/pytile.svg
[license]: https://github.com/bachya/pytile/blob/main/LICENSE
[maintainability-badge]: https://api.codeclimate.com/v1/badges/71eb642c735e33adcdfc/maintainability
[maintainability]: https://codeclimate.com/github/bachya/pytile/maintainability
[new-issue]: https://github.com/bachya/pytile/issues/new
[pypi-badge]: https://img.shields.io/pypi/v/pytile.svg
[pypi]: https://pypi.python.org/pypi/pytile
[tile]: https://www.thetileapp.com
[version-badge]: https://img.shields.io/pypi/pyversions/pytile.svg
[version]: https://pypi.python.org/pypi/pytile
Raw data
{
"_id": null,
"home_page": "https://github.com/bachya/pytile",
"name": "pytile",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Aaron Bach",
"author_email": "bachya1208@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ea/04/8893c318486e35acff0522ce6600299d2b8bb08557795390eb1b2b1f950e/pytile-2023.12.0.tar.gz",
"platform": null,
"description": "# \ud83d\udce1 pytile: A simple Python API for Tile\u00ae Bluetooth trackers\n\n[![CI][ci-badge]][ci]\n[![PyPI][pypi-badge]][pypi]\n[![Version][version-badge]][version]\n[![License][license-badge]][license]\n[![Code Coverage][codecov-badge]][codecov]\n[![Maintainability][maintainability-badge]][maintainability]\n\n<a href=\"https://www.buymeacoffee.com/bachya1208P\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"41\" width=\"174\"></a>\n\n`pytile` is a simple Python library for retrieving information on\n[Tile\u00ae Bluetooth trackers][tile] (including last location and more).\n\nThis library is built on an unpublished, unofficial Tile API; it may alter or\ncease operation at any point.\n\n- [Python Versions](#python-versions)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Contributing](#contributing)\n\n# NOTE: Version 5.0.0\n\nVersion 5.0.0 is a complete re-architecture of `pytile` \u2013 as such, the API has changed.\nPlease read the documentation carefully!\n\n# Python Versions\n\n`pytile` is currently supported on:\n\n- Python 3.10\n- Python 3.11\n- Python 3.12\n\n# Installation\n\n```bash\npip install pytile\n```\n\n# Usage\n\n## Getting an API Object\n\n`pytile` usage starts with an [`aiohttp`][aiohttp] `ClientSession` \u2013 note that this\nClientSession is required to properly authenticate the library:\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom pytile import async_login\n\n\nasync def main() -> None:\n \"\"\"Run!\"\"\"\n async with ClientSession() as session:\n api = await async_login(\"<EMAIL>\", \"<PASSWORD>\", session)\n\n\nasyncio.run(main())\n```\n\nIf for some reason you need to use a specific client UUID (to, say, ensure that the\nTile API sees you as a client it's seen before) or a specific locale, you can do\nso easily:\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom pytile import async_login\n\n\nasync def main() -> None:\n \"\"\"Run!\"\"\"\n async with ClientSession() as session:\n api = await async_login(\n \"<EMAIL>\", \"<PASSWORD>\", session, client_uuid=\"MY_UUID\", locale=\"en-GB\"\n )\n\n\nasyncio.run(main())\n```\n\n## Getting Tiles\n\n**Tile Premium Required: No**\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom pytile import async_login\n\n\nasync def main() -> None:\n \"\"\"Run!\"\"\"\n async with ClientSession() as session:\n api = await async_login(\"<EMAIL>\", \"<PASSWORD>\", session)\n\n tiles = await api.async_get_tiles()\n\n\nasyncio.run(main())\n```\n\nThe `async_get_tiles` coroutine returns a dict with Tile UUIDs as the keys and `Tile`\nobjects as the values.\n\n### The `Tile` Object\n\nThe Tile object comes with several properties:\n\n- `accuracy`: the location accuracy of the Tile\n- `altitude`: the altitude of the Tile\n- `archetype`: the internal reference string that describes the Tile's \"family\"\n- `dead`: whether the Tile is inactive\n- `firmware_version`: the Tile's firmware version\n- `hardware_version`: the Tile's hardware version\n- `kind`: the kind of Tile (e.g., `TILE`, `PHONE`)\n- `last_timestamp`: the timestamp at which the current attributes were received\n- `latitude`: the latitude of the Tile\n- `longitude`: the latitude of the Tile\n- `lost`: whether the Tile has been marked as \"lost\"\n- `lost_timestamp`: the timestamp at which the Tile was last marked as \"lost\"\n- `name`: the name of the Tile\n- `uuid`: the Tile UUID\n- `visible`: whether the Tile is visible in the mobile app\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom pytile import async_login\n\n\nasync def main() -> None:\n \"\"\"Run!\"\"\"\n async with ClientSession() as session:\n api = await async_login(\"<EMAIL>\", \"<PASSWORD>\", session)\n\n tiles = await api.async_get_tiles()\n\n for tile_uuid, tile in tiles.items():\n print(f\"The Tile's name is {tile.name}\")\n # ...\n\n\nasyncio.run(main())\n```\n\nIn addition to these properties, the `Tile` object comes with an `async_update` coroutine\nwhich requests new data from the Tile cloud API for this Tile:\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom pytile import async_login\n\n\nasync def main() -> None:\n \"\"\"Run!\"\"\"\n async with ClientSession() as session:\n api = await async_login(\"<EMAIL>\", \"<PASSWORD>\", session)\n\n tiles = await api.async_get_tiles()\n\n for tile_uuid, tile in tiles.items():\n await tile.async_update()\n\n\nasyncio.run(main())\n```\n\n## Getting Premium Tile's History\n\n**Tile Premium Required: Yes**\n\nYou can retrieve a Tile's history by calling its `async_history` coroutine:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom aiohttp import ClientSession\n\nfrom pytile import async_login\n\n\nasync def main() -> None:\n \"\"\"Run!\"\"\"\n async with ClientSession() as session:\n api = await async_login(\"<EMAIL>\", \"<PASSWORD>\", session)\n\n tiles = await api.async_get_tiles()\n\n for tile_uuid, tile in tiles.items():\n # Define a start and end datetime to get history for:\n start = datetime(2023, 1, 1, 0, 0, 0)\n end = datetime(2023, 1, 31, 0, 0, 0)\n history = await tile.async_history(start, end)\n # >>> { \"version\": 1, \"revision\": 1, ... }\n\n\nasyncio.run(main())\n```\n\n# Contributing\n\nThanks to all of [our contributors][contributors] so far!\n\n1. [Check for open features/bugs][issues] or [initiate a discussion on one][new-issue].\n2. [Fork the repository][fork].\n3. (_optional, but highly recommended_) Create a virtual environment: `python3 -m venv .venv`\n4. (_optional, but highly recommended_) Enter the virtual environment: `source ./.venv/bin/activate`\n5. Install the dev environment: `script/setup`\n6. Code your new feature or bug fix on a new branch.\n7. Write tests that cover your new functionality.\n8. Run tests and ensure 100% code coverage: `poetry run pytest --cov pytile tests`\n9. Update `README.md` with any new documentation.\n10. Submit a pull request!\n\n[aiohttp]: https://github.com/aio-libs/aiohttp\n[ci-badge]: https://github.com/bachya/pytile/workflows/CI/badge.svg\n[ci]: https://github.com/bachya/pytile/actions\n[codecov-badge]: https://codecov.io/gh/bachya/pytile/branch/dev/graph/badge.svg\n[codecov]: https://codecov.io/gh/bachya/pytile\n[contributors]: https://github.com/bachya/pytile/graphs/contributors\n[fork]: https://github.com/bachya/pytile/fork\n[issues]: https://github.com/bachya/pytile/issues\n[license-badge]: https://img.shields.io/pypi/l/pytile.svg\n[license]: https://github.com/bachya/pytile/blob/main/LICENSE\n[maintainability-badge]: https://api.codeclimate.com/v1/badges/71eb642c735e33adcdfc/maintainability\n[maintainability]: https://codeclimate.com/github/bachya/pytile/maintainability\n[new-issue]: https://github.com/bachya/pytile/issues/new\n[pypi-badge]: https://img.shields.io/pypi/v/pytile.svg\n[pypi]: https://pypi.python.org/pypi/pytile\n[tile]: https://www.thetileapp.com\n[version-badge]: https://img.shields.io/pypi/pyversions/pytile.svg\n[version]: https://pypi.python.org/pypi/pytile\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple Python API for Tile\u00ae Bluetooth trackers",
"version": "2023.12.0",
"project_urls": {
"Bug Tracker": "https://github.com/bachya/pytile/issues",
"Changelog": "https://github.com/bachya/pytile/releases",
"Homepage": "https://github.com/bachya/pytile",
"Repository": "https://github.com/bachya/pytile"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0aed229dd6b9197b363dfc3b786268808cec8df5dcd9bfc051be150212e7d9fb",
"md5": "9793bf9040d3437b1d293022febbb466",
"sha256": "164c18e834977b7be3236083c0338e0ab7ada74229ce408c7657ada1ed69d8a9"
},
"downloads": -1,
"filename": "pytile-2023.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9793bf9040d3437b1d293022febbb466",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 8899,
"upload_time": "2023-12-18T02:11:50",
"upload_time_iso_8601": "2023-12-18T02:11:50.688120Z",
"url": "https://files.pythonhosted.org/packages/0a/ed/229dd6b9197b363dfc3b786268808cec8df5dcd9bfc051be150212e7d9fb/pytile-2023.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ea048893c318486e35acff0522ce6600299d2b8bb08557795390eb1b2b1f950e",
"md5": "72b6ae4d2968f2f8109114c3fd712d1f",
"sha256": "cd0a00e0c4884c35baac523ae0ea1c0222aea2ec1485c9830aa3909191ad3b34"
},
"downloads": -1,
"filename": "pytile-2023.12.0.tar.gz",
"has_sig": false,
"md5_digest": "72b6ae4d2968f2f8109114c3fd712d1f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 10498,
"upload_time": "2023-12-18T02:11:51",
"upload_time_iso_8601": "2023-12-18T02:11:51.963751Z",
"url": "https://files.pythonhosted.org/packages/ea/04/8893c318486e35acff0522ce6600299d2b8bb08557795390eb1b2b1f950e/pytile-2023.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-18 02:11:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bachya",
"github_project": "pytile",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pytile"
}
