updated docstring in preperation for sphinx

steam/__init__.py

@@ -1,4 +1,5 @@
-__version__ = "0.5.4"
+version_info = (0, 6, 0, 'alpha')
+__version__ = "0.6.0a"
 __author__ = "Rossen Georgiev"
 
 from steam.steamid import SteamID

steam/enums/__init__.py

@@ -1 +1,23 @@
+"""This module contains various value enumerations.
+
+They are all based on :py:class:`IntEnum`, which gives them :py:class:`int` properties.
+They can be compared to :py:class:`int` and used in places there :py:class:`int` is required.
+Like for example, protobuf message.
+They also provide a easy way to resolve a name or value for a specific enum.
+
+.. code:: python
+
+    >>> EResult.OK
+    <EResult.OK: 1>
+    >>> EResult(1)
+    <EResult.OK: 1>
+    >>> EResult['OK']
+    <EResult.OK: 1>
+    >>> EResult.OK == 1
+    True
+
+.. note::
+    all enums from :py:mod:`steam.enum.common` can be imported directly from :py:mod:`steam.enum`
+"""
+
 from steam.enums.common import EResult, EType, EUniverse, EServerType

steam/enums/emsg.py

@@ -1,3 +1,7 @@
+"""The EMsg enum contains many members and takes a bit to load.
+For this reason it is seperate, and imported only when needed.
+"""
+
 from steam.enums.base import SteamIntEnum
 
 

steam/steamid.py

@@ -26,16 +26,7 @@ class SteamID(int):
     """
     Object for converting steamID to its' various representations
 
-    (immutable)
+    .. code:: python
-    """
-
-    def __new__(cls, *args, **kwargs):
-        steam64 = make_steam64(*args, **kwargs)
-        return super(SteamID, cls).__new__(cls, steam64)
-
-    def __init__(self, *args, **kwargs):
-        """
-        The instance can be initialized with various parameters
 
         SteamID()  # invalid steamid
         SteamID(12345)  # accountid
@@ -45,11 +36,13 @@ class SteamID(int):
         SteamID('103582791429521412')
         SteamID('STEAM_1:0:2')  # steam2
         SteamID('[g:1:4]')  # steam3
+    """
 
-        To create a SteamID from a community url use:
+    def __new__(cls, *args, **kwargs):
+        steam64 = make_steam64(*args, **kwargs)
+        return super(SteamID, cls).__new__(cls, steam64)
 
-        steam.steamid.from_url()
+    def __init__(self, *args, **kwargs):
-        """
         pass
 
     def __repr__(self):
@@ -63,30 +56,55 @@ class SteamID(int):
 
     @property
     def id(self):
+        """
+        :return: account id
+        :rtype: int
+        """
         return int(self) & 0xFFffFFff
 
     @property
     def instance(self):
+        """
+        :rtype: int
+        """
         return (int(self) >> 32) & 0xFFffF
 
     @property
     def type(self):
+        """
+        :rtype: :py:class:`steam.enum.EType`
+        """
         return EType((int(self) >> 52) & 0xF)
 
     @property
     def universe(self):
+        """
+        :rtype: :py:class:`steam.enum.EUniverse`
+        """
         return EUniverse((int(self) >> 56) & 0xFF)
 
     @property
     def as_32(self):
+        """
+        :return: account id
+        :rtype: int
+        """
         return self.id
 
     @property
     def as_64(self):
+        """
+        :return: steam64 format
+        :rtype: int
+        """
         return int(self)
 
     @property
     def as_steam2(self):
+        """
+        :return: steam2 format (e.g ``STEAM_0:0:1234``)
+        :rtype: str
+        """
         return "STEAM_0:%s:%s" % (
             self.id % 2,
             self.id >> 1,
@@ -94,6 +112,10 @@ class SteamID(int):
 
     @property
     def as_steam3(self):
+        """
+        :return: steam3 format (e.g ``[U:1:1234]``)
+        :rtype: str
+        """
         if self.type is EType.AnonGameServer:
             return "[%s:%s:%s:%s]" % (
                 str(ETypeChar(self.type)),
@@ -110,6 +132,10 @@ class SteamID(int):
 
     @property
     def community_url(self):
+        """
+        :return: e.g https://steamcommunity.com/profiles/123456789
+        :rtype: str
+        """
         suffix = {
             EType.Individual: "profiles/%s",
             EType.Clan: "gid/%s",
@@ -121,6 +147,9 @@ class SteamID(int):
         return None
 
     def is_valid(self):
+        """
+        :rtype: :py:class:`bool`
+        """
         return (self.id > 0
                 and self.type is not EType.Invalid
                 and self.universe is not EUniverse.Invalid
@@ -131,14 +160,16 @@ def make_steam64(id=0, *args, **kwargs):
         """
         Returns steam64 from various other representations.
 
