Package paramiko :: Module sftp_si |
[frames] | no frames]

# Source Code for Module paramiko.sftp_si

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