[tor-commits] [stem/master] Renaming ExitPolicy's is_default() to has_default()
atagar at torproject.org
atagar at torproject.org
Sun Sep 7 19:31:10 UTC 2014
commit be32881152f198a7479e4c951cfd917c4d06831c
Author: Damian Johnson <atagar at torproject.org>
Date: Sun Sep 7 12:19:08 2014 -0700
Renaming ExitPolicy's is_default() to has_default()
Renaming the ExitPolicy's new is_default() method, and adding a has_private()
counterpart for private rules. Also updating our changelog and noting when
several of our new additions were added.
---
docs/change_log.rst | 4 ++--
stem/control.py | 11 +++++++++
stem/exit_policy.py | 49 ++++++++++++++++++++++++++++++++-------
stem/socket.py | 2 ++
stem/util/proc.py | 2 ++
stem/util/str_tools.py | 2 ++
test/unit/exit_policy/policy.py | 5 ++--
7 files changed, 63 insertions(+), 12 deletions(-)
diff --git a/docs/change_log.rst b/docs/change_log.rst
index 130b24f..ec7eaef 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -44,7 +44,7 @@ The following are only available within Stem's `git repository
* Added :func:`~stem.control.BaseController.connection_time` to the :class:`~stem.control.BaseController`
* Changed :func:`~stem.control.Controller.get_microdescriptor`, :func:`~stem.control.Controller.get_server_descriptor`, and :func:`~stem.control.Controller.get_network_status` to get our own descriptor if no fingerprint or nickname is provided.
- * Added an :func:`~stem.exit_policy.ExitPolicy.strip_private` method to :class:`~stem.exit_policy.ExitPolicy` and :func:`~stem.exit_policy.ExitPolicy.is_private` to :class:`~stem.exit_policy.ExitPolicyRule`
+ * Added :class:`~stem.exit_policy.ExitPolicy` methods for more easily handling 'private' policies (the `default prefix <https://www.torproject.org/docs/tor-manual.html.en#ExitPolicyRejectPrivate>`_) and the defaultly appended suffix. This includes :func:`~stem.exit_policy.ExitPolicy.has_private`, :func:`~stem.exit_policy.ExitPolicy.strip_private`, :func:`~stem.exit_policy.ExitPolicy.has_default`, and :func:`~stem.exit_policy.ExitPolicy.strip_default` :class:`~stem.exit_policy.ExitPolicy` methods in addition to :func:`~stem.exit_policy.ExitPolicyRule.is_private` and :func:`~stem.exit_policy.ExitPolicyRule.is_default` for the :class:`~stem.exit_policy.ExitPolicyRule`. (:trac:`10107`)
* **Descriptors**
@@ -56,7 +56,7 @@ The following are only available within Stem's `git repository
* Added support for directories to :func:`stem.util.conf.Config.load`.
* Changed :func:`stem.util.conf.uses_settings` to only provide a 'config' keyword arument if the decorated function would accept it.
* Added :func:`stem.util.str_tools.crop`
- * Added :func:`stem.util.proc.get_file_descriptors_used`
+ * Added :func:`stem.util.proc.file_descriptors_used`
* Dropped the 'get_*' prefix from most function names. Old names will still work, but are a deprecated alias.
* **Interpreter**
diff --git a/stem/control.py b/stem/control.py
index 1b33659..c9a9a5f 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -485,6 +485,8 @@ class BaseController(object):
disconnected. That is to say, the time we connected if we're presently
connected and the time we disconnected if we're not connected.
+ .. versionadded:: 1.3.0
+
:returns: **float** for when we last connected or disconnected, zero if
we've never connected
"""
@@ -1317,6 +1319,9 @@ class Controller(BaseController):
authorities so this both won't be available for newly started relays and
may be up to around an hour out of date.
+ .. versionchanged:: 1.3.0
+ Changed so we'd fetch our own descriptor if no 'relay' is provided.
+
:param str relay: fingerprint or nickname of the relay to be queried
:param object default: response if the query fails
@@ -1417,6 +1422,9 @@ class Controller(BaseController):
really need server descriptors then you can get them by setting
'UseMicrodescriptors 0'.
+ .. versionchanged:: 1.3.0
+ Changed so we'd fetch our own descriptor if no 'relay' is provided.
+
:param str relay: fingerprint or nickname of the relay to be queried
:param object default: response if the query fails
@@ -1526,6 +1534,9 @@ class Controller(BaseController):
authorities so this both won't be available for newly started relays and
may be up to around an hour out of date.
+ .. versionchanged:: 1.3.0
+ Changed so we'd fetch our own descriptor if no 'relay' is provided.
+
:param str relay: fingerprint or nickname of the relay to be queried
:param object default: response if the query fails
diff --git a/stem/exit_policy.py b/stem/exit_policy.py
index 06f4d83..9adb699 100644
--- a/stem/exit_policy.py
+++ b/stem/exit_policy.py
@@ -30,8 +30,9 @@ exiting to a destination is permissible or not. For instance...
|- 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
- |- is_default - checks if policy ends with the defaultly appended suffix
+ |- has_private - checks if policy has anything expanded from the 'private' keyword
|- strip_private - provides a copy of the policy without 'private' entries
+ |- has_default - checks if policy ends with the defaultly appended suffix
|- strip_default - provides a copy of the policy without the default suffix
|- __str__ - string representation
+- __iter__ - ExitPolicyRule entries that this contains
@@ -45,8 +46,8 @@ exiting to a destination is permissible or not. For instance...
|- is_match - checks if we match a given destination
|- get_mask - provides the address representation of our mask
|- get_masked_bits - provides the bit representation of our mask
- |- is_private - flag indicating if this was expanded from a 'private' keyword
|- is_default - flag indicating if this was part of the default end of a policy
+ |- is_private - flag indicating if this was expanded from a 'private' keyword
+- __str__ - string representation for this rule
get_config_policy - provides the ExitPolicy based on torrc rules
@@ -381,15 +382,20 @@ class ExitPolicy(object):
return (label_prefix + ', '.join(display_ranges)).strip()
- def is_default(self):
+ def has_private(self):
"""
- Checks if we have the default policy suffix.
+ Checks if we have any rules expanded from the 'private' keyword. Tor
+ appends these by default to the start of the policy and includes a dynamic
+ address (the relay's public IP).
- :returns: **True** if we have the default policy suffix, **False** otherwise
+ .. versionadded:: 1.3.0
+
+ :returns: **True** if we have any private rules expanded from the 'private'
+ keyword, **False** otherwise
"""
for rule in self._get_rules():
- if rule.is_default():
+ if rule.is_private():
return True
return False
@@ -398,15 +404,34 @@ class ExitPolicy(object):
"""
Provides a copy of this policy without 'private' policy entries.
+ .. versionadded:: 1.3.0
+
:returns: **ExitPolicy** without private rules
"""
return ExitPolicy(*[rule for rule in self._get_rules() if not rule.is_private()])
+ def has_default(self):
+ """
+ Checks if we have the default policy suffix.
+
+ .. versionadded:: 1.3.0
+
+ :returns: **True** if we have the default policy suffix, **False** otherwise
+ """
+
+ for rule in self._get_rules():
+ if rule.is_default():
+ return True
+
+ return False
+
def strip_default(self):
"""
Provides a copy of this policy without the default policy suffix.
+ .. versionadded:: 1.3.0
+
:returns: **ExitPolicy** without default rules
"""
@@ -791,14 +816,22 @@ class ExitPolicyRule(object):
def is_private(self):
"""
- True if this rule was expanded from the 'private' keyword, False otherwise.
+ Checks if this rule was expanded from the 'private' policy keyword.
+
+ .. versionadded:: 1.3.0
+
+ :returns: **True** if this rule was expanded from the 'private' keyword, **False** otherwise.
"""
return self._is_private
def is_default(self):
"""
- True if this rule was part of the default end of a policy, False otherwise.
+ Checks if this rule belongs to the default exit policy suffix.
+
+ .. versionadded:: 1.3.0
+
+ :returns: **True** if this rule was part of the default end of a policy, **False** otherwise.
"""
return self._is_default_suffix
diff --git a/stem/socket.py b/stem/socket.py
index e25f385..7991899 100644
--- a/stem/socket.py
+++ b/stem/socket.py
@@ -211,6 +211,8 @@ class ControlSocket(object):
disconnected. That is to say, the time we connected if we're presently
connected and the time we disconnected if we're not connected.
+ .. versionadded:: 1.3.0
+
:returns: **float** for when we last connected or disconnected, zero if
we've never connected
"""
diff --git a/stem/util/proc.py b/stem/util/proc.py
index 184e450..c7cb5ce 100644
--- a/stem/util/proc.py
+++ b/stem/util/proc.py
@@ -301,6 +301,8 @@ def file_descriptors_used(pid):
"""
Provides the number of file descriptors currently being used by a process.
+ .. versionadded:: 1.3.0
+
:param int pid: process id of the process to be queried
:returns: **int** of the number of file descriptors used
diff --git a/stem/util/str_tools.py b/stem/util/str_tools.py
index 33ecb84..16681d5 100644
--- a/stem/util/str_tools.py
+++ b/stem/util/str_tools.py
@@ -173,6 +173,8 @@ def crop(msg, size, min_word_length = 4, min_crop = 0, ending = Ending.ELLIPSE,
such details of how this works might change in the future. Callers should not
rely on the details of how this crops.
+ .. versionadded:: 1.3.0
+
:param str msg: text to be processed
:param int size: space available for text
:param int min_word_length: minimum characters before which a word is
diff --git a/test/unit/exit_policy/policy.py b/test/unit/exit_policy/policy.py
index a1ee390..406ef62 100644
--- a/test/unit/exit_policy/policy.py
+++ b/test/unit/exit_policy/policy.py
@@ -104,7 +104,8 @@ class TestExitPolicy(unittest.TestCase):
self.assertFalse(rule.is_private())
self.assertFalse(rule.is_default())
- self.assertFalse(policy.is_default())
+ self.assertFalse(policy.has_private())
+ self.assertFalse(policy.has_default())
self.assertEqual(policy, policy.strip_private())
self.assertEqual(policy, policy.strip_default())
@@ -129,7 +130,7 @@ class TestExitPolicy(unittest.TestCase):
for rule in policy:
self.assertTrue(rule.is_default())
- self.assertTrue(policy.is_default())
+ self.assertTrue(policy.has_default())
self.assertEqual(ExitPolicy(), policy.strip_default())
def test_mixed_private_policy(self):
More information about the tor-commits
mailing list