[stem/master] Revised API docs for stem.exit_policy - tor-commits

28 Oct 2012

commit d00d2ac5a4679a428358f06242cb0980660bb100
Author: Damian Johnson atagar@torproject.org
Date:   Sun Oct 21 21:26:26 2012 -0700
Revised API docs for stem.exit_policy
---
 docs/api.rst               |    1 +
 docs/types/exit_policy.rst |    5 +++
 stem/exit_policy.py        |   77 +++++++++++++++++++++++--------------------
 stem/version.py            |    4 +-
 4 files changed, 49 insertions(+), 38 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 3015210..b0531b0 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -4,5 +4,6 @@ API
 Types
 -----
+* `stem.exit_policy <types/exit_policy.html>`_ - Relay policy for the destinations it will or won't allow traffic to.
 * `stem.version <types/version.html>`_ - Tor versions that can be compared to determine Tor's capablilites.
diff --git a/docs/types/exit_policy.rst b/docs/types/exit_policy.rst
new file mode 100644
index 0000000..2963fa8
--- /dev/null
+++ b/docs/types/exit_policy.rst
@@ -0,0 +1,5 @@
+Exit Policy
+===========
+
+.. automodule:: stem.exit_policy
+
diff --git a/stem/exit_policy.py b/stem/exit_policy.py
index 0337a6b..1c47bb5 100644
--- a/stem/exit_policy.py
+++ b/stem/exit_policy.py
@@ -4,7 +4,8 @@ exiting to a destination is permissable or not. For instance...
::
-  >>> policy = stem.exit_policy.ExitPolicy("accept *:80", "accept *:443", "reject *:*")
+  >>> from stem.exit_policy import ExitPolicy, MicrodescriptorExitPolicy
+  >>> policy = ExitPolicy("accept *:80", "accept *:443", "reject *:*")
...
...
...
print policy
accept *:80, accept *:443, reject *:*
...
...
...
print policy.summary()
@@ -12,16 +13,17 @@ exiting to a destination is permissable or not. For instance...
...
...
...
policy.can_exit_to("75.119.206.243", 80)
True
-  >>> policy = stem.exit_policy.MicrodescriptorExitPolicy("accept 80,443")
+  >>> policy = MicrodescriptorExitPolicy("accept 80,443")
...
...
...
print policy
accept 80,443
-  >>> policy.check("75.119.206.243", 80)
+  >>> policy.can_exit_to("75.119.206.243", 80)
   True
::
ExitPolicy - Exit policy for a Tor relay
     |  + MicrodescriptorExitPolicy - Microdescriptor exit policy
+    |- set_default_allowed - sets the can_exit_to response when no rules match
     |- can_exit_to - check if exiting to this destination is allowed or not
     |- is_exiting_allowed - check if any exiting is allowed
     |- summary - provides a short label, similar to a microdescriptor
@@ -33,6 +35,11 @@ exiting to a destination is permissable or not. For instance...
     |- is_port_wildcard - checks if we'll accept any port
     |- is_match - checks if we match a given destination
     +- __str__ - string representation for this rule
+
+  AddressType - Enumerations for IP address types that can be in an exit policy
+    |- WILDCARD - any address of either IPv4 or IPv6
+    |- IPv4 - IPv4 address
+    +- IPv6 - IPv6 address
 """
import stem.util.connection
@@ -62,9 +69,10 @@ AddressType = stem.util.enum.Enum(("WILDCARD", "Wildcard"), ("IPv4", "IPv4"), ("
 class ExitPolicy(object):
   """
   Policy for the destinations that a relay allows or denies exiting to. This
-  is, in effect, simply a list of ExitPolicyRule entries.
+  is, in effect, just a list of :class:`~stem.exit_policy.ExitPolicyRule`
+  entries.
-  :param list rules: str or ExitPolicyRule entries that make up this policy
+  :param list rules: **str** or :class:`~stem.exit_policy.ExitPolicyRule` entries that make up this policy
   """
def __init__(self, *rules):
@@ -83,17 +91,12 @@ class ExitPolicy(object):
def set_default_allowed(self, is_allowed_default):
     """
-    Generally policies end with either an 'reject *:*' or 'accept *:*' policy,
-    but if it doesn't then is_allowed_default will determine the default
-    response for our :meth:`~stem.exit_policy.ExitPolicy.can_exit_to` method.
-    This defaults to True because, according to the dir-spec, this is Tor's
-    default...
-    
-    ::
+    Generally policies end with either an 'reject *:*' or 'accept *:*'
+    policy, but if it doesn't then is_allowed_default will determine the
+    default response for our :meth:`~stem.exit_policy.ExitPolicy.can_exit_to`
+    method.
-      The rules are considered in order; if no rule matches, the address will
-      be accepted. For clarity, the last such entry SHOULD be accept *:* or
-      reject *:*.
+    Our default, and tor's, is **True**.
:param bool is_allowed_default: :meth:`~stem.exit_policy.ExitPolicy.can_exit_to` default when no rules apply
     """
@@ -109,7 +112,7 @@ class ExitPolicy(object):
     :param str address: IPv4 or IPv6 address (with or without brackets)
     :param int port: port number
-    :returns: True if exiting to this destination is allowed, False otherwise
+    :returns: **True** if exiting to this destination is allowed, **False** otherwise
     """
for rule in self._rules:
@@ -120,7 +123,8 @@ class ExitPolicy(object):
def is_exiting_allowed(self):
     """
-    Provides True if the policy allows exiting whatsoever, False otherwise.
+    Provides **True** if the policy allows exiting whatsoever, **False**
+    otherwise.
     """
