docs/change_log.rst

   1 Change Log
   2 ==========
   3
   4 The following is a log of all user-facing changes to Stem, both released and
   5 unreleased. For a monthly report on work being done see my `development log
   6 <http://blog.atagar.com/>`_.
   7
   8 * :ref:`versioning`
   9 * :ref:`unreleased`
  10 * :ref:`version_1.8`
  11 * :ref:`version_1.7`
  12 * :ref:`version_1.6`
  13 * :ref:`version_1.5`
  14 * :ref:`version_1.4`
  15 * :ref:`version_1.3`
  16 * :ref:`version_1.2`
  17 * :ref:`version_1.1`
  18 * :ref:`version_1.0`
  19
  20 .. _versioning:
  21
  22 Versioning
  23 ----------
  24
  25 Stem uses `semantic versioning <http://semver.org/>`_, which means that
  26 **versions consist of three numbers** (such as '**1.2.4**'). These are used to
  27 convey the kind of backward compatibility you can expect...
  28
  29  * The first value is the **major version**. This changes infrequently, and
  30    indicates that backward incompatible changes have been made (such as the
  31    removal of deprecated functions).
  32
  33  * The second value is the **minor version**. This is the most common kind of
  34    release, and denotes that the improvements are backward compatible.
  35
  36  * The third value is the **patch version**. When a Stem release has a major
  37    issue another release is made which fixes just that problem. These do not
  38    contain substantial improvements or new features. This value is sometimes
  39    left off to indicate all releases with a given major/minor version.
  40
  41 .. _unreleased:
  42
  43 Unreleased
  44 ----------
  45
  46 The following are only available within Stem's `git repository
  47 <download.html>`_.
  48
  49  * **General**
  50
  51   * Stem now requires Python 3.6+. Support for deprecated Python versions (2.6 -> 3.5) has been removed.
  52   * Deprecated methods and attributes have been removed.
  53   * Our API now provides `type hints <https://blog.atagar.com/may2020/>`_.
  54   * Migrated to `asyncio <https://docs.python.org/3/library/asyncio.html>`_. Stem can now be used by `both synchronous and asynchronous applications <https://blog.atagar.com/july2020/>`_.
  55   * Installation has migrated from distutils to setuptools.
  56   * Added the 'reset_timeouts' argument to :func:`~stem.control.Controller.drop_guards` (:ticket:`73`)
  57   * Replace all IOErrors with OSErrors. Python 3.3 changed IOError into an `OSError alias <https://docs.python.org/3/library/exceptions.html#OSError>`_ to `deprecate it <https://www.python.org/dev/peps/pep-3151/#confusing-set-of-os-related-exceptions>`_.
  58
  59  * **Controller**
  60
  61   * Socket based control connections often raised BrokenPipeError when closed
  62   * Added :func:`~stem.control.Controller.add_hidden_service_auth`, :func:`~stem.control.Controller.remove_hidden_service_auth`, and :func:`~stem.control.Controller.list_hidden_service_auth` to the :class:`~stem.control.Controller`
  63   * Incorrect filesystem encoding broke latin-1 cookie path (:ticket:`57`)
  64   * Allow control connection to IPv6 addresses (:ticket:`74`)
  65
  66  * **Descriptors**
  67
  68   * Cached CollecTor files always reported a hash mismatch (:ticket:`76`)
  69   * *transport* lines within extrainfo descriptors failed to validate
  70
  71  * **Utilities**
  72
  73   * *ss* connection resolver failed on platforms that append whitespace (:ticket:`46`)
  74
  75  * **Installation**
  76
  77   * Migrated from distutil to setuptools
  78
  79  * **Website**
  80
  81   * Download link for tutorial examples
  82
  83 .. _version_1.8:
  84
  85 Version 1.8 (December 29th, 2019)
  86 ---------------------------------
  87
  88 `Stem 1.8 <http://blog.atagar.com/stem-release-1-8/>`_ is the final release in Stem’s 1.x series and with it `Python 2.x support <https://www.python.org/doc/sunset-python-2/>`_. Over a year in the making, this introduces `CollecTor <api/descriptor/collector.html>`_, `bandwidth metric <api/descriptor/bandwidth_file.html>`_, and `HSv3 descriptor support <api/descriptor/hidden_service.html#stem.descriptor.hidden_service.HiddenServiceDescriptorV3>`_.
  89
  90  * **Controller**
  91
  92   * Added :func:`~stem.control.Controller.get_start_time` method to the :class:`~stem.control.Controller`
  93   * Added :func:`~stem.control.Controller.get_uptime` method to the :class:`~stem.control.Controller`
  94   * Controller events could fail to be delivered in a timely fashion (:ticket:`archive-27173`)
  95   * Adjusted :func:`~stem.control.Controller.get_microdescriptors` fallback to also use '.new' cache files (:ticket:`archive-28508`)
  96   * ExitPolicies could raise TypeError when read concurrently (:ticket:`archive-29899`)
  97   * Moved the *arrived_at* attribute from :class:`~stem.response.event.Event` to :class:`~stem.response.__init__.ControlMessage`
  98   * **STALE_DESC** :data:`~stem.Flag` (:spec:`d14164d`)
  99   * **DORMANT** and **ACTIVE** :data:`~stem.Signal` (:spec:`4421149`)
 100   * **QUERY_RATE_LIMITED** :data:`~stem.HSDescReason` (:spec:`bd80679`)
 101   * **EXTOR** and **HTTPTUNNEL** :data:`~stem.control.Listener`
 102
 103  * **Descriptors**
 104
 105   * Added the `stem.descriptor.collector <api/descriptor/collector.html>`_ module (:ticket:`archive-17979`)
 106   * Added `v3 hidden service descriptor support <api/descriptor/hidden_service.html>`_ (:ticket:`archive-31369`)
 107   * `Bandwidth file support <api/descriptor/bandwidth_file.html>`_ (:ticket:`archive-29056`)
 108   * `stem.descriptor.remote <api/descriptor/remote.html>`_ methods now raise :class:`stem.DownloadFailed`
 109   * Check Ed25519 validity though the cryptography module rather than PyNaCl (:ticket:`archive-22022`)
 110   * Download compressed descriptors by default (:ticket:`archive-29186`)
 111   * Added :class:`~stem.descriptor.Compression` class
 112   * Added :func:`stem.descriptor.remote.get_microdescriptors`
 113   * Added :func:`stem.descriptor.remote.get_bandwidth_file` (:ticket:`archive-26902`)
 114   * Added :class:`~stem.descriptor.networkstatus.DetachedSignature` parsing (:ticket:`archive-28495`)
 115   * Added :func:`~stem.descriptor.__init__.Descriptor.from_str` method (:ticket:`archive-28450`)
 116   * Added :func:`~stem.descriptor.__init__.Descriptor.type_annotation` method (:ticket:`archive-28397`)
 117   * Added :func:`~stem.descriptor.networkstatus.NetworkStatusDocument.digest` method (:ticket:`archive-28398`)
 118   * Added the **hash_type** and **encoding** arguments to `ServerDescriptor <api/descriptor/server_descriptor.html#stem.descriptor.server_descriptor.ServerDescriptor.digest>`_ and `ExtraInfo's <api/descriptor/extrainfo_descriptor.html#stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor.digest>`_ digest methods (:ticket:`archive-28398`)
 119   * Added the network status vote's new bandwidth_file_digest attribute (:spec:`1b686ef`)
 120   * Added :func:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3.is_valid` and :func:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3.is_fresh` methods (:ticket:`archive-28448`)
 121   * Replaced :func:`~stem.descriptor.router_status_entry.RouterStatusEntryMicroV3` hex encoded **digest** attribute with a base64 encoded **microdescriptor_digest**
 122   * Replaced the **digest** attribute of :class:`~stem.descriptor.microdescriptor.Microdescriptor` with a method by the same name (:ticket:`archive-28398`)
 123   * Default the **version_flavor** attribute of :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3` to 'ns' (:spec:`d97f8d9`)
 124   * DescriptorDownloader crashed if **use_mirrors** is set (:ticket:`archive-28393`)
 125   * Renamed stem.descriptor.hidden_service_descriptor to stem.descriptor.hidden_service
 126   * Don't download from Serge, a bridge authority that frequently timeout
 127   * Updated dizum authority's address (:ticket:`archive-31406`)
 128
 129  * **Client**
 130
 131   * Sockets with ORPorts errored if responses exceeded a hardcoded buffer size (:ticket:`archive-28961`)
 132
 133  * **Utilities**
 134
 135   * :func:`~stem.util.tor_tools.is_valid_hidden_service_address` now provides *true* if a v3 hidden servie address
 136   * Fixed 'invalid escape sequence' python 3.6 warnings (:ticket:`archive-27270`)
 137
 138  * **Website**
 139
 140   * `Migrated to GitHub's issue tracker <https://github.com/torproject/stem/>`_
 141   * Added NetBSD to our `download page <download.html>`_
 142   * Describe `advanced listener usage <tutorials/tortoise_and_the_hare.html#advanced-listeners>`_
 143   * Exemplify `manual SAFECOOKIE authentication <faq.html#i-m-using-safe-cookie-authentication>`_
 144   * `Update PyPI links <https://packaging.python.org/guides/migrating-to-pypi-org/>`_ (:ticket:`archive-30137`)
 145
 146  * **Interpreter**
 147
 148   * tor-prompt is now ~34% faster when used to non-interactively invoke commands
 149
 150 .. _version_1.7:
 151
 152 Version 1.7 (October 7th, 2018)
 153 -------------------------------
 154
 155 `Stem 1.7 <http://blog.atagar.com/stem-release-1-7/>`_ is a full year of
 156 improments. Most notably this adds the ability to `download descriptors through
 157 ORPorts
 158 <tutorials/mirror_mirror_on_the_wall.html#where-can-i-get-the-current-descriptors>`_
 159 and the `stem.directory module <api/directory.html>`_.
 160
 161  * **Controller**
 162
 163   * Listener exceptions and malformed events no longer break further event processing (:ticket:`archive-27053`)
 164   * Documented v3 hidden service support (:ticket:`archive-25124`, :spec:`6bd0a69`)
 165   * Added the stem.control.MALFORMED_EVENTS event listener constant
 166   * Added support for limiting the maximum number of streams for :func:`~stem.control.Controller.create_ephemeral_hidden_service` (:spec:`2fcb1c2`)
 167   * Added a timeout argument to :class:`~stem.control.Controller` methods that could await a response (:ticket:`archive-26056`)
 168   * Added a close_output argument to :class:`~stem.process.launch_tor`
 169   * :func:`stem.connection.connect` crashed if its port argument was a string
 170   * More reliable ExitPolicy resolution (:ticket:`archive-25739`)
 171   * Fixed cache invalidation when another contorller calls SETCONF (:ticket:`archive-25821`)
 172   * :func:`~stem.control.COntroller.create_hidden_service` failed when creating services with v2 options (:ticket:`archive-27446`)
 173   * :func:`~stem.control.Controller.get_info` commonly raised :class:`stem.ProtocolError` when it should provide a :class:`stem.OperationFailed`
 174   * :func:`~stem.control.Controller.get_microdescriptors` now reads microdescriptors from the control port rather than disk when available (:spec:`b5396d5`)
 175   * Added the delivered_read, delivered_written, overhead_read, and overhead_written attributes to :class:`~stem.response.events.CircuitBandwidthEvent` (:spec:`fbb38ec`)
 176   * The *config* attribute of :class:`~stem.response.events.ConfChangedEvent` couldn't represent tor configuration options with multiple values. It has been replaced with new *changed* and *unset* attributes.
 177   * Replaced socket's :func:`~stem.socket.ControlPort.get_address`, :func:`~stem.socket.ControlPort.get_port`, and :func:`~stem.socket.ControlSocketFile.get_socket_path` with attributes
 178   * :class:`~stem.response.ControlMessage` is now comparable and hashable
 179   * Removed the 'raw' argument from :func:`~stem.socket.ControlSocket.send`
 180
 181  * **Descriptors**
 182
 183   * `stem.descriptor.remote <api/descriptor/remote.html>`_ can now download from relay ORPorts
 184   * Zstd and lzma compression support (:spec:`1cb56af`)
 185   * Moved the Directory classes into their own `stem.directory <api/directory.html>`_ module
 186   * Added :func:`~stem.descriptor.remote.Directory.from_cache` and :func:`~stem.descriptor.remote.Directory.from_remote` to the :class:`~stem.descriptor.remote.DirectoryAuthority` subclass
 187   * `Tor rearranged its files <https://lists.torproject.org/pipermail/tor-dev/2018-July/013287.html>`_, adjusted :func:`stem.descriptor.remote.Directory.from_remote` and :func:`stem.manual.Manual.from_remote` to account for this
 188   * `Fallback directory v2 support <https://lists.torproject.org/pipermail/tor-dev/2017-December/012721.html>`_, which adds *nickname* and *extrainfo*
 189   * Added the *orport_v6* attribute to the :class:`~stem.directory.Authority` class
 190   * Added server descriptor's new is_hidden_service_dir attribute
 191   * Added the network status vote's new bandwidth_file_headers attribute (:spec:`84591df`)
 192   * Added the microdescriptor router status entry's new or_addresses attribute (:ticket:`archive-26405`, :spec:`fdc8f3e`)
 193   * Don't retry downloading descriptors when we've timed out
 194   * Don't download from tor26, an authority that frequently timeout
 195   * Replaced Bifroest bridge authority with Serge (:ticket:`archive-26771`)
 196   * `stem.descriptor.remote <api/descriptor/remote.html>`_  now consistently defaults **fall_back_to_authority** to false
 197   * Deprecated `stem.descriptor.export <api/descriptor/export.html>`_. If you use it please `let us know <https://www.atagar.com/contact/>`_.
 198   * Added :func:`~stem.descriptor.remote.their_server_descriptor`
 199   * Added the reply_headers attribute to :class:`~stem.descriptor.remote.Query`
 200   * Supplying a User-Agent when downloading descriptors
 201   * Reduced maximum descriptors fetched by the remote module to match tor's new limit (:ticket:`archive-24743`)
 202   * Consensus **shared_randomness_*_reveal_count** attributes undocumented, and unavailable if retrieved before their corresponding shared_randomness_*_value attribute (:ticket:`archive-25046`)
 203   * Allow 'proto' line to have blank values (:spec:`a8455f4`)
 204
 205  * **Utilities**
 206
 207   * Fixed PyPy compatibility (:ticket:`archive-26207`)
 208   * Python 3.6+ syntax error if test_tools.py imported (:ticket:`archive-26739`)
 209   * Connection information from proc limited to 10,000 results
 210   * Include attribute types in most equality checks and hashes
 211   * Cache hash values of immutable classes
 212   * More performant string concatenation `via bytearrays <https://docs.python.org/3/faq/programming.html#what-is-the-most-efficient-way-to-concatenate-many-strings-together>`_
 213   * Functions using lru_cache could fail with a KeyError on Python 3.5 (:ticket:`archive-26412`)
 214
 215  * **Website**
 216
 217   * Added `terminal styling <tutorials/east_of_the_sun.html#terminal-styling>`_ to our utilities tutorial
 218   * Added `multiprocessing <tutorials/east_of_the_sun.html#multiprocessing>`_ to our utilities tutorial
 219   * Added a `descriptor download example <tutorials/examples/download_descriptor.html>`_
 220   * Added a `relay connection summary example <tutorials/examples/relay_connections.html>`_
 221
 222  * **Version 1.7.1** (December 26th, 2018) - :func:`~stem.process.launch_tor`
 223    compatibility with an upcoming log format change (:ticket:`archive-28731`)
 224
 225 .. _version_1.6:
 226
 227 Version 1.6 (November 5th, 2017)
 228 --------------------------------
 229
 230 Year long accumulation of fixes and improvements in support of the `Nyx 2.0 release <http://blog.atagar.com/nyx-release-2-0/>`_.
 231
 232  * **Controller**
 233
 234   * :func:`~stem.process.launch_tor` raised a ValueError if invoked when outside the main thread
 235   * Failure to authenticate could raise an improper response or hang (:ticket:`archive-22679`)
 236   * Renamed :class:`~stem.response.events.ConnectionBandwidthEvent` type attribute to conn_type to avoid conflict with parent class (:ticket:`archive-21774`)
 237   * Added 'force' argument to :func:`~stem.control.Controller.save_conf` (:spec:`5c82d5e`)
 238   * Added the QUERY_NO_HSDIR :data:`~stem.HSDescReason` and recognizing unknown HSDir results (:spec:`1412d79`)
 239   * Added the GUARD_WAIT :data:`~stem.CircStatus` (:spec:`6446210`)
 240   * Unable to use cookie auth when path includes wide characters (chinese, japanese, etc)
 241   * Tor change caused :func:`~stem.control.Controller.list_ephemeral_hidden_services` to provide empty strings if unset (:ticket:`archive-21329`)
 242   * Better error message when :func:`~stem.control.Controller.set_conf` fails due to an option being immutable
 243   * :func:`~stem.control.Controller.get_ports` didn't provide ports for many representations of localhost (:ticket:`archive-24085`)
 244   * :func:`~stem.control.Controller.is_geoip_unavailable` now determines if database is available right away
 245   * Added the time attribute to :class:`~stem.response.events.StreamBwEvent` and :class:`~stem.response.events.CircuitBandwidthEvent` (:spec:`00b9daf`)
 246   * Added the consensus_content attribute to :class:`~stem.response.events.NewConsensusEvent` and deprecated its 'desc'
 247   * Deprecated :func:`~stem.control.Controller.is_geoip_unavailable`, this is now available via getinfo instead (:ticket:`archive-23237`, :spec:`dc973f8`)
 248   * Deprecated :class:`~stem.respose.events.AuthDirNewDescEvent` (:ticket:`archive-22377`, :spec:`6e887ba`)
 249   * Caching manual information as sqlite rather than stem.util.conf, making :func:`stem.manual.Manual.from_cache` about ~8x faster
 250   * Added :func:`~stem.manual.database` to get a cursor for the manual cache
 251   * Failed to parse torrcs without a port on ipv6 exit policy entries
 252   * Resilient to 'Tor' prefix in 'GETINFO version' result (:spec:`c5ff1b1`)
 253   * Added a **all_extra** parameter to :class:`stem.version.Version` and support for multiple parenthetical entries (:ticket:`archive-22110`, :spec:`b50917d`)
 254   * Setting 'UseMicrodescriptors 1' in your torrc caused :func:`~stem.control.Controller.get_network_statuses` to error (:ticket:`archive-24110`)
 255   * Closing controller connection faster when under heavy event load
 256   * Better messaging when unable to connect to tor on FreeBSD
 257   * More succinct trace level logging
 258
 259  * **Descriptors**
 260
 261   * Supporting `descriptor creation <tutorials/mirror_mirror_on_the_wall.html#can-i-create-descriptors>`_ (:ticket:`archive-10227`)
 262   * Support and validation for `ed25519 certificates <api/descriptor/certificate.html>`_ (`spec <https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt>`_, :ticket:`archive-21558`)
 263   * Added :func:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3.validate_signatures` to check our key certificate signatures (:ticket:`archive-11045`)
 264   * Moved from the deprecated `pycrypto <https://www.dlitz.net/software/pycrypto/>`_ module to `cryptography <https://pypi.org/project/cryptography/>`_ for validating signatures (:ticket:`archive-21086`)
 265   * Sped descriptor reading by ~25% by deferring defaulting when validating
 266   * Added server descriptor's new extra_info_sha256_digest attribute (:spec:`0f03581`)
 267   * Added server descriptor's new protocol attribute (:spec:`eb4fb3c`)
 268   * Added server descriptor's new bridge_distribution attribute (:ticket:`archive-21177`)
 269   * Added extrainfo descriptor's new padding_counts attributes (:spec:`0803997`)
 270   * Shared randomness properties weren't being read in votes (:ticket:`archive-21102`)
 271   * Added bastet as a new authority (:ticket:`archive-23912`)
 272   * Updated longclaw authority's address (:ticket:`archive-23592`)
 273
 274  * **Utilities**
 275
 276   * Support connection resolution on OpenBSD using fstat (:ticket:`archive-13807`)
 277   * Added :func:`~stem.util.system.size_of`
 278   * Added :func:`~stem.util.log.is_tracing`
 279   * Added timeout argument to :func:`~stem.util.system.call`
 280   * Added cwd argument to :func:`~stem.util.system.call`
 281   * Added round argument to :func:`~stem.util.str_tools.size_label`
 282   * Added :class:`~stem.util.test_tools.TimedTestRunner` and :func:`~stem.util.test_tools.test_runtimes`
 283   * Supporting pid arguments in :func:`~stem.util.system.is_running`
 284   * Made connection resolution via proc about 5x faster
 285   * Normalized :func:`~stem.util.term.format` to return unicode
 286   * Don't load vim swap files as configurations
 287
 288  * **Interpreter**
 289
 290   * Added a `'--run [command or path]' argument <tutorials/down_the_rabbit_hole.html#running-individual-commands>`_ to invoke specific commands (:ticket:`archive-21541`)
 291   * Allowing interpreter to continue after tor shuts down (:ticket:`archive-22374`)
 292   * Interpreter buffered an unbounded number of events, leaking memory over time
 293
 294  * **Website**
 295
 296   * Source code served by '[source]' links perpetually stale (:ticket:`archive-19521`)
 297
 298 .. _version_1.5:
 299
 300 Version 1.5 (November 20th, 2016)
 301 ---------------------------------
 302
 303 `Stem 1.5 <http://blog.atagar.com/stem-release-1-5/>`_ is a long overdue
 304 accumulation of seventeen months of improvements including dramatically
 305 improved python 3.x performance, `tor manual information <api/manual.html>`_,
 306 and much more.
 307
 308  * **Controller**
 309
 310   * Dramatic, 300x performance improvement for reading from the control port with python 3
 311   * Added `stem.manual <api/manual.html>`_, which provides information available about Tor from `its manual <https://www.torproject.org/docs/tor-manual.html.en>`_ (:ticket:`archive-8251`)
 312   * :func:`~stem.connection.connect` and :func:`~stem.control.Controller.from_port` now connect to both port 9051 (relay's default) and 9151 (Tor Browser's default) (:ticket:`archive-16075`)
 313   * :class:`~stem.exit_policy.ExitPolicy` support for *accept6/reject6* and *\*4/6* wildcards (:ticket:`archive-16053`)
 314   * Added `support for NETWORK_LIVENESS events <api/response.html#stem.response.events.NetworkLivenessEvent>`_ (:spec:`44aac63`)
 315   * Added support for basic authentication to :func:`~stem.control.Controller.create_ephemeral_hidden_service` (:spec:`c2865d9`)
 316   * Added support for non-anonymous services to :func:`~stem.control.Controller.create_ephemeral_hidden_service` (:spec:`b8fe774`)
 317   * Added :func:`~stem.control.event_description` for getting human-friendly descriptions of tor events (:ticket:`archive-19061`)
 318   * Added :func:`~stem.control.Controller.reconnect` to the :class:`~stem.control.Controller`
 319   * Added :func:`~stem.control.Controller.is_set` to the :class:`~stem.control.Controller`
 320   * Added :func:`~stem.control.Controller.is_user_traffic_allowed` to the :class:`~stem.control.Controller`
 321   * Added the replica attribute to :class:`~stem.response.events.HSDescEvent` (:spec:`4989e73`)
 322   * Added the NoEdConsensus :data:`~stem.Flag` (:spec:`dc99160`)
 323   * Recognize listeners with IPv6 addresses in :func:`~stem.control.Controller.get_listeners`
 324   * :func:`~stem.process.launch_tor` could leave a lingering process during an unexpected exception (:ticket:`archive-17946`)
 325   * IPv6 addresses could trigger errors in :func:`~stem.control.Controller.get_listeners`, :class:`~stem.response.events.ORConnEvent`, and quite a few other things (:ticket:`archive-16174`)
 326   * Don't obscure stacktraces, most notably :class:`~stem.control.Controller` getter methods with default values
 327   * Classes with custom equality checks didn't provide a corresponding inequality method
 328
 329  * **Descriptors**
 330
 331   * `Shorthand functions for stem.descriptor.remote <api/descriptor/remote.html#stem.descriptor.remote.get_instance>`_
 332   * Added `fallback directory information <api/descriptor/remote.html#stem.descriptor.remote.FallbackDirectory>`_.
 333   * Support for ed25519 descriptor fields (:spec:`5a79d67`)
 334   * Support downloading microdescriptor consensus with :func:~stem.descriptor.remote.DescriptorDownloader.get_consensus` (:spec`e788b8f`)
 335   * Added consensus and vote's new shared randomness attributes (:spec:`9949f64`)
 336   * Added server descriptor's new allow_tunneled_dir_requests attribute (:spec:`8bc30d6`)
 337   * Server descriptor validation fails with 'extra-info-digest line had an invalid value' from additions in proposal 228 (:ticket:`archive-16227`)
 338   * :class:`~stem.descriptor.server_descriptor.BridgeDescriptor` now has 'ntor_onion_key' like its unsanitized counterparts
 339   * Replaced the :class:`~stem.descriptor.microdescriptor.Microdescriptor` identifier and identifier_type attributes with an identifiers hash since it can now appear multiple times (:spec:`09ff9e2`)
 340   * Unable to read descriptors from data directories on Windows due to their CRLF newlines (:ticket:`archive-17051`)
 341   * TypeError under python3 when using 'use_mirrors = True' (:ticket:`archive-17083`)
 342   * Deprecated hidden service descriptor's *introduction_points_auth* field, which was never implemented in tor (:ticket:`archive-15190`, :spec:`9c218f9`)
 343   * Deprecated :func:`~stem.descriptor.remote.DescriptorDownloader.get_microdescriptors` as it was never implemented in tor (:ticket:`archive-9271`)
 344   * :func:`~stem.control.Controller.get_hidden_service_descriptor` errored when provided a *servers* argument (:ticket:`archive-18401`)
 345   * Fixed parsing of server descriptor's *allow-single-hop-exits* and *caches-extra-info* lines
 346   * Bracketed IPv6 addresses were mistreated as being invalid content
 347   * Better validation for non-ascii descriptor content
 348   * Updated dannenberg's v3ident (:ticket:`archive-17906`)
 349   * Removed urras as a directory authority (:ticket:`archive-19271`)
 350
 351  * **Utilities**
 352
 353   * IPv6 support in :func:`~stem.util.connection.get_connections` when resolving with proc, netstat, lsof, or ss (:ticket:`archive-18079`)
 354   * The 'ss' connection resolver didn't work on Gentoo (:ticket:`archive-18079`)
 355   * Recognize IPv4-mapped IPv6 addresses in our utils (:ticket:`archive-18079`)
 356   * Allow :func:`stem.util.conf.Config.set` to remove values when provided with a **None** value
 357   * Support prefix and suffix issue strings in :func:`~stem.util.test_tools.pyflakes_issues`
 358   * Additional information when :func:`~stem.util.system.call` fails through a :class:`~stem.util.system.CallError`
 359   * Added **stem.util.system.SYSTEM_CALL_TIME** with the total time spent on system calls
 360   * Added an **is_ipv6** value to :class:`~stem.util.connection.Connection` instances
 361   * Added LINES attribute to :data:`~stem.util.term.Attr`
 362   * Added :func:`~stem.util.system.pids_by_user`
 363   * Added :func:`~stem.util.connection.address_to_int`
 364   * Added :func:`~stem.util.term.encoding`
 365   * Added :func:`~stem.util.__init__.datetime_to_unix`
 366
 367  * **Interpreter**
 368
 369   * Added a '--tor [path]' argument to specify the tor binary to run.
 370
 371  * **Website**
 372
 373   * Example for `custom path selection for circuits <tutorials/to_russia_with_love.html#custom-path-selection>`_ (:ticket:`archive-8728`)
 374   * Download link for tutorial examples (:ticket:`archive-10411`)
 375
 376 .. _version_1.4:
 377
 378 Version 1.4 (May 13th, 2015)
 379 ----------------------------
 380
 381 `Stem's 1.4 release <https://blog.torproject.org/blog/stem-release-14>`_ brings
 382 with it new hidden service capabilities. Most notably, `ephemeral hidden
 383 services <tutorials/over_the_river.html#ephemeral-hidden-services>`_ and the
 384 ability to `read hidden service descriptors
 385 <tutorials/over_the_river.html#hidden-service-descriptors>`_. This release also
 386 changes descriptor validation to now be opt-in rather than opt-out. When
 387 unvalidated content is lazy-loaded, `greatly improving our performance
 388 <https://lists.torproject.org/pipermail/tor-dev/2015-January/008211.html>`_.
 389
 390 And last, Stem also now runs directly under both python2 and python3 without a
 391 2to3 conversion (:ticket:`archive-14075`)!
 392
 393  * **Controller**
 394
 395   * Added :class:`~stem.control.Controller` methods for a new style of hidden services that don't touch disk: :func:`~stem.control.Controller.list_ephemeral_hidden_services`, :func:`~stem.control.Controller.create_ephemeral_hidden_service`, and :func:`~stem.control.Controller.remove_ephemeral_hidden_service` (:spec:`f5ff369`)
 396   * Added :func:`~stem.control.Controller.get_hidden_service_descriptor` and `support for HS_DESC_CONTENT events <api/response.html#stem.response.events.HSDescContentEvent>`_ (:ticket:`archive-14847`, :spec:`aaf2434`)
 397   * :func:`~stem.process.launch_tor_with_config` avoids writing a temporary torrc to disk if able (:ticket:`archive-13865`)
 398   * :class:`~stem.response.events.CircuitEvent` support for the new SOCKS_USERNAME and SOCKS_PASSWORD arguments (:ticket:`archive-14555`, :spec:`2975974`)
 399   * The 'strict' argument of :func:`~stem.exit_policy.ExitPolicy.can_exit_to` didn't behave as documented (:ticket:`archive-14314`)
 400   * Threads spawned for status change listeners were never joined on, potentially causing noise during interpreter shutdown
 401   * Added support for specifying the authentication type and client names in :func:`~stem.control.Controller.create_hidden_service` (:ticket:`archive-14320`)
 402
 403  * **Descriptors**
 404
 405   * Lazy-loading descriptors, improving performance by 25-70% depending on what type it is (:ticket:`archive-14011`)
 406   * Added `support for hidden service descriptors <api/descriptor/hidden_service.html>`_ (:ticket:`archive-15004`)
 407   * When reading sanitised bridge descriptors (server or extrainfo), :func:`~stem.descriptor.__init__.parse_file` treated the whole file as a single descriptor
 408   * The :class:`~stem.descriptor.networkstatus.DirectoryAuthority` 'fingerprint' attribute was actually its 'v3ident'
 409   * Added consensus' new package attribute (:spec:`ab64534`)
 410   * Added extra info' new hs_stats_end, hs_rend_cells, hs_rend_cells_attr, hs_dir_onions_seen, and hs_dir_onions_seen_attr attributes (:spec:`ddb630d`)
 411   * Updating Faravahar's address (:ticket:`archive-14487`)
 412
 413  * **Utilities**
 414
 415   * Windows support for connection resolution (:ticket:`archive-14844`)
 416   * :func:`stem.util.connection.port_usage` always returned None (:ticket:`archive-14046`)
 417   * :func:`~stem.util.test_tools.stylistic_issues` and :func:`~stem.util.test_tools.pyflakes_issues` now provide namedtuples that also includes the line
 418   * Added :func:`stem.util.system.tail`
 419   * Proc connection resolution could fail on especially busy systems (:ticket:`archive-14048`)
 420
 421  * **Website**
 422
 423   * Added support and `instructions for tox <faq.html#how-do-i-test-compatibility-with-multiple-python-versions>`_ (:ticket:`archive-14091`)
 424   * Added OSX to our `download page <download.html>`_ (:ticket:`archive-8588`)
 425   * Updated our twitter example to work with the service's 1.1 API (:ticket:`archive-9003`)
 426
 427  * **Version 1.4.1** (May 18th, 2015) - fixed issue where descriptors couldn't
 428    be unpickled (:ticket:`archive-16054`) and a parsing issue for router status entry
 429    bandwidth lines (:ticket:`archive-16048`)
 430
 431 .. _version_1.3:
 432
 433 Version 1.3 (December 22nd, 2014)
 434 ---------------------------------
 435
 436 With `Stem's 1.3 release <https://blog.torproject.org/blog/stem-release-13>`_
 437 it's now much easier to `work with hidden services
 438 <tutorials/over_the_river.html>`_, 40% faster to read decriptors, and includes
 439 a myriad of other improvements. For a nice description of the changes this
 440 brings see `Nathan Willis' LWN article <http://lwn.net/Articles/632914/>`_.
 441
 442  * **Controller**
 443
 444   * Added :class:`~stem.control.Controller` methods to more easily work with hidden service configurations: :func:`~stem.control.Controller.get_hidden_service_conf`, :func:`~stem.control.Controller.set_hidden_service_conf`, :func:`~stem.control.Controller.create_hidden_service`, and :func:`~stem.control.Controller.remove_hidden_service` (:ticket:`archive-12533`)
 445   * Added :func:`~stem.control.Controller.get_accounting_stats` to the :class:`~stem.control.Controller`
 446   * Added :func:`~stem.control.Controller.get_effective_rate` to the :class:`~stem.control.Controller`
 447   * Added :func:`~stem.control.BaseController.connection_time` to the :class:`~stem.control.BaseController`
 448   * 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.
 449   * 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`. (:ticket:`archive-10107`)
 450   * Added the reason attribute to :class:`~stem.response.events.HSDescEvent` (:spec:`7908c8d`)
 451   * :func:`~stem.process.launch_tor_with_config` could cause a "Too many open files" OSError if called too many times (:ticket:`archive-13141`)
 452   * The :func:`~stem.control.Controller.get_exit_policy` method errored if tor couldn't determine our external address
 453   * The Controller's methods for retrieving descriptors could raise unexpected ValueErrors if tor didn't have any descriptors available
 454   * Throwing a new :class:`~stem.DescriptorUnavailable` exception type when the :class:`~stem.control.Controller` can't provide the descriptor for a relay (:ticket:`archive-13879`)
 455
 456  * **Descriptors**
 457
 458   * Improved speed for parsing consensus documents by around 40% (:ticket:`archive-12859` and :ticket:`archive-13821`)
 459   * Don't fail if consensus method 1 is not present, as it is no longer required (:spec:`fc8a6f0`)
 460   * Include '\*.new' files when reading from a Tor data directory (:ticket:`archive-13756`)
 461   * Updated the authorities we list, `replacing turtles with longclaw <https://lists.torproject.org/pipermail/tor-talk/2014-November/035650.html>`_ and `updating gabelmoo's address <https://lists.torproject.org/pipermail/tor-talk/2014-September/034898.html>`_
 462   * Noting if authorities are also a bandwidth authority or not
 463   * Microdescriptor validation issues could result in an AttributeError (:ticket:`archive-13904`)
 464
 465  * **Utilities**
 466
 467   * Added support for directories to :func:`stem.util.conf.Config.load`
 468   * Changed :func:`stem.util.conf.uses_settings` to only provide a 'config' keyword arument if the decorated function would accept it
 469   * Added :func:`stem.util.str_tools.crop`
 470   * Added :func:`stem.util.proc.file_descriptors_used`
 471   * Dropped the 'get_*' prefix from most function names. Old names will still work, but are a deprecated alias.
 472
 473  * **Interpreter**
 474
 475   * The /info command errored for relays without contact information
 476
 477  * **Website**
 478
 479   * Tutorial for `hidden services <tutorials/over_the_river.html>`_
 480   * Example for `writing descriptors to disk and reading them back <tutorials/mirror_mirror_on_the_wall.html#saving-and-loading-descriptors>`_ (:ticket:`archive-13774`)
 481   * Added Gentoo to our `download page <download.html>`_ and handful of testing revisions for that platform (:ticket:`archive-13904`)
 482   * Tests for our tutorial examples (:ticket:`archive-11335`)
 483   * Revised `GitWeb <https://gitweb.torproject.org/>`_ urls to work after its upgrade
 484
 485 .. _version_1.2:
 486
 487 Version 1.2 (June 1st, 2014)
 488 ----------------------------
 489
 490 `Stem release 1.2 <https://blog.torproject.org/blog/stem-release-12>`_
 491 added our `interactive Tor interpreter <tutorials/down_the_rabbit_hole.html>`_
 492 among numerous other improvements and fixes.
 493
 494  * **Controller**
 495
 496   * New, better :func:`~stem.connection.connect` function that deprecates :func:`~stem.connection.connect_port` and :func:`~stem.connection.connect_socket_file`
 497   * Added :func:`~stem.control.Controller.is_newnym_available` and :func:`~stem.control.Controller.get_newnym_wait` methods to the :class:`~stem.control.Controller`
 498   * Added :func:`~stem.control.Controller.get_ports` and :func:`~stem.control.Controller.get_listeners` methods to the :class:`~stem.control.Controller`
 499   * Added :func:`~stem.control.Controller.drop_guards` (:ticket:`archive-10032`, :spec:`7c6c7fc`)
 500   * Added the id attribute to :class:`~stem.response.events.ORConnEvent` (:spec:`6f2919a`)
 501   * Added `support for CONN_BW events <api/response.html#stem.response.events.ConnectionBandwidthEvent>`_ (:spec:`6f2919a`)
 502   * Added `support for CIRC_BW events <api/response.html#stem.response.events.CircuitBandwidthEvent>`_ (:spec:`6f2919a`)
 503   * Added `support for CELL_STATS events <api/response.html#stem.response.events.CellStatsEvent>`_ (:spec:`6f2919a`)
 504   * Added `support for TB_EMPTY events <api/response.html#stem.response.events.TokenBucketEmptyEvent>`_ (:spec:`6f2919a`)
 505   * Added `support for HS_DESC events <api/response.html#stem.response.events.HSDescEvent>`_ (:ticket:`archive-10807`, :spec:`a67ac4d`)
 506   * Changed :func:`~stem.control.Controller.get_network_status` and :func:`~stem.control.Controller.get_network_statuses` to provide :class:`~stem.descriptor.router_status_entry.RouterStatusEntryMicroV3` if Tor is using microdescriptors (:ticket:`archive-7646`)
 507   * The :func:`~stem.connection.connect_port` and :func:`~stem.connection.connect_socket_file` didn't properly mark the Controller it returned as being authenticated, causing event listening among other things to fail
 508   * The :func:`~stem.control.Controller.add_event_listener` method couldn't accept event types that Stem didn't already recognize
 509   * The :class:`~stem.exit_policy.ExitPolicy` class couldn't be pickled
 510   * Tor instances spawned with :func:`~stem.process.launch_tor` and :func:`~stem.process.launch_tor_with_config` could hang due to unread stdout content, we now close stdout and stderr once tor finishes bootstrapping (:ticket:`archive-9862`)
 511
 512  * **Descriptors**
 513
 514   * Added tarfile support to :func:`~stem.descriptor.__init__.parse_file` (:ticket:`archive-10977`)
 515   * Added microdescriptor's new identifier and identifier_type attributes (:spec:`22cda72`)
 516
 517  * **Utilities**
 518
 519   * Added the `stem.util.test_tools <api/util/test_tools.html>`_ module
 520   * Started vending the `stem.util.tor_tools <api/util/tor_tools.html>`_ module
 521   * Added :func:`stem.util.connection.port_usage`
 522   * Added :func:`stem.util.system.files_with_suffix`
 523
 524  * **Interpreter**
 525
 526   * Initial release of our `interactive Tor interpreter <tutorials/down_the_rabbit_hole.html>`_!
 527
 528  * **Website**
 529
 530   * Added a section with `example scripts <tutorials/double_double_toil_and_trouble.html#scripts>`_.
 531   * Made FAQ and other sections quite a bit more succinct.
 532
 533  * **Version 1.2.2** (June 7th, 2014) - fixed an issue where the stem.util.conf
 534    module would fail under Python 2.6 with an AttributeError (:ticket:`archive-12223`)
 535
 536  * **Version 1.2.1** (June 3rd, 2014) - fixed an issue where descriptor
 537    parsersing would fail under Python 3.x with a TypeError (:ticket:`archive-12185`)
 538
 539 .. _version_1.1:
 540
 541 Version 1.1 (October 14th, 2013)
 542 --------------------------------
 543
 544 `Stem release 1.1 <https://blog.torproject.org/blog/stem-release-11>`_
 545 introduced `remote descriptor fetching <api/descriptor/remote.html>`_,
 546 `connection resolution <tutorials/east_of_the_sun.html#connection-resolution>`_
 547 and a myriad of smaller improvements and fixes.
 548
 549  * **Controller**
 550
 551   * :func:`~stem.control.Controller.get_network_status` and :func:`~stem.control.Controller.get_network_statuses` now provide v3 rather than v2 directory information (:ticket:`archive-7953`, :spec:`d2b7ebb`)
 552   * :class:`~stem.response.events.AddrMapEvent` support for the new CACHED argument (:ticket:`archive-8596`, :spec:`25b0d43`)
 553   * :func:`~stem.control.Controller.attach_stream` could encounter an undocumented 555 response (:ticket:`archive-8701`, :spec:`7286576`)
 554   * :class:`~stem.descriptor.server_descriptor.RelayDescriptor` digest validation was broken when dealing with non-unicode content with Python 3 (:ticket:`archive-8755`)
 555   * The :class:`~stem.control.Controller` use of cached content wasn't thread safe (:ticket:`archive-8607`)
 556   * Added :func:`~stem.control.Controller.get_user` method to the :class:`~stem.control.Controller`
 557   * Added :func:`~stem.control.Controller.get_pid` method to the :class:`~stem.control.Controller`
 558   * :class:`~stem.response.events.StreamEvent` didn't recognize IPv6 addresses (:ticket:`archive-9181`)
 559   * :func:`~stem.control.Controller.get_conf` mistakenly cached hidden service related options (:ticket:`archive-9792`)
 560   * Added `support for TRANSPORT_LAUNCHED events <api/response.html#stem.response.events.TransportLaunchedEvent>`_ (:spec:`48f6dd0`)
 561
 562  * **Descriptors**
 563
 564   * Added the `stem.descriptor.remote <api/descriptor/remote.html>`_ module.
 565   * Added support for `TorDNSEL exit lists <api/descriptor/tordnsel.html>`_ (:ticket:`archive-8255`)
 566   * The :class:`~stem.descriptor.reader.DescriptorReader` mishandled relative paths (:ticket:`archive-8815`)
 567
 568  * **Utilities**
 569
 570   * Connection resolution via the :func:`~stem.util.connection.get_connections` function (:ticket:`archive-7910`)
 571   * :func:`~stem.util.system.set_process_name` inserted spaces between characters (:ticket:`archive-8631`)
 572   * :func:`~stem.util.system.pid_by_name` can now pull for all processes with a given name
 573   * :func:`~stem.util.system.call` ignored the subprocess' exit status
 574   * Added :func:`stem.util.system.name_by_pid`
 575   * Added :func:`stem.util.system.user`
 576   * Added :func:`stem.util.system.start_time`
 577   * Added :func:`stem.util.system.bsd_jail_path`
 578   * Added :func:`stem.util.system.is_tarfile`
 579   * Added :func:`stem.util.connection.is_private_address`
 580
 581  * **Website**
 582
 583   * Overhaul of Stem's `download page <download.html>`_. This included several
 584     improvements, most notably the addition of PyPI, Ubuntu, Fedora, Slackware,
 585     and FreeBSD.
 586   * Replaced default sphinx header with a navbar menu.
 587   * Added this change log.
 588   * Added the `FAQ page <faq.html>`_.
 589   * Settled on a `logo
 590     <http://www.wpclipart.com/plants/assorted/P/plant_stem.png.html>`_ for
 591     Stem.
 592   * Expanded the `client usage tutorial <tutorials/to_russia_with_love.html>`_
 593     to cover SocksiPy and include an example for polling Twitter.
 594   * Subtler buttons for the frontpage (`before
 595     <https://www.atagar.com/transfer/stem_frontpage/before.png>`_ and `after
 596     <https://www.atagar.com/transfer/stem_frontpage/after.png>`_).
 597
 598  * **Version 1.1.1** (November 9th, 2013) - fixed an issue where imports of stem.util.system
 599    would fail with an ImportError for pwd under Windows (:ticket:`archive-10072`)
 600
 601 .. _version_1.0:
 602
 603 Version 1.0 (March 26th, 2013)
 604 ------------------------------
 605
 606 This was the `initial release of Stem
 607 <https://blog.torproject.org/blog/stem-release-10>`_.
 608
 609  * **Version 1.0.1** (March 27th, 2013) - fixed an issue where installing with
 610    Python 3.x (python3 setup.py install) resulted in a stacktrace
 611