From ff1976e27b9aa7354e201239468fdad6aa9a3f0d Mon Sep 17 00:00:00 2001
From: Rossen Georgiev <rossen@rgp.io>
Date: Sun, 21 Feb 2016 17:28:30 +0000
Subject: [PATCH] WebAPI: now gevent cooperative + updated docs

---
 docs/api/steam.rst         | 25 ++--------------
 docs/api/steam.steamid.rst |  7 +++++
 docs/api/steam.webapi.rst  |  9 ++++++
 steam/webapi.py            | 60 +++++++++++++++++++++++++++++---------
 4 files changed, 64 insertions(+), 37 deletions(-)
 create mode 100644 docs/api/steam.steamid.rst
 create mode 100644 docs/api/steam.webapi.rst

diff --git a/docs/api/steam.rst b/docs/api/steam.rst
index 0004786..fa2876f 100644
--- a/docs/api/steam.rst
+++ b/docs/api/steam.rst
@@ -5,27 +5,6 @@ steam
     steam.client
     steam.core
     steam.enums
+    steam.steamid
     steam.util
-
-.. automodule:: steam
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-steam.steamid
--------------
-
-.. automodule:: steam.steamid
-    :members: SteamID, from_url, steam64_from_url, steam2_to_tuple, steam3_to_tuple
-    :undoc-members:
-    :show-inheritance:
-
-steam.webapi
-------------
-
-.. automodule:: steam.webapi
-    :members: WebAPI
-    :undoc-members:
-    :show-inheritance:
-
-
+    steam.webapi
diff --git a/docs/api/steam.steamid.rst b/docs/api/steam.steamid.rst
new file mode 100644
index 0000000..2d9e214
--- /dev/null
+++ b/docs/api/steam.steamid.rst
@@ -0,0 +1,7 @@
+steam.steamid
+=============
+
+.. automodule:: steam.steamid
+    :members: SteamID, from_url, steam64_from_url, steam2_to_tuple, steam3_to_tuple
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/steam.webapi.rst b/docs/api/steam.webapi.rst
new file mode 100644
index 0000000..06b0cad
--- /dev/null
+++ b/docs/api/steam.webapi.rst
@@ -0,0 +1,9 @@
+steam.webapi
+============
+
+.. automodule:: steam.webapi
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
diff --git a/steam/webapi.py b/steam/webapi.py
index 9b95882..553ea12 100644
--- a/steam/webapi.py
+++ b/steam/webapi.py
@@ -1,5 +1,34 @@
+"""
+WebAPI provides a thin gevent cooperative wrapper over Steam's WebAPI
+
+Calling an endpoint
+
+.. code:: python
+
+    >>> api = WebAPI(key)
+    >>> api.ISteamUser.ResolveVanityURL(vanityurl="valve", url_type=2)
+    >>> api.call('ISteamUser.ResolveVanityURL', vanityurl="valve", url_type=2)
+    {u'response': {u'steamid': u'103582791429521412', u'success': 1}}
+
+All globals params (``key``, ``https``, ``format``, ``raw``) can be specified on per call basis.
+
+.. code:: python
+
+    >>> print a.ISteamUser.ResolveVanityURL(format='vdf', raw=True, vanityurl="valve", url_type=2)
+    "response"
+    {
+            "steamid"       "103582791429521412"
+            "success"       "1"
+    }
+"""
 from __future__ import print_function
 import requests
+import gevent.monkey
+gevent.monkey.patch_socket()
+gevent.monkey.patch_ssl()
+
+session = requests.Session()
+session.mount('any', requests.adapters.HTTPAdapter())
 
 DEFAULT_PARAMS = {
     # api parameters
@@ -15,6 +44,16 @@ DEFAULT_PARAMS = {
 def webapi_request(path, method='GET', caller=None, params={}):
     """
     Low level function for calling Steam's WebAPI
+
+    :param path: request url
+    :type path: :class:`str`
+    :param method: HTTP method (GET or POST)
+    :type method: :class:`str`
+    :param caller: caller reference, caller.last_response is set to the last response
+    :param params: dict of WebAPI and endpoint specific params
+    :type params: :class:`dict`
+    :return: response based on paramers
+    :rtype: :class:`dict`, :class:`lxml.etree.Element`, :class:`str`
     """
     if method not in ('GET', 'POST'):
         raise NotImplemented("HTTP method: %s" % repr(self.method))
@@ -37,23 +76,25 @@ def webapi_request(path, method='GET', caller=None, params={}):
     # simplifies code calling this method
     kwargs = {'params': params} if method == "GET" else {'data': params}
 
-    f = getattr(requests, method.lower())
+    f = getattr(session, method.lower())
     resp = f(path, stream=False, timeout=onetime['http_timeout'], **kwargs)
 
+    # we keep a reference of the last response instance on the caller
     if caller is not None:
         caller.last_response = resp
 
-    if not resp.ok:
-        raise requests.exceptions.HTTPError("%s %s" % (resp.status_code, resp.reason))
+    # 4XX and 5XX will cause this to raise
+    resp.raise_for_status()
 
+    # response
     if onetime['raw']:
-        return resp.content
+        return resp.text
 
     if onetime['format'] == 'json':
         return resp.json()
     elif onetime['format'] == 'xml':
         import lxml.etree
-        return lxml.etree.parse(resp.raw)
+        return lxml.etree.fromstring(resp.content)
     elif onetime['format'] == 'vdf':
         import vdf
         return vdf.loads(resp.text)
@@ -78,15 +119,6 @@ class WebAPI(object):
     :type auto_load_interfaces: bool
 
     These can be specified per method call for one off calls
-
-    Example usage:
-
-    .. code:: python
-
-        >>> api = WebAPI(key)
-        >>> api.ISteamUser.ResolveVanityURL(vanityurl="valve", url_type=2)
-        >>> api.call('ISteamUser.ResolveVanityURL', vanityurl="valve", url_type=2)
-        {u'response': {u'steamid': u'103582791429521412', u'success': 1}}
     """
 
     def __init__(self, key, format='json', raw=False, https=True, http_timeout=30, auto_load_interfaces=True):