Update docstrings

trovebox/api/api_album.py

@@ -8,13 +8,19 @@ from .api_base import ApiBase
 class ApiAlbums(ApiBase):
     """ Definitions of /albums/ API endpoints """
     def list(self, **kwds):
-        """ Return a list of Album objects """
+        """
+        Endpoint: /albums/list.json
+
+        Returns a list of Album objects.
+        """
         albums = self._client.get("/albums/list.json", **kwds)["result"]
         albums = http.result_to_list(albums)
         return [Album(self._client, album) for album in albums]
 
 class ApiAlbum(ApiBase):
     """ Definitions of /album/ API endpoints """
+    # def cover_update(self, album, photo, **kwds):
+
     def create(self, name, **kwds):
         """
         Endpoint: /album/create.json
@@ -41,10 +47,12 @@ class ApiAlbum(ApiBase):
         """ Not yet implemented """
         raise NotImplementedError()
 
+    # TODO: Should be just "add"
     def add_photos(self, album, photos, **kwds):
         """ Not yet implemented """
         raise NotImplementedError()
 
+    # TODO: Should be just "remove"
     def remove_photos(self, album, photos, **kwds):
         """ Not yet implemented """
         raise NotImplementedError()
@@ -54,6 +62,7 @@ class ApiAlbum(ApiBase):
         Endpoint: /album/<id>/update.json
 
         Updates an album with the specified parameters.
+        Returns the updated album object.
         """
         if not isinstance(album, Album):
             album = Album(self._client, {"id": album})

trovebox/api/api_photo.py

@@ -8,7 +8,7 @@ from trovebox.errors import TroveboxError
 from trovebox.objects.photo import Photo
 from .api_base import ApiBase
 
-def extract_ids(photos):
+def _extract_ids(photos):
     """
     Given a list of objects, extract the photo id for each Photo
     object.
@@ -23,41 +23,54 @@ def extract_ids(photos):
 
 class ApiPhotos(ApiBase):
     """ Definitions of /photos/ API endpoints """
+    # TODO: Add options
     def list(self, **kwds):
-        """ Returns a list of Photo objects """
+        """
+        Endpoint: /photos/list.json
+
+        Returns a list of Photo objects.
+        """
         photos = self._client.get("/photos/list.json", **kwds)["result"]
         photos = http.result_to_list(photos)
         return [Photo(self._client, photo) for photo in photos]
 
-    def update(self, photos, **kwds):
+    # def share(self, **kwds):
-        """
-        Updates a list of photos.
-        Returns True if successful.
-        Raises TroveboxError if not.
-        """
-        ids = extract_ids(photos)
-        if not self._client.post("/photos/update.json", ids=ids,
-                                 **kwds)["result"]:
-            raise TroveboxError("Update response returned False")
-        return True
 
     def delete(self, photos, **kwds):
         """
+        Endpoint: /photos/delete.json
+
         Deletes a list of photos.
         Returns True if successful.
-        Raises TroveboxError if not.
+        Raises a TroveboxError if not.
         """
-        ids = extract_ids(photos)
+        ids = _extract_ids(photos)
         if not self._client.post("/photos/delete.json", ids=ids,
                                  **kwds)["result"]:
             raise TroveboxError("Delete response returned False")
         return True
 
+    def update(self, photos, **kwds):
+        """
+        Endpoint: /photos/<id>/update.json
+
+        Updates a list of photos with the specified parameters.
+        Returns True if successful.
+        Raises TroveboxError if not.
+        """
+        ids = _extract_ids(photos)
+        if not self._client.post("/photos/update.json", ids=ids,
+                                 **kwds)["result"]:
+            raise TroveboxError("Update response returned False")
+        return True
+
 class ApiPhoto(ApiBase):
     """ Definitions of /photo/ API endpoints """
     def delete(self, photo, **kwds):
         """
-        Delete a photo.
+        Endpoint: /photo/<id>/delete.json
+
+        Deletes a photo.
         Returns True if successful.
         Raises a TroveboxError if not.
         """
@@ -65,8 +78,14 @@ class ApiPhoto(ApiBase):
             photo = Photo(self._client, {"id": photo})
         return photo.delete(**kwds)
 
+    # def delete_source(self, photo, **kwds):
+
     def edit(self, photo, **kwds):
-        """ Returns an HTML form to edit a photo """
+        """
+        Endpoint: /photo/<id>/edit.json
+
+        Returns an HTML form to edit a photo's attributes.
+        """
         if not isinstance(photo, Photo):
             photo = Photo(self._client, {"id": photo})
         return photo.edit(**kwds)
@@ -81,18 +100,25 @@ class ApiPhoto(ApiBase):
 
     def update(self, photo, **kwds):
         """
-        Update a photo with the specified parameters.
+        Endpoint: /photo/<id>/update.json
-        Returns the updated photo object
+
+        Updates a photo with the specified parameters.
+        Returns the updated photo object.
         """
         if not isinstance(photo, Photo):
             photo = Photo(self._client, {"id": photo})
         photo.update(**kwds)
         return photo
 
+    # TODO: Add options
     def view(self, photo, **kwds):
         """
