third_party/boto/core/README

What's This All About?
======================

This directory contains the beginnings of what is hoped will be the
new core of boto.  We want to move from using httplib to using
requests.  We also want to offer full support for Python 2.6, 2.7, and
3.x.  This is a pretty big change and will require some time to roll
out but this module provides a starting point.

What you will find in this module:

* auth.py provides a SigV2 authentication packages as a args hook for requests.
* credentials.py provides a way of finding AWS credentials (see below).
* dictresponse.py provides a generic response handler that parses XML responses
  and returns them as nested Python data structures.
* service.py provides a simple example of a service that actually makes an EC2
  request and returns a response.

Credentials
===========

Credentials are being handled a bit differently here.  The following
describes the order of search for credentials:

1. If your local environment for has ACCESS_KEY and SECRET_KEY variables
   defined, these will be used.

2. If your local environment has AWS_CREDENTIAL_FILE defined, it is assumed
   that it will be a config file with entries like this:

   [default]
   access_key = xxxxxxxxxxxxxxxx
   sercret_key = xxxxxxxxxxxxxxxxxx

   [test]
   access_key = yyyyyyyyyyyyyy
   secret_key = yyyyyyyyyyyyyyyyyy

   Each section in the config file is called a persona and you can reference
   a particular persona by name when instantiating a Service class.

3. If a standard boto config file is found that contains credentials, those
   will be used.

4. If temporary credentials for an IAM Role are found in the instance
   metadata of an EC2 instance, these credentials will be used.

Trying Things Out
=================
To try this code out, cd to the directory containing the core module.

    >>> import core.service
    >>> s = core.service.Service()
    >>> s.describe_instances()

This code should return a Python data structure containing information
about your currently running EC2 instances.  This example should run in
Python 2.6.x, 2.7.x and Python 3.x.