File: version.py

package info (click to toggle)
python-stem 1.7.1-1.1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 5,768 kB
  • sloc: python: 29,441; java: 312; makefile: 125; sh: 17
file content (396 lines) | stat: -rw-r--r-- 14,516 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
# Copyright 2011-2018, Damian Johnson and The Tor Project
# See LICENSE for licensing information

"""
Tor versioning information and requirements for its features. These can be
easily parsed and compared, for instance...

::

  >>> from stem.version import get_system_tor_version, Requirement
  >>> my_version = get_system_tor_version()
  >>> print(my_version)
  0.2.1.30
  >>> my_version >= Requirement.TORRC_CONTROL_SOCKET
  True

**Module Overview:**

::

  get_system_tor_version - gets the version of our system's tor installation

  Version - Tor versioning information

.. data:: Requirement (enum)

  Enumerations for the version requirements of features.

  .. deprecated:: 1.6.0
     Requirement entries belonging to tor versions which have been obsolete for
     at least six months will be removed when we break backward compatibility
     in the 2.x stem release.

  ===================================== ===========
  Requirement                           Description
  ===================================== ===========
  **AUTH_SAFECOOKIE**                   SAFECOOKIE authentication method
  **DESCRIPTOR_COMPRESSION**            `Expanded compression support for ZSTD and LZMA <https://gitweb.torproject.org/torspec.git/commit/?id=1cb56afdc1e55e303e3e6b69e90d983ee217d93f>`_
  **DROPGUARDS**                        DROPGUARDS requests
  **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_HS_DESC_CONTENT**             HS_DESC_CONTENT events
  **EVENT_NETWORK_LIVENESS**            NETWORK_LIVENESS 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
  **EVENT_TRANSPORT_LAUNCHED**          TRANSPORT_LAUNCHED events
  **EVENT_CONN_BW**                     CONN_BW events
  **EVENT_CIRC_BW**                     CIRC_BW events
  **EVENT_CELL_STATS**                  CELL_STATS events
  **EVENT_TB_EMPTY**                    TB_EMPTY events
  **EVENT_HS_DESC**                     HS_DESC 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
  **GETINFO_GEOIP_AVAILABLE**           'GETINFO ip-to-country/ipv4-available' query and its ipv6 counterpart
  **GETINFO_MICRODESCRIPTORS**          'GETINFO md/all' query
  **HIDDEN_SERVICE_V3**                 Support for v3 hidden services
  **HSFETCH**                           HSFETCH requests
  **HSPOST**                            HSPOST requests
  **ADD_ONION**                         ADD_ONION and DEL_ONION requests
  **ADD_ONION_BASIC_AUTH**              ADD_ONION supports basic authentication
  **ADD_ONION_NON_ANONYMOUS**           ADD_ONION supports non-anonymous mode
  **ADD_ONION_MAX_STREAMS**             ADD_ONION support for MaxStreamsCloseCircuit
  **LOADCONF**                          LOADCONF requests
  **MICRODESCRIPTOR_IS_DEFAULT**        Tor gets microdescriptors by default rather than server descriptors
  **SAVECONF_FORCE**                    Added the 'FORCE' flag to SAVECONF
  **TAKEOWNERSHIP**                     TAKEOWNERSHIP requests
  **TORRC_CONTROL_SOCKET**              'ControlSocket <path>' config option
  **TORRC_PORT_FORWARDING**             'PortForwarding' config option
  **TORRC_DISABLE_DEBUGGER_ATTACHMENT** 'DisableDebuggerAttachment' config option
  **TORRC_VIA_STDIN**                   Allow torrc options via 'tor -f -' (:trac:`13865`)
  ===================================== ===========
"""

import os
import re

import stem.prereq
import stem.util
import stem.util.enum
import stem.util.system

if stem.prereq._is_lru_cache_available():
  from functools import lru_cache
else:
  from stem.util.lru_cache import lru_cache

# cache for the get_system_tor_version function
VERSION_CACHE = {}

VERSION_PATTERN = re.compile(r'^([0-9]+)\.([0-9]+)\.([0-9]+)(\.[0-9]+)?(-\S*)?(( \(\S*\))*)$')


