[Fix] First set of changes to include Netatmo home parameter (#43)

Author: philippelt

README.md

@@ -7,6 +7,14 @@ For more detailed information see http://dev.netatmo.com
 I have no relation with the netatmo company, I wrote this because I needed it myself,
 and published it to save time to anyone who would have same needs.
 
+Following the implementation of "Home" everywhere in the Netatmo API with various behavior, the library has been adjusted to include the home parameters in most calls.
+If you are using a single account with a single home and single weather station, the library has been implemented so that your code should continue to run without change.
+
+If you have multiple homes or were supplying a station name in some method calls, you will have to adapt your code :
+ - to supply a home name when looking for data for most class initializers
+ - to use the new station name set by Netatmo (which is not your previously set value)
+
+
 ### Install ###
 
 To install lnetatmo simply run:
@@ -18,6 +26,9 @@ To install lnetatmo simply run:
     pip install lnetatmo
 
 Depending on your permissions you might be required to use sudo.
+
+It is a single file module, on platforms where you have limited access, you just have to clone the repo and take the lnetatmo.py in the same directory than your main program.
+
 Once installed you can simple add lnetatmo to your python scripts by including:
 
     import lnetatmo

lnetatmo.py

@@ -10,11 +10,14 @@
 PythonAPI Netatmo REST data access
 coding=utf-8
 """
+
+import warnings
+if __name__ == "__main__": warnings.filterwarnings("ignore") # For installation test only
+
 from sys import version_info
 from os import getenv
 from os.path import expanduser, exists
 import platform
-import warnings
 import json, time
 import imghdr
 import warnings
@@ -156,6 +159,10 @@ class NoDevice( Exception ):
     pass
 
 
+class NoHome( Exception ):
+    pass
+
+
 class AuthFailure( Exception ):
     pass
 
@@ -251,34 +258,35 @@ class ThermostatData:
 
     Args:
         authData (clientAuth): Authentication information with a working access Token
+        home : Home name or id of the home who's thermostat belongs to
     """
-    def __init__(self, authData):
+    def __init__(self, authData, home=None):
+
+        # I don't own a thermostat thus I am not able to test the Thermostat support
+        warnings.warn("The Thermostat code is not tested due to the lack of test environment.\n" \
+                      "As Netatmo is continuously breaking API compatibility, risk that current bindings are wrong is high.\n" \
+                      "Please report found issues (https://github.com/philippelt/netatmo-api-python/issues)",
+                       RuntimeWarning )
+
         self.getAuthToken = authData.accessToken
         postParams = {
                 "access_token" : self.getAuthToken
                 }
         resp = postRequest(_GETTHERMOSTATDATA_REQ, postParams)
         self.rawData = resp['body']['devices']
         if not self.rawData : raise NoDevice("No thermostat available")
-        self.thermostat = { d['_id'] : d for d in self.rawData }
-        for t,v in self.thermostat.items():
-            v['name'] = v['station_name']
-            for m in v['modules']:
-                m['name'] = m['module_name']
-        self.defaultThermostat = self.rawData[0]['station_name']
-        self.defaultThermostatId = self.rawData[0]['_id']
-        self.defaultModule = self.rawData[0]['modules'][0]
-
-    def getThermostat(self, name=None, tid=None):
-        if tid:
-            if tid in self.thermostat.keys():
-                return self.thermostat[tid]
-            else:
-                return None
-        elif name:
-            for t in self.thermostat.values():
-                if t['name'] == name: return t
-            return None
+        self.thermostatData = filter_home_data(rawData, home)
+        if not self.thermostatData : raise NoHome("No home %s found" % home)
+        self.thermostatData['name'] = self.thermostatData['home_name']
+        for m in self.thermostatData['modules']:
+            m['name'] = m['module_name']
+        self.defaultThermostat = self.thermostatData['home_name']
+        self.defaultThermostatId = self.thermostatData['_id']
+        self.defaultModule = self.thermostatData['modules'][0]
+
+    def getThermostat(self, name=None):
+        if ['name'] != name: return None
+        else: return 
         return self.thermostat[self.defaultThermostatId]
 
     def moduleNamesList(self, name=None, tid=None):
@@ -299,23 +307,28 @@ class WeatherStationData:
     Args:
         authData (ClientAuth): Authentication information with a working access Token
     """
-    def __init__(self, authData):
+    def __init__(self, authData, home=None, station=None):
         self.getAuthToken = authData.accessToken
         postParams = {
                 "access_token" : self.getAuthToken
                 }
         resp = postRequest(_GETSTATIONDATA_REQ, postParams)
         self.rawData = resp['body']['devices']
         # Weather data
-        if not self.rawData : raise NoDevice("No weather station available")
-        self.stations = { d['_id'] : d for d in self.rawData }
+        if not self.rawData : raise NoDevice("No weather station in any homes")
+        # Stations are no longer in the Netatmo API, keeping them for compatibility
+        self.stations = { d['station_name'] : d for d in self.rawData }
+        self.homes = { d['home_name'] : d["station_name"] for d in self.rawData }
+        # Keeping the old behavior for default station name
+        if station and station not in self.stations: raise NoDevice("No station with name %s" % station)
+        self.default_station = station or list(self.stations.keys())[0]
+        if home and home not in self.homes : raise NoHome("No home with name %s" % home)
+        self.default_home = home or list(self.homes.keys())[0]
         self.modules = dict()
-        for i in range(len(self.rawData)):
-            # Loop on external modules if they are present
-            if 'modules' in self.rawData[i]:
-                for m in self.rawData[i]['modules']:
-                    self.modules[ m['_id'] ] = m
-        self.default_station = list(self.stations.values())[0]['station_name']
+        self.default_station_data = self.stationByName(self.default_station)
+        if 'modules' in self.default_station_data:
+            for m in self.default_station_data['modules']:
+                self.modules[ m['_id'] ] = m
         # User data
         userData = resp['body']['user']
         self.user = UserInfo()
@@ -327,7 +340,7 @@ def __init__(self, authData):
                 setattr(self.user, k, v)
 
 
-    def modulesNamesList(self, station=None):
+    def modulesNamesList(self, station=None, home=None):
         res = [m['module_name'] for m in self.modules.values()]
         res.append(self.stationByName(station)['module_name'])
         return res
@@ -340,31 +353,20 @@ def stationByName(self, station=None):
         return None
 
     def stationById(self, sid):
-        return None if sid not in self.stations else self.stations[sid]
+        return self.stations.get(sid)
 
-    def moduleByName(self, module, station=None):
-        s = None
-        if station :
-            s = self.stationByName(station)
-            if not s : return None
+    def moduleByName(self, module):
         for m in self.modules:
             mod = self.modules[m]
             if mod['module_name'] == module :
                 return mod
         return None
 
-    def moduleById(self, mid, sid=None):
-        s = self.stationById(sid) if sid else None
-        if mid in self.modules :
-            if s:
-                for module in s['modules']:
-                    if module['_id'] == mid:
-                        return module
-            else:
-                return self.modules[mid]
+    def moduleById(self, mid):
+        return self.modules.get(mid)
 
-    def lastData(self, station=None, exclude=0):
-        s = self.stationByName(station) or self.stationById(station)
+    def lastData(self, exclude=0):
+        s = self.default_station_data
         # Breaking change from Netatmo : dashboard_data no longer available if station lost
         if not s or 'dashboard_data' not in s : return None
         lastD = dict()
@@ -417,22 +419,16 @@ def getMeasure(self, device_id, scale, mtype, module_id=None, date_begin=None, d
         postParams['real_time'] = "true" if real_time else "false"
         return postRequest(_GETMEASURE_REQ, postParams)
 
-    def MinMaxTH(self, station=None, module=None, frame="last24"):
-        if not station : station = self.default_station
-        s = self.stationByName(station)
-        if not s :
-            s = self.stationById(station)
-            if not s : return None
+    def MinMaxTH(self, module=None, frame="last24"):
+        s = self.default_station_data
         if frame == "last24":
             end = time.time()
             start = end - 24*3600 # 24 hours ago
         elif frame == "day":
             start, end = todayStamps()
         if module and module != s['module_name']:
-            m = self.moduleByName(module, s['station_name'])
-            if not m :
-                m = self.moduleById(s['_id'], module)
-                if not m : return None
+            m = self.moduleById(module) or self.moduleByName(module)
+            if not m : raise NoDevice("Can't find module %s" % module)
             # retrieve module's data
             resp = self.getMeasure(
                     device_id  = s['_id'],
@@ -470,7 +466,7 @@ class HomeData:
     Args:
         authData (ClientAuth): Authentication information with a working access Token
     """
-    def __init__(self, authData):
+    def __init__(self, authData, home=None):
         self.getAuthToken = authData.accessToken
         postParams = {
             "access_token" : self.getAuthToken
@@ -480,7 +476,7 @@ def __init__(self, authData):
         # Collect homes
         self.homes = { d['id'] : d for d in self.rawData['homes'] }
         if not self.homes : raise NoDevice("No home available")
-        self.default_home = list(self.homes.values())[0]['name']
+        self.default_home = home or list(self.homes.values())[0]['name']
         # Split homes data by category
         self.persons = dict()
         self.events = dict()
@@ -754,6 +750,17 @@ class WelcomeData(HomeData):
 
 # Utilities routines
 
+
+def filter_home_data(rawData, home):
+    if home:
+        # Find a home who's home id or name is the one requested
+        for h in rawData:
+            if h["home_name"] == home or h["home_id"] == home:
+                return h
+        return None
+    # By default, the first home is returned
+    return rawData[0]
+
 def cameraCommand(cameraUrl, commande, parameters=None, timeout=3):
     url = cameraUrl + ( commande % parameters if parameters else commande)
     return postRequest(url, timeout=timeout)
@@ -798,25 +805,29 @@ def todayStamps():
 
 # Global shortcut
 
-def getStationMinMaxTH(station=None, module=None):
+def getStationMinMaxTH(station=None, module=None, home=None):
     authorization = ClientAuth()
-    devList = DeviceList(authorization)
-    if not station : station = devList.default_station
-    if module :
-        mname = module
-    else :
-        mname = devList.stationByName(station)['module_name']
-    lastD = devList.lastData(station)
-    if mname == "*":
+    devList = WeatherStationData(authorization, station=station, home=home)
+    if module == "*":
+        pass
+    elif module:
+        module = devList.moduleById(module) or devList.moduleByName(module)
+        if not module: raise NoDevice("No such module %s" % module)
+        else: module = module["module_name"]
+    else:
+        module = list(devList.modules.values())[0]["module_name"]
+    lastD = devList.lastData()
+    if module == "*":
         result = dict()
         for m in lastD.keys():
             if time.time()-lastD[m]['When'] > 3600 : continue
             r = devList.MinMaxTH(module=m)
             result[m] = (r[0], lastD[m]['Temperature'], r[1])
     else:
         if time.time()-lastD[mname]['When'] > 3600 : result = ["-", "-"]
-        else : result = [lastD[mname]['Temperature'], lastD[mname]['Humidity']]
-        result.extend(devList.MinMaxTH(station, mname))
+        else : 
+            result = [lastD[module]['Temperature'], lastD[module]['Humidity']]
+            result.extend(devList.MinMaxTH(module))
     return result
 
 
@@ -841,7 +852,6 @@ def getStationMinMaxTH(station=None, module=None):
     else:
         weatherStation.MinMaxTH()                          # Test GETMEASUR
 
-
     try:
         homes = HomeData(authorization)
     except NoDevice :

setup.py

@@ -4,7 +4,7 @@
 
 setup(
     name='lnetatmo',
-    version='1.6.2',
+    version='2.0.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/tarball/v1.6.2.tar.gz',
+    download_url='https://github.com/philippelt/netatmo-api-python/tarball/v2.0.0.tar.gz',
     license='GPL V3',
     description='Simple API to access Netatmo weather station data from any python script.'
 )

usage.md

@@ -7,9 +7,11 @@ Python Netatmo API programmers guide
 
 >2014-01-13, Revision to include new modules additionnal informations
 
->2016-06-25 Update documentation for Netatmo Welcome
+>2016-06-25, Update documentation for Netatmo Welcome
 
->2017-01-09 Minor updates to packaging info
+>2017-01-09, Minor updates to packaging info
+
+>2020-12-07, Breaking changes due to removal of direct access to devices, "home" being now required (Netatmo redesign)
 
 No additional library other than standard Python library is required.
 
@@ -232,17 +234,22 @@ In most cases, you will not need to use this class that is oriented toward an ap
 Constructor
 
 ```python
-    weatherData = lnetatmo.WeatherStationData( authorization )
+    weatherData = lnetatmo.WeatherStationData( authorization, home=None, station=None )
 ```
 
 
-Requires : an authorization object (ClientAuth instance)
-
+ * Input :  : an authorization object (ClientAuth instance), an optional home name, an optional station name
 
 Return : a WeatherStationData object. This object contains most administration properties of stations and modules accessible to the user and the last data pushed by the station to the Netatmo servers.
 
 Raise a lnetatmo.NoDevice exception if no weather station is available for the given account.
 
+If no home is specified, the first returned home will be set as default home. Same apply to station.
+If you have only one home and one station, you can safely ignore these new parameters. Note that return order is undefined. If you have multiple homes and a weather station in only one, the default home may be the one without station and the call will fail.
+
+    **Breaking change**
+      >  If you used the station name in the past in any method call, you should be aware that Netatmo decided to rename your station with their own value thus your existing code will have to be updated.
+
 Properties, all properties are read-only unless specified:
 
 
@@ -443,8 +450,9 @@ Methods :
 If you just need the current temperature and humidity reported by a sensor with associated min and max values on the last 24 hours, you can get it all with only one call that handle all required steps including authentication :
 
 
-**getStationMinMaxTH**(station=None, module=None) :
+**getStationMinMaxTH**(station=None, module=Nonei, home=None) :
   * Input : optional station name and/or module name (if no station name is provided, default_station will be used, if no module name is provided, station sensor will be reported).
+    if no home is specified, first returned home will be used
   * Output : A tuple of 6 values (Temperature, Humidity, minT, MaxT, minH, maxH)
 
 ```python