codekingpro/portable-devtools

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 the6# terms of the GNU Lesser General Public License as published by the Free7# 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 ANY11# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR12# A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more13# details.14#15# You should have received a copy of the GNU Lesser General Public License16# 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"""20An interface to override for SFTP server support.21"""22 23import os24import sys25from paramiko.sftp import SFTP_OP_UNSUPPORTED26 27 28class SFTPServerInterface:29    """30    This class defines an interface for controlling the behavior of paramiko31    when using the `.SFTPServer` subsystem to provide an SFTP server.32 33    Methods on this class are called from the SFTP session's thread, so you can34    block as long as necessary without affecting other sessions (even other35    SFTP sessions).  However, raising an exception will usually cause the SFTP36    session to abruptly end, so you will usually want to catch exceptions and37    return an appropriate error code.38 39    All paths are in string form instead of unicode because not all SFTP40    clients & servers obey the requirement that paths be encoded in UTF-8.41    """42 43    def __init__(self, server, *args, **kwargs):44        """45        Create a new SFTPServerInterface object.  This method does nothing by46        default and is meant to be overridden by subclasses.47 48        :param .ServerInterface server:49            the server object associated with this channel and SFTP subsystem50        """51        super().__init__(*args, **kwargs)52 53    def session_started(self):54        """55        The SFTP server session has just started.  This method is meant to be56        overridden to perform any necessary setup before handling callbacks57        from SFTP operations.58        """59        pass60 61    def session_ended(self):62        """63        The SFTP server session has just ended, either cleanly or via an64        exception.  This method is meant to be overridden to perform any65        necessary cleanup before this `.SFTPServerInterface` object is66        destroyed.67        """68        pass69 70    def open(self, path, flags, attr):71        """72        Open a file on the server and create a handle for future operations73        on that file.  On success, a new object subclassed from `.SFTPHandle`74        should be returned.  This handle will be used for future operations75        on the file (read, write, etc).  On failure, an error code such as76        ``SFTP_PERMISSION_DENIED`` should be returned.77 78        ``flags`` contains the requested mode for opening (read-only,79        write-append, etc) as a bitset of flags from the ``os`` module:80 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``88 89        (One of ``os.O_RDONLY``, ``os.O_WRONLY``, or ``os.O_RDWR`` will always90        be set.)91 92        The ``attr`` object contains requested attributes of the file if it93        has to be created.  Some or all attribute fields may be missing if94        the client didn't specify them.95 96        .. note:: The SFTP protocol defines all files to be in "binary" mode.97            There is no equivalent to Python's "text" mode.98 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 requested103            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_UNSUPPORTED109 110    def list_folder(self, path):111        """112        Return a list of files within a given folder.  The ``path`` will use113        posix notation (``"/"`` separates folder names) and may be an absolute114        or relative path.115 116        The list of files is expected to be a list of `.SFTPAttributes`117        objects, which are similar in structure to the objects returned by118        ``os.stat``.  In addition, each object should have its ``filename``119        field filled in, since this is important to a directory listing and120        not normally present in ``os.stat`` results.  The method121        `.SFTPAttributes.from_stat` will usually do what you want.122 123        In case of an error, you should return one of the ``SFTP_*`` error124        codes, such as ``SFTP_PERMISSION_DENIED``.125 126        :param str path: the requested path (relative or absolute) to be127            listed.128        :return:129            a list of the files in the given folder, using `.SFTPAttributes`130            objects.131 132        .. note::133            You should normalize the given ``path`` first (see the `os.path`134            module) and check appropriate permissions before returning the list135            of files.  Be careful of malicious clients attempting to use136            relative paths to escape restricted folders, if you're doing a137            direct translation from the SFTP server path to your local138            filesystem.139        """140        return SFTP_OP_UNSUPPORTED141 142    def stat(self, path):143        """144        Return an `.SFTPAttributes` object for a path on the server, or an145        error code.  If your server supports symbolic links (also known as146        "aliases"), you should follow them.  (`lstat` is the corresponding147        call that doesn't follow symlinks/aliases.)148 149        :param str path:150            the requested path (relative or absolute) to fetch file statistics151            for.152        :return:153            an `.SFTPAttributes` object for the given file, or an SFTP error154            code (like ``SFTP_PERMISSION_DENIED``).155        """156        return SFTP_OP_UNSUPPORTED157 158    def lstat(self, path):159        """160        Return an `.SFTPAttributes` object for a path on the server, or an161        error code.  If your server supports symbolic links (also known as162        "aliases"), you should not follow them -- instead, you should163        return data on the symlink or alias itself.  (`stat` is the164        corresponding call that follows symlinks/aliases.)165 166        :param str path:167            the requested path (relative or absolute) to fetch file statistics168            for.169        :type path: str170        :return:171            an `.SFTPAttributes` object for the given file, or an SFTP error172            code (like ``SFTP_PERMISSION_DENIED``).173        """174        return SFTP_OP_UNSUPPORTED175 176    def remove(self, path):177        """178        Delete a file, if possible.179 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_UNSUPPORTED185 186    def rename(self, oldpath, newpath):187        """188        Rename (or move) a file.  The SFTP specification implies that this189        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's191        probably a good idea to implement "move" in this method too, even for192        files that cross disk partition boundaries, if at all possible.193 194        .. note:: You should return an error if a file with the same name as195            ``newpath`` already exists.  (The rename operation should be196            non-desctructive.)197 198        .. note::199            This method implements 'standard' SFTP ``RENAME`` behavior; those200            seeking the OpenSSH "POSIX rename" extension behavior should use201            `posix_rename`.202 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_UNSUPPORTED209 210    def posix_rename(self, oldpath, newpath):211        """212        Rename (or move) a file, following posix conventions. If newpath213        already exists, it will be overwritten.214 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``.219 220        :versionadded: 2.2221        """222        return SFTP_OP_UNSUPPORTED223 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.228 229        The ``attr`` object will contain only those fields provided by the230        client in its request, so you should use ``hasattr`` to check for231        the presence of fields before using them.  In some cases, the ``attr``232        object may be completely empty.233 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_UNSUPPORTED240 241    def rmdir(self, path):242        """243        Remove a directory if it exists.  The ``path`` should refer to an244        existing, empty folder -- otherwise this method should return an245        error.246 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_UNSUPPORTED252 253    def chattr(self, path, attr):254        """255        Change the attributes of a file.  The ``attr`` object will contain256        only those fields provided by the client in its request, so you257        should check for the presence of fields before using them.258 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_UNSUPPORTED267 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 path272        ``"../betty"`` would be canonicalized to ``"/home/betty"``.  Note273        the obvious security issues: if you're serving files only from a274        specific folder, you probably don't want this method to reveal path275        names outside that folder.276 277        You may find the Python methods in ``os.path`` useful, especially278        ``os.path.normpath`` and ``os.path.realpath``.279 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 format288            out = out.replace("\\", "/")289        return out290 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 error295        should be returned.296 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 like300            ``SFTP_NO_SUCH_FILE``.301        """302        return SFTP_OP_UNSUPPORTED303 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.308 309        :param str target_path:310            path (relative or absolute) of the target for this new symbolic311            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_UNSUPPORTED317