commit be32881152f198a7479e4c951cfd917c4d06831c Author: Damian Johnson <atagar@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):