jacob.eva/Reticulum
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added docstrings to Resource

Browse Source
This commit is contained in:
Mark Qvist 2021-05-16 23:29:25 +02:00
parent dfb5af5dd1
commit 08dc980282
1 changed files with 39 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
RNS/Resource.py
View File

@ -8,6 +8,21 @@ from .vendor import umsgpack as umsgpack
from time import sleep from time import sleep
class Resource: class Resource:
"""
The Resource class allows transferring arbitrary amounts
of data over a link. It will automatically handle sequencing,
compression, coordination and checksumming.
:param data: The data to be transferred. Can be *bytes* or an open *file handle*. See the :ref:`Filetransfer Example<example-filetransfer>` for details.
:param link: The :ref:`RNS.Link<api-link>` instance on which to transfer the data.
:param advertise: Whether to automatically advertise the resource. Can be *True* or *False*.
:param auto_compress: Whether to auto-compress the resource. Can be *True* or *False*.
:param auto_compress: Whether the resource must be compressed. Can be *True* or *False*. Used for debugging, will disappear in the future.
:param callback: A *callable* with the signature *callback(resource)*. Will be called when the resource transfer concludes.
:param progress_callback: A *callable* with the signature *callback(resource)*. Will be called whenever the resource transfer progress is updated.
:param segment_index: Internal use, ignore.
:param original_hash: Internal use, ignore.
"""
WINDOW_FLEXIBILITY = 4 WINDOW_FLEXIBILITY = 4
WINDOW_MIN = 1 WINDOW_MIN = 1
WINDOW_MAX = 10 WINDOW_MAX = 10
@ -16,16 +31,21 @@ class Resource:
SDU = RNS.Packet.MDU SDU = RNS.Packet.MDU
RANDOM_HASH_SIZE = 4 RANDOM_HASH_SIZE = 4
# This is an indication of what the
# maximum size a resource should be, if
# it is to be handled within reasonable
# time constraint, even on small systems.
#
# A small system in this regard is
# defined as a Raspberry Pi, which should
# be able to compress, encrypt and hash-map
# the resource in about 10 seconds.
MAX_EFFICIENT_SIZE = 16 * 1024 * 1024 MAX_EFFICIENT_SIZE = 16 * 1024 * 1024
"""
This is an indication of what the
maximum size a resource should be, if
it is to be handled within reasonable
time constraint, even on small systems.
A small system in this regard is
defined as a Raspberry Pi, which should
be able to compress, encrypt and hash-map
the resource in about 10 seconds.
This constant will be used when determining
how to sequence the sending of large resources.
"""
# The maximum size to auto-compress with # The maximum size to auto-compress with
# bz2 before sending. # bz2 before sending.
@ -301,6 +321,10 @@ class Resource:
return RNS.Identity.full_hash(data+self.random_hash)[:Resource.MAPHASH_LEN] return RNS.Identity.full_hash(data+self.random_hash)[:Resource.MAPHASH_LEN]
def advertise(self): def advertise(self):
"""
Advertise the resource. If the other end of the link accepts
the resource advertisement it will begin transferring.
"""
thread = threading.Thread(target=self.__advertise_job) thread = threading.Thread(target=self.__advertise_job)
thread.setDaemon(True) thread.setDaemon(True)
thread.start() thread.start()
@ -698,6 +722,9 @@ class Resource:
self.__progress_callback(self) self.__progress_callback(self)
def cancel(self): def cancel(self):
"""
Cancels transferring the resource.
"""
if self.status < Resource.COMPLETE: if self.status < Resource.COMPLETE:
self.status = Resource.FAILED self.status = Resource.FAILED
if self.initiator: if self.initiator:
@ -719,6 +746,9 @@ class Resource:
self.__progress_callback = callback self.__progress_callback = callback
def progress(self): def progress(self):
"""
:returns: The current progress of the resource transfer as a *float* between 0.0 and 1.0.
"""
if self.initiator: if self.initiator:
# TODO: Remove # TODO: Remove
# progress = self.sent_parts / len(self.parts) # progress = self.sent_parts / len(self.parts)