Hydro-Quebec-API-Wrapper 4.2.6__tar.gz → 4.3.0__tar.gz

hydro_quebec_api_wrapper-4.3.0/.github/scripts/home_assistant_versions.py

@@ -0,0 +1,49 @@
+"""Select the latest Home Assistant release and a compatible runner Python."""
+
+import json
+import os
+from urllib.request import urlopen
+
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
+
+
+def load_json(url):
+    """Fetch JSON metadata from a public endpoint."""
+    with urlopen(url, timeout=30) as response:
+        return json.load(response)
+
+
+home_assistant = load_json("https://pypi.org/pypi/homeassistant/json")["info"]
+home_assistant_version = home_assistant["version"]
+if Version(home_assistant_version).is_prerelease:
+    raise SystemExit("The latest Home Assistant release is not stable")
+
+requires_python = SpecifierSet(home_assistant["requires_python"])
+manifest = load_json(
+    "https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json"
+)
+available = [
+    Version(entry["version"])
+    for entry in manifest
+    if entry["stable"]
+    and Version(entry["version"]) in requires_python
+    and any(
+        file["platform"] == "linux"
+        and file["arch"] == "x64"
+        and file.get("platform_version") == "24.04"
+        for file in entry["files"]
+    )
+]
+if not available:
+    raise SystemExit(f"No runner Python version satisfies {requires_python}")
+
+oldest_minor = min((version.major, version.minor) for version in available)
+python_version = str(
+    max(version for version in available if version.release[:2] == oldest_minor)
+)
+print(f"Home Assistant {home_assistant_version} requires Python {requires_python}")
+print(f"Selected Python {python_version}")
+with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output:
+    print(f"home_assistant={home_assistant_version}", file=output)
+    print(f"python={python_version}", file=output)

hydro_quebec_api_wrapper-4.3.0/.github/workflows/ci.yml