-        make_steam64()  # invalid steamid
+        .. code:: python
-        make_steam64(12345)  # accountid
+
-        make_steam64('12345')
+            make_steam64()  # invalid steamid
-        make_steam64(id=12345, type='Invalid', universe='Invalid', instance=0)
+            make_steam64(12345)  # accountid
-        make_steam64(103582791429521412)  # steam64
+            make_steam64('12345')
-        make_steam64('103582791429521412')
+            make_steam64(id=12345, type='Invalid', universe='Invalid', instance=0)
-        make_steam64('STEAM_1:0:2')  # steam2
+            make_steam64(103582791429521412)  # steam64
-        make_steam64('[g:1:4]')  # steam3
+            make_steam64('103582791429521412')
+            make_steam64('STEAM_1:0:2')  # steam2
+            make_steam64('[g:1:4]')  # steam3
         """
 
         accountid = id
@@ -210,6 +241,12 @@ def make_steam64(id=0, *args, **kwargs):
 
 
 def steam2_to_tuple(value):
+    """
+    :param value: steam2 (e.g. ``STEAM_0:0:1234``)
+    :type value: str
+    :return: (accountid, type, universe, instance)
+    :rtype: ``tuple`` or ``None``
+    """
     match = re.match(r"^STEAM_(?P<universe>[01])"
                      r":(?P<reminder>[0-1])"
                      r":(?P<id>\d+)$", value
@@ -224,6 +261,12 @@ def steam2_to_tuple(value):
 
 
 def steam3_to_tuple(value):
+    """
+    :param value: steam3 (e.g. ``[U:1:1234]``)
+    :type value: str
+    :return: (accountid, type, universe, instance)
+    :rtype: ``tuple`` or ``None``
+    """
     match = re.match(r"^\["
                      r"(?P<type>[%s]):"        # type char
                      r"(?P<universe>\d+):"     # universe
@@ -254,14 +297,19 @@ def steam64_from_url(url):
     """
     Takes a Steam Community url and returns steam64 or None
 
-    Example URLs:
+    :param url: steam community url
-    ----
+    :type url: str
-    https://steamcommunity.com/gid/[g:1:4]
+    :return: steam64
-    https://steamcommunity.com/gid/103582791429521412
+    :rtype: ``int`` or ``None``
-    https://steamcommunity.com/groups/Valve
+
-    https://steamcommunity.com/profiles/[U:1:12]
+    Example URLs::
-    https://steamcommunity.com/profiles/76561197960265740
+
-    https://steamcommunity.com/id/johnc
+        https://steamcommunity.com/gid/[g:1:4]
+        https://steamcommunity.com/gid/103582791429521412
+        https://steamcommunity.com/groups/Valve
+        https://steamcommunity.com/profiles/[U:1:12]
+        https://steamcommunity.com/profiles/76561197960265740
+        https://steamcommunity.com/id/johnc
     """
 
     match = re.match(r'^https?://steamcommunity.com/'
@@ -289,14 +337,12 @@ def from_url(url):
     """
     Takes Steam community url and returns a SteamID instance or None
 
-    Example URLs:
+    :param url: steam community url
-    ----
+    :type url: str
-    https://steamcommunity.com/gid/[g:1:4]
+    :return: `SteamID` instance
-    https://steamcommunity.com/gid/103582791429521412
+    :rtype: :py:class:`steam.SteamID` or ``None``
-    https://steamcommunity.com/groups/Valve
+
-    https://steamcommunity.com/profiles/[U:1:12]
+    See :py:func:`steam64_from_url`
-    https://steamcommunity.com/profiles/76561197960265740
-    https://steamcommunity.com/id/johnc
     """
 
     steam64 = steam64_from_url(url)

steam/util/__init__.py

@@ -1,23 +1,56 @@
+"""Utility package with various useful functions
+"""
+
 import struct
 import socket
 
-
 def ip_from_int(ip):
+    """Convert IP to :py:class:`int`
+
+    :param ip: IP in dot-decimal notation
+    :type ip: str
+    :rtype: int
+    """
     return socket.inet_ntoa(struct.pack(">L", ip))
 
 def ip_to_int(ip):
+    """Convert :py:class:`int` to IP
+
+    :param ip: int representing an IP
+    :type ip: int
+    :return: IP in dot-decimal notation
+    :rtype: str
+    """
     return struct.unpack(">L", socket.inet_aton(ip))[0]
 
 
 protobuf_mask = 0x80000000
 
 def is_proto(emsg):
+    """
+    :param emsg: emsg number
+    :type emsg: int
+    :return: True or False
+    :rtype: bool
+    """
     return (int(emsg) & protobuf_mask) > 0
 
 def set_proto_bit(emsg):
+    """
+    :param emsg: emsg number
+    :type emsg: int
+    :return: emsg with proto bit set
+    :rtype: int
+    """
     return int(emsg) | protobuf_mask
 
 def clear_proto_bit(emsg):
+    """
+    :param emsg: emsg number
+    :type emsg: int
+    :return: emsg with proto bit removed
+    :rtype: int
+    """
     return int(emsg) & ~protobuf_mask
 
 

steam/util/events.py

@@ -5,12 +5,22 @@ from gevent.event import AsyncResult
 
 class EventEmitter(object):
     """
