Update Readme

Mostly this updates the `Url` model documentation to reflect its more pythonic nature as a true dictionary.
Also update a couple links, don't use `sudo` and fix the RST formatting for a few code blocks.

Author: joncotton

README.rst

@@ -1,51 +1,55 @@
 embedly-python
 ==============
-Python Library for interacting with Embedly's API. To get started sign up for
-a key at `embed.ly/signup <http://embed.ly/signup>`_.
+Python library for interacting with Embedly's API. To get started sign up for
+a key at `embed.ly/signup <https://app.embed.ly/signup>`_.
 
 Install
 -------
 Install with `Pip <http://www.pip-installer.org>`_ (recommended)::
 
   pip install embedly
 
-Or easy_install
+Or easy_install::
 
-  sudo easy_install Embedly
+  easy_install Embedly
 
 Or setuptools::
 
   git clone git://github.com/embedly/embedly-python.git
-  sudo python setup.py
+  python setup.py
 
 
 Getting Started
 ---------------
 This library is meant to be a dead simple way to interact with the Embedly API.
-There are only 2 main objects, the ``Embedly`` client and the ``Url`` model.
-Here is a simple example and then we will go into the objects::
+There are only 2 main objects, the ``Embedly`` client and the ``Url`` response
+model. Here is a simple example and then we will go into the objects::
 
   >>> from embedly import Embedly
   >>> client = Embedly(:key)
-  >>> obj = client.oembed('http://instagr.am/p/BL7ti/')
+  >>> obj = client.oembed('http://instagram.com/p/BL7ti/')
   >>> obj['type']
   u'photo'
   >>> obj['url']
-  u'http://distillery.s3.amazonaws.com/media/2011/01/24/cdd759a319184cb79793506607ff5746_7.jpg'
+  u'http://images.ak.instagram.com/media/2011/01/24/cdd759a319184cb79793506607ff5746_7.jpg'
 
-  >>> obj = client.oembed('http://instagr.am/p/error')
+  >>> obj = client.oembed('http://instagram.com/error/error/')
   >>> obj['error']
   True
 
 Embedly Client
 """"""""""""""
-The Embedly client is a object that takes in a key and an optional User Agent
-then handles all the interactions and HTTP requests to Embedly. To initialize
-the object pass in your key you got from signing up for Embedly and an optional
-User Agent.
+The Embedly client is a object that takes in a key and optional User Agent
+and timeout parameters then handles all the interactions and HTTP requests
+to Embedly. To initialize the object, you'll need the key that you got when
+you signed up for Embedly.
+::
 
   >>> from embedly import Embedly
-  >>> client = Embedly('key', 'Mozilla/5.0 (compatible; example-org;)')
+  >>> client = Embedly('key')
+  >>> client2 = Embedly('key', 'Mozilla/5.0 (compatible; example-org;)')
+  >>> client3 = Embedly('key', 'Mozilla/5.0 (compatible; example-org;)', 30)
+  >>> client4 = Embedly('key', timeout=10, user_agent='Mozilla/5.0 (compatible; example-org;)')
 
 The client object now has a bunch of different methods that you can use.
 
@@ -92,7 +96,7 @@ keyword arguments that correspond to Embedly's `query arguments
   >>> client.oembed(['http://vimeo.com/18150336',
     'http://www.youtube.com/watch?v=hD7ydlyhvKs'], maxwidth=500, words=20)
 
-There are some supporting functions that allow you to limit urls before sending
+There are some supporting functions that allow you to limit URLs before sending
 them to Embedly. Embedly can return metadata for any URL, these just allow a
 developer to only pass a subset of Embedly `providers
 <http://embed.ly/providers>`_. Note that URL shorteners like bit.ly or t.co are
@@ -116,43 +120,60 @@ not supported through these regexes.
 
 Url Object
 """"""""""
-The ``Url`` Object is just a smart dictionary that acts more like an object.
-For example when you run ``oembed`` you get back a Url Object:
+The ``Url`` object is basically a response dictionary returned from
+one of the Embedly API endpoints.
+::
 
-  >>> obj = client.oembed('http://vimeo.com/18150336', words=10)
+  >>> response = client.oembed('http://vimeo.com/18150336', words=10)
 
-Depending on the method you are using, the object has a different set of
+Depending on the method you are using, the response will have different
 attributes. We will go through a few, but you should read the `documentation
-<http://embed.ly/docs>`_ to get the full list of data that is passed back.::
+<http://embed.ly/docs>`_ to get the full list of data that is passed back.
+::
 
-  # Url Object can be accessed like a dictionary
-  >>> obj['type']
+  >>> response['type']
   u'video'
+  >>> response['title']
+  u'Wingsuit Basejumping - The Need 4 Speed: The Art of Flight'
+  >>> response['provider_name']
+  u'Vimeo'
+  >>> response['width']
+  1280
+
+As you can see the ``Url`` object works like a dictionary, but it's slightly
+enhanced. It will always have ``method`` and ``original_url`` attributes,
+which represent the Embedly request type and the URL requested.
+::
+
+  >>> response.method
+  'oembed'
+  >>> response.original_url
+  'http://vimeo.com/18150336'
 
-  # The url object always has an ``original_url`` attrbiute.
-  >>> obj.original_url
-  u'http://vimeo.com/18150336'
-  # The method used to retrieve the URL is also on the obj
-  >>> obj.method
-  u'oembed'
+  # useful because the response data itself may not have a URL
+  # (or it could have a redirected link, querystring params, etc)
+  >>> response['url']
+  ...
+  KeyError: 'url'
 
-For the Preview and Objectify endpoints the sub objects can also be accessed in
+For the Preview and Objectify endpoints the sub-objects can also be accessed in
 the same manner.
+::
 
   >>> obj = client.preview('http://vimeo.com/18150336', words=10)
   >>> obj['object']['type']
   u'video'
-  >>> obj['images'][0].url
+  >>> obj['images'][0]['url']
   u'http://b.vimeocdn.com/ts/117/311/117311910_1280.jpg'
 
 Error Handling
 --------------
-If there was an error processing the request, The ``Url`` object will contain
+If there was an error processing the request, the ``Url`` object will contain
 an error. For example if we use an invalid key, we will get a 401 response back
 ::
 
   >>> client = Embedly('notakey')
-  >>> obj = client.preview('http://vimeo.com/18150336', words=10)
+  >>> obj = client.preview('http://vimeo.com/18150336')
   >>> obj['error']
   True
   >>> obj['error_code']