Instantiate me with a pathname (for example,
FilePath('/home/myuser/public_html')) and I will attempt to only provide
access to files which reside inside that path. I may be a path to a file,
a directory, or a file which does not exist.

The correct way to use me is to instantiate me, and then do ALL
filesystem access through me. In other words, do not import the 'os'
module; if you need to open a file, call my 'open' method. If you need to
list a directory, call my 'path' method.

Even if you pass me a relative path, I will convert that to an absolute
path internally.

Note: although time-related methods do return floating-point results,
they may still be only second resolution depending on the platform and the
last value passed to os.stat_float_times. If you want
greater-than-second precision, call os.stat_float_times(True),
or use Python 2.5. Greater-than-second precision is only available in
Windows on Python2.5 and later.

Instance Variables

alwaysCreate

When opening this file, only succeed if the file does not already
exist.
(type: bool
)

path

The path from which 'downward' traversal is permitted.
(type: str
)

statinfo

The currently cached status information about the file on the filesystem
that this FilePath
points to. This attribute is None if the file is in an
indeterminate state (either this FilePath has
not yet had cause to call stat() yet or FilePath.changed
indicated that new information is required), 0 if stat() was
called and returned an error (i.e. the path did not exist when
stat() was called), or a stat_result object that
describes the last known status of the underlying file (or directory, as
the case may be). Trust me when I tell you that you do not want to use
this attribute. Instead, use the methods on FilePath
which give you information about it, like getsize(),
isdir(), getModificationTime(), and so on.
(type: int or types.NoneType or
os.stat_result
)

Attempt to return a path with my name, given multiple possible
extensions.

Each extension in exts will be tested and the first path which exists
will be returned. If no path exists, None will be returned. If '' is in
exts, then if the file referred to by this path exists, 'self' will be
returned.

The extension '*' has a magic meaning, which means "any path that
begins with self.path+'.' is acceptable".

Returns the absolute target as a FilePath if self is a link, self
otherwise. The absolute link is the ultimate file or directory the link
refers to (for instance, if the link refers to another link, and
another...). If the filesystem does not support symlinks, or if the link
is cyclical, raises a LinkError.

Behaves like os.path.realpath in that it does not resolve
link names in the middle (ex. /x/y/z, y is a link to w - realpath on z will
return /x/y/z, not /x/w/z).

Creates a symlink to self to at the path in the FilePathlinkFilePath. Only works on posix systems due to its
dependence on os.symlink. Propagates OSErrors up
from os.symlink if linkFilePath.parent() does not
exist, or linkFilePath already exists.

Replace the file at this path with a new file that contains the given
bytes, trying to avoid data-loss in the meanwhile.

On UNIX-like platforms, this method does its best to ensure that by the
time this method returns, either the old contents or the new
contents of the file will be present at this path for subsequent readers
regardless of premature device removal, program crash, or power loss,
making the following assumptions:

your filesystem is journaled (i.e. your filesystem will not
itself lose data due to power loss)

On most versions of Windows there is no atomic rename()
(see http://bit.ly/win32-overwrite for more information), so
this method is slightly less helpful. There is a small window where the
file at this path may be deleted before the new file is moved to replace
it: however, the new file will be fully written and flushed beforehand so
in the unlikely event that there is a crash at that point, it should be
possible for the user to manually recover the new version of their data. In
the future, Twisted will support atomic file moves on those versions of
Windows which do support them: see Twisted
ticket 3004.

This method should be safe for use by multiple concurrent processes, but
note that it is not easy to predict which process's contents will
ultimately end up on disk if they invoke this method at close to the same
time.

Parameters

content

The desired contents of the file at this path.
(type: str
)

ext

An extension to append to the temporary filename used to store the bytes
while they are being written. This can be used to make sure that temporary
files can be identified by their suffix, for cleanup in case of
crashes.
(type: str
)

The resulting path will be unpredictable, so that other subprocesses
should neither accidentally attempt to refer to the same path before it is
created, nor they should other processes be able to guess its name in
advance.

Parameters

extension

A suffix to append to the created filename. (Note that if you want an
extension with a '.' you must include the '.' yourself.)
(type: str
)

Returns

a path object with the given extension suffix, alwaysCreate
set to True.
(type: FilePath
)

If self is a directory, this method copies its children (but not itself)
recursively to destination - if destination does not exist as a directory,
this method creates it. If destination is a file, an IOError will be
raised.

If self is a file, this method copies it to destination. If destination
is a file, this method overwrites it. If destination is a directory, an
IOError will be raised.

If self is a link (and followLinks is False), self will be copied over
as a new symlink with the same target as returned by os.readlink. That
means that if it is absolute, both the old and new symlink will link to the
same thing. If it's relative, then perhaps not (and it's also possible
that this relative link will be broken).

File/directory permissions and ownership will NOT be copied over.

If followLinks is True, symlinks are followed so that they're treated as
their targets. In other words, if self is a link, the link's target will
be copied. If destination is a link, self will be copied to the
destination's target (the actual destination will be destination's target).
Symlinks under self (if self is a directory) will be followed and its
target's children be copied recursively.

If followLinks is False, symlinks will be copied over as symlinks.

Parameters

destination

the destination (a FilePath) to which self should be copied

followLinks

whether symlinks in self should be treated as links or as their
targets

Move self to destination - basically renaming self to whatever
destination is named. If destination is an already-existing directory,
moves all children to destination if destination is empty. If destination
is a non-empty directory, or destination is a file, an OSError will be
raised.

If moving between filesystems, self needs to be copied, and everything
that applies to copyTo applies to moveTo.

Parameters

destination

the destination (a FilePath) to which self should be copied

followLinks

whether symlinks in self should be treated as links or as their targets
(only applicable when moving between filesystems)