@@ -0,0 +1,121 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Quality
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+          cache: pip
+          cache-dependency-path: test_requirements.txt
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y build-essential graphviz
+      - name: Install tox
+        run: python -m pip install tox
+      - name: Run quality checks
+        run: tox -e pylint,flake8,pydocstyle,typing,black --parallel auto
+      - name: Upload quality reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: quality-reports
+          if-no-files-found: ignore
+          path: |
+            mypy-junit.xml
+            mypy-txt-report/
+            mypy-html-report/
+            classes.png
+            classes.mmd
+            classes.html
+            packages.png
+            packages.mmd
+            packages.html
+
+  home-assistant:
+    name: Home Assistant compatibility
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install version parser
+        run: python -m pip install packaging
+      - name: Select Home Assistant and Python versions
+        id: versions
+        run: python .github/scripts/home_assistant_versions.py
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ steps.versions.outputs.python }}
+      - name: Check dependency compatibility
+        env:
+          HOME_ASSISTANT_VERSION: ${{ steps.versions.outputs.home_assistant }}
+        run: |
+          python -m pip install "homeassistant==${HOME_ASSISTANT_VERSION}" .
+          python -m pip check
+
+  package:
+    name: Build package
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install build tools
+        run: python -m pip install build twine
+      - name: Build and verify distributions
+        run: |
+          python -m build
+          python -m twine check --strict dist/*
+      - name: Upload distributions
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          if-no-files-found: ignore
+          path: dist/
+
+  renovate:
+    name: Validate Renovate configuration
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Check for configuration changes
+        id: changes
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- renovate.json5 | grep -q .; then
+            echo 'changed=true' >> "$GITHUB_OUTPUT"
+          fi
+      - uses: actions/setup-node@v4
+        if: steps.changes.outputs.changed == 'true'
+        with:
+          node-version: '24'
+      - name: Validate Renovate configuration
+        if: steps.changes.outputs.changed == 'true'
+        run: npx --yes --package renovate -- renovate-config-validator --strict renovate.json5

hydro_quebec_api_wrapper-4.3.0/.github/workflows/release.yml

@@ -0,0 +1,179 @@
+name: Create Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Release version (for example, 1.2.3)
+        required: true
+        type: string
+      commit_sha:
+        description: Commit SHA on main (defaults to the latest commit or the existing tag)
+        required: false
+        type: string
+      publish_to_pypi:
+        description: Publish to PyPI
+        required: true
+        default: false
+        type: boolean
+
+permissions: {}
+
+concurrency:
+  group: release-${{ inputs.version }}
+  cancel-in-progress: false
+
+jobs:
+  tag:
+    name: Create or verify tag
+    runs-on: ubuntu-24.04
+    permissions:
+      actions: read
+      contents: write
+    outputs:
+      tag: ${{ steps.release.outputs.tag }}
+      sha: ${{ steps.release.outputs.sha }}
+    steps:
+      - name: Require the main workflow ref
+        env:
+          WORKFLOW_REF: ${{ github.ref }}
+        run: |
+          if [[ "$WORKFLOW_REF" != refs/heads/main ]]; then
+            echo 'Run this workflow from main.' >&2
+            exit 1
+          fi
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+      - name: Verify the release and create the tag
+        id: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_VERSION: ${{ inputs.version }}
+          COMMIT_SHA: ${{ inputs.commit_sha }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$RELEASE_VERSION" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
+            echo 'Version must use the format 1.2.3.' >&2
+            exit 1
+          fi
+          if [[ -n "$COMMIT_SHA" && ! "$COMMIT_SHA" =~ ^[0-9a-fA-F]{7,40}$ ]]; then
+            echo 'Commit SHA must contain 7 to 40 hexadecimal characters.' >&2
+            exit 1
+          fi
+
+          tag="v${RELEASE_VERSION}"
+          if git show-ref --verify --quiet "refs/tags/$tag"; then
+            tag_sha=$(git rev-parse "refs/tags/$tag^{commit}")
+            target_sha=$tag_sha
+            if [[ -n "$COMMIT_SHA" ]]; then
+              target_sha=$(git rev-parse --verify "${COMMIT_SHA}^{commit}")
+              if [[ "$target_sha" != "$tag_sha" ]]; then
+                echo 'The existing tag points to a different commit.' >&2
+                exit 1
+              fi
+            fi
+            echo "Using existing tag $tag at $target_sha."
+          else
+            target_sha=$(git rev-parse --verify "${COMMIT_SHA:-refs/remotes/origin/main}^{commit}")
+          fi
+
+          if ! git merge-base --is-ancestor "$target_sha" refs/remotes/origin/main; then
+            echo 'The release commit must be in the history of main.' >&2
+            exit 1
+          fi
+
+          conclusion=$(gh api "repos/${GITHUB_REPOSITORY}/actions/workflows/ci.yml/runs?branch=main&event=push&head_sha=${target_sha}&per_page=100" \
+            --jq '.workflow_runs[0].conclusion // "missing"')
+          if [[ "$conclusion" != success ]]; then
+            echo "The latest CI run for $target_sha on main must succeed (status: $conclusion)." >&2
+            exit 1
+          fi
+
+          if ! git show-ref --verify --quiet "refs/tags/$tag"; then
+            git tag "$tag" "$target_sha"
+            git push origin "refs/tags/$tag"
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "sha=$target_sha" >> "$GITHUB_OUTPUT"
+
+  publish:
+    name: Publish to PyPI
+    if: inputs.publish_to_pypi
+    needs: tag
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.tag.outputs.sha }}
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Verify tag and PyPI version
+        env:
+          RELEASE_TAG: ${{ needs.tag.outputs.tag }}
+          RELEASE_SHA: ${{ needs.tag.outputs.sha }}
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+          if [[ "$(git rev-parse "refs/tags/${RELEASE_TAG}^{commit}")" != "$RELEASE_SHA" ]]; then
+            echo 'The release tag no longer points to the selected commit.' >&2
+            exit 1
+          fi
+          python - <<'PY'
+          import os
+          from urllib.error import HTTPError
+          from urllib.request import urlopen
+
+          version = os.environ["RELEASE_VERSION"]
+          url = f"https://pypi.org/pypi/Hydro-Quebec-API-Wrapper/{version}/json"
+          try:
+              with urlopen(url, timeout=30):
+                  raise SystemExit(f"Version {version} already exists on PyPI")
+          except HTTPError as error:
+              if error.code != 404:
+                  raise
+          PY
+      - name: Install build tools
+        run: python -m pip install build twine packaging
+      - name: Build and verify distributions
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          python -m build
+          python -m twine check --strict dist/*
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          from packaging.utils import parse_sdist_filename, parse_wheel_filename
+          from packaging.version import Version
+
+          expected = Version(os.environ["RELEASE_VERSION"])
+          distributions = list(Path("dist").iterdir())
+          if len(distributions) != 2:
+              raise SystemExit("Expected one wheel and one source distribution")
+          versions = []
+          formats = set()
+          for path in distributions:
+              if path.name.endswith(".whl"):
+                  formats.add("wheel")
+                  versions.append(parse_wheel_filename(path.name)[1])
+              elif path.name.endswith(".tar.gz"):
+                  formats.add("sdist")
+                  versions.append(parse_sdist_filename(path.name)[1])
+              else:
+                  raise SystemExit(f"Unexpected distribution: {path.name}")
+          if formats != {"wheel", "sdist"}:
+              raise SystemExit("Expected one wheel and one source distribution")
+          if any(version != expected for version in versions):
+              raise SystemExit(f"Distribution versions {versions} do not match {expected}")
+          PY
+      - name: Publish distributions
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: python -m twine upload --non-interactive dist/*

{hydro_quebec_api_wrapper-4.2.6 → hydro_quebec_api_wrapper-4.3.0}/.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
   - id: check-ast
 
 - repo: https://github.com/psf/black
-  rev: 25.11.0
+  rev: 25.12.0
   hooks:
   - id: black
     language_version: python3
@@ -40,16 +40,16 @@ repos:
   - id: doc8
 
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.19.0
+  rev: v1.20.2
   hooks:
   - id: mypy
     args: [--strict, --pretty, --show-error-codes]
     additional_dependencies:
       - "types-pytz==2025.2.0.20251108"
-      - "types-PyYAML==6.0.12.20250915"
-      - "types-python-dateutil==2.9.0.20251115"
+      - "types-PyYAML==6.0.12.20260724"
+      - "types-python-dateutil==2.9.0.20260807"
       - "pytest-stub==1.1.0"
-      - "aiohttp==3.13.2"
+      - "aiohttp==3.14.3"
       - "aiocache==0.12.3"
       - "pkce==1.0.3"
-      - "pytest-asyncio==1.3.0"
+      - "pytest-asyncio==1.4.0"

{hydro_quebec_api_wrapper-4.2.6 → hydro_quebec_api_wrapper-4.3.0/Hydro_Quebec_API_Wrapper.egg-info}/PKG-INFO

@@ -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 → hydro_quebec_api_wrapper-4.3.0}/Hydro_Quebec_API_Wrapper.egg-info/SOURCES.txt

@@ -16,6 +16,9 @@ test_requirements.txt
 tox.ini
 .devcontainer/Dockerfile
 .devcontainer/devcontainer.json
+.github/scripts/home_assistant_versions.py
+.github/workflows/ci.yml
+.github/workflows/release.yml
 Hydro_Quebec_API_Wrapper.egg-info/PKG-INFO
 Hydro_Quebec_API_Wrapper.egg-info/SOURCES.txt
 Hydro_Quebec_API_Wrapper.egg-info/dependency_links.txt
@@ -66,6 +69,7 @@ hydroqc/hydro_api/__init__.py
 hydroqc/hydro_api/cache.py
 hydroqc/hydro_api/client.py
 hydroqc/hydro_api/consts.py
+hydroqc/hydro_api/mfa.py
 hydroqc/peak/__init__.py
 hydroqc/peak/basepeak.py
 hydroqc/peak/basepeakhandler.py
@@ -100,4 +104,7 @@ tests/subtest_contract_m.py
 tests/subtest_contract_m_gdp.py
 tests/test_basic.py
 tests/test_timerange.py
-tests/tools.py
+tests/tools.py
+tests/unit/__init__.py
+tests/unit/test_login_flow.py
+tests/unit/test_mfa.py

{hydro_quebec_api_wrapper-4.2.6/Hydro_Quebec_API_Wrapper.egg-info → hydro_quebec_api_wrapper-4.3.0}/PKG-INFO

@@ -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 → hydro_quebec_api_wrapper-4.3.0}/README.md

@@ -1,8 +1,8 @@
 # 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/)
 
 
 
@@ -65,6 +65,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
@@ -80,7 +132,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