tor-commits May 2020

tor-commits@lists.torproject.org

18 participants
1587 discussions

[collector/master] Bump version to 1.15.2-dev.
by karsten＠torproject.org 17 May '20

17 May '20

commit 52236731f8a19f33aaf0768775e0809cb9e77977 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Sun May 17 09:48:51 2020 +0200 Bump version to 1.15.2-dev. --- CHANGELOG.md | 3 +++ build.xml | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7db8dea..f1dc8ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +# Changes in version 1.??.? - 2020-??-?? + + # Changes in version 1.15.2 - 2020-05-17 * Medium changes diff --git a/build.xml b/build.xml index d2a8aad..6bf561a 100644 --- a/build.xml +++ b/build.xml @@ -9,7 +9,7 @@ <property name="javadoc-title" value="CollecTor API Documentation"/> <property name="implementation-title" value="CollecTor" /> - <property name="release.version" value="1.15.2" /> + <property name="release.version" value="1.15.2-dev" /> <property name="project-main-class" value="org.torproject.metrics.collector.Main" /> <property name="name" value="collector"/> <property name="metricslibversion" value="2.13.0" />

1 0

[stem/master] Drop :param: tag types
by atagar＠torproject.org 17 May '20

17 May '20

commit 8634aa04114e74dc5f94875113f9b44549305368 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat May 16 18:29:05 2020 -0700 Drop :param: tag types Between our Python type hints and sphinx_autodoc_typehints our reStructured :param: tags no longer use their type. As such we can drop 'em. --- stem/client/__init__.py | 20 +-- stem/client/cell.py | 42 +++--- stem/client/datatype.py | 8 +- stem/connection.py | 61 ++++---- stem/control.py | 245 ++++++++++++++++---------------- stem/descriptor/__init__.py | 97 +++++++------ stem/descriptor/bandwidth_file.py | 6 +- stem/descriptor/certificate.py | 12 +- stem/descriptor/collector.py | 118 +++++++-------- stem/descriptor/extrainfo_descriptor.py | 20 +-- stem/descriptor/hidden_service.py | 71 +++++---- stem/descriptor/microdescriptor.py | 12 +- stem/descriptor/networkstatus.py | 49 +++---- stem/descriptor/remote.py | 47 +++--- stem/descriptor/router_status_entry.py | 26 ++-- stem/descriptor/server_descriptor.py | 22 +-- stem/directory.py | 18 +-- stem/exit_policy.py | 20 +-- stem/interpreter/arguments.py | 2 +- stem/interpreter/autocomplete.py | 6 +- stem/interpreter/commands.py | 8 +- stem/interpreter/help.py | 4 +- stem/manual.py | 24 ++-- stem/process.py | 32 ++--- stem/response/__init__.py | 46 +++--- stem/response/events.py | 8 +- stem/response/getinfo.py | 2 +- stem/socket.py | 32 ++--- stem/util/__init__.py | 10 +- stem/util/conf.py | 54 +++---- stem/util/connection.py | 44 +++--- stem/util/enum.py | 10 +- stem/util/log.py | 16 +-- stem/util/proc.py | 36 ++--- stem/util/str_tools.py | 66 ++++----- stem/util/system.py | 61 ++++---- stem/util/term.py | 6 +- stem/util/test_tools.py | 30 ++-- stem/util/tor_tools.py | 22 +-- stem/version.py | 4 +- 40 files changed, 702 insertions(+), 715 deletions(-) diff --git a/stem/client/__init__.py b/stem/client/__init__.py index 8726bdbf..639f118f 100644 --- a/stem/client/__init__.py +++ b/stem/client/__init__.py @@ -79,9 +79,9 @@ class Relay(object): """ Establishes a connection with the given ORPort. - :param str address: ip address of the relay - :param int port: ORPort of the relay - :param tuple link_protocols: acceptable link protocol versions + :param address: ip address of the relay + :param port: ORPort of the relay + :param link_protocols: acceptable link protocol versions :raises: * **ValueError** if address or port are invalid @@ -156,7 +156,7 @@ class Relay(object): Reads the next cell from our ORPort. If none is present this blocks until one is available. - :param bool raw: provides bytes rather than parsing as a cell if **True** + :param raw: provides bytes rather than parsing as a cell if **True** :returns: next :class:`~stem.client.cell.Cell` """ @@ -212,7 +212,7 @@ class Relay(object): It's quite possible this is a stupid approach. If so, patches welcome. - :param stem.client.cell.Cell cell: cell to be sent + :param cell: cell to be sent :returns: **generator** with the cells received in reply """ @@ -331,8 +331,8 @@ class Circuit(object): """ Request descriptors from the relay. - :param str request: directory request to make - :param int stream_id: specific stream this concerns + :param request: directory request to make + :param stream_id: specific stream this concerns :returns: **str** with the requested descriptor data """ @@ -366,9 +366,9 @@ class Circuit(object): """ Sends a message over the circuit. - :param stem.client.datatype.RelayCommand command: command to be issued - :param bytes data: message payload - :param int stream_id: specific stream this concerns + :param command: command to be issued + :param data: message payload + :param stream_id: specific stream this concerns """ with self.relay._orport_lock: diff --git a/stem/client/cell.py b/stem/client/cell.py index c88ba716..dad962f2 100644 --- a/stem/client/cell.py +++ b/stem/client/cell.py @@ -107,7 +107,7 @@ class Cell(object): """ Provides cell attributes by its name. - :param str name: cell command to fetch + :param name: cell command to fetch :returns: cell class with this name @@ -125,7 +125,7 @@ class Cell(object): """ Provides cell attributes by its value. - :param int value: cell value to fetch + :param value: cell value to fetch :returns: cell class with this numeric value @@ -146,8 +146,8 @@ class Cell(object): """ Unpacks all cells from a response. - :param bytes content: payload to decode - :param int link_protocol: link protocol version + :param content: payload to decode + :param link_protocol: link protocol version :returns: :class:`~stem.client.cell.Cell` generator @@ -165,8 +165,8 @@ class Cell(object): """ Unpacks the first cell. - :param bytes content: payload to decode - :param int link_protocol: link protocol version + :param content: payload to decode + :param link_protocol: link protocol version :returns: (:class:`~stem.client.cell.Cell`, remainder) tuple @@ -204,10 +204,10 @@ class Cell(object): Fixed: [ CircuitID ][ Command ][ Payload ][ Padding ] Variable: [ CircuitID ][ Command ][ Size ][ Payload ] - :param str name: cell command - :param int link_protocol: link protocol version - :param bytes payload: cell payload - :param int circ_id: circuit id, if a CircuitCell + :param name: cell command + :param link_protocol: link protocol version + :param payload: cell payload + :param circ_id: circuit id, if a CircuitCell :returns: **bytes** with the encoded payload @@ -251,9 +251,9 @@ class Cell(object): """ Subclass implementation for unpacking cell content. - :param bytes content: payload to decode - :param int circ_id: circuit id cell is for - :param stem.client.datatype.LinkProtocol link_protocol: link protocol version + :param content: payload to decode + :param circ_id: circuit id cell is for + :param link_protocol: link protocol version :returns: instance of this cell type @@ -402,11 +402,10 @@ class RelayCell(CircuitCell): (cell (RelayCell), new_key (CipherContext), new_digest (HASH)) - :param int link_protocol: link protocol version - :param bytes content: cell content to be decrypted - :param cryptography.hazmat.primitives.ciphers.CipherContext key: - key established with the relay we received this cell from - :param hashlib.HASH digest: running digest held with the relay + :param link_protocol: link protocol version + :param content: cell content to be decrypted + :param key: key established with the relay we received this cell from + :param digest: running digest held with the relay :returns: **tuple** with our decrypted cell and updated key/digest @@ -456,10 +455,9 @@ class RelayCell(CircuitCell): (payload (bytes), new_key (CipherContext), new_digest (HASH)) - :param int link_protocol: link protocol version - :param cryptography.hazmat.primitives.ciphers.CipherContext key: - key established with the relay we're sending this cell to - :param hashlib.HASH digest: running digest held with the relay + :param link_protocol: link protocol version + :param key: key established with the relay we're sending this cell to + :param digest: running digest held with the relay :returns: **tuple** with our encrypted payload and updated key/digest """ diff --git a/stem/client/datatype.py b/stem/client/datatype.py index acc9ec34..527fdb12 100644 --- a/stem/client/datatype.py +++ b/stem/client/datatype.py @@ -252,8 +252,8 @@ def split(content: bytes, size: int) -> Tuple[bytes, bytes]: """ Simple split of bytes into two substrings. - :param bytes content: string to split - :param int size: index to split the string on + :param content: string to split + :param size: index to split the string on :returns: two value tuple with the split bytes """ @@ -326,7 +326,7 @@ class Field(object): """ Decodes bytes into a field of this type. - :param bytes packed: content to decode + :param packed: content to decode :returns: instance of this class @@ -345,7 +345,7 @@ class Field(object): """ Decodes bytes as this field type, providing it and the remainder. - :param bytes packed: content to decode + :param packed: content to decode :returns: tuple of the form (unpacked, remainder) diff --git a/stem/connection.py b/stem/connection.py index ff950a0c..0ce2a153 100644 --- a/stem/connection.py +++ b/stem/connection.py @@ -235,13 +235,13 @@ def connect(control_port: Tuple[str, Union[str, int]] = ('127.0.0.1', 'default') .. versionchanged:: 1.5.0 Use both port 9051 and 9151 by default. - :param tuple contol_port: address and port tuple, for instance **('127.0.0.1', 9051)** - :param str control_socket: path where the control socket is located - :param str password: passphrase to authenticate to the socket - :param bool password_prompt: prompt for the controller password if it wasn't + :param contol_port: address and port tuple, for instance **('127.0.0.1', 9051)** + :param control_socket: path where the control socket is located + :param password: passphrase to authenticate to the socket + :param password_prompt: prompt for the controller password if it wasn't supplied - :param str chroot_path: path prefix if in a chroot environment - :param Class controller: :class:`~stem.control.BaseController` subclass to be + :param chroot_path: path prefix if in a chroot environment + :param controller: :class:`~stem.control.BaseController` subclass to be returned, this provides a :class:`~stem.socket.ControlSocket` if **None** :returns: authenticated control connection, the type based on the controller argument @@ -305,12 +305,12 @@ def _connect_auth(control_socket: stem.socket.ControlSocket, password: str, pass Helper for the connect_* functions that authenticates the socket and constructs the controller. - :param stem.socket.ControlSocket control_socket: socket being authenticated to - :param str password: passphrase to authenticate to the socket - :param bool password_prompt: prompt for the controller password if it wasn't + :param control_socket: socket being authenticated to + :param password: passphrase to authenticate to the socket + :param password_prompt: prompt for the controller password if it wasn't supplied - :param str chroot_path: path prefix if in a chroot environment - :param Class controller: :class:`~stem.control.BaseController` subclass to be + :param chroot_path: path prefix if in a chroot environment + :param controller: :class:`~stem.control.BaseController` subclass to be returned, this provides a :class:`~stem.socket.ControlSocket` if **None** :returns: authenticated control connection, the type based on the controller argument @@ -381,10 +381,10 @@ def authenticate(controller: Union[stem.control.BaseController, stem.socket.Cont :class:`~stem.socket.ControlSocket`. :param controller: tor controller or socket to be authenticated - :param str password: passphrase to present to the socket if it uses password + :param password: passphrase to present to the socket if it uses password authentication (skips password auth if **None**) - :param str chroot_path: path prefix if in a chroot environment - :param stem.response.protocolinfo.ProtocolInfoResponse protocolinfo_response: + :param chroot_path: path prefix if in a chroot environment + :param protocolinfo_response: tor protocolinfo response, this is retrieved on our own if **None** :raises: If all attempts to authenticate fails then this will raise a @@ -597,7 +597,7 @@ def authenticate_none(controller: Union[stem.control.BaseController, stem.socket instead. :param controller: tor controller or socket to be authenticated - :param bool suppress_ctl_errors: reports raised + :param suppress_ctl_errors: reports raised :class:`~stem.ControllerError` as authentication rejection if **True**, otherwise they're re-raised @@ -649,8 +649,8 @@ def authenticate_password(controller: Union[stem.control.BaseController, stem.so instead. :param controller: tor controller or socket to be authenticated - :param str password: passphrase to present to the socket - :param bool suppress_ctl_errors: reports raised + :param password: passphrase to present to the socket + :param suppress_ctl_errors: reports raised :class:`~stem.ControllerError` as authentication rejection if **True**, otherwise they're re-raised @@ -726,8 +726,8 @@ def authenticate_cookie(controller: Union[stem.control.BaseController, stem.sock instead. :param controller: tor controller or socket to be authenticated - :param str cookie_path: path of the authentication cookie to send to tor - :param bool suppress_ctl_errors: reports raised + :param cookie_path: path of the authentication cookie to send to tor + :param suppress_ctl_errors: reports raised :class:`~stem.ControllerError` as authentication rejection if **True**, otherwise they're re-raised @@ -823,8 +823,8 @@ def authenticate_safecookie(controller: Union[stem.control.BaseController, stem. instead. :param controller: tor controller or socket to be authenticated - :param str cookie_path: path of the authentication cookie to send to tor - :param bool suppress_ctl_errors: reports raised + :param cookie_path: path of the authentication cookie to send to tor + :param suppress_ctl_errors: reports raised :class:`~stem.ControllerError` as authentication rejection if **True**, otherwise they're re-raised @@ -1001,7 +1001,7 @@ def _connection_for_default_port(address: str) -> stem.socket.ControlPort: relays) or 9151 (default for Tor Browser). If both fail then this raises the exception for port 9051. - :param str address: address to connect to + :param address: address to connect to :returns: :class:`~stem.socket.ControlPort` for the controller conneciton @@ -1021,8 +1021,8 @@ def _read_cookie(cookie_path: str, is_safecookie: bool) -> bytes: """ Provides the contents of a given cookie file. - :param str cookie_path: absolute path of the cookie file - :param bool is_safecookie: **True** if this was for SAFECOOKIE + :param cookie_path: absolute path of the cookie file + :param is_safecookie: **True** if this was for SAFECOOKIE authentication, **False** if for COOKIE :returns: **bytes** with the cookie file content @@ -1065,8 +1065,8 @@ def _hmac_sha256(key: bytes, msg: bytes) -> bytes: """ Generates a sha256 digest using the given key and message. - :param bytes key: starting key for the hash - :param bytes msg: message to be hashed + :param key: starting key for the hash + :param msg: message to be hashed :returns: sha256 digest of msg as bytes, hashed using the given key """ @@ -1131,11 +1131,10 @@ class CookieAuthFailed(AuthenticationFailure): """ Failure to authenticate with an authentication cookie. - :param str cookie_path: location of the authentication cookie we attempted - :param bool is_safecookie: **True** if this was for SAFECOOKIE + :param cookie_path: location of the authentication cookie we attempted + :param is_safecookie: **True** if this was for SAFECOOKIE authentication, **False** if for COOKIE - :param stem.response.ControlMessage auth_response: reply to our - authentication attempt + :param auth_response: reply to our authentication attempt """ def __init__(self, message: str, cookie_path: str, is_safecookie: bool, auth_response: Optional[stem.response.ControlMessage] = None) -> None: @@ -1210,7 +1209,7 @@ class NoAuthCookie(MissingAuthInfo): """ PROTOCOLINFO response supports cookie auth but doesn't have its path. - :param bool is_safecookie: **True** if this was for SAFECOOKIE + :param is_safecookie: **True** if this was for SAFECOOKIE authentication, **False** if for COOKIE """ diff --git a/stem/control.py b/stem/control.py index 626b2b3e..ec88aa38 100644 --- a/stem/control.py +++ b/stem/control.py @@ -504,7 +504,7 @@ def event_description(event: str) -> str: """ Provides a description for Tor events. - :param str event: the event for which a description is needed + :param event: the event for which a description is needed :returns: **str** The event description or **None** if this is an event name we don't have a description for @@ -584,7 +584,7 @@ class BaseController(object): """ Sends a message to our control socket and provides back its reply. - :param str message: message to be formatted and sent to tor + :param message: message to be formatted and sent to tor :returns: :class:`~stem.response.ControlMessage` with the response @@ -779,8 +779,8 @@ class BaseController(object): callback could block for a while. If still outstanding these threads are joined on as part of closing this controller. - :param function callback: function to be notified when our state changes - :param bool spawn: calls function via a new thread if **True**, otherwise + :param callback: function to be notified when our state changes + :param spawn: calls function via a new thread if **True**, otherwise it's part of the connect/close method call """ @@ -791,7 +791,7 @@ class BaseController(object): """ Stops listener from being notified of further events. - :param function callback: function to be removed from our listeners + :param callback: function to be removed from our listeners :returns: **bool** that's **True** if we removed one or more occurrences of the callback, **False** otherwise @@ -820,8 +820,7 @@ class BaseController(object): Callback to be overwritten by subclasses for event listening. This is notified whenever we receive an event from the control socket. - :param stem.response.ControlMessage event_message: message received from - the control socket + :param event_message: message received from the control socket """ pass @@ -859,7 +858,7 @@ class BaseController(object): """ Informs our status listeners that a state change occurred. - :param stem.control.State state: state change that has occurred + :param state: state change that has occurred """ # Any changes to our is_alive() state happen under the send lock, so we @@ -997,8 +996,8 @@ class Controller(BaseController): .. versionchanged:: 1.5.0 Use both port 9051 and 9151 by default. - :param str address: ip address of the controller - :param int port: port number of the controller + :param address: ip address of the controller + :param port: port number of the controller :returns: :class:`~stem.control.Controller` attached to the given port @@ -1024,7 +1023,7 @@ class Controller(BaseController): """ Constructs a :class:`~stem.socket.ControlSocketFile` based Controller. - :param str path: path where the control socket is located + :param path: path where the control socket is located :returns: :class:`~stem.control.Controller` attached to the given socket file @@ -1128,9 +1127,9 @@ class Controller(BaseController): Errors commonly provided a :class:`stem.ProtocolError` when we should raise a :class:`stem.OperationFailed`. - :param str,list params: GETINFO option or options to be queried - :param object default: response if the query fails - :param bool get_bytes: provides **bytes** values rather than a **str** under python 3.x + :param params: GETINFO option or options to be queried + :param default: response if the query fails + :param get_bytes: provides **bytes** values rather than a **str** under python 3.x :returns: Response depends upon how we were called as follows... @@ -1242,7 +1241,7 @@ class Controller(BaseController): A convenience method to get tor version that current controller is connected to. - :param object default: response if the query fails + :param default: response if the query fails :returns: :class:`~stem.version.Version` of the tor instance that we're connected to @@ -1275,7 +1274,7 @@ class Controller(BaseController): parsing the user's torrc entries. This should be more reliable for some edge cases. (:trac:`25739`) - :param object default: response if the query fails + :param default: response if the query fails :returns: :class:`~stem.exit_policy.ExitPolicy` of the tor instance that we're connected to @@ -1307,9 +1306,8 @@ class Controller(BaseController): .. versionadded:: 1.2.0 - :param stem.control.Listener listener_type: connection type being handled - by the ports we return - :param object default: response if the query fails + :param listener_type: connection type being handled by the ports we return + :param default: response if the query fails :returns: **list** of **ints** for the local ports where tor handles connections of the given type @@ -1347,9 +1345,8 @@ class Controller(BaseController): .. versionchanged:: 1.5.0 Recognize listeners with IPv6 addresses. - :param stem.control.Listener listener_type: connection type being handled - by the listeners we return - :param object default: response if the query fails + :param listener_type: connection type handled by listeners we return + :param default: response if the query fails :returns: **list** of **(address, port)** tuples for the available listeners @@ -1448,7 +1445,7 @@ class Controller(BaseController): .. versionadded:: 1.3.0 - :param object default: response if the query fails + :param default: response if the query fails :returns: :class:`~stem.control.AccountingStats` with our accounting stats @@ -1489,7 +1486,7 @@ class Controller(BaseController): A convenience method to get the protocol info of the controller. - :param object default: response if the query fails + :param default: response if the query fails :returns: :class:`~stem.response.protocolinfo.ProtocolInfoResponse` provided by tor @@ -1516,7 +1513,7 @@ class Controller(BaseController): .. versionadded:: 1.1.0 - :param object default: response if the query fails + :param default: response if the query fails :returns: str with the username tor is running as """ @@ -1551,7 +1548,7 @@ class Controller(BaseController): .. versionadded:: 1.1.0 - :param object default: response if the query fails + :param default: response if the query fails :returns: **int** for tor's pid @@ -1605,7 +1602,7 @@ class Controller(BaseController): .. versionadded:: 1.8.0 - :param object default: response if the query fails + :param default: response if the query fails :returns: **float** for the unix timestamp of when the tor process began @@ -1655,7 +1652,7 @@ class Controller(BaseController): .. versionadded:: 1.8.0 - :param object default: response if the query fails + :param default: response if the query fails :returns: **float** for the number of seconds tor has been running @@ -1723,8 +1720,8 @@ class Controller(BaseController): .. 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 + :param relay: fingerprint or nickname of the relay to be queried + :param default: response if the query fails :returns: :class:`~stem.descriptor.microdescriptor.Microdescriptor` for the given relay @@ -1777,7 +1774,7 @@ class Controller(BaseController): directly from disk instead, which will not work remotely or if our process lacks read permissions. - :param list default: items to provide if the query fails + :param default: items to provide if the query fails :returns: iterates over :class:`~stem.descriptor.microdescriptor.Microdescriptor` for relays in @@ -1817,8 +1814,8 @@ class Controller(BaseController): .. 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 + :param relay: fingerprint or nickname of the relay to be queried + :param default: response if the query fails :returns: :class:`~stem.descriptor.server_descriptor.RelayDescriptor` for the given relay @@ -1871,7 +1868,7 @@ class Controller(BaseController): really need server descriptors then you can get them by setting 'UseMicrodescriptors 0'. - :param list default: items to provide if the query fails + :param default: items to provide if the query fails :returns: iterates over :class:`~stem.descriptor.server_descriptor.RelayDescriptor` for relays in @@ -1911,8 +1908,8 @@ class Controller(BaseController): .. 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 + :param relay: fingerprint or nickname of the relay to be queried + :param default: response if the query fails :returns: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` for the given relay @@ -1961,7 +1958,7 @@ class Controller(BaseController): Provides an iterator for all of the router status entries that tor currently knows about. - :param list default: items to provide if the query fails + :param default: items to provide if the query fails :returns: iterates over :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` for @@ -2009,10 +2006,10 @@ class Controller(BaseController): .. versionchanged:: 1.7.0 Added the timeout argument. - :param str address: address of the hidden service descriptor, the '.onion' suffix is optional - :param object default: response if the query fails - :param list servers: requrest the descriptor from these specific servers - :param float timeout: seconds to wait when **await_result** is **True** + :param address: address of the hidden service descriptor, the '.onion' suffix is optional + :param default: response if the query fails + :param servers: requrest the descriptor from these specific servers + :param timeout: seconds to wait when **await_result** is **True** :returns: :class:`~stem.descriptor.hidden_service.HiddenServiceDescriptorV2` for the given service if **await_result** is **True**, or **None** otherwise @@ -2107,9 +2104,9 @@ class Controller(BaseController): provides **None** if **multiple** was **False** and an empty list if it was **True**. - :param str param: configuration option to be queried - :param object default: response if the option is unset or the query fails - :param bool multiple: if **True** then provides a list with all of the + :param param: configuration option to be queried + :param default: response if the option is unset or the query fails + :param multiple: if **True** then provides a list with all of the present values (this is an empty list if the config option is unset) :returns: @@ -2173,10 +2170,10 @@ class Controller(BaseController): **Note:** HiddenServiceOptions are best retrieved via the :func:`~stem.control.Controller.get_hidden_service_conf` method instead. - :param str,list params: configuration option(s) to be queried - :param object default: value for the mappings if the configuration option + :param params: configuration option(s) to be queried + :param default: value for the mappings if the configuration option is either undefined or the query fails - :param bool multiple: if **True** then the values provided are lists with + :param multiple: if **True** then the values provided are lists with all of the present values :returns: @@ -2294,8 +2291,8 @@ class Controller(BaseController): .. versionadded:: 1.5.0 - :param str param: configuration option to check - :param object default: response if the query fails + :param param: configuration option to check + :param default: response if the query fails :returns: **True** if option differs from its default and **False** otherwise @@ -2342,8 +2339,8 @@ class Controller(BaseController): * a list of strings to set a series of values (for instance the ExitPolicy) * None to either set the value to 0/NULL - :param str param: configuration option to be set - :param str,list value: value to set the parameter to + :param param: configuration option to be set + :param value: value to set the parameter to :raises: * :class:`stem.ControllerError` if the call fails @@ -2359,7 +2356,7 @@ class Controller(BaseController): """ Reverts one or more parameters to their default values. - :param str params: configuration option to be reset + :param params: configuration option to be reset :raises: * :class:`stem.ControllerError` if the call fails @@ -2391,9 +2388,9 @@ class Controller(BaseController): reason this type of argument would be useful is for hidden service configuration (those options are order dependent). - :param dict,list params: mapping of configuration options to the values + :param params: mapping of configuration options to the values we're setting it to - :param bool reset: issues a RESETCONF, returning **None** values to their + :param reset: issues a RESETCONF, returning **None** values to their defaults if **True** :raises: @@ -2478,7 +2475,7 @@ class Controller(BaseController): .. versionadded:: 1.3.0 - :param object default: response if the query fails + :param default: response if the query fails :returns: **dict** with the hidden service configuration @@ -2569,7 +2566,7 @@ class Controller(BaseController): .. versionadded:: 1.3.0 - :param dict conf: configuration dictionary + :param conf: configuration dictionary :raises: * :class:`stem.ControllerError` if the call fails @@ -2628,13 +2625,13 @@ class Controller(BaseController): .. versionchanged:: 1.4.0 Added the auth_type and client_names arguments. - :param str path: path for the hidden service's data directory - :param int port: hidden service port - :param str target_address: address of the service, by default 127.0.0.1 - :param int target_port: port of the service, by default this is the same as + :param path: path for the hidden service's data directory + :param port: hidden service port + :param target_address: address of the service, by default 127.0.0.1 + :param target_port: port of the service, by default this is the same as **port** - :param str auth_type: authentication type: basic, stealth or None to disable auth - :param list client_names: client names (1-16 characters "A-Za-z0-9+-_") + :param auth_type: authentication type: basic, stealth or None to disable auth + :param client_names: client names (1-16 characters "A-Za-z0-9+-_") :returns: :class:`~stem.control.CreateHiddenServiceOutput` if we create or update a hidden service, **None** otherwise @@ -2734,8 +2731,8 @@ class Controller(BaseController): .. versionadded:: 1.3.0 - :param str path: path for the hidden service's data directory - :param int port: hidden service port + :param path: path for the hidden service's data directory + :param port: hidden service port :returns: **True** if the hidden service is discontinued, **False** if it wasn't running in the first place @@ -2783,10 +2780,10 @@ class Controller(BaseController): Tor change caused this to start providing empty strings if unset (:trac:`21329`). - :param object default: response if the query fails - :param bool our_services: include services created with this controller + :param default: response if the query fails + :param our_services: include services created with this controller that weren't flagged as 'detached' - :param bool detached: include services whos contiuation isn't tied to a + :param detached: include services whos contiuation isn't tied to a controller :returns: **list** of hidden service addresses without their '.onion' @@ -2888,21 +2885,21 @@ class Controller(BaseController): .. versionchanged:: 1.7.0 Added the timeout and max_streams arguments. - :param int,list,dict ports: hidden service port(s) or mapping of hidden + :param ports: hidden service port(s) or mapping of hidden service ports to their targets - :param str key_type: type of key being provided, generates a new key if + :param key_type: type of key being provided, generates a new key if 'NEW' (options are: **NEW**, **RSA1024**, and **ED25519-V3**) - :param str key_content: key for the service to use or type of key to be + :param key_content: key for the service to use or type of key to be generated (options when **key_type** is **NEW** are **BEST**, **RSA1024**, and **ED25519-V3**) - :param bool discard_key: avoid providing the key back in our response - :param bool detached: continue this hidden service even after this control + :param discard_key: avoid providing the key back in our response + :param detached: continue this hidden service even after this control connection is closed if **True** - :param bool await_publication: blocks until our descriptor is successfully + :param await_publication: blocks until our descriptor is successfully published if **True** - :param float timeout: seconds to wait when **await_result** is **True** - :param dict basic_auth: required user credentials to access this service - :param int max_streams: maximum number of streams the hidden service will + :param timeout: seconds to wait when **await_result** is **True** + :param basic_auth: required user credentials to access this service + :param max_streams: maximum number of streams the hidden service will accept, unlimited if zero or not set :returns: :class:`~stem.response.add_onion.AddOnionResponse` with the response @@ -3001,7 +2998,7 @@ class Controller(BaseController): .. versionadded:: 1.4.0 - :param str service_id: hidden service address without the '.onion' suffix + :param service_id: hidden service address without the '.onion' suffix :returns: **True** if the hidden service is discontinued, **False** if it wasn't running in the first place @@ -3048,8 +3045,8 @@ class Controller(BaseController): Listener exceptions and malformed events no longer break further event processing. Added the **MALFORMED_EVENTS** constant. - :param functor listener: function to be called when an event is received - :param stem.control.EventType events: event types to be listened for + :param listener: function to be called when an event is received + :param events: event types to be listened for :raises: :class:`stem.ProtocolError` if unable to set the events """ @@ -3080,7 +3077,7 @@ class Controller(BaseController): """ Stops a listener from being notified of further tor events. - :param stem.control.EventListener listener: listener to be removed + :param listener: listener to be removed :raises: :class:`stem.ProtocolError` if unable to set the events """ @@ -3106,8 +3103,8 @@ class Controller(BaseController): """ Queries our request cache for the given key. - :param str param: key to be queried - :param str namespace: namespace in which to check for the key + :param param: key to be queried + :param namespace: namespace in which to check for the key :returns: cached value corresponding to key or **None** if the key wasn't found """ @@ -3123,8 +3120,8 @@ class Controller(BaseController): """ Queries our request cache for multiple entries. - :param list params: keys to be queried - :param str namespace: namespace in which to check for the keys + :param params: keys to be queried + :param namespace: namespace in which to check for the keys :returns: **dict** of 'param => cached value' pairs of keys present in cache """ @@ -3146,8 +3143,8 @@ class Controller(BaseController): Sets the given request cache entries. If the new cache value is **None** then it is removed from our cache. - :param dict params: **dict** of 'cache_key => value' pairs to be cached - :param str namespace: namespace for the keys + :param params: **dict** of 'cache_key => value' pairs to be cached + :param namespace: namespace for the keys """ with self._cache_lock: @@ -3187,7 +3184,7 @@ class Controller(BaseController): """ Drops dependent portions of the cache when configuration changes. - :param dict params: **dict** of 'config_key => value' pairs for configs + :param params: **dict** of 'config_key => value' pairs for configs that changed. The entries' values are currently unused. """ @@ -3220,7 +3217,7 @@ class Controller(BaseController): """ Enables or disables caching of information retrieved from tor. - :param bool enabled: **True** to enable caching, **False** to disable it + :param enabled: **True** to enable caching, **False** to disable it """ self._is_caching_enabled = enabled @@ -3242,7 +3239,7 @@ class Controller(BaseController): Sends the configuration text to Tor and loads it as if it has been read from the torrc. - :param str configtext: the configuration text + :param configtext: the configuration text :raises: :class:`stem.ControllerError` if the call fails """ @@ -3263,7 +3260,7 @@ class Controller(BaseController): .. versionchanged:: 1.6.0 Added the force argument. - :param bool force: overwrite the configuration even if it includes a + :param force: overwrite the configuration even if it includes a '%include' clause, this is ignored if tor doesn't support it :raises: @@ -3286,7 +3283,7 @@ class Controller(BaseController): Checks if a control connection feature is enabled. These features can be enabled using :func:`~stem.control.Controller.enable_feature`. - :param str feature: feature to be checked + :param feature: feature to be checked :returns: **True** if feature is enabled, **False** otherwise """ @@ -3305,7 +3302,7 @@ class Controller(BaseController): control connection must be opened to get a connection with the feature disabled. Feature names are case-insensitive. - :param str,list features: a single feature or a list of features to be enabled + :param features: a single feature or a list of features to be enabled :raises: * :class:`stem.ControllerError` if the call fails @@ -3337,8 +3334,8 @@ class Controller(BaseController): Provides a circuit currently available from tor. - :param int circuit_id: circuit to be fetched - :param object default: response if the query fails + :param circuit_id: circuit to be fetched + :param default: response if the query fails :returns: :class:`stem.response.events.CircuitEvent` for the given circuit @@ -3362,7 +3359,7 @@ class Controller(BaseController): Provides tor's currently available circuits. - :param object default: response if the query fails + :param default: response if the query fails :returns: **list** of :class:`stem.response.events.CircuitEvent` for our circuits @@ -3386,10 +3383,10 @@ class Controller(BaseController): .. versionchanged:: 1.7.0 Added the timeout argument. - :param str,list path: one or more relays to make a circuit through - :param str purpose: 'general' or 'controller' - :param bool await_build: blocks until the circuit is built if **True** - :param float timeout: seconds to wait when **await_build** is **True** + :param path: one or more relays to make a circuit through + :param purpose: 'general' or 'controller' + :param await_build: blocks until the circuit is built if **True** + :param timeout: seconds to wait when **await_build** is **True** :returns: str of the circuit id of the newly created circuit @@ -3423,12 +3420,12 @@ class Controller(BaseController): .. versionchanged:: 1.7.0 Added the timeout argument. - :param str circuit_id: id of a circuit to be extended - :param str,list path: one or more relays to make a circuit through, this is + :param circuit_id: id of a circuit to be extended + :param path: one or more relays to make a circuit through, this is required if the circuit id is non-zero - :param str purpose: 'general' or 'controller' - :param bool await_build: blocks until the circuit is built if **True** - :param float timeout: seconds to wait when **await_build** is **True** + :param purpose: 'general' or 'controller' + :param await_build: blocks until the circuit is built if **True** + :param timeout: seconds to wait when **await_build** is **True** :returns: str of the circuit id of the created or extended circuit @@ -3501,8 +3498,8 @@ class Controller(BaseController): * general * controller - :param str circuit_id: id of the circuit whose purpose is to be changed - :param str purpose: purpose (either 'general' or 'controller') + :param circuit_id: id of the circuit whose purpose is to be changed + :param purpose: purpose (either 'general' or 'controller') :raises: :class:`stem.InvalidArguments` if the circuit doesn't exist or if the purpose was invalid """ @@ -3519,8 +3516,8 @@ class Controller(BaseController): """ Closes the specified circuit. - :param str circuit_id: id of the circuit to be closed - :param str flag: optional value to modify closing, the only flag available + :param circuit_id: id of the circuit to be closed + :param flag: optional value to modify closing, the only flag available is 'IfUnused' which will not close the circuit unless it is unused :raises: @@ -3545,7 +3542,7 @@ class Controller(BaseController): Provides the list of streams tor is currently handling. - :param object default: response if the query fails + :param default: response if the query fails :returns: list of :class:`stem.response.events.StreamEvent` objects @@ -3569,9 +3566,9 @@ class Controller(BaseController): Note: Tor attaches streams to circuits automatically unless the __LeaveStreamsUnattached configuration variable is set to '1' - :param str stream_id: id of the stream that must be attached - :param str circuit_id: id of the circuit to which it must be attached - :param int exiting_hop: hop in the circuit where traffic should exit + :param stream_id: id of the stream that must be attached + :param circuit_id: id of the circuit to which it must be attached + :param exiting_hop: hop in the circuit where traffic should exit :raises: * :class:`stem.InvalidRequest` if the stream or circuit id were unrecognized @@ -3600,9 +3597,9 @@ class Controller(BaseController): """ Closes the specified stream. - :param str stream_id: id of the stream to be closed - :param stem.RelayEndReason reason: reason the stream is closing - :param str flag: not currently used + :param stream_id: id of the stream to be closed + :param reason: reason the stream is closing + :param flag: not currently used :raises: * :class:`stem.InvalidArguments` if the stream or reason are not recognized @@ -3628,7 +3625,7 @@ class Controller(BaseController): """ Sends a signal to the Tor client. - :param stem.Signal signal: type of signal to be sent + :param signal: type of signal to be sent :raises: * :class:`stem.ControllerError` if sending the signal failed @@ -3688,8 +3685,8 @@ class Controller(BaseController): .. versionadded:: 1.3.0 - :param object default: response if the query fails - :param bool burst: provides the burst bandwidth, otherwise this provides + :param default: response if the query fails + :param burst: provides the burst bandwidth, otherwise this provides the standard rate :returns: **int** with the effective bandwidth rate in bytes per second @@ -3725,7 +3722,7 @@ class Controller(BaseController): original address is already mapped to a different address the mapping is removed. - :param dict mapping: mapping of original addresses to replacement addresses + :param mapping: mapping of original addresses to replacement addresses :returns: **dict** with 'original -> replacement' address mappings @@ -3880,7 +3877,7 @@ def _parse_circ_path(path: str) -> Sequence[Tuple[str, str]]: example: $E57A476CD4DFBD99B4EE52A100A58610AD6E80B9,hamburgerphone,PrivacyRepublic14 - :param str path: circuit path to be parsed + :param path: circuit path to be parsed :returns: list of **(fingerprint, nickname)** tuples, fingerprints do not have a proceeding '$' @@ -3902,7 +3899,7 @@ def _parse_circ_entry(entry: str) -> Tuple[str, str]: Parses a single relay's 'LongName' or 'ServerID'. See the :func:`~stem.control._parse_circ_path` function for more information. - :param str entry: relay information to be parsed + :param entry: relay information to be parsed :returns: **(fingerprint, nickname)** tuple @@ -3940,9 +3937,9 @@ def _case_insensitive_lookup(entries: Union[Sequence[str], Mapping[str, Any]], k Makes a case insensitive lookup within a list or dictionary, providing the first matching entry that we come across. - :param list,dict entries: list or dictionary to be searched - :param str key: entry or key value to look up - :param object default: value to be returned if the key doesn't exist + :param entries: list or dictionary to be searched + :param key: entry or key value to look up + :param default: value to be returned if the key doesn't exist :returns: case insensitive match or default if one was provided and key wasn't found diff --git a/stem/descriptor/__init__.py b/stem/descriptor/__init__.py index 477e15e9..5ffefcbc 100644 --- a/stem/descriptor/__init__.py +++ b/stem/descriptor/__init__.py @@ -231,7 +231,7 @@ class _Compression(object): """ Decompresses the given content via this method. - :param bytes content: content to be decompressed + :param content: content to be decompressed :returns: **bytes** with the decompressed content @@ -355,15 +355,15 @@ def parse_file(descriptor_file: Union[str, BinaryIO, tarfile.TarFile, IO[bytes]] my_descriptor_file = open(descriptor_path, 'rb') - :param str,file,tarfile descriptor_file: path or opened file with the descriptor contents - :param str descriptor_type: `descriptor type <https://metrics.torproject.org/collector.html#data-formats>`_, this is guessed if not provided - :param bool validate: checks the validity of the descriptor's content if - **True**, skips these checks otherwise - :param stem.descriptor.__init__.DocumentHandler document_handler: method in - which to parse the :class:`~stem.descriptor.networkstatus.NetworkStatusDocument` - :param bool normalize_newlines: converts windows newlines (CRLF), this is the + :param descriptor_file: path or opened file with the descriptor contents + :param descriptor_type: `descriptor type <https://metrics.torproject.org/collector.html#data-formats>`_, this is guessed if not provided + :param validate: checks the validity of the descriptor's content if **True**, + skips these checks otherwise + :param document_handler: method in which to parse the + :class:`~stem.descriptor.networkstatus.NetworkStatusDocument` + :param normalize_newlines: converts windows newlines (CRLF), this is the default when reading data directories on windows - :param dict kwargs: additional arguments for the descriptor constructor + :param kwargs: additional arguments for the descriptor constructor :returns: iterator for :class:`~stem.descriptor.__init__.Descriptor` instances in the file @@ -585,10 +585,10 @@ def _descriptor_content(attr: Mapping[str, str] = None, exclude: Sequence[str] = fingerprint 12345 contact atagar - :param dict attr: keyword/value mappings to be included in the descriptor - :param list exclude: mandatory keywords to exclude from the descriptor - :param tuple header_template: key/value pairs for mandatory fields before unrecognized content - :param tuple footer_template: key/value pairs for mandatory fields after unrecognized content + :param attr: keyword/value mappings to be included in the descriptor + :param exclude: mandatory keywords to exclude from the descriptor + :param header_template: key/value pairs for mandatory fields before unrecognized content + :param footer_template: key/value pairs for mandatory fields after unrecognized content :returns: bytes with the requested descriptor content """ @@ -760,10 +760,10 @@ def _mappings_for(keyword: str, value: str, require_value: bool = False, divider functions this is a helper, returning the attribute value rather than setting a descriptor field. This way parsers can perform additional validations. - :param str keyword: descriptor field being parsed - :param str value: 'attribute => values' mappings to parse - :param str divider: separator between the key/value mappings - :param bool require_value: validates that values are not empty + :param keyword: descriptor field being parsed + :param value: 'attribute => values' mappings to parse + :param divider: separator between the key/value mappings + :param require_value: validates that values are not empty :returns: **generator** with the key/value of the map attribute @@ -852,10 +852,10 @@ class Descriptor(object): .. versionadded:: 1.8.0 - :param str,bytes content: string to construct the descriptor from - :param bool multiple: if provided with **True** this provides a list of + :param content: string to construct the descriptor from + :param multiple: if provided with **True** this provides a list of descriptors rather than a single one - :param dict kwargs: additional arguments for :func:`~stem.descriptor.__init__.parse_file` + :param kwargs: additional arguments for :func:`~stem.descriptor.__init__.parse_file` :returns: :class:`~stem.descriptor.__init__.Descriptor` subclass for the given content, or a **list** of descriptors if **multiple = True** is @@ -889,8 +889,8 @@ class Descriptor(object): .. versionadded:: 1.6.0 - :param dict attr: keyword/value mappings to be included in the descriptor - :param list exclude: mandatory keywords to exclude from the descriptor, this + :param attr: keyword/value mappings to be included in the descriptor + :param exclude: mandatory keywords to exclude from the descriptor, this results in an invalid descriptor :returns: **bytes** with the content of a descriptor @@ -911,10 +911,10 @@ class Descriptor(object): .. versionadded:: 1.6.0 - :param dict attr: keyword/value mappings to be included in the descriptor - :param list exclude: mandatory keywords to exclude from the descriptor, this + :param attr: keyword/value mappings to be included in the descriptor + :param exclude: mandatory keywords to exclude from the descriptor, this results in an invalid descriptor - :param bool validate: checks the validity of the descriptor's content if + :param validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise :returns: :class:`~stem.descriptor.Descriptor` subclass @@ -1002,9 +1002,9 @@ class Descriptor(object): Parses a series of 'keyword => (value, pgp block)' mappings and applies them as attributes. - :param dict entries: descriptor contents to be applied - :param bool validate: checks the validity of descriptor content if True - :param dict parsers: mapping of lines to the function for parsing it + :param entries: descriptor contents to be applied + :param validate: checks the validity of descriptor content if True + :param parsers: mapping of lines to the function for parsing it :raises: **ValueError** if an error occurs in validation """ @@ -1041,8 +1041,8 @@ class Descriptor(object): """ Provides the signed digest we should have given this key and signature. - :param str signing_key: key block used to make this signature - :param str signature: signed digest for this descriptor content + :param signing_key: key block used to make this signature + :param signature: signed digest for this descriptor content :returns: the digest string encoded in uppercase hex @@ -1103,8 +1103,8 @@ class Descriptor(object): """ Provides the descriptor content inclusively between two substrings. - :param bytes start: start of the content range to get - :param bytes end: end of the content range to get + :param start: start of the content range to get + :param end: end of the content range to get :returns: **bytes** within the given range @@ -1228,14 +1228,14 @@ def _read_until_keywords_with_ending_keyword(keywords: Union[str, Sequence[str]] Reads from the descriptor file until we get to one of the given keywords or reach the end of the file. - :param str,list keywords: keyword(s) we want to read until - :param file descriptor_file: file with the descriptor content - :param bool inclusive: includes the line with the keyword if True - :param bool ignore_first: doesn't check if the first line read has one of the + :param keywords: keyword(s) we want to read until + :param descriptor_file: file with the descriptor content + :param inclusive: includes the line with the keyword if True + :param ignore_first: doesn't check if the first line read has one of the given keywords - :param bool skip: skips buffering content, returning None - :param int end_position: end if we reach this point in the file - :param bool include_ending_keyword: provides the keyword we broke on if **True** + :param skip: skips buffering content, returning None + :param end_position: end if we reach this point in the file + :param include_ending_keyword: provides the keyword we broke on if **True** :returns: **list** with the lines until we find one of the keywords, this is a two value tuple with the ending keyword if include_ending_keyword is @@ -1291,7 +1291,7 @@ def _bytes_for_block(content: str) -> bytes: """ Provides the base64 decoded content of a pgp-style block. - :param str content: block to be decoded + :param content: block to be decoded :returns: decoded block content @@ -1310,7 +1310,7 @@ def _get_pseudo_pgp_block(remaining_contents: List[str]) -> Tuple[str, str]: Checks if given contents begins with a pseudo-Open-PGP-style block and, if so, pops it off and provides it back to the caller. - :param list remaining_contents: lines to be checked for a public key block + :param remaining_contents: lines to be checked for a public key block :returns: **tuple** of the (block_type, content) or None if it doesn't exist @@ -1348,7 +1348,7 @@ def create_signing_key(private_key: Optional['cryptography.hazmat.backends.opens .. versionadded:: 1.6.0 - :param cryptography.hazmat.backends.openssl.rsa._RSAPrivateKey private_key: private key + :param private_key: private key :returns: :class:`~stem.descriptor.__init__.SigningKey` that can be used to create descriptors @@ -1396,9 +1396,8 @@ def _append_router_signature(content: bytes, private_key: 'cryptography.hazmat.b """ Appends a router signature to a server or extrainfo descriptor. - :param bytes content: descriptor content up through 'router-signature\\n' - :param cryptography.hazmat.backends.openssl.rsa._RSAPrivateKey private_key: - private relay signing key + :param content: descriptor content up through 'router-signature\\n' + :param private_key: private relay signing key :returns: **bytes** with the signed descriptor content """ @@ -1461,12 +1460,12 @@ def _descriptor_components_with_extra(raw_contents: bytes, validate: bool, extra entries because this influences the resulting exit policy, but for everything else in server descriptors the order does not matter. - :param bytes raw_contents: descriptor content provided by the relay - :param bool validate: checks the validity of the descriptor's content if + :param raw_contents: descriptor content provided by the relay + :param validate: checks the validity of the descriptor's content if True, skips these checks otherwise - :param list extra_keywords: entity keywords to put into a separate listing + :param extra_keywords: entity keywords to put into a separate listing with ordering intact - :param list non_ascii_fields: fields containing non-ascii content + :param non_ascii_fields: fields containing non-ascii content :returns: **collections.OrderedDict** with the 'keyword => (value, pgp key) entries' diff --git a/stem/descriptor/bandwidth_file.py b/stem/descriptor/bandwidth_file.py index f1f0b1e2..f4be6020 100644 --- a/stem/descriptor/bandwidth_file.py +++ b/stem/descriptor/bandwidth_file.py @@ -157,10 +157,10 @@ def _parse_file(descriptor_file: BinaryIO, validate: bool = False, **kwargs: Any """ Iterates over the bandwidth authority metrics in a file. - :param file descriptor_file: file with descriptor content - :param bool validate: checks the validity of the descriptor's content if + :param descriptor_file: file with descriptor content + :param validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise - :param dict kwargs: additional arguments for the descriptor constructor + :param kwargs: additional arguments for the descriptor constructor :returns: :class:`stem.descriptor.bandwidth_file.BandwidthFile` object diff --git a/stem/descriptor/certificate.py b/stem/descriptor/certificate.py index bc09be2d..188da52d 100644 --- a/stem/descriptor/certificate.py +++ b/stem/descriptor/certificate.py @@ -148,7 +148,7 @@ class Ed25519Certificate(object): """ Parses a byte encoded ED25519 certificate. - :param bytes content: encoded certificate + :param content: encoded certificate :returns: :class:`~stem.descriptor.certificate.Ed25519Certificate` subclsss for the given certificate @@ -168,7 +168,7 @@ class Ed25519Certificate(object): """ Parses a base64 encoded ED25519 certificate. - :param str content: base64 encoded certificate + :param content: base64 encoded certificate :returns: :class:`~stem.descriptor.certificate.Ed25519Certificate` subclsss for the given certificate @@ -204,7 +204,7 @@ class Ed25519Certificate(object): """ Base64 encoded certificate data. - :param bool pem: include `PEM header/footer + :param pem: include `PEM header/footer <https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail>`_, for more information see `RFC 7468 <https://tools.ietf.org/html/rfc7468>`_ @@ -247,8 +247,8 @@ class Ed25519CertificateV1(Ed25519Certificate): :var list extensions: :class:`~stem.descriptor.certificate.Ed25519Extension` in this certificate :var bytes signature: certificate signature - :param bytes signature: pre-calculated certificate signature - :param cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey signing_key: certificate signing key + :param signature: pre-calculated certificate signature + :param signing_key: certificate signing key :raises: **ImportError** if key is a cryptographic type and ed25519 support is unavailable @@ -367,7 +367,7 @@ class Ed25519CertificateV1(Ed25519Certificate): * :class:`~stem.descriptor.server_descriptor.RelayDescriptor` * :class:`~stem.descriptor.hidden_service.HiddenServiceDescriptorV3` - :param stem.descriptor.__init__.Descriptor descriptor: descriptor to validate + :param descriptor: descriptor to validate :raises: * **ValueError** if signing key or descriptor are invalid diff --git a/stem/descriptor/collector.py b/stem/descriptor/collector.py index a978519d..865fc1eb 100644 --- a/stem/descriptor/collector.py +++ b/stem/descriptor/collector.py @@ -225,17 +225,17 @@ class File(object): is provided then the file is downloaded to a temporary directory that's deleted after it is read. - :param str directory: destination to download into - :param str descriptor_type: `descriptor type + :param directory: destination to download into + :param descriptor_type: `descriptor type <https://metrics.torproject.org/collector.html#data-formats>`_, this is guessed if not provided - :param datetime.datetime start: publication time to begin with - :param datetime.datetime end: publication time to end with - :param stem.descriptor.__init__.DocumentHandler document_handler: method in + :param start: publication time to begin with + :param end: publication time to end with + :param document_handler: method in which to parse a :class:`~stem.descriptor.networkstatus.NetworkStatusDocument` - :param int timeout: timeout when connection becomes idle, no timeout + :param timeout: timeout when connection becomes idle, no timeout applied if **None** - :param int retries: maximum attempts to impose + :param retries: maximum attempts to impose :returns: iterator for :class:`~stem.descriptor.__init__.Descriptor` instances in the file @@ -295,12 +295,12 @@ class File(object): Downloads this file to the given location. If a file already exists this is a no-op. - :param str directory: destination to download into - :param bool decompress: decompress written file - :param int timeout: timeout when connection becomes idle, no timeout + :param directory: destination to download into + :param decompress: decompress written file + :param timeout: timeout when connection becomes idle, no timeout applied if **None** - :param int retries: maximum attempts to impose - :param bool overwrite: if this file exists but mismatches CollecTor's + :param retries: maximum attempts to impose + :param overwrite: if this file exists but mismatches CollecTor's checksum then overwrites if **True**, otherwise rases an exception :returns: **str** with the path we downloaded to @@ -412,14 +412,14 @@ class CollecTor(object): Provides server descriptors published during the given time range, sorted oldest to newest. - :param datetime.datetime start: publication time to begin with - :param datetime.datetime end: publication time to end with - :param str cache_to: directory to cache archives into, if an archive is + :param start: publication time to begin with + :param end: publication time to end with + :param cache_to: directory to cache archives into, if an archive is available here it is not downloaded - :param bool bridge: standard descriptors if **False**, bridge if **True** - :param int timeout: timeout for downloading each individual archive when + :param bridge: standard descriptors if **False**, bridge if **True** + :param timeout: timeout for downloading each individual archive when the connection becomes idle, no timeout applied if **None** - :param int retries: maximum attempts to impose on a per-archive basis + :param retries: maximum attempts to impose on a per-archive basis :returns: **iterator** of :class:`~stem.descriptor.server_descriptor.ServerDescriptor` for the @@ -439,14 +439,14 @@ class CollecTor(object): Provides extrainfo descriptors published during the given time range, sorted oldest to newest. - :param datetime.datetime start: publication time to begin with - :param datetime.datetime end: publication time to end with - :param str cache_to: directory to cache archives into, if an archive is + :param start: publication time to begin with + :param end: publication time to end with + :param cache_to: directory to cache archives into, if an archive is available here it is not downloaded - :param bool bridge: standard descriptors if **False**, bridge if **True** - :param int timeout: timeout for downloading each individual archive when + :param bridge: standard descriptors if **False**, bridge if **True** + :param timeout: timeout for downloading each individual archive when the connection becomes idle, no timeout applied if **None** - :param int retries: maximum attempts to impose on a per-archive basis + :param retries: maximum attempts to impose on a per-archive basis :returns: **iterator** of :class:`~stem.descriptor.extrainfo_descriptor.RelayExtraInfoDescriptor` @@ -476,13 +476,13 @@ class CollecTor(object): tarballs often contain very few. Microdescriptors also do not contain their publication timestamp, so this is estimated. - :param datetime.datetime start: publication time to begin with - :param datetime.datetime end: publication time to end with - :param str cache_to: directory to cache archives into, if an archive is + :param start: publication time to begin with + :param end: publication time to end with + :param cache_to: directory to cache archives into, if an archive is available here it is not downloaded - :param int timeout: timeout for downloading each individual archive when + :param timeout: timeout for downloading each individual archive when the connection becomes idle, no timeout applied if **None** - :param int retries: maximum attempts to impose on a per-archive basis + :param retries: maximum attempts to impose on a per-archive basis :returns: **iterator** of :class:`~stem.descriptor.microdescriptor.Microdescriptor` @@ -500,19 +500,19 @@ class CollecTor(object): Provides consensus router status entries published during the given time range, sorted oldest to newest. - :param datetime.datetime start: publication time to begin with - :param datetime.datetime end: publication time to end with - :param str cache_to: directory to cache archives into, if an archive is + :param start: publication time to begin with + :param end: publication time to end with + :param cache_to: directory to cache archives into, if an archive is available here it is not downloaded - :param stem.descriptor.__init__.DocumentHandler document_handler: method in + :param document_handler: method in which to parse a :class:`~stem.descriptor.networkstatus.NetworkStatusDocument` - :param int version: consensus variant to retrieve (versions 2 or 3) - :param bool microdescriptor: provides the microdescriptor consensus if + :param version: consensus variant to retrieve (versions 2 or 3) + :param microdescriptor: provides the microdescriptor consensus if **True**, standard consensus otherwise - :param bool bridge: standard descriptors if **False**, bridge if **True** - :param int timeout: timeout for downloading each individual archive when + :param bridge: standard descriptors if **False**, bridge if **True** + :param timeout: timeout for downloading each individual archive when the connection becomes idle, no timeout applied if **None** - :param int retries: maximum attempts to impose on a per-archive basis + :param retries: maximum attempts to impose on a per-archive basis :returns: **iterator** of :class:`~stem.descriptor.router_status_entry.RouterStatusEntry` @@ -544,13 +544,13 @@ class CollecTor(object): Directory authority key certificates for the given time range, sorted oldest to newest. - :param datetime.datetime start: publication time to begin with - :param datetime.datetime end: publication time to end with - :param str cache_to: directory to cache archives into, if an archive is + :param start: publication time to begin with + :param end: publication time to end with + :param cache_to: directory to cache archives into, if an archive is available here it is not downloaded - :param int timeout: timeout for downloading each individual archive when + :param timeout: timeout for downloading each individual archive when the connection becomes idle, no timeout applied if **None** - :param int retries: maximum attempts to impose on a per-archive basis + :param retries: maximum attempts to impose on a per-archive basis :returns: **iterator** of :class:`~stem.descriptor.networkstatus.KeyCertificate` @@ -568,13 +568,13 @@ class CollecTor(object): Bandwidth authority heuristics for the given time range, sorted oldest to newest. - :param datetime.datetime start: publication time to begin with - :param datetime.datetime end: publication time to end with - :param str cache_to: directory to cache archives into, if an archive is + :param start: publication time to begin with + :param end: publication time to end with + :param cache_to: directory to cache archives into, if an archive is available here it is not downloaded - :param int timeout: timeout for downloading each individual archive when + :param timeout: timeout for downloading each individual archive when the connection becomes idle, no timeout applied if **None** - :param int retries: maximum attempts to impose on a per-archive basis + :param retries: maximum attempts to impose on a per-archive basis :returns: **iterator** of :class:`~stem.descriptor.bandwidth_file.BandwidthFile` @@ -592,13 +592,13 @@ class CollecTor(object): `TorDNSEL exit lists <https://www.torproject.org/projects/tordnsel.html.en>`_ for the given time range, sorted oldest to newest. - :param datetime.datetime start: publication time to begin with - :param datetime.datetime end: publication time to end with - :param str cache_to: directory to cache archives into, if an archive is + :param start: publication time to begin with + :param end: publication time to end with + :param cache_to: directory to cache archives into, if an archive is available here it is not downloaded - :param int timeout: timeout for downloading each individual archive when + :param timeout: timeout for downloading each individual archive when the connection becomes idle, no timeout applied if **None** - :param int retries: maximum attempts to impose on a per-archive basis + :param retries: maximum attempts to impose on a per-archive basis :returns: **iterator** of :class:`~stem.descriptor.tordnsel.TorDNSEL` @@ -615,7 +615,7 @@ class CollecTor(object): """ Provides the archives available in CollecTor. - :param descriptor.Compression compression: compression type to + :param compression: compression type to download from, if undefiled we'll use the best decompression available :returns: **dict** with the archive contents @@ -654,9 +654,9 @@ class CollecTor(object): """ Provides files CollecTor presently has, sorted oldest to newest. - :param str descriptor_type: descriptor type or prefix to retrieve - :param datetime.datetime start: publication time to begin with - :param datetime.datetime end: publication time to end with + :param descriptor_type: descriptor type or prefix to retrieve + :param start: publication time to begin with + :param end: publication time to end with :returns: **list** of :class:`~stem.descriptor.collector.File` @@ -689,8 +689,8 @@ class CollecTor(object): """ Recursively provies files within the index. - :param dict val: index hash - :param list path: path we've transversed into + :param val: index hash + :param path: path we've transversed into :returns: **list** of :class:`~stem.descriptor.collector.File` """ diff --git a/stem/descriptor/extrainfo_descriptor.py b/stem/descriptor/extrainfo_descriptor.py index cd9467d1..3b84c185 100644 --- a/stem/descriptor/extrainfo_descriptor.py +++ b/stem/descriptor/extrainfo_descriptor.py @@ -171,11 +171,11 @@ def _parse_file(descriptor_file: BinaryIO, is_bridge = False, validate = False, """ Iterates over the extra-info descriptors in a file. - :param file descriptor_file: file with descriptor content - :param bool is_bridge: parses the file as being a bridge descriptor - :param bool validate: checks the validity of the descriptor's content if + :param descriptor_file: file with descriptor content + :param is_bridge: parses the file as being a bridge descriptor + :param validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise - :param dict kwargs: additional arguments for the descriptor constructor + :param kwargs: additional arguments for the descriptor constructor :returns: iterator for :class:`~stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor` instances in the file @@ -215,8 +215,8 @@ def _parse_timestamp_and_interval(keyword: str, content: str) -> Tuple[datetime. """ Parses a 'YYYY-MM-DD HH:MM:SS (NSEC s) *' entry. - :param str keyword: line's keyword - :param str content: line content to be parsed + :param keyword: line's keyword + :param content: line content to be parsed :returns: **tuple** of the form (timestamp (**datetime**), interval (**int**), remaining content (**str**)) @@ -827,8 +827,8 @@ class ExtraInfoDescriptor(Descriptor): descriptor's content as it's parsed. This validation can be disabled to either improve performance or be accepting of malformed data. - :param str raw_contents: extra-info content provided by the relay - :param bool validate: checks the validity of the extra-info descriptor if + :param raw_contents: extra-info content provided by the relay + :param validate: checks the validity of the extra-info descriptor if **True**, skips these checks otherwise :raises: **ValueError** if the contents is malformed and validate is True @@ -875,8 +875,8 @@ class ExtraInfoDescriptor(Descriptor): .. versionchanged:: 1.8.0 Added the hash_type and encoding arguments. - :param stem.descriptor.DigestHash hash_type: digest hashing algorithm - :param stem.descriptor.DigestEncoding encoding: digest encoding + :param hash_type: digest hashing algorithm + :param encoding: digest encoding :returns: **hashlib.HASH** or **str** based on our encoding argument """ diff --git a/stem/descriptor/hidden_service.py b/stem/descriptor/hidden_service.py index 5b3b5178..49737f9d 100644 --- a/stem/descriptor/hidden_service.py +++ b/stem/descriptor/hidden_service.py @@ -168,7 +168,7 @@ class IntroductionPointV3(collections.namedtuple('IntroductionPointV3', ['link_s """ Parses an introduction point from its descriptor content. - :param str content: descriptor content to parse + :param content: descriptor content to parse :returns: :class:`~stem.descriptor.hidden_service.IntroductionPointV3` for the descriptor content @@ -206,13 +206,13 @@ class IntroductionPointV3(collections.namedtuple('IntroductionPointV3', ['link_s """ Simplified constructor for a single address/port link specifier. - :param str address: IPv4 or IPv6 address where the service is reachable - :param int port: port where the service is reachable - :param datetime.datetime expiration: when certificates should expire - :param str onion_key: encoded, X25519PublicKey, or X25519PrivateKey onion key - :param str enc_key: encoded, X25519PublicKey, or X25519PrivateKey encryption key - :param str auth_key: encoded, Ed25519PublicKey, or Ed25519PrivateKey authentication key - :param cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey signing_key: service signing key + :param address: IPv4 or IPv6 address where the service is reachable + :param port: port where the service is reachable + :param expiration: when certificates should expire + :param onion_key: encoded, X25519PublicKey, or X25519PrivateKey onion key + :param enc_key: encoded, X25519PublicKey, or X25519PrivateKey encryption key + :param auth_key: encoded, Ed25519PublicKey, or Ed25519PrivateKey authentication key + :param signing_key: service signing key :returns: :class:`~stem.descriptor.hidden_service.IntroductionPointV3` with these attributes @@ -241,12 +241,12 @@ class IntroductionPointV3(collections.namedtuple('IntroductionPointV3', ['link_s Simplified constructor. For more sophisticated use cases you can use this as a template for how introduction points are properly created. - :param list link_specifiers: series of stem.client.datatype.LinkSpecifier where the service is reachable - :param datetime.datetime expiration: when certificates should expire - :param str onion_key: encoded, X25519PublicKey, or X25519PrivateKey onion key - :param str enc_key: encoded, X25519PublicKey, or X25519PrivateKey encryption key - :param str auth_key: encoded, Ed25519PublicKey, or Ed25519PrivateKey authentication key - :param cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey signing_key: service signing key + :param link_specifiers: series of stem.client.datatype.LinkSpecifier where the service is reachable + :param expiration: when certificates should expire + :param onion_key: encoded, X25519PublicKey, or X25519PrivateKey onion key + :param enc_key: encoded, X25519PublicKey, or X25519PrivateKey encryption key + :param auth_key: encoded, Ed25519PublicKey, or Ed25519PrivateKey authentication key + :param signing_key: service signing key :returns: :class:`~stem.descriptor.hidden_service.IntroductionPointV3` with these attributes @@ -440,11 +440,11 @@ def _parse_file(descriptor_file: BinaryIO, desc_type: Optional[Type['stem.descri """ Iterates over the hidden service descriptors in a file. - :param file descriptor_file: file with descriptor content - :param class desc_type: HiddenServiceDescriptor subclass - :param bool validate: checks the validity of the descriptor's content if + :param descriptor_file: file with descriptor content + :param desc_type: HiddenServiceDescriptor subclass + :param validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise - :param dict kwargs: additional arguments for the descriptor constructor + :param kwargs: additional arguments for the descriptor constructor :returns: iterator for :class:`~stem.descriptor.hidden_service.HiddenServiceDescriptor` instances in the file @@ -744,7 +744,7 @@ class HiddenServiceDescriptorV2(HiddenServiceDescriptor): """ Provided this service's introduction points. - :param bytes authentication_cookie: base64 encoded authentication cookie + :param authentication_cookie: base64 encoded authentication cookie :returns: **list** of :class:`~stem.descriptor.hidden_service.IntroductionPointV2` @@ -956,22 +956,17 @@ class HiddenServiceDescriptorV3(HiddenServiceDescriptor): HiddenServiceDescriptorV3.create(blinding_nonce = os.urandom(32)) - :param dict attr: keyword/value mappings to be included in plaintext descriptor - :param list exclude: mandatory keywords to exclude from the descriptor, this + :param attr: keyword/value mappings to be included in plaintext descriptor + :param exclude: mandatory keywords to exclude from the descriptor, this results in an invalid descriptor - :param bool sign: includes cryptographic signatures and digests if True - :param stem.descriptor.hidden_service.InnerLayer inner_layer: inner - encrypted layer - :param stem.descriptor.hidden_service.OuterLayer outer_layer: outer - encrypted layer - :param cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey identity_key: - service identity key - :param cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey signing_key: - service signing key - :param stem.descriptor.Ed25519CertificateV1 signing_cert: certificate - signing this descriptor - :param int revision_counter: descriptor revision number - :param bytes blinding_nonce: 32 byte blinding factor to derive the blinding key + :param sign: includes cryptographic signatures and digests if True + :param inner_layer: inner encrypted layer + :param outer_layer: outer encrypted layer + :param identity_key: service identity key + :param signing_key: service signing key + :param signing_cert: certificate signing this descriptor + :param revision_counter: descriptor revision number + :param blinding_nonce: 32 byte blinding factor to derive the blinding key :returns: **str** with the content of a descriptor @@ -1071,7 +1066,7 @@ class HiddenServiceDescriptorV3(HiddenServiceDescriptor): layers (:class:`~stem.descriptor.hidden_service.OuterLayer` and :class:`~stem.descriptor.hidden_service.InnerLayer`). - :param str onion_address: hidden service address this descriptor is from + :param onion_address: hidden service address this descriptor is from :returns: :class:`~stem.descriptor.hidden_service.InnerLayer` with our decrypted content @@ -1102,8 +1097,8 @@ class HiddenServiceDescriptorV3(HiddenServiceDescriptor): Converts a hidden service identity key into its address. This accepts all key formats (private, public, or public bytes). - :param Ed25519PublicKey,Ed25519PrivateKey,bytes key: hidden service identity key - :param bool suffix: includes the '.onion' suffix if true, excluded otherwise + :param key: hidden service identity key + :param suffix: includes the '.onion' suffix if true, excluded otherwise :returns: **str** hidden service address @@ -1124,7 +1119,7 @@ class HiddenServiceDescriptorV3(HiddenServiceDescriptor): """ Converts a hidden service address into its public identity key. - :param str onion_address: hidden service address + :param onion_address: hidden service address :returns: **bytes** for the hidden service's public identity key diff --git a/stem/descriptor/microdescriptor.py b/stem/descriptor/microdescriptor.py index 7bd241e4..9b5b045d 100644 --- a/stem/descriptor/microdescriptor.py +++ b/stem/descriptor/microdescriptor.py @@ -109,10 +109,10 @@ def _parse_file(descriptor_file: BinaryIO, validate: bool = False, **kwargs: Any """ Iterates over the microdescriptors in a file. - :param file descriptor_file: file with descriptor content - :param bool validate: checks the validity of the descriptor's content if + :param descriptor_file: file with descriptor content + :param validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise - :param dict kwargs: additional arguments for the descriptor constructor + :param kwargs: additional arguments for the descriptor constructor :returns: iterator for Microdescriptor instances in the file @@ -277,8 +277,8 @@ class Microdescriptor(Descriptor): .. versionadded:: 1.8.0 - :param stem.descriptor.DigestHash hash_type: digest hashing algorithm - :param stem.descriptor.DigestEncoding encoding: digest encoding + :param hash_type: digest hashing algorithm + :param encoding: digest encoding :returns: **hashlib.HASH** or **str** based on our encoding argument """ @@ -331,7 +331,7 @@ class Microdescriptor(Descriptor): Does a basic check that the entries conform to this descriptor type's constraints. - :param dict entries: keyword => (value, pgp key) entries + :param entries: keyword => (value, pgp key) entries :raises: **ValueError** if an issue arises in validation """ diff --git a/stem/descriptor/networkstatus.py b/stem/descriptor/networkstatus.py index 6c0f5e8f..d7e541fa 100644 --- a/stem/descriptor/networkstatus.py +++ b/stem/descriptor/networkstatus.py @@ -302,15 +302,15 @@ def _parse_file(document_file: BinaryIO, document_type: Optional[Type] = None, v document that these instances reference have an empty 'routers' attribute to allow for limited memory usage. - :param file document_file: file with network status document content - :param class document_type: NetworkStatusDocument subclass - :param bool validate: checks the validity of the document's contents if + :param document_file: file with network status document content + :param document_type: NetworkStatusDocument subclass + :param validate: checks the validity of the document's contents if **True**, skips these checks otherwise - :param bool is_microdescriptor: **True** if this is for a microdescriptor + :param is_microdescriptor: **True** if this is for a microdescriptor consensus, **False** otherwise - :param stem.descriptor.__init__.DocumentHandler document_handler: method in + :param document_handler: method in which to parse :class:`~stem.descriptor.networkstatus.NetworkStatusDocument` - :param dict kwargs: additional arguments for the descriptor constructor + :param kwargs: additional arguments for the descriptor constructor :returns: :class:`stem.descriptor.networkstatus.NetworkStatusDocument` object @@ -381,8 +381,8 @@ def _parse_file_key_certs(certificate_file: BinaryIO, validate: bool = False) -> """ Parses a file containing one or more authority key certificates. - :param file certificate_file: file with key certificates - :param bool validate: checks the validity of the certificate's contents if + :param certificate_file: file with key certificates + :param validate: checks the validity of the certificate's contents if **True**, skips these checks otherwise :returns: iterator for :class:`stem.descriptor.networkstatus.KeyCertificate` @@ -410,8 +410,8 @@ def _parse_file_detached_sigs(detached_signature_file: BinaryIO, validate: bool """ Parses a file containing one or more detached signatures. - :param file detached_signature_file: file with detached signatures - :param bool validate: checks the validity of the detached signature's + :param detached_signature_file: file with detached signatures + :param validate: checks the validity of the detached signature's contents if **True**, skips these checks otherwise :returns: iterator for :class:`stem.descriptor.networkstatus.DetachedSignature` @@ -447,8 +447,8 @@ class NetworkStatusDocument(Descriptor): .. versionadded:: 1.8.0 - :param stem.descriptor.DigestHash hash_type: digest hashing algorithm - :param stem.descriptor.DigestEncoding encoding: digest encoding + :param hash_type: digest hashing algorithm + :param encoding: digest encoding :returns: **hashlib.HASH** or **str** based on our encoding argument """ @@ -1180,9 +1180,9 @@ class NetworkStatusDocumentV3(NetworkStatusDocument): """ Parse a v3 network status document. - :param str raw_content: raw network status document data - :param bool validate: **True** if the document is to be validated, **False** otherwise - :param bool default_params: includes defaults in our params dict, otherwise + :param raw_content: raw network status document data + :param validate: **True** if the document is to be validated, **False** otherwise + :param default_params: includes defaults in our params dict, otherwise it just contains values from the document :raises: **ValueError** if the document is invalid @@ -1266,7 +1266,7 @@ class NetworkStatusDocumentV3(NetworkStatusDocument): .. versionadded:: 1.6.0 - :param list key_certs: :class:`~stem.descriptor.networkstatus.KeyCertificate` + :param key_certs: :class:`~stem.descriptor.networkstatus.KeyCertificate` to validate the consensus against :raises: **ValueError** if an insufficient number of valid signatures are present. @@ -1308,7 +1308,7 @@ class NetworkStatusDocumentV3(NetworkStatusDocument): consensuses, checking our 'consensus-method' and 'consensus-methods' entries. - :param int method: consensus-method to check for + :param method: consensus-method to check for :returns: **True** if we meet the given consensus-method, and **False** otherwise """ @@ -1411,9 +1411,9 @@ def _check_for_missing_and_disallowed_fields(document: 'stem.descriptor.networks any fields exclusive to the other (ie, no vote-only fields appear in a consensus or vice versa). - :param NetworkStatusDocumentV3 document: network status document - :param dict entries: ordered keyword/value mappings of the header or footer - :param list fields: expected field attributes (either + :param document: network status document + :param entries: ordered keyword/value mappings of the header or footer + :param fields: expected field attributes (either **HEADER_STATUS_DOCUMENT_FIELDS** or **FOOTER_STATUS_DOCUMENT_FIELDS**) :raises: **ValueError** if we're missing mandatory fields or have fields we shouldn't @@ -1614,10 +1614,10 @@ class DirectoryAuthority(Descriptor): """ Parse a directory authority entry in a v3 network status document. - :param str raw_content: raw directory authority entry information - :param bool validate: checks the validity of the content if True, skips + :param raw_content: raw directory authority entry information + :param validate: checks the validity of the content if True, skips these checks otherwise - :param bool is_vote: True if this is for a vote, False if it's for a consensus + :param is_vote: True if this is for a vote, False if it's for a consensus :raises: ValueError if the descriptor data is invalid """ @@ -1808,7 +1808,8 @@ class DocumentSignature(object): :var str signature: document signature :var str flavor: consensus type this signature is for (such as 'microdesc'), **None** if for the standard consensus - :param bool validate: checks validity if **True** + + :param validate: checks validity if **True** :raises: **ValueError** if a validity check fails """ diff --git a/stem/descriptor/remote.py b/stem/descriptor/remote.py index 9ced7de3..e90c4442 100644 --- a/stem/descriptor/remote.py +++ b/stem/descriptor/remote.py @@ -366,8 +366,8 @@ class Query(object): :var str download_url: last url used to download the descriptor, this is unset until we've actually made a download attempt - :param bool start: start making the request when constructed (default is **True**) - :param bool block: only return after the request has been completed, this is + :param start: start making the request when constructed (default is **True**) + :param block: only return after the request has been completed, this is the same as running **query.run(True)** (default is **False**) """ @@ -457,7 +457,7 @@ class Query(object): Blocks until our request is complete then provides the descriptors. If we haven't yet started our request then this does so. - :param bool suppress: avoids raising exceptions if **True** + :param suppress: avoids raising exceptions if **True** :returns: list for the requested :class:`~stem.descriptor.__init__.Descriptor` instances @@ -517,7 +517,7 @@ class Query(object): Provides an endpoint to query. If we have multiple endpoints then one is picked at random. - :param bool use_authority: ignores our endpoints and uses a directory + :param use_authority: ignores our endpoints and uses a directory authority instead :returns: :class:`stem.Endpoint` for the location to be downloaded @@ -568,7 +568,7 @@ class DescriptorDownloader(object): Configurable class that issues :class:`~stem.descriptor.remote.Query` instances on your behalf. - :param bool use_mirrors: downloads the present consensus and uses the directory + :param use_mirrors: downloads the present consensus and uses the directory mirrors to fetch future requests, this fails silently if the consensus cannot be downloaded :param default_args: default arguments for the @@ -634,8 +634,8 @@ class DescriptorDownloader(object): fingerprints are provided then this returns all descriptors known by the relay. - :param str,list fingerprints: fingerprint or list of fingerprints to be - retrieved, gets all descriptors if **None** + :param fingerprints: fingerprint or list of fingerprints to be retrieved, + gets all descriptors if **None** :param query_args: additional arguments for the :class:`~stem.descriptor.remote.Query` constructor @@ -664,8 +664,8 @@ class DescriptorDownloader(object): fingerprints are provided then this returns all descriptors in the present consensus. - :param str,list fingerprints: fingerprint or list of fingerprints to be - retrieved, gets all descriptors if **None** + :param fingerprints: fingerprint or list of fingerprints to be retrieved, + gets all descriptors if **None** :param query_args: additional arguments for the :class:`~stem.descriptor.remote.Query` constructor @@ -715,8 +715,7 @@ class DescriptorDownloader(object): ntor-onion-key kWOHNd+2uBlMpcIUbbpFLiq/rry66Ep6MlwmNpwzcBg= id ed25519 xE/GeYImYAIB0RbzJXFL8kDLpDrj/ydCuCdvOgC4F/4 - :param str,list hashes: microdescriptor hash or list of hashes to be - retrieved + :param hashes: microdescriptor hash or list of hashes to be retrieved :param query_args: additional arguments for the :class:`~stem.descriptor.remote.Query` constructor @@ -741,11 +740,11 @@ class DescriptorDownloader(object): .. versionchanged:: 1.5.0 Added the microdescriptor argument. - :param str authority_v3ident: fingerprint of the authority key for which + :param authority_v3ident: fingerprint of the authority key for which to get the consensus, see `'v3ident' in tor's config.c <https://gitweb.torproject.org/tor.git/tree/src/or/config.c>`_ for the values. - :param bool microdescriptor: provides the microdescriptor consensus if + :param microdescriptor: provides the microdescriptor consensus if **True**, standard consensus otherwise :param query_args: additional arguments for the :class:`~stem.descriptor.remote.Query` constructor @@ -782,7 +781,7 @@ class DescriptorDownloader(object): """ Provides the present vote for a given directory authority. - :param stem.directory.Authority authority: authority for which to retrieve a vote for + :param authority: authority for which to retrieve a vote for :param query_args: additional arguments for the :class:`~stem.descriptor.remote.Query` constructor @@ -803,7 +802,7 @@ class DescriptorDownloader(object): If no fingerprints are provided then this returns all present key certificates. - :param str,list authority_v3idents: fingerprint or list of fingerprints of the + :param authority_v3idents: fingerprint or list of fingerprints of the authority keys, see `'v3ident' in tor's config.c <https://gitweb.torproject.org/tor.git/tree/src/or/config.c>`_ for the values. @@ -907,7 +906,7 @@ class DescriptorDownloader(object): The **fall_back_to_authority** default when using this method is now **False**, like the :class:`~stem.descriptor.Query` class. - :param str resource: resource being fetched, such as '/tor/server/all' + :param resource: resource being fetched, such as '/tor/server/all' :param query_args: additional arguments for the :class:`~stem.descriptor.remote.Query` constructor @@ -944,9 +943,9 @@ def _download_from_orport(endpoint: stem.ORPort, compression: Sequence[stem.desc identity-ed25519 ... rest of the descriptor content... - :param stem.ORPort endpoint: endpoint to download from - :param list compression: compression methods for the request - :param str resource: descriptor resource to download + :param endpoint: endpoint to download from + :param compression: compression methods for the request + :param resource: descriptor resource to download :returns: two value tuple of the form (data, reply_headers) @@ -988,9 +987,9 @@ def _download_from_dirport(url: str, compression: Sequence[stem.descriptor._Comp """ Downloads descriptors from the given url. - :param str url: dirport url from which to download from - :param list compression: compression methods for the request - :param float timeout: duration before we'll time out our request + :param url: dirport url from which to download from + :param compression: compression methods for the request + :param timeout: duration before we'll time out our request :returns: two value tuple of the form (data, reply_headers) @@ -1030,8 +1029,8 @@ def _decompress(data: bytes, encoding: str) -> bytes: ... and with zstd we need to use the streaming API. - :param bytes data: data we received - :param str encoding: 'Content-Encoding' header of the response + :param data: data we received + :param encoding: 'Content-Encoding' header of the response :returns: **bytes** with the decompressed data diff --git a/stem/descriptor/router_status_entry.py b/stem/descriptor/router_status_entry.py index 2c4937f3..ecfcb7fd 100644 --- a/stem/descriptor/router_status_entry.py +++ b/stem/descriptor/router_status_entry.py @@ -56,16 +56,16 @@ def _parse_file(document_file: BinaryIO, validate: bool, entry_class: Type['stem Either an end_position or section_end_keywords must be provided. - :param file document_file: file with network status document content - :param bool validate: checks the validity of the document's contents if + :param document_file: file with network status document content + :param validate: checks the validity of the document's contents if **True**, skips these checks otherwise - :param class entry_class: class to construct instance for - :param str entry_keyword: first keyword for the entry instances - :param int start_position: start of the section, default is the current position - :param int end_position: end of the section - :param tuple section_end_keywords: keyword(s) that deliminate the end of the + :param entry_class: class to construct instance for + :param entry_keyword: first keyword for the entry instances + :param start_position: start of the section, default is the current position + :param end_position: end of the section + :param section_end_keywords: keyword(s) that deliminate the end of the section if no end_position was provided - :param tuple extra_args: extra arguments for the entry_class (after the + :param extra_args: extra arguments for the entry_class (after the content and validate flag) :returns: iterator over entry_class instances @@ -358,8 +358,8 @@ def _base64_to_hex(identity: str, check_if_fingerprint: bool = True) -> str: >>> _base64_to_hex('p1aag7VwarGxqctS7/fS0y5FU+s') 'A7569A83B5706AB1B1A9CB52EFF7D2D32E4553EB' - :param str identity: encoded fingerprint from the consensus - :param bool check_if_fingerprint: asserts that the result is a fingerprint if **True** + :param identity: encoded fingerprint from the consensus + :param check_if_fingerprint: asserts that the result is a fingerprint if **True** :returns: **str** with the uppercase hex encoding of the relay's fingerprint @@ -447,10 +447,10 @@ class RouterStatusEntry(Descriptor): """ Parse a router descriptor in a network status document. - :param str content: router descriptor content to be parsed - :param bool validate: checks the validity of the content if **True**, skips + :param content: router descriptor content to be parsed + :param validate: checks the validity of the content if **True**, skips these checks otherwise - :param NetworkStatusDocument document: document this descriptor came from + :param document: document this descriptor came from :raises: **ValueError** if the descriptor data is invalid """ diff --git a/stem/descriptor/server_descriptor.py b/stem/descriptor/server_descriptor.py index fbb5c633..6e6a5369 100644 --- a/stem/descriptor/server_descriptor.py +++ b/stem/descriptor/server_descriptor.py @@ -149,11 +149,11 @@ def _parse_file(descriptor_file: BinaryIO, is_bridge: bool = False, validate: bo """ Iterates over the server descriptors in a file. - :param file descriptor_file: file with descriptor content - :param bool is_bridge: parses the file as being a bridge descriptor - :param bool validate: checks the validity of the descriptor's content if + :param descriptor_file: file with descriptor content + :param is_bridge: parses the file as being a bridge descriptor + :param validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise - :param dict kwargs: additional arguments for the descriptor constructor + :param kwargs: additional arguments for the descriptor constructor :returns: iterator for ServerDescriptor instances in the file @@ -591,8 +591,8 @@ class ServerDescriptor(Descriptor): validation can be disables to either improve performance or be accepting of malformed data. - :param str raw_contents: descriptor content provided by the relay - :param bool validate: checks the validity of the descriptor's content if + :param raw_contents: descriptor content provided by the relay + :param validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise :raises: **ValueError** if the contents is malformed and validate is True @@ -638,8 +638,8 @@ class ServerDescriptor(Descriptor): .. versionchanged:: 1.8.0 Added the hash_type and encoding arguments. - :param stem.descriptor.DigestHash hash_type: digest hashing algorithm - :param stem.descriptor.DigestEncoding encoding: digest encoding + :param hash_type: digest hashing algorithm + :param encoding: digest encoding :returns: **hashlib.HASH** or **str** based on our encoding argument """ @@ -651,7 +651,7 @@ class ServerDescriptor(Descriptor): Does a basic check that the entries conform to this descriptor type's constraints. - :param dict entries: keyword => (value, pgp key) entries + :param entries: keyword => (value, pgp key) entries :raises: **ValueError** if an issue arises in validation """ @@ -839,8 +839,8 @@ class RelayDescriptor(ServerDescriptor): """ Provides the digest of our descriptor's content. - :param stem.descriptor.DigestHash hash_type: digest hashing algorithm - :param stem.descriptor.DigestEncoding encoding: digest encoding + :param hash_type: digest hashing algorithm + :param encoding: digest encoding :returns: **hashlib.HASH** or **str** based on our encoding argument diff --git a/stem/directory.py b/stem/directory.py index 3ecb0b71..6f1b8958 100644 --- a/stem/directory.py +++ b/stem/directory.py @@ -75,9 +75,9 @@ def _match_with(lines: Sequence[str], regexes: Sequence[Pattern], required: Opti mapping of regexes to their capture groups. This maping is with the value if the regex has just a single capture group, and a tuple otherwise. - :param list lines: text to parse - :param list regexes: regexes to match against - :param list required: matches that must be in the content + :param lines: text to parse + :param regexes: regexes to match against + :param required: matches that must be in the content :returns: **dict** mapping matchers against their capture groups @@ -200,7 +200,7 @@ class Directory(object): .. versionchanged:: 1.7.0 Support added to the :class:`~stem.directory.Authority` class. - :param int timeout: seconds to wait before timing out the request + :param timeout: seconds to wait before timing out the request :returns: **dict** of **str** identifiers to their :class:`~stem.directory.Directory` @@ -476,11 +476,11 @@ class Fallback(Directory): Persists fallback directories to a location in a way that can be read by from_cache(). - :param dict fallbacks: mapping of fingerprints to their fallback directory - :param str tor_commit: tor commit the fallbacks came from - :param str stem_commit: stem commit the fallbacks came from - :param dict headers: metadata about the file these came from - :param str path: location fallbacks will be persisted to + :param fallbacks: mapping of fingerprints to their fallback directory + :param tor_commit: tor commit the fallbacks came from + :param stem_commit: stem commit the fallbacks came from + :param headers: metadata about the file these came from + :param path: location fallbacks will be persisted to """ conf = stem.util.conf.Config() diff --git a/stem/exit_policy.py b/stem/exit_policy.py index 19178c9a..8139ce50 100644 --- a/stem/exit_policy.py +++ b/stem/exit_policy.py @@ -160,7 +160,7 @@ class ExitPolicy(object): is, in effect, just a list of :class:`~stem.exit_policy.ExitPolicyRule` entries. - :param list rules: **str** or :class:`~stem.exit_policy.ExitPolicyRule` + :param rules: **str** or :class:`~stem.exit_policy.ExitPolicyRule` entries that make up this policy """ @@ -207,9 +207,9 @@ class ExitPolicy(object): address or port is omitted then this will check if we're allowed to exit to any instances of the defined address or port. - :param str address: IPv4 or IPv6 address (with or without brackets) - :param int port: port number - :param bool strict: if the address or port is excluded then check if we can + :param address: IPv4 or IPv6 address (with or without brackets) + :param port: port number + :param strict: if the address or port is excluded then check if we can exit to **all** instances of the defined address or port :returns: **True** if exiting to this destination is allowed, **False** otherwise @@ -505,7 +505,7 @@ class MicroExitPolicy(ExitPolicy): :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 + :param policy: policy string that describes this policy """ def __init__(self, policy: str) -> None: @@ -589,7 +589,7 @@ class ExitPolicyRule(object): :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 + :param rule: exit policy rule to be parsed :raises: **ValueError** if input isn't a valid tor exit policy rule """ @@ -675,9 +675,9 @@ class ExitPolicyRule(object): the address or port is omitted then this will check if we're allowed to exit to any instances of the defined address or port. - :param str address: IPv4 or IPv6 address (with or without brackets) - :param int port: port number - :param bool strict: if the address or port is excluded then check if we can + :param address: IPv4 or IPv6 address (with or without brackets) + :param port: port number + :param strict: if the address or port is excluded then check if we can exit to **all** instances of the defined address or port :returns: **bool** indicating if we match against this destination @@ -754,7 +754,7 @@ class ExitPolicyRule(object): Provides the address represented by our mask. This is **None** if our address type is a wildcard. - :param bool cache: caches the result if **True** + :param cache: caches the result if **True** :returns: str of our subnet mask for the address (ex. '255.255.255.0') """ diff --git a/stem/interpreter/arguments.py b/stem/interpreter/arguments.py index dd0b19bb..90ec3886 100644 --- a/stem/interpreter/arguments.py +++ b/stem/interpreter/arguments.py @@ -34,7 +34,7 @@ class Arguments(NamedTuple): """ Parses our commandline arguments into this class. - :param list argv: input arguments to be parsed + :param argv: input arguments to be parsed :returns: :class:`stem.interpreter.arguments.Arguments` for this commandline input diff --git a/stem/interpreter/autocomplete.py b/stem/interpreter/autocomplete.py index e310ed28..54642472 100644 --- a/stem/interpreter/autocomplete.py +++ b/stem/interpreter/autocomplete.py @@ -88,7 +88,7 @@ class Autocompleter(object): """ Provides autocompletion matches for the given text. - :param str text: text to check for autocompletion matches with + :param text: text to check for autocompletion matches with :returns: **list** with possible matches """ @@ -101,8 +101,8 @@ class Autocompleter(object): Provides case insensetive autocompletion options, acting as a functor for the readlines set_completer function. - :param str text: text to check for autocompletion matches with - :param int state: index of result to be provided, readline fetches matches + :param text: text to check for autocompletion matches with + :param state: index of result to be provided, readline fetches matches until this function provides None :returns: **str** with the autocompletion match, **None** if eithe none diff --git a/stem/interpreter/commands.py b/stem/interpreter/commands.py index 254e46a1..4c506b5e 100644 --- a/stem/interpreter/commands.py +++ b/stem/interpreter/commands.py @@ -35,8 +35,8 @@ def _get_fingerprint(arg: str, controller: stem.control.Controller) -> str: * IPv4 addresses, either with or without an ORPort * Empty input, which is resolved to ourselves if we're a relay - :param str arg: input to be resolved to a relay fingerprint - :param stem.control.Controller controller: tor control connection + :param arg: input to be resolved to a relay fingerprint + :param controller: tor control connection :returns: **str** for the relay fingerprint @@ -302,8 +302,8 @@ class ControlInterpreter(code.InteractiveConsole): Runs the given command. Requests starting with a '/' are special commands to the interpreter, and anything else is sent to the control port. - :param str command: command to be processed - :param bool print_response: prints the response to stdout if true + :param command: command to be processed + :param print_response: prints the response to stdout if true :returns: **str** output of the command diff --git a/stem/interpreter/help.py b/stem/interpreter/help.py index 3a206c35..14b46e35 100644 --- a/stem/interpreter/help.py +++ b/stem/interpreter/help.py @@ -25,8 +25,8 @@ def response(controller: stem.control.Controller, arg: str) -> str: """ Provides our /help response. - :param stem.control.Controller controller: tor control connection - :param str arg: controller or interpreter command to provide help output for + :param controller: tor control connection + :param arg: controller or interpreter command to provide help output for :returns: **str** with our help response """ diff --git a/stem/manual.py b/stem/manual.py index a5d3ebef..b98f601c 100644 --- a/stem/manual.py +++ b/stem/manual.py @@ -126,8 +126,8 @@ def query(query: str, *param: str) -> 'sqlite3.Cursor': # type: ignore .. versionadded:: 1.6.0 - :param str query: query to run on the cache - :param list param: query parameters + :param query: query to run on the cache + :param param: query parameters :returns: :class:`sqlite3.Cursor` with the query results @@ -190,7 +190,7 @@ def _config(lowercase: bool = True) -> Dict[str, Union[List[str], str]]: * manual.important (list) - configuration options considered to be important * manual.summary.* (str) - summary descriptions of config options - :param bool lowercase: uses lowercase keys if **True** to allow for case + :param lowercase: uses lowercase keys if **True** to allow for case insensitive lookups """ @@ -256,7 +256,7 @@ def is_important(option: str) -> bool: """ Indicates if a configuration option of particularly common importance or not. - :param str option: tor configuration option to check + :param option: tor configuration option to check :returns: **bool** that's **True** if this is an important option and **False** otherwise @@ -272,10 +272,10 @@ def download_man_page(path: Optional[str] = None, file_handle: Optional[BinaryIO both slow and unreliable - please see the warnings on :func:`~stem.manual.Manual.from_remote`. - :param str path: path to save tor's man page to - :param file file_handle: file handler to save tor's man page to - :param str url: url to download tor's asciidoc manual from - :param int timeout: seconds to wait before timing out the request + :param path: path to save tor's man page to + :param file_handle: file handler to save tor's man page to + :param url: url to download tor's asciidoc manual from + :param timeout: seconds to wait before timing out the request :raises: **IOError** if unable to retrieve the manual """ @@ -375,7 +375,7 @@ class Manual(object): Added support for sqlite cache. Support for :class:`~stem.util.conf.Config` caches will be dropped in Stem 2.x. - :param str path: cached manual content to read, if not provided this uses + :param path: cached manual content to read, if not provided this uses the bundled manual information :returns: :class:`~stem.manual.Manual` with our bundled manual information @@ -435,7 +435,7 @@ class Manual(object): may not quite match other platforms. For instance, it normalizes long dashes into '--'. - :param str man_path: path argument for 'man', for example you might want + :param man_path: path argument for 'man', for example you might want '/path/to/tor/doc/tor.1' to read from tor's git repository :returns: :class:`~stem.manual.Manual` for the system's man page @@ -493,7 +493,7 @@ class Manual(object): * 5.57s to convert the asciidoc to a man page * 0.17s for stem to read and parse the manual - :param int timeout: seconds to wait before timing out the request + :param timeout: seconds to wait before timing out the request :returns: latest :class:`~stem.manual.Manual` available for tor @@ -512,7 +512,7 @@ class Manual(object): Added support for sqlite cache. Support for :class:`~stem.util.conf.Config` caches will be dropped in Stem 2.x. - :param str path: path to save our manual content to + :param path: path to save our manual content to :raises: * **ImportError** if saving as sqlite and the sqlite3 module is diff --git a/stem/process.py b/stem/process.py index 3c7688a5..417a0570 100644 --- a/stem/process.py +++ b/stem/process.py @@ -58,21 +58,21 @@ def launch_tor(tor_cmd: str = 'tor', args: Optional[Sequence[str]] = None, torrc .. versionchanged:: 1.7.0 Added the **close_output** argument. - :param str tor_cmd: command for starting tor - :param list args: additional arguments for tor - :param str torrc_path: location of the torrc for us to use - :param int completion_percent: percent of bootstrap completion at which + :param tor_cmd: command for starting tor + :param args: additional arguments for tor + :param torrc_path: location of the torrc for us to use + :param completion_percent: percent of bootstrap completion at which this'll return - :param functor init_msg_handler: optional functor that will be provided with + :param init_msg_handler: optional functor that will be provided with tor's initialization stdout as we get it - :param int timeout: time after which the attempt to start tor is aborted, no + :param timeout: time after which the attempt to start tor is aborted, no timeouts are applied if **None** - :param bool take_ownership: asserts ownership over the tor process so it + :param take_ownership: asserts ownership over the tor process so it aborts if this python process terminates or a :class:`~stem.control.Controller` we establish to it disconnects - :param bool close_output: closes tor's stdout and stderr streams when + :param close_output: closes tor's stdout and stderr streams when bootstrapping is complete if true - :param str stdin: content to provide on stdin + :param stdin: content to provide on stdin :returns: **subprocess.Popen** instance for the tor subprocess @@ -222,19 +222,19 @@ def launch_tor_with_config(config: Dict[str, Union[str, Sequence[str]]], tor_cmd .. versionchanged:: 1.7.0 Added the **close_output** argument. - :param dict config: configuration options, such as "{'ControlPort': '9051'}", + :param config: configuration options, such as "{'ControlPort': '9051'}", values can either be a **str** or **list of str** if for multiple values - :param str tor_cmd: command for starting tor - :param int completion_percent: percent of bootstrap completion at which + :param tor_cmd: command for starting tor + :param completion_percent: percent of bootstrap completion at which this'll return - :param functor init_msg_handler: optional functor that will be provided with + :param init_msg_handler: optional functor that will be provided with tor's initialization stdout as we get it - :param int timeout: time after which the attempt to start tor is aborted, no + :param timeout: time after which the attempt to start tor is aborted, no timeouts are applied if **None** - :param bool take_ownership: asserts ownership over the tor process so it + :param take_ownership: asserts ownership over the tor process so it aborts if this python process terminates or a :class:`~stem.control.Controller` we establish to it disconnects - :param bool close_output: closes tor's stdout and stderr streams when + :param close_output: closes tor's stdout and stderr streams when bootstrapping is complete if true :returns: **subprocess.Popen** instance for the tor subprocess diff --git a/stem/response/__init__.py b/stem/response/__init__.py index 2f851389..af779324 100644 --- a/stem/response/__init__.py +++ b/stem/response/__init__.py @@ -76,8 +76,8 @@ def convert(response_type: str, message: 'stem.response.ControlMessage', **kwarg **SINGLELINE** :class:`stem.response.SingleLineResponse` =================== ===== - :param str response_type: type of tor response to convert to - :param stem.response.ControlMessage message: message to be converted + :param response_type: type of tor response to convert to + :param message: message to be converted :param kwargs: optional keyword arguments to be passed to the parser method :raises: @@ -184,9 +184,9 @@ class ControlMessage(object): .. versionchanged:: 1.6.0 Added the normalize argument. - :param str content: message to construct the message from - :param str msg_type: type of tor reply to parse the content as - :param bool normalize: ensures expected carriage return and ending newline + :param content: message to construct the message from + :param msg_type: type of tor reply to parse the content as + :param normalize: ensures expected carriage return and ending newline are present :param kwargs: optional keyword arguments to be passed to the parser method @@ -271,7 +271,7 @@ class ControlMessage(object): .. versionchanged:: 1.1.0 Added the get_bytes argument. - :param bool get_bytes: provides **bytes** for the **content** rather than a **str** + :param get_bytes: provides **bytes** for the **content** rather than a **str** :returns: **list** of (str, str, str) tuples for the components of this message """ @@ -288,7 +288,7 @@ class ControlMessage(object): .. versionchanged:: 1.1.0 Added the get_bytes argument. - :param bool get_bytes: if **True** then this provides **bytes** rather than a **str** + :param get_bytes: if **True** then this provides **bytes** rather than a **str** :returns: **str** of the socket data used to generate this message """ @@ -405,7 +405,7 @@ class ControlLine(str): """ Checks if our next entry is a quoted value or not. - :param bool escaped: unescapes the string + :param escaped: unescapes the string :returns: **True** if the next entry can be parsed as a quoted value, **False** otherwise """ @@ -417,9 +417,9 @@ class ControlLine(str): """ Checks if our next entry is a KEY=VALUE mapping or not. - :param str key: checks that the key matches this value, skipping the check if **None** - :param bool quoted: checks that the mapping is to a quoted value - :param bool escaped: unescapes the string + :param key: checks that the key matches this value, skipping the check if **None** + :param quoted: checks that the mapping is to a quoted value + :param escaped: unescapes the string :returns: **True** if the next entry can be parsed as a key=value mapping, **False** otherwise @@ -476,8 +476,8 @@ class ControlLine(str): >>> print line.pop(True, True) "this has a \\" and \\\\ in it" - :param bool quoted: parses the next entry as a quoted value, removing the quotes - :param bool escaped: unescapes the string + :param quoted: parses the next entry as a quoted value, removing the quotes + :param escaped: unescapes the string :returns: **str** of the next space separated entry @@ -504,9 +504,9 @@ class ControlLine(str): .. versionchanged:: 1.6.0 Added the get_bytes argument. - :param bool quoted: parses the value as being quoted, removing the quotes - :param bool escaped: unescapes the string - :param bool get_bytes: provides **bytes** for the **value** rather than a **str** + :param quoted: parses the value as being quoted, removing the quotes + :param escaped: unescapes the string + :param get_bytes: provides **bytes** for the **value** rather than a **str** :returns: **tuple** of the form (key, value) @@ -537,10 +537,10 @@ def _parse_entry(line: str, quoted: bool, escaped: bool, get_bytes: bool) -> Tup """ Parses the next entry from the given space separated content. - :param str line: content to be parsed - :param bool quoted: parses the next entry as a quoted value, removing the quotes - :param bool escaped: unescapes the string - :param bool get_bytes: provides **bytes** for the entry rather than a **str** + :param line: content to be parsed + :param quoted: parses the next entry as a quoted value, removing the quotes + :param escaped: unescapes the string + :param get_bytes: provides **bytes** for the entry rather than a **str** :returns: **tuple** of the form (entry, remainder) @@ -598,8 +598,8 @@ def _get_quote_indices(line: str, escaped: bool) -> Tuple[int, int]: """ Provides the indices of the next two quotes in the given content. - :param str line: content to be parsed - :param bool escaped: unescapes the string + :param line: content to be parsed + :param escaped: unescapes the string :returns: **tuple** of two ints, indices being -1 if a quote doesn't exist """ @@ -635,7 +635,7 @@ class SingleLineResponse(ControlMessage): Checks if the response code is "250". If strict is **True** then this checks if the response is "250 OK" - :param bool strict: checks for a "250 OK" message if **True** + :param strict: checks for a "250 OK" message if **True** :returns: * If strict is **False**: **True** if the response code is "250", **False** otherwise diff --git a/stem/response/events.py b/stem/response/events.py index 65419fe6..300d02d0 100644 --- a/stem/response/events.py +++ b/stem/response/events.py @@ -134,7 +134,7 @@ class Event(stem.response.ControlMessage): """ Parses an iso timestamp (ISOTime2Frac in the control-spec). - :param str timestamp: timestamp to parse + :param timestamp: timestamp to parse :returns: **datetime** with the parsed timestamp @@ -158,8 +158,8 @@ class Event(stem.response.ControlMessage): Checks if an attribute exists in a given enumeration, logging a message if it isn't. Attributes can either be for a string or collection of strings - :param str attr: name of the attribute to check - :param stem.util.enum.Enum enum: enumeration to check against + :param attr: name of the attribute to check + :param enum: enumeration to check against """ attr_values = getattr(self, attr) @@ -1485,7 +1485,7 @@ def _parse_cell_type_mapping(mapping: str) -> Dict[str, int]: ... in which keys are strings and values are integers. - :param str mapping: value to be parsed + :param mapping: value to be parsed :returns: dict of **str => int** mappings diff --git a/stem/response/getinfo.py b/stem/response/getinfo.py index 9d9da21b..4473b942 100644 --- a/stem/response/getinfo.py +++ b/stem/response/getinfo.py @@ -72,7 +72,7 @@ class GetInfoResponse(stem.response.ControlMessage): """ Checks if we match a given set of parameters, and raise a ProtocolError if not. - :param set params: parameters to assert that we contain + :param params: parameters to assert that we contain :raises: * :class:`stem.ProtocolError` if parameters don't match this response diff --git a/stem/socket.py b/stem/socket.py index b5da4b78..81019cf2 100644 --- a/stem/socket.py +++ b/stem/socket.py @@ -356,9 +356,9 @@ class RelaySocket(BaseSocket): """ RelaySocket constructor. - :param str address: ip address of the relay - :param int port: orport of the relay - :param bool connect: connects to the socket if True, leaves it unconnected otherwise + :param address: ip address of the relay + :param port: orport of the relay + :param connect: connects to the socket if True, leaves it unconnected otherwise :raises: :class:`stem.SocketError` if connect is **True** and we're unable to establish a connection @@ -375,7 +375,7 @@ class RelaySocket(BaseSocket): """ Sends a message to the relay's ORPort. - :param str message: message to be formatted and sent to the socket + :param message: message to be formatted and sent to the socket :raises: * :class:`stem.SocketError` if a problem arises in using the socket @@ -388,7 +388,7 @@ class RelaySocket(BaseSocket): """ Receives a message from the relay. - :param float timeout: maxiumum number of seconds to await a response, this + :param timeout: maxiumum number of seconds to await a response, this blocks indefinitely if **None** :returns: bytes for the message received @@ -444,7 +444,7 @@ class ControlSocket(BaseSocket): Formats and sends a message to the control socket. For more information see the :func:`~stem.socket.send_message` function. - :param str message: message to be formatted and sent to the socket + :param message: message to be formatted and sent to the socket :raises: * :class:`stem.SocketError` if a problem arises in using the socket @@ -481,9 +481,9 @@ class ControlPort(ControlSocket): """ ControlPort constructor. - :param str address: ip address of the controller - :param int port: port number of the controller - :param bool connect: connects to the socket if True, leaves it unconnected otherwise + :param address: ip address of the controller + :param port: port number of the controller + :param connect: connects to the socket if True, leaves it unconnected otherwise :raises: :class:`stem.SocketError` if connect is **True** and we're unable to establish a connection @@ -520,8 +520,8 @@ class ControlSocketFile(ControlSocket): """ ControlSocketFile constructor. - :param str socket_path: path where the control socket is located - :param bool connect: connects to the socket if True, leaves it unconnected otherwise + :param socket_path: path where the control socket is located + :param connect: connects to the socket if True, leaves it unconnected otherwise :raises: :class:`stem.SocketError` if connect is **True** and we're unable to establish a connection @@ -566,10 +566,10 @@ def send_message(control_file: BinaryIO, message: Union[bytes, str], raw: bool = <line 3>\\r\\n .\\r\\n - :param file control_file: file derived from the control socket (see the + :param control_file: file derived from the control socket (see the socket's makefile() method for more information) - :param str message: message to be sent on the control socket - :param bool raw: leaves the message formatting untouched, passing it to the + :param message: message to be sent on the control socket + :param raw: leaves the message formatting untouched, passing it to the socket as-is :raises: @@ -618,7 +618,7 @@ def recv_message(control_file: BinaryIO, arrived_at: Optional[float] = None) -> Pulls from a control socket until we either have a complete message or encounter a problem. - :param file control_file: file derived from the control socket (see the + :param control_file: file derived from the control socket (see the socket's makefile() method for more information) :returns: :class:`~stem.response.ControlMessage` read from the socket @@ -740,7 +740,7 @@ def send_formatting(message: str) -> str: Performs the formatting expected from sent control messages. For more information see the :func:`~stem.socket.send_message` function. - :param str message: message to be formatted + :param message: message to be formatted :returns: **str** of the message wrapped by the formatting expected from controllers diff --git a/stem/util/__init__.py b/stem/util/__init__.py index 498234cd..e4fa3ca8 100644 --- a/stem/util/__init__.py +++ b/stem/util/__init__.py @@ -72,7 +72,7 @@ def datetime_to_unix(timestamp: 'datetime.datetime') -> float: .. versionadded:: 1.5.0 - :param datetime timestamp: timestamp to be converted + :param timestamp: timestamp to be converted :returns: **float** for the unix timestamp of the given datetime object """ @@ -115,10 +115,10 @@ def _hash_attr(obj: Any, *attributes: str, **kwargs: Any): """ Provide a hash value for the given set of attributes. - :param Object obj: object to be hashed - :param list attributes: attribute names to take into account - :param bool cache: persists hash in a '_cached_hash' object attribute - :param class parent: include parent's hash value + :param obj: object to be hashed + :param attributes: attribute names to take into account + :param cache: persists hash in a '_cached_hash' object attribute + :param parent: include parent's hash value """ is_cached = kwargs.get('cache', False) diff --git a/stem/util/conf.py b/stem/util/conf.py index 1fd31fd0..1ac0d107 100644 --- a/stem/util/conf.py +++ b/stem/util/conf.py @@ -214,9 +214,9 @@ def config_dict(handle: str, conf_mappings: Dict[str, Any], handler: Optional[Ca **The dictionary you get from this is manged by the Config class and should be treated as being read-only.** - :param str handle: unique identifier for a config instance - :param dict conf_mappings: config key/value mappings used as our defaults - :param functor handler: function referred to prior to assigning values + :param handle: unique identifier for a config instance + :param conf_mappings: config key/value mappings used as our defaults + :param handler: function referred to prior to assigning values :returns: mapping of attributes to their current configuration value """ @@ -232,7 +232,7 @@ def get_config(handle: str) -> 'stem.util.conf.Config': already exists for the handle then it's returned. Otherwise a fresh instance is constructed. - :param str handle: unique identifier used to access this config instance + :param handle: unique identifier used to access this config instance """ if handle not in CONFS: @@ -259,9 +259,9 @@ def uses_settings(handle: str, path: str, lazy_load: bool = True) -> Callable: def my_function(config): print 'hello %s!' % config.get('username', '') - :param str handle: hande for the configuration - :param str path: path where the configuration should be loaded from - :param bool lazy_load: loads the configuration file when the decorator is + :param handle: hande for the configuration + :param path: path where the configuration should be loaded from + :param lazy_load: loads the configuration file when the decorator is used if true, otherwise it's loaded right away :returns: **function** that can be used as a decorator to provide the @@ -298,9 +298,9 @@ def parse_enum(key: str, value: str, enumeration: 'stem.util.enum.Enum') -> Any: Provides the enumeration value for a given key. This is a case insensitive lookup and raises an exception if the enum key doesn't exist. - :param str key: configuration key being looked up - :param str value: value to be parsed - :param stem.util.enum.Enum enumeration: enumeration the values should be in + :param key: configuration key being looked up + :param value: value to be parsed + :param enumeration: enumeration the values should be in :returns: enumeration value @@ -325,10 +325,10 @@ def parse_enum_csv(key: str, value: str, enumeration: 'stem.util.enum.Enum', cou is inclusive and either can be None to indicate the lack of a lower or upper bound. - :param str key: configuration key being looked up - :param str value: value to be parsed - :param stem.util.enum.Enum enumeration: enumeration the values should be in - :param int,tuple count: validates that we have this many items + :param key: configuration key being looked up + :param value: value to be parsed + :param enumeration: enumeration the values should be in + :param count: validates that we have this many items :returns: list with the enumeration values @@ -479,9 +479,9 @@ class Config(object): .. versionchanged:: 1.6.0 Avoid loading vim swap files. - :param str path: file or directory path to be loaded, this uses the last + :param path: file or directory path to be loaded, this uses the last loaded path if not provided - :param bool commenting: ignore line content after a '#' if **True**, read + :param commenting: ignore line content after a '#' if **True**, read otherwise :raises: @@ -544,7 +544,7 @@ class Config(object): Saves configuration contents to disk. If a path is provided then it replaces the configuration location that we track. - :param str path: location to be saved to + :param path: location to be saved to :raises: * **IOError** if we fail to save the file (insufficient permissions, etc) @@ -584,8 +584,8 @@ class Config(object): Registers the function to be notified of configuration updates. Listeners are expected to be functors which accept (config, key). - :param functor listener: function to be notified when our configuration is changed - :param bool backfill: calls the function with our current values if **True** + :param listener: function to be notified when our configuration is changed + :param backfill: calls the function with our current values if **True** """ with self._contents_lock: @@ -631,9 +631,9 @@ class Config(object): .. versionchanged:: 1.5.0 Allow removal of values by overwriting with a **None** value. - :param str key: key for the configuration mapping - :param str,list value: value we're setting the mapping to - :param bool overwrite: replaces the previous value if **True**, otherwise + :param key: key for the configuration mapping + :param value: value we're setting the mapping to + :param overwrite: replaces the previous value if **True**, otherwise the values are appended """ @@ -694,8 +694,8 @@ class Config(object): * values are split into key/value pairs on "=>" with extra whitespace stripped - :param str key: config setting to be fetched - :param default object: value provided if no such key exists or fails to be converted + :param key: config setting to be fetched + :param default: value provided if no such key exists or fails to be converted :returns: given configuration value with its type inferred with the above rules """ @@ -746,9 +746,9 @@ class Config(object): """ This provides the current value associated with a given key. - :param str key: config setting to be fetched - :param object default: value provided if no such key exists - :param bool multiple: provides back a list of all values if **True**, + :param key: config setting to be fetched + :param default: value provided if no such key exists + :param multiple: provides back a list of all values if **True**, otherwise this returns the last loaded configuration value :returns: **str** or **list** of string configuration values associated diff --git a/stem/util/connection.py b/stem/util/connection.py index 21745c43..f8a21f50 100644 --- a/stem/util/connection.py +++ b/stem/util/connection.py @@ -164,10 +164,10 @@ def download(url: str, timeout: Optional[float] = None, retries: Optional[int] = .. versionadded:: 1.8.0 - :param str url: uncompressed url to download from - :param float timeout: timeout when connection becomes idle, no timeout + :param url: uncompressed url to download from + :param timeout: timeout when connection becomes idle, no timeout applied if **None** - :param int retires: maximum attempts to impose + :param retires: maximum attempts to impose :returns: **bytes** content of the given url @@ -213,11 +213,11 @@ def get_connections(resolver: Optional['stem.util.connection.Resolver'] = None, .. versionchanged:: 1.5.0 IPv6 support when resolving via proc, netstat, lsof, or ss. - :param Resolver resolver: method of connection resolution to use, if not + :param resolver: method of connection resolution to use, if not provided then one is picked from among those that should likely be available for the system - :param int process_pid: pid of the process to retrieve - :param str process_name: name of the process to retrieve + :param process_pid: pid of the process to retrieve + :param process_name: name of the process to retrieve :returns: **list** of :class:`~stem.util.connection.Connection` instances @@ -345,7 +345,7 @@ def system_resolvers(system: Optional[str] = None) -> Sequence['stem.util.connec Renamed from get_system_resolvers() to system_resolvers(). The old name still works as an alias, but will be dropped in Stem version 2.0.0. - :param str system: system to get resolvers for, this is determined by + :param system: system to get resolvers for, this is determined by platform.system() if not provided :returns: **list** of :data:`~stem.util.connection.Resolver` instances available on this platform @@ -391,7 +391,7 @@ def port_usage(port: int) -> Optional[str]: .. versionadded:: 1.2.0 - :param int port: port number to look up + :param port: port number to look up :returns: **str** with a description for the port, **None** if none is known """ @@ -434,7 +434,7 @@ def is_valid_ipv4_address(address: str) -> bool: """ Checks if a string is a valid IPv4 address. - :param str address: string to be checked + :param address: string to be checked :returns: **True** if input is a valid IPv4 address, **False** otherwise """ @@ -463,8 +463,8 @@ def is_valid_ipv6_address(address: str, allow_brackets: bool = False) -> bool: """ Checks if a string is a valid IPv6 address. - :param str address: string to be checked - :param bool allow_brackets: ignore brackets which form '[address]' + :param address: string to be checked + :param allow_brackets: ignore brackets which form '[address]' :returns: **True** if input is a valid IPv6 address, **False** otherwise """ @@ -518,8 +518,8 @@ def is_valid_port(entry: Union[str, int, Sequence[str], Sequence[int]], allow_ze """ Checks if a string or int is a valid port number. - :param list,str,int entry: string, integer or list to be checked - :param bool allow_zero: accept port number of zero (reserved by definition) + :param entry: string, integer or list to be checked + :param allow_zero: accept port number of zero (reserved by definition) :returns: **True** if input is an integer and within the valid port range, **False** otherwise """ @@ -556,7 +556,7 @@ def is_private_address(address: str) -> bool: .. versionadded:: 1.1.0 - :param str address: string to be checked + :param address: string to be checked :returns: **True** if input is in a private range, **False** otherwise @@ -589,7 +589,7 @@ def address_to_int(address: str) -> int: .. versionadded:: 1.5.0 - :param str address: IPv4 or IPv6 address + :param address: IPv4 or IPv6 address :returns: **int** representation of the address """ @@ -616,7 +616,7 @@ def expand_ipv6_address(address: str) -> str: >>> expand_ipv6_address('::ffff:5.9.158.75') '0000:0000:0000:0000:0000:ffff:0509:9e4b' - :param str address: IPv6 address to be expanded + :param address: IPv6 address to be expanded :raises: **ValueError** if the address can't be expanded due to being malformed """ @@ -668,7 +668,7 @@ def get_mask_ipv4(bits: int) -> str: """ Provides the IPv4 mask for a given number of bits, in the dotted-quad format. - :param int bits: number of bits to be converted + :param bits: number of bits to be converted :returns: **str** with the subnet mask representation for this many bits @@ -695,7 +695,7 @@ def get_mask_ipv6(bits: int) -> str: Provides the IPv6 mask for a given number of bits, in the hex colon-delimited format. - :param int bits: number of bits to be converted + :param bits: number of bits to be converted :returns: **str** with the subnet mask representation for this many bits @@ -722,7 +722,7 @@ def _get_masked_bits(mask: str) -> int: Provides the number of bits that an IPv4 subnet mask represents. Note that not all masks can be represented by a bit count. - :param str mask: mask to be converted + :param mask: mask to be converted :returns: **int** with the number of bits represented by the mask @@ -747,8 +747,8 @@ def _get_binary(value: int, bits: int) -> str: Provides the given value as a binary string, padded with zeros to the given number of bits. - :param int value: value to be converted - :param int bits: number of bits to pad to + :param value: value to be converted + :param bits: number of bits to pad to :returns: **str** of this binary value """ @@ -764,7 +764,7 @@ def _address_to_binary(address: str) -> str: """ Provides the binary value for an IPv4 or IPv6 address. - :param str address: address to convert + :param address: address to convert :returns: **str** with the binary representation of this address diff --git a/stem/util/enum.py b/stem/util/enum.py index 719a4c06..a946305d 100644 --- a/stem/util/enum.py +++ b/stem/util/enum.py @@ -56,7 +56,7 @@ def UppercaseEnum(*args: str) -> 'Enum': >>> runlevels.DEBUG 'DEBUG' - :param list args: enum keys to initialize with + :param args: enum keys to initialize with :returns: :class:`~stem.util.enum.Enum` instance with the given keys """ @@ -104,7 +104,7 @@ class Enum(object): """ Provides the index of the given value in the collection. - :param object value: entry to be looked up + :param value: entry to be looked up :returns: **int** index of the given entry @@ -117,7 +117,7 @@ class Enum(object): """ Provides the next enumeration after the given value. - :param object value: enumeration for which to get the next entry + :param value: enumeration for which to get the next entry :returns: enum value following the given entry @@ -134,7 +134,7 @@ class Enum(object): """ Provides the previous enumeration before the given value. - :param object value: enumeration for which to get the previous entry + :param value: enumeration for which to get the previous entry :returns: enum value proceeding the given entry @@ -151,7 +151,7 @@ class Enum(object): """ Provides the values for the given key. - :param str item: key to look up + :param item: key to look up :returns: value for the given key diff --git a/stem/util/log.py b/stem/util/log.py index 404249a7..ca1ecc72 100644 --- a/stem/util/log.py +++ b/stem/util/log.py @@ -117,7 +117,7 @@ def logging_level(runlevel: 'stem.util.log.Runlevel') -> int: """ Translates a runlevel into the value expected by the logging module. - :param stem.util.log.Runlevel runlevel: runlevel to be returned, no logging if **None** + :param runlevel: runlevel to be returned, no logging if **None** """ if runlevel: @@ -147,7 +147,7 @@ def escape(message: str) -> str: Escapes specific sequences for logging (newlines, tabs, carriage returns). If the input is **bytes** then this converts it to **unicode** under python 3.x. - :param str message: string to be escaped + :param message: string to be escaped :returns: str that is escaped """ @@ -164,8 +164,8 @@ def log(runlevel: 'stem.util.log.Runlevel', message: str) -> None: """ Logs a message at the given runlevel. - :param stem.util.log.Runlevel runlevel: runlevel to log the message at, logging is skipped if **None** - :param str message: message to be logged + :param runlevel: runlevel to log the message at, logging is skipped if **None** + :param message: message to be logged """ if runlevel: @@ -177,9 +177,9 @@ def log_once(message_id: str, runlevel: 'stem.util.log.Runlevel', message: str) Logs a message at the given runlevel. If a message with this ID has already been logged then this is a no-op. - :param str message_id: unique message identifier to deduplicate on - :param stem.util.log.Runlevel runlevel: runlevel to log the message at, logging is skipped if **None** - :param str message: message to be logged + :param message_id: unique message identifier to deduplicate on + :param runlevel: runlevel to log the message at, logging is skipped if **None** + :param message: message to be logged :returns: **True** if we log the message, **False** otherwise """ @@ -234,7 +234,7 @@ def log_to_stdout(runlevel: 'stem.util.log.Runlevel') -> None: """ Logs further events to stdout. - :param stem.util.log.Runlevel runlevel: minimum runlevel a message needs to be to be logged + :param runlevel: minimum runlevel a message needs to be to be logged """ get_logger().addHandler(_StdoutLogger(runlevel)) diff --git a/stem/util/proc.py b/stem/util/proc.py index e180bb66..1c23fc0d 100644 --- a/stem/util/proc.py +++ b/stem/util/proc.py @@ -151,7 +151,7 @@ def cwd(pid: int) -> str: """ Provides the current working directory for the given process. - :param int pid: process id of the process to be queried + :param pid: process id of the process to be queried :returns: **str** with the path of the working directory for the process @@ -179,7 +179,7 @@ def uid(pid: int) -> int: """ Provides the user ID the given process is running under. - :param int pid: process id of the process to be queried + :param pid: process id of the process to be queried :returns: **int** with the user id for the owner of the process @@ -204,7 +204,7 @@ def memory_usage(pid: int) -> Tuple[int, int]: """ Provides the memory usage in bytes for the given process. - :param int pid: process id of the process to be queried + :param pid: process id of the process to be queried :returns: **tuple** of two ints with the memory usage of the process, of the form **(resident_size, virtual_size)** @@ -238,8 +238,8 @@ def stats(pid: int, *stat_types: 'stem.util.proc.Stat') -> Sequence[str]: Provides process specific information. See the :data:`~stem.util.proc.Stat` enum for valid options. - :param int pid: process id of the process to be queried - :param Stat stat_types: information to be provided back + :param pid: process id of the process to be queried + :param stat_types: information to be provided back :returns: **tuple** with all of the requested statistics as strings @@ -308,7 +308,7 @@ def file_descriptors_used(pid: int) -> int: .. versionadded:: 1.3.0 - :param int pid: process id of the process to be queried + :param pid: process id of the process to be queried :returns: **int** of the number of file descriptors used @@ -335,8 +335,8 @@ def connections(pid: Optional[int] = None, user: Optional[str] = None) -> Sequen friends but is much faster. If no **pid** or **user** are provided this provides all present connections. - :param int pid: pid to provide connections for - :param str user: username to look up connections for + :param pid: pid to provide connections for + :param user: username to look up connections for :returns: **list** of :class:`~stem.util.connection.Connection` instances @@ -418,7 +418,7 @@ def _inodes_for_sockets(pid: int) -> Set[bytes]: """ Provides inodes in use by a process for its sockets. - :param int pid: process id of the process to be queried + :param pid: process id of the process to be queried :returns: **set** with inodes for its sockets @@ -463,7 +463,7 @@ def _unpack_addr(addr: bytes) -> str: "0500000A" -> "10.0.0.5" "F804012A4A5190010000000002000000" -> "2a01:4f8:190:514a::2" - :param str addr: proc address entry to be decoded + :param addr: proc address entry to be decoded :returns: **str** of the decoded address """ @@ -515,9 +515,9 @@ def _get_lines(file_path: str, line_prefixes: Sequence[str], parameter: str) -> Fetches lines with the given prefixes from a file. This only provides back the first instance of each prefix. - :param str file_path: path of the file to read - :param tuple line_prefixes: string prefixes of the lines to return - :param str parameter: description of the proc attribute being fetch + :param file_path: path of the file to read + :param line_prefixes: string prefixes of the lines to return + :param parameter: description of the proc attribute being fetch :returns: mapping of prefixes to the matching line @@ -558,9 +558,9 @@ def _log_runtime(parameter: str, proc_location: str, start_time: float) -> None: """ Logs a message indicating a successful proc query. - :param str parameter: description of the proc attribute being fetch - :param str proc_location: proc files we were querying - :param int start_time: unix time for when this query was started + :param parameter: description of the proc attribute being fetch + :param proc_location: proc files we were querying + :param start_time: unix time for when this query was started """ runtime = time.time() - start_time @@ -571,8 +571,8 @@ def _log_failure(parameter: str, exc: BaseException) -> None: """ Logs a message indicating that the proc query failed. - :param str parameter: description of the proc attribute being fetch - :param Exception exc: exception that we're raising + :param parameter: description of the proc attribute being fetch + :param exc: exception that we're raising """ log.debug('proc call failed (%s): %s' % (parameter, exc)) diff --git a/stem/util/str_tools.py b/stem/util/str_tools.py index a0bef734..64bcfc46 100644 --- a/stem/util/str_tools.py +++ b/stem/util/str_tools.py @@ -67,7 +67,7 @@ def _to_bytes(msg: Union[str, bytes]) -> bytes: http://python3porting.com/problems.html#nicer-solutions - :param str,unicode msg: string to be converted + :param msg: string to be converted :returns: ASCII bytes for string """ @@ -84,7 +84,7 @@ def _to_unicode(msg: Union[str, bytes]) -> str: provide python 3 compatability, normalizing the unicode/ASCII change in the version bump. - :param str,unicode msg: string to be converted + :param msg: string to be converted :returns: unicode conversion """ @@ -110,7 +110,7 @@ def _to_int(msg: Union[str, bytes]) -> int: """ Serializes a string to a number. - :param str msg: string to be serialized + :param msg: string to be serialized :returns: **int** representation of the string """ @@ -131,9 +131,9 @@ def _to_camel_case(label: str, divider: str = '_', joiner: str = ' ') -> str: >>> _to_camel_case('I_LIKE_PEPPERJACK!') 'I Like Pepperjack!' - :param str label: input string to be converted - :param str divider: word boundary - :param str joiner: replacement for word boundaries + :param label: input string to be converted + :param divider: word boundary + :param joiner: replacement for word boundaries :returns: camel cased string """ @@ -169,8 +169,8 @@ def _split_by_length(msg, size): >>> _split_by_length('hello', 2) ['he', 'll', 'o'] - :param str msg: string to split - :param int size: number of characters to chunk into + :param msg: string to split + :param size: number of characters to chunk into :returns: **list** with chunked string components """ @@ -213,15 +213,15 @@ def crop(msg: str, size: int, min_word_length: int = 4, min_crop: int = 0, endin .. 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 + :param msg: text to be processed + :param size: space available for text + :param min_word_length: minimum characters before which a word is dropped, requires whole word if **None** - :param int min_crop: minimum characters that must be dropped if a word is + :param min_crop: minimum characters that must be dropped if a word is cropped - :param Ending ending: type of ending used when truncating, no special + :param ending: type of ending used when truncating, no special truncation is used if **None** - :param bool get_remainder: returns a tuple with the second part being the + :param get_remainder: returns a tuple with the second part being the cropped portion of the message :returns: **str** of the text truncated to the given length @@ -320,11 +320,11 @@ def size_label(byte_count: int, decimal: int = 0, is_long: bool = False, is_byte .. versionchanged:: 1.6.0 Added round argument. - :param int byte_count: number of bytes to be converted - :param int decimal: number of decimal digits to be included - :param bool is_long: expands units label - :param bool is_bytes: provides units in bytes if **True**, bits otherwise - :param bool round: rounds normally if **True**, otherwise rounds down + :param byte_count: number of bytes to be converted + :param decimal: number of decimal digits to be included + :param is_long: expands units label + :param is_bytes: provides units in bytes if **True**, bits otherwise + :param round: rounds normally if **True**, otherwise rounds down :returns: **str** with human readable representation of the size """ @@ -356,9 +356,9 @@ def time_label(seconds: int, decimal: int = 0, is_long: bool = False) -> str: >>> time_label(61, 2, True) '1.01 minutes' - :param int seconds: number of seconds to be converted - :param int decimal: number of decimal digits to be included - :param bool is_long: expands units label + :param seconds: number of seconds to be converted + :param decimal: number of decimal digits to be included + :param is_long: expands units label :returns: **str** with human readable representation of the time """ @@ -380,8 +380,8 @@ def time_labels(seconds: int, is_long: bool = False) -> Sequence[str]: >>> time_labels(3640, True) ['1 hour', '40 seconds'] - :param int seconds: number of seconds to be converted - :param bool is_long: expands units label + :param seconds: number of seconds to be converted + :param is_long: expands units label :returns: **list** of strings with human readable representations of the time """ @@ -409,7 +409,7 @@ def short_time_label(seconds: int) -> str: >>> short_time_label(544100) '6-07:08:20' - :param int seconds: number of seconds to be converted + :param seconds: number of seconds to be converted :returns: **str** with the short representation for the time @@ -450,7 +450,7 @@ def parse_short_time_label(label: str) -> int: >>> parse_short_time_label('6-07:08:20') 544100 - :param str label: time entry to be parsed + :param label: time entry to be parsed :returns: **int** with the number of seconds represented by the label @@ -489,7 +489,7 @@ def _parse_timestamp(entry: str) -> datetime.datetime: 2012-11-08 16:48:41 - :param str entry: timestamp to be parsed + :param entry: timestamp to be parsed :returns: **datetime** for the time represented by the timestamp @@ -515,7 +515,7 @@ def _parse_iso_timestamp(entry: str) -> 'datetime.datetime': 2012-11-08T16:48:41.420251 - :param str entry: timestamp to be parsed + :param entry: timestamp to be parsed :returns: **datetime** for the time represented by the timestamp @@ -550,12 +550,12 @@ def _get_label(units: Sequence[Tuple[float, str, str]], count: int, decimal: int Provides label corresponding to units of the highest significance in the provided set. This rounds down (ie, integer truncation after visible units). - :param tuple units: type of units to be used for conversion, containing + :param units: type of units to be used for conversion, containing (count_per_unit, short_label, long_label) - :param int count: number of base units being converted - :param int decimal: decimal precision of label - :param bool is_long: uses the long label if **True**, short label otherwise - :param bool round: rounds normally if **True**, otherwise rounds down + :param count: number of base units being converted + :param decimal: decimal precision of label + :param is_long: uses the long label if **True**, short label otherwise + :param round: rounds normally if **True**, otherwise rounds down """ # formatted string for the requested number of digits diff --git a/stem/util/system.py b/stem/util/system.py index a5147976..49589c5c 100644 --- a/stem/util/system.py +++ b/stem/util/system.py @@ -367,8 +367,8 @@ def is_available(command: str, cached: bool = True) -> bool: try to assume that it's available. This only happends for recognized shell commands (those in SHELL_COMMANDS). - :param str command: command to search for - :param bool cached: makes use of available cached results if **True** + :param command: command to search for + :param cached: makes use of available cached results if **True** :returns: **True** if an executable we can use by that name exists in the PATH, **False** otherwise @@ -407,8 +407,8 @@ def is_running(command: Union[str, int, Sequence[str]]) -> bool: .. versionchanged:: 1.6.0 Added support for list and pid arguments. - :param str,list,int command: process name if a str, multiple process names if - a list, or pid if an int to be checked + :param command: process name if a str, multiple process names if a list, or + pid if an int to be checked :returns: **True** if the process is running, **False** if it's not among ps results, and **None** if ps can't be queried @@ -475,8 +475,8 @@ def size_of(obj: Any, exclude: Optional[Collection[int]] = None) -> int: .. versionadded:: 1.6.0 - :param object obj: object to provide the size of - :param set exclude: object ids to exclude from size estimation + :param obj: object to provide the size of + :param exclude: object ids to exclude from size estimation :returns: **int** with the size of the object in bytes @@ -515,7 +515,7 @@ def name_by_pid(pid: int) -> Optional[str]: 1. Information from /proc 2. ps -p <pid> -o command - :param int pid: process id of the process to be queried + :param pid: process id of the process to be queried :returns: **str** with the process name, **None** if it can't be determined """ @@ -561,8 +561,8 @@ def pid_by_name(process_name: str, multiple: bool = False) -> Union[int, List[in 4. lsof -tc <name> 5. tasklist | str <name>.exe - :param str process_name: process name for which to fetch the pid - :param bool multiple: provides a list of all pids if **True**, otherwise + :param process_name: process name for which to fetch the pid + :param multiple: provides a list of all pids if **True**, otherwise results with multiple processes are discarded :returns: @@ -733,7 +733,7 @@ def pid_by_port(port: int) -> Optional[int]: Most queries limit results to listening TCP connections. This function likely won't work on Mac OSX. - :param int port: port where the process we're looking for is listening + :param port: port where the process we're looking for is listening :returns: **int** with the process id, **None** if it can't be determined """ @@ -848,7 +848,7 @@ def pid_by_open_file(path: str) -> Optional[int]: lsof -w <path> - :param str path: location of the socket file to query against + :param path: location of the socket file to query against :returns: **int** with the process id, **None** if it can't be determined """ @@ -883,7 +883,7 @@ def pids_by_user(user: str) -> Optional[Sequence[int]]: .. versionadded:: 1.5.0 - :param str user: user to look up processes for + :param user: user to look up processes for :returns: **list** with the process ids, **None** if it can't be determined """ @@ -913,7 +913,7 @@ def cwd(pid: int) -> Optional[str]: """ Provides the working directory of the given process. - :param int pid: process id of the process to be queried + :param pid: process id of the process to be queried :returns: **str** with the absolute path for the process' present working directory, **None** if it can't be determined @@ -982,7 +982,7 @@ def user(pid: int) -> Optional[str]: """ Provides the user a process is running under. - :param int pid: process id of the process to be queried + :param pid: process id of the process to be queried :returns: **str** with the username a process is running under, **None** if it can't be determined @@ -1013,7 +1013,7 @@ def start_time(pid: str) -> Optional[float]: """ Provides the unix timestamp when the given process started. - :param int pid: process id of the process to be queried + :param pid: process id of the process to be queried :returns: **float** for the unix timestamp when the process began, **None** if it can't be determined @@ -1049,8 +1049,8 @@ def tail(target: Union[str, BinaryIO], lines: Optional[int] = None) -> Iterator[ reversed(list(tail('/tmp/my_log', 50))) - :param str,file target: path or file object to read from - :param int lines: number of lines to read + :param target: path or file object to read from + :param lines: number of lines to read :returns: **generator** that reads lines, starting with the end @@ -1098,7 +1098,7 @@ def bsd_jail_id(pid: int) -> int: Gets the jail id for a process. These seem to only exist for FreeBSD (this style for jails does not exist on Linux, OSX, or OpenBSD). - :param int pid: process id of the jail id to be queried + :param pid: process id of the jail id to be queried :returns: **int** for the jail id, zero if this can't be determined """ @@ -1132,7 +1132,7 @@ def bsd_jail_path(jid: int) -> Optional[str]: """ Provides the path of the given FreeBSD jail. - :param int jid: jail id to be queried + :param jid: jail id to be queried :returns: **str** of the path prefix, **None** if this can't be determined """ @@ -1156,7 +1156,7 @@ def is_tarfile(path: str) -> bool: .. versionadded:: 1.2.0 - :param str path: path to be checked + :param path: path to be checked :returns: **True** if the path belongs to a tarball, **False** otherwise """ @@ -1181,8 +1181,8 @@ def expand_path(path: str, cwd: Optional[str] = None) -> str: Provides an absolute path, expanding tildes with the user's home and appending a current working directory if the path was relative. - :param str path: path to be expanded - :param str cwd: current working directory to expand relative paths with, our + :param path: path to be expanded + :param cwd: current working directory to expand relative paths with, our process' if this is **None** :returns: **str** of the path expanded to be an absolute path, never with an @@ -1228,8 +1228,8 @@ def files_with_suffix(base_path: str, suffix: str) -> Iterator[str]: .. versionadded:: 1.2.0 - :param str base_path: directory to be iterated over - :param str suffix: filename suffix to look for + :param base_path: directory to be iterated over + :param suffix: filename suffix to look for :returns: iterator that yields the absolute path for files with the given suffix """ @@ -1262,13 +1262,12 @@ def call(command: Union[str, Sequence[str]], default: Any = UNDEFINED, ignore_ex .. versionchanged:: 1.6.0 Added timeout and cwd arguments. - :param str,list command: command to be issued - :param object default: response if the query fails - :param bool ignore_exit_status: reports failure if our command's exit status + :param command: command to be issued + :param default: response if the query fails + :param ignore_exit_status: reports failure if our command's exit status was non-zero - :param float timeout: maximum seconds to wait, blocks indefinitely if - **None** - :param dict env: environment variables + :param timeout: maximum seconds to wait, blocks indefinitely if **None** + :param env: environment variables :returns: **list** with the lines of output from the command @@ -1402,7 +1401,7 @@ def set_process_name(process_name: str) -> None: Renames our current process from "python <args>" to a custom name. This is best-effort, not necessarily working on all platforms. - :param str process_name: new name for our process + :param process_name: new name for our process :raises: **IOError** if the process cannot be renamed """ diff --git a/stem/util/term.py b/stem/util/term.py index 862767c4..6ef53926 100644 --- a/stem/util/term.py +++ b/stem/util/term.py @@ -78,7 +78,7 @@ def encoding(*attrs: Union['stem.util.term.Color', 'stem.util.term.BgColor', 'st .. versionadded:: 1.5.0 - :param list attr: :data:`~stem.util.term.Color`, + :param attr: :data:`~stem.util.term.Color`, :data:`~stem.util.term.BgColor`, or :data:`~stem.util.term.Attr` to provide an ecoding for @@ -117,8 +117,8 @@ def format(msg: str, *attr: Union['stem.util.term.Color', 'stem.util.term.BgColo Normalized return value to be unicode to better support python 2/3 compatibility. - :param str msg: string to be formatted - :param str attr: text attributes, this can be :data:`~stem.util.term.Color`, + :param msg: string to be formatted + :param attr: text attributes, this can be :data:`~stem.util.term.Color`, :data:`~stem.util.term.BgColor`, or :data:`~stem.util.term.Attr` enums and are case insensitive (so strings like 'red' are fine) diff --git a/stem/util/test_tools.py b/stem/util/test_tools.py index 34573450..36b4110e 100644 --- a/stem/util/test_tools.py +++ b/stem/util/test_tools.py @@ -66,9 +66,9 @@ def assert_equal(expected: Any, actual: Any, msg: Optional[str] = None) -> None: .. versionadded:: 1.6.0 - :param object expected: expected value - :param object actual: actual value - :param str msg: message if assertion fails + :param expected: expected value + :param actual: actual value + :param msg: message if assertion fails :raises: **AssertionError** if values aren't equal """ @@ -83,9 +83,9 @@ def assert_in(expected: Any, actual: Any, msg: Optional[str] = None) -> None: .. versionadded:: 1.6.0 - :param object expected: expected value - :param object actual: actual value - :param str msg: message if assertion fails + :param expected: expected value + :param actual: actual value + :param msg: message if assertion fails :raises: **AssertionError** if the expected value isn't in the actual """ @@ -100,7 +100,7 @@ def skip(msg: str) -> None: .. versionadded:: 1.6.0 - :param str msg: reason test is being skipped + :param msg: reason test is being skipped :raises: **unittest.case.SkipTest** for this reason """ @@ -300,7 +300,7 @@ def clean_orphaned_pyc(paths: Sequence[str]) -> List[str]: * Another developer clones our repository and is confused because we have a bunch of ImportErrors. - :param list paths: paths to search for orphaned pyc files + :param paths: paths to search for orphaned pyc files :returns: **list** of absolute paths that were deleted """ @@ -413,12 +413,12 @@ def stylistic_issues(paths: Sequence[str], check_newlines: bool = False, check_e Changed 'pycodestyle.ignore' code snippets to only need to match against the prefix. - :param list paths: paths to search for stylistic issues - :param bool check_newlines: check that we have standard newlines (\\n), not + :param paths: paths to search for stylistic issues + :param check_newlines: check that we have standard newlines (\\n), not windows (\\r\\n) nor classic mac (\\r) - :param bool check_exception_keyword: checks that we're using 'as' for + :param check_exception_keyword: checks that we're using 'as' for exceptions rather than a comma - :param bool prefer_single_quotes: standardize on using single rather than + :param prefer_single_quotes: standardize on using single rather than double quotes for strings, when reasonable :returns: dict of paths list of :class:`stem.util.test_tools.Issue` instances @@ -526,7 +526,7 @@ def pyflakes_issues(paths: Sequence[str]) -> Dict[str, List['stem.util.test_tool .. versionchanged:: 1.5.0 Support matching against prefix or suffix issue strings. - :param list paths: paths to search for problems + :param paths: paths to search for problems :returns: dict of paths list of :class:`stem.util.test_tools.Issue` instances """ @@ -578,7 +578,7 @@ def type_issues(args: Sequence[str]) -> Dict[str, List['stem.util.test_tools.Iss mypy.ignore stem/util/system.py => Incompatible types in assignment* - :param list args: mypy commmandline arguments + :param args: mypy commmandline arguments :returns: dict of paths list of :class:`stem.util.test_tools.Issue` instances """ @@ -634,7 +634,7 @@ def _module_exists(module_name: str) -> bool: """ Checks if a module exists. - :param str module_name: module to check existance of + :param module_name: module to check existance of :returns: **True** if module exists and **False** otherwise """ diff --git a/stem/util/tor_tools.py b/stem/util/tor_tools.py index 2398b7bc..e2df4312 100644 --- a/stem/util/tor_tools.py +++ b/stem/util/tor_tools.py @@ -53,8 +53,8 @@ def is_valid_fingerprint(entry: str, check_prefix: bool = False) -> bool: a '$' prefix if check_prefix is true, otherwise this only validates the hex digits. - :param str entry: string to be checked - :param bool check_prefix: checks for a '$' prefix + :param entry: string to be checked + :param check_prefix: checks for a '$' prefix :returns: **True** if the string could be a relay fingerprint, **False** otherwise """ @@ -78,7 +78,7 @@ def is_valid_nickname(entry: str) -> bool: """ Checks if a string is a valid format for being a nickname. - :param str entry: string to check + :param entry: string to check :returns: **True** if the string could be a nickname, **False** otherwise """ @@ -96,7 +96,7 @@ def is_valid_circuit_id(entry: str) -> bool: """ Checks if a string is a valid format for being a circuit identifier. - :param str entry: string to check + :param entry: string to check :returns: **True** if the string could be a circuit id, **False** otherwise """ @@ -115,7 +115,7 @@ def is_valid_stream_id(entry: str) -> bool: Checks if a string is a valid format for being a stream identifier. Currently, this is just an alias to :func:`~stem.util.tor_tools.is_valid_circuit_id`. - :param str entry: string to check + :param entry: string to check :returns: **True** if the string could be a stream id, **False** otherwise """ @@ -128,7 +128,7 @@ def is_valid_connection_id(entry: str) -> bool: Checks if a string is a valid format for being a connection identifier. Currently, this is just an alias to :func:`~stem.util.tor_tools.is_valid_circuit_id`. - :param str entry: string to check + :param entry: string to check :returns: **True** if the string could be a connection id, **False** otherwise """ @@ -145,9 +145,9 @@ def is_valid_hidden_service_address(entry: str, version: Optional[Union[int, Seq Added the **version** argument, and responds with **True** if a version 3 hidden service address rather than just version 2 addresses. - :param str entry: string to check - :param int,list version: versions to check for, if unspecified either v2 or v3 - hidden service address will provide **True** + :param entry: string to check + :param version: versions to check for, if unspecified either v2 or v3 hidden + service address will provide **True** :returns: **True** if the string could be a hidden service address, **False** otherwise @@ -180,8 +180,8 @@ def is_hex_digits(entry: str, count: int) -> bool: Checks if a string is the given number of hex digits. Digits represented by letters are case insensitive. - :param str entry: string to be checked - :param int count: number of hex digits to be checked for + :param entry: string to be checked + :param count: number of hex digits to be checked for :returns: **True** if the given number of hex digits, **False** otherwise """ diff --git a/stem/version.py b/stem/version.py index 6ef7c890..d01e04d9 100644 --- a/stem/version.py +++ b/stem/version.py @@ -55,7 +55,7 @@ def get_system_tor_version(tor_cmd: str = 'tor') -> 'stem.version.Version': 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 + :param tor_cmd: command used to run tor :returns: :class:`~stem.version.Version` provided by the tor command @@ -122,7 +122,7 @@ class Version(object): :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 + :param version_str: version to be parsed :raises: **ValueError** if input isn't a valid tor version """

1 0

[stem/master] Add Sphinx sphinx_autodoc_typehints plugin
by atagar＠torproject.org 17 May '20

17 May '20

commit 4f55589f837db2e7a5d4bf7b3e971780fb0eaa5c Author: Damian Johnson <atagar(a)torproject.org> Date: Sat May 16 17:33:01 2020 -0700 Add Sphinx sphinx_autodoc_typehints plugin Our methods document parater types twice... def my_method(my_arg: str) => None: """ Dummy method. :param str my_arg: sample argument """ The method signature and :param: reStructured tag both cite our my_arg type. By using Sphinx's sphinx_autodoc_typehints plugin we can drop our parameter types... https://github.com/agronholm/sphinx-autodoc-typehints Deduplication aside this makes our API docs look nicer by stripping Python type hints from our signatures. In other words... stem.util.system.is_available(command: str, cached: bool = True) → bool Parameters: command (str) -- command to search for cached (bool) -- makes use of available cached results if True ... becomes... stem.util.system.is_available(command, cached=True) Parameters: command (str) -- command to search for cached (bool) -- makes use of available cached results if True --- docs/conf.py | 32 ++++++++++++++++++++++++++++++-- stem/manual.py | 6 +++--- 2 files changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index b880b114..f9aa73fc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,9 +11,37 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import os +import sys +import warnings + from sphinx.domains.python import PythonDomain +TYPEHINTS_REQUIRED = """\ +Building Stem's website requires... + + https://github.com/agronholm/sphinx-autodoc-typehints + +Please run... + + % pip install sphinx-autodoc-typehints +""" + +try: + import sphinx_autodoc_typehints +except ImportError: + print(TYPEHINTS_REQUIRED, file = sys.stderr) + sys.exit(1) + +# These warnings are due to: https://github.com/agronholm/sphinx-autodoc-typehints/issues/133 + +warnings.filterwarnings('ignore', message = 'sphinx.util.inspect.Signature is deprecated') + +# Drop redundant return types because we state this in our :returns: clasuses. +# This is an argument for sphinx-autodoc-typehints. + +typehints_document_rtype = False + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -27,7 +55,7 @@ needs_sphinx = '1.1' # required for the sphinx-apidoc command # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'roles'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_autodoc_typehints', 'roles'] autodoc_default_options = { 'members': True, diff --git a/stem/manual.py b/stem/manual.py index 9bc10b85..a5d3ebef 100644 --- a/stem/manual.py +++ b/stem/manual.py @@ -64,7 +64,7 @@ import stem.util.log import stem.util.str_tools import stem.util.system -from typing import Any, Dict, IO, List, Mapping, Optional, Sequence, Tuple, Union +from typing import Any, BinaryIO, Dict, List, Mapping, Optional, Sequence, Tuple, Union Category = stem.util.enum.Enum('GENERAL', 'CLIENT', 'RELAY', 'DIRECTORY', 'AUTHORITY', 'HIDDEN_SERVICE', 'DENIAL_OF_SERVICE', 'TESTING', 'UNKNOWN') GITWEB_MANUAL_URL = 'https://gitweb.torproject.org/tor.git/plain/doc/tor.1.txt' @@ -265,7 +265,7 @@ def is_important(option: str) -> bool: return option.lower() in _config()['manual.important'] -def download_man_page(path: Optional[str] = None, file_handle: Optional[IO[bytes]] = None, url: str = GITWEB_MANUAL_URL, timeout: int = 20) -> None: +def download_man_page(path: Optional[str] = None, file_handle: Optional[BinaryIO] = None, url: str = GITWEB_MANUAL_URL, timeout: int = 20) -> None: """ Downloads tor's latest man page from `gitweb.torproject.org <https://gitweb.torproject.org/tor.git/plain/doc/tor.1.txt>`_. This method is @@ -501,7 +501,7 @@ class Manual(object): """ with tempfile.NamedTemporaryFile() as tmp: - download_man_page(file_handle = tmp, timeout = timeout) + download_man_page(file_handle = tmp, timeout = timeout) # type: ignore return Manual.from_man(tmp.name) def save(self, path: str) -> None:

1 0

[torspec/master] resolve singularity for which version used the new version spec
by arma＠torproject.org 16 May '20

16 May '20

commit 63a9476cfd513a3b6e9d80c8f7f767dec769035d Author: Roger Dingledine <arma(a)torproject.org> Date: Sat May 16 18:10:17 2020 -0400 resolve singularity for which version used the new version spec --- version-spec.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/version-spec.txt b/version-spec.txt index e7f855c..63782b6 100644 --- a/version-spec.txt +++ b/version-spec.txt @@ -22,7 +22,7 @@ 2. The New Way - After 0.1.0, versions are of the format: + Starting at 0.1.0.1-rc, versions are of the format: MAJOR.MINOR.MICRO[.PATCHLEVEL][-STATUS_TAG][ (EXTRA_INFO)]*

1 0

[translation/bridgedb_completed] https://gitweb.torproject.org/translation.git/commit/?h=bridgedb_completed
by translation＠torproject.org 16 May '20

16 May '20

commit d75d261eea4847ad848972388b5a91dd109623e4 Author: Translation commit bot <translation(a)torproject.org> Date: Sat May 16 16:45:20 2020 +0000 https://gitweb.torproject.org/translation.git/commit/?h=bridgedb_completed --- it/LC_MESSAGES/bridgedb.po | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/it/LC_MESSAGES/bridgedb.po b/it/LC_MESSAGES/bridgedb.po index 83997d0d97..8046c4b2e1 100644 --- a/it/LC_MESSAGES/bridgedb.po +++ b/it/LC_MESSAGES/bridgedb.po @@ -10,6 +10,7 @@ # Francesca Ciceri <madamezou(a)zouish.org>, 2014 # Gabriele <gabboxl0(a)gmail.com>, 2020 # HostFat <hostfat(a)gmail.com>, 2015 +# Irene Quadrelli <irene.quadrelli(a)gmail.com>, 2020 # ironbishop <ironbishop(a)fsfe.org>, 2011 # ironbishop <ironbishop(a)fsfe.org>, 2011 # Jacob Appelbaum <jacob(a)appelbaum.net>, 2009 @@ -27,14 +28,14 @@ msgid "" msgstr "" "Project-Id-Version: Tor Project\n" "Report-Msgid-Bugs-To: 'https://trac.torproject.org/projects/tor/newticket?component=BridgeDB&keywo…'\n" -"POT-Creation-Date: 2020-04-09 14:45-0700\n" -"PO-Revision-Date: 2020-04-15 19:46+0000\n" -"Last-Translator: Transifex Bot <>\n" +"POT-Creation-Date: 2020-05-14 14:21-0700\n" +"PO-Revision-Date: 2020-05-16 16:43+0000\n" +"Last-Translator: Irene Quadrelli <irene.quadrelli(a)gmail.com>\n" "Language-Team: Italian (http://www.transifex.com/otf/torproject/language/it/)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 2.7.0\n" +"Generated-By: Babel 2.8.0\n" "Language: it\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" @@ -98,31 +99,26 @@ msgstr "Mostra Codice QR" msgid "QRCode for your bridge lines" msgstr "Codice QR per le tue bridge lines" -#. TRANSLATORS: Please translate this into some silly way to say -#. "There was a problem!" in your language. For example, -#. for Italian, you might translate this into "Mama mia!", -#. or for French: "Sacrebleu!". :) -#: bridgedb/distributors/https/templates/bridges.html:67 -#: bridgedb/distributors/https/templates/bridges.html:119 -msgid "Uh oh, spaghettios!" -msgstr "Figo!" - -#: bridgedb/distributors/https/templates/bridges.html:68 +#: bridgedb/distributors/https/templates/bridges.html:63 msgid "It seems there was an error getting your QRCode." msgstr "Sembra che ci sia stato un errore nell'ottenere il tuo QRCode." -#: bridgedb/distributors/https/templates/bridges.html:73 +#: bridgedb/distributors/https/templates/bridges.html:68 msgid "" "This QRCode contains your bridge lines. Scan it with a QRCode reader to copy" " your bridge lines onto mobile and other devices." msgstr "" -#: bridgedb/distributors/https/templates/bridges.html:125 +#: bridgedb/distributors/https/templates/bridges.html:110 +msgid "BridgeDB encountered an error." +msgstr "" + +#: bridgedb/distributors/https/templates/bridges.html:116 msgid "There currently aren't any bridges available..." msgstr "Non ci sono bridge disponibili al momento..." -#: bridgedb/distributors/https/templates/bridges.html:127 -#: bridgedb/distributors/https/templates/bridges.html:131 +#: bridgedb/distributors/https/templates/bridges.html:118 +#: bridgedb/distributors/https/templates/bridges.html:122 #, python-format msgid "" " Perhaps you should try %s going back %s and choosing a different bridge "

1 0

[translation/bridgedb] https://gitweb.torproject.org/translation.git/commit/?h=bridgedb
by translation＠torproject.org 16 May '20

16 May '20

commit 570844e46a0c98715fa857d51b50d7d71244400f Author: Translation commit bot <translation(a)torproject.org> Date: Sat May 16 16:45:13 2020 +0000 https://gitweb.torproject.org/translation.git/commit/?h=bridgedb --- it/LC_MESSAGES/bridgedb.po | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/it/LC_MESSAGES/bridgedb.po b/it/LC_MESSAGES/bridgedb.po index 61e0c859cb..afd682d5d5 100644 --- a/it/LC_MESSAGES/bridgedb.po +++ b/it/LC_MESSAGES/bridgedb.po @@ -10,6 +10,7 @@ # Francesca Ciceri <madamezou(a)zouish.org>, 2014 # Gabriele <gabboxl0(a)gmail.com>, 2020 # HostFat <hostfat(a)gmail.com>, 2015 +# Irene Quadrelli <irene.quadrelli(a)gmail.com>, 2020 # ironbishop <ironbishop(a)fsfe.org>, 2011 # ironbishop <ironbishop(a)fsfe.org>, 2011 # Jacob Appelbaum <jacob(a)appelbaum.net>, 2009 @@ -28,8 +29,8 @@ msgstr "" "Project-Id-Version: Tor Project\n" "Report-Msgid-Bugs-To: 'https://trac.torproject.org/projects/tor/newticket?component=BridgeDB&keywo…'\n" "POT-Creation-Date: 2020-05-14 14:21-0700\n" -"PO-Revision-Date: 2020-05-15 08:24+0000\n" -"Last-Translator: Transifex Bot <>\n" +"PO-Revision-Date: 2020-05-16 16:43+0000\n" +"Last-Translator: Irene Quadrelli <irene.quadrelli(a)gmail.com>\n" "Language-Team: Italian (http://www.transifex.com/otf/torproject/language/it/)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" @@ -110,7 +111,7 @@ msgstr "Questo codice QR contiene le tue linee ponte. Scansionalo con un lettore #: bridgedb/distributors/https/templates/bridges.html:110 msgid "BridgeDB encountered an error." -msgstr "" +msgstr "BridgeDB ha riscontrato un problema " #: bridgedb/distributors/https/templates/bridges.html:116 msgid "There currently aren't any bridges available..."

1 0

[metrics-lib/master] Bump version to 2.13.0-dev.
by karsten＠torproject.org 16 May '20

16 May '20

commit de0c37b0880f496f766068ab2b21d8602535cae3 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Sat May 16 17:35:44 2020 +0200 Bump version to 2.13.0-dev. --- CHANGELOG.md | 3 +++ build.xml | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bddabeb..100bed2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +# Changes in version 2.??.? - 2020-??-?? + + # Changes in version 2.13.0 - 2020-05-16 * Medium changes diff --git a/build.xml b/build.xml index 126be8e..0b57853 100644 --- a/build.xml +++ b/build.xml @@ -7,7 +7,7 @@ <project default="usage" name="metrics-lib" basedir="." xmlns:ivy="antlib:org.apache.ivy.ant"> - <property name="release.version" value="2.13.0" /> + <property name="release.version" value="2.13.0-dev" /> <property name="javadoc-title" value="Tor Metrics Library API Documentation"/> <property name="javadoc-excludes" value="**/impl/** **/index/** **/internal/** **/log/**" /> <property name="implementation-title" value="Tor Metrics Library" />

1 0

[metrics-lib/release] Include previously unknown error codes in Torperf results.
by karsten＠torproject.org 16 May '20

16 May '20

commit afc57a61209f806581c3c6ca472077fbcba835ec Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Tue May 12 21:35:58 2020 +0200 Include previously unknown error codes in Torperf results. As discussed on #34031, we should avoid keeping a map of known failure types in the sources and simply put together the error code in the format we want. This patch implements that change. --- CHANGELOG.md | 4 ++++ .../onionperf/OnionPerfAnalysisConverter.java | 24 ++++++++-------------- .../onionperf/OnionPerfAnalysisConverterTest.java | 2 +- 3 files changed, 13 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index af5a7f0..5ed2425 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changes in version 2.??.? - 2020-??-?? + * Minor changes + - Include previously unknown error codes in Torperf results + converted from OnionPerf analysis files. + # Changes in version 2.12.2 - 2020-04-30 diff --git a/src/main/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverter.java b/src/main/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverter.java index 18adf8c..8ca5efd 100644 --- a/src/main/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverter.java +++ b/src/main/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverter.java @@ -127,18 +127,6 @@ public class OnionPerfAnalysisConverter { private StringBuilder formatTorperfResults( ParsedOnionPerfAnalysis parsedOnionPerfAnalysis) { StringBuilder formattedTorperfResults = new StringBuilder(); - Map<String, String> errorCodes = new HashMap<>(); - errorCodes.put("AUTH", "TGEN/AUTH"); - errorCodes.put("READ", "TGEN/READ"); - errorCodes.put("STALLOUT", "TGEN/STALLOUT"); - errorCodes.put("TIMEOUT", "TGEN/TIMEOUT"); - errorCodes.put("PROXY", "TOR"); - errorCodes.put("PROXY_CANT_ATTACH", "TOR/CANT_ATTACH"); - errorCodes.put("PROXY_DESTROY", "TOR/DESTROY"); - errorCodes.put("PROXY_END_TIMEOUT", "TOR/END/TIMEOUT"); - errorCodes.put("PROXY_END_CONNECTREFUSED", "TOR/END/CONNECTREFUSED"); - errorCodes.put("PROXY_RESOLVEFAILED", "TOR/RESOLVEFAILED"); - errorCodes.put("PROXY_TIMEOUT", "TOR/TIMEOUT"); for (Map.Entry<String, ParsedOnionPerfAnalysis.MeasurementData> data : parsedOnionPerfAnalysis.data.entrySet()) { String nickname = data.getKey(); @@ -183,7 +171,12 @@ public class OnionPerfAnalysisConverter { List<String> errorCodeParts = null; if (transfer.isError) { errorCodeParts = new ArrayList<>(); - errorCodeParts.add(transfer.errorCode); + if ("PROXY".equals(transfer.errorCode)) { + errorCodeParts.add("TOR"); + } else { + errorCodeParts.add("TGEN"); + errorCodeParts.add(transfer.errorCode); + } } String sourcePort = endpointLocalParts[2]; if (streamsBySourcePort.containsKey(sourcePort)) { @@ -207,9 +200,8 @@ public class OnionPerfAnalysisConverter { } } if (null != errorCodeParts) { - String errorCode = String.join("_", errorCodeParts); - torperfResultsBuilder.addString("ERRORCODE", - errorCodes.getOrDefault(errorCode, errorCode)); + String errorCode = String.join("/", errorCodeParts); + torperfResultsBuilder.addString("ERRORCODE", errorCode); } formattedTorperfResults.append(torperfResultsBuilder.build()); } diff --git a/src/test/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverterTest.java b/src/test/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverterTest.java index c921a2d..7a1a3a0 100644 --- a/src/test/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverterTest.java +++ b/src/test/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverterTest.java @@ -70,7 +70,7 @@ public class OnionPerfAnalysisConverterTest { + "ENDPOINTLOCAL=localhost:127.0.0.1:40948 " + "ENDPOINTPROXY=localhost:127.0.0.1:35900 " + "ENDPOINTREMOTE=37.218.245.95:37.218.245.95:443 " - + "ERRORCODE=PROXY_END_MISC FILESIZE=51200 HOSTNAMELOCAL=op-nl2 " + + "ERRORCODE=TOR/END/MISC FILESIZE=51200 HOSTNAMELOCAL=op-nl2 " + "HOSTNAMEREMOTE=(null) LAUNCH=1587991454.80 NEGOTIATE=1587991580.81 " + "PATH=$12CF6DB4DAE106206D6C6B09988E865C0509843B," + "$1DC17C4A52A458B5C8B1E79157F8665696210E10,"

1 0

[metrics-lib/release] Bump version to 2.12.2-dev.
by karsten＠torproject.org 16 May '20

16 May '20

commit 95771bfb9fa745849673ae11bfe4d5d422111a26 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Thu Apr 30 22:15:10 2020 +0200 Bump version to 2.12.2-dev. --- CHANGELOG.md | 3 +++ build.xml | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b2722c..af5a7f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +# Changes in version 2.??.? - 2020-??-?? + + # Changes in version 2.12.2 - 2020-04-30 * Minor changes diff --git a/build.xml b/build.xml index d3d78ea..978ed37 100644 --- a/build.xml +++ b/build.xml @@ -7,7 +7,7 @@ <project default="usage" name="metrics-lib" basedir="." xmlns:ivy="antlib:org.apache.ivy.ant"> - <property name="release.version" value="2.12.2" /> + <property name="release.version" value="2.12.2-dev" /> <property name="javadoc-title" value="Tor Metrics Library API Documentation"/> <property name="javadoc-excludes" value="**/impl/** **/index/** **/internal/** **/log/**" /> <property name="implementation-title" value="Tor Metrics Library" />

1 0

[metrics-lib/release] Parse partial download times from Onionperf files.
by karsten＠torproject.org 16 May '20

16 May '20

commit ba6c63a707ceb7acc6354f541a8efd9366842c53 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Thu May 14 09:23:12 2020 +0200 Parse partial download times from Onionperf files. Implements #26673. --- CHANGELOG.md | 6 +++- .../org/torproject/descriptor/TorperfResult.java | 9 ++++++ .../descriptor/impl/TorperfResultImpl.java | 34 +++++++++++++++++++++ .../onionperf/OnionPerfAnalysisConverter.java | 9 ++++++ .../onionperf/ParsedOnionPerfAnalysis.java | 5 +++ .../onionperf/OnionPerfAnalysisConverterTest.java | 13 ++++++-- .../resources/onionperf/onionperf.analysis.json.xz | Bin 17376 -> 17420 bytes 7 files changed, 73 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ed2425..ac7ef89 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,8 @@ -# Changes in version 2.??.? - 2020-??-?? +# Changes in version 2.13.0 - 2020-??-?? + + * Medium changes + - Extend Torperf results to provide partial download times for 10, + 20, 50, 100, 200, and 500 KiB as well as 1, 2, and 5 MiB. * Minor changes - Include previously unknown error codes in Torperf results diff --git a/src/main/java/org/torproject/descriptor/TorperfResult.java b/src/main/java/org/torproject/descriptor/TorperfResult.java index 961a206..695be01 100644 --- a/src/main/java/org/torproject/descriptor/TorperfResult.java +++ b/src/main/java/org/torproject/descriptor/TorperfResult.java @@ -136,6 +136,15 @@ public interface TorperfResult extends Descriptor { Boolean didTimeout(); /** + * Return the times in milliseconds since the epoch when the given number of + * bytes were read, or null if the torperf line didn't contain that + * information. + * + * @since 2.13.0 + */ + SortedMap<Integer, Long> getPartials(); + + /** * Return the times in milliseconds since the epoch when {@code x%} of * expected bytes were read for {@code 0 <= x <= 100}, or null if the * torperf line didn't contain that information. diff --git a/src/main/java/org/torproject/descriptor/impl/TorperfResultImpl.java b/src/main/java/org/torproject/descriptor/impl/TorperfResultImpl.java index f8879d7..b2c58cc 100644 --- a/src/main/java/org/torproject/descriptor/impl/TorperfResultImpl.java +++ b/src/main/java/org/torproject/descriptor/impl/TorperfResultImpl.java @@ -185,6 +185,8 @@ public class TorperfResultImpl extends DescriptorImpl default: if (key.startsWith("DATAPERC")) { this.parseDataPercentile(value, keyValue, line); + } else if (key.startsWith("PARTIAL")) { + this.parsePartial(value, keyValue, line); } else { if (this.unrecognizedKeys == null) { this.unrecognizedKeys = new TreeMap<>(); @@ -313,6 +315,31 @@ public class TorperfResultImpl extends DescriptorImpl } } + private void parsePartial(String value, String keyValue, String line) + throws DescriptorParseException { + String key = keyValue.substring(0, keyValue.indexOf("=")); + String bytesString = key.substring("PARTIAL".length()); + int bytes; + try { + bytes = Integer.parseInt(bytesString); + } catch (NumberFormatException e) { + /* Treat key as unrecognized below. */ + bytes = -1; + } + if (bytes < 0) { + if (this.unrecognizedKeys == null) { + this.unrecognizedKeys = new TreeMap<>(); + } + this.unrecognizedKeys.put(key, value); + } else { + long timestamp = this.parseTimestamp(value, keyValue, line); + if (this.partials == null) { + this.partials = new TreeMap<>(); + } + this.partials.put(bytes, timestamp); + } + } + private void parseDataPercentile(String value, String keyValue, String line) throws DescriptorParseException { String key = keyValue.substring(0, keyValue.indexOf("=")); @@ -564,6 +591,13 @@ public class TorperfResultImpl extends DescriptorImpl return this.didTimeout; } + private SortedMap<Integer, Long> partials; + + @Override + public SortedMap<Integer, Long> getPartials() { + return this.partials == null ? null : new TreeMap<>(this.partials); + } + private SortedMap<Integer, Long> dataPercentiles; @Override diff --git a/src/main/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverter.java b/src/main/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverter.java index 8ca5efd..5e7e683 100644 --- a/src/main/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverter.java +++ b/src/main/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverter.java @@ -265,6 +265,15 @@ public class OnionPerfAnalysisConverter { transfer.elapsedSeconds.command); torperfResultsBuilder.addTimestamp("DATARESPONSE", transfer.unixTsStart, transfer.elapsedSeconds.response); + if (null != transfer.elapsedSeconds.payloadBytes) { + for (Map.Entry<String, Double> payloadBytesEntry + : transfer.elapsedSeconds.payloadBytes.entrySet()) { + String key = String.format("PARTIAL%s", payloadBytesEntry.getKey()); + Double elapsedSeconds = payloadBytesEntry.getValue(); + torperfResultsBuilder.addTimestamp(key, transfer.unixTsStart, + elapsedSeconds); + } + } if (null != transfer.elapsedSeconds.payloadProgress) { for (Map.Entry<String, Double> payloadProgressEntry : transfer.elapsedSeconds.payloadProgress.entrySet()) { diff --git a/src/main/java/org/torproject/descriptor/onionperf/ParsedOnionPerfAnalysis.java b/src/main/java/org/torproject/descriptor/onionperf/ParsedOnionPerfAnalysis.java index 679879e..4eca0ff 100644 --- a/src/main/java/org/torproject/descriptor/onionperf/ParsedOnionPerfAnalysis.java +++ b/src/main/java/org/torproject/descriptor/onionperf/ParsedOnionPerfAnalysis.java @@ -200,6 +200,11 @@ public class ParsedOnionPerfAnalysis { Double lastByte; /** + * Time until the given number of bytes were read. + */ + Map<String, Double> payloadBytes; + + /** * Time until the given fraction of expected bytes were read. */ Map<String, Double> payloadProgress; diff --git a/src/test/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverterTest.java b/src/test/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverterTest.java index 7a1a3a0..51e0896 100644 --- a/src/test/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverterTest.java +++ b/src/test/java/org/torproject/descriptor/onionperf/OnionPerfAnalysisConverterTest.java @@ -32,7 +32,10 @@ public class OnionPerfAnalysisConverterTest { + "ENDPOINTPROXY=localhost:127.0.0.1:35900 " + "ENDPOINTREMOTE=m3eahz7co6lzi6jn.onion:0.0.0.0:443 FILESIZE=1048576 " + "HOSTNAMELOCAL=op-nl2 HOSTNAMEREMOTE=op-nl2 LAUNCH=1587991281.38 " - + "NEGOTIATE=1587991280.37 " + + "NEGOTIATE=1587991280.37 PARTIAL10240=1587991283.81 " + + "PARTIAL102400=1587991284.15 PARTIAL1048576=1587991286.62 " + + "PARTIAL20480=1587991283.81 PARTIAL204800=1587991284.38 " + + "PARTIAL51200=1587991283.81 PARTIAL512000=1587991285.14 " + "PATH=$970F0966DAA7EBDEE44E3772045527A6854E997B," + "$8101421BEFCCF4C271D5483C5AABCAAD245BBB9D," + "$1A7A2516A961F2838F7F94786A8811BE82F9CFFE READBYTES=1048643 " @@ -54,6 +57,10 @@ public class OnionPerfAnalysisConverterTest { + "ENDPOINTREMOTE=3czoq6qyehjio6lcdo4tb4vk5uv2bm4gfk5iacnawza22do6klsj7wy" + "d.onion:0.0.0.0:443 FILESIZE=1048576 HOSTNAMELOCAL=op-nl2 " + "HOSTNAMEREMOTE=op-nl2 LAUNCH=1587991881.70 NEGOTIATE=1587991880.37 " + + "PARTIAL10240=1587991910.74 PARTIAL102400=1587991913.71 " + + "PARTIAL1048576=1587991927.74 PARTIAL20480=1587991910.74 " + + "PARTIAL204800=1587991916.00 PARTIAL51200=1587991910.74 " + + "PARTIAL512000=1587991921.80 " + "PATH=$D5C6F62A5D1B3C711CA5E6F9D3772A432E96F6C2," + "$94EC34B871936504BE70671B44760BC99242E1F3," + "$E0F638ECCE918B5455CE29D2CD9ECC9DBD8F8B21 READBYTES=1048643 " @@ -96,7 +103,9 @@ public class OnionPerfAnalysisConverterTest { String formattedTorperfResult = new String(descriptor.getRawDescriptorBytes()).trim(); assertNotNull(formattedTorperfResult); - assertTrue(formattedTorperfResult.equals(torperfResultTransfer1m1) + assertTrue(String.format("Unrecognized formatted Torperf result: %s", + formattedTorperfResult), + formattedTorperfResult.equals(torperfResultTransfer1m1) || formattedTorperfResult.equals(torperfResultTransfer1m3) || formattedTorperfResult.equals(torperfResultTransfer50k2)); } diff --git a/src/test/resources/onionperf/onionperf.analysis.json.xz b/src/test/resources/onionperf/onionperf.analysis.json.xz index 41a4fa1..08162a1 100644 Binary files a/src/test/resources/onionperf/onionperf.analysis.json.xz and b/src/test/resources/onionperf/onionperf.analysis.json.xz differ

1 0

Jump to page:

2025

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

tor-commits May 2020