-        Used to view the photo at a particular size.
+        Endpoint: /photo/<id>/view.json
-        Returns the requested photo object
+
+        Requests all properties of a photo.
+        Can be used to obtain URLs for the photo at a particular size,
+          by using the "returnSizes" parameter.
+        Returns the requested photo object.
         """
         if not isinstance(photo, Photo):
             photo = Photo(self._client, {"id": photo})
@@ -100,7 +126,11 @@ class ApiPhoto(ApiBase):
         return photo
 
     def upload(self, photo_file, **kwds):
-        """ Uploads the specified file to the server """
+        """
+        Endpoint: /photo/upload.json
+
+        Uploads the specified photo filename.
+        """
         with open(photo_file, 'rb') as in_file:
             result = self._client.post("/photo/upload.json",
                                        files={'photo': in_file},
@@ -108,7 +138,11 @@ class ApiPhoto(ApiBase):
         return Photo(self._client, result)
 
     def upload_encoded(self, photo_file, **kwds):
-        """ Base64-encodes and uploads the specified file """
+        """
+        Endpoint: /photo/upload.json
+
+        Base64-encodes and uploads the specified photo filename.
+        """
         with open(photo_file, "rb") as in_file:
             encoded_photo = base64.b64encode(in_file.read())
         result = self._client.post("/photo/upload.json", photo=encoded_photo,
@@ -119,8 +153,11 @@ class ApiPhoto(ApiBase):
         """ Not yet implemented """
         raise NotImplementedError()
 
+    # TODO: Add options
     def next_previous(self, photo, **kwds):
         """
+        Endpoint: /photo/<id>/nextprevious.json
+
         Returns a dict containing the next and previous photo lists
         (there may be more than one next/previous photo returned).
         """
@@ -130,8 +167,11 @@ class ApiPhoto(ApiBase):
 
     def transform(self, photo, **kwds):
         """
-        Performs transformation specified in **kwds
+        Endpoint: /photo/<id>/transform.json
-        Example: transform(photo, rotate=90)
+
+        Performs the specified transformations.
+          eg. transform(photo, rotate=90)
+        Returns the transformed photo.
         """
         if not isinstance(photo, Photo):
             photo = Photo(self._client, {"id": photo})

trovebox/objects/album.py

@@ -18,6 +18,8 @@ class Album(TroveboxObject):
         if isinstance(self.cover, dict):
             self.cover = Photo(self._trovebox, self.cover)
 
+    # def cover_update(self, photo, **kwds):
+
     def delete(self, **kwds):
         """
         Endpoint: /album/<id>/delete.json
@@ -37,10 +39,12 @@ class Album(TroveboxObject):
         """ Not implemented yet """
         raise NotImplementedError()
 
+    # TODO: Should be just "add"
     def add_photos(self, photos, **kwds):
         """ Not implemented yet """
         raise NotImplementedError()
 
+    # TODO: Should be just "remove"
     def remove_photos(self, photos, **kwds):
         """ Not implemented yet """
         raise NotImplementedError()

trovebox/objects/photo.py

@@ -8,7 +8,9 @@ class Photo(TroveboxObject):
     """ Representation of a Photo object """
     def delete(self, **kwds):
         """
-        Delete this photo.
+        Endpoint: /photo/<id>/delete.json
+
+        Deletes this photo.
         Returns True if successful.
         Raises a TroveboxError if not.
         """
@@ -19,8 +21,14 @@ class Photo(TroveboxObject):
         self._delete_fields()
         return result
 
+    # def delete_source(self, **kwds):
+
     def edit(self, **kwds):
-        """ Returns an HTML form to edit the photo """
+        """
+        Endpoint: /photo/<id>/edit.json
+
+        Returns an HTML form to edit this photo's attributes.
+        """
         result = self._trovebox.get("/photo/%s/edit.json" %
                                     self.id, **kwds)["result"]
         return result["markup"]
@@ -34,14 +42,23 @@ class Photo(TroveboxObject):
         raise NotImplementedError()
 
     def update(self, **kwds):
-        """ Update this photo with the specified parameters """
+        """
+        Endpoint: /photo/<id>/update.json
+
+        Updates this photo with the specified parameters.
+        """
         result = self._trovebox.post("/photo/%s/update.json" %
                                      self.id, **kwds)["result"]
         self._replace_fields(result)
 
+    # TODO: Add options
     def view(self, **kwds):
         """
-        Used to view the photo at a particular size.
+        Endpoint: /photo/<id>/view.json
+
+        Requests all properties of this photo.
+        Can be used to obtain URLs for the photo at a particular size,
+          by using the "returnSizes" parameter.
         Updates the photo's fields with the response.
         """
         result = self._trovebox.get("/photo/%s/view.json" %
@@ -52,8 +69,11 @@ class Photo(TroveboxObject):
         """ Not implemented yet """
         raise NotImplementedError()
 
+    # TODO: Add options
     def next_previous(self, **kwds):
         """
+        Endpoint: /photo/<id>/nextprevious.json
+
         Returns a dict containing the next and previous photo lists
         (there may be more than one next/previous photo returned).
         """
@@ -82,8 +102,11 @@ class Photo(TroveboxObject):
 
     def transform(self, **kwds):
         """
-        Performs transformation specified in **kwds
+        Endpoint: /photo/<id>/transform.json
-        Example: transform(rotate=90)
+
+        Performs the specified transformations.
+          eg. transform(photo, rotate=90)
+        Updates the photo's fields with the response.
         """
         result = self._trovebox.post("/photo/%s/transform.json" %
                                      self.id, **kwds)["result"]