opower 0.0.1__tar.gz

opower-0.0.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

opower-0.0.1/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.1
+Name: opower
+Version: 0.0.1
+Summary: A Python library for getting historical and forecasted usage/cost from utilities that use opower.com such as PG&E
+Author-email: tronikos <tronikos@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/tronikos/opower
+Project-URL: Bug Tracker, https://github.com/tronikos/opower/issues
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# opower
+A Python library for getting historical and forecasted usage/cost from utilities that use opower.com such as PG&amp;E.
+
+To add support for a new utility that uses opower JSON API (you can tell if the energy dashboard of your utility is hosted on opower.com, e.g. pge.opower.com) add a file similar to [pge.py](https://github.com/tronikos/opower/blob/main/src/opower/utilities/pge.py).
+
+## Example
+
+See [demo.py](https://github.com/tronikos/opower/blob/main/src/demo.py)
+
+## Development environment
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+# for Windows CMD:
+# .venv\Scripts\activate.bat
+# for Windows PowerShell:
+# .venv\Scripts\Activate.ps1
+
+# Install dependencies
+python -m pip install --upgrade pip
+python -m pip install .
+
+# Run formatter
+python -m pip install isort black
+isort .
+black .
+
+# Run lint
+python -m pip install flake8 ruff
+flake8 .
+ruff .
+
+# Run tests
+python -m pip install pytest
+pytest
+
+# Run demo
+python src/demo.py --help
+# To output debug logs to a file:
+python src/demo.py --verbose 2> out.txt
+
+# Build package
+python -m pip install build
+python -m build
+```

opower-0.0.1/README.md

@@ -0,0 +1,46 @@
+# opower
+A Python library for getting historical and forecasted usage/cost from utilities that use opower.com such as PG&E.
+
+To add support for a new utility that uses opower JSON API (you can tell if the energy dashboard of your utility is hosted on opower.com, e.g. pge.opower.com) add a file similar to [pge.py](https://github.com/tronikos/opower/blob/main/src/opower/utilities/pge.py).
+
+## Example
+
+See [demo.py](https://github.com/tronikos/opower/blob/main/src/demo.py)
+
+## Development environment
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+# for Windows CMD:
+# .venv\Scripts\activate.bat
+# for Windows PowerShell:
+# .venv\Scripts\Activate.ps1
+
+# Install dependencies
+python -m pip install --upgrade pip
+python -m pip install .
+
+# Run formatter
+python -m pip install isort black
+isort .
+black .
+
+# Run lint
+python -m pip install flake8 ruff
+flake8 .
+ruff .
+
+# Run tests
+python -m pip install pytest
+pytest
+
+# Run demo
+python src/demo.py --help
+# To output debug logs to a file:
+python src/demo.py --verbose 2> out.txt
+
+# Build package
+python -m pip install build
+python -m build
+```

opower-0.0.1/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "opower"
+version = "0.0.1"
+license = {text = "Apache-2.0"}
+authors = [
+    { name="tronikos", email="tronikos@gmail.com" },
+]
+description = "A Python library for getting historical and forecasted usage/cost from utilities that use opower.com such as PG&E"
+readme = "README.md"
+requires-python = ">=3.7"
+dependencies = [
+    "aiohttp>=3.8",
+    "asyncio>=3.4.3",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/tronikos/opower"
+"Bug Tracker" = "https://github.com/tronikos/opower/issues"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.black]
+extend-exclude = "_pb2.py|_pb2_grpc.py"
+
+[tool.isort]
+profile = "black"
+force_sort_within_sections = true
+combine_as_imports = true
+extend_skip_glob = ["*_pb2.py", "*_pb2_grpc.py"]
+
+[tool.ruff]
+target-version = "py311"
+exclude = ["*_pb2.py", "*_pb2_grpc.py", "*.pyi"]
+line-length = 127
+
+select = [
+    "B007", # Loop control variable {name} not used within loop body
+    "B014", # Exception handler with duplicate exception
+    "C",  # complexity
+    "D",  # docstrings
+    "E",  # pycodestyle
+    "F",  # pyflakes/autoflake
+    "ICN001", # import concentions; {name} should be imported as {asname}
+    "PGH004",  # Use specific rule codes when using noqa
+    "PLC0414", # Useless import alias. Import alias does not rename original package.
+    "SIM105", # Use contextlib.suppress({exception}) instead of try-except-pass
+    "SIM117", # Merge with-statements that use the same scope
+    "SIM118", # Use {key} in {dict} instead of {key} in {dict}.keys()
+    "SIM201", # Use {left} != {right} instead of not {left} == {right}
+    "SIM212", # Use {a} if {a} else {b} instead of {b} if not {a} else {a}
+    "SIM300", # Yoda conditions. Use 'age == 42' instead of '42 == age'.
+    "SIM401", # Use get from dict with default instead of an if block
+    "T20",  # flake8-print
+    "TRY004", # Prefer TypeError exception for invalid type
+    "RUF006", # Store a reference to the return value of asyncio.create_task
+    "UP",  # pyupgrade
+    "W",  # pycodestyle
+]
+
+ignore = [
+    "D203",  # 1 blank line required before class docstring
+    "D213",  # Multi-line docstring summary should start at the second line
+]
+
+[tool.ruff.flake8-pytest-style]
+fixture-parentheses = false
+
+[tool.ruff.pyupgrade]
+keep-runtime-typing = true
+
+[tool.ruff.per-file-ignores]
+# Allow for demo script to write to stdout
+"demo.py" = ["T201"]
+
+[tool.ruff.mccabe]
+max-complexity = 25

opower-0.0.1/setup.cfg

@@ -0,0 +1,16 @@
+[flake8]
+exclude = .venv,.git,docs,venv,bin,lib,deps,build,*_pb2.py,*_pb2_grpc.py
+max-complexity = 25
+doctests = True
+ignore = 
+	E501,
+	W503,
+	E203,
+	D202,
+	W504
+noqa-require-code = True
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

opower-0.0.1/src/demo.py

@@ -0,0 +1,138 @@
+"""Demo usage of Opower library."""
+
+import argparse
+import asyncio
+from datetime import datetime, timedelta
+from getpass import getpass
+import logging
+
+import aiohttp
+
+from opower import AggregateType, Opower, get_supported_utility_subdomains
+
+
+async def _main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--utility",
+        help="Utility (subdomain of opower.com). Defaults to pge",
+        choices=get_supported_utility_subdomains(),
+        default="pge",
+    )
+    parser.add_argument(
+        "--username",
+        help="Username for logging into the utility's website. "
+        "If not provided, you will be asked for it",
+    )
+    parser.add_argument(
+        "--password",
+        help="Password for logging into the utility's website. "
+        "If not provided, you will be asked for it",
+    )
+    parser.add_argument(
+        "--aggregate_type",
+        help="How to aggregate historical data. Defaults to day",
+        choices=list(AggregateType),
+        default=AggregateType.DAY,
+    )
+    parser.add_argument(
+        "--start_date",
+        help="Start datetime for historical data. Defaults to 7 days ago",
+        type=lambda s: datetime.fromisoformat(s),
+        default=datetime.now() - timedelta(days=7),
+    )
+    parser.add_argument(
+        "--end_date",
+        help="end datetime for historical data. Defaults to now",
+        type=lambda s: datetime.fromisoformat(s),
+        default=datetime.now(),
+    )
+    parser.add_argument(
+        "--usage_only",
+        help="If true will output usage only, not cost",
+        action="store_true",
+    )
+    parser.add_argument(
+        "-v", "--verbose", help="enable verbose logging", action="store_true"
+    )
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.INFO)
+
+    username = args.username or input("Username: ")
+    password = args.password or getpass("Password: ")
+
+    async with aiohttp.ClientSession() as session:
+        opower = Opower(session, args.utility, username, password)
+        await opower.async_login()
+        forecasts = await opower.async_get_forecast()
+        for forecast in forecasts:
+            print("\nData for meter:", forecast.account.meter_type)
+            print("\nCurrent bill forecast:", forecast)
+            print(
+                "\nGetting historical data: aggregate_type=",
+                args.aggregate_type,
+                "start_date=",
+                args.start_date,
+                "end_date=",
+                args.end_date,
+            )
+            if args.usage_only:
+                usage_data = await opower.async_get_usage_reads(
+                    forecast.account,
+                    args.aggregate_type,
+                    args.start_date,
+                    args.end_date,
+                )
+                prev_end = None
+                print(
+                    "start_time\tend_time\tconsumption"
+                    "\tstart_minus_prev_end\tend_minus_prev_end"
+                )
+                for usage_read in usage_data:
+                    start_minus_prev_end = (
+                        None if prev_end is None else usage_read.start_time - prev_end
+                    )
+                    end_minus_prev_end = (
+                        None if prev_end is None else usage_read.end_time - prev_end
+                    )
+                    prev_end = usage_read.end_time
+                    print(
+                        f"{usage_read.start_time}"
+                        f"\t{usage_read.end_time}"
+                        f"\t{usage_read.consumption}"
+                        f"\t{start_minus_prev_end}"
+                        f"\t{end_minus_prev_end}"
+                    )
+            else:
+                cost_data = await opower.async_get_cost_reads(
+                    forecast.account,
+                    args.aggregate_type,
+                    args.start_date,
+                    args.end_date,
+                )
+                prev_end = None
+                print(
+                    "start_time\tend_time\tconsumption\tprovided_cost"
+                    "\tstart_minus_prev_end\tend_minus_prev_end"
+                )
+                for cost_read in cost_data:
+                    start_minus_prev_end = (
+                        None if prev_end is None else cost_read.start_time - prev_end
+                    )
+                    end_minus_prev_end = (
+                        None if prev_end is None else cost_read.end_time - prev_end
+                    )
+                    prev_end = cost_read.end_time
+                    print(
+                        f"{cost_read.start_time}"
+                        f"\t{cost_read.end_time}"
+                        f"\t{cost_read.consumption}"
+                        f"\t{cost_read.provided_cost}"
+                        f"\t{start_minus_prev_end}"
+                        f"\t{end_minus_prev_end}"
+                    )
+            print()
+
+
+asyncio.run(_main())

