chargealong 0.1.0__tar.gz

chargealong-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      # No install step: the library has no dependencies and the suite runs on
+      # stdlib unittest, so this is the real "does it work from scratch".
+      - run: PYTHONPATH=src python -m unittest discover -s tests -v

chargealong-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+# Trusted publishing: PyPI verifies this workflow's identity, so there is no
+# long lived API token in the repository to leak. Configure the publisher at
+# pypi.org/manage/project/chargealong/settings/publishing/ before the first tag.
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: PYTHONPATH=src python -m unittest discover -s tests
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

chargealong-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.venv/

chargealong-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `nearby`, `site`, `search`, `plan_trip`, `vehicles`, `vehicle`, `countries`,
+  `overview`, `country`, `region`, `networks`, `network`, `locality` and
+  `redirect`, covering the free read only surface of api.chargealong.io.
+- Every row that carries a `path` has a `url` for its page on chargealong.io.
+- `NotFound` for an id that never existed; a retired charger answers with
+  `status` of `"removed"`. `NoRoute` tells a trip with no road from a parameter to fix.
+- Every parameter is checked against the service's own bounds before a
+  request is spent on it.
+- No dependencies.

chargealong-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChargeAlong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chargealong-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: chargealong
+Version: 0.1.0
+Summary: Find EV chargers near a point, plan a road trip through charging stops, and look up electric car charging speeds. Free and keyless.
+Project-URL: Homepage, https://chargealong.io
+Project-URL: Documentation, https://chargealong.io/docs/
+Project-URL: Source, https://github.com/chargealong/chargealong-python
+Project-URL: Changelog, https://github.com/chargealong/chargealong-python/blob/main/CHANGELOG.md
+Author: ChargeAlong
+License: MIT License
+        
+        Copyright (c) 2026 ChargeAlong
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: australia,charging network,charging station locator,electric car charging,electric vehicle,ev charger api,ev charging stations,ev trip planner,new zealand,open charge map
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# chargealong
+
+**Public EV chargers, road trips through charging stops, and how fast electric
+cars charge, as an API.** Find the chargers nearest a point, plan Melbourne to
+Sydney with the stops and the minutes at each, or look up a car's charging
+curve.
+
+- Free and keyless. No account, nothing to configure
+- No dependencies: the standard library only
+- Typed dataclasses with the field names the API sends, so the docs and your
+  editor agree
+- Every parameter checked against the service's own limits before a request is
+  spent on it
+
+```sh
+pip install chargealong
+```
+
+## Quick start
+
+```python
+from chargealong import ChargeAlong
+
+ca = ChargeAlong()
+
+near = ca.nearby(-37.7404, 144.9633, min_kw=50, limit=5)
+for site in near.sites:
+    print(site.name, site.network_name, site.max_kw, "kW", site.distance_m, "m")
+    print(site.url)
+```
+
+Nearest first, within 50 km unless you pass `radius_km` (up to 150), at most
+30 sites unless you pass `limit` (up to 50). `near.near` is the closest named
+place, for a heading.
+
+Only `status == "active"` sites are worth sending a driver to.
+
+### Filters
+
+```python
+ca.nearby(lat, lng,
+          min_kw=100,                     # a stop, not a top up
+          connector=["ccs2", "chademo"],  # any of these
+          network="evie-networks")
+```
+
+`CONNECTORS` lists the standards: `ccs2`, `chademo`, `type-2`, `nacs`,
+`ccs1`, `type-1`, `gbt`.
+
+## Plan a trip
+
+```python
+plan = ca.plan_trip((-37.8136, 144.9631), (-33.8688, 151.2093), range_km=400)
+
+print(plan.route.distance_km, "km,", plan.total_min, "minutes in all")
+for stop in plan.stops:
+    print(f"{stop.site.name}: arrive {stop.arrive_pct}%, "
+          f"charge {stop.charge_min} min to {stop.depart_pct}%")
+```
+
+`range_km` is how far the car really goes on a full battery. The rest is
+optional: `reserve` (never arrive below, default 20%), `start` (default 100%),
+`charge_to` (default 80%), `battery_kwh`, `max_dc_kw`, `max_ac_kw`, `min_kw`
+(ignore slower chargers, default 50) and `connectors` (default `ccs2` and
+`type-2`).
+
+`plan.feasible` false is an answer, not an error: the car cannot make it
+without dropping below the reserve, and `plan.gap` says where, in km from the
+start. No road between the points raises `NoRoute`: Sydney to Auckland, say.
+Trips are planned in Australia and New Zealand.
+
+`plan.route.line` is the road as `(longitude, latitude)` pairs, ready for a
+GeoJSON LineString.
+
+## Electric cars
+
+```python
+for car in ca.vehicles("model 3", limit=5):
+    print(car.brand, car.model, car.range_km, "km", car.dc_kw, "kW DC")
+
+car = ca.vehicle("tesla-model-3")
+for t in car.charging:
+    print(f"10 to 80% on {t.charger_kw} kW: {t.minutes_10_80} min")
+```
+
+## One charging site
+
+```python
+detail = ca.site("hwqb4abf")
+
+print(detail.site.name, detail.site.cost.text)
+for c in detail.connectors:
+    print(c.label, c.power_kw, "kW x", c.quantity)
+print(detail.reviews.summary.count, "reviews, last worked", detail.reviews.summary.last_worked_at)
+```
+
+The public id is permanent: store it rather than a name or a path. A site
+removed from its source still answers, with `site.status` of `"removed"`, and an
+id that never existed raises `NotFound`, so code holding stored ids can tell a
+retired charger from a typo.
+
+## Search
+
+```python
+found = ca.search("coburg", prefer="AU")
+found.localities   # suburbs and towns, exact matches first
+found.postcodes    # a postcode's centre, for nearby()
+found.sites        # sites by name
+```
+
+`prefer` is a two letter country code whose places rank first. A term with
+fewer than three letters or digits answers empty without a request.
+
+## Browsing
+
+`countries()`, `overview()`, `country("australia")`,
+`region("australia", "victoria")`, `networks("australia")`,
+`network("australia", "chargefox")` and
+`locality("australia", "victoria", "coburg")` read the directory the way the
+site's pages do. Rows that carry a `path` have a `url` for that page on
+chargealong.io.
+
+`redirect("/en/...")` says where a moved page went, or `None` if it did not
+move.
+
+## Errors
+
+```python
+from chargealong import BadRequest, NoRoute, NotFound, RateLimited
+
+try:
+    ca.plan_trip(a, b, range_km=400)
+except NoRoute:
+    ...  # no road between them
+except BadRequest as e:
+    print(e.detail)  # "range_km: must be between 50 and 1500"
+```
+
+Every error is a `ChargeAlongError` carrying the service's own `title` and
+`detail`, which say what to do. `RateLimited` carries `retry_after` in seconds
+when the service said.
+
+## Being a good citizen
+
+The API is free and cached at the edge. Keep answers rather than fetching them
+again, debounce anything a person types, and make one client and share it.
+
+## Attribution
+
+Charging site data is from [Open Charge Map](https://openchargemap.org/)
+contributors, Transport for NSW and the Queensland Government, and places from
+[GeoNames](https://www.geonames.org/), all under
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Car data is from
+Open EV Data. Publishing what you get back means carrying those credits: see
+[where the data comes from](https://chargealong.io/en/guides/where-the-data-comes-from/)
+and the [terms](https://chargealong.io/en/terms/).
+
+## Also available
+
+| Language | Package |
+|---|---|
+| JavaScript and TypeScript | [`@chargealong/client`](https://www.npmjs.com/package/@chargealong/client) ([source](https://github.com/chargealong/chargealong-js)) |
+
+API reference: [chargealong.io/docs](https://chargealong.io/docs/).
+
+## Licence
+
+MIT for this library. The data carries its own licences, above.

chargealong-0.1.0/README.md

@@ -0,0 +1,168 @@
+# chargealong
+
+**Public EV chargers, road trips through charging stops, and how fast electric
+cars charge, as an API.** Find the chargers nearest a point, plan Melbourne to
+Sydney with the stops and the minutes at each, or look up a car's charging
+curve.
+
+- Free and keyless. No account, nothing to configure
+- No dependencies: the standard library only
+- Typed dataclasses with the field names the API sends, so the docs and your
+  editor agree
+- Every parameter checked against the service's own limits before a request is
+  spent on it
+
+```sh
+pip install chargealong
+```
+
+## Quick start
+
+```python
+from chargealong import ChargeAlong
+
+ca = ChargeAlong()
+
+near = ca.nearby(-37.7404, 144.9633, min_kw=50, limit=5)
+for site in near.sites:
+    print(site.name, site.network_name, site.max_kw, "kW", site.distance_m, "m")
+    print(site.url)
+```
+
+Nearest first, within 50 km unless you pass `radius_km` (up to 150), at most
+30 sites unless you pass `limit` (up to 50). `near.near` is the closest named
+place, for a heading.
+
+Only `status == "active"` sites are worth sending a driver to.
+
+### Filters
+
+```python
+ca.nearby(lat, lng,
+          min_kw=100,                     # a stop, not a top up
+          connector=["ccs2", "chademo"],  # any of these
+          network="evie-networks")
+```
+
+`CONNECTORS` lists the standards: `ccs2`, `chademo`, `type-2`, `nacs`,
+`ccs1`, `type-1`, `gbt`.
+
+## Plan a trip
+
+```python
+plan = ca.plan_trip((-37.8136, 144.9631), (-33.8688, 151.2093), range_km=400)
+
+print(plan.route.distance_km, "km,", plan.total_min, "minutes in all")
+for stop in plan.stops:
+    print(f"{stop.site.name}: arrive {stop.arrive_pct}%, "
+          f"charge {stop.charge_min} min to {stop.depart_pct}%")
+```
+
+`range_km` is how far the car really goes on a full battery. The rest is
+optional: `reserve` (never arrive below, default 20%), `start` (default 100%),
+`charge_to` (default 80%), `battery_kwh`, `max_dc_kw`, `max_ac_kw`, `min_kw`
+(ignore slower chargers, default 50) and `connectors` (default `ccs2` and
+`type-2`).
+
+`plan.feasible` false is an answer, not an error: the car cannot make it
+without dropping below the reserve, and `plan.gap` says where, in km from the
+start. No road between the points raises `NoRoute`: Sydney to Auckland, say.
+Trips are planned in Australia and New Zealand.
+
+`plan.route.line` is the road as `(longitude, latitude)` pairs, ready for a
+GeoJSON LineString.
+
+## Electric cars
+
+```python
+for car in ca.vehicles("model 3", limit=5):
+    print(car.brand, car.model, car.range_km, "km", car.dc_kw, "kW DC")
+
+car = ca.vehicle("tesla-model-3")
+for t in car.charging:
+    print(f"10 to 80% on {t.charger_kw} kW: {t.minutes_10_80} min")
+```
+
+## One charging site
+
+```python
+detail = ca.site("hwqb4abf")
+
+print(detail.site.name, detail.site.cost.text)
+for c in detail.connectors:
+    print(c.label, c.power_kw, "kW x", c.quantity)
+print(detail.reviews.summary.count, "reviews, last worked", detail.reviews.summary.last_worked_at)
+```
+
+The public id is permanent: store it rather than a name or a path. A site
+removed from its source still answers, with `site.status` of `"removed"`, and an
+id that never existed raises `NotFound`, so code holding stored ids can tell a
+retired charger from a typo.
+
+## Search
+
+```python
+found = ca.search("coburg", prefer="AU")
+found.localities   # suburbs and towns, exact matches first
+found.postcodes    # a postcode's centre, for nearby()
+found.sites        # sites by name
+```
+
+`prefer` is a two letter country code whose places rank first. A term with
+fewer than three letters or digits answers empty without a request.
+
+## Browsing
+
+`countries()`, `overview()`, `country("australia")`,
+`region("australia", "victoria")`, `networks("australia")`,
+`network("australia", "chargefox")` and
+`locality("australia", "victoria", "coburg")` read the directory the way the
+site's pages do. Rows that carry a `path` have a `url` for that page on
+chargealong.io.
+
+`redirect("/en/...")` says where a moved page went, or `None` if it did not
+move.
+
+## Errors
+
+```python
+from chargealong import BadRequest, NoRoute, NotFound, RateLimited
+
+try:
+    ca.plan_trip(a, b, range_km=400)
+except NoRoute:
+    ...  # no road between them
+except BadRequest as e:
+    print(e.detail)  # "range_km: must be between 50 and 1500"
+```
+
+Every error is a `ChargeAlongError` carrying the service's own `title` and
+`detail`, which say what to do. `RateLimited` carries `retry_after` in seconds
+when the service said.
+
+## Being a good citizen
+
+The API is free and cached at the edge. Keep answers rather than fetching them
+again, debounce anything a person types, and make one client and share it.
+
+## Attribution
+
+Charging site data is from [Open Charge Map](https://openchargemap.org/)
+contributors, Transport for NSW and the Queensland Government, and places from
+[GeoNames](https://www.geonames.org/), all under
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Car data is from
+Open EV Data. Publishing what you get back means carrying those credits: see
+[where the data comes from](https://chargealong.io/en/guides/where-the-data-comes-from/)
+and the [terms](https://chargealong.io/en/terms/).
+
+## Also available
+
+| Language | Package |
+|---|---|
+| JavaScript and TypeScript | [`@chargealong/client`](https://www.npmjs.com/package/@chargealong/client) ([source](https://github.com/chargealong/chargealong-js)) |
+
+API reference: [chargealong.io/docs](https://chargealong.io/docs/).
+
+## Licence
+
+MIT for this library. The data carries its own licences, above.

chargealong-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chargealong"
+version = "0.1.0"
+description = "Find EV chargers near a point, plan a road trip through charging stops, and look up electric car charging speeds. Free and keyless."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "ChargeAlong" }]
+keywords = [
+  "ev charger api",
+  "ev charging stations",
+  "charging station locator",
+  "ev trip planner",
+  "electric vehicle",
+  "electric car charging",
+  "charging network",
+  "open charge map",
+  "australia",
+  "new zealand",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Scientific/Engineering :: GIS",
+  "Typing :: Typed",
+]
+# No dependencies, on purpose. The whole client is one urllib call and a set of
+# dataclasses; asking for requests would make this the heaviest thing in
+# somebody's lambda for no gain.
+dependencies = []
+
+[project.urls]
+Homepage = "https://chargealong.io"
+Documentation = "https://chargealong.io/docs/"
+Source = "https://github.com/chargealong/chargealong-python"
+Changelog = "https://github.com/chargealong/chargealong-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chargealong"]

chargealong-0.1.0/src/chargealong/__init__.py

@@ -0,0 +1,66 @@
+"""ChargeAlong: public EV charging sites, trip planning and electric cars, as an API.
+
+Free, keyless and cached at the edge. The directory behind chargealong.io.
+
+    >>> from chargealong import ChargeAlong
+    >>> ca = ChargeAlong()
+    >>> near = ca.nearby(-37.7404, 144.9633, min_kw=50)
+    >>> near.sites[0].name, near.sites[0].max_kw
+    ('Coburg Civic Centre / Moreland City', 50)
+
+Charging site data from Open Charge Map contributors, Transport for NSW and the
+Queensland Government, places from GeoNames, all CC BY 4.0. Publishing what you
+get back means carrying those credits:
+chargealong.io/en/guides/where-the-data-comes-from/.
+"""
+
+from ._client import DEFAULT_BASE_URL, ChargeAlong, Transport, __version__
+from ._errors import BadRequest, ChargeAlongError, NoRoute, NotFound, RateLimited
+from ._models import (
+    CONNECTORS,
+    SITE,
+    ChargeTime,
+    Connector,
+    Cost,
+    Country,
+    CountryDetail,
+    CountryOverview,
+    CurvePoint,
+    Facet,
+    Gap,
+    Locality,
+    LocalityDetail,
+    NearPlace,
+    Nearby,
+    Network,
+    NetworkDetail,
+    NetworkList,
+    Overview,
+    Photo,
+    PlaceMatch,
+    PostcodeMatch,
+    Redirect,
+    Region,
+    RegionDetail,
+    Review,
+    Reviews,
+    ReviewSummary,
+    Route,
+    SearchResult,
+    Site,
+    SiteDetail,
+    Source,
+    TripPlan,
+    TripStop,
+    Vehicle,
+)
+
+__all__ = [
+    "BadRequest", "CONNECTORS", "ChargeAlong", "ChargeAlongError", "ChargeTime", "Connector", "Cost",
+    "Country", "CountryDetail", "CountryOverview", "CurvePoint", "DEFAULT_BASE_URL", "Facet", "Gap",
+    "Locality", "LocalityDetail", "NearPlace", "Nearby", "Network", "NetworkDetail",
+    "NetworkList", "NoRoute", "NotFound", "Overview", "Photo", "PlaceMatch", "PostcodeMatch",
+    "RateLimited", "Redirect", "Region", "RegionDetail", "Review", "ReviewSummary", "Reviews",
+    "Route", "SITE", "SearchResult", "Site", "SiteDetail", "Source", "Transport", "TripPlan",
+    "TripStop", "Vehicle", "__version__",
+]