rejected_ports = set()
@@ -154,7 +158,7 @@ class ExitPolicy(object):
       >>> policy.summary()
       "reject 1-442, 444-1024"
-    :returns: str with a concise summary for our policy
+    :returns: **str** with a concise summary for our policy
     """
if self._summary_representation is None:
@@ -231,8 +235,8 @@ class ExitPolicy(object):
 class MicrodescriptorExitPolicy(ExitPolicy):
   """
   Exit policy provided by the microdescriptors. This is a distilled version of
-  a normal ExitPolicy contains, just consisting of a list of ports that are
-  either accepted or rejected. For instance...
+  a normal :class:`~stem.exit_policy.ExitPolicy` contains, just consisting of a
+  list of ports that are either accepted or rejected. For instance...
::
@@ -241,7 +245,7 @@ class MicrodescriptorExitPolicy(ExitPolicy):
Since these policies are a subset of the exit policy information (lacking IP
   ranges) clients can only use them to guess if a relay will accept traffic or
-  not. To quote the dir-spec (section 3.2.1)...
+  not. To quote the `dir-spec https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt`_ (section 3.2.1)...
::
@@ -251,7 +255,7 @@ class MicrodescriptorExitPolicy(ExitPolicy):
     wrong, in which case they'll have to try elsewhere.
:var set ports: ports that this policy includes
-  :var bool is_accept: True if these are ports that we accept, False if they're ports that we reject
+  :var bool is_accept: **True** if these are ports that we accept, **False** if they're ports that we reject
:param str policy: policy string that describes this policy
   """
@@ -322,7 +326,8 @@ class ExitPolicyRule(object):
   form complete policies that describe where a relay will and will not allow
   traffic to exit.
-  The format of these rules are formally described in the dir-spec as an
+  The format of these rules are formally described in the `dir-spec
+  https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt`_ as an
   "exitpattern". Note that while these are similar to tor's man page entry for
   ExitPolicies, it's not the exact same. An exitpattern is better defined and
   scricter in what it'll accept. For instance, ports are not optional and it
@@ -336,14 +341,14 @@ class ExitPolicyRule(object):
   :var AddressType address_type: type of address that we have
   :var str address: address that this rule is for
   :var str mask: subnet mask for the address (ex. "255.255.255.0")
-  :var int masked_bits: number of bits the subnet mask represents, None if the mask can't have a bit representation
+  :var int masked_bits: number of bits the subnet mask represents, **None** if the mask can't have a bit representation
:var int min_port: lower end of the port range that we include (inclusive)
   :var int max_port: upper end of the port range that we include (inclusive)
:param str rule: exit policy rule to be parsed
-  :raises: ValueError if input isn't a valid tor exit policy rule
+  :raises: **ValueError** if input isn't a valid tor exit policy rule
   """
def __init__(self, rule):
@@ -393,36 +398,36 @@ class ExitPolicyRule(object):
def is_address_wildcard(self):
     """
-    True if we'll match against any address, False otherwise. Note that this
-    may be different from matching against a /0 because policies can contain
-    both IPv4 and IPv6 addresses (so 0.0.0.0/0 won't match against an IPv6
-    address).
+    **True** if we'll match against any address, **False** otherwise. Note that
+    this may be different from matching against a /0 because policies can
+    contain both IPv4 and IPv6 addresses (so 0.0.0.0/0 won't match against an
+    IPv6 address).
-    :returns: bool for if our address matching is a wildcard
+    :returns: **bool** for if our address matching is a wildcard
     """
return self.address_type == AddressType.WILDCARD
def is_port_wildcard(self):
     """
-    True if we'll match against any port, False otherwise.
+    **True** if we'll match against any port, **False** otherwise.
-    :returns: bool for if our port matching is a wildcard
+    :returns: **bool** for if our port matching is a wildcard
     """
return self.min_port in (0, 1) and self.max_port == 65535
def is_match(self, address = None, port = None):
     """
-    True if we match against the given destination, False otherwise. If the
-    address or port is omitted then that'll only match against a wildcard.
+    **True** if we match against the given destination, **False** otherwise. If
+    the address or port is omitted then that'll only match against a wildcard.
:param str address: IPv4 or IPv6 address (with or without brackets)
     :param int port: port number
-    :returns: bool indicating if we match against this destination
+    :returns: **bool** indicating if we match against this destination
-    :raises: ValueError if provided with a malformed address or port
+    :raises: **ValueError** if provided with a malformed address or port
     """
# validate our input and check if the argumement doens't match our address type
diff --git a/stem/version.py b/stem/version.py
index bb75c18..42f6c16 100644
--- a/stem/version.py
+++ b/stem/version.py
@@ -17,7 +17,7 @@ easily parsed and compared, for instance...
get_system_tor_version - gets the version of our system's tor installation
-  Version - Tor versioning information.
+  Version - Tor versioning information
     |- meets_requirements - checks if this version meets the given requirements
     |- __str__ - string representation
     +- __cmp__ - compares with another Version
@@ -27,7 +27,7 @@ easily parsed and compared, for instance...
     |- less_than    - adds rule that matches if we're less than a version
     +- in_range     - adds rule that matches if we're within a given version range
-  Requirement - Enumerations for the version requirements of features.
+  Requirement - Enumerations for the version requirements of features
     |- AUTH_SAFECOOKIE      - 'SAFECOOKIE' authentication method
     |- GETINFO_CONFIG_TEXT  - 'GETINFO config-text' query
     |- TORRC_CONTROL_SOCKET - 'ControlSocket <path>' config option

    