opower-0.0.1/src/opower/__init__.py

@@ -0,0 +1,27 @@
+"""Library for getting historical and forecasted usage/cost from an utility using opower.com JSON API."""
+
+from .opower import (
+    Account,
+    AggregateType,
+    CostRead,
+    Forecast,
+    MeterType,
+    Opower,
+    UnitOfMeasure,
+    UsageRead,
+    get_supported_utility_names,
+    get_supported_utility_subdomains,
+)
+
+__all__ = [
+    "Account",
+    "AggregateType",
+    "CostRead",
+    "Forecast",
+    "MeterType",
+    "Opower",
+    "UnitOfMeasure",
+    "UsageRead",
+    "get_supported_utility_names",
+    "get_supported_utility_subdomains",
+]

opower-0.0.1/src/opower/opower.py

@@ -0,0 +1,395 @@
+"""Implementation of opower.com JSON API."""
+
+import dataclasses
+from datetime import date, datetime, timedelta
+from enum import Enum
+import json
+import logging
+import re
+from typing import Any
+from urllib.parse import urlencode
+
+import aiohttp
+from multidict import CIMultiDict
+
+from .utilities import UtilityBase
+
+_LOGGER = logging.getLogger(__file__)
+
+
+class MeterType(Enum):
+    """Meter type. Electric or gas."""
+
+    ELEC = "ELEC"
+    GAS = "GAS"
+
+    def __str__(self):
+        """Return the value of the enum."""
+        return self.value
+
+
+class UnitOfMeasure(Enum):
+    """Unit of measure for the associated meter type. kWh for electricity or Therm for gas,."""
+
+    KWH = "KWH"
+    THERM = "THERM"
+
+    def __str__(self):
+        """Return the value of the enum."""
+        return self.value
+
+
+class AggregateType(Enum):
+    """How to aggregate historical data."""
+
+    BILL = "bill"
+    DAY = "day"
+    HOUR = "hour"
+
+    def __str__(self):
+        """Return the value of the enum."""
+        return self.value
+
+
+@dataclasses.dataclass
+class Account:
+    """Data about an account."""
+
+    uuid: str
+    utility_account_id: str
+    meter_type: MeterType
+
+
+@dataclasses.dataclass
+class Forecast:
+    """Forecast data for an account."""
+
+    account: Account
+    start_date: date
+    end_date: date
+    current_date: date
+    unit_of_measure: UnitOfMeasure
+    usage_to_date: float
+    cost_to_date: float
+    forecasted_usage: float
+    forecasted_cost: float
+    typical_usage: float
+    typical_cost: float
+
+
+@dataclasses.dataclass
+class CostRead:
+    """A read from the meter that has both consumption and cost data."""
+
+    start_time: datetime
+    end_time: datetime
+    consumption: float  # taken from value field, in KWH or THERM
+    provided_cost: float  # in $
+
+
+@dataclasses.dataclass
+class UsageRead:
+    """A read from the meter that has consumption data."""
+
+    start_time: datetime
+    end_time: datetime
+    consumption: float  # taken from consumption.value field, in KWH or THERM
+
+
+def get_supported_utility_names() -> list[str]:
+    """Return a list of names of all supported utilities."""
+    return [utility.name() for utility in UtilityBase.subclasses]
+
+
+def get_supported_utility_subdomains() -> list[str]:
+    """Return a list of subdomains of all supported utilities."""
+    return [utility.subdomain() for utility in UtilityBase.subclasses]
+
+
+def _select_utility(name_or_subdomain: str) -> type[UtilityBase]:
+    """Return the utility with the given name or subdomain."""
+    for utility in UtilityBase.subclasses:
+        if name_or_subdomain in [utility.name(), utility.subdomain()]:
+            return utility
+    raise ValueError(f"Utility {name_or_subdomain} not found")
+
+
+def _get_form_action_url_and_hidden_inputs(html: str):
+    """Return the URL and hidden inputs from the single form in a page."""
+    match = re.search(r'action="([^"]*)"', html)
+    if not match:
+        return None, None
+    action_url = match.group(1)
+    inputs = {}
+    for match in re.finditer(
+        r'input\s*type="hidden"\s*name="([^"]*)"\s*value="([^"]*)"', html
+    ):
+        inputs[match.group(1)] = match.group(2)
+    return action_url, inputs
+
+
+def _strip_time(date_time: datetime):
+    return date_time.astimezone().replace(hour=0, minute=0, second=0, microsecond=0)
+
+
+class Opower:
+    """Class that can get historical and forecasted usage/cost from an utility."""
+
+    def __init__(
+        self, session: aiohttp.ClientSession, utility: str, username: str, password: str
+    ) -> None:
+        """Initialize."""
+        self.session = session
+        self.session._default_headers = CIMultiDict({"User-Agent": "Mozilla/5.0"})
+        self.session._raise_for_status = True
+        self.utility: type[UtilityBase] = _select_utility(utility)
+        self.username = username
+        self.password = password
+        self.customer = None
+
+    async def async_login(self) -> None:
+        """Login to the utility website and authorize opower.com for access."""
+        url = await self.utility.login(self.session, self.username, self.password)
+        await self._async_authorize(url)
+
+    async def _async_authorize(self, url: str) -> None:
+        # Fetch the URL on the utility website to get RelayState and SAMLResponse.
+        async with self.session.get(url) as resp:
+            result = await resp.text()
+        action_url, hidden_inputs = _get_form_action_url_and_hidden_inputs(result)
+        assert action_url == "https://sso2.opower.com/sp/ACS.saml2"
+        assert set(hidden_inputs.keys()) == {"RelayState", "SAMLResponse"}
+
+        # Pass them to https://sso2.opower.com/sp/ACS.saml2 to get opentoken.
+        async with self.session.post(action_url, data=hidden_inputs) as resp:
+            result = await resp.text()
+        action_url, hidden_inputs = _get_form_action_url_and_hidden_inputs(result)
+        assert set(hidden_inputs.keys()) == {"opentoken"}
+
+        # Pass it back to the utility website.
+        async with self.session.post(action_url, data=hidden_inputs) as resp:
+            pass
+
+    async def async_get_accounts(self) -> list[Account]:
+        """Get a list of accounts for the signed in user.
+
+        Typically one account for electricity and one for gas.
+        """
+        customer = await self._async_get_customer()
+        accounts = []
+        for account in customer["utilityAccounts"]:
+            accounts.append(
+                Account(
+                    uuid=account["uuid"],
+                    utility_account_id=account["preferredUtilityAccountId"],
+                    meter_type=MeterType(account["meterType"]),
+                )
+            )
+        return accounts
+
+    async def async_get_forecast(self) -> list[Forecast]:
+        """Get current and forecasted usage and cost for the current monthly bill.
+
+        One forecast for each account, typically one for electricity, one for gas.
+        """
+        customer = await self._async_get_customer()
+        customer_uuid = customer["uuid"]
+        url = (
+            "https://"
+            f"{self.utility.subdomain()}"
+            ".opower.com/ei/edge/apis/bill-forecast-cws-v1/cws/"
+            f"{self.utility.subdomain()}"
+            "/customers/"
+            f"{customer_uuid}"
+            "/combined-forecast"
+        )
+        _LOGGER.debug("Fetching: %s", url)
+        async with self.session.get(url) as resp:
+            result = await resp.json()
+            _LOGGER.debug("Fetched: %s", json.dumps(result, indent=2))
+        forecasts = []
+        for forecast in result["accountForecasts"]:
+            forecasts.append(
+                Forecast(
+                    account=Account(
+                        uuid=forecast["accountUuids"][0],
+                        utility_account_id=str(forecast["preferredUtilityAccountId"]),
+                        meter_type=MeterType(forecast["meterType"]),
+                    ),
+                    start_date=date.fromisoformat(forecast["startDate"]),
+                    end_date=date.fromisoformat(forecast["endDate"]),
+                    current_date=date.fromisoformat(forecast["currentDate"]),
+                    unit_of_measure=UnitOfMeasure(forecast["unitOfMeasure"]),
+                    usage_to_date=float(forecast["usageToDate"]),
+                    cost_to_date=float(forecast["costToDate"]),
+                    forecasted_usage=float(forecast["forecastedUsage"]),
+                    forecasted_cost=float(forecast["forecastedCost"]),
+                    typical_usage=float(forecast["typicalUsage"]),
+                    typical_cost=float(forecast["typicalCost"]),
+                )
+            )
+        return forecasts
+
+    async def _async_get_customer(self):
+        """Get information about the current customer."""
+        # Cache the customer data
+        if not self.customer:
+            async with self.session.get(
+                "https://"
+                f"{self.utility.subdomain()}"
+                ".opower.com/ei/edge/apis/multi-account-v1/cws/"
+                f"{self.utility.subdomain()}"
+                # Alternative to get multiple accounts:
+                # /customers?offset=0&batchSize=100&addressFilter=
+                "/customers/current"
+            ) as resp:
+                self.customer = await resp.json()
+                _LOGGER.debug("Fetched: %s", json.dumps(self.customer, indent=2))
+        assert self.customer
+        return self.customer
+
+    async def async_get_cost_reads(
+        self,
+        account: Account,
+        aggregate_type: AggregateType,
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+    ) -> list[CostRead]:
+        """Get cost data for the selected account in the given date range aggregated by bill/day/hour.
+
+        The resolution for gas is typically 'day' while for electricity it's hour or quarter hour.
+        Opower typically keeps historical cost data for 3 years.
+        """
+        url = (
+            "https://"
+            f"{self.utility.subdomain()}"
+            ".opower.com/ei/edge/apis/DataBrowser-v1/cws/cost/utilityAccount/"
+            f"{account.uuid}"
+        )
+        reads = await self._async_get_dated_data(
+            url, aggregate_type, start_date, end_date
+        )
+        result = []
+        for read in reads:
+            result.append(
+                CostRead(
+                    start_time=datetime.fromisoformat(read["startTime"]),
+                    end_time=datetime.fromisoformat(read["endTime"]),
+                    consumption=read["value"],
+                    provided_cost=read["providedCost"],
+                )
+            )
+        # Remove last entries with 0 values
+        while result:
+            last = result.pop()
+            if last.provided_cost != 0 or last.consumption != 0:
+                result.append(last)
+                break
+        return result
+
+    async def async_get_usage_reads(
+        self,
+        account: Account,
+        aggregate_type: AggregateType,
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+    ) -> list[UsageRead]:
+        """Get usage data for the selected account in the given date range aggregated by bill/day/hour.
+
+        The resolution for gas is typically 'day' while for electricity it's hour or quarter hour.
+        Opower typically keeps historical usage data for a bit over 3 years.
+        """
+        url = (
+            "https://"
+            f"{self.utility.subdomain()}"
+            ".opower.com/ei/edge/apis/DataBrowser-v1/cws/utilities/"
+            f"{self.utility.subdomain()}"
+            "/utilityAccounts/"
+            f"{account.uuid}"
+            "/reads"
+        )
+        reads = await self._async_get_dated_data(
+            url, aggregate_type, start_date, end_date
+        )
+        result = []
+        for read in reads:
+            result.append(
+                UsageRead(
+                    start_time=datetime.fromisoformat(read["startTime"]),
+                    end_time=datetime.fromisoformat(read["endTime"]),
+                    consumption=read["consumption"]["value"],
+                )
+            )
+        return result
+
+    async def _async_get_dated_data(
+        self,
+        url: str,
+        aggregate_type: AggregateType,
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+    ) -> list[Any]:
+        """Wrap _async_fetch by breaking requests for big date ranges to smaller ones to satisfy opower imposed limits."""
+        if start_date is None:
+            if aggregate_type == AggregateType.BILL:
+                return await self._async_fetch(
+                    url, aggregate_type, start_date, end_date
+                )
+            raise ValueError("Missing start_date")
+
+        if end_date is None:
+            end_date = datetime.max
+        end_date = min(datetime.now(), end_date)
+
+        start_date = _strip_time(start_date)
+        end_date = _strip_time(end_date) + timedelta(days=1)
+        assert start_date
+        assert end_date
+
+        max_request_days = None
+        if aggregate_type == AggregateType.DAY:
+            max_request_days = 363
+        elif aggregate_type == AggregateType.HOUR:
+            max_request_days = 26
+
+        # Fetch data in batches in reverse chronological order
+        # until we reach start_date or there is no fetched data
+        # (non bill data are available up to 3 years ago).
+        result: list[Any] = []
+        req_end = end_date
+        while True:
+            req_start = start_date
+            if max_request_days:
+                req_start = max(start_date, req_end - timedelta(days=max_request_days))
+            if req_start >= req_end:
+                return result
+            reads = await self._async_fetch(url, aggregate_type, req_start, req_end)
+            if not reads:
+                return result
+            result = reads + result
+            req_end = req_start - timedelta(days=1)
+
+    async def _async_fetch(
+        self,
+        url: str,
+        aggregate_type: AggregateType,
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+    ) -> list[Any]:
+        convert_to_date = not (
+            aggregate_type == AggregateType.DAY and "/cws/cost/" in url
+        )
+        params = {"aggregateType": aggregate_type.value}
+        if start_date:
+            params["startDate"] = (
+                start_date.date() if convert_to_date else start_date
+            ).isoformat()
+        if end_date:
+            params["endDate"] = (
+                end_date.date() if convert_to_date else end_date
+            ).isoformat()
+        _LOGGER.debug("Fetching: %s?%s", url, urlencode(params))
+        async with self.session.get(url, params=params) as resp:
+            result = await resp.json()
+            _LOGGER.debug("Fetched: %s", json.dumps(result, indent=2))
+            return result["reads"]

