aiomapit 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1 @@
1
+ * @mapit-iot/maintainers
@@ -0,0 +1,30 @@
1
+ name: CI
2
+ on:
3
+ pull_request:
4
+ push:
5
+ branches: [main]
6
+ # A private repo spends Actions minutes against a cap: one cheap job, newest push wins.
7
+ concurrency:
8
+ group: ci-${{ github.ref }}
9
+ cancel-in-progress: true
10
+ permissions:
11
+ contents: read
12
+ jobs:
13
+ check:
14
+ runs-on: ubuntu-latest
15
+ timeout-minutes: 10
16
+ strategy:
17
+ fail-fast: false
18
+ matrix:
19
+ python: ["3.12", "3.13"]
20
+ steps:
21
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
22
+ - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
23
+ with:
24
+ python-version: ${{ matrix.python }}
25
+ enable-cache: true
26
+ - run: uv sync --locked
27
+ - run: uv run ruff check .
28
+ - run: uv run ruff format --check .
29
+ - run: uv run mypy
30
+ - run: uv run pytest
@@ -0,0 +1,30 @@
1
+ # PyPI trusted publisher: mapit-iot/aiomapit, workflow release.yml, environment pypi.
2
+ name: Release
3
+ on:
4
+ release:
5
+ types: [published]
6
+ permissions:
7
+ contents: read
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
13
+ - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
14
+ - run: uv build
15
+ - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
16
+ with:
17
+ name: dist
18
+ path: dist/
19
+ publish:
20
+ needs: build
21
+ runs-on: ubuntu-latest
22
+ environment: pypi
23
+ permissions:
24
+ id-token: write # trusted publishing: no token stored
25
+ steps:
26
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
27
+ with:
28
+ name: dist
29
+ path: dist/
30
+ - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
@@ -0,0 +1,8 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
5
+ .coverage
6
+ .mypy_cache/
7
+ .pytest_cache/
8
+ .ruff_cache/
@@ -0,0 +1,10 @@
1
+ # aiomapit
2
+
3
+ Async Python client for the Mapit API. The API is documented at https://developers.mapit.me
4
+ (reference and OpenAPI at https://api.mapit.me/v1/openapi.json). Library only: no OAuth, no global
5
+ session. Home Assistant depends on it, so keep it small, typed and dependency-free beyond aiohttp.
6
+
7
+ Checks (use a uv virtualenv): `uv sync`, then `uv run ruff check .`, `uv run ruff format --check .`,
8
+ `uv run mypy`, `uv run pytest` (coverage must stay at 95% or more). Tests mock HTTP with
9
+ aioresponses; `aiohttp<3.14` is pinned in the dev group because aioresponses does not support 3.14 yet.
10
+ Never merge your own PR.
@@ -0,0 +1,8 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 - 2026-11-17
4
+
5
+ First release: every `/v1` endpoint (account, summary, vehicles, subscription, status, routes,
6
+ route geometry, ride stats, connections), cursor pagination as async iterators, ETag and
7
+ `If-None-Match` with a cached object on 304, typed errors from `application/problem+json`.
8
+ `Account.id`: the stable account id from `/v1/me` (None from servers that predate it).
aiomapit-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mapit IoT S.L.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,145 @@
1
+ Metadata-Version: 2.5
2
+ Name: aiomapit
3
+ Version: 0.1.0
4
+ Summary: Async Python client for the Mapit API
5
+ Project-URL: Homepage, https://github.com/mapit-iot/aiomapit
6
+ Project-URL: Issues, https://github.com/mapit-iot/aiomapit/issues
7
+ Project-URL: Changelog, https://github.com/mapit-iot/aiomapit/blob/main/CHANGELOG.md
8
+ Author: Mapit IoT S.L.
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: aiohttp,api,asyncio,home-assistant,mapit
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Framework :: AsyncIO
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Typing :: Typed
19
+ Requires-Python: >=3.12
20
+ Requires-Dist: aiohttp>=3.9
21
+ Description-Content-Type: text/markdown
22
+
23
+ # aiomapit
24
+
25
+ Async Python client for the [Mapit](https://mapit.me) API (`https://api.mapit.me/v1`): the account,
26
+ vehicles, last reported position and routes that the Mapit app shows. Read-only, apart from disconnecting
27
+ apps and keys (`delete_connection`, which needs the Manage connections permission). Built on `aiohttp`,
28
+ fully typed. Used by the Home Assistant integration.
29
+
30
+ > **Beta, free for now.** The Mapit API it talks to is a beta: it may change or stop, it has no uptime promise, and Mapit does not charge for it today. This library may need updates to follow it. Do not rely on it for emergencies or to recover a stolen bike: use the Mapit app. Use is subject to the [Mapit API Terms of Use](https://developers.mapit.me/terms) and [Privacy Notice](https://developers.mapit.me/privacy), for personal, non-commercial use.
31
+
32
+ ```
33
+ pip install aiomapit
34
+ ```
35
+
36
+ Python 3.12 or newer.
37
+
38
+ ## A personal key (your own scripts)
39
+
40
+ You need a Mapit account. Create a key at <https://login.mapit.me/connections> and pass it as the token.
41
+ Location, route history and managing connections each need their own permission, ticked when the key
42
+ is created (see [personal keys](https://developers.mapit.me/keys)).
43
+
44
+ ```python
45
+ import asyncio
46
+
47
+ from aiomapit import MapitClient
48
+
49
+
50
+ async def main() -> None:
51
+ async with MapitClient("mapit_...") as client:
52
+ async for status in client.iter_statuses():
53
+ if status.state:
54
+ print(status.vehicle_id, status.state.latitude, status.state.longitude)
55
+
56
+
57
+ asyncio.run(main())
58
+ ```
59
+
60
+ ## A token callback (apps that do OAuth themselves)
61
+
62
+ This is for apps that Mapit has approved (see [Approved apps](https://developers.mapit.me/approved-apps)); anything built for other Mapit customers needs Mapit's written approval. The
63
+ OAuth flow itself is described at <https://developers.mapit.me/oauth>. The library has no OAuth logic. Give it an async callable that returns a valid access token; it is
64
+ called before every request, so it may refresh. Share your own `aiohttp.ClientSession`:
65
+
66
+ ```python
67
+ async def token() -> str:
68
+ await oauth_session.async_ensure_token_valid()
69
+ return oauth_session.token["access_token"]
70
+
71
+
72
+ client = MapitClient(token, session=session, user_agent="my-app/1.0")
73
+ vehicles = [v async for v in client.iter_vehicles()]
74
+ ```
75
+
76
+ Without `session`, the client creates one and closes it in `close()` (or when leaving `async with`).
77
+ With one, the session stays yours.
78
+
79
+ ## What it covers
80
+
81
+ | Method | Endpoint |
82
+ | --- | --- |
83
+ | `get_me()` (an `Account` with `id`, `name`, `email`; `id` is stable across email changes) | `GET /me` |
84
+ | `get_summary(vehicle_cursor=, transfer_cursor=)` | `GET /summary` |
85
+ | `get_vehicles_page(cursor)`, `iter_vehicles()` | `GET /vehicles` |
86
+ | `get_vehicle(id)`, `get_subscription(id)` | `GET /vehicles/{id}`, `.../subscription` |
87
+ | `get_statuses_page(cursor)`, `iter_statuses()`, `get_vehicle_status(id)` (Location permission) | `GET /status`, `/vehicles/{id}/status` |
88
+ | `get_routes_page(id, day=, start=, end=, ...)`, `iter_routes(id, ...)` (Route history permission) | `GET /vehicles/{id}/routes` |
89
+ | `get_route(id, route_id, geometry=, simplify=)` (Route history) | `GET /vehicles/{id}/routes/{route_id}` |
90
+ | `get_ride_stats(id, start, end, timezone=)` (Route history) | `GET /vehicles/{id}/stats` |
91
+ | `get_connections()`, `delete_connection(id)` | `GET`, `DELETE /me/connections` (a personal key with "Manage connections") |
92
+
93
+ Ids and cursors are opaque: pass them back as you got them. `iter_*` follow the cursors for you.
94
+ The API allows 30 requests a minute per key or token, and positions are what the device last
95
+ reported, so poll `iter_statuses()` once a minute at most.
96
+
97
+ Every `get_*` returns a `Response` with `data` (a frozen dataclass, snake_case fields),
98
+ `not_modified` and `etag`.
99
+
100
+ ## ETag and 304
101
+
102
+ The client remembers the `ETag` of what it fetched (in memory, per URL and query) and sends it as
103
+ `If-None-Match`. On `304` you get the earlier object back with `not_modified=True`:
104
+
105
+ ```python
106
+ res = await client.get_vehicle_status(vehicle_id)
107
+ if not res.not_modified:
108
+ update(res.data)
109
+ ```
110
+
111
+ The cache key includes the token, so two tokens never share an object; a refreshed OAuth token starts
112
+ with a fresh cache. A 304 saves bandwidth and parsing, not quota: it still counts towards the 30 requests a minute.
113
+ The routes list without a `day` or `start`/`end` is "the last 30 days to now" and never answers 304.
114
+
115
+ ## Errors
116
+
117
+ All derive from `MapitError`, which has `status`, `title` and `detail` from the
118
+ `application/problem+json` body.
119
+
120
+ | Raised | When |
121
+ | --- | --- |
122
+ | `MapitAuthError` | 401: missing, expired or revoked token |
123
+ | `MapitScopeError` | 403 `insufficient_scope`; `.scope` is the missing scope |
124
+ | `MapitNotFound` | 404: also for a foreign or unknown id |
125
+ | `MapitRateLimited` | 429; `.retry_after` in seconds, or `None` |
126
+ | `MapitConnectionError` | 5xx, timeout, network failure |
127
+ | `MapitResponseError` | a 2xx answer that is not valid JSON or lacks the expected fields |
128
+
129
+ Other statuses (such as 400 for a bad filter) raise `MapitError` itself. The client never retries:
130
+ back off on `MapitRateLimited` and `MapitConnectionError` yourself.
131
+
132
+ ## Development
133
+
134
+ ```
135
+ uv sync
136
+ uv run ruff check . && uv run ruff format --check .
137
+ uv run mypy
138
+ uv run pytest
139
+ ```
140
+
141
+ ## Help
142
+
143
+ Docs and API reference: <https://developers.mapit.me>. Questions: atencioncliente@mapit.me.
144
+
145
+ MIT licence.
@@ -0,0 +1,123 @@
1
+ # aiomapit
2
+
3
+ Async Python client for the [Mapit](https://mapit.me) API (`https://api.mapit.me/v1`): the account,
4
+ vehicles, last reported position and routes that the Mapit app shows. Read-only, apart from disconnecting
5
+ apps and keys (`delete_connection`, which needs the Manage connections permission). Built on `aiohttp`,
6
+ fully typed. Used by the Home Assistant integration.
7
+
8
+ > **Beta, free for now.** The Mapit API it talks to is a beta: it may change or stop, it has no uptime promise, and Mapit does not charge for it today. This library may need updates to follow it. Do not rely on it for emergencies or to recover a stolen bike: use the Mapit app. Use is subject to the [Mapit API Terms of Use](https://developers.mapit.me/terms) and [Privacy Notice](https://developers.mapit.me/privacy), for personal, non-commercial use.
9
+
10
+ ```
11
+ pip install aiomapit
12
+ ```
13
+
14
+ Python 3.12 or newer.
15
+
16
+ ## A personal key (your own scripts)
17
+
18
+ You need a Mapit account. Create a key at <https://login.mapit.me/connections> and pass it as the token.
19
+ Location, route history and managing connections each need their own permission, ticked when the key
20
+ is created (see [personal keys](https://developers.mapit.me/keys)).
21
+
22
+ ```python
23
+ import asyncio
24
+
25
+ from aiomapit import MapitClient
26
+
27
+
28
+ async def main() -> None:
29
+ async with MapitClient("mapit_...") as client:
30
+ async for status in client.iter_statuses():
31
+ if status.state:
32
+ print(status.vehicle_id, status.state.latitude, status.state.longitude)
33
+
34
+
35
+ asyncio.run(main())
36
+ ```
37
+
38
+ ## A token callback (apps that do OAuth themselves)
39
+
40
+ This is for apps that Mapit has approved (see [Approved apps](https://developers.mapit.me/approved-apps)); anything built for other Mapit customers needs Mapit's written approval. The
41
+ OAuth flow itself is described at <https://developers.mapit.me/oauth>. The library has no OAuth logic. Give it an async callable that returns a valid access token; it is
42
+ called before every request, so it may refresh. Share your own `aiohttp.ClientSession`:
43
+
44
+ ```python
45
+ async def token() -> str:
46
+ await oauth_session.async_ensure_token_valid()
47
+ return oauth_session.token["access_token"]
48
+
49
+
50
+ client = MapitClient(token, session=session, user_agent="my-app/1.0")
51
+ vehicles = [v async for v in client.iter_vehicles()]
52
+ ```
53
+
54
+ Without `session`, the client creates one and closes it in `close()` (or when leaving `async with`).
55
+ With one, the session stays yours.
56
+
57
+ ## What it covers
58
+
59
+ | Method | Endpoint |
60
+ | --- | --- |
61
+ | `get_me()` (an `Account` with `id`, `name`, `email`; `id` is stable across email changes) | `GET /me` |
62
+ | `get_summary(vehicle_cursor=, transfer_cursor=)` | `GET /summary` |
63
+ | `get_vehicles_page(cursor)`, `iter_vehicles()` | `GET /vehicles` |
64
+ | `get_vehicle(id)`, `get_subscription(id)` | `GET /vehicles/{id}`, `.../subscription` |
65
+ | `get_statuses_page(cursor)`, `iter_statuses()`, `get_vehicle_status(id)` (Location permission) | `GET /status`, `/vehicles/{id}/status` |
66
+ | `get_routes_page(id, day=, start=, end=, ...)`, `iter_routes(id, ...)` (Route history permission) | `GET /vehicles/{id}/routes` |
67
+ | `get_route(id, route_id, geometry=, simplify=)` (Route history) | `GET /vehicles/{id}/routes/{route_id}` |
68
+ | `get_ride_stats(id, start, end, timezone=)` (Route history) | `GET /vehicles/{id}/stats` |
69
+ | `get_connections()`, `delete_connection(id)` | `GET`, `DELETE /me/connections` (a personal key with "Manage connections") |
70
+
71
+ Ids and cursors are opaque: pass them back as you got them. `iter_*` follow the cursors for you.
72
+ The API allows 30 requests a minute per key or token, and positions are what the device last
73
+ reported, so poll `iter_statuses()` once a minute at most.
74
+
75
+ Every `get_*` returns a `Response` with `data` (a frozen dataclass, snake_case fields),
76
+ `not_modified` and `etag`.
77
+
78
+ ## ETag and 304
79
+
80
+ The client remembers the `ETag` of what it fetched (in memory, per URL and query) and sends it as
81
+ `If-None-Match`. On `304` you get the earlier object back with `not_modified=True`:
82
+
83
+ ```python
84
+ res = await client.get_vehicle_status(vehicle_id)
85
+ if not res.not_modified:
86
+ update(res.data)
87
+ ```
88
+
89
+ The cache key includes the token, so two tokens never share an object; a refreshed OAuth token starts
90
+ with a fresh cache. A 304 saves bandwidth and parsing, not quota: it still counts towards the 30 requests a minute.
91
+ The routes list without a `day` or `start`/`end` is "the last 30 days to now" and never answers 304.
92
+
93
+ ## Errors
94
+
95
+ All derive from `MapitError`, which has `status`, `title` and `detail` from the
96
+ `application/problem+json` body.
97
+
98
+ | Raised | When |
99
+ | --- | --- |
100
+ | `MapitAuthError` | 401: missing, expired or revoked token |
101
+ | `MapitScopeError` | 403 `insufficient_scope`; `.scope` is the missing scope |
102
+ | `MapitNotFound` | 404: also for a foreign or unknown id |
103
+ | `MapitRateLimited` | 429; `.retry_after` in seconds, or `None` |
104
+ | `MapitConnectionError` | 5xx, timeout, network failure |
105
+ | `MapitResponseError` | a 2xx answer that is not valid JSON or lacks the expected fields |
106
+
107
+ Other statuses (such as 400 for a bad filter) raise `MapitError` itself. The client never retries:
108
+ back off on `MapitRateLimited` and `MapitConnectionError` yourself.
109
+
110
+ ## Development
111
+
112
+ ```
113
+ uv sync
114
+ uv run ruff check . && uv run ruff format --check .
115
+ uv run mypy
116
+ uv run pytest
117
+ ```
118
+
119
+ ## Help
120
+
121
+ Docs and API reference: <https://developers.mapit.me>. Questions: atencioncliente@mapit.me.
122
+
123
+ MIT licence.
@@ -0,0 +1,62 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "aiomapit"
7
+ version = "0.1.0"
8
+ description = "Async Python client for the Mapit API"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Mapit IoT S.L." }]
13
+ requires-python = ">=3.12"
14
+ dependencies = ["aiohttp>=3.9"]
15
+ keywords = ["mapit", "api", "asyncio", "aiohttp", "home-assistant"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Framework :: AsyncIO",
19
+ "Intended Audience :: Developers",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Programming Language :: Python :: 3.13",
23
+ "Typing :: Typed",
24
+ ]
25
+
26
+ [project.urls]
27
+ Homepage = "https://github.com/mapit-iot/aiomapit"
28
+ Issues = "https://github.com/mapit-iot/aiomapit/issues"
29
+ Changelog = "https://github.com/mapit-iot/aiomapit/blob/main/CHANGELOG.md"
30
+
31
+ [dependency-groups]
32
+ dev = [
33
+ # aioresponses 0.7.9 breaks on aiohttp 3.14 (pnuckowski/aioresponses#288); lift when fixed.
34
+ "aiohttp<3.14",
35
+ "aioresponses>=0.7.6",
36
+ "mypy>=1.11",
37
+ "pytest>=8",
38
+ "pytest-asyncio>=0.24",
39
+ "pytest-cov>=5",
40
+ "ruff>=0.6",
41
+ ]
42
+
43
+ [tool.hatch.build.targets.wheel]
44
+ packages = ["src/aiomapit"]
45
+
46
+ [tool.pytest.ini_options]
47
+ asyncio_mode = "auto"
48
+ asyncio_default_fixture_loop_scope = "function"
49
+ addopts = "--cov=aiomapit --cov-report=term-missing --cov-fail-under=95"
50
+ testpaths = ["tests"]
51
+
52
+ [tool.mypy]
53
+ strict = true
54
+ files = ["src", "tests"]
55
+ mypy_path = "src"
56
+
57
+ [tool.ruff]
58
+ target-version = "py312"
59
+ line-length = 100
60
+
61
+ [tool.ruff.lint]
62
+ select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "ASYNC", "PT"]
@@ -0,0 +1,57 @@
1
+ """Async Python client for the Mapit API."""
2
+
3
+ from ._version import __version__
4
+ from .client import DEFAULT_BASE_URL, MapitClient, TokenProvider
5
+ from .exceptions import (
6
+ MapitAuthError,
7
+ MapitConnectionError,
8
+ MapitError,
9
+ MapitNotFound,
10
+ MapitRateLimited,
11
+ MapitResponseError,
12
+ MapitScopeError,
13
+ )
14
+ from .models import (
15
+ Account,
16
+ Connection,
17
+ DeviceState,
18
+ IncomingTransfer,
19
+ Page,
20
+ Response,
21
+ RideDay,
22
+ RideStats,
23
+ RideTotals,
24
+ Route,
25
+ Subscription,
26
+ Summary,
27
+ Vehicle,
28
+ VehicleStatus,
29
+ )
30
+
31
+ __all__ = [
32
+ "DEFAULT_BASE_URL",
33
+ "Account",
34
+ "Connection",
35
+ "DeviceState",
36
+ "IncomingTransfer",
37
+ "MapitAuthError",
38
+ "MapitClient",
39
+ "MapitConnectionError",
40
+ "MapitError",
41
+ "MapitNotFound",
42
+ "MapitRateLimited",
43
+ "MapitResponseError",
44
+ "MapitScopeError",
45
+ "Page",
46
+ "Response",
47
+ "RideDay",
48
+ "RideStats",
49
+ "RideTotals",
50
+ "Route",
51
+ "Subscription",
52
+ "Summary",
53
+ "TokenProvider",
54
+ "Vehicle",
55
+ "VehicleStatus",
56
+ "__version__",
57
+ ]
@@ -0,0 +1,4 @@
1
+ from importlib.metadata import version
2
+
3
+ # Read once at import: reading it per client would hit the disk inside the event loop.
4
+ __version__ = version("aiomapit")