| #!/usr/bin/python |
| |
| """ |
| Extend gdata.service.GDataService to support authenticated CRUD ops on |
| Books API |
| |
| http://code.google.com/apis/books/docs/getting-started.html |
| http://code.google.com/apis/books/docs/gdata/developers_guide_protocol.html |
| |
| TODO: (here and __init__) |
| * search based on label, review, or other annotations (possible?) |
| * edit (specifically, Put requests) seem to fail effect a change |
| |
| Problems With API: |
| * Adding a book with a review to the library adds a note, not a review. |
| This does not get included in the returned item. You see this by |
| looking at My Library through the website. |
| * Editing a review never edits a review (unless it is freshly added, but |
| see above). More generally, |
| * a Put request with changed annotations (label/rating/review) does NOT |
| change the data. Note: Put requests only work on the href from |
| GetEditLink (as per the spec). Do not try to PUT to the annotate or |
| library feeds, this will cause a 400 Invalid URI Bad Request response. |
| Attempting to Post to one of the feeds with the updated annotations |
| does not update them. See the following for (hopefully) a follow up: |
| google.com/support/forum/p/booksearch-apis/thread?tid=27fd7f68de438fc8 |
| * Attempts to workaround the edit problem continue to fail. For example, |
| removing the item, editing the data, readding the item, gives us only |
| our originally added data (annotations). This occurs even if we |
| completely shut python down, refetch the book from the public feed, |
| and re-add it. There is some kind of persistence going on that I |
| cannot change. This is likely due to the annotations being cached in |
| the annotation feed and the inability to edit (see Put, above) |
| * GetAnnotationLink has www.books.... as the server, but hitting www... |
| results in a bad URI error. |
| * Spec indicates there may be multiple labels, but there does not seem |
| to be a way to get the server to accept multiple labels, nor does the |
| web interface have an obvious way to have multiple labels. Multiple |
| labels are never returned. |
| """ |
| |
| __author__ = "James Sams <sams.james@gmail.com>" |
| __copyright__ = "Apache License v2.0" |
| |
| from shlex import split |
| |
| import gdata.service |
| try: |
| import books |
| except ImportError: |
| import gdata.books as books |
| |
| |
| BOOK_SERVER = "books.google.com" |
| GENERAL_FEED = "/books/feeds/volumes" |
| ITEM_FEED = "/books/feeds/volumes/" |
| LIBRARY_FEED = "/books/feeds/users/%s/collections/library/volumes" |
| ANNOTATION_FEED = "/books/feeds/users/%s/volumes" |
| PARTNER_FEED = "/books/feeds/p/%s/volumes" |
| BOOK_SERVICE = "print" |
| ACCOUNT_TYPE = "HOSTED_OR_GOOGLE" |
| |
| |
| class BookService(gdata.service.GDataService): |
| |
| def __init__(self, email=None, password=None, source=None, |
| server=BOOK_SERVER, account_type=ACCOUNT_TYPE, |
| exception_handlers=tuple(), **kwargs): |
| """source should be of form 'ProgramCompany - ProgramName - Version'""" |
| |
| gdata.service.GDataService.__init__(self, email=email, |
| password=password, service=BOOK_SERVICE, source=source, |
| server=server, **kwargs) |
| self.exception_handlers = exception_handlers |
| |
| def search(self, q, start_index="1", max_results="10", |
| min_viewability="none", feed=GENERAL_FEED, |
| converter=books.BookFeed.FromString): |
| """ |
| Query the Public search feed. q is either a search string or a |
| gdata.service.Query instance with a query set. |
| |
| min_viewability must be "none", "partial", or "full". |
| |
| If you change the feed to a single item feed, note that you will |
| probably need to change the converter to be Book.FromString |
| """ |
| |
| if not isinstance(q, gdata.service.Query): |
| q = gdata.service.Query(text_query=q) |
| if feed: |
| q.feed = feed |
| q['start-index'] = start_index |
| q['max-results'] = max_results |
| q['min-viewability'] = min_viewability |
| return self.Get(uri=q.ToUri(),converter=converter) |
| |
| def search_by_keyword(self, q='', feed=GENERAL_FEED, start_index="1", |
| max_results="10", min_viewability="none", **kwargs): |
| """ |
| Query the Public Search Feed by keyword. Non-keyword strings can be |
| set in q. This is quite fragile. Is there a function somewhere in |
| the Google library that will parse a query the same way that Google |
| does? |
| |
| Legal Identifiers are listed below and correspond to their meaning |
| at http://books.google.com/advanced_book_search: |
| all_words |
| exact_phrase |
| at_least_one |
| without_words |
| title |
| author |
| publisher |
| subject |
| isbn |
| lccn |
| oclc |
| seemingly unsupported: |
| publication_date: a sequence of two, two tuples: |
| ((min_month,min_year),(max_month,max_year)) |
| where month is one/two digit month, year is 4 digit, eg: |
| (('1','2000'),('10','2003')). Lower bound is inclusive, |
| upper bound is exclusive |
| """ |
| |
| for k, v in kwargs.items(): |
| if not v: |
| continue |
| k = k.lower() |
| if k == 'all_words': |
| q = "%s %s" % (q, v) |
| elif k == 'exact_phrase': |
| q = '%s "%s"' % (q, v.strip('"')) |
| elif k == 'at_least_one': |
| q = '%s %s' % (q, ' '.join(['OR "%s"' % x for x in split(v)])) |
| elif k == 'without_words': |
| q = '%s %s' % (q, ' '.join(['-"%s"' % x for x in split(v)])) |
| elif k in ('author','title', 'publisher'): |
| q = '%s %s' % (q, ' '.join(['in%s:"%s"'%(k,x) for x in split(v)])) |
| elif k == 'subject': |
| q = '%s %s' % (q, ' '.join(['%s:"%s"' % (k,x) for x in split(v)])) |
| elif k == 'isbn': |
| q = '%s ISBN%s' % (q, v) |
| elif k == 'issn': |
| q = '%s ISSN%s' % (q,v) |
| elif k == 'oclc': |
| q = '%s OCLC%s' % (q,v) |
| else: |
| raise ValueError("Unsupported search keyword") |
| return self.search(q.strip(),start_index=start_index, feed=feed, |
| max_results=max_results, |
| min_viewability=min_viewability) |
| |
| def search_library(self, q, id='me', **kwargs): |
| """Like search, but in a library feed. Default is the authenticated |
| user's feed. Change by setting id.""" |
| |
| if 'feed' in kwargs: |
| raise ValueError("kwarg 'feed' conflicts with library_id") |
| feed = LIBRARY_FEED % id |
| return self.search(q, feed=feed, **kwargs) |
| |
| def search_library_by_keyword(self, id='me', **kwargs): |
| """Hybrid of search_by_keyword and search_library |
| """ |
| |
| if 'feed' in kwargs: |
| raise ValueError("kwarg 'feed' conflicts with library_id") |
| feed = LIBRARY_FEED % id |
| return self.search_by_keyword(feed=feed,**kwargs) |
| |
| def search_annotations(self, q, id='me', **kwargs): |
| """Like search, but in an annotation feed. Default is the authenticated |
| user's feed. Change by setting id.""" |
| |
| if 'feed' in kwargs: |
| raise ValueError("kwarg 'feed' conflicts with library_id") |
| feed = ANNOTATION_FEED % id |
| return self.search(q, feed=feed, **kwargs) |
| |
| def search_annotations_by_keyword(self, id='me', **kwargs): |
| """Hybrid of search_by_keyword and search_annotations |
| """ |
| |
| if 'feed' in kwargs: |
| raise ValueError("kwarg 'feed' conflicts with library_id") |
| feed = ANNOTATION_FEED % id |
| return self.search_by_keyword(feed=feed,**kwargs) |
| |
| def add_item_to_library(self, item): |
| """Add the item, either an XML string or books.Book instance, to the |
| user's library feed""" |
| |
| feed = LIBRARY_FEED % 'me' |
| return self.Post(data=item, uri=feed, converter=books.Book.FromString) |
| |
| def remove_item_from_library(self, item): |
| """ |
| Remove the item, a books.Book instance, from the authenticated user's |
| library feed. Using an item retrieved from a public search will fail. |
| """ |
| |
| return self.Delete(item.GetEditLink().href) |
| |
| def add_annotation(self, item): |
| """ |
| Add the item, either an XML string or books.Book instance, to the |
| user's annotation feed. |
| """ |
| # do not use GetAnnotationLink, results in 400 Bad URI due to www |
| return self.Post(data=item, uri=ANNOTATION_FEED % 'me', |
| converter=books.Book.FromString) |
| |
| def edit_annotation(self, item): |
| """ |
| Send an edited item, a books.Book instance, to the user's annotation |
| feed. Note that whereas extra annotations in add_annotations, minus |
| ratings which are immutable once set, are simply added to the item in |
| the annotation feed, if an annotation has been removed from the item, |
| sending an edit request will remove that annotation. This should not |
| happen with add_annotation. |
| """ |
| |
| return self.Put(data=item, uri=item.GetEditLink().href, |
| converter=books.Book.FromString) |
| |
| def get_by_google_id(self, id): |
| return self.Get(ITEM_FEED + id, converter=books.Book.FromString) |
| |
| def get_library(self, id='me',feed=LIBRARY_FEED, start_index="1", |
| max_results="100", min_viewability="none", |
| converter=books.BookFeed.FromString): |
| """ |
| Return a generator object that will return gbook.Book instances until |
| the search feed no longer returns an item from the GetNextLink method. |
| Thus max_results is not the maximum number of items that will be |
| returned, but rather the number of items per page of searches. This has |
| been set high to reduce the required number of network requests. |
| """ |
| |
| q = gdata.service.Query() |
| q.feed = feed % id |
| q['start-index'] = start_index |
| q['max-results'] = max_results |
| q['min-viewability'] = min_viewability |
| x = self.Get(uri=q.ToUri(), converter=converter) |
| while 1: |
| for entry in x.entry: |
| yield entry |
| else: |
| l = x.GetNextLink() |
| if l: # hope the server preserves our preferences |
| x = self.Get(uri=l.href, converter=converter) |
| else: |
| break |
| |
| def get_annotations(self, id='me', start_index="1", max_results="100", |
| min_viewability="none", converter=books.BookFeed.FromString): |
| """ |
| Like get_library, but for the annotation feed |
| """ |
| |
| return self.get_library(id=id, feed=ANNOTATION_FEED, |
| max_results=max_results, min_viewability = min_viewability, |
| converter=converter) |
