commit 1163efbefe66b10315197d375e3bdf392e8b18fb Author: Dave Rolek dmr-x@riseup.net Date: Fri Aug 17 20:51:00 2018 +0000
Update stem.client.cell docstrings for style, consistency, and clarity
Much of the updates here is to reduce the line length. --- stem/client/cell.py | 42 +++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 17 deletions(-)
diff --git a/stem/client/cell.py b/stem/client/cell.py index fec8bb1b..d1265c10 100644 --- a/stem/client/cell.py +++ b/stem/client/cell.py @@ -369,7 +369,8 @@ class RelayCell(CircuitCell): :var stem.client.datatype.RelayCommand command: command to be issued :var int command_int: integer value of our command :var bytes data: payload of the cell - :var int recognized: zero if cell is decrypted, otherwise mostly non-zero (can rarely be zero) + :var int recognized: zero if cell is decrypted, otherwise mostly non-zero + (can rarely be zero) :var int digest: running digest held with the relay :var int stream_id: specific stream this concerns """ @@ -458,22 +459,26 @@ class RelayCell(CircuitCell):
def apply_digest(self, digest, prep_cell = True): """ - Calculates, updates, and applies the digest to the cell payload, returning a new (cell, digest) tuple. + Calculates, updates, and applies the digest to the cell payload, + returning a new (cell, digest) tuple.
:param HASH digest: running digest held with the relay - :param bool prep_cell: preps the cell payload according to the spec, if **True** (default) + :param bool prep_cell: preps the cell payload according to the spec, if + **True** (default) if **False**, the digest will be calculated as-is, namely: - the 'recognized' field will not be set to 0, - the digest field will not be set to 0, - and any 'unused' padding will be taken as-is. - Use with caution. - - :returns: (:class:`~stem.client.cell.RelayCell`, HASH) tuple updated as follows: - digest: updated via digest.update(payload) - RelayCell: a copy of self, with the following updates: - RelayCell.recognized: set to 0, if prep_cell is **True** - RelayCell.digest: updated with the calculated digest - RelayCell.unused: treated as padding and overwritten, if prep_cell is **True** + * the 'recognized' field will not be set to 0, + * the digest field will not be set to 0, + * and any 'unused' padding will be taken as-is. + Use **False** with caution. + + :returns: (:class:`~stem.client.cell.RelayCell`, HASH) tuple of object + copies updated as follows: + * digest: updated via digest.update(payload) + * RelayCell: a copy of self, with the following updates: + * RelayCell.recognized: set to 0, if prep_cell is **True** + * RelayCell.digest: updated with the calculated digest + * RelayCell.unused: treated as padding and overwritten, if prep_cell + is **True** """
if prep_cell: @@ -496,9 +501,11 @@ class RelayCell(CircuitCell):
def pack_payload(self, **kwargs): """ - Convenience method for running _pack_payload on self. + Convenience method for running + :func:`~stem.client.cell.RelayCell._pack_payload` on self.
- :param bool pad_remaining: (optional, defaults to **True**) pads up to payload size if **True** + :param bool pad_remaining: (optional, defaults to **True**) pads up to + payload size if **True**
:returns: **bytes** with the packed payload """ @@ -511,7 +518,8 @@ class RelayCell(CircuitCell): Directly pack the payload without any validation beyond Size constraints.
:param int command_int: integer value of our command - :param int recognized: zero if cell is decrypted, otherwise mostly non-zero (can rarely be zero) + :param int recognized: zero if cell is decrypted, otherwise mostly non-zero + (can rarely be zero) :param int stream_id: specific stream this concerns :param HASH,str,int digest: running digest held with the relay :param int data_len: length of body data