diff --git a/autobahn/autobahn/util.py b/autobahn/autobahn/util.py index 439cc48e..8698bf00 100644 --- a/autobahn/autobahn/util.py +++ b/autobahn/autobahn/util.py @@ -25,7 +25,8 @@ __all__ = ("utcnow", "newid", "rtime", "Stopwatch", - "Tracker") + "Tracker", + "EqualityMixin") import time @@ -40,7 +41,8 @@ def utcnow(): """ Get current time in UTC as ISO 8601 string. - :returns: str -- Current time as string in ISO 8601 format. + :returns: Current time as string in ISO 8601 format. + :rtype: unicode """ now = datetime.utcnow() return now.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z" @@ -51,10 +53,11 @@ def utcstr(ts): """ Format UTC timestamp in ISO 8601 format. - :param ts: Timestamp. - :type ts: instance of datetime. + :param ts: The timestamp to format. + :type ts: instance of :py:class:`datetime.datetime` - :returns: str -- Timestamp formatted in ISO 8601 format. + :returns: Timestamp formatted in ISO 8601 format. + :rtype: unicode """ if ts: return ts.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z" @@ -65,16 +68,17 @@ def utcstr(ts): def parseutc(datestr): """ - Parse an ISO 8601 combined date and time string, like i.e. ``"2011-11-23T12:23Z"`` + Parse an ISO 8601 combined date and time string, like i.e. ``"2011-11-23T12:23:00Z"`` into a UTC datetime instance. .. deprecated:: 0.8.12 Use the **iso8601** module instead (e.g. ``iso8601.parse_date("2014-05-23T13:03:44.123Z")``) :param datestr: The datetime string to parse. - :type datestr: str + :type datestr: unicode - :returns: obj -- A instance of datetime. + :returns: The converted datetime object. + :rtype: instance of :py:class:`datetime.datetime` """ try: return datetime.strptime(datestr, "%Y-%m-%dT%H:%M:%SZ") @@ -87,12 +91,14 @@ def id(): """ Generate a new random object ID from range **[0, 2**53]**. - The upper bound 2**53 is chosen since it is the maximum integer that can be + The upper bound **2**53** is chosen since it is the maximum integer that can be represented as a IEEE double such that all smaller integers are representable as well. - Hence, IDs can be safely used with languages that use IEEE double as their - main (or only) number type (JavaScript, Lua, ..). - :returns: int -- The random object ID. + Hence, IDs can be safely used with languages that use IEEE double as their + main (or only) number type (JavaScript, Lua, etc). + + :returns: A random object ID. + :rtype: int """ return random.randint(0, 9007199254740992) @@ -105,7 +111,8 @@ def newid(len = 16): :param len: The length (in chars) of the ID to generate. :type len: int - :returns: str -- A random object ID. + :returns: A random object ID. + :rtype: str """ return ''.join([random.choice("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_") for _ in xrange(len)]) @@ -119,27 +126,39 @@ if sys.platform.startswith('win'): ## first call to this function, as a floating point number, based on the ## Win32 function QueryPerformanceCounter(). The resolution is typically ## better than one microsecond - rtime = time.clock - _ = rtime() + _rtime = time.clock + _ = _rtime() # this starts wallclock else: ## On Unix-like platforms, this used the first available from this list: ## (1) gettimeofday() -- resolution in microseconds ## (2) ftime() -- resolution in milliseconds ## (3) time() -- resolution in seconds - rtime = time.time + _rtime = time.time +rtime = _rtime +""" +Precise wallclock time. + +:returns: The current wallclock in seconds. Returned values are only guaranteed + to be meaningful relative to each other. +:rtype: float +""" + class Stopwatch: """ - Stopwatch based on walltime. Can be used to do code timing and uses the - most precise walltime measurement available on the platform. This is - a very light-weight object, so create/dispose is very cheap. + Stopwatch based on walltime. + + This can be used to do code timing and uses the most precise walltime measurement + available on the platform. This is a very light-weight object, + so create/dispose is very cheap. """ def __init__(self, start = True): """ - Creates a new stopwatch and by default immediately starts (= resumes) it. + :param start: If ``True``, immediately start the stopwatch. + :type start: bool """ self._elapsed = 0 if start: @@ -152,6 +171,9 @@ class Stopwatch: def elapsed(self): """ Return total time elapsed in seconds during which the stopwatch was running. + + :returns: The elapsed time in seconds. + :rtype: float """ if self._running: now = rtime() @@ -163,6 +185,9 @@ class Stopwatch: """ Pauses the stopwatch and returns total time elapsed in seconds during which the stopwatch was running. + + :returns: The elapsed time in seconds. + :rtype: float """ if self._running: now = rtime() @@ -176,6 +201,9 @@ class Stopwatch: """ Resumes a paused stopwatch and returns total elapsed time in seconds during which the stopwatch was running. + + :returns: The elapsed time in seconds. + :rtype: float """ if not self._running: self._started = rtime() @@ -189,6 +217,9 @@ class Stopwatch: """ Stops the stopwatch and returns total time elapsed in seconds during which the stopwatch was (previously) running. + + :returns: The elapsed time in seconds. + :rtype: float """ elapsed = self.pause() self._elapsed = 0 @@ -199,6 +230,9 @@ class Stopwatch: class Tracker: + """ + A key-based statistics tracker. + """ def __init__(self, tracker, tracked): """ @@ -228,10 +262,11 @@ class Tracker: :type startKey: str :param endKey: Second key for interval (younger timestamp). :type endKey: str - :param format: If `True`, format computed time period and return string. + :param format: If ``True``, format computed time period and return string. :type format: bool - :returns: float or str -- Computed time period in seconds (or formatted string). + :returns: Computed time period in seconds (or formatted string). + :rtype: float or str """ if endKey in self._timings and startKey in self._timings: d = self._timings[endKey] - self._timings[startKey] @@ -260,8 +295,8 @@ class Tracker: :param key: The key :type key: str - :returns: obj -- Timezone-naive datetime. - + :returns: Timezone-naive datetime. + :rtype: instance of :py:class:`datetime.datetime` """ elapsed = self[key] if elapsed is None: @@ -286,8 +321,25 @@ class Tracker: class EqualityMixin: + """ + Mixing to add equality comparison operators to a class. + + Two objects are identical under this mixin, if and only if: + + 1. both object have the same class + 2. all non-private object attributes are equal + """ def __eq__(self, other): + """ + Compare this object to another object for equality. + + :param other: The other object to compare with. + :type other: obj + + :returns: ``True`` iff the objects are equal. + :rtype: bool + """ if not isinstance(other, self.__class__): return False # we only want the actual message data attributes (not eg _serialize) @@ -300,4 +352,13 @@ class EqualityMixin: def __ne__(self, other): + """ + Compare this object to another object for inequality. + + :param other: The other object to compare with. + :type other: obj + + :returns: ``True`` iff the objects are not equal. + :rtype: bool + """ return not self.__eq__(other) diff --git a/autobahn/autobahn/wamp/message.py b/autobahn/autobahn/wamp/message.py index 2c87ad77..7aaefe2b 100644 --- a/autobahn/autobahn/wamp/message.py +++ b/autobahn/autobahn/wamp/message.py @@ -186,7 +186,7 @@ class Hello(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -337,7 +337,7 @@ class Welcome(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -461,7 +461,7 @@ class Abort(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -544,7 +544,7 @@ class Challenge(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -616,7 +616,7 @@ class Authenticate(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -693,7 +693,7 @@ class Goodbye(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -783,7 +783,7 @@ class Heartbeat(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -892,7 +892,7 @@ class Error(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -1040,7 +1040,7 @@ class Publish(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -1201,7 +1201,7 @@ class Published(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -1278,7 +1278,7 @@ class Subscribe(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -1365,7 +1365,7 @@ class Subscribed(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -1434,7 +1434,7 @@ class Unsubscribe(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -1498,7 +1498,7 @@ class Unsubscribed(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -1584,7 +1584,7 @@ class Event(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -1723,7 +1723,7 @@ class Call(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -1862,7 +1862,7 @@ class Cancel(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -1965,7 +1965,7 @@ class Result(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -2077,7 +2077,7 @@ class Register(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -2178,7 +2178,7 @@ class Registered(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -2247,7 +2247,7 @@ class Unregister(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -2311,7 +2311,7 @@ class Unregistered(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -2428,7 +2428,7 @@ class Invocation(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -2605,7 +2605,7 @@ class Interrupt(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## @@ -2709,7 +2709,7 @@ class Yield(Message): :param wmsg: The unserialized raw message. :type wmsg: list - :returns: obj -- An instance of this class. + :returns: An instance of this class. """ ## this should already be verified by WampSerializer.unserialize ## diff --git a/doc/_static/css/page.css b/doc/_static/css/page.css index 52cb9d20..717bf9d5 100644 --- a/doc/_static/css/page.css +++ b/doc/_static/css/page.css @@ -128,6 +128,10 @@ dl .table tr:first-child { font-weight: normal; } +th.field-name { + white-space: nowrap; +} + dl.class, dl.exception, dl.function { margin-top: 24px; box-shadow: 0 0 8px 1px rgba(0, 0, 0, 0.2);