Document suds client configuration

README

@@ -1,85 +1,97 @@
-Stamps.com API for Python
-
-
-The Idea
-========
-
-The goal of this API is to provide a thin Python wrapper around the Stamps.com
-Web Services API. As to why anyone would be generating big W-S APIs in the 21st
-century? Don't get me started.
-
-This API gives you a flexible configuration mechanism, calls for the more
-common operations, cached authenticator token, conversation out-of-sync
-detection, and examples as test cases.
-
-This API depends on Python "Suds" and exerts minimal opinion on the format or
-results of the Stamps.com operations. In other words, the naming conventions
-for Suds-based I/O are not Pythonic and are dictated, instead, by the backing
-WSDL. You'll probably want to extend the API here with your own so you can bury
-all of the weird syntax under your own version of awesomeness.
-
-
-The Installation
-================
-
-Simple with pip:
-
-$ pip install stamps.py
-
-Easy with setuptools (but you really shouldn't):
-
-$ easy_install stamps.py
-
-
-The Interface
-=============
-
-These and other public functions are documented in
-stamps.services.StampsService:
-
-add_postage
-    Add postage to your account so you can start creating labels.
-
-create_*
-    Convenience methods for creating various call objects. In general, these
-    will be bare objects that need to be populated with detail information
-    based on the call you wish to make. See the get_* functions in tests.py for
-    details.
-
-get_account
-    Account information accessor.
-
-get_label
-    Get a shipping label from one address to another based on a given rate.
-
-get_rates
-    Get the available rates for a given shipping object.
-
-get_tracking
-    Get the tracking events for a given label ID.
-
-register_account
-    Register a new account with Stamps.com.
-
-remove_label
-    Cancel a shipping label (triggers a postage refund with Stamps.com).
-
-
-The Instantiation
-=================
-
-The best way to get started is to digest the code in tests.py, which uses a
-file to initialize a test StampsConfiguration. Below is a simple example that
-uses the API to retrieve account information. Register with
-developer.stamps.com to get your own integration ID, username, and password.
-
-    from stamps.config import StampsConfiguration
-    from stamps.services import StampsService
-
-    integration_id = "XXXXXXXX-1111-2222-3333-YYYYYYYYYYYY"
-    username = "stampy"
-    password = "secret"
-    configuration = StampsConfiguration(integration_id=integration_id,
-        username=username, password=password)
-    service = StampsService(configuration=configuration)
-    account = service.get_account()
+Stamps.com API for Python
+
+
+The Idea
+========
+
+The goal of this API is to provide a thin Python wrapper around the Stamps.com
+Web Services API. As to why anyone would be generating big W-S APIs in the 21st
+century? Don't get me started.
+
+This API gives you a flexible configuration mechanism, calls for the more
+common operations, cached authenticator token, conversation out-of-sync
+detection, and examples as test cases.
+
+This API depends on Python "Suds" and exerts minimal opinion on the format or
+results of the Stamps.com operations. In other words, the naming conventions
+for Suds-based I/O are not Pythonic and are dictated, instead, by the backing
+WSDL. You'll probably want to extend the API here with your own so you can bury
+all of the weird syntax under your own version of awesomeness.
+
+
+The Installation
+================
+
+Simple with pip:
+
+$ pip install stamps.py
+
+Easy with setuptools (but you really shouldn't):
+
+$ easy_install stamps.py
+
+
+The Interface
+=============
+
+These and other public functions are documented in
+stamps.services.StampsService:
+
+add_postage
+    Add postage to your account so you can start creating labels.
+
+create_*
+    Convenience methods for creating various call objects. In general, these
+    will be bare objects that need to be populated with detail information
+    based on the call you wish to make. See the get_* functions in tests.py for
+    details.
+
+get_account
+    Account information accessor.
+
+get_label
+    Get a shipping label from one address to another based on a given rate.
+
+get_rates
+    Get the available rates for a given shipping object.
+
+get_tracking
+    Get the tracking events for a given label ID.
+
+register_account
+    Register a new account with Stamps.com.
+
+remove_label
+    Cancel a shipping label (triggers a postage refund with Stamps.com).
+
+
+The Instantiation
+=================
+
+The best way to get started is to digest the code in tests.py, which uses a
+file to initialize a test StampsConfiguration. Below is a simple example that
+uses the API to retrieve account information. Register with
+developer.stamps.com to get your own integration ID, username, and password.
+
+    from stamps.config import StampsConfiguration
+    from stamps.services import StampsService
+
+    integration_id = "XXXXXXXX-1111-2222-3333-YYYYYYYYYYYY"
+    username = "stampy"
+    password = "secret"
+    configuration = StampsConfiguration(integration_id=integration_id,
+        username=username, password=password)
+    service = StampsService(configuration=configuration)
+    account = service.get_account()
+
+
+Running behind proxy
+====================
+
+The suds client does not configure proxy information from environment variables automatically.
+The proxy configuration can be supplied explicitly as follows:
+
+    import urllib
+
+    service = StampsService(configuration=config)
+    service.client.set_options(proxy=urllib.getproxies())