commit 8634aa04114e74dc5f94875113f9b44549305368 Author: Damian Johnson atagar@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 """