Coverage for /pythoncovmergedfiles/medio/medio/src/paramiko/paramiko/sftp_si.py: 49%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
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.
19"""
20An interface to override for SFTP server support.
21"""
23import os
24import sys
25from paramiko.sftp import SFTP_OP_UNSUPPORTED
28class SFTPServerInterface:
29 """
30 This class defines an interface for controlling the behavior of paramiko
31 when using the `.SFTPServer` subsystem to provide an SFTP server.
33 Methods on this class are called from the SFTP session's thread, so you can
34 block as long as necessary without affecting other sessions (even other
35 SFTP sessions). However, raising an exception will usually cause the SFTP
36 session to abruptly end, so you will usually want to catch exceptions and
37 return an appropriate error code.
39 All paths are in string form instead of unicode because not all SFTP
40 clients & servers obey the requirement that paths be encoded in UTF-8.
41 """
43 def __init__(self, server, *args, **kwargs):
44 """
45 Create a new SFTPServerInterface object. This method does nothing by
46 default and is meant to be overridden by subclasses.
48 :param .ServerInterface server:
49 the server object associated with this channel and SFTP subsystem
50 """
51 super().__init__(*args, **kwargs)
53 def session_started(self):
54 """
55 The SFTP server session has just started. This method is meant to be
56 overridden to perform any necessary setup before handling callbacks
57 from SFTP operations.
58 """
59 pass
61 def session_ended(self):
62 """
63 The SFTP server session has just ended, either cleanly or via an
64 exception. This method is meant to be overridden to perform any
65 necessary cleanup before this `.SFTPServerInterface` object is
66 destroyed.
67 """
68 pass
70 def open(self, path, flags, attr):
71 """
72 Open a file on the server and create a handle for future operations
73 on that file. On success, a new object subclassed from `.SFTPHandle`
74 should be returned. This handle will be used for future operations
75 on the file (read, write, etc). On failure, an error code such as
76 ``SFTP_PERMISSION_DENIED`` should be returned.
78 ``flags`` contains the requested mode for opening (read-only,
79 write-append, etc) as a bitset of flags from the ``os`` module:
81 - ``os.O_RDONLY``
82 - ``os.O_WRONLY``
83 - ``os.O_RDWR``
84 - ``os.O_APPEND``
85 - ``os.O_CREAT``
86 - ``os.O_TRUNC``
87 - ``os.O_EXCL``
89 (One of ``os.O_RDONLY``, ``os.O_WRONLY``, or ``os.O_RDWR`` will always
90 be set.)
92 The ``attr`` object contains requested attributes of the file if it
93 has to be created. Some or all attribute fields may be missing if
94 the client didn't specify them.
96 .. note:: The SFTP protocol defines all files to be in "binary" mode.
97 There is no equivalent to Python's "text" mode.
99 :param str path:
100 the requested path (relative or absolute) of the file to be opened.
101 :param int flags:
102 flags or'd together from the ``os`` module indicating the requested
103 mode for opening the file.
104 :param .SFTPAttributes attr:
105 requested attributes of the file if it is newly created.
106 :return: a new `.SFTPHandle` or error code.
107 """
108 return SFTP_OP_UNSUPPORTED
110 def list_folder(self, path):
111 """
112 Return a list of files within a given folder. The ``path`` will use
113 posix notation (``"/"`` separates folder names) and may be an absolute
114 or relative path.
116 The list of files is expected to be a list of `.SFTPAttributes`
117 objects, which are similar in structure to the objects returned by
118 ``os.stat``. In addition, each object should have its ``filename``
119 field filled in, since this is important to a directory listing and
120 not normally present in ``os.stat`` results. The method
121 `.SFTPAttributes.from_stat` will usually do what you want.
123 In case of an error, you should return one of the ``SFTP_*`` error
124 codes, such as ``SFTP_PERMISSION_DENIED``.
126 :param str path: the requested path (relative or absolute) to be
127 listed.
128 :return:
129 a list of the files in the given folder, using `.SFTPAttributes`
130 objects.
132 .. note::
133 You should normalize the given ``path`` first (see the `os.path`
134 module) and check appropriate permissions before returning the list
135 of files. Be careful of malicious clients attempting to use
136 relative paths to escape restricted folders, if you're doing a
137 direct translation from the SFTP server path to your local
138 filesystem.
139 """
140 return SFTP_OP_UNSUPPORTED
142 def stat(self, path):
143 """
144 Return an `.SFTPAttributes` object for a path on the server, or an
145 error code. If your server supports symbolic links (also known as
146 "aliases"), you should follow them. (`lstat` is the corresponding
147 call that doesn't follow symlinks/aliases.)
149 :param str path:
150 the requested path (relative or absolute) to fetch file statistics
151 for.
152 :return:
153 an `.SFTPAttributes` object for the given file, or an SFTP error
154 code (like ``SFTP_PERMISSION_DENIED``).
155 """
156 return SFTP_OP_UNSUPPORTED
158 def lstat(self, path):
159 """
160 Return an `.SFTPAttributes` object for a path on the server, or an
161 error code. If your server supports symbolic links (also known as
162 "aliases"), you should not follow them -- instead, you should
163 return data on the symlink or alias itself. (`stat` is the
164 corresponding call that follows symlinks/aliases.)
166 :param str path:
167 the requested path (relative or absolute) to fetch file statistics
168 for.
169 :type path: str
170 :return:
171 an `.SFTPAttributes` object for the given file, or an SFTP error
172 code (like ``SFTP_PERMISSION_DENIED``).
173 """
174 return SFTP_OP_UNSUPPORTED
176 def remove(self, path):
177 """
178 Delete a file, if possible.
180 :param str path:
181 the requested path (relative or absolute) of the file to delete.
182 :return: an SFTP error code `int` like ``SFTP_OK``.
183 """
184 return SFTP_OP_UNSUPPORTED
186 def rename(self, oldpath, newpath):
187 """
188 Rename (or move) a file. The SFTP specification implies that this
189 method can be used to move an existing file into a different folder,
190 and since there's no other (easy) way to move files via SFTP, it's
191 probably a good idea to implement "move" in this method too, even for
192 files that cross disk partition boundaries, if at all possible.
194 .. note:: You should return an error if a file with the same name as
195 ``newpath`` already exists. (The rename operation should be
196 non-desctructive.)
198 .. note::
199 This method implements 'standard' SFTP ``RENAME`` behavior; those
200 seeking the OpenSSH "POSIX rename" extension behavior should use
201 `posix_rename`.
203 :param str oldpath:
204 the requested path (relative or absolute) of the existing file.
205 :param str newpath: the requested new path of the file.
206 :return: an SFTP error code `int` like ``SFTP_OK``.
207 """
208 return SFTP_OP_UNSUPPORTED
210 def posix_rename(self, oldpath, newpath):
211 """
212 Rename (or move) a file, following posix conventions. If newpath
213 already exists, it will be overwritten.
215 :param str oldpath:
216 the requested path (relative or absolute) of the existing file.
217 :param str newpath: the requested new path of the file.
218 :return: an SFTP error code `int` like ``SFTP_OK``.
220 :versionadded: 2.2
221 """
222 return SFTP_OP_UNSUPPORTED
224 def mkdir(self, path, attr):
225 """
226 Create a new directory with the given attributes. The ``attr``
227 object may be considered a "hint" and ignored.
229 The ``attr`` object will contain only those fields provided by the
230 client in its request, so you should use ``hasattr`` to check for
231 the presence of fields before using them. In some cases, the ``attr``
232 object may be completely empty.
234 :param str path:
235 requested path (relative or absolute) of the new folder.
236 :param .SFTPAttributes attr: requested attributes of the new folder.
237 :return: an SFTP error code `int` like ``SFTP_OK``.
238 """
239 return SFTP_OP_UNSUPPORTED
241 def rmdir(self, path):
242 """
243 Remove a directory if it exists. The ``path`` should refer to an
244 existing, empty folder -- otherwise this method should return an
245 error.
247 :param str path:
248 requested path (relative or absolute) of the folder to remove.
249 :return: an SFTP error code `int` like ``SFTP_OK``.
250 """
251 return SFTP_OP_UNSUPPORTED
253 def chattr(self, path, attr):
254 """
255 Change the attributes of a file. The ``attr`` object will contain
256 only those fields provided by the client in its request, so you
257 should check for the presence of fields before using them.
259 :param str path:
260 requested path (relative or absolute) of the file to change.
261 :param attr:
262 requested attributes to change on the file (an `.SFTPAttributes`
263 object)
264 :return: an error code `int` like ``SFTP_OK``.
265 """
266 return SFTP_OP_UNSUPPORTED
268 def canonicalize(self, path):
269 """
270 Return the canonical form of a path on the server. For example,
271 if the server's home folder is ``/home/foo``, the path
272 ``"../betty"`` would be canonicalized to ``"/home/betty"``. Note
273 the obvious security issues: if you're serving files only from a
274 specific folder, you probably don't want this method to reveal path
275 names outside that folder.
277 You may find the Python methods in ``os.path`` useful, especially
278 ``os.path.normpath`` and ``os.path.realpath``.
280 The default implementation returns ``os.path.normpath('/' + path)``.
281 """
282 if os.path.isabs(path):
283 out = os.path.normpath(path)
284 else:
285 out = os.path.normpath("/" + path)
286 if sys.platform == "win32":
287 # on windows, normalize backslashes to sftp/posix format
288 out = out.replace("\\", "/")
289 return out
291 def readlink(self, path):
292 """
293 Return the target of a symbolic link (or shortcut) on the server.
294 If the specified path doesn't refer to a symbolic link, an error
295 should be returned.
297 :param str path: path (relative or absolute) of the symbolic link.
298 :return:
299 the target `str` path of the symbolic link, or an error code like
300 ``SFTP_NO_SUCH_FILE``.
301 """
302 return SFTP_OP_UNSUPPORTED
304 def symlink(self, target_path, path):
305 """
306 Create a symbolic link on the server, as new pathname ``path``,
307 with ``target_path`` as the target of the link.
309 :param str target_path:
310 path (relative or absolute) of the target for this new symbolic
311 link.
312 :param str path:
313 path (relative or absolute) of the symbolic link to create.
314 :return: an error code `int` like ``SFTP_OK``.
315 """
316 return SFTP_OP_UNSUPPORTED