Raw export of async FS API

aysnc_fs.py

class IResourceRunnable(IRunnable):
    """
    A resource which acts as a client to provide the end-user functionality.
    """

    avatar = Attribute('The client/credentials for this resource.')

    def heartbeat():
        """
        Called to signal that a command was requested for the location.

        Return a deferred which is fired when locations is connected.
        """

    def callWhenConnected(call, *args, **kwargs):
        """
        Call when runnable is connected and ready to accept commands.

        If it is not connected, it will try to connect.

        Return a deferred which is fired with the result of the call.
        """


class ILocation(IResourceRunnable):
    """
    Local or remote location used by an ITransfer.

    All method support only absolute paths.
    """

    def watch(configuration, handler, on_error, on_snapshot):
        """
        Watch path defined by `configuration` and use `handler` to
        handle changes.

        When watch fails, it will call `on_error` with the exception as
        argument.

        Return a `watched_handler` object representing the watched path and
        which can be used to unwatch the path.

        `on_snapshot` is called for each time a new snapshot is made by the
        watch.
        """

    def unwatch(watched_handler):
        """
        Stop watching `path` for changes.
        """

    def joinPath(*parts):
        """
        Join one or more path components, resolving any relative parts and
        converting separators.
        """

    def splitPath(path):
        """
        Split the path into a (dirname, basename).
        The basename part will never contain a slash; if path ends in a slash,
        basename will be empty.
        """

    def relativePath(base, path):
        """
        Return a relative file path to `path` from the `base` directory.
        """

    def exists(path):
        """
        `True` when path exists, `False` otherwise.

        Return a deferred that fires with the result.
        """

    def rename(source_path, destination_path):
        """
        Rename file or folder inside the location.

        Return a deferred that fires when operation is done.
        """

    def deleteFile(path):
        """
        Delete file at path.

        Return a deferred that fires when operation is done.
        """

    def deleteFolder(path, recursive=False):
        """
        Delete folder at path.

        Return a deferred that fires when operation is done.
        """

    def createFolder(path):
        """
        Create a folder at path, without creating parents.

        Return a deferred that fires when operation is done.
        """

    def getFolderMemberAttributes(path):
        """
        Return a deferred that fires with a list `IFileAttributes`.
        """

    def getAttributes(path):
        """
        Return a deferred that fires with the `IFileAttributes` for `path`.
        """

    def getStreamForReading(path):
        """
        Return an deferred with an `ITransferStream` opened for
        reading at the start of the stream.
        """

    def getStreamForWriting(path, length=None):
        """
        Return a deferred with an `ITransferStream` opened for writing,

        `length` is the expected data to be written and some location
        implementation might ignore it.

        Creates the file if it does not exist, otherwise removes existing
        content.
        """

    def getStreamForAppending(path):
        """
        Return a deferred with an `ITransferStream` opened for appending.

        Creates the file if it does not exist.
        """


class ILocalLocation(ILocation):
    """
    A location on local filesystem.
    """

    def touch(path):
        """
        Create a new file at path or update its modified date.

        Return a deferred that fires when operation is done.
        """

    def copyFile(source_path, destination_path, overwrite=False):
        """
        Return a deferred which fires when file was copied from `source_path`
        to destination path.

        If `destination_path` is a folder, the file will be copied at
        `destination_path/SOURCE_FILENAME`.

        If `destination_path` already exists and `overwrite` is not `true`,
        copy will fail.
        """


class ILocationShell(Interface):
    """
    Low level client shell used by a location to perform file operations.

    The client is already connected.
    """

    avatar = Attribute('Client avatar for this location.')

    def authenticate():
        """
        Return a deferred which fires when the client is authenticated.
        """

    def callOnConnectionLost(callback):
        """
        Call `callback` when connection is lost.
        """


class ITransferStream(Interface):
    """
    A file/stream which is used to read/write data.
    """

    location = Attribute('ILocation associated with this stream.')
    path = Attribute('Path in the ILocation associated with this stream.')
    mode = Attribute('Description of the mode in which stream was opened.')

    def close():
        """"
        Close the stream.
        """

    def read(length):
        """
        Return data of maximum `length`.
        """

    def write(data):
        """
        Write data.
        """