Changeset 170

Timestamp:

2002-04-01 18:29:30 (7 years ago)

Author:

schwa

Message:

Documentation mostly complete.

Files:

• trunk/ftputil.txt (modified) (3 diffs)

trunk/ftputil.txt

@@ -71 +71 @@
-    def func(path, file):
-        ...
-
+
-which works on the local file system and catches OSErrors. If you
-change the parameter list to
@@ -129 +129 @@
-FTPHost OBJECTS
-
+Construction
+------------
+
+FTPHost instances may be generated with the following call:
+
+    host = ftputil.FTPHost(host, user, password, account,
+                           session_factory=ftplib.FTP)
+
+The first four parameters are strings with the same meaning as for the
+FTP class in the ftplib module. The keyword argument session_factory
+may be used to generate FTP connections with other factories than the
+default ftplib.FTP. For example, the M2Crypto distribution uses a
+secure FTP class which is derived from ftplib.FTP.
+
+In fact, all positional and keyword arguments other than
+session_factory are passed to the factory to generate a new background
+session (which happens for every remote file that is opened; see
+below).
+
+FTPHost attributes and methods
+------------------------------
+
+curdir, pardir, sep
+    are strings which denote the current and the parent directory on
+    the remote server. sep identifies the path separator. Though RFC
+    959 (File Transfer Protocol) notes that these values may be server
+    dependent, the Unix counterparts seem to work well in practice,
+    even for non-Unix servers.
+
+file(path, mode='r')
+    returns a file-like object that is connected to the path on the
+    remote host. This path may be absolute or relative to current
+    directory on the remote host (this directory can be determined
+    with the getcwd method). As with local file objects the default
+    mode is 'r', i. e. reading text files. Valid modes are 'r', 'rb',
+    'w', and 'wb'.
+
+open(path, mode='r')
+    is an alias for file (see above).
+
+copyfileobj(source, target, length=64*1024)
+    copies the contents from the file-like object source to the
+    file-like object target. The only difference to shutil.copyfileobj
+    is the default buffer size.
+
+upload(source, target, mode='')
+    copies a local source file (given by a filename, i. e. a string)
+    to the remote host under the name target. Both source and target
+    may be absolute paths or relative to their corresponding current
+    directory (on the local or the remote host, respectively). The
+    mode may be '' or 'a' for ASCII uploads or 'b' for binary uploads.
+    ASCII mode is the default (again, similar to regular local file
+    objects).
+
+download(source, target, mode='')
+    performs a download from the remote source to a target file. Both
+    source and target are strings. Additionally, the description of
+    the upload method applies here, too.
+
+upload_if_newer(source, target, mode='')
+    is similar to the upload method. The only difference is that the
+    upload is only invoked if the time of the last modification for
+    the source file is more recent than that of the target file, or
+    the target doesn't exist at all.
+
+download_if_newer(source, target, mode='')
+    corresponds to upload_if_newer but performs a download from the
+    server to the local host. Read the descriptions of download and
+    upload_if_newer for more.
+
+close()
+    closes the connection to the remote host. After this, no more
+    interaction with the FTP server is possible without using a new
+    FTPHost object.
+
+getcwd()
+    returns the absolute current directory on the remote host. This
+    method acts similar to os.getcwd.
+
+chdir(directory)
+    sets the current directory on the FTP server. This resembles
+    os.chdir, as you may have expected. :-)
+
+mkdir(path, [mode])
+    makes the given directory on the remote host. In the current
+    implementation, this doesn't construct "intermediate" directories
+    which don't already exist. The mode parameter is ignored. This is
+    for compatibilty with os.mkdir if an FTPHost object is passed into
+    a function instead of the os module (see the subsection on Python
+    exceptions above for an explanation).
+
+rmdir(path)
+    removes the given remote directory. Currently, "intermediate"
+    directories can't be deleted (as with os.rmdir).
+
+remove(path)
+    removes a file on the remote host (similar to os.remove).
+
+unlink(path)
+    is an alias for remove.
+
+rename(source, target)
+    renames the source file (or directory) on the FTP server.
+
+listdir(path)
+    returns a list containing the names of the files and directories
+    in the given path; similar to os.listdir.
+
+lstat(path)
+    returns an object similar that from os.lstat (a "tuple" with
+    additional attributes; see the documentation of the os module for
+    details). However, due to the nature of the application, there are
+    some important aspects to keep in mind:
+
+    - The result is derived by parsing the output of a DIR command on
+      the server. Therefore, the result from FTPHost.lstat can not
+      contain nore information than the received text. In particular:
+
+    - User and group ids can only be determined as strings, not as
+      numbers, and that only, if the server supplies them. This is
+      usually the case with Unix servers but may not be for other FTP
+      server programs.
+
+    - Values for the time of the last modification may be rough,
+      depending on the information from the server. For timestamps
+      older than a year, this usually means that the precision of the
+      modification timestamp value is not better than days. For newer
+      files, the information may be accurate to a minute.
+
+    - Links can only be recognized on servers that provide this
+      information in the DIR output.
+      
+    - Items that can't be determined at all, are set to None.
+
+    Currently, ftputil recognizes the MS Robin FTP server. Otherwise,
+    a format commonly used by Unix servers is assumed. If you need to
+    parse output from another server type, please contact me under the
+    email address at the end of this text.
+
+stat(path)
+    return stat information also for files which are pointed to by a
+    link. This method follows multiple links until a regular file or
+    directory is found. If an infinite link chain is encountered, a
+    PermanentError is raised.
+
+FTPHost.path methods
+--------------------
+
+FTPHost objects contain an attribute named path, similar to os.path.
+(See there for documentation.) The following methods can be applied
+to the remote host with the same semantics as for os.path: abspath,
+basename, commonprefix, dirname, exists, getmtime, getsize, isabs,
+isdir, isfile, islink, join, normcase, normpath, split, splitdrive,
+splitext, and even walk. See the section on the os.path module in the
+Library Reference,
+http://www.python.org/doc/current/lib/module-os.path.html
-
-----------------------------------------------------------------------
-FTPFile OBJECTS
-
+FTPFile objects as returned by a call to FTPHost.file (or
+FTPHost.open) have, like "normal" file objects, the following methods.
+Note that ftputil supports both binary and text mode (with the
+appropriate line ending conversions). The following methods - with the
+same arguments and semantics as for local files - can be used: close,
+read, readline, readlines, write, writelines, and xreadlines. See
+the section "File objects" in the Library Reference,
+http://www.python.org/doc/current/lib/bltin-file-objects.html
-
-----------------------------------------------------------------------
-BUGS AND LIMITATIONS
-
+- ftputil needs at least Python 2.1 to run.
+
+- Depending on local time and/or daylight saving time settings
+  different local hosts may interpret the modification times in the
+  FTP server output differently.
+
+- Timeouts of individual child sessions currently are not handled.
+
+- Until now, I haven't paid attention to thread safety. In principle,
+  different FTPFile objects should be usable in different threads.
+
+- FTPFile objects in text mode _may not_ support charsets with more
+  than one byte per character. Please email me your experiences
+  (address below), if you deal with multibyte text streams.
+
+----------------------------------------------------------------------
+SEE ALSO
+
+Postel J, Reynolds J. 1985.
+    RFC 959 - File Transfer Protocol (FTP).
+    http://www.ietf.org/rfc/rfc959.txt
+
+Van Rossum G, Drake Jr FL. 2001.
+    Python Library Reference.
+    http://www.python.org/doc/current/lib/lib.html
+
-----------------------------------------------------------------------
-AUTHOR
@@ -142 +332 @@
-Stefan Schwarzer <s.schwarzer@ndh.net>
-
-----------------------------------------------------------------------
-