Fix functions for Watchlists API endpoint (#294)

* Add PUT HTTP request method

* Fix update_watchlist

* Fix add_watchlist

* Add docstrings

* Add get_watchlist_by_name

Author: k-kristof

alpaca_trade_api/rest.py

@@ -157,6 +157,9 @@ def get(self, path, data=None):
 
     def post(self, path, data=None):
         return self._request('POST', path, data)
+    
+    def put(self, path, data=None):
+        return self._request('PUT', path, data)
 
     def patch(self, path, data=None):
         return self._request('PATCH', path, data)
@@ -529,39 +532,61 @@ def get_calendar(self, start: str = None, end: str = None) -> Calendars:
         return [Calendar(o) for o in resp]
 
     def get_watchlists(self) -> Watchlists:
+        """Get the list of watchlists registered under the account"""
         resp = self.get('/watchlists')
         return [Watchlist(o) for o in resp]
 
     def get_watchlist(self, watchlist_id: str) -> Watchlist:
+        """Get a watchlist identified by the ID"""
         resp = self.get('/watchlists/{}'.format((watchlist_id)))
         return Watchlist(resp)
 
-    def add_watchlist(self, watchlist_name: str) -> Watchlists:
-        resp = self.post('/watchlists', data=dict(name=watchlist_name))
-        return [Watchlist(o) for o in resp]
+    def get_watchlist_by_name(self, watchlist_name: str) -> Watchlist:
+        """Get a watchlist identified by its name"""
+        params = {
+            'name': watchlist_name,
+        }
+        resp = self.get('/watchlists:by_name', data=params)
+        return Watchlist(resp)
+
+    def create_watchlist(self,
+                         watchlist_name: str,
+                         symbols = None) -> Watchlist:
+        """Create a new watchlist with an optional initial set of assets"""
+        params = {
+            'name': watchlist_name,
+        }
+        if symbols is not None:
+            params['symbols'] = symbols
+        resp = self.post('/watchlists', data=params)
+        return Watchlist(resp)
 
     def add_to_watchlist(self, watchlist_id: str, symbol: str) -> Watchlist:
+        """Append the asset for a symbol to the end of a watchlist's asset list""" 
         resp = self.post(
             '/watchlists/{}'.format(watchlist_id), data=dict(symbol=symbol)
         )
         return Watchlist(resp)
 
     def update_watchlist(self,
-                         watchlist_id,
+                         watchlist_id: str,
                          name: str = None,
-                         symbols=None) -> Watchlist:
+                         symbols = None) -> Watchlist:
+        """Update a watchlist's name and/or asset list"""
         params = {}
         if name is not None:
             params['name'] = name
         if symbols is not None:
             params['symbols'] = symbols
-        resp = self.patch('/watchlists/{}'.format(watchlist_id), data=params)
+        resp = self.put('/watchlists/{}'.format(watchlist_id), data=params)
         return Watchlist(resp)
 
     def delete_watchlist(self, watchlist_id: str) -> None:
+        """Delete a watchlist identified by the ID permanently"""
         self.delete('/watchlists/{}'.format(watchlist_id))
 
     def delete_from_watchlist(self, watchlist_id: str, symbol: str) -> None:
+        """Remove an asset from the watchlist's asset list"""
         self.delete('/watchlists/{}/{}'.format(watchlist_id, symbol))
 
     def get_portfolio_history(self,