Hydro-Quebec-API-Wrapper 4.2.6__py3-none-any.whl → 4.3.0__py3-none-any.whl

{hydro_quebec_api_wrapper-4.2.6.dist-info → hydro_quebec_api_wrapper-4.3.0.dist-info}/METADATA

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: Hydro-Quebec-API-Wrapper
-Version: 4.2.6
+Version: 4.3.0
 Summary: A wrapper library to access hydro quebec API and more
 Home-page: https://hydroqc.ca
 Author-email: Hydroqc Team <info@hydroqc.ca>
 License: LGPL-3.0-or-later
-Project-URL: Source Code, https://gitlab.com/hydroqc/hydroqc
-Project-URL: Bug Reports, https://gitlab.com/hydroqc/hydroqc/-/issues
+Project-URL: Source Code, https://github.com/hydroqc/hydroqc
+Project-URL: Bug Reports, https://github.com/hydroqc/hydroqc/issues
 Project-URL: Home-page, https://hydroqc.ca
 Keywords: hydroquebec,lib
 Platform: any
@@ -25,8 +25,8 @@ Dynamic: license-file
 # HydroQC - Hydro Quebec API wrapper
 
 
-[![coverage report](https://gitlab.com/hydroqc/hydroqc/badges/main/coverage.svg)](https://gitlab.com/hydroqc/hydroqc/-/commits/main)
-[![pipeline status](https://gitlab.com/hydroqc/hydroqc/badges/main/pipeline.svg)](https://gitlab.com/hydroqc/hydroqc/-/commits/main)
+[![CI](https://github.com/hydroqc/hydroqc/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/hydroqc/hydroqc/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/Hydro-Quebec-API-Wrapper.svg)](https://pypi.org/project/Hydro-Quebec-API-Wrapper/)
 
 
 
@@ -89,6 +89,58 @@ We don't have anyone to test with. Please reach out to us if you have this plan
 
 If you need more information about the usage and current integrations of the library please see our website [https://hydroqc.ca](https://hydroqc.ca)
 
+## E-mail verification (MFA)
+
+Hydro-Québec can ask for a one-time code sent by e-mail after the password round
+trip. `login()` returns a `LoginStatus` instead of a plain boolean:
+
+```python
+from hydroqc.consts import LoginStatus
+from hydroqc.error import HydroQcMFAInvalidCodeError
+
+status = await webuser.login()
+while status is LoginStatus.MFA_REQUIRED:
+    code = input("Verification code (empty = send a new one): ")
+    if not code.strip():
+        await webuser.request_mfa_code()
+        continue
+    try:
+        status = await webuser.submit_mfa_code(code)
+    except HydroQcMFAInvalidCodeError:
+        print("Code refused, try again.")
+
+if status is not LoginStatus.SUCCESS:
+    raise RuntimeError("Login failed")
+```
+
+`bool(status)` is only true for `LoginStatus.SUCCESS`, so existing code using
+`if await webuser.login():` keeps working. The code is requested automatically
+when the step is detected; `request_mfa_code()` sends a new one. The
+verification step expires after a few minutes (3 minutes on the current
+portal): `HydroQcMFAExpiredError` means the login has to be restarted.
+
+A silent background login cannot ask for a code and raises
+`HydroQcMFARequiredError` instead of failing quietly.
+
+### Reusing a session
+
+`export_session_state()` returns the OAuth tokens plus the Azure AD B2C cookies;
+`import_session_state()` restores them. Persisting that state lets a later run
+skip the password (and a new verification code) while the refresh token or the
+single sign-on cookie is still valid. The current portal issues 15-minute access
+tokens and a 24-hour refresh token, so the stored session is normally reusable
+for about a day; once the refresh token and the single sign-on cookie are both
+refused, a new interactive login (and a new code) is required:
+
+```python
+state = webuser.export_session_state()   # store it somewhere safe
+# ... next run ...
+webuser = WebUser(username, password, verify_ssl=True)
+webuser.import_session_state(state)
+if await webuser.try_silent_login() is not LoginStatus.SUCCESS:
+    await webuser.login()
+```
+
 ## Goal
 
 Make it easy to fetch and manipulate data from Hydro-Quebec, especially the winter credit periods
@@ -104,7 +156,7 @@ This uses python 3.10
 1. Clone the repo
 
    ```bash
-   git clone https://gitlab.com/hydroqc/hydroqc.git
+   git clone https://github.com/hydroqc/hydroqc.git
    ```
 
 2. Create a virtual-env

{hydro_quebec_api_wrapper-4.2.6.dist-info → hydro_quebec_api_wrapper-4.3.0.dist-info}/RECORD

@@ -1,16 +1,16 @@
-hydro_quebec_api_wrapper-4.2.6.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
+hydro_quebec_api_wrapper-4.3.0.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
 hydroqc/__init__.py,sha256=sFhCh7-LWoISCQuAtdrLQOmj2x5wjHBGbAAPg4SN6Pc,40
 hydroqc/account.py,sha256=84PO2npB_VG8cEzGIbmXj9sD1whG8qynkiGd-yEYddM,3375
-hydroqc/consts.py,sha256=a9dWq5i6t5VedYosUbP8zIuG2q5TPw4ruT0jOaC8Yo8,209
+hydroqc/consts.py,sha256=CcqeInTfcpBe-u1-KGHUHd2SVv6Hq_27I8vLW5W53oM,768
 hydroqc/customer.py,sha256=Z3zq1p6ZwCXsxMnE8R6RmrGOCTxUFualMuu9MPRwQLI,6267
 hydroqc/diagnostic.py,sha256=eVY3HfMcLCjTbKWo9xdaw14ygju4qUIKy9pxcQstoRc,17322
-hydroqc/error.py,sha256=2HzWBak_RpuhfIrLhnfgNuY3FhUwwNyo1BLUDH6U0CI,598
+hydroqc/error.py,sha256=rrtPTcG_99DLqubrux2gG50FX9f3hSnWpNWja6j9iio,1312
 hydroqc/logger.py,sha256=Fez6CqjBBxd841U3avtnrT3E43Vyy-v1e7hqwUmf9bg,1256
 hydroqc/public_client.py,sha256=pUXA9rkgA8b4wIA3EMsd8FAC-swp-IRa4S-VK0v60SQ,3065
 hydroqc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 hydroqc/timerange.py,sha256=MXR9yau72m4UZBSmN1qB0jMs0x4_jEZYnwtaUnGq-MQ,1137
 hydroqc/utils.py,sha256=sxA5qkOA-Ui5jgEYItFQIeQdBsS_5z8J3xn8YxKZMow,232
-hydroqc/webuser.py,sha256=MqlZNLLpuLGxHfRKyyVj-2SbDeWq7ERFZAnvvvzqVbo,4578
+hydroqc/webuser.py,sha256=2NiRoGB9yA5xvmHbNQV2DOhtn7o5ueG4cSjQv13ccKU,7206
 hydroqc/contract/__init__.py,sha256=uqxjOgyhpKFd-n_umxdaW5FB_DkJJaettWnEFC0nRYc,548
 hydroqc/contract/common.py,sha256=xVw9z_Yjqp95SGCPNAfJVABvgp_C-KM51VTBEU9wjeM,15705
 hydroqc/contract/contract_d.py,sha256=6jPYTCjFq8zonfbXPrEujDVz58n5RUEuq54VCGqph6o,856
@@ -23,8 +23,9 @@ hydroqc/contract/contract_residential.py,sha256=v88mWvJsJP7FsY5cHmr0ZYYT_S-6xtSk
 hydroqc/contract/outage.py,sha256=K5XX0enSKMVpL-JCkWsykuKUw-5_GcSJLzcSR1SqQDk,3979
 hydroqc/hydro_api/__init__.py,sha256=bIIjTkhQcXG7kn4cQr_Q6tFSKGjAx-AXLjMMlRCjclY,32
 hydroqc/hydro_api/cache.py,sha256=14nLVxV8Q2d9qnEi2iKK9exkhe5WCFueGu9uX5y_tyU,1716
-hydroqc/hydro_api/client.py,sha256=yTNBoVriSTjQsdF1b4rPjtN2NlOBnl7i8BRiTKqRv-I,38874
+hydroqc/hydro_api/client.py,sha256=YUQOnMJ3OTRG-j52aT93pkYI9UuWAETrQPaRMQ-DbWs,58946
 hydroqc/hydro_api/consts.py,sha256=XDNOjZVpC-Z7rsOL4GDgfexb7m8zc7HiafiKGiFvoUI,4607
+hydroqc/hydro_api/mfa.py,sha256=UDfmXHjb4l5ggM1K9noAUQy2kO_yLZBHB-fqnUwtSx0,27825
 hydroqc/peak/__init__.py,sha256=ye2KbWXhJEHZnBDaFylWioy3W-mzJw_lDplsJNAapNs,19
 hydroqc/peak/basepeak.py,sha256=DMXjZXyNRHWnuhB0Vp3ZINGhNQngG7AU15cDLajmC7M,1954
 hydroqc/peak/basepeakhandler.py,sha256=XVemlzDd2IeriDdvunvTxV7qwH1qEJcc0zm5-C716Ts,9184
@@ -46,8 +47,8 @@ hydroqc/types/cpc.py,sha256=ghmtBTT1FKuqVodJJ0kCtUbYNTLCOrngxgcrzjJYvok,2116
 hydroqc/types/dpc.py,sha256=mwA5T9fGcNTA-kb_f25wq2ALJCwa5lKABOS73L6znY0,1981
 hydroqc/types/dt.py,sha256=rEXDgNewhlOsRbso0Shlq69TvJFoT56EGYOAjTFZU80,693
 hydroqc/types/outage.py,sha256=XTsNyu8mmxUx44XWvOOUHKSoijp-lgbXwQroiqm9S0o,3932
-hydro_quebec_api_wrapper-4.2.6.dist-info/METADATA,sha256=2oqKBuMOjWQ_GdQlfpZXqvaDRyYPVIEViT6fD-2MAlk,7949
-hydro_quebec_api_wrapper-4.2.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-hydro_quebec_api_wrapper-4.2.6.dist-info/entry_points.txt,sha256=G2YKkCH9rFt2dXbFyHINBp4bmqY2HTEIaf7F1CwbC_k,57
-hydro_quebec_api_wrapper-4.2.6.dist-info/top_level.txt,sha256=YAcYLnu5YYkbxt1psUoBfo_opl-lAZKq0A7B3IN_P6M,8
-hydro_quebec_api_wrapper-4.2.6.dist-info/RECORD,,
+hydro_quebec_api_wrapper-4.3.0.dist-info/METADATA,sha256=-rhBBK2NsxhFiVvO1Ak-bqRaA79rT_cQcHz_jnHdJsI,10017
+hydro_quebec_api_wrapper-4.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hydro_quebec_api_wrapper-4.3.0.dist-info/entry_points.txt,sha256=G2YKkCH9rFt2dXbFyHINBp4bmqY2HTEIaf7F1CwbC_k,57
+hydro_quebec_api_wrapper-4.3.0.dist-info/top_level.txt,sha256=YAcYLnu5YYkbxt1psUoBfo_opl-lAZKq0A7B3IN_P6M,8
+hydro_quebec_api_wrapper-4.3.0.dist-info/RECORD,,

hydroqc/consts.py

@@ -1,8 +1,28 @@
 """Hydroqc Consts."""
 
+from enum import StrEnum
+
 from dateutil import tz
 
 # Always get the time using HydroQuebec Local Time
 HQ_TIMEZONE = tz.gettz("America/Toronto")
 
 LOGGING_LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
+
+
+class LoginStatus(StrEnum):
+    """Outcome of a login attempt.
+
+    ``bool(status)`` is only true for :attr:`SUCCESS`, so the historic
+    ``if await webuser.login():`` idiom keeps behaving as before while callers
+    that need to react to the new e-mail verification step can inspect the
+    value.
+    """
+
+    SUCCESS = "success"
+    MFA_REQUIRED = "mfa_required"
+    FAILED = "failed"
+
+    def __bool__(self) -> bool:
+        """Return True only when the login actually succeeded."""
+        return self is LoginStatus.SUCCESS

hydroqc/error.py

@@ -15,6 +15,27 @@ class HydroQcHTTPError(HydroQcError):
         super().__init__(message)
 
 
+class HydroQcMFARequiredError(HydroQcError):
+    """The login needs a one-time code that cannot be requested here.
+
+    Raised when a silent re-login (session expired in the background) lands on
+    the e-mail verification step: there is nobody to ask for the code at that
+    point, the caller has to start an interactive login again.
+    """
+
+
+class HydroQcMFAInvalidCodeError(HydroQcMFARequiredError):
+    """The one-time code was refused by Hydro-Québec.
+
+    The verification step is still valid, the caller can ask the user for
+    another code and try again.
+    """
+
+
+class HydroQcMFAExpiredError(HydroQcMFARequiredError):
+    """The verification step expired and the login flow has to be restarted."""
+
+
 class HydroQcAnnualError(HydroQcError):
     """Annual HydroQc Error."""