-from zope.interface import Interface
+from zope.interface import Interface, Attribute
from foolscap.api import StringConstraint, ListOf, TupleOf, SetOf, DictOf, \
ChoiceOf, IntegerConstraint, Any, RemoteInterface, Referenceable
"""Cannot add an unknown child cap specified in a rw_uri field."""
+class IProgress(Interface):
+ """
+ Remembers progress measured in arbitrary units. Users of these
+ instances must call ``set_progress_total`` at least once before
+ progress can be valid, and must use the same units for both
+ ``set_progress_total`` and ``set_progress calls``.
+
+ See also:
+ :class:`allmydata.util.progress.PercentProgress`
+ """
+
+ progress = Attribute(
+ "Current amount of progress (in percentage)"
+ )
+
+ def set_progress(self, value):
+ """
+ Sets the current amount of progress.
+
+ Arbitrary units, but must match units used for
+ set_progress_total.
+ """
+
+ def set_progress_total(self, value):
+ """
+ Sets the total amount of expected progress
+
+ Arbitrary units, but must be same units as used when calling
+ set_progress() on this instance)..
+ """
+
+
class IReadable(Interface):
"""I represent a readable object -- either an immutable file, or a
specific version of a mutable file.
def get_size():
"""Return the length (in bytes) of this readable object."""
- def download_to_data():
+ def download_to_data(progress=None):
"""Download all of the file contents. I return a Deferred that fires
- with the contents as a byte string."""
+ with the contents as a byte string.
+
+ :param progress: None or IProgress implementer
+ """
def read(consumer, offset=0, size=None):
"""Download a portion (possibly all) of the file's contents, making
the Deferred will errback with an UnrecoverableFileError.
"""
- def download_best_version():
+ def download_best_version(progress=None):
"""Download the contents of the version that would be returned
by get_best_readable_version(). This is equivalent to calling
download_to_data() on the IReadable given by that method.
+ progress is anything that implements IProgress
+
I return a Deferred that fires with a byte string when the file
has been fully downloaded. To support streaming download, use
the 'read' method of IReadable. If no version is recoverable,
everything) to get increased visibility.
"""
- def upload(new_contents, servermap):
+ def upload(new_contents, servermap, progress=None):
"""Replace the contents of the file with new ones. This requires a
servermap that was previously updated with MODE_WRITE.
operation. If I do not signal UncoordinatedWriteError, then I was
able to write the new version without incident.
+ ``progress`` is either None or an IProgress provider
+
I return a Deferred that fires (with a PublishStatus object) when the
publish has completed. I will update the servermap in-place with the
location of all new shares.
equivalent to calling set_node() multiple times, but is much more
efficient."""
- def add_file(name, uploadable, metadata=None, overwrite=True):
+ def add_file(name, uploadable, metadata=None, overwrite=True, progress=None):
"""I upload a file (using the given IUploadable), then attach the
resulting ImmutableFileNode to the directory at the given name. I set
metadata the same way as set_uri and set_node. The child name must be
a unicode string.
+ ``progress`` either provides IProgress or is None
+
I return a Deferred that fires (with the IFileNode of the uploaded
file) when the operation completes."""