opower-0.0.1/src/opower/utilities/__init__.py

@@ -0,0 +1,16 @@
+"""Directory of all supported utility websites that use opower.com API."""
+
+from .base import UtilityBase
+
+__all__ = ["UtilityBase"]
+
+# Import all modules in the current directory.
+from importlib import import_module
+from pathlib import Path
+
+for f in Path(__file__).parent.glob("*.py"):
+    module_name = f.stem
+    if (not module_name.startswith("_")) and (module_name not in globals()):
+        import_module(f".{module_name}", __package__)
+    del f, module_name
+del import_module, Path

opower-0.0.1/src/opower/utilities/base.py

@@ -0,0 +1,35 @@
+"""Base class that each utility needs to extend."""
+
+
+import aiohttp
+
+
+class UtilityBase:
+    """Base class that each utility needs to extend."""
+
+    subclasses: list[type["UtilityBase"]] = []
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        """Keep track of all subclass implementations."""
+        super().__init_subclass__(**kwargs)
+        cls.subclasses.append(cls)
+
+    @staticmethod
+    def name() -> str:
+        """Distinct recognizable name of the utility."""
+        raise NotImplementedError
+
+    @staticmethod
+    def subdomain() -> str:
+        """Return the opower.com subdomain for this utility."""
+        raise NotImplementedError
+
+    @staticmethod
+    async def login(
+        session: aiohttp.ClientSession, username: str, password: str
+    ) -> str:
+        """Login to the utility website and return a URL where we can authorize opower.com.
+
+        Any failure to login should raise ClientResponseError with status 401 or 403.
+        """
+        raise NotImplementedError

