[Change] Refactoring of authentication

Author: philippelt

README.md

@@ -13,6 +13,8 @@ I am trying to make this library survive to continuous Netatmo changes but their
 
 >NEW MAJOR BREAKING CHANGE (december 2023): Web generated refresh_tokens are no more long lived tokens, they will be automatically refreshed. Consequences : No more static authentication in the library source and ~/.netatmo-credentials file will be updated to reflect change in the refresh token. This file MUST be writable and if you run Netatmo tools in container, remember to persist this file between container run. **This new token policy will completely forbid you to use your credentials on two or more systems if you can't share the .netatmo-credentials file**.
 
+There is no longer credential load at library import, credentials are loaded at `ClientAuth` class initialization and a new parameter `credentialFile` allow to specify private name and location for the credential file.
+
 ### Install ###
 
 To install lnetatmo simply run:

lnetatmo.py

@@ -43,25 +43,12 @@
 # To ease Docker packaging of your application, you can setup your authentication parameters through env variables
 
 # Authentication:
-#  1 - The .netatmo.credentials file in JSON format in your home directory (now mandatory for regular use)
-#  2 - Values defined in environment variables : CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN
+#  1 - Values defined in environment variables : CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN
+#  2 - Parameters passed to ClientAuth initialization
+#  3 - The .netatmo.credentials file in JSON format in your home directory (now mandatory for regular use)
 
 # Note that the refresh token being short lived, using envvar will be restricted to speific testing use case
 
-# Note: this file will be rewritten by the library to record refresh_token change
-# If you run your application in container, remember to persist this file
-CREDENTIALS = expanduser("~/.netatmo.credentials")
-with open(CREDENTIALS, "r") as f:
-    cred = {k.upper():v for k,v in json.loads(f.read()).items()}
-
-def getParameter(key, default):
-    return getenv(key, default.get(key, None))
-
-# Override values with content of env variables if defined
-_CLIENT_ID     = getParameter("CLIENT_ID", cred)
-_CLIENT_SECRET = getParameter("CLIENT_SECRET", cred)
-_REFRESH_TOKEN = getParameter("REFRESH_TOKEN", cred)
-
 #########################################################################
 
 
