[tor-commits] [stem/master] Moving event version requrements to the version module
atagar at torproject.org
atagar at torproject.org
Wed Jan 16 17:30:07 UTC 2013
commit 1f498f1ce24e149e166ce280872283a61fa76ef4
Author: Damian Johnson <atagar at torproject.org>
Date: Wed Jan 16 07:33:22 2013 -0800
Moving event version requrements to the version module
Moving the location to the Requirement enum so users can more easily check if
an event is available or not.
---
stem/response/events.py | 114 +++++++++++++++++++++++------------------------
stem/version.py | 42 ++++++++++++++----
2 files changed, 89 insertions(+), 67 deletions(-)
diff --git a/stem/response/events.py b/stem/response/events.py
index b7c84cf..4b199ce 100644
--- a/stem/response/events.py
+++ b/stem/response/events.py
@@ -147,6 +147,9 @@ class AddrMapEvent(Event):
"""
Event that indicates a new address mapping.
+ The ADDRMAP event was one of the first Control Protocol V1 events and was
+ introduced in tor version 0.1.1.1-alpha.
+
:var str hostname: address being resolved
:var str destination: destionation of the resolution, this is usually an ip,
but could be a hostname if TrackHostExits is enabled or **NONE** if the
@@ -154,9 +157,6 @@ class AddrMapEvent(Event):
:var datetime expiry: expiration time of the resolution in local time
:var str error: error code if the resolution failed
:var datetime utc_expiry: expiration time of the resolution in UTC
-
- The ADDRMAP event was one of the first Control Protocol V1 events and was
- introduced in tor version 0.1.1.1-alpha.
"""
_POSITIONAL_ARGS = ("hostname", "destination", "expiry")
@@ -183,15 +183,15 @@ class AuthDirNewDescEvent(Event):
descriptors. The descriptor type contained within this event is unspecified
so the descriptor contents are left unparsed.
+ The AUTHDIR_NEWDESCS event was introduced in tor version 0.1.1.10-alpha.
+
:var stem.AuthDescriptorAction action: what is being done with the descriptor
:var str message: explanation of why we chose this action
:var str descriptor: content of the descriptor
-
- The AUTHDIR_NEWDESCS event was introduced in tor version 0.1.1.10-alpha.
"""
_SKIP_PARSING = True
- _VERSION_ADDED = stem.version.Version('0.1.1.10-alpha')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_AUTHDIR_NEWDESCS
def _parse(self):
lines = str(self).split('\n')
@@ -210,11 +210,11 @@ class BandwidthEvent(Event):
"""
Event emitted every second with the bytes sent and received by tor.
- :var long read: bytes received by tor that second
- :var long written: bytes sent by tor that second
-
The BW event was one of the first Control Protocol V1 events and was
introduced in tor version 0.1.1.1-alpha.
+
+ :var long read: bytes received by tor that second
+ :var long written: bytes sent by tor that second
"""
_POSITIONAL_ARGS = ("read", "written")
@@ -236,6 +236,8 @@ class BuildTimeoutSetEvent(Event):
Event indicating that the timeout value for a circuit has changed. This was
first added in tor version 0.2.2.7.
+ The BUILDTIMEOUT_SET event was introduced in tor version 0.2.2.7-alpha.
+
:var stem.TimeoutSetType set_type: way in which the timeout is changing
:var int total_times: circuit build times tor used to determine the timeout
:var int timeout: circuit timeout value in milliseconds
@@ -245,8 +247,6 @@ class BuildTimeoutSetEvent(Event):
:var float timeout_rate: ratio of circuits that have time out
:var int close_timeout: duration to keep measurement circuits in milliseconds
:var float close_rate: ratio of measurement circuits that are closed
-
- The BUILDTIMEOUT_SET event was introduced in tor version 0.2.2.7-alpha.
"""
_POSITIONAL_ARGS = ("set_type",)
@@ -260,7 +260,7 @@ class BuildTimeoutSetEvent(Event):
"CLOSE_MS": "close_timeout",
"CLOSE_RATE": "close_rate",
}
- _VERSION_ADDED = stem.version.Version('0.2.2.7-alpha')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_BUILDTIMEOUT_SET
def _parse(self):
# convert our integer and float parameters
@@ -294,6 +294,9 @@ class CircuitEvent(Event):
VERBOSE_NAMES feature isn't enabled. The option was first introduced in tor
version 0.1.2.2, and on by default after 0.2.2.1.
+ The CIRC event was one of the first Control Protocol V1 events and was
+ introduced in tor version 0.1.1.1-alpha.
+
:var str id: circuit identifier
:var stem.CircStatus status: reported status for the circuit
:var tuple path: relays involved in the circuit, these are
@@ -306,9 +309,6 @@ class CircuitEvent(Event):
:var datetime created: time when the circuit was created or cannibalized
:var stem.CircClosureReason reason: reason for the circuit to be closed
:var stem.CircClosureReason remote_reason: remote side's reason for the circuit to be closed
-
- The CIRC event was one of the first Control Protocol V1 events and was
- introduced in tor version 0.1.1.1-alpha.
"""
_POSITIONAL_ARGS = ("id", "status", "path")
@@ -350,6 +350,8 @@ class CircMinorEvent(Event):
Event providing information about minor changes in our circuits. This was
first added in tor version 0.2.3.11.
+ The CIRC_MINOR event was introduced in tor version 0.2.3.11-alpha.
+
:var str id: circuit identifier
:var stem.CircEvent event: type of change in the circuit
:var tuple path: relays involved in the circuit, these are
@@ -362,8 +364,6 @@ class CircMinorEvent(Event):
:var datetime created: time when the circuit was created or cannibalized
:var stem.CircPurpose old_purpose: prior purpose for the circuit
:var stem.HiddenServiceState old_hs_state: prior status as a hidden service circuit
-
- The CIRC_MINOR event was introduced in tor version 0.2.3.11-alpha.
"""
_POSITIONAL_ARGS = ("id", "event", "path")
@@ -376,7 +376,7 @@ class CircMinorEvent(Event):
"OLD_PURPOSE": "old_purpose",
"OLD_HS_STATE": "old_hs_state",
}
- _VERSION_ADDED = stem.version.Version('0.2.3.11-alpha')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_CIRC_MINOR
def _parse(self):
self.path = tuple(stem.control._parse_circ_path(self.path))
@@ -405,11 +405,11 @@ class ClientsSeenEvent(Event):
"""
Periodic event on bridge relays that provides a summary of our users.
+ The CLIENTS_SEEN event was introduced in tor version 0.2.1.10-alpha.
+
:var datetime start_time: time in UTC that we started collecting these stats
:var dict locales: mapping of country codes to a rounded count for the number of users
:var dict ip_versions: mapping of ip protocols to a rounded count for the number of users
-
- The CLIENTS_SEEN event was introduced in tor version 0.2.1.10-alpha.
"""
_KEYWORD_ARGS = {
@@ -417,7 +417,7 @@ class ClientsSeenEvent(Event):
"CountrySummary": "locales",
"IPVersions": "ip_versions",
}
- _VERSION_ADDED = stem.version.Version('0.2.1.10-alpha')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_CLIENTS_SEEN
def _parse(self):
if self.start_time is not None:
@@ -465,14 +465,14 @@ class ConfChangedEvent(Event):
Event that indicates that our configuration changed, either in response to a
SETCONF or RELOAD signal.
+ The CONF_CHANGED event was introduced in tor version 0.2.3.3-alpha.
+
:var dict config: mapping of configuration options to their new values
(**None** if the option is being unset)
-
- The CONF_CHANGED event was introduced in tor version 0.2.3.3-alpha.
"""
_SKIP_PARSING = True
- _VERSION_ADDED = stem.version.Version('0.2.3.3-alpha')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_CONF_CHANGED
def _parse(self):
self.config = {}
@@ -502,23 +502,21 @@ class DescChangedEvent(Event):
The DESCCHANGED event was introduced in tor version 0.1.2.2-alpha.
"""
- _VERSION_ADDED = stem.version.Version('0.1.2.2-alpha')
-
- pass
+ _VERSION_ADDED = stem.version.Requirement.EVENT_DESCCHANGED
class GuardEvent(Event):
"""
Event that indicates that our guard relays have changed.
+ The GUARD event was introduced in tor version 0.1.2.5-alpha.
+
:var stem.GuardType guard_type: purpose the guard relay is for
:var str name: nickname or fingerprint of the guard relay
:var stem.GuardStatus status: status of the guard relay
-
- The GUARD event was introduced in tor version 0.1.2.5-alpha.
"""
- _VERSION_ADDED = stem.version.Version('0.1.2.5-alpha')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_GUARD
# TODO: We should replace the 'name' field with a fingerprint or nickname
# attribute once we know what it can be...
@@ -533,11 +531,11 @@ class LogEvent(Event):
Tor logging event. These are the most visible kind of event since, by
default, tor logs at the NOTICE :data:`~stem.Runlevel` to stdout.
- :var stem.Runlevel runlevel: runlevel of the logged message
- :var str message: logged message
-
The logging events were some of the first Control Protocol V1 events
and were introduced in tor version 0.1.1.1-alpha.
+
+ :var stem.Runlevel runlevel: runlevel of the logged message
+ :var str message: logged message
"""
_SKIP_PARSING = True
@@ -557,13 +555,13 @@ class NetworkStatusEvent(Event):
Event for when our copy of the consensus has changed. This was introduced in
tor version 0.1.2.3.
- :var list desc: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` for the changed descriptors
-
The NS event was introduced in tor version 0.1.2.3-alpha.
+
+ :var list desc: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` for the changed descriptors
"""
_SKIP_PARSING = True
- _VERSION_ADDED = stem.version.Version('0.1.2.3-alpha')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_NS
def _parse(self):
content = str(self).lstrip("NS\n")
@@ -582,13 +580,13 @@ class NewConsensusEvent(Event):
the whole consensus so anything not listed is implicitly no longer
recommended.
- :var list desc: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` for the changed descriptors
-
The NEWCONSENSUS event was introduced in tor version 0.2.1.13-alpha.
+
+ :var list desc: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` for the changed descriptors
"""
_SKIP_PARSING = True
- _VERSION_ADDED = stem.version.Version('0.2.1.13-alpha')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_NEWCONSENSUS
def _parse(self):
content = str(self).lstrip("NEWCONSENSUS\n")
@@ -608,11 +606,11 @@ class NewDescEvent(Event):
VERBOSE_NAMES feature isn't enabled. The option was first introduced in tor
version 0.1.2.2, and on by default after 0.2.2.1.
- :var tuple relays: **(fingerprint, nickname)** tuples for the relays with
- new descriptors
-
The NEWDESC event was one of the first Control Protocol V1 events and was
introduced in tor version 0.1.1.1-alpha.
+
+ :var tuple relays: **(fingerprint, nickname)** tuples for the relays with
+ new descriptors
"""
def _parse(self):
@@ -631,6 +629,9 @@ class ORConnEvent(Event):
The derived 'endpoint_*' attributes are generally more useful.
+ The ORCONN event was one of the first Control Protocol V1 events and was
+ introduced in tor version 0.1.1.1-alpha.
+
:var str endpoint: relay that the event concerns
:var str endpoint_fingerprint: endpoint's finterprint if it was provided
:var str endpoint_nickname: endpoint's nickname if it was provided
@@ -639,9 +640,6 @@ class ORConnEvent(Event):
:var stem.ORStatus status: state of the connection
:var stem.ORClosureReason reason: reason for the connection to be closed
:var int circ_count: number of established and pending circuits
-
- The ORCONN event was one of the first Control Protocol V1 events and was
- introduced in tor version 0.1.1.1-alpha.
"""
_POSITIONAL_ARGS = ("endpoint", "status")
@@ -693,13 +691,13 @@ class SignalEvent(Event):
* NEWNYM
* CLEARDNSCACHE
- :var stem.Signal signal: signal that tor received
-
The SIGNAL event was introduced in tor version 0.2.3.1-alpha.
+
+ :var stem.Signal signal: signal that tor received
"""
_POSITIONAL_ARGS = ("signal",)
- _VERSION_ADDED = stem.version.Version('0.2.3.1-alpha')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_SIGNAL
def _parse(self):
# log if we recieved an unrecognized signal
@@ -721,16 +719,16 @@ class StatusEvent(Event):
However, unlike :class:`~stem.response.events.LogEvent` these contain well
formed data.
+ The STATUS_GENERAL, STATUS_CLIENT, STATUS_SERVER events were introduced
+ in tor version 0.1.2.3-alpha.
+
:var stem.StatusType status_type: category of the status event
:var stem.Runlevel runlevel: runlevel of the logged message
:var str message: logged message
-
- The STATUS_GENERAL, STATUS_CLIENT, STATUS_SERVER events were introduced
- in tor version 0.1.2.3-alpha.
"""
_POSITIONAL_ARGS = ("runlevel", "action")
- _VERSION_ADDED = stem.version.Version('0.1.2.3-alpha')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_STATUS
def _parse(self):
if self.type == 'STATUS_GENERAL':
@@ -749,6 +747,9 @@ class StreamEvent(Event):
"""
Event that indicates that a stream has changed.
+ The STREAM event was one of the first Control Protocol V1 events and was
+ introduced in tor version 0.1.1.1-alpha.
+
:var str id: stream identifier
:var stem.StreamStatus status: reported status for the stream
:var str circ_id: circuit that the stream is attached to
@@ -762,9 +763,6 @@ class StreamEvent(Event):
:var str source_address: requester address (ip or hostname)
:var int source_port: requester port
:var stem.StreamPurpose purpose: purpose for the stream
-
- The STREAM event was one of the first Control Protocol V1 events and was
- introduced in tor version 0.1.1.1-alpha.
"""
_POSITIONAL_ARGS = ("id", "status", "circ_id", "target")
@@ -821,15 +819,15 @@ class StreamBwEvent(Event):
Event (emitted approximately every second) with the bytes sent and received
by the application since the last such event on this stream.
+ The STREAM_BW event was introduced in tor version 0.1.2.8-beta.
+
:var str id: stream identifier
:var long written: bytes sent by the application
:var long read: bytes received by the application
-
- The STREAM_BW event was introduced in tor version 0.1.2.8-beta.
"""
_POSITIONAL_ARGS = ("id", "written", "read")
- _VERSION_ADDED = stem.version.Version('0.1.2.8-beta')
+ _VERSION_ADDED = stem.version.Requirement.EVENT_STREAM_BW
def _parse(self):
if not tor_tools.is_valid_stream_id(self.id):
diff --git a/stem/version.py b/stem/version.py
index af6d248..47b8393 100644
--- a/stem/version.py
+++ b/stem/version.py
@@ -34,16 +34,28 @@ easily parsed and compared, for instance...
===================================== ===========
Requirement Description
===================================== ===========
- **AUTH_SAFECOOKIE** 'SAFECOOKIE' authentication method
+ **AUTH_SAFECOOKIE** SAFECOOKIE authentication method
+ **EVENT_AUTHDIR_NEWDESCS** AUTHDIR_NEWDESC events
+ **EVENT_BUILDTIMEOUT_SET** BUILDTIMEOUT_SET events
+ **EVENT_CIRC_MINOR** CIRC_MINOR events
+ **EVENT_CLIENTS_SEEN** CLIENTS_SEEN events
+ **EVENT_CONF_CHANGED** CONF_CHANGED events
+ **EVENT_DESCCHANGED** DESCCHANGED events
+ **EVENT_GUARD** GUARD events
+ **EVENT_NEWCONSENSUS** NEWCONSENSUS events
+ **EVENT_NS** NS events
+ **EVENT_SIGNAL** SIGNAL events
+ **EVENT_STATUS** STATUS_GENERAL, STATUS_CLIENT, and STATUS_SERVER events
+ **EVENT_STREAM_BW** STREAM_BW events
+ **EXTENDCIRCUIT_PATH_OPTIONAL** EXTENDCIRCUIT queries can omit the path if the circuit is zero
+ **FEATURE_EXTENDED_EVENTS** 'EXTENDED_EVENTS' optional feature
+ **FEATURE_VERBOSE_NAMES** 'VERBOSE_NAMES' optional feature
**GETINFO_CONFIG_TEXT** 'GETINFO config-text' query
- **EXTENDCIRCUIT_PATH_OPTIONAL** 'EXTENDCIRCUIT' queries can omit the path if the circuit is zero
- **LOADCONF** 'LOADCONF' requests
- **TAKEOWNERSHIP** 'TAKEOWNERSHIP' requests
+ **LOADCONF** LOADCONF requests
+ **TAKEOWNERSHIP** TAKEOWNERSHIP requests
**TORRC_CONTROL_SOCKET** 'ControlSocket <path>' config option
**TORRC_PORT_FORWARDING** 'PortForwarding' config option
**TORRC_DISABLE_DEBUGGER_ATTACHMENT** 'DisableDebuggerAttachment' config option
- **FEATURE_VERBOSE_NAMES** 'VERBOSE_NAMES' optional feature
- **FEATURE_EXTENDED_EVENTS** 'EXTENDED_EVENTS' optional feature
===================================== ===========
"""
@@ -271,13 +283,25 @@ safecookie_req.greater_than(Version("0.2.3.13"))
Requirement = stem.util.enum.Enum(
("AUTH_SAFECOOKIE", safecookie_req),
- ("GETINFO_CONFIG_TEXT", Version("0.2.2.7-alpha")),
+ ("EVENT_AUTHDIR_NEWDESCS", Version('0.1.1.10-alpha')),
+ ("EVENT_BUILDTIMEOUT_SET", Version('0.2.2.7-alpha')),
+ ("EVENT_CIRC_MINOR", Version('0.2.3.11-alpha')),
+ ("EVENT_CLIENTS_SEEN", Version('0.2.1.10-alpha')),
+ ("EVENT_CONF_CHANGED", Version('0.2.3.3-alpha')),
+ ("EVENT_DESCCHANGED", Version('0.1.2.2-alpha')),
+ ("EVENT_GUARD", Version('0.1.2.5-alpha')),
+ ("EVENT_NS", Version('0.1.2.3-alpha')),
+ ("EVENT_NEWCONSENSUS", Version('0.2.1.13-alpha')),
+ ("EVENT_SIGNAL", Version('0.2.3.1-alpha')),
+ ("EVENT_STATUS", Version('0.1.2.3-alpha')),
+ ("EVENT_STREAM_BW", Version('0.1.2.8-beta')),
("EXTENDCIRCUIT_PATH_OPTIONAL", Version("0.2.2.9")),
+ ("FEATURE_EXTENDED_EVENTS", Version("0.2.2.1-alpha")),
+ ("FEATURE_VERBOSE_NAMES", Version("0.2.2.1-alpha")),
+ ("GETINFO_CONFIG_TEXT", Version("0.2.2.7-alpha")),
("LOADCONF", Version("0.2.1.1")),
("TAKEOWNERSHIP", Version("0.2.2.28-beta")),
("TORRC_CONTROL_SOCKET", Version("0.2.0.30")),
("TORRC_PORT_FORWARDING", Version("0.2.3.1-alpha")),
("TORRC_DISABLE_DEBUGGER_ATTACHMENT", Version("0.2.3.9")),
- ("FEATURE_VERBOSE_NAMES", Version("0.2.2.1-alpha")),
- ("FEATURE_EXTENDED_EVENTS", Version("0.2.2.1-alpha")),
)
More information about the tor-commits
mailing list