From 7afb709531e11847c4fa807a72045f46858e7082 Mon Sep 17 00:00:00 2001 From: sneakypete81 Date: Sat, 7 Sep 2013 10:49:14 +0100 Subject: [PATCH] Update docstrings --- trovebox/api/api_album.py | 11 ++++- trovebox/api/api_photo.py | 90 ++++++++++++++++++++++++++++----------- trovebox/objects/album.py | 4 ++ trovebox/objects/photo.py | 35 ++++++++++++--- 4 files changed, 108 insertions(+), 32 deletions(-) diff --git a/trovebox/api/api_album.py b/trovebox/api/api_album.py index e46eeea..eaa147b 100644 --- a/trovebox/api/api_album.py +++ b/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//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}) diff --git a/trovebox/api/api_photo.py b/trovebox/api/api_photo.py index e83e74e..885ac61 100644 --- a/trovebox/api/api_photo.py +++ b/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): - """ - 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 share(self, **kwds): 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//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//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//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. - Returns the updated photo object + Endpoint: /photo//update.json + + 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. - Returns the requested photo object + Endpoint: /photo//view.json + + 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//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 - Example: transform(photo, rotate=90) + Endpoint: /photo//transform.json + + Performs the specified transformations. + eg. transform(photo, rotate=90) + Returns the transformed photo. """ if not isinstance(photo, Photo): photo = Photo(self._client, {"id": photo}) diff --git a/trovebox/objects/album.py b/trovebox/objects/album.py index b2acdb4..b09b471 100644 --- a/trovebox/objects/album.py +++ b/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//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() diff --git a/trovebox/objects/photo.py b/trovebox/objects/photo.py index ffb66af..47a9901 100644 --- a/trovebox/objects/photo.py +++ b/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//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//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//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//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//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 - Example: transform(rotate=90) + Endpoint: /photo//transform.json + + 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"]