Merge pull request garnaat#65 from alexharv074/Issue_64

Issue 64
Thanks for the improved docs.

README.md

@@ -13,29 +13,29 @@ of calls and save them to a data file and then replay those calls later
 Installation
 ------------
 
-```
+~~~
 $ pip install placebo
-```
+~~~
 
 Quickstart
 ----------
 
 Placebo uses the event mechanism in botocore to do most of its work. To start
 with, you need a boto3 Session object.
 
-```
+~~~ python
 import boto3
 import placebo
 
 session = boto3.Session()
-```
+~~~
 
 Once you have a Session object, you can tell placebo about the Session like
 this:
 
-```
+~~~ python
 pill = placebo.attach(session, data_path='/path/to/response/directory')
-```
+~~~
 
 The ``data_path`` is a path to a directory where you want responses to be stored
 or that contains previously recorded responses you want to playback.
@@ -47,36 +47,36 @@ created by this session object.
 The first thing you will probably want to do is record some requests. To do
 this, simply:
 
-```
+~~~ python
 pill.record()
-```
+~~~
 
 By default, the ``record`` method will cause all responses from all services to
 be recorded to the ``data_path``. If you are only interested in responses from
 one certain services, you can limit the recording by passing in a list of
 service names.
 
-```
+~~~ python
 pill.record(services='ec2,iam')
-```
+~~~
 
 This would limit to recording to responses from the ``ec2`` service and the
 ``iam`` service. If you want to restrict recording to only certain operations
 in a single service, you can do this:
 
-```
+~~~ python
 pill.record(services='ec2', operations='DescribeInstances,DescribeKeyPairs')
-```
+~~~
 
 From this point on, any clients that match the recording specification and are
 created from the session will be placebo-aware. To record responses, just
 create the client and use it as you normally would.
 
-```
+~~~ python
 lambda = session.client('lambda')
 lambda.list_functions()
 ... more lambda calls ...
-```
+~~~
 
 Each response will be saved as an individual JSON data file in the ``data_path``
 path you specified when you attached the session. Multiple responses from the
@@ -85,7 +85,7 @@ the same order on playback.
 
 Later, to replay saved requests:
 
-```
+~~~ python
 import boto3
 import placebo
 
@@ -95,13 +95,42 @@ pill.playback()
 lambda = session.client('lambda')
 lambda.list_functions()
 ... mocked response will be returned
-```
+~~~
+
+#### Attaching to the default session
+
+Sometimes, Placebo needs to be attached to the Boto3 [default session](https://boto3.readthedocs.io/en/latest/guide/session.html#default-session)
+object.
+
+To attach Placebo to the default session, it is necessary to explicitly set up
+the default session by making a call to `boto3.setup_default_session()`. The
+default session is then accessible at `boto3.DEFAULT_SESSION`.
+
+For example:
+
+~~~ python
+import boto3
+import placebo
+
+# Explicity set up the default session and attach Placebo to it.
+boto3.setup_default_session()
+session = boto3.DEFAULT_SESSION
+pill = placebo.attach(session, data_path='/path/to/response/directory')
+pill.record()
+
+# Now make Boto3 calls using the default session.
+client = boto3.client('ec2')
+client.describe_images(DryRun=False)
+~~~
+
+This is particularly useful if you are writing tests for legacy code that
+makes use of the Boto3 default session.
 
 #### Manual Mocking
 
 You can also add mocked responses manually:
 
-```
+~~~ python
 list_functions_response = [
  {
  "Version": "$LATEST",
@@ -120,7 +149,7 @@ list_functions_response = [
 
 pill.save_response(service='lambda', operation='ListFunctions',
  response_data=list_functions_response, http_response=200)
-```
+~~~
 
 You can add additional responses to a particular operation and the responses
 will be returned in order. The final parameter is the HTTP response code which
@@ -131,34 +160,34 @@ is optional. The default value is 200.
 Placebo also provides a decorator for easier usage.
 
 First, you'll want to decorate your test method with `placebo_session` and include the `session` kwarg in your method, ex:
-```python
+~~~ python
 @placebo_session
 def test_your_function(self, session):
  foo = Foo()
  arn = foo.create_iam_roles(session)
  self.assertEqual(arn, "arn:aws:iam::123:role/{}".format(foo.role_name))
-```
+~~~
 
 Now, you'll be able to record the AWS interactions with an environment variable:
-```bash
+~~~ bash
 $ PLACEBO_MODE=record nosetests tests.tests:TestFoo.test_create_iam_roles
-```
+~~~
 
 You can optionally pass an AWS profile to use:
-```bash
+~~~ bash
 $ PLACEBO_PROFILE=foo PLACEBO_MODE=record nosetests tests.tests:TestFoo.test_create_iam_roles
-```
+~~~
 
 In this example, it has created the following JSON blobs:
-```bash
+~~~
 tests/placebo/TestFoo.test_create_iam_roles
 tests/placebo/TestFoo.test_create_iam_roles/iam.CreateRole_1.json
 tests/placebo/TestFoo.test_create_iam_roles/iam.GetRole_1.json
 tests/placebo/TestFoo.test_create_iam_roles/iam.GetRolePolicy_1.json
 tests/placebo/TestFoo.test_create_iam_roles/iam.PutRolePolicy_1.json
-```
+~~~
 
 After the JSON has been created, simply drop the environment variables and re-run your test:
-```bash
+~~~ bash
 $ nosetests tests.tests:TestFoo.test_create_iam_roles
-```
+~~~