diff options
Diffstat (limited to 'paramiko/sftp_handle.py')
| -rw-r--r-- | paramiko/sftp_handle.py | 93 |
1 files changed, 42 insertions, 51 deletions
diff --git a/paramiko/sftp_handle.py b/paramiko/sftp_handle.py index 29d3d0d..92dd9cf 100644 --- a/paramiko/sftp_handle.py +++ b/paramiko/sftp_handle.py @@ -21,9 +21,7 @@ Abstraction of an SFTP file handle (for server mode). """ import os - -from paramiko.common import * -from paramiko.sftp import * +from paramiko.sftp import SFTP_OP_UNSUPPORTED, SFTP_OK class SFTPHandle (object): @@ -33,21 +31,20 @@ class SFTPHandle (object): by the client to refer to the underlying file. Server implementations can (and should) subclass SFTPHandle to implement - features of a file handle, like L{stat} or L{chattr}. + features of a file handle, like `stat` or `chattr`. """ def __init__(self, flags=0): """ Create a new file handle representing a local file being served over - SFTP. If C{flags} is passed in, it's used to determine if the file + SFTP. If ``flags`` is passed in, it's used to determine if the file is open in append mode. - @param flags: optional flags as passed to L{SFTPServerInterface.open} - @type flags: int + :param int flags: optional flags as passed to `.SFTPServerInterface.open` """ self.__flags = flags self.__name = None # only for handles to folders: - self.__files = { } + self.__files = {} self.__tell = None def close(self): @@ -56,10 +53,10 @@ class SFTPHandle (object): Normally you would use this method to close the underlying OS level file object(s). - The default implementation checks for attributes on C{self} named - C{readfile} and/or C{writefile}, and if either or both are present, - their C{close()} methods are called. This means that if you are - using the default implementations of L{read} and L{write}, this + The default implementation checks for attributes on ``self`` named + ``readfile`` and/or ``writefile``, and if either or both are present, + their ``close()`` methods are called. This means that if you are + using the default implementations of `read` and `write`, this method's default implementation should be fine also. """ readfile = getattr(self, 'readfile', None) @@ -71,24 +68,22 @@ class SFTPHandle (object): def read(self, offset, length): """ - Read up to C{length} bytes from this file, starting at position - C{offset}. The offset may be a python long, since SFTP allows it + Read up to ``length`` bytes from this file, starting at position + ``offset``. The offset may be a Python long, since SFTP allows it to be 64 bits. If the end of the file has been reached, this method may return an - empty string to signify EOF, or it may also return L{SFTP_EOF}. + empty string to signify EOF, or it may also return `.SFTP_EOF`. - The default implementation checks for an attribute on C{self} named - C{readfile}, and if present, performs the read operation on the python + The default implementation checks for an attribute on ``self`` named + ``readfile``, and if present, performs the read operation on the Python file-like object found there. (This is meant as a time saver for the - common case where you are wrapping a python file object.) + common case where you are wrapping a Python file object.) - @param offset: position in the file to start reading from. - @type offset: int or long - @param length: number of bytes to attempt to read. - @type length: int - @return: data read from the file, or an SFTP error code. - @rtype: str + :param offset: position in the file to start reading from. + :type offset: int or long + :param int length: number of bytes to attempt to read. + :return: data read from the file, or an SFTP error code, as a `str`. """ readfile = getattr(self, 'readfile', None) if readfile is None: @@ -100,7 +95,7 @@ class SFTPHandle (object): readfile.seek(offset) self.__tell = offset data = readfile.read(length) - except IOError, e: + except IOError as e: self.__tell = None return SFTPServer.convert_errno(e.errno) self.__tell += len(data) @@ -108,23 +103,22 @@ class SFTPHandle (object): def write(self, offset, data): """ - Write C{data} into this file at position C{offset}. Extending the - file past its original end is expected. Unlike python's normal - C{write()} methods, this method cannot do a partial write: it must - write all of C{data} or else return an error. + Write ``data`` into this file at position ``offset``. Extending the + file past its original end is expected. Unlike Python's normal + ``write()`` methods, this method cannot do a partial write: it must + write all of ``data`` or else return an error. - The default implementation checks for an attribute on C{self} named - C{writefile}, and if present, performs the write operation on the - python file-like object found there. The attribute is named - differently from C{readfile} to make it easy to implement read-only + The default implementation checks for an attribute on ``self`` named + ``writefile``, and if present, performs the write operation on the + Python file-like object found there. The attribute is named + differently from ``readfile`` to make it easy to implement read-only (or write-only) files, but if both attributes are present, they should refer to the same file. - @param offset: position in the file to start reading from. - @type offset: int or long - @param data: data to write into the file. - @type data: str - @return: an SFTP error code like L{SFTP_OK}. + :param offset: position in the file to start reading from. + :type offset: int or long + :param str data: data to write into the file. + :return: an SFTP error code like `.SFTP_OK`. """ writefile = getattr(self, 'writefile', None) if writefile is None: @@ -139,7 +133,7 @@ class SFTPHandle (object): self.__tell = offset writefile.write(data) writefile.flush() - except IOError, e: + except IOError as e: self.__tell = None return SFTPServer.convert_errno(e.errno) if self.__tell is not None: @@ -148,33 +142,30 @@ class SFTPHandle (object): def stat(self): """ - Return an L{SFTPAttributes} object referring to this open file, or an - error code. This is equivalent to L{SFTPServerInterface.stat}, except + Return an `.SFTPAttributes` object referring to this open file, or an + error code. This is equivalent to `.SFTPServerInterface.stat`, except it's called on an open file instead of a path. - @return: an attributes object for the given file, or an SFTP error - code (like L{SFTP_PERMISSION_DENIED}). - @rtype: L{SFTPAttributes} I{or error code} + :return: + an attributes object for the given file, or an SFTP error code + (like `.SFTP_PERMISSION_DENIED`). + :rtype: `.SFTPAttributes` or error code """ return SFTP_OP_UNSUPPORTED def chattr(self, attr): """ - Change the attributes of this file. The C{attr} object will contain + Change the attributes of this file. The ``attr`` object will contain only those fields provided by the client in its request, so you should check for the presence of fields before using them. - @param attr: the attributes to change on this file. - @type attr: L{SFTPAttributes} - @return: an error code like L{SFTP_OK}. - @rtype: int + :param .SFTPAttributes attr: the attributes to change on this file. + :return: an `int` error code like `.SFTP_OK`. """ return SFTP_OP_UNSUPPORTED - ### internals... - def _set_files(self, files): """ Used by the SFTP server code to cache a directory listing. (In |