twisted :: python :: filepath :: FilePath :: Class FilePath

Class FilePath

_PathHelper --+
              |
             FilePath

Known Subclasses:

web.static.File

I am a path on the filesystem that only permits 'downwards' access.

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.

Nested Classes
	clonePath I am a path on the filesystem that only permits 'downwards' access.

Instance Methods

__init__(self, path, alwaysCreate=False)

__getstate__(self)

child(self, path)

preauthChild(self, path)
Use me if `path' might have slashes in it, but you know they're safe.

childSearchPreauth(self, *paths)
Return my first existing child with a name in 'paths'.

siblingExtensionSearch(self, *exts)
Attempt to return a path with my name, given multiple possible extensions.

realpath(self)
Returns the absolute target as a FilePath if self is a link, self otherwise.

siblingExtension(self, ext)

linkTo(self, linkFilePath)
Creates a symlink to self to at the path in the FilePath linkFilePath.

open(self, mode='r')

restat(self, reraise=True)
Re-calculate cached effects of 'stat'.

chmod(self, mode)
Changes the permissions on self, if possible.

getsize(self)

float

getModificationTime(self)
Retrieve the time of last access from this file.

float

getStatusChangeTime(self)
Retrieve the time of the last status change for this file.

float

getAccessTime(self)
Retrieve the time that this file was last accessed.

bool

exists(self)
Check if the path exists.

isdir(self)

isfile(self)

islink(self)

isabs(self)

listdir(self)

splitext(self)

__repr__(self)

touch(self)

remove(self)
Removes the file or directory that is represented by self.

makedirs(self)
Create all directories not yet existing in path segments, using os.makedirs.

globChildren(self, pattern)
Assuming I am representing a directory, return a list of FilePaths representing my children that match the given pattern.

basename(self)

dirname(self)

parent(self)

setContent(self, content, ext='.new')

__cmp__(self, other)

createDirectory(self)

requireCreate(self, val=1)

create(self)
Exclusively create a file, only if this file previously did not exist.

temporarySibling(self)
Create a path naming a temporary sibling of this path in a secure fashion.

copyTo(self, destination, followLinks=True)
Copies self to destination.

moveTo(self, destination, followLinks=True)
Move self to destination - basically renaming self to whatever destination is named.

Inherited from _PathHelper: __hash__, children, getContent, getatime, getctime, getmtime, parents, segmentsFrom, sibling, walk

Class Variables
	statinfo = `None` hash(x)
	path = `None` hash(x)

Instance Variables
`bool`	alwaysCreate When opening this file, only succeed if the file does not already exist.

Method Details

preauthChild(self, path)

Use me if `path' might have slashes in it, but you know they're safe.

(NOT slashes at the beginning. It still needs to be a _child_).

childSearchPreauth(self, *paths)

Return my first existing child with a name in 'paths'.

paths is expected to be a list of *pre-secured* path fragments; in most cases this will be specified by a system administrator and not an arbitrary user.

If no appropriately-named children exist, this will return None.

siblingExtensionSearch(self, *exts)

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".

realpath(self)

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).

Returns:

FilePath of the target path

Raises:

LinkError - if links are not supported or links are cyclical.

linkTo(self, linkFilePath)

Creates a symlink to self to at the path in the FilePath linkFilePath. 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.

Parameters:

linkFilePath (FilePath) - a FilePath representing the link to be created

restat(self, reraise=True)

Re-calculate cached effects of 'stat'. To refresh information on this path after you know the filesystem may have changed, call this method.

Parameters:

reraise - a boolean. If true, re-raise exceptions from os.stat; otherwise, mark this path as not existing, and remove any cached stat information.

chmod(self, mode)

Changes the permissions on self, if possible. Propagates errors from os.chmod up.

Parameters:

mode (int) - integer representing the new permissions desired (same as the command line chmod)

getModificationTime(self)

Retrieve the time of last access from this file.

Returns: float: a number of seconds from the epoch.

getStatusChangeTime(self)

Retrieve the time of the last status change for this file.

Returns: float: a number of seconds from the epoch.

getAccessTime(self)

Retrieve the time that this file was last accessed.

Returns: float: a number of seconds from the epoch.

exists(self)

Check if the path exists.

Returns: bool: True if the stats of path can be retrieved successfully, False in the other cases.

remove(self)

Removes the file or directory that is represented by self. If self.path is a directory, recursively remove all its children before removing the directory. If it's a file or link, just delete it.

copyTo(self, destination, followLinks=True)

Copies self to destination.

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

moveTo(self, destination, followLinks=True)

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)