pygazpar 1.2.7__tar.gz → 1.3.0__tar.gz

{pygazpar-1.2.7 → pygazpar-1.3.0}/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2025-02-15
+
+### Added
+
+[#84](https://github.com/ssenart/PyGazpar/issues/84) : Add a function to retrieve list of PCE ids.
+
+### Changed
+
+[#85](https://github.com/ssenart/PyGazpar/issues/85) : Move to Poetry dependency/package management tool.
+
+## [1.2.8](https://github.com/ssenart/PyGazpar/compare/1.2.8...1.2.7) - 2025-01-11
+
+### Added
+- [#81](https://github.com/ssenart/PyGazpar/issues/81): Add meter/temperature debug log messages to help investigation in case of errors.
+
 ## [1.2.7](https://github.com/ssenart/PyGazpar/compare/1.2.7...1.2.6) - 2025-01-06
 
 ### Fixed

pygazpar-1.2.7/LICENSE.md → pygazpar-1.3.0/LICENSE

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

pygazpar-1.3.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.3
+Name: pygazpar
+Version: 1.3.0
+Summary: Python library to download gas consumption from a GrDF (French Gas Company) account
+License: MIT License
+         
+         Copyright (c) 2025 Stéphane Senart
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Author: Stéphane Senart
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: openpyxl (>=3.1.5,<4.0.0)
+Requires-Dist: pandas (>=2.1.4,<3.0.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Description-Content-Type: text/markdown
+
+# PyGazpar
+
+PyGazpar is a Python library for getting natural gas consumption from GrDF French provider.
+
+Their natural gas meter is called Gazpar. It is wireless and transmit the gas consumption once per day.
+
+All consumption data is available on the client account at GrDF Web Site (https://monespace.grdf.fr).
+
+PyGazpar automatically goes through the Web Site and download the consumption data, and make it available in a Python structure.
+
+## Installation
+
+### Requirements
+PyGazpar does not require Selenium and corresponding geckodriver to work.
+
+With the new GrDF web site, it is possible to load the consumption data far easily than before.
+
+PyGazpar uses [Poetry](https://python-poetry.org/) for dependency and package management.
+
+### Create your virtual environment
+
+```bash
+$ cd /path/to/my_project_folder/
+
+$ poetry install
+```
+
+### PyGazpar installation
+
+Use the package manager [pip](https://pip.pypa.io/en/stable/) to install PyGazpar.
+
+```bash
+pip install pygazpar
+```
+
+You can also download the source code and install it manually.
+```bash
+cd /path/to/pygazpar/
+
+$ poetry install
+```
+
+## Usage
+
+#### Command line:
+
+1. Standard usage (using Json GrDF API).
+
+```bash
+$ pygazpar -u 'your login' -p 'your password' -c 'your PCE identifier' --datasource 'json'
+```
+
+2. Alternate usage (using Excel GrDF document).
+
+```bash
+$ pygazpar -u 'your login' -p 'your password' -c 'your PCE identifier' -t 'temporary directory where to store Excel file (ex: /tmp)' --datasource 'excel'
+```
+
+3. Test usage (using local static data files, do not connect to GrDF site).
+
+```bash
+$ pygazpar -u 'your login' -p 'your password' -c 'your PCE identifier' --datasource 'test'
+```
+
+#### Library:
+
+1. Standard usage (using Json GrDF API).
+
+```python
+import pygazpar
+
+client = pygazpar.Client(pygazpar.JsonWebDataSource(
+    username='your login',
+    password='your password')
+)
+
+# Returns the list of your PCE identifiers attached to your account.
+pce_identifiers = client.get_pce_identifiers()
+
+# Returns the daily and monthly consumptions for the last 60 days on your PCE identifier.
+data = client.load_since(pce_identifier='your PCE identifier',
+                        last_n_days=60,
+                        frequencies=[pygazpar.Frequency.DAILY, pygazpar.Frequency.MONTHLY])
+```
+See [samples/jsonSample.py](samples/jsonSample.py) file for the full example.
+
+2. Alternate usage (using Excel GrDF document).
+
+```python
+import pygazpar
+
+client = pygazpar.Client(pygazpar.ExcelWebDataSource(
+    username='your login',
+    password='your password')
+)
+
+# Returns the list of your PCE identifiers attached to your account.
+pce_identifiers = client.get_pce_identifiers()
+
+# Returns the daily and monthly consumptions for the last 60 days on your PCE identifier.
+data = client.load_since(pce_identifier='your PCE identifier',
+                        last_n_days=60,
+                        frequencies=[pygazpar.Frequency.DAILY, pygazpar.Frequency.MONTHLY])
+```
+See [samples/excelSample.py](samples/jsonSample.py) file for the full example.
+
+3. Test usage (using local static data files, do not connect to GrDF site).
+
+```python
+import pygazpar
+
+client = pygazpar.Client(pygazpar.TestDataSource())
+
+data = client.load_since(pce_identifier='your PCE identifier',
+                        last_n_days=10,
+                        frequencies=[pygazpar.Frequency.DAILY, Frequency.MONTHLY])
+```
+See [samples/testSample.py](samples/jsonSample.py) file for the full example.
+
+#### Output:
+
+```json
+data =>
+{
+  "daily": [
+    {
+      "time_period": "13/10/2022",
+      "start_index_m3": 15724,
+      "end_index_m3": 15725,
+      "volume_m3": 2,
+      "energy_kwh": 17,
+      "converter_factor_kwh/m3": 11.16,
+      "temperature_degC": null,
+      "type": "Mesur\u00e9",
+      "timestamp": "2022-12-13T23:58:35.606763"
+    },
+    ...
+    {
+      "time_period": "11/12/2022",
+      "start_index_m3": 16081,
+      "end_index_m3": 16098,
+      "volume_m3": 18,
+      "energy_kwh": 201,
+      "converter_factor_kwh/m3": 11.27,
+      "temperature_degC": -1.47,
+      "type": "Mesur\u00e9",
+      "timestamp": "2022-12-13T23:58:35.606763"
+    }
+  ],
+  "monthly": [
+    {
+      "time_period": "Novembre 2022",
+      "start_index_m3": 15750,
+      "end_index_m3": 15950,
+      "volume_m3": 204,
+      "energy_kwh": 2227,
+      "timestamp": "2022-12-13T23:58:35.606763"
+    },
+    {
+      "time_period": "D\u00e9cembre 2022",
+      "start_index_m3": 15950,
+      "end_index_m3": 16098,
+      "volume_m3": 148,
+      "energy_kwh": 1664,
+      "timestamp": "2022-12-13T23:58:35.606763"
+    }
+  ]
+}
+```
+
+## Limitation
+PyGazpar relies on how GrDF Web Site is built.
+
+Any change in the Web site may break this library.
+
+We expect in close Future that GrDF makes available an open API from which we can get safely their data.
+
+## Contributing
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+
+## License
+[MIT](https://choosealicense.com/licenses/mit/)
+
+## Project status
+PyGazpar has been initiated for integration with [Home Assistant](https://www.home-assistant.io/).
+
+Corresponding Home Assistant integration custom component is available [here](https://github.com/ssenart/home-assistant-gazpar).

{pygazpar-1.2.7 → pygazpar-1.3.0}/README.md

@@ -1,7 +1,5 @@
 # PyGazpar
 
-## $\text{\color{green}{!!! This library is working again. CAPTCHA has been removed !!!}}$
-
 PyGazpar is a Python library for getting natural gas consumption from GrDF French provider.
 
 Their natural gas meter is called Gazpar. It is wireless and transmit the gas consumption once per day.
@@ -17,20 +15,20 @@ PyGazpar does not require Selenium and corresponding geckodriver to work.
 
 With the new GrDF web site, it is possible to load the consumption data far easily than before.
 
+PyGazpar uses [Poetry](https://python-poetry.org/) for dependency and package management.
+
 ### Create your virtual environment
+
 ```bash
 $ cd /path/to/my_project_folder/
 
-$ python -m venv .venv
+$ poetry install
 ```
 
 ### PyGazpar installation
-Activate your virtual environment.
-```bash
-source .venv/bin/activate
-```
 
 Use the package manager [pip](https://pip.pypa.io/en/stable/) to install PyGazpar.
+
 ```bash
 pip install pygazpar
 ```
@@ -38,7 +36,8 @@ pip install pygazpar
 You can also download the source code and install it manually.
 ```bash
 cd /path/to/pygazpar/
-python setup.py install
+
+$ poetry install
 ```
 
 ## Usage
@@ -75,8 +74,12 @@ client = pygazpar.Client(pygazpar.JsonWebDataSource(
     password='your password')
 )
 
-data = client.loadSince(pceIdentifier='your PCE identifier',
-                        lastNDays=60,
+# Returns the list of your PCE identifiers attached to your account.
+pce_identifiers = client.get_pce_identifiers()
+
+# Returns the daily and monthly consumptions for the last 60 days on your PCE identifier.
+data = client.load_since(pce_identifier='your PCE identifier',
+                        last_n_days=60,
                         frequencies=[pygazpar.Frequency.DAILY, pygazpar.Frequency.MONTHLY])
 ```
 See [samples/jsonSample.py](samples/jsonSample.py) file for the full example.
@@ -91,8 +94,12 @@ client = pygazpar.Client(pygazpar.ExcelWebDataSource(
     password='your password')
 )
 
-data = client.loadSince(pceIdentifier='your PCE identifier',
-                        lastNDays=60,
+# Returns the list of your PCE identifiers attached to your account.
+pce_identifiers = client.get_pce_identifiers()
+
+# Returns the daily and monthly consumptions for the last 60 days on your PCE identifier.
+data = client.load_since(pce_identifier='your PCE identifier',
+                        last_n_days=60,
                         frequencies=[pygazpar.Frequency.DAILY, pygazpar.Frequency.MONTHLY])
 ```
 See [samples/excelSample.py](samples/jsonSample.py) file for the full example.
@@ -104,8 +111,8 @@ import pygazpar
 
 client = pygazpar.Client(pygazpar.TestDataSource())
 
-data = client.loadSince(pceIdentifier='your PCE identifier',
-                        lastNDays=10,
+data = client.load_since(pce_identifier='your PCE identifier',
+                        last_n_days=10,
                         frequencies=[pygazpar.Frequency.DAILY, Frequency.MONTHLY])
 ```
 See [samples/testSample.py](samples/jsonSample.py) file for the full example.

pygazpar-1.3.0/pygazpar/__init__.py

@@ -0,0 +1,10 @@
+from pygazpar.client import Client  # noqa: F401
+from pygazpar.datasource import (  # noqa: F401
+    ExcelFileDataSource,
+    ExcelWebDataSource,
+    JsonFileDataSource,
+    JsonWebDataSource,
+    TestDataSource,
+)
+from pygazpar.enum import Frequency, PropertyName  # noqa: F401
+from pygazpar.version import __version__  # noqa: F401

pygazpar-1.3.0/pygazpar/__main__.py

@@ -0,0 +1,89 @@
+import argparse
+import json
+import logging
+import os
+import sys
+import traceback
+
+import pygazpar
+
+Logger = logging.getLogger(__name__)
+
+
+def main():
+    """Main function"""
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-v", "--version", action="version", version=f"PyGazpar {pygazpar.__version__}")
+    parser.add_argument("-u", "--username", required=True, help="GRDF username (email)")
+    parser.add_argument("-p", "--password", required=True, help="GRDF password")
+    parser.add_argument("-c", "--pce", required=True, help="GRDF PCE identifier")
+    parser.add_argument("-t", "--tmpdir", required=False, default="/tmp", help="tmp directory (default is /tmp)")
+    parser.add_argument(
+        "-f",
+        "--frequency",
+        required=False,
+        type=lambda frequency: pygazpar.Frequency[frequency],
+        choices=list(pygazpar.Frequency),
+        default="DAILY",
+        help="Meter reading frequency (DAILY, WEEKLY, MONTHLY, YEARLY)",
+    )
+    parser.add_argument(
+        "-d",
+        "--lastNDays",
+        required=False,
+        type=int,
+        default=365,
+        help="Get only the last N days of records (default: 365 days)",
+    )
+    parser.add_argument("--datasource", required=False, default="json", help="Datasource: json | excel | test")
+
+    args = parser.parse_args()
+
+    print(f"PyGazpar version: {pygazpar.__version__}")
+    print(f"Running on Python version: {sys.version}")
+
+    # We create the tmp directory if not already exists.
+    if not os.path.exists(args.tmpdir):
+        os.mkdir(args.tmpdir)
+
+    # We remove the pygazpar log file.
+    pygazparLogFile = f"{args.tmpdir}/pygazpar.log"
+    if os.path.isfile(pygazparLogFile):
+        os.remove(pygazparLogFile)
+
+    # Setup logging.
+    logging.basicConfig(
+        filename=f"{pygazparLogFile}", level=logging.DEBUG, format="%(asctime)s %(levelname)s [%(name)s] %(message)s"
+    )
+
+    Logger.info(f"PyGazpar version: {pygazpar.__version__}")
+    Logger.info(f"Running on Python version: {sys.version}")
+    Logger.info(f"--tmpdir {args.tmpdir}")
+    Logger.info(f"--frequency {args.frequency}")
+    Logger.info(f"--lastNDays {args.lastNDays}")
+    Logger.info(f"--datasource {bool(args.datasource)}")
+
+    if args.datasource == "json":
+        client = pygazpar.Client(pygazpar.JsonWebDataSource(args.username, args.password))
+    elif args.datasource == "excel":
+        client = pygazpar.Client(pygazpar.ExcelWebDataSource(args.username, args.password, args.tmpdir))
+    elif args.datasource == "test":
+        client = pygazpar.Client(pygazpar.TestDataSource())
+    else:
+        raise ValueError("Invalid datasource: (json | excel | test) is expected")
+
+    try:
+        data = client.load_since(args.pce, int(args.lastNDays), [args.frequency])
+    except BaseException:  # pylint: disable=broad-except
+        print("An error occured while querying PyGazpar library : %s", traceback.format_exc())
+        return 1
+
+    Logger.info(f"Data loaded: {len(data)} records")
+    Logger.debug(f"Data: {data}")
+    print(json.dumps(data, indent=2))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())