@@ -225,14 +212,28 @@ class ClientAuth:
         refreshToken (str) : Scoped refresh token
     """
 
-    def __init__(self, clientId=_CLIENT_ID,
-                       clientSecret=_CLIENT_SECRET,
-                       refreshToken=_REFRESH_TOKEN):
-
-        self._clientId = clientId
-        self._clientSecret = clientSecret
-        self._accessToken = None
-        self.refreshToken = refreshToken
+    def __init__(self, clientId=None,
+                       clientSecret=None,
+                       refreshToken=None,
+                       credentialFile=None):
+        
+        # replace values with content of env variables if defined
+        clientId = getenv("CLIENT_ID", clientId)
+        clientSecret = getenv("CLIENT_SECRET", clientSecret)
+        refreshToken = getenv("REFRESH_TOKEN", refreshToken)
+
+        # Look for credentials in file if not already provided
+        # Note: this file will be rewritten by the library to record refresh_token change
+        # If you run your application in container, remember to persist this file
+        if not (clientId and clientSecret and refreshToken):
+            credentialFile = credentialFile or expanduser("~/.netatmo.credentials")
+            self._credentialFile = credentialFile
+            with open(self._credentialFile, "r") as f:
+                cred = {k.upper():v for k,v in json.loads(f.read()).items()}
+
+        self._clientId = clientId or cred["CLIENT_ID"]
+        self._clientSecret = clientSecret or cred["CLIENT_SECRET"]
+        self.refreshToken = refreshToken or cred["REFRESH_TOKEN"]
         self.expiration = 0 # Force refresh token
 
     @property
@@ -250,8 +251,10 @@ def renew_token(self):
         resp = postRequest("authentication", _AUTH_REQ, postParams)
         if self.refreshToken != resp['refresh_token']:
             self.refreshToken = resp['refresh_token']
-            cred["REFRESH_TOKEN"] = self.refreshToken
-            with open(CREDENTIALS, "w") as f:
+            cred = {"CLIENT_ID":self._clientId,
+                    "CLIENT_SECRET":self._clientSecret,
+                    "REFRESH_TOKEN":self.refreshToken }
+            with open(self._credentialFile, "w") as f:
                 f.write(json.dumps(cred, indent=True))
         self._accessToken = resp['access_token']
         self.expiration = int(resp['expire_in'] + time.time())
@@ -451,10 +454,16 @@ def __init__(self, authData, home=None, station=None):
             else:
                 setattr(self.user, k, v)
 
-
-    def modulesNamesList(self, station=None, home=None):
+    def modulesNamesList(self, station=None):
+        s = self.getStation(station)
+        if not s: raise NoDevice("No station with name or id %s" % station)
+        self.default_station = station
+        self.default_station_data = s
+        self.modules = dict()
+        if 'modules' in self.default_station_data:
+            for m in self.default_station_data['modules']:
+                self.modules[ m['_id'] ] = m
         res = [m['module_name'] for m in self.modules.values()]
-        station = self.stationByName(station) or self.stationById(station)
         res.append(station['module_name'])
         return res
 
@@ -468,21 +477,21 @@ def getStation(self, station=None):
         if station in self.stationIds : return self.stationIds[station]
         return None
 
+    def getModule(self, module):
+        if module in self.modules: return self.modules[module]
+        for m in self.modules.values():
+            if m['module_name'] == module : return m
+        return None
+    
     # Functions for compatibility with previous versions
     def stationByName(self, station=None):
         return self.getStation(station)
     def stationById(self, sid):
         return self.getStation(sid)
-
     def moduleByName(self, module):
-        for m in self.modules:
-            mod = self.modules[m]
-            if mod['module_name'] == module :
-                return mod
-        return None
-
+        return self.getModule(module)
     def moduleById(self, mid):
-        return self.modules.get(mid)
+        return self.getModule(mid)
 
     def lastData(self, station=None, exclude=0):
         s = self.stationByName(station) or self.stationById(station)
@@ -1082,10 +1091,6 @@ def getStationMinMaxTH(station=None, module=None, home=None):
 
     logging.basicConfig(format='%(name)s - %(levelname)s: %(message)s', level=logging.INFO)
 
-    if not _CLIENT_ID or not _CLIENT_SECRET or not _REFRESH_TOKEN :
-           stderr.write("Library source missing identification arguments to check lnetatmo.py (user/password/etc...)")
-           exit(1)
-
     authorization = ClientAuth()                                                          # Test authentication method
 
     try:

setup.py

@@ -4,7 +4,7 @@
 
 setup(
     name='lnetatmo',
-    version='4.0.1',
+    version='4.1.0',
     classifiers=[
         'Development Status :: 5 - Production/Stable',
         'Intended Audience :: Developers',
@@ -17,7 +17,7 @@
     scripts=[],
     data_files=[],
     url='https://github.com/philippelt/netatmo-api-python',
-    download_url='https://github.com/philippelt/netatmo-api-python/archive/v4.0.1.tar.gz',
+    download_url='https://github.com/philippelt/netatmo-api-python/archive/v4.1.0.tar.gz',
     license='GPL V3',
     description='Simple API to access Netatmo weather station data from any python script.'
 )

usage.md

@@ -19,6 +19,8 @@ Python Netatmo API programmers guide
 
 >2023-12-04, New update to Netatmo authentication rules, no longer long lived refresh token -> credentials MUST be writable, Hard coding credentials in the library no longer possible (bad luck for small home automation device)
 
+>2024-01-03, New authentication method priorities, credential file as a parameter
+
 No additional library other than standard Python library is required.
 
 Both Python V2.7x and V3.x.x are supported without change.
@@ -50,31 +52,36 @@ Copy the lnetatmo.py file in your work directory (or use pip install lnetatmo).
 
 Authentication data can be supplied with 3 different methods (each method override any settings of previous methods) : 
 
- 1. Some or all values can stored in ~/.netatmo.credentials (in your platform home directory) file containing the keys in JSON format  
+ 1. Some or all values can be defined by explicit call to initializer of ClientAuth class  
+ 
+        ̀```bash
+        # Example: REFRESH_TOKEN supposed to be defined by an other method
+        authData = lnetatmo.ClientAuth( clientId="netatmo-client-id",
+                                        clientSecret="secret" )
+        ```
+
+ 2. Some or all values can stored in ~/.netatmo.credentials (in your platform home directory) or a file path specified using the ̀`credentialFile` parameter. The file containing the keys in JSON format  
 
+        ̀̀```bash
         $ cat .netatmo.credentials   # Here all values are defined but it is not mandatory
         {
             "CLIENT_ID" : "`xxx",
             "CLIENT_SECRET" : "xxx",
             "REFRESH_TOKEN" : "xxx"
         }
         $
+        ̀̀```
 
-> Due to Netatmo continuous changes, this method is the only one available for production use as the refresh token will be frequently refreshed and this file MUST be writable by the library to keep a usable refresh token.
-
- 2. Some or all values can be overriden by environment variables. This is the easiest method if your are packaging your application with Docker. It also allow you to do some testing with other accounts without touching your current ~/.netatmo.credentials file 
+ 3. Some or all values can be overriden by environment variables. This is the easiest method if your are packaging your application with Docker.
 
+        ̀̀```bash
         $ export REFRESH_TOKEN="yyy"
         $ python3 MyCodeUsingLnetatmo.py
-        ...
+        ̀̀```
         
- 3. Some or all values can be overriden by explicit call to initializer of ClientAuth class  
- 
-        # Example: REFRESH_TOKEN supposed to be defined by one of the previous methods
-        authData = lnetatmo.ClientAuth( clientId="netatmo-client-id",
-                                        clientSecret="secret" )
+> Due to Netatmo continuous changes, the credential file is the recommended method for production use as the refresh token will be frequently refreshed and this file MUST be writable by the library to keep a usable refresh token. You can also recover the `authorization.refreshToken` before your program termination and save it to be able to pass it back when your program restart.
 
-If you provide all the values, using any method or mix except 3, you can test that everything is working properly by simply running the package as a standalone program.
+If you provide all the values in a credential file, you can test that everything is working properly by simply running the package as a standalone program.
 
 This will run a full access test to the account and stations and return 0 as return code if everything works well. If run interactively, it will also display an OK message.
 
@@ -171,6 +178,7 @@ Constructor
     authorization = lnetatmo.ClientAuth( clientId = _CLIENT_ID,
                                          clientSecret = _CLIENT_SECRET,
                                          refreshToken = _REFRESH_TOKEN,
+                                         credentialFile = "~/.netatmo.credentials"
                                         )
 ```