FS objects are not permitted to work with any files / directories outside of the Filesystem they represent. If you attempt to open a file or directory outside the root of the FS (e.g. by using "../" in the path) you will get a ``ValueError``.
There is no concept of a current working directory in PyFilesystem, since it is a common source of bugs and not all filesytems even have such a notion. If you want to work with a sub-directory of a FS object, you can use the :meth:`~fs.base.FS.opendir` method which returns another FS object representing the sub-directory.
There is no concept of a current working directory in PyFilesystem, since it is a common source of bugs and not all filesystems even have such a notion. If you want to work with a sub-directory of a FS object, you can use the :meth:`~fs.base.FS.opendir` method which returns another FS object representing the sub-directory.
For example, consider the following directory structure. The directory `foo` contains two sub-directories; `bar` and `baz`::
...
...
@@ -29,7 +29,7 @@ The `foo_fs` object can work with any of the contents of `bar` and `baz`, which
bar_fs = foo_fs.opendir('bar')
This creates a completely new FS object that represents everything in the `foo/bar` directory. The root directory of `bar_fs` has been re-position, so that from `bar_fs`'s point of view, the readment.txt and photo.jpg files are in the root::
This creates a completely new FS object that represents everything in the `foo/bar` directory. The root directory of `bar_fs` has been re-position, so that from `bar_fs`'s point of view, the readme.txt and photo.jpg files are in the root::
--bar
|--readme.txt
...
...
@@ -54,7 +54,7 @@ When working with paths in FS objects, keep in mind the following:
* A double dot means 'previous directory'
Note that paths used by the FS interface will use this format, but the constructor or additional methods may not.
Notably the :mod:`~fs.osfs.OSFS` constructor which requires an OS path -- the format of which can be platform-dependant.
Notably the :mod:`~fs.osfs.OSFS` constructor which requires an OS path -- the format of which can be platform-dependent.
There are many helpful functions for working with paths in the :mod:`fs.path` module.
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.
* Boto (required for :mod:`fs.s3fs`) http://code.google.com/p/boto/
* Paramikio (required for :class:`fs.ftpfs.FTPFS`) http://www.lag.net/paramiko/
* Paramiko (required for :class:`fs.ftpfs.FTPFS`) http://www.lag.net/paramiko/
* wxPython (required for :mod:`fs.browsewin`) http://www.wxpython.org/
Quick Examples
--------------
Before you dive in to the API documentation, here are a few interesting things you can do with pyFilesystem.
Before you dive in to the API documentation, here are a few interesting things you can do with PyFilesystem.
The following will list all the files in your home directory::
PyFilesystems objects are designed to be as generic as possible and still expose the full filesystem functionality.
PyFilesystem objects are designed to be as generic as possible and still expose the full filesystem functionality.
With a little care, you can write a wrapper for your filesystem that allows it to work interchangeably with any of the built-in FS classes and tools.
To create a working PyFilesystem interface, derive a class from :py:class:`fs.base.FS` and implement the 9 :ref:`essential-methods`.
...
...
@@ -11,7 +11,7 @@ The base class uses these essential methods as a starting point for providing a
but in some cases the default implementation may not be the most efficient.
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:
Any of the :ref:`non-essential-methods` may be overridden, 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
...
...
@@ -37,7 +37,7 @@ but there is nothing preventing you from implementing them -- just be careful to
Filesystem Errors
-----------------
With the exception of the constuctor, FS methods should throw :class:`fs.errors.FSError` exceptions in preference to any implementation-specific exception classes,
With the exception of the constructor, FS methods should throw :class:`fs.errors.FSError` exceptions in preference to any implementation-specific exception classes,
so that generic exception handling can be written.
The constructor *may* throw a non-FSError exception, if no appropriate FSError exists.
The rationale for this is that creating an FS interface may require specific knowledge,
...
...
@@ -59,7 +59,7 @@ Any code written to catch the generic error, can also retrieve the original exce
Thread Safety
-------------
All PyFilesystems methods, other than the constructor, should be thread-safe where-ever possible.
All PyFilesystem methods, other than the constructor, should be thread-safe where-ever possible.
One way to do this is to pass ``threads_synchronize=True`` to the base constructor and use the :func:`~fs.base.synchronize` decorator to lock the FS object when a method is called.
If the implementation can not be made thread-safe for technical reasons, ensure that ``getmeta("thread_safe")`` returns ``False``.
...
...
@@ -86,8 +86,8 @@ Essential Methods
The following methods are required for a minimal Filesystem interface:
* :meth:`~fs.base.FS.open` Opens a file for read/writing
* :meth:`~fs.base.FS.isfile` Check wether the path exists and is a file
* :meth:`~fs.base.FS.isdir` Check wether a path exists and is a directory
* :meth:`~fs.base.FS.isfile` Check whether the path exists and is a file
* :meth:`~fs.base.FS.isdir` Check whether a path exists and is a directory
* :meth:`~fs.base.FS.listdir` List the contents of a directory
* :meth:`~fs.base.FS.makedir` Create a new directory
* :meth:`~fs.base.FS.remove` Remove an existing file
...
...
@@ -101,11 +101,11 @@ The following methods are required for a minimal Filesystem interface:
Non - Essential Methods
-----------------------
The following methods have default implementations in :py:class:`fs.base.FS` and aren't required for a functional FS interface. They may be overriden if an alternative implementation can be supplied:
The following methods have default implementations in :py:class:`fs.base.FS` and aren't required for a functional FS interface. They may be overridden if an alternative implementation can be supplied:
* :meth:`~fs.base.FS.copy` Copy a file to a new location
* :meth:`~fs.base.FS.copydir` Recursively copy a directory to a new location
* :meth:`~fs.base.FS.desc` Return a short destriptive text regarding a path
* :meth:`~fs.base.FS.desc` Return a short descriptive text regarding a path
* :meth:`~fs.base.FS.exists` Check whether a path exists as file or directory
* :meth:`~fs.base.FS.listdirinfo` Get a directory listing along with the info dict for each entry
* :meth:`~fs.base.FS.ilistdir` Generator version of the listdir method
...
...
@@ -114,7 +114,7 @@ The following methods have default implementations in :py:class:`fs.base.FS` and
* :meth:`~fs.base.FS.getsyspath` Get a file's name in the local filesystem, if possible
* :meth:`~fs.base.FS.getmeta` Get the value of a filesystem meta value, if it exists
* :meth:`~fs.base.FS.getmmap` Gets an mmap object for the given resource, if supported
* :meth:`~fs.base.FS.hassyspath` Check if a path maps to a system path (recognised by the OS)
* :meth:`~fs.base.FS.hassyspath` Check if a path maps to a system path (recognized by the OS)
* :meth:`~fs.base.FS.haspathurl` Check if a path maps to an external URL
* :meth:`~fs.base.FS.hasmeta` Check if a filesystem meta value exists
* :meth:`~fs.base.FS.move` Move a file to a new location
Generally, when you want to work with the files and directories of any of the supported filesytems,
Generally, when you want to work with the files and directories of any of the supported filesystems,
you create an instance of the appropriate class. For example, the following opens the directory ``/foo/bar``::
from fs.osfs import OSFS
...
...
@@ -17,9 +17,9 @@ In these situations you can use an *opener*, which is a generic way of specifyin
The ``fsopendir`` callable takes a string that identifies the filesystem with a URI syntax, but if called with a regular path will return an :class:`~fs.osfs.OSFS` instance.
To open a different kind of filesystem, precede the path with the required protocol.
For example, the following code opens an FTP filesystem rather than a directory on your harddrive::
For example, the following code opens an FTP filesystem rather than a directory on your hard-drive::
from fs.opener import fsopendir
my_fs = fsopendir('ftp://example.org/foo/bar')
For further information regarding filesystem openers see :doc:`opener`.
\ No newline at end of file
For further information regarding filesystem openers see :doc:`opener`.
There are occasions when you want to specify a filesytem from the command line or in a config file.
This module enables that functionality, and can return an FS object given a URI like syntax (http://commons.apache.org/vfs/filesystems.html).
There are occasions when you want to specify a filesystem from the command line
or in a config file. This module enables that functionality, and can return an
FS object given a filesystem specification in a URI-like syntax (inspired by
the syntax of http://commons.apache.org/vfs/filesystems.html).
The `OpenerRegistry` class maps the protocol (file, ftp etc.) on to an Opener object, which returns an appropriate filesystem object and path.
You can create a custom opener registry that opens just the filesystems you require, or use the opener registry defined here (also called `opener`) that can open any supported filesystem.
The `parse` method of an `OpenerRegsitry` object returns a tuple of an FS object a path. Here's an example of how to use the default opener registry::
The `OpenerRegistry` class maps the protocol (file, ftp etc.) on to an Opener
object, which returns an appropriate filesystem object and path. You can
create a custom opener registry that opens just the filesystems you require, or
use the opener registry defined here (also called `opener`) that can open any
supported filesystem.
The `parse` method of an `OpenerRegsitry` object returns a tuple of an FS
object a path. Here's an example of how to use the default opener registry::
>>> from fs.opener import opener
>>> opener.parse('ftp://ftp.mozilla.org/pub')
(<fs.ftpfs.FTPFS object at 0x96e66ec>, u'pub')
You can use use the `opendir` method, which just returns an FS object. In the example above, `opendir` will return a FS object for the directory `pub`::
You can use use the `opendir` method, which just returns an FS object. In the
example above, `opendir` will return a FS object for the directory `pub`::
>>> opener.opendir('ftp://ftp.mozilla.org/pub')
<SubFS: <FTPFS ftp.mozilla.org>/pub>
If you are just interested in a single file, use the `open` method of a registry which returns a file-like object, and has the same signature as FS objects and the `open` builtin::
If you are just interested in a single file, use the `open` method of a registry
which returns a file-like object, and has the same signature as FS objects and
