Permalink
Browse files

Doc fixes

git-svn-id: http://pyfilesystem.googlecode.com/svn/trunk@651 67cdc799-7952-0410-af00-57a81ceafa0f
  • Loading branch information...
1 parent b791169 commit d796d3b241416455eb00d97663a565515349f4f7 willmcgugan committed Mar 8, 2011
Showing with 44 additions and 45 deletions.
  1. +4 −4 docs/base.rst
  2. +4 −2 docs/commands.rst
  3. +2 −2 docs/concepts.rst
  4. +1 −1 docs/expose.rst
  5. +1 −1 docs/ftpfs.rst
  6. +5 −5 docs/getting_started.rst
  7. +6 −6 docs/implementersguide.rst
  8. +0 −1 docs/introduction.rst
  9. +3 −2 fs/base.py
  10. +5 −8 fs/ftpfs.py
  11. +1 −1 fs/mountfs.py
  12. +6 −6 fs/utils.py
  13. +2 −2 fs/watch.py
  14. +4 −4 fs/xattrs.py
View
@@ -6,15 +6,15 @@ This module contains the basic FS interface and a number of other essential inte
fs.base.FS
----------
-All Filesystem objects inherit from this class,
+All Filesystem objects inherit from this class.
.. autoclass:: fs.base.FS
:members:
fs.base.SubFS
-------------
-A SubFS is an FS implementation that represents a directory on another Filesystem. When you use the `opendir` method it will return a SubFS instance. You should not need to instantiate a SubFS directly.
+A SubFS is an FS implementation that represents a directory on another Filesystem. When you use the :meth:`fs.base.FS.opendir` method it will return a SubFS instance. You should not need to instantiate a SubFS directly.
For example::
@@ -28,7 +28,7 @@ fs.base.NullFile
A NullFile is a file-like object with no functionality. It is used in situations where a file-like object is required but the caller doesn't have any data to read or write.
-The `safeopen` method returns an NullFile instance, which can reduce error-handling code.
+The :meth:`fs.base.FS.safeopen` method returns an NullFile instance, which can reduce error-handling code.
For example, the following code may be written to append some text to a log file::
@@ -44,5 +44,5 @@ This could be re-written using the `safeopen` method::
myfs.safeopen('log.txt', 'a').writeline('operation successful!')
-If the file doesn't exist then the call to writeline will be a null-operation (i.e. not do anything)
+If the file doesn't exist then the call to writeline will be a null-operation (i.e. not do anything).
View
@@ -18,17 +18,19 @@ For example, the following uses a custom opener to list the contents of a direct
fsls --fs mypackage.mymodule.myfs.MyFSOpener myfs://127.0.0.1
+
Listing Supported Filesystems
-----------------------------
-All of the command line applications support the `--listopeners` switch, which lists all available installed openers::
+All of the command line applications support the ``--listopeners`` switch, which lists all available installed openers::
fsls --listopeners
+
fsls
----
-Lists the contents of a directory, similar to the `ls` command, e.g.::
+Lists the contents of a directory, similar to the ``ls`` command, e.g.::
fsls
fsls ../
View
@@ -71,7 +71,7 @@ For example::
u'/home/will/test.txt'
Not all FS implementation will map to a valid system path (e.g. the FTP FS object).
-If you call :meth:`~fs.base.FS.getsyspath` on such FS objects you will either get a :class:`~fs.errors.NoSysPathError` exception or a return value of ``None``, if you call ``getsyspath`` with `allow_none=True`.
+If you call :meth:`~fs.base.FS.getsyspath` on such FS objects you will either get a :class:`~fs.errors.NoSysPathError` exception or a return value of ``None``, if you call ``getsyspath`` with ``allow_none=True``.
Errors
------
@@ -89,4 +89,4 @@ PyFilesystem converts all exceptions to a common type, so that you need only wri
return open(self.getsyspath(path), mode, kwargs.get("buffering", -1))
fs.errors.ResourceNotFoundError: Resource not found: doesnotexist.txt
-All PyFilesystem exceptions are derived from :class:`fs.errors.FSError`, so you may use that if you want to catch all possible exceptions.
+All PyFilesystem exceptions are derived from :class:`fs.errors.FSError`, so you may use that if you want to catch all possible filesystem related exceptions.
View
@@ -1,7 +1,7 @@
Exposing FS objects
===================
-The ``fs.expose`` module offers a number of ways of making an FS implementation available over an internet connection, or to other processes on the system.
+The ``fs.expose`` module offers a number of ways of making an FS implementation available over an Internet connection, or to other processes on the system.
FUSE
View
@@ -1,2 +1,2 @@
-.. automodule:: fs.ftpfs
+.. autoclass:: fs.ftpfs.FTPFS
:members:
View
@@ -1,7 +1,7 @@
Getting Started
===============
-PyFilesystem is a Python-only module and can be installed with easy_install or by source. PyFilesystem is known to work on Linux, Mac and OSX.
+PyFilesystem is a Python-only module and can be installed with easy_install or from source. PyFilesystem is known to work on Linux, Mac and OSX.
Installing
----------
@@ -30,10 +30,10 @@ Prerequisites
-------------
PyFilesystem requires at least **Python 2.5**. There are a few other dependencies if you want to use some of the more advanced filesystem interfaces, but for basic use all that is needed is the Python standard library.
-
- * wxPython (required for fs.browsewin) http://www.wxpython.org/
- * Boto (required for fs.s3fs) http://code.google.com/p/boto/
- * Paramikio (required for fs.ftpfs) http://www.lag.net/paramiko/
+
+ * Boto (required for :mod:`fs.s3fs`) http://code.google.com/p/boto/
+ * Paramikio (required for :mod:`fs.ftpfs`) http://www.lag.net/paramiko/
+ * wxPython (required for :mod:`fs.browsewin`) http://www.wxpython.org/
Quick Examples
View
@@ -9,9 +9,9 @@ With a little care, you can write a wrapper for your filesystem that allows it t
To create a working PyFilesystem interface, derive a class from :py:class:`fs.base.FS` and implement the 9 :ref:`essential-methods`.
The base class uses these essential methods as a starting point for providing a lot of extra functionality,
but in some cases the default implementation may not be the most efficient.
-For example, most filesystems have some atomic way of moving a file without having to copy data,
-whereas the default implementation of :meth:`~fs.base.FS.move` method must copy all the bytes in the file.
-Although any of the :ref:`non-essential-methods` may be overriden, efficient versions of the following methods will have the greatest impact on performance:
+For example, most filesystems have an atomic way of moving a file from one location to another without having to copy data,
+whereas the default implementation of :meth:`~fs.base.FS.move` method must copy all the bytes in the source file to the destination file.
+Any of the :ref:`non-essential-methods` may be overriden, but efficient custom versions of the following methods will have the greatest impact on performance:
* :meth:`~fs.base.FS.copy` copy a file
* :meth:`~fs.base.FS.copydir` copy a directory
@@ -20,7 +20,7 @@ Although any of the :ref:`non-essential-methods` may be overriden, efficient ver
* :meth:`~fs.base.FS.move` move a file
* :meth:`~fs.base.FS.movedir` move a directory
-For network based filesystems (i.e. where the physical data is pulled from a network),
+For network based filesystems (i.e. where the physical data is pulled over a network),
there are a few methods which can reduce the number of round trips to the server,
if an efficient implementation is provided:
@@ -46,7 +46,7 @@ but this shouldn't prevent it from working with more generic code.
If specific exceptions need to be translated in to an equivalent FSError,
pass the original exception class to the FSError constructor with the 'details' keyword argument.
-For example, the following translates some ficticious exception in to an FS exception,
+For example, the following translates some fictitious exception in to an FSError exception,
and passes the original exception as an argument.::
try:
@@ -75,7 +75,7 @@ Implementations are also free to reserve a dotted namespace notation for themsel
If you do this, please avoid generic terms as they may conflict with existing or future implementations.
For example ``"bobs_ftpfs.author"``, rather than ``"ftpfs.author"``.
-If your meta values are static, i.e. they never change, then create a dictionary class attribute called ``_meta`` in your implementation that contains all the meta keys, values.
+If your meta values are static, i.e. they never change, then create a dictionary class attribute called ``_meta`` in your implementation that contains all the meta keys and values.
The default ``getmeta`` implementation will pull the meta values from this dictionary.
.. _essential-methods:
View
@@ -28,4 +28,3 @@ Discussion Group
There is also a discussion group for PyFilesystem: http://groups.google.com/group/pyfilesystem-discussion
-
View
@@ -235,9 +235,10 @@ def getmeta(self, meta_name, default=NoDefaultMeta):
* *atomic.rename* True if rename is an atomic operation, (and not implemented as a copy followed by a delete)
* *atomic.setcontents* True if the implementation supports setting the contents of a file as an atomic operation (without opening a file)
* *free_space* The free space (in bytes) available on the file system
- * *total_space* The total space (in bytes) available on the file system
+ * *total_space* The total space (in bytes) available on the file system
+ * *virtual* True if the filesystem defers to other filesystems
- FS implementations may expose non-generic meta data through a self-named namespace. e.g. ``somefs.some_meta``
+ FS implementations may expose non-generic meta data through a self-named namespace. e.g. ``"somefs.some_meta"``
Since no meta value is guaranteed to exist, it is advisable to always supply a
default value to ``getmeta``.
View
@@ -813,10 +813,8 @@ class FTPFS(FS):
'file.read_and_write' : False,
}
- def __init__(self, host='', user='', passwd='', acct='', timeout=_GLOBAL_DEFAULT_TIMEOUT,
- port=21,
- dircache=True):
- """ Connect to a FTP server.
+ def __init__(self, host='', user='', passwd='', acct='', timeout=_GLOBAL_DEFAULT_TIMEOUT, port=21, dircache=True):
+ """Connect to a FTP server.
:param host: Host to connect to
:param user: Username, or a blank string for anonymous
@@ -825,10 +823,9 @@ def __init__(self, host='', user='', passwd='', acct='', timeout=_GLOBAL_DEFAULT
:param timeout: Timeout in seconds
:param port: Port to connection (default is 21)
:param dircache: If True then directory information will be cached,
- which will speed up operations such as getinfo, isdir, isfile, but
- changes to the ftp file structure will not be visible until
- `~fs.ftpfs.FTPFS.clear_dircache` is called
- :param dircache: If True directory information will be cached for fast access
+ speeding up operations such as `getinfo`, `isdir`, `isfile`, but
+ changes to the ftp file structure will not be visible until
+ :meth:`~fs.ftpfs.FTPFS.clear_dircache` is called
"""
View
@@ -396,7 +396,7 @@ def mountfile(self, path, open_callable=None, info_callable=None):
"""Mounts a single file path.
:param path: A path within the MountFS
- :param open_Callable: A callable that returns a file-like object
+ :param open_callable: A callable that returns a file-like object
:param info_callable: A callable that returns a dictionary with information regarding the file-like object
"""
View
@@ -18,7 +18,7 @@
import sys
import stat
from fs.mountfs import MountFS
-from fs.path import pathjoin, pathsplit
+from fs.path import pathjoin
from fs.errors import DestinationExistsError
from fs.base import FS
@@ -32,7 +32,7 @@ def copyfile(src_fs, src_path, dst_fs, dst_path, overwrite=True, chunk_size=64*1
:param src_path: -- Source path
:param dst_fs: Destination filesystem object
:param dst_path: Destination filesystem object
- :param chunk_size: Size of chunks to move if system copyfile is not available (default 16K)
+ :param chunk_size: Size of chunks to move if system copyfile is not available (default 64K)
"""
@@ -76,7 +76,7 @@ def copyfile_non_atomic(src_fs, src_path, dst_fs, dst_path, overwrite=True, chun
:param src_path: -- Source path
:param dst_fs: Destination filesystem object
:param dst_path: Destination filesystem object
- :param chunk_size: Size of chunks to move if system copyfile is not available (default 16K)
+ :param chunk_size: Size of chunks to move if system copyfile is not available (default 64K)
"""
@@ -109,7 +109,7 @@ def movefile(src_fs, src_path, dst_fs, dst_path, overwrite=True, chunk_size=64*1
:param src_path: Source path
:param dst_fs: Destination filesystem object
:param dst_path: Destination filesystem object
- :param chunk_size: Size of chunks to move if system copyfile is not available (default 16K)
+ :param chunk_size: Size of chunks to move if system copyfile is not available (default 64K)
"""
src_syspath = src_fs.getsyspath(src_path, allow_none=True)
@@ -151,13 +151,13 @@ def movefile(src_fs, src_path, dst_fs, dst_path, overwrite=True, chunk_size=64*1
def movefile_non_atomic(src_fs, src_path, dst_fs, dst_path, overwrite=True, chunk_size=64*1024):
- """A non atomic version of movefile (wont block other threads using src_fs or dst_fs
+ """A non atomic version of movefile (wont block other threads using src_fs or dst_fs)
:param src_fs: Source filesystem object
:param src_path: Source path
:param dst_fs: Destination filesystem object
:param dst_path: Destination filesystem object
- :param chunk_size: Size of chunks to move if system copyfile is not available (default 16K)
+ :param chunk_size: Size of chunks to move if system copyfile is not available (default 64K)
"""
View
@@ -10,13 +10,13 @@
An FS object that wants to be "watchable" must provide the following methods:
- * add_watcher(callback,path="/",events=None,recursive=True)
+ * ``add_watcher(callback,path="/",events=None,recursive=True)``
Request that the given callback be executed in response to changes
to the given path. A specific set of change events can be specified.
This method returns a Watcher object.
- * del_watcher(watcher_or_callback)
+ * ``del_watcher(watcher_or_callback)``
Remove the given watcher object, or any watchers associated with
the given callback.
View
@@ -11,10 +11,10 @@
FS instances offering extended attribute support must provide the following
methods:
- * getxattr(path,name) Get the named attribute for the given path, or None if it does not exist
- * setxattr(path,name,value) Set the named attribute for the given path to the given value
- * delxattr(path,name) Delete the named attribute for the given path, raising KeyError if it does not exist
- * listxattrs(path) Iterate over all stored attribute names for the given path
+ * ``getxattr(path,name)`` Get the named attribute for the given path, or None if it does not exist
+ * ``setxattr(path,name,value)`` Set the named attribute for the given path to the given value
+ * ``delxattr(path,name)`` Delete the named attribute for the given path, raising KeyError if it does not exist
+ * ``listxattrs(path)`` Iterate over all stored attribute names for the given path
If extended attributes are required by FS-consuming code, it should use the
function 'ensure_xattrs'. This will interrogate an FS object to determine

0 comments on commit d796d3b

Please sign in to comment.