1# Copyright (C) 2003-2007 Robey Pointer <robeypointer@gmail.com> 2# 3# This file is part of paramiko. 4# 5# Paramiko is free software; you can redistribute it and/or modify it under the 6# terms of the GNU Lesser General Public License as published by the Free 7# Software Foundation; either version 2.1 of the License, or (at your option) 8# any later version. 9# 10# Paramiko is distributed in the hope that it will be useful, but WITHOUT ANY 11# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 12# A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 13# details. 14# 15# You should have received a copy of the GNU Lesser General Public License 16# along with Paramiko; if not, write to the Free Software Foundation, Inc., 17# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 18 19""" 20Abstraction of an SFTP file handle (for server mode). 21""" 22 23import os 24from paramiko.sftp import SFTP_OP_UNSUPPORTED, SFTP_OK 25from paramiko.util import ClosingContextManager 26 27 28class SFTPHandle(ClosingContextManager): 29 """ 30 Abstract object representing a handle to an open file (or folder) in an 31 SFTP server implementation. Each handle has a string representation used 32 by the client to refer to the underlying file. 33 34 Server implementations can (and should) subclass SFTPHandle to implement 35 features of a file handle, like `stat` or `chattr`. 36 37 Instances of this class may be used as context managers. 38 """ 39 40 def __init__(self, flags=0): 41 """ 42 Create a new file handle representing a local file being served over 43 SFTP. If ``flags`` is passed in, it's used to determine if the file 44 is open in append mode. 45 46 :param int flags: optional flags as passed to 47 `.SFTPServerInterface.open` 48 """ 49 self.__flags = flags 50 self.__name = None 51 # only for handles to folders: 52 self.__files = {} 53 self.__tell = None 54 55 def close(self): 56 """ 57 When a client closes a file, this method is called on the handle. 58 Normally you would use this method to close the underlying OS level 59 file object(s). 60 61 The default implementation checks for attributes on ``self`` named 62 ``readfile`` and/or ``writefile``, and if either or both are present, 63 their ``close()`` methods are called. This means that if you are 64 using the default implementations of `read` and `write`, this 65 method's default implementation should be fine also. 66 """ 67 readfile = getattr(self, "readfile", None) 68 if readfile is not None: 69 readfile.close() 70 writefile = getattr(self, "writefile", None) 71 if writefile is not None: 72 writefile.close() 73 74 def read(self, offset, length): 75 """ 76 Read up to ``length`` bytes from this file, starting at position 77 ``offset``. The offset may be a Python long, since SFTP allows it 78 to be 64 bits. 79 80 If the end of the file has been reached, this method may return an 81 empty string to signify EOF, or it may also return ``SFTP_EOF``. 82 83 The default implementation checks for an attribute on ``self`` named 84 ``readfile``, and if present, performs the read operation on the Python 85 file-like object found there. (This is meant as a time saver for the 86 common case where you are wrapping a Python file object.) 87 88 :param offset: position in the file to start reading from. 89 :param int length: number of bytes to attempt to read. 90 :return: data read from the file, or an SFTP error code, as a `str`. 91 """ 92 readfile = getattr(self, "readfile", None) 93 if readfile is None: 94 return SFTP_OP_UNSUPPORTED 95 try: 96 if self.__tell is None: 97 self.__tell = readfile.tell() 98 if offset != self.__tell: 99 readfile.seek(offset) 100 self.__tell = offset 101 data = readfile.read(length) 102 except IOError as e: 103 self.__tell = None 104 return SFTPServer.convert_errno(e.errno) 105 self.__tell += len(data) 106 return data 107 108 def write(self, offset, data): 109 """ 110 Write ``data`` into this file at position ``offset``. Extending the 111 file past its original end is expected. Unlike Python's normal 112 ``write()`` methods, this method cannot do a partial write: it must 113 write all of ``data`` or else return an error. 114 115 The default implementation checks for an attribute on ``self`` named 116 ``writefile``, and if present, performs the write operation on the 117 Python file-like object found there. The attribute is named 118 differently from ``readfile`` to make it easy to implement read-only 119 (or write-only) files, but if both attributes are present, they should 120 refer to the same file. 121 122 :param offset: position in the file to start reading from. 123 :param str data: data to write into the file. 124 :return: an SFTP error code like ``SFTP_OK``. 125 """ 126 writefile = getattr(self, "writefile", None) 127 if writefile is None: 128 return SFTP_OP_UNSUPPORTED 129 try: 130 # in append mode, don't care about seeking 131 if (self.__flags & os.O_APPEND) == 0: 132 if self.__tell is None: 133 self.__tell = writefile.tell() 134 if offset != self.__tell: 135 writefile.seek(offset) 136 self.__tell = offset 137 writefile.write(data) 138 writefile.flush() 139 except IOError as e: 140 self.__tell = None 141 return SFTPServer.convert_errno(e.errno) 142 if self.__tell is not None: 143 self.__tell += len(data) 144 return SFTP_OK 145 146 def stat(self): 147 """ 148 Return an `.SFTPAttributes` object referring to this open file, or an 149 error code. This is equivalent to `.SFTPServerInterface.stat`, except 150 it's called on an open file instead of a path. 151 152 :return: 153 an attributes object for the given file, or an SFTP error code 154 (like ``SFTP_PERMISSION_DENIED``). 155 :rtype: `.SFTPAttributes` or error code 156 """ 157 return SFTP_OP_UNSUPPORTED 158 159 def chattr(self, attr): 160 """ 161 Change the attributes of this file. The ``attr`` object will contain 162 only those fields provided by the client in its request, so you should 163 check for the presence of fields before using them. 164 165 :param .SFTPAttributes attr: the attributes to change on this file. 166 :return: an `int` error code like ``SFTP_OK``. 167 """ 168 return SFTP_OP_UNSUPPORTED 169 170 # ...internals... 171 172 def _set_files(self, files): 173 """ 174 Used by the SFTP server code to cache a directory listing. (In 175 the SFTP protocol, listing a directory is a multi-stage process 176 requiring a temporary handle.) 177 """ 178 self.__files = files 179 180 def _get_next_files(self): 181 """ 182 Used by the SFTP server code to retrieve a cached directory 183 listing. 184 """ 185 fnlist = self.__files[:16] 186 self.__files = self.__files[16:] 187 return fnlist 188 189 def _get_name(self): 190 return self.__name 191 192 def _set_name(self, name): 193 self.__name = name 194 195 196from paramiko.sftp_server import SFTPServer 197