-    Implements event emitter using gevent library
+    Implements event emitter using ``gevent`` module.
+    Other modules can inherit from this object.
+
+    .. code:: python
+
+        class SomeClass(EventEmitter):
+            pass
+
     """
 
     def emit(self, event, *args):
         """
         Emit event with some arguments
+
+        :type event: any
+        :param args: any or no arguments
         """
 
         gevent.idle()
@@ -36,7 +46,11 @@ class EventEmitter(object):
 
     def remove_listener(self, event, callback):
         """
-        Removes a callback for the specified event
+        Removes callback for the specified event
+
+        :param event: event identifier
+        :param callback: callback reference
+        :type callback: function, method or :py:class:`gevent.event.AsyncResult`
         """
 
         if not hasattr(self, '_event_callbacks'):
@@ -47,6 +61,13 @@ class EventEmitter(object):
     def wait_event(self, event, timeout=None):
         """
         Blocks until an event and returns the results
+
+        :param event: event identifier
+        :param timeout: seconds to wait before raising an exception
+        :type timeout: int
+        :return: returns event arguments, if any. If there are many, returns tuple.
+        :rtype: None, any, or tuple
+        :raises: gevent.Timeout
         """
         result = AsyncResult()
         self.on(event, result)
@@ -56,7 +77,20 @@ class EventEmitter(object):
         """
         Registers a callback for the specified event
 
+        :param event: event name
+        :param callback: callback function
+
         Can be as function decorator if only event is specified.
+
+        .. code:: python
+
+            @instaceOfSomeClass.on("some event")
+            def handle_event():
+                pass
+
+            instaceOfSomeClass.on("some event", handle_event)
+
+        To listen for any event, use :py:class:`None` as event identifier.
         """
 
         if not hasattr(self, '_event_callbacks'):

steam/webapi.py

@@ -61,27 +61,35 @@ def webapi_request(path, method='GET', caller=None, params={}):
 
 class WebAPI(object):
     """
-    Steam Web API wrapper
+    Steam WebAPI wrapper. See https://developer.valvesoftware.com/wiki/Steam_Web_API
 
-    Interfaces and methods are populated upon init based on
+    .. note::
-    response of available such from the API.
+        Interfaces and methods are populated automatically from WebAPI.
 
-    More: https://developer.valvesoftware.com/wiki/Steam_Web_API
+    :param key: api key from https://steamcommunity.com/dev/apikey
-    """
+    :type key: str
+    :param format: response format, either (``json``, ``vdf``, or ``xml``)
+    :type format: str
+    :param raw: return raw response
+    :type raw: bool
+    :param https: use ``https``
+    :type https: bool
+    :param auto_load_interfaces: load interfaces from the WebAPI
+    :type auto_load_interfaces: bool
 
-    def __init__(self, key, format='json', raw=False, https=True, http_timeout=30, auto_load_interfaces=True):
+    These can be specified per method call for one off calls
-        """
-        Optain apikey at https://steamcommunity.com/dev/apikey
 
-        key                   - apikey
+    Example usage:
-        format                - output format (json, vdf, xml)
-        raw                   - whenver to deserialize the response
-        https                 - whenever to use https or not
-        auto_load_interfaces  - should we load interfaces upon initialization
 
-        These can be specified per method call for one off calls
+    .. 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):
         self.key = key
         self.format = format
         self.raw = raw
@@ -101,10 +109,11 @@ class WebAPI(object):
 
     def fetch_interfaces(self):
         """
-        Returns a dict with the response from GetSupportedAPIList
+        Returns a dict with the response from ``GetSupportedAPIList``
 
-        This is then feeded into WebAPI.load_interfaces(reponse)
+        :return: ``dict`` of all interfaces and methods
-        The reponse could be cached/save and used to load interfaces
+
+        The returned value can passed to :py:func:`WebAPI.load_interfaces`
         """
         return webapi_request(
             "ISteamWebAPIUtil/GetSupportedAPIList/v1/",
@@ -141,7 +150,11 @@ class WebAPI(object):
         """
         Make an API call for specific method
 
-        method_path is a str in the format of "INTERFACE.METHOD"
+        :param method_path: format ``Interface.Method`` (e.g. ``ISteamWebAPIUtil.GetServerInfo``)
+        :type method_path: str
+        :param kwargs: keyword arguments for the specific method
+        :return: response
+        :rtype: ``dict``, ``lxml.etree.ElementTree`` or ``str``
         """
 
         interface, method = method_path.split('.', 1)
@@ -149,14 +162,14 @@ class WebAPI(object):
 
 
     def doc(self):
-        print(self.__doc__)
+        """
+        Print documentation for all interfaces and their methods
+        """
 
-    @property
-    def __doc__(self):
         doc = "Steam Web API - List of all interfaces\n\n"
         for interface in self.interfaces:
             doc += interface.__doc__
-        return doc
+        print(doc)
 
 
 class WebAPIInterface(object):