def get_system_tor_version(tor_cmd = 'tor'):
  """
  Queries tor for its version. This is os dependent, only working on linux,
  osx, and bsd.

  :param str tor_cmd: command used to run tor

  :returns: :class:`~stem.version.Version` provided by the tor command

  :raises: **IOError** if unable to query or parse the version
  """

  if tor_cmd not in VERSION_CACHE:
    version_cmd = '%s --version' % tor_cmd

    try:
      version_output = stem.util.system.call(version_cmd)
    except OSError as exc:
      # make the error message nicer if this is due to tor being unavialable

      if 'No such file or directory' in str(exc):
        if os.path.isabs(tor_cmd):
          exc = "Unable to check tor's version. '%s' doesn't exist." % tor_cmd
        else:
          exc = "Unable to run '%s'. Maybe tor isn't in your PATH?" % version_cmd

      raise IOError(exc)

    if version_output:
      # output example:
      # Oct 21 07:19:27.438 [notice] Tor v0.2.1.30. This is experimental software. Do not rely on it for strong anonymity. (Running on Linux i686)
      # Tor version 0.2.1.30.

      last_line = version_output[-1]

      if last_line.startswith('Tor version ') and last_line.endswith('.'):
        try:
          version_str = last_line[12:-1]
          VERSION_CACHE[tor_cmd] = Version(version_str)
        except ValueError as exc:
          raise IOError(exc)
      else:
        raise IOError("Unexpected response from '%s': %s" % (version_cmd, last_line))
    else:
      raise IOError("'%s' didn't have any output" % version_cmd)

  return VERSION_CACHE[tor_cmd]


@lru_cache()
def _get_version(version_str):
  return Version(version_str)


class Version(object):
  """
  Comparable tor version. These are constructed from strings that conform to
  the 'new' style in the `tor version-spec
  <https://gitweb.torproject.org/torspec.git/tree/version-spec.txt>`_,
  such as "0.1.4" or "0.2.2.23-alpha (git-7dcd105be34a4f44)".

  .. versionchanged:: 1.6.0
     Added all_extra parameter.

  :var int major: major version
  :var int minor: minor version
  :var int micro: micro version
  :var int patch: patch level (**None** if undefined)
  :var str status: status tag such as 'alpha' or 'beta-dev' (**None** if undefined)
  :var str extra: first extra information without its parentheses such as
    'git-8be6058d8f31e578' (**None** if undefined)
  :var list all_extra: all extra information entries, without their parentheses
  :var str git_commit: git commit id (**None** if it wasn't provided)

  :param str version_str: version to be parsed

  :raises: **ValueError** if input isn't a valid tor version
  """

  def __init__(self, version_str):
    self.version_str = version_str
    version_parts = VERSION_PATTERN.match(version_str)

    if version_parts:
      major, minor, micro, patch, status, extra_str, _ = version_parts.groups()

      # The patch and status matches are optional (may be None) and have an extra
      # proceeding period or dash if they exist. Stripping those off.

      if patch:
        patch = int(patch[1:])

      if status:
        status = status[1:]

      self.major = int(major)
      self.minor = int(minor)
      self.micro = int(micro)
      self.patch = patch
      self.status = status
      self.all_extra = [entry[1:-1] for entry in extra_str.strip().split()] if extra_str else []
      self.extra = self.all_extra[0] if self.all_extra else None
      self.git_commit = None

      for extra in self.all_extra:
        if extra and re.match('^git-[0-9a-f]{16}$', extra):
          self.git_commit = extra[4:]
          break
    else:
      raise ValueError("'%s' isn't a properly formatted tor version" % version_str)

  def __str__(self):
    """
    Provides the string used to construct the version.
    """

    return self.version_str

  def _compare(self, other, method):
    """
    Compares version ordering according to the spec.
    """

    if not isinstance(other, Version):
      return False

    for attr in ('major', 'minor', 'micro', 'patch'):
      my_version = getattr(self, attr)
      other_version = getattr(other, attr)

      if my_version is None:
        my_version = 0

      if other_version is None:
        other_version = 0

      if my_version != other_version:
        return method(my_version, other_version)

    # According to the version spec...
    #
    #   If we *do* encounter two versions that differ only by status tag, we
    #   compare them lexically as ASCII byte strings.

    my_status = self.status if self.status else ''
    other_status = other.status if other.status else ''

    return method(my_status, other_status)

  def __hash__(self):
    return stem.util._hash_attr(self, 'major', 'minor', 'micro', 'patch', 'status', cache = True)

  def __eq__(self, other):
    return self._compare(other, lambda s, o: s == o)

  def __ne__(self, other):
    return not self == other

  def __gt__(self, other):
    """
    Checks if this version meets the requirements for a given feature. We can
    be compared to either a :class:`~stem.version.Version` or
    :class:`~stem.version._VersionRequirements`.
    """

    if isinstance(other, _VersionRequirements):
      for rule in other.rules:
        if rule(self):
          return True

      return False

    return self._compare(other, lambda s, o: s > o)

  def __ge__(self, other):
    if isinstance(other, _VersionRequirements):
      for rule in other.rules:
        if rule(self):
          return True

      return False

    return self._compare(other, lambda s, o: s >= o)


