added stem python library

lib/stem/__init__.py

@@ -0,0 +1,700 @@
+# Copyright 2011-2013, Damian Johnson and The Tor Project
+# See LICENSE for licensing information
+
+"""
+Library for working with the tor process.
+
+**Module Overview:**
+
+::
+
+  ControllerError - Base exception raised when using the controller.
+    |- ProtocolError - Malformed socket data.
+    |- OperationFailed - Tor was unable to successfully complete the operation.
+    |  |- UnsatisfiableRequest - Tor was unable to satisfy a valid request.
+    |  |  +- CircuitExtensionFailed - Attempt to make or extend a circuit failed.
+    |  +- InvalidRequest - Invalid request.
+    |     +- InvalidArguments - Invalid request parameters.
+    +- SocketError - Communication with the socket failed.
+       +- SocketClosed - Socket has been shut down.
+
+.. data:: Runlevel (enum)
+
+  Rating of importance used for event logging.
+
+  =========== ===========
+  Runlevel    Description
+  =========== ===========
+  **ERR**     critical issues that impair tor's ability to function
+  **WARN**    non-critical issues the user should be aware of
+  **NOTICE**  information that may be helpful to the user
+  **INFO**    high level runtime information
+  **DEBUG**   low level runtime information
+  =========== ===========
+
+.. data:: Signal (enum)
+
+  Signals that the tor process will accept.
+
+  ========================= ===========
+  Signal                    Description
+  ========================= ===========
+  **RELOAD** or **HUP**     reloads our torrc
+  **SHUTDOWN** or **INT**   shut down, waiting ShutdownWaitLength first if we're a relay
+  **DUMP** or **USR1**      dumps information about open connections and circuits to our log
+  **DEBUG** or **USR2**     switch our logging to the DEBUG runlevel
+  **HALT** or **TERM**      exit tor immediately
+  **NEWNYM**                switch to new circuits, so new application requests don't share any circuits with old ones (this also clears our DNS cache)
+  **CLEARDNSCACHE**         clears cached DNS results
+  ========================= ===========
+
+.. data:: Flag (enum)
+
+  Flag assigned to tor relays by the authorities to indicate various
+  characteristics.
+
+  ================= ===========
+  Flag              Description
+  ================= ===========
+  **AUTHORITY**     relay is a directory authority
+  **BADEXIT**       relay shouldn't be used as an exit due to being either problematic or malicious (`wiki <https://trac.torproject.org/projects/tor/wiki/doc/badRelays>`_)
+  **BADDIRECTORY**  relay shouldn't be used for directory information
+  **EXIT**          relay's exit policy makes it more useful as an exit rather than middle hop
+  **FAST**          relay's suitable for high-bandwidth circuits
+  **GUARD**         relay's suitable for being an entry guard (first hop)
+  **HSDIR**         relay is being used as a v2 hidden service directory
+  **NAMED**         relay can be referred to by its nickname
+  **RUNNING**       relay is currently usable
+  **STABLE**        relay's suitable for long-lived circuits
+  **UNNAMED**       relay isn't presently bound to a nickname
+  **V2DIR**         relay supports the v2 directory protocol
+  **VALID**         relay has been validated
+  ================= ===========
+
+.. data:: CircStatus (enum)
+
+  Statuses that a circuit can be in. Tor may provide statuses not in this enum.
+
+  ============ ===========
+  CircStatus   Description
+  ============ ===========
+  **LAUNCHED** new circuit was created
+  **BUILT**    circuit finished being created and can accept traffic
+  **EXTENDED** circuit has been extended by a hop
+  **FAILED**   circuit construction failed
+  **CLOSED**   circuit has been closed
+  ============ ===========
+
+.. data:: CircBuildFlag (enum)
+
+  Attributes about how a circuit is built. These were introduced in tor version
+  0.2.3.11. Tor may provide flags not in this enum.
+
+  ================= ===========
+  CircBuildFlag     Description
+  ================= ===========
+  **ONEHOP_TUNNEL** single hop circuit to fetch directory information
+  **IS_INTERNAL**   circuit that won't be used for client traffic
+  **NEED_CAPACITY** circuit only includes high capacity relays
+  **NEED_UPTIME**   circuit only includes relays with a high uptime
+  ================= ===========
+
+.. data:: CircPurpose (enum)
+
+  Description of what a circuit is intended for. These were introduced in tor
+  version 0.2.1.6. Tor may provide purposes not in this enum.
+
+  ==================== ===========
+  CircPurpose          Description
+  ==================== ===========
+  **GENERAL**          client traffic or fetching directory information
+  **HS_CLIENT_INTRO**  client side introduction point for a hidden service circuit
+  **HS_CLIENT_REND**   client side hidden service rendezvous circuit
+  **HS_SERVICE_INTRO** server side introduction point for a hidden service circuit
+  **HS_SERVICE_REND**  server side hidden service rendezvous circuit
+  **TESTING**          testing to see if we're reachable, so we can be used as a relay
+  **CONTROLLER**       circuit that was built by a controller
+  **MEASURE_TIMEOUT**  circuit being kept around to see how long it takes
+  ==================== ===========
+
+.. data:: CircClosureReason (enum)
+
+  Reason that a circuit is being closed or failed to be established. Tor may
+  provide reasons not in this enum.
+
+  ========================= ===========
+  CircClosureReason         Description
+  ========================= ===========
+  **NONE**                  no reason given
+  **TORPROTOCOL**           violation in the tor protocol
+  **INTERNAL**              internal error
+  **REQUESTED**             requested by the client via a TRUNCATE command
+  **HIBERNATING**           relay is presently hibernating
+  **RESOURCELIMIT**         relay is out of memory, sockets, or circuit IDs
+  **CONNECTFAILED**         unable to contact the relay
+  **OR_IDENTITY**           relay had the wrong OR identification
+  **OR_CONN_CLOSED**        connection failed after being established
+  **FINISHED**              circuit has expired (see tor's MaxCircuitDirtiness config option)
+  **TIMEOUT**               circuit construction timed out
+  **DESTROYED**             circuit unexpectedly closed
+  **NOPATH**                not enough relays to make a circuit
+  **NOSUCHSERVICE**         requested hidden service does not exist
+  **MEASUREMENT_EXPIRED**   same as **TIMEOUT** except that it was left open for measurement purposes
+  ========================= ===========
+
+.. data:: CircEvent (enum)
+
+  Type of change reflected in a circuit by a CIRC_MINOR event. Tor may provide
+  event types not in this enum.
+
+  ===================== ===========
+  CircEvent             Description
+  ===================== ===========
+  **PURPOSE_CHANGED**   circuit purpose or hidden service state has changed
+  **CANNIBALIZED**      circuit connections are being reused for a different circuit
+  ===================== ===========
+
+.. data:: HiddenServiceState (enum)
+
+  State that a hidden service circuit can have. These were introduced in tor
+  version 0.2.3.11. Tor may provide states not in this enum.
+
+  Enumerations fall into four groups based on their prefix...
+
+  ======= ===========
+  Prefix  Description
+  ======= ===========
+  HSCI_*  client-side introduction-point
+  HSCR_*  client-side rendezvous-point
+  HSSI_*  service-side introduction-point
+  HSSR_*  service-side rendezvous-point
+  ======= ===========
+
+  ============================= ===========
+  HiddenServiceState            Description
+  ============================= ===========
+  **HSCI_CONNECTING**           connecting to the introductory point
+  **HSCI_INTRO_SENT**           sent INTRODUCE1 and awaiting a reply
+  **HSCI_DONE**                 received a reply, circuit is closing
+  **HSCR_CONNECTING**           connecting to the introductory point
+  **HSCR_ESTABLISHED_IDLE**     rendezvous-point established, awaiting an introduction
+  **HSCR_ESTABLISHED_WAITING**  introduction received, awaiting a rend
+  **HSCR_JOINED**               connected to the hidden service
+  **HSSI_CONNECTING**           connecting to the introductory point
+  **HSSI_ESTABLISHED**          established introductory point
+  **HSSR_CONNECTING**           connecting to the introductory point
+  **HSSR_JOINED**               connected to the rendezvous-point
+  ============================= ===========
+
+.. data:: RelayEndReason (enum)
+
+  Reasons why the stream is to be closed.
+
+  =================== ===========
+  RelayEndReason      Description
+  =================== ===========
+  **MISC**            none of the following reasons
+  **RESOLVEFAILED**   unable to resolve the hostname
+  **CONNECTREFUSED**  remote host refused the connection
+  **EXITPOLICY**      OR refuses to connect to the destination
+  **DESTROY**         circuit is being shut down
+  **DONE**            connection has been closed
+  **TIMEOUT**         connection timed out
+  **NOROUTE**         routing error while contacting the destination
+  **HIBERNATING**     relay is temporarily hibernating
+  **INTERNAL**        internal error at the relay
+  **RESOURCELIMIT**   relay has insufficient resources to service the request
+  **CONNRESET**       connection was unexpectedly reset
+  **TORPROTOCOL**     violation in the tor protocol
+  **NOTDIRECTORY**    directory information requested from a relay that isn't mirroring it
+  =================== ===========
+
+.. data:: StreamStatus (enum)
+
+  State that a stream going through tor can have. Tor may provide states not in
+  this enum.
+
+  ================= ===========
+  StreamStatus      Description
+  ================= ===========
+  **NEW**           request for a new connection
+  **NEWRESOLVE**    request to resolve an address
+  **REMAP**         address is being re-mapped to another
+  **SENTCONNECT**   sent a connect cell along a circuit
+  **SENTRESOLVE**   sent a resolve cell along a circuit
+  **SUCCEEDED**     stream has been established
+  **FAILED**        stream is detached, and won't be re-established
+  **DETACHED**      stream is detached, but might be re-established
+  **CLOSED**        stream has closed
+  ================= ===========
+
+.. data:: StreamClosureReason (enum)
+
+  Reason that a stream is being closed or failed to be established. This
+  includes all values in the :data:`~stem.RelayEndReason` enumeration as
+  well as the following. Tor may provide reasons not in this enum.
+
+  ===================== ===========
+  StreamClosureReason   Description
+  ===================== ===========
+  **END**               endpoint has sent a RELAY_END cell
+  **PRIVATE_ADDR**      endpoint was a private address (127.0.0.1, 10.0.0.1, etc)
+  ===================== ===========
+
+.. data:: StreamSource (enum)
+
+  Cause of a stream being remapped to another address. Tor may provide sources
+  not in this enum.
+
+  ============= ===========
+  StreamSource  Description
+  ============= ===========
+  **CACHE**     tor is remapping because of a cached answer
+  **EXIT**      exit relay requested the remap
+  ============= ===========
+
+.. data:: StreamPurpose (enum)
+
+  Purpsoe of the stream. This is only provided with new streams and tor may
+  provide purposes not in this enum.
+
+  ================= ===========
+  StreamPurpose     Description
+  ================= ===========
+  **DIR_FETCH**     fetching directory information (descriptors, consensus, etc)
+  **DIR_UPLOAD**    uploading our descriptor to an authority
+  **DNS_REQUEST**   user initiated DNS request
+  **DIRPORT_TEST**  checking that our directory port is reachable externally
+  **USER**          either relaying user traffic or not one of the above categories
+  ================= ===========
+
+.. data:: ORStatus (enum)
+
+  State that an OR connection can have. Tor may provide states not in this
+  enum.
+
+  =============== ===========
+  ORStatus        Description
+  =============== ===========
+  **NEW**         received OR connection, starting server-side handshake
+  **LAUNCHED**    launched outbound OR connection, starting client-side handshake
+  **CONNECTED**   OR connection has been established
+  **FAILED**      attempt to establish OR connection failed
+  **CLOSED**      OR connection has been closed
+  =============== ===========
+
+.. data:: ORClosureReason (enum)
+
+  Reason that an OR connection is being closed or failed to be established. Tor
+  may provide reasons not in this enum.
+
+  =================== ===========
+  ORClosureReason     Description
+  =================== ===========
+  **DONE**            OR connection shut down cleanly
+  **CONNECTREFUSED**  got a ECONNREFUSED when connecting to the relay
+  **IDENTITY**        identity of the relay wasn't what we expected
+  **CONNECTRESET**    got a ECONNRESET or similar error from relay
+  **TIMEOUT**         got a ETIMEOUT or similar error from relay
+  **NOROUTE**         got a ENOTCONN, ENETUNREACH, ENETDOWN, EHOSTUNREACH, or similar error from relay
+  **IOERROR**         got a different kind of error from relay
+  **RESOURCELIMIT**   relay has insufficient resources to service the request
+  **MISC**            connection refused for another reason
+  =================== ===========
+
+.. data:: AuthDescriptorAction (enum)
+
+  Actions that directory authorities might take with relay descriptors. Tor may
+  provide reasons not in this enum.
+
+  ===================== ===========
+  AuthDescriptorAction  Description
+  ===================== ===========
+  **ACCEPTED**          accepting the descriptor as the newest version
+  **DROPPED**           descriptor rejected without notifying the relay
+  **REJECTED**          relay notified that its descriptor has been rejected
+  ===================== ===========
+
+.. data:: StatusType (enum)
+
+  Sources for tor status events. Tor may provide types not in this enum.
+
+  ============= ===========
+  StatusType    Description
+  ============= ===========
+  **GENERAL**   general tor activity, not specifically as a client or relay
+  **CLIENT**    related to our activity as a tor client
+  **SERVER**    related to our activity as a tor relay
+  ============= ===========
+
+.. data:: GuardType (enum)
+
+  Use a guard relay can be for. Tor may provide types not in this enum.
+
+  =========== ===========
+  GuardType   Description
+  =========== ===========
+  **ENTRY**   used to connect to the tor network
+  =========== ===========
+
+.. data:: GuardStatus (enum)
+
+  Status a guard relay can have. Tor may provide types not in this enum.
+
+  ============= ===========
+  GuardStatus   Description
+  ============= ===========
+  **NEW**       new guard that we weren't previously using
+  **DROPPED**   removed from use as one of our guards
+  **UP**        guard is now reachable
+  **DOWN**      guard is now unreachable
+  **BAD**       consensus or relay considers this relay to be unusable as a guard
+  **GOOD**      consensus or relay considers this relay to be usable as a guard
+  ============= ===========
+
+.. data:: TimeoutSetType (enum)
+
+  Way in which the timeout value of a circuit is changing. Tor may provide
+  types not in this enum.
+
+  =============== ===========
+  TimeoutSetType  Description
+  =============== ===========
+  **COMPUTED**    tor has computed a new timeout based on prior circuits
+  **RESET**       timeout reverted to its default
+  **SUSPENDED**   timeout reverted to its default until network connectivity has recovered
+  **DISCARD**     throwing out timeout value from when the network was down
+  **RESUME**      resumed calculations to determine the proper timeout
+  =============== ===========
+"""
+
+__version__ = '1.1.1'
+__author__ = 'Damian Johnson'
+__contact__ = 'atagar@torproject.org'
+__url__ = 'https://stem.torproject.org/'
+__license__ = 'LGPLv3'
+
+__all__ = [
+  "descriptor",
+  "response",
+  "util",
+  "connection",
+  "control",
+  "exit_policy",
+  "prereq",
+  "process",
+  "socket",
+  "version",
+  "ControllerError",
+  "ProtocolError",
+  "OperationFailed",
+  "UnsatisfiableRequest",
+  "CircuitExtensionFailed",
+  "InvalidRequest",
+  "InvalidArguments",
+  "SocketError",
+  "SocketClosed",
+  "Runlevel",
+  "Signal",
+  "Flag",
+  "CircStatus",
+  "CircBuildFlag",
+  "CircPurpose",
+  "CircClosureReason",
+  "CircEvent",
+  "HiddenServiceState",
+  "RelayEndReason",
+  "StreamStatus",
+  "StreamClosureReason",
+  "StreamSource",
+  "StreamPurpose",
+  "ORStatus",
+  "ORClosureReason",
+  "AuthDescriptorAction",
+  "StatusType",
+  "GuardType",
+  "GuardStatus",
+  "TimeoutSetType",
+]
+
+import stem.util.enum
+
+# Constant to indicate an undefined argument default. Usually we'd use None for
+# this, but users will commonly provide None as the argument so need something
+# else fairly unique...
+
+UNDEFINED = "<Undefined_ >"
+
+
+class ControllerError(Exception):
+  "Base error for controller communication issues."
+
+
+class ProtocolError(ControllerError):
+  "Malformed content from the control socket."
+
+
+class OperationFailed(ControllerError):
+  """
+  Base exception class for failed operations that return an error code
+
+  :var str code: error code returned by Tor
+  :var str message: error message returned by Tor or a human readable error
+    message
+  """
+
+  def __init__(self, code = None, message = None):
+    super(ControllerError, self).__init__(message)
+    self.code = code
+    self.message = message
+
+
+class UnsatisfiableRequest(OperationFailed):
+  """
+  Exception raised if Tor was unable to process our request.
+  """
+
+
+class CircuitExtensionFailed(UnsatisfiableRequest):
+  """
+  An attempt to create or extend a circuit failed.
+
+  :var stem.response.CircuitEvent circ: response notifying us of the failure
+  """
+
+  def __init__(self, message, circ = None):
+    super(CircuitExtensionFailed, self).__init__(message = message)
+    self.circ = circ
+
+
+class InvalidRequest(OperationFailed):
+  """
+  Exception raised when the request was invalid or malformed.
+  """
+
+
+class InvalidArguments(InvalidRequest):
+  """
+  Exception class for requests which had invalid arguments.
+
+  :var str code: error code returned by Tor
+  :var str message: error message returned by Tor or a human readable error
+    message
+  :var list arguments: a list of arguments which were invalid
+  """
+
+  def __init__(self, code = None, message = None, arguments = None):
+    super(InvalidArguments, self).__init__(code, message)
+    self.arguments = arguments
+
+
+class SocketError(ControllerError):
+  "Error arose while communicating with the control socket."
+
+
+class SocketClosed(SocketError):
+  "Control socket was closed before completing the message."
+
+Runlevel = stem.util.enum.UppercaseEnum(
+  "DEBUG",
+  "INFO",
+  "NOTICE",
+  "WARN",
+  "ERR",
+)
+
+Flag = stem.util.enum.Enum(
+  ("AUTHORITY", "Authority"),
+  ("BADEXIT", "BadExit"),
+  ("BADDIRECTORY", "BadDirectory"),
+  ("EXIT", "Exit"),
+  ("FAST", "Fast"),
+  ("GUARD", "Guard"),
+  ("HSDIR", "HSDir"),
+  ("NAMED", "Named"),
+  ("RUNNING", "Running"),
+  ("STABLE", "Stable"),
+  ("UNNAMED", "Unnamed"),
+  ("V2DIR", "V2Dir"),
+  ("V3DIR", "V3Dir"),
+  ("VALID", "Valid"),
+)
+
+Signal = stem.util.enum.UppercaseEnum(
+  "RELOAD",
+  "HUP",
+  "SHUTDOWN",
+  "INT",
+  "DUMP",
+  "USR1",
+  "DEBUG",
+  "USR2",
+  "HALT",
+  "TERM",
+  "NEWNYM",
+  "CLEARDNSCACHE",
+)
+
+CircStatus = stem.util.enum.UppercaseEnum(
+  "LAUNCHED",
+  "BUILT",
+  "EXTENDED",
+  "FAILED",
+  "CLOSED",
+)
+
+CircBuildFlag = stem.util.enum.UppercaseEnum(
+  "ONEHOP_TUNNEL",
+  "IS_INTERNAL",
+  "NEED_CAPACITY",
+  "NEED_UPTIME",
+)
+
+CircPurpose = stem.util.enum.UppercaseEnum(
+  "GENERAL",
+  "HS_CLIENT_INTRO",
+  "HS_CLIENT_REND",
+  "HS_SERVICE_INTRO",
+  "HS_SERVICE_REND",
+  "TESTING",
+  "CONTROLLER",
+  "MEASURE_TIMEOUT",
+)
+
+CircClosureReason = stem.util.enum.UppercaseEnum(
+  "NONE",
+  "TORPROTOCOL",
+  "INTERNAL",
+  "REQUESTED",
+  "HIBERNATING",
+  "RESOURCELIMIT",
+  "CONNECTFAILED",
+  "OR_IDENTITY",
+  "OR_CONN_CLOSED",
+  "FINISHED",
+  "TIMEOUT",
+  "DESTROYED",
+  "NOPATH",
+  "NOSUCHSERVICE",
+  "MEASUREMENT_EXPIRED",
+)
+
+CircEvent = stem.util.enum.UppercaseEnum(
+  "PURPOSE_CHANGED",
+  "CANNIBALIZED",
+)
+
+HiddenServiceState = stem.util.enum.UppercaseEnum(
+  "HSCI_CONNECTING",
+  "HSCI_INTRO_SENT",
+  "HSCI_DONE",
+  "HSCR_CONNECTING",
+  "HSCR_ESTABLISHED_IDLE",
+  "HSCR_ESTABLISHED_WAITING",
+  "HSCR_JOINED",
+  "HSSI_CONNECTING",
+  "HSSI_ESTABLISHED",
+  "HSSR_CONNECTING",
+  "HSSR_JOINED",
+)
+
+RelayEndReason = stem.util.enum.UppercaseEnum(
+  "MISC",
+  "RESOLVEFAILED",
+  "CONNECTREFUSED",
+  "EXITPOLICY",
+  "DESTROY",
+  "DONE",
+  "TIMEOUT",
+  "NOROUTE",
+  "HIBERNATING",
+  "INTERNAL",
+  "RESOURCELIMIT",
+  "CONNRESET",
+  "TORPROTOCOL",
+  "NOTDIRECTORY",
+)
+
+StreamStatus = stem.util.enum.UppercaseEnum(
+  "NEW",
+  "NEWRESOLVE",
+  "REMAP",
+  "SENTCONNECT",
+  "SENTRESOLVE",
+  "SUCCEEDED",
+  "FAILED",
+  "DETACHED",
+  "CLOSED",
+)
+
+# StreamClosureReason is a superset of RelayEndReason
+StreamClosureReason = stem.util.enum.UppercaseEnum(*(RelayEndReason.keys() + [
+  "END",
+  "PRIVATE_ADDR",
+]))
+
+StreamSource = stem.util.enum.UppercaseEnum(
+  "CACHE",
+  "EXIT",
+)
+
+StreamPurpose = stem.util.enum.UppercaseEnum(
+  "DIR_FETCH",
+  "DIR_UPLOAD",
+  "DNS_REQUEST",
+  "DIRPORT_TEST",
+  "USER",
+)
+
+ORStatus = stem.util.enum.UppercaseEnum(
+  "NEW",
+  "LAUNCHED",
+  "CONNECTED",
+  "FAILED",
+  "CLOSED",
+)
+
+ORClosureReason = stem.util.enum.UppercaseEnum(
+  "DONE",
+  "CONNECTREFUSED",
+  "IDENTITY",
+  "CONNECTRESET",
+  "TIMEOUT",
+  "NOROUTE",
+  "IOERROR",
+  "RESOURCELIMIT",
+  "MISC",
+)
+
+AuthDescriptorAction = stem.util.enum.UppercaseEnum(
+  "ACCEPTED",
+  "DROPPED",
+  "REJECTED",
+)
+
+StatusType = stem.util.enum.UppercaseEnum(
+  "GENERAL",
+  "CLIENT",
+  "SERVER",
+)
+
+GuardType = stem.util.enum.UppercaseEnum(
+  "ENTRY",
+)
+
+GuardStatus = stem.util.enum.UppercaseEnum(
+  "NEW",
+  "UP",
+  "DOWN",
+  "BAD",
+  "GOOD",
+  "DROPPED",
+)
+
+TimeoutSetType = stem.util.enum.UppercaseEnum(
+  "COMPUTED",
+  "RESET",
+  "SUSPENDED",
+  "DISCARD",
+  "RESUME",
+)