Sebastian Rahlf avatar Sebastian Rahlf committed 5160329

Tweaked introductory text a bit.

Comments (0)

Files changed (2)

docs/source/basic-usage.rst

 
-Basic usage
-===========
+.. _getting-started:
+
+Getting started
+===============
 
 In order to use this API you'll obviously need an Amazon Associates Web Service
 account for which you must `register with Amazon`_. Each account contains an
 *AWSAccessKeyId* and a *SecretKey*. As of API version 2011-08-01 you will also
 need to `register for an AssociateTag`_.
 
+.. note:: It is assumed that you know what the Amazon Product Advertising API
+   does. If you are unsure, read their `developer guide`_ (particularly the
+   section *Introduction to the Product Advertising API*.  
+
+.. _developer guide: http://docs.amazonwebservices.com/AWSECommerceService/
+    2011-08-01/DG/Welcome.html?r=4324
 
 Basic setup
 -----------
 
 If you haven't done so already, create a file ``~/.amazon-product-api``
-(``C:\Users\You\.amazon-product-api`` if your on Windows) and paste the
+(``C:\Users\You\.amazon-product-api`` if you're on Windows) and paste the
 following content into it::
 
     [Credentials]
     api = API(locale='us')
     items = api.item_search('Books', Publisher="O'Reilly")
 
-The ``node`` object returned is a `lxml.objectified`__ element. All its 
-attributes can be accessed the pythonic way::
-    
-    # .pyval will convert the node content into int here
-    total_results = node.Items.TotalResults.pyval
-    total_pages = node.Items.TotalPages.pyval
+So what happens here? First you initialised your API wrapper to use Amazon.com.
+There are, of course, `other locales available`_ should you wish to use a
+different one. For instance, ``locale='de'`` will cause requests to be sent to
+Amazon.de (Germany).
+
+Afterwards you called the API operation *ItemSearch* to get a list of all books
+that where published by O'Reilly. Now method ``item_search`` does several
+things at once for you: 
+
+1. It turns all your parameters into a validly signed URL and sends a request.
+2. The returned XML document is parsed and if it contains any error message,
+   the appropriate Python exception is raised (see :ref:`dealing-with-errors`). 
+3. Amazon itself provides their results spread over several pages. If you were
+   to do this manually you would have to make several calls. To make things
+   easier for you :meth:`item_search` will iterate over all availabe results
+   (see :ref:`pagination` for more information).
+
+.. _other locales available: http://docs.amazonwebservices.com/
+    AWSECommerceService/latest/DG/CHAP_LocaleConsiderations.html
+
+You can now iterate over the ``items`` and will get a number of parsed XML
+nodes (by default and if available `lxml.objectify`_ is used). With it you can
+access all elements and attributes in a Pythonic way::
     
     # get all books from result set and 
     # print author and title
-    for book in node.Items.Item:
+    for book in items:
         print '%s: "%s"' % (book.ItemAttributes.Author, 
                             book.ItemAttributes.Title)
 
-Please refer to the `lxml.objectify`_ documentation for more details.
+Please refer to the `lxml.objectify`_ documentation for more details. If you
+cannot/will not use lxml, see :ref:`pagination` for alternatives.
+
+You can find more API operations later in :ref:`operations`.
 
 .. _lxml.objectify: http://codespeak.net/lxml/objectify.html
-__ lxml.objectify_
 
 
+.. _dealing-with-errors:
+
 Dealing with errors
 -------------------
 
 
 A list of exceptions can be found in :ref:`error-handling`.
 
-
-More information on the API
----------------------------
-
-* Amazon Product Advertising API Best Practices: 
-  http://aws.amazon.com/articles/1057

docs/source/operations.rst

+
+.. _operations:
 
 Operations
 ==========
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.