class _VersionRequirements(object):
  """
  Series of version constraints that can be compared to. For instance, this
  allows for comparisons like 'if I'm greater than version X in the 0.2.2
  series, or greater than version Y in the 0.2.3 series'.

  This is a logical 'or' of the series of rules.
  """

  def __init__(self):
    self.rules = []

  def greater_than(self, version, inclusive = True):
    """
    Adds a constraint that we're greater than the given version.

    :param stem.version.Version version: version we're checking against
    :param bool inclusive: if comparison is inclusive or not
    """

    if inclusive:
      self.rules.append(lambda v: version <= v)
    else:
      self.rules.append(lambda v: version < v)

  def less_than(self, version, inclusive = True):
    """
    Adds a constraint that we're less than the given version.

    :param stem.version.Version version: version we're checking against
    :param bool inclusive: if comparison is inclusive or not
    """

    if inclusive:
      self.rules.append(lambda v: version >= v)
    else:
      self.rules.append(lambda v: version > v)

  def in_range(self, from_version, to_version, from_inclusive = True, to_inclusive = False):
    """
    Adds constraint that we're within the range from one version to another.

    :param stem.version.Version from_version: beginning of the comparison range
    :param stem.version.Version to_version: end of the comparison range
    :param bool from_inclusive: if comparison is inclusive with the starting version
    :param bool to_inclusive: if comparison is inclusive with the ending version
    """

    def new_rule(v):
      if from_inclusive and to_inclusive:
        return from_version <= v <= to_version
      elif from_inclusive:
        return from_version <= v < to_version
      else:
        return from_version < v < to_version

    self.rules.append(new_rule)


safecookie_req = _VersionRequirements()
safecookie_req.in_range(Version('0.2.2.36'), Version('0.2.3.0'))
safecookie_req.greater_than(Version('0.2.3.13'))

Requirement = stem.util.enum.Enum(
  ('AUTH_SAFECOOKIE', safecookie_req),
  ('DESCRIPTOR_COMPRESSION', Version('0.3.1.1-alpha')),
  ('DROPGUARDS', Version('0.2.5.1-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_HS_DESC_CONTENT', Version('0.2.7.1-alpha')),
  ('EVENT_NS', Version('0.1.2.3-alpha')),
  ('EVENT_NETWORK_LIVENESS', Version('0.2.7.2-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')),
  ('EVENT_TRANSPORT_LAUNCHED', Version('0.2.5.0-alpha')),
  ('EVENT_CONN_BW', Version('0.2.5.2-alpha')),
  ('EVENT_CIRC_BW', Version('0.2.5.2-alpha')),
  ('EVENT_CELL_STATS', Version('0.2.5.2-alpha')),
  ('EVENT_TB_EMPTY', Version('0.2.5.2-alpha')),
  ('EVENT_HS_DESC', Version('0.2.5.2-alpha')),
  ('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')),
  ('GETINFO_GEOIP_AVAILABLE', Version('0.3.2.1-alpha')),
  ('GETINFO_MICRODESCRIPTORS', Version('0.3.5.1-alpha')),
  ('HIDDEN_SERVICE_V3', Version('0.3.3.1-alpha')),
  ('HSFETCH', Version('0.2.7.1-alpha')),
  ('HSPOST', Version('0.2.7.1-alpha')),
  ('ADD_ONION', Version('0.2.7.1-alpha')),
  ('ADD_ONION_BASIC_AUTH', Version('0.2.9.1-alpha')),
  ('ADD_ONION_NON_ANONYMOUS', Version('0.2.9.3-alpha')),
  ('ADD_ONION_MAX_STREAMS', Version('0.2.7.2-alpha')),
  ('LOADCONF', Version('0.2.1.1')),
  ('MICRODESCRIPTOR_IS_DEFAULT', Version('0.2.3.3')),
  ('SAVECONF_FORCE', Version('0.3.1.1-alpha')),
  ('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')),
  ('TORRC_VIA_STDIN', Version('0.2.6.3-alpha')),
)