pybluecurrent 0.0.1__tar.gz → 0.0.2__tar.gz

{pybluecurrent-0.0.1 → pybluecurrent-0.0.2}/.github/workflows/publish.yaml

@@ -16,7 +16,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: "3.x"
 

{pybluecurrent-0.0.1 → pybluecurrent-0.0.2}/.github/workflows/test.yaml

@@ -16,7 +16,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: "3.x"
 

{pybluecurrent-0.0.1 → pybluecurrent-0.0.2}/.gitignore

@@ -128,5 +128,8 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
+# Ruff
+.ruff_cache
+
 # Setuptools SCM version
 _version.py

pybluecurrent-0.0.2/PKG-INFO

@@ -0,0 +1,395 @@
+Metadata-Version: 2.1
+Name: pybluecurrent
+Version: 0.0.2
+Summary: Python client for BlueCurrent charge points.
+Author-email: Rogier van der Geer <rogier@vander-geer.nl>
+License: MIT
+Project-URL: Repository, https://github.com/rogiervandergeer/pybluecurrent
+Keywords: api,blue current,electric vehicle,ev
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncio-multisubscriber-queue>=0.4.1
+Requires-Dist: requests>=2.31.0
+Requires-Dist: sjcl>=0.2.1
+Requires-Dist: websockets>=11.0.3
+Provides-Extra: dev
+Requires-Dist: black==23.3.0; extra == "dev"
+Requires-Dist: pre-commit>=3.3.3; extra == "dev"
+Requires-Dist: pytest>=7.3.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.1; extra == "dev"
+
+# pybluecurrent
+
+Python client for [BlueCurrent](https://www.bluecurrent.nl) charge points.
+
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/rogiervandergeer/pybluecurrent/test.yaml) 
+![PyPI](https://img.shields.io/pypi/v/pybluecurrent)
+![PyPI - License](https://img.shields.io/pypi/l/pybluecurrent)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/pybluecurrent) 
+
+## Usage
+
+Using the client is as simple as:
+```python
+from pybluecurrent import BlueCurrentClient
+
+client = BlueCurrentClient("your_username", "your_secret_password")
+
+async with client:
+   charge_points = await client.get_charge_points()
+
+transactions = client.get_transactions(charge_points[0]["evse_id"])
+```
+
+## Methods
+
+BlueCurrent exposes two APIs, a synchronous REST API as well as an asynchronous Websocket API. 
+As a result, the `BlueCurrentClient` also exposes synchronous as well as asynchronous methods:
+  
+ - [Asynchronous](#asynchronous)
+   - [`get_account`](#getaccount---get-your-account-information)
+   - [`get_charge_cards`](#getchargecards---get-your-charge-cards)
+   - [`get_charge_points`](#getchargepoints---get-your-charge-points)
+   - [`get_charge_point_settings`](#getchargepointsettings---get-the-settings-of-a-charge-point)
+   - [`get_grid_status`](#getgridstatus---get-the-grid-status-associated-to-a-charge-point)
+   - [`get_sustainability_status`](#getsustainabilitystatus---get-statistics-on-the-sustainability-of-all-your-charge-points)
+   - [`set_status`](#setstatus---enable-or-disable-a-charge-point)
+ - [Synchronous](#synchronous)
+   - [`login`](#login---log-in)
+   - [`get_charge_point_status`](#getchargepointstatus---get-the-status-of-a-charge-point)
+   - [`get_contracts`](#getcontracts---get-your-contracts)
+   - [`get_grids`](#getgrids---get-your-grid-connections)
+   - [`get_transactions`](#gettransactions---get-a-list-of-transactions)
+   - [`iterate_transactions`](#iteratetransactions---iterate-through-your-transactions)
+
+### Asynchronous
+
+The async methods can only be used when the websocket client is connected. For example:
+```python
+client = BlueCurrentClient("your_username", "your_secret_password")
+async with client:
+    result = await client.get_account()
+```
+Entering the async context will automatically login.
+
+#### `get_account` - Get your account information.
+
+```python
+async def get_account(self) -> dict[str, bool | str]
+```
+
+##### Returns
+A dictionary describing your account:
+
+```python
+{
+    "full_name": "Your Full Name",
+    "email": "your@email.address",
+    "login": "your@email.address",
+    "should_reset_password": False,
+    "developer_mode_enabled": False,
+    "tel": "",
+    "marketing_target": "bluecurrent",
+    "first_login_app": date(2020, 1, 1),
+    "hubspot_user_identity": "a_very_long_string"
+}
+```
+
+#### `get_charge_cards` - Get your charge cards.
+
+```python
+async def get_charge_cards(self) -> list[dict[str, date | int | str | None]]
+```
+
+##### Returns
+
+A list of dictionaries, each representing a charge card:
+```python
+{
+    "uid": "A1B2C3D4E5F6",
+    "id": "NL-ABC-123456-0",
+    "name": "My Charge Cards",
+    "customer_name": "Your Name",
+    "valid": 1,
+    "date_created": date(2023, 6, 27),
+    "date_modified": date(2023, 7, 11),
+    "date_became_invalid": None
+}
+```
+
+#### `get_charge_points` - Get your charge points.
+
+```python
+async def get_charge_points(self) -> list[dict[str, bool | dict | str]]
+```
+
+##### Returns
+
+A list of dictionaries, each representing a charge card:
+```python
+{
+    "evse_id": "BCU123456",
+    "name": "",
+    "model_type": "H:MOVE-C32T2",
+    "chargepoint_type": "HIDDEN",
+    "is_cable": True,
+    "public_charging": {"value": False, "permission": "write"},
+                    "default_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
+                     "customer_name": "Your Name", "valid": 1},
+    "preferred_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
+                       "customer_name": "Your Name", "valid": 1},
+    "plug_and_charge_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
+                             "customer_name": "Your Name", "valid": 1},
+    "tariff":  {"tariff_id","NLBCUT58", "price_ex_vat": 0.2, "start_price_ex_vat": 0, "price_in_vat": 0.242,
+                "start_price_in_vat": 0, "currency": "EUR", "vat_percentage": 21},
+    "plug_and_charge_notification": False,
+    "plug_and_charge": {"value": True, "permission": "write"},
+    "led_interaction": {"value": False, "permission": "read"},
+    "publish_location": {"value": False, "permission": "write"},
+    "smart_charging": True,
+    "smart_charging_dynamic": True,
+    "activity": "available",
+    "location": {"x_coord": 50.1234, "y_coord": 5.01234, "street": "Europalaan", "housenumber": "100",
+                 "zipcode": "3526KS", "city": "Utrecht", "country": "NL"},
+    "delayed_charging": {"value": False, "permission": "none"}
+}
+```
+
+#### `get_charge_point_settings` - Get the settings of a charge point.
+
+All the information returned by this endpoint is already included 
+in the response of [`get_charge_points`](#getchargepoints---get-your-charge-points).
+
+```python
+async def get_charge_point_settings(self, evse_id: str) -> dict[str, bool | dict | str]
+```
+
+##### Arguments
+- `evse_id`: The ID of the charge point.
+
+##### Returns
+A dictionary describing the settings:
+```python
+{
+    "evse_id": "BCU123456",
+    "plug_and_charge": {"value": True, "permission": "write"},
+    "public_charging": {"value": False, "permission": "write"},
+    "default_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
+                     "customer_name": "Your Name", "valid": 1},
+    "preferred_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
+                       "customer_name": "Your Name", "valid": 1},
+    "plug_and_charge_card": {"uid": "A1B2C3D4E5F6", "id": "NL-ABC-123456-0", "name": "Your Card",
+                             "customer_name": "Your Name", "valid": 1},
+    "smart_charging": True,
+    "smart_charging_dynamic": True,
+    "model_type": "H:MOVE-C32T2",
+    "is_cable": True,
+    "chargepoint_type": "HIDDEN",
+    "plug_and_charge_notification": False,
+    "led_intensity": {"value": 0, "permission": "none"},
+    "led_interaction": {"value": False, "permission": "none"}
+}
+```
+
+#### `get_grid_status` - Get the grid status associated to a charge point.
+
+```python
+async def get_grid_status(self, evse_id: str) -> dict[str, int | str]
+```
+
+##### Arguments
+- `evse_id`: The ID of the charge point.
+
+##### Returns
+A dictionary describing the actual grid current and maximum current in amps:
+```python
+{
+    "id": "GRID-BCU123456",
+    "grid_actual_p1": 1,
+    "grid_actual_p2": 2,
+    "grid_actual_p3": 3,
+    "grid_max_install": 25,
+    "grid_max_reserved": 25
+}
+```
+
+#### `get_sustainability_status` - Get statistics on the sustainability of all your charge points.
+
+```python
+async def get_sustainability_status(self) -> dict[str, float | int]
+```
+
+##### Returns
+A dictionary with two keys: `{"trees": 1, "co2": 12.345}`
+
+#### `set_status` - Enable or disable a charge point.
+
+```python
+async def set_status(self, evse_id: str, enabled: bool) -> None
+```
+
+##### Arguments
+- `evse_id`: The ID of the charge point.
+- `enabled`: Boolean that indicates the desired status.
+
+### Synchronous
+
+#### `login` - Log in
+```python
+def login(self) -> None
+```
+
+This method does not do anything if the client is already logged in. 
+Connection to the websocket api (async with client) automatically logs in the client,
+so this endpoint is not needed when using the async API.
+
+
+#### `get_charge_point_status` - Get the status of a charge point.
+
+```python
+def get_charge_point_status(self, evse_id: str) -> dict[str, datetime | float | int | str | None]
+```
+
+##### Arguments
+- `evse_id`: The ID of the charge point.
+
+##### Returns
+A dictionary with the chargepoint status:
+```python
+{
+    "actual_p1": 0,
+    "actual_p2": 0,
+    "actual_p3": 0,
+    "activity": "available",
+    "actual_v1": 0,
+    "actual_v2": 0,
+    "actual_v3": 0,
+    "actual_kwh": 0,
+    "max_usage": 20,
+    "smartcharging_max_usage": 6,
+    "max_offline": 10,
+    "offline_since": "",
+    "start_datetime": datetime(2023, 7, 24, 15, 25, 33),
+    "stop_datetime": datetime(2023, 7, 26, 7, 48, 40),
+    "total_cost": 9.93,
+    "vehicle_status": "A",
+    "evse_id": "BCU123456",
+}
+```
+
+#### `get_contracts` - Get your contracts.
+
+```python
+def get_contracts(self) -> list[dict[str, str]]
+```
+
+##### Returns
+A list of dictionaries, each representing a contract:
+```python
+[
+    {
+        "contract_id": "BCU12345678",
+        "contact_email": "your@email.address",
+        "subscription_type": "BASIS",
+        "beneficiary_name": "Your Name",
+        "iban_beneficiary": "NL00ABCD0123456789"
+    }
+]
+```
+
+#### `get_grids` - Get your grid connections.
+
+```python
+def get_grids(self) -> list[dict[str, bool | dict[str, str] | str]]
+```
+
+##### Returns
+A list of dictionaries, each representing a grid:
+```python
+[
+    {
+        "address": {"street": "Street Name", "housenumber": "1", "postal_code": "1234AB",
+                    "city": "Amsterdam", "country": "NL", "region": ""},
+        "smart_charging": True,
+        "id": "GRID-BCU123456"
+    }
+]
+```
+
+#### `get_transactions` - Get a list of transactions.
+
+```python
+def get_transactions(
+        self, evse_id: str, newest_first: bool = True, page: int = 1
+    ) -> dict[str, int | list[dict[str, Any]]]
+```
+
+##### Arguments
+- `evse_id`: The ID of the charge point.
+- `newest_first`: If `True`, start with the most recent transaction. Defaults to `True`.
+- `page`: Page number to get. Defaults to `1`.
+
+##### Returns
+A dictionary like this:
+```python
+{
+    "current_page": 1,
+    "next_page": 2,  # This is None when there is no next page.
+    "max_per_page": 25,
+    "total_pages": 8,
+    "transactions: [
+        {
+            "transaction_id": 12345678,
+            "chargepoint_id": "BCU123456",
+            "chargepoint_type": "HIDDEN",
+            "evse_name": "Charge Point Name",
+            "started_at": datetime(2023, 7, 1, 12, 34, 56),
+            "end_time": datetime(2023, 7, 1, 14, 0, 0),
+            "kwh": 12.34,
+            "card_id": "NL-ABC-123456-0",
+            "card_name": "Card Name",
+            "total_costs": 5.97,
+            "total_costs_ex_vat": 4.93,
+            "vat": 21,
+            "currency": "EUR"
+        },
+        ...
+    ]
+}
+```
+
+#### `iterate_transactions` - Iterate through your transactions
+
+```python
+def iterate_transactions(self, evse_id: str, newest_first: bool = True) -> Iterable[dict[str, Any]]
+```
+
+##### Arguments
+- `evse_id`: The ID of the charge point.
+- `newest_first`: If `True`, start with the most recent transaction. Defaults to `True`.
+
+##### Returns
+An iterable of dictionaries describing the transactions. Each dictionary looks like this:
+```python
+{
+    "transaction_id": 12345678,
+    "chargepoint_id": "BCU123456",
+    "chargepoint_type": "HIDDEN",
+    "evse_name": "Charge Point Name",
+    "started_at": datetime(2023, 7, 1, 12, 34, 56),
+    "end_time": datetime(2023, 7, 1, 14, 0, 0),
+    "kwh": 12.34,
+    "card_id": "NL-ABC-123456-0",
+    "card_name": "Card Name",
+    "total_costs": 5.97,
+    "total_costs_ex_vat": 4.93,
+    "vat": 21,
+    "currency": "EUR"
+}
+```