Commits

Sebastian Rahlf committed 71eeead

Moved documentation about configuration options out of tutorial. Again.

  • Participants
  • Parent commits 306a98a

Comments (0)

Files changed (3)

File docs/source/basic-usage.rst

 *AWSAccessKeyId* and a *SecretKey*. As of API version 2011-08-01 you will also
 need to `register for an AssociateTag`_.
 
-.. _register with Amazon: https://affiliate-program.amazon.com/gp/advertising/api/detail/your-account.html
+
+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
+following content into it::
+
+    [Credentials]
+    access_key = <your access key>
+    secret_key = <your secret key>
+    associate_tag = <your associate id>
+
+Of course, you'll need to fill in the appropriate values! More information on
+how to configure the module can be found :ref:`later on <config>`.
+
+.. _register with Amazon: https://affiliate-program.amazon.com/gp/advertising/
+    api/detail/your-account.html
 .. _register for an AssociateTag: https://affiliate-program.amazon.com/
 
+
+Your first API request
+----------------------
+
 Here is an example how to use the API to search for books of a certain 
-publisher. Of course, you'll need to replace ``AWS_KEY``, ``SECRET_KEY`` and
-``ASSOCIATE_TAG`` with the appropriate values! ::
+publisher.  ::
 
-    AWS_KEY = '...'
-    SECRET_KEY = '...'
-    ASSOCIATE_TAG = 'mytag-12'
-    
-    api = API(AWS_KEY, SECRET_KEY, 'us', ASSOCIATE_TAG)
-    node = api.item_search('Books', Publisher='Galileo Press')
+    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::
 A list of exceptions can be found in :ref:`error-handling`.
 
 
-.. _config:
-
-Configuration
--------------
-
-.. versionadded:: 0.2.6
-
-There is a growing list of configuration options for the library, many of which
-can be passed directly to the API constructor at initialisation. Some options,
-such as credentials, can also be read from environment variables (e.g.
-``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY``).
-
-The order of precedence for is always:
-
-* Parameters passed into Connection class constructor.
-* Parameters specified by environment variables
-* Parameters specified as options in the config file.
-
-The following table gives an overview which values can be defined where:
-
-=============  ======================  =====================
-config file    boto config             environment variable
-=============  ======================  =====================
-access_key     aws_access_key_id       AWS_ACCESS_KEY_ID
-secret_key     aws_secret_access_key   AWS_SECRET_ACCESS_KEY
-associate_tag                          AWS_ASSOCIATE_TAG
-locale                                 AWS_LOCALE
-=============  ======================  =====================
-
-
-Config files
-~~~~~~~~~~~~
-
-Upon initialisation, the API looks for configuration files (similar to the
-`boto config`_, where I have borrowed the idea from) in the following
-locations and in the following order:
-
-* any `boto config`_ files ``/etc/boto.cfg`` and ``~/.boto``
-* ``/etc/amazon-product-api.cfg`` for site-wide settings that all users on
-  this machine will use
-* ``~/.amazon-product-api`` for user-specific settings
-
-The options are merged into a single, in-memory configuration that is available.
-Files from this wrapper will always take precedence over boto config files!
-
-The following sections and options are currently recognized within the config
-file.
-
-``Credentials``
-    The Credentials section is used to specify the AWS credentials used for
-    all requests.
-
-
-    ``access_key``
-        Your AWS access key
-
-    ``secret_key``
-        Your AWS secret access key
-
-    ``associate_tag``
-        Your AWS associate ID
-
-    Example::
-
-        [Credentials]
-        access_key = <your access key>
-        secret_key = <your secret key>
-        associate_tag = <your associate id>
-
-.. _boto config: http://code.google.com/p/boto/wiki/BotoConfig
-
-
-Environment variables
-~~~~~~~~~~~~~~~~~~~~~
-
-You can also set the following environment variables:
-
-``AWS_ACCESS_KEY_ID``
-    Your AWS access key
-
-``AWS_SECRET_ACCESS_KEY``
-    Your AWS secret access key
-
-``AWS_ASSOCIATE_TAG``
-    Your AWS associate ID
-
-``AWS_LOCALE``
-    Your API locale
-
-
 More information on the API
 ---------------------------
 

File docs/source/config.rst

+
+.. _config:
+
+Configuration
+=============
+
+.. versionadded:: 0.2.6
+
+There is a growing list of configuration options for the library, many of which
+can be passed directly to the API constructor at initialisation. Some options,
+such as credentials, can also be read from environment variables (e.g.
+``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY``).
+
+The order of precedence for is always:
+
+* Parameters passed into Connection class constructor.
+* Parameters specified by environment variables
+* Parameters specified as options in the config file.
+
+The following table gives an overview which values can be defined where:
+
+=============  ======================  =====================
+config file    boto config             environment variable
+=============  ======================  =====================
+access_key     aws_access_key_id       AWS_ACCESS_KEY_ID
+secret_key     aws_secret_access_key   AWS_SECRET_ACCESS_KEY
+associate_tag                          AWS_ASSOCIATE_TAG
+locale                                 AWS_LOCALE
+=============  ======================  =====================
+
+
+Config files
+------------
+
+Upon initialisation, the API looks for configuration files (similar to the
+`boto config`_, where I have borrowed the idea from) in the following
+locations and in the following order:
+
+* any `boto config`_ files ``/etc/boto.cfg`` and ``~/.boto``
+* ``/etc/amazon-product-api.cfg`` for site-wide settings that all users on
+  this machine will use
+* ``~/.amazon-product-api`` for user-specific settings
+
+The options are merged into a single, in-memory configuration that is available.
+Files from this wrapper will always take precedence over boto config files!
+
+The following sections and options are currently recognized within the config
+file.
+
+``Credentials``
+    The Credentials section is used to specify the AWS credentials used for
+    all requests.
+
+
+    ``access_key``
+        Your AWS access key
+
+    ``secret_key``
+        Your AWS secret access key
+
+    ``associate_tag``
+        Your AWS associate ID
+
+    Example::
+
+        [Credentials]
+        access_key = <your access key>
+        secret_key = <your secret key>
+        associate_tag = <your associate id>
+
+.. _boto config: http://code.google.com/p/boto/wiki/BotoConfig
+
+
+Environment variables
+---------------------
+
+You can also set the following environment variables:
+
+``AWS_ACCESS_KEY_ID``
+    Your AWS access key
+
+``AWS_SECRET_ACCESS_KEY``
+    Your AWS secret access key
+
+``AWS_ASSOCIATE_TAG``
+    Your AWS associate ID
+
+``AWS_LOCALE``
+    Your API locale
+
+

File docs/source/index.rst

    basic-usage
    operations
    errors
+   config
    advanced
    faq
    contributing