opower-0.0.1/src/opower/utilities/pge.py

@@ -0,0 +1,91 @@
+"""Pacific Gas & Electric (PG&E)."""
+
+import aiohttp
+from aiohttp.client_exceptions import ClientResponseError
+
+from .base import UtilityBase
+
+
+class PGE(UtilityBase):
+    """Pacific Gas & Electric (PG&E)."""
+
+    @staticmethod
+    def name() -> str:
+        """Distinct recognizable name of the utility."""
+        return "Pacific Gas & Electric"
+
+    @staticmethod
+    def subdomain() -> str:
+        """Return the opower.com subdomain for this utility."""
+        return "pge"
+
+    @staticmethod
+    async def login(
+        session: aiohttp.ClientSession, username: str, password: str
+    ) -> str:
+        """Login to the utility website and return a URL where we can authorize opower.com."""
+        # 1st way of login
+        async with session.post(
+            "https://www.pge.com/eimpapi/auth/login",
+            json={
+                "username": username,
+                "password": password,
+                "appName": "CustomerSSO",
+            },
+        ) as resp:
+            result = await resp.json()
+            if "errorMsg" in result:
+                raise ClientResponseError(
+                    resp.request_info,
+                    resp.history,
+                    status=403,
+                    message=result["errorMsg"],
+                )
+
+        # 2nd way of login
+        # async with session.get(
+        #     "https://apigprd.cloud.pge.com/myaccount/v1/login",
+        #     headers={
+        #         "Authorization": "Basic "
+        #         + base64.b64encode(f"{username}:{password}".encode()).decode(),
+        #     },
+        # ) as resp:
+        #     await resp.json()
+
+        # Skip the following 2 requests since emToolUrl is constant.
+        # If it ever changes consider uncommenting.
+        # These only work with the 2nd way of login.
+
+        # async with session.get(
+        #     "https://apigprd.cloud.pge.com/myaccount/v1/cocaccount/secure/account/retrieveMyEnergyAccounts",
+        #     params=(("userId", username),),
+        # ) as resp:
+        #     energy_accounts = await resp.json()
+
+        # for energy_account in energy_accounts["accounts"]:
+        #     accountNumber = energy_account["accountNumber"]
+        #     addressAsString = energy_account["accountAddress"]["addressAsString"]
+        #     print(accountNumber)
+        #     print(addressAsString)
+        #     break
+
+        # async with session.get(
+        #     f"https://apigprd.cloud.pge.com/myaccount/v1/cocaccount/secure/retrieveEnergyManagementInfo/{accountNumber}/myusage"
+        # ) as resp:
+        #     result = await resp.json()
+
+        # for energyManagementInfo in result["energyManagementInfoList"]:
+        #     if energyManagementInfo["vendorType"] == "OPOWER":
+        #         emToolUrl = energyManagementInfo["emToolUrl"]
+        #         break
+        # assert emToolUrl == (
+        #     "https://itiamping.cloud.pge.com/idp/startSSO.ping?"
+        #     "PartnerSpId=sso.opower.com&TargetResource="
+        #     "https%3A%2F%2Fpge.opower.com%2Fei%2Fapp%2Fr%2Fenergy-usage-details"
+        # )
+
+        return (
+            "https://itiamping.cloud.pge.com/idp/startSSO.ping?"
+            "PartnerSpId=sso.opower.com&TargetResource="
+            "https%3A%2F%2Fpge.opower.com%2Fei%2Fapp%2Fr%2Fenergy-usage-details"
+        )

