[Zope3-checkins] SVN: Zope3/trunk/src/zope/server/interfaces/ftp.py
Corrected typos.
Steve Alexander
steve at z3u.com
Thu Sep 30 12:44:33 EDT 2004
Log message for revision 27714:
Corrected typos.
Wrote some XXX comments about parts of the IFileSystem interface that are
not specified in enough detail.
Changed:
U Zope3/trunk/src/zope/server/interfaces/ftp.py
-=-
Modified: Zope3/trunk/src/zope/server/interfaces/ftp.py
===================================================================
--- Zope3/trunk/src/zope/server/interfaces/ftp.py 2004-09-30 16:22:13 UTC (rev 27713)
+++ Zope3/trunk/src/zope/server/interfaces/ftp.py 2004-09-30 16:44:33 UTC (rev 27714)
@@ -188,34 +188,34 @@
class IFileSystemAccess(Interface):
- """Provides authenticated access to a filesystem.
- """
+ """Provides authenticated access to a filesystem."""
def authenticate(credentials):
"""Verifies filesystem access based on the presented credentials.
- Should raise Unauthorized if the user can not be authenticated.
+ Should raise zope.security.interfaces.Unauthorized if the user can
+ not be authenticated.
- This method only checks general access and is not used for each
+ This method checks only general access and is not used for each
call to open(). Rather, open() should do its own verification.
- Credentials are passed as username/password tuples.
-
+ Credentials are passed as (username, password) tuples.
+
"""
def open(credentials):
"""Returns an IFileSystem.
- Should raise Unauthorized if the user can not be authenticated.
+ Should raise zope.security.interfaces.Unauthorized if the user
+ can not be authenticated.
- Credentials are passed as username/password tuples.
+ Credentials are passed as (username, password) tuples.
"""
class IFileSystem(Interface):
- """We want to provide a complete wrapper around any and all read
- filesystem operations.
+ """An abstract filesystem.
Opening files for reading, and listing directories, should
return a producer.
@@ -224,45 +224,46 @@
which mainly means that FS implementations always expect forward
slashes, and filenames are case-sensitive.
- Note: A file system should *not* store any state!
+ Note that a file system should not store any state.
+ (XXX: Please explain why not.)
"""
def type(path):
- """Return the file type at path
+ """Return the file type at `path`.
The return valie is 'd', for a directory, 'f', for a file, and
- None if there is no file at the path.
+ None if there is no file at `path`.
This method doesn't raise exceptions.
"""
def names(path, filter=None):
- """Return a sequence of the names in a directory
+ """Return a sequence of the names in a directory.
- If the filter is not None, include only those names for which
- the filter returns a true value.
+ If `filter` is not None, include only those names for which
+ `filter` returns a true value.
"""
def ls(path, filter=None):
- """Return a sequence of information objects
+ """Return a sequence of information objects.
- Returm item info objects (see ls_info) for the files in a directory.
+ Returm item info objects (see the ls_info operation) for the files
+ in a directory.
- If the filter is not None, include only those names for which
- the filter returns a true value.
+ If `filter` is not None, include only those names for which
+ `filter` returns a true value.
"""
- return list(tuple(str, str))
def readfile(path, outstream, start=0, end=None):
- """Outputs the file at path to a stream.
+ """Outputs the file at `path` to a stream.
- Data are copied starting from start. If end is not None,
- data are copied up to end.
-
+ Data are copied starting from `start`. If `end` is not None,
+ data are copied up to `end`.
+
"""
def lsinfo(path):
- """Return information for a unix-style ls listing for the path
+ """Return information for a unix-style ls listing for `path`.
Data are returned as a dictionary containing the following keys:
@@ -272,51 +273,51 @@
owner_name
- Defaults to "na". Must not include spaces.
+ Defaults to "na". Must not include spaces.
owner_readable
- defaults to True
+ Defaults to True.
owner_writable
- defaults to True
+ Defaults to True.
owner_executable
- defaults to True for directories and false otherwise.
+ Defaults to True for directories and False otherwise.
group_name
- Defaults to "na". Must not include spaces.
+ Defaults to "na". Must not include spaces.
group_readable
- defaults to True
+ Defaults to True.
group_writable
- defaults to True
+ Defaults to True.
group_executable
- defaults to True for directories and false otherwise.
+ Defaults to True for directories and False otherwise.
other_readable
- defaults to False
+ Defaults to False.
other_writable
- defaults to False
+ Defaults to False.
other_executable
- defaults to True for directories and false otherwise.
+ Defaults to True for directories and false otherwise.
mtime
- Optional time, as a datetime.
+ Optional time, as a datetime.datetime object.
nlinks
@@ -328,29 +329,39 @@
name
- The file name.
+ The file name.
"""
def mtime(path):
- """Return the modification time for the file
+ """Return the modification time for the file at `path`.
Return None if it is unknown.
+
+ XXX: what about if there is no file at `path`?
"""
def size(path):
- """Return the size of the file at path
+ """Return the size of the file at path.
+
+ XXX: what about if there is no file at `path`?
"""
def mkdir(path):
"""Create a directory.
+
+ XXX: what to do if it is not possible, or not allowed?
"""
def remove(path):
- """Remove a file. Same as unlink.
+ """Remove a file. Same as unlink.
+
+ XXX: What to do if removal is not possible, or not allowed?
"""
def rmdir(path):
"""Remove a directory.
+
+ XXX: What to do if removal is not possible, or not allowed?
"""
def rename(old, new):
@@ -360,29 +371,30 @@
def writefile(path, instream, start=None, end=None, append=False):
"""Write data to a file.
- If start or end is not None, then only part of the file is
+ If `start` or `end` is not None, then only part of the file is
written. The remainder of the file is unchanged.
- If start or end are specified, they must ne non-negative.
- If end is None, then the file is truncated after the data are
- written. If end is not None, parts of the file after end, if
- any, are unchanged. If end is not None and there isn't enough
- data in instream to fill out the file, then the missing data
+ If `start` or `end` are specified, they must not be negative.
+
+ If `end` is None, then the file is truncated after the data are
+ written. If `end` is not None, parts of the file after `end`, if
+ any, are unchanged. If `end` is not None and there is not enough
+ data in `instream` to fill out the file, then the missing data
are undefined.
-
- If neither start nor end are specified, then the file contents
+
+ If neither `start` nor `end` are specified, then the file contents
are overwritten.
- If start is specified and the file doesn't exist or is shorter
- than start, the file will contain undefined data before start.
+ If `start` is specified and the file doesn't exist or is shorter
+ than `start`, the file will contain undefined data before `start`.
- If append is true, start and end are ignored.
+ If `append` is true, `start` and `end` are ignored.
"""
def writable(path):
- """Return boolean indicating whether a file at path is writable
+ """Return boolean indicating whether a file at path is writable.
Note that a true value should be returned if the file doesn't
- exist but it's directory is writable.
+ exist but its directory is writable.
"""
More information about the Zope3-Checkins
mailing list