Coverage for /pythoncovmergedfiles/medio/medio/src/paramiko/paramiko/sftp_handle.py: 24%

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# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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: the `bytes` read, or an error code `int`. 

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 bytes 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