opower-0.0.1/src/opower.egg-info/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.1
+Name: opower
+Version: 0.0.1
+Summary: A Python library for getting historical and forecasted usage/cost from utilities that use opower.com such as PG&E
+Author-email: tronikos <tronikos@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/tronikos/opower
+Project-URL: Bug Tracker, https://github.com/tronikos/opower/issues
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# opower
+A Python library for getting historical and forecasted usage/cost from utilities that use opower.com such as PG&amp;E.
+
+To add support for a new utility that uses opower JSON API (you can tell if the energy dashboard of your utility is hosted on opower.com, e.g. pge.opower.com) add a file similar to [pge.py](https://github.com/tronikos/opower/blob/main/src/opower/utilities/pge.py).
+
+## Example
+
+See [demo.py](https://github.com/tronikos/opower/blob/main/src/demo.py)
+
+## Development environment
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+# for Windows CMD:
+# .venv\Scripts\activate.bat
+# for Windows PowerShell:
+# .venv\Scripts\Activate.ps1
+
+# Install dependencies
+python -m pip install --upgrade pip
+python -m pip install .
+
+# Run formatter
+python -m pip install isort black
+isort .
+black .
+
+# Run lint
+python -m pip install flake8 ruff
+flake8 .
+ruff .
+
+# Run tests
+python -m pip install pytest
+pytest
+
+# Run demo
+python src/demo.py --help
+# To output debug logs to a file:
+python src/demo.py --verbose 2> out.txt
+
+# Build package
+python -m pip install build
+python -m build
+```

opower-0.0.1/src/opower.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+setup.cfg
+src/demo.py
+src/opower/__init__.py
+src/opower/opower.py
+src/opower.egg-info/PKG-INFO
+src/opower.egg-info/SOURCES.txt
+src/opower.egg-info/dependency_links.txt
+src/opower.egg-info/requires.txt
+src/opower.egg-info/top_level.txt
+src/opower/utilities/__init__.py
+src/opower/utilities/base.py
+src/opower/utilities/pge.py
+tests/test_opower.py

opower-0.0.1/src/opower.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opower-0.0.1/src/opower.egg-info/requires.txt

@@ -0,0 +1,2 @@
+aiohttp>=3.8
+asyncio>=3.4.3

opower-0.0.1/src/opower.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+demo
+opower

opower-0.0.1/tests/test_opower.py

@@ -0,0 +1,6 @@
+"""Tests for Opower."""
+
+
+def test_dummy():
+    """Test dummy."""
+    assert True