twisted.python.filepath.FilePath : API documentation

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.

On both Python 2 and Python 3, paths can only be bytes.

Instance Variable	alwaysCreate	When opening this file, only succeed if the file does not already exist. (type: `bool`)
Instance Variable	path	The path from which 'downward' traversal is permitted. (type: `bytes`)
Instance Variable	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`)
Method	__init__	Convert a path string to an absolute path if necessary and initialize the `FilePath` with the result.
Method	__getstate__	Support serialization by discarding cached `os.stat` results and returning everything else.
Method	child	Create and return a new `FilePath` representing a path contained by `self`.
Method	preauthChild	Use me if `path` might have slashes in it, but you know they're safe.
Method	childSearchPreauth	Return my first existing child with a name in `paths`.
Method	siblingExtensionSearch	Attempt to return a path with my name, given multiple possible extensions.
Method	realpath	Returns the absolute target as a `FilePath` if self is a link, self otherwise.
Method	siblingExtension	Attempt to return a path with my name, given the extension at `ext`.
Method	linkTo	Creates a symlink to self to at the path in the `FilePath` `linkFilePath`.
Method	open	Open this file using `mode` or for writing if `alwaysCreate` is `True`.
Method	restat	Re-calculate cached effects of 'stat'. To refresh information on this path after you know the filesystem may have changed, call this method.
Method	changed	Clear any cached information about the state of this path on disk.
Method	chmod	Changes the permissions on self, if possible. Propagates errors from `os.chmod` up.
Method	getsize	Retrieve the size of this file in bytes.
Method	getModificationTime	Retrieve the time of last access from this file.
Method	getStatusChangeTime	Retrieve the time of the last status change for this file.
Method	getAccessTime	Retrieve the time that this file was last accessed.
Method	getInodeNumber	Retrieve the file serial number, also called inode number, which distinguishes this file from all other files on the same device.
Method	getDevice	Retrieves the device containing the file. The inode number and device number together uniquely identify the file, but the device number is not necessarily consistent across reboots or system crashes.
Method	getNumberOfHardLinks	Retrieves the number of hard links to the file.
Method	getUserID	Returns the user ID of the file's owner.
Method	getGroupID	Returns the group ID of the file.
Method	getPermissions	Returns the permissions of the file. Should also work on Windows, however, those permissions may not be what is expected in Windows.
Method	exists	Check if this `FilePath` exists.
Method	isdir	Check if this `FilePath` refers to a directory.
Method	isfile	Check if this file path refers to a regular file.
Method	isBlockDevice	Returns whether the underlying path is a block device.
Method	isSocket	Returns whether the underlying path is a socket.
Method	islink	Check if this `FilePath` points to a symbolic link.
Method	isabs	Check if this `FilePath` refers to an absolute path.
Method	listdir	List the base names of the direct children of this `FilePath`.
Method	splitext	Split the file path into a pair `(root, ext)` such that `root + ext == path`.
Method	__repr__	Undocumented
Method	touch	Updates the access and last modification times of the file at this file path to the current time. Also creates the file if it does not already exist.
Method	remove	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.
Method	makedirs	Create all directories not yet existing in `path` segments, using `os.makedirs`.
Method	globChildren	Assuming I am representing a directory, return a list of FilePaths representing my children that match the given pattern.
Method	basename	Retrieve the final component of the file path's path (everything after the final path separator).
Method	dirname	Retrieve all of the components of the `FilePath`'s path except the last one (everything up to the final path separator).
Method	parent	A file path for the directory containing the file at this file path.
Method	setContent	Replace the file at this path with a new file that contains the given bytes, trying to avoid data-loss in the meanwhile.
Method	__cmp__	Undocumented
Method	createDirectory	Create the directory the `FilePath` refers to.
Method	requireCreate	Sets the `alwaysCreate` variable.
Method	create	Exclusively create a file, only if this file previously did not exist.
Method	temporarySibling	Construct a path referring to a sibling of this path.
Method	copyTo	Copies self to destination.
Method	moveTo	Move self to destination - basically renaming self to whatever destination is named.

Inherited from AbstractFilePath:

Method	getContent	Retrieve the file-like object for this file path.
Method	parents	Retrieve an iterator of all the ancestors of this path.
Method	children	List the children of this path object.
Method	walk	Yield myself, then each of my children, and each of those children's children in turn.
Method	sibling	Return a `FilePath` with the same directory as this instance but with a basename of `path`.
Method	descendant	Retrieve a child or child's child of this path.
Method	segmentsFrom	Return a list of segments between a child and its ancestor.
Method	__hash__	Hash the same as another `FilePath` with the same path as mine.
Method	getmtime	Deprecated. Use getModificationTime instead.
Method	getatime	Deprecated. Use getAccessTime instead.
Method	getctime	Deprecated. Use getStatusChangeTime instead.

Convert a path string to an absolute path if necessary and initialize the FilePath with the result.

Support serialization by discarding cached os.stat results and returning everything else.

Create and return a new FilePath representing a path contained by self.

Parameters	path	The base name of the new `FilePath`. If this contains directory separators or parent references it will be rejected. (type: `bytes`)
Returns	The child path. (type: `FilePath`)
Raises	InsecurePath	If the result of combining this path with `path` would result in a path which is not a direct child of this path.

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

Parameters	path	A relative path (ie, a path not starting with `"/"`) which will be interpreted as a child or descendant of this path. (type: `bytes`)
Returns	The child path. (type: `FilePath`)

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.

Returns None or the child path. (type: types.NoneType or FilePath)

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

Returns	`FilePath` of the target path. (type: `FilePath`)
Raises	LinkError	if links are not supported or links are cyclical.

Attempt to return a path with my name, given the extension at ext.

Parameters	ext	File-extension to search for. (type: `str`)
Returns	The sibling path. (type: `FilePath`)

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 a FilePath representing the link to be created. (type: FilePath)

Open this file using mode or for writing if alwaysCreate is True.

In all cases the file is opened in binary mode, so it is not necessary to include "b" in mode.

Parameters	mode	The mode to open the file in. Default is `"r"`. (type: `str`)
Returns	An open `file` object. (type: `file`)
Raises	AssertionError	If `"a"` is included in the mode and `alwaysCreate` is `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.
Raises	Exception	If `reraise` is `True` and an exception occurs while reloading metadata.

Clear any cached information about the state of this path on disk.

Present Since 10.1.0

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

Parameters mode integer representing the new permissions desired (same as the command line chmod) (type: int)

Retrieve the size of this file in bytes.

Returns	The size of the file at this file path in bytes. (type: `int`)
Raises	Exception	if the size cannot be obtained.

Retrieve the time of last access from this file.

Returns a number of seconds from the epoch. (type: float)

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

Returns a number of seconds from the epoch. (type: float)

Retrieve the time that this file was last accessed.

Returns a number of seconds from the epoch. (type: float)

Retrieve the file serial number, also called inode number, which distinguishes this file from all other files on the same device.

Returns	a number representing the file serial number (type: `int`)
Raises	NotImplementedError	if the platform is Windows, since the inode number would be a dummy value for all files in Windows
Present Since	11.0

Retrieves the device containing the file. The inode number and device number together uniquely identify the file, but the device number is not necessarily consistent across reboots or system crashes.

Returns	a number representing the device (type: `int`)
Raises	NotImplementedError	if the platform is Windows, since the device number would be 0 for all partitions on a Windows platform
Present Since	11.0

Retrieves the number of hard links to the file.

This count keeps track of how many directories have entries for this file. If the count is ever decremented to zero then the file itself is discarded as soon as no process still holds it open. Symbolic links are not counted in the total.

Returns	the number of hard links to the file (type: `int`)
Raises	NotImplementedError	if the platform is Windows, since Windows doesn't maintain a link count for directories, and `os.stat` does not set `st_nlink` on Windows anyway.
Present Since	11.0

Returns the user ID of the file's owner.

Returns	the user ID of the file's owner (type: `int`)
Raises	NotImplementedError	if the platform is Windows, since the UID is always 0 on Windows
Present Since	11.0

Returns the group ID of the file.

Returns	the group ID of the file (type: `int`)
Raises	NotImplementedError	if the platform is Windows, since the GID is always 0 on windows
Present Since	11.0

Returns the permissions of the file. Should also work on Windows, however, those permissions may not be what is expected in Windows.

Returns	the permissions for the file (type: `Permissions`)
Present Since	11.1

Check if this FilePath exists.

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

Check if this FilePath refers to a directory.

Returns True if this FilePath refers to a directory, False otherwise. (type: bool)

Check if this file path refers to a regular file.

Returns True if this FilePath points to a regular file (not a directory, socket, named pipe, etc), False otherwise. (type: bool)

Returns whether the underlying path is a block device.

Returns	`True` if it is a block device, `False` otherwise (type: `bool`)
Present Since	11.1

Returns whether the underlying path is a socket.

Returns	`True` if it is a socket, `False` otherwise (type: `bool`)
Present Since	11.1

Check if this FilePath points to a symbolic link.

Returns True if this FilePath points to a symbolic link, False otherwise. (type: bool)

Check if this FilePath refers to an absolute path.

This always returns True.

Returns True, always. (type: bool)

List the base names of the direct children of this FilePath.

Returns	A `list` of `bytes` giving the names of the contents of the directory this `FilePath` refers to. These names are relative to this `FilePath`. (type: `list`)
Raises	Anything the platform `os.listdir` implementation might raise (typically `OSError`).

Split the file path into a pair (root, ext) such that root + ext == path.

Returns Tuple where the first item is the filename and second item is the file extension. See Python docs for os.path.splitext. (type: tuple)

Updates the access and last modification times of the file at this file path to the current time. Also creates the file if it does not already exist.

Raises Exception if unable to create or modify the last modification time of the file.

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.

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

Returns None

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

Parameters	pattern	A glob pattern to use to match child paths. (type: `bytes`)
Returns	A `list` of matching children. (type: `list`)

Retrieve the final component of the file path's path (everything after the final path separator).

Returns The final component of the FilePath's path (Everything after the final path separator). (type: bytes)

Retrieve all of the components of the FilePath's path except the last one (everything up to the final path separator).

Returns All of the components of the FilePath's path except the last one (everything up to the final path separator). (type: bytes)

A file path for the directory containing the file at this file path.

Returns A FilePath representing the path which directly contains this FilePath. (type: FilePath)

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)
your filesystem's rename() is atomic
your filesystem will not discard new data while preserving new metadata (see http://mjg59.livejournal.com/108257.html for more detail)

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: `bytes`)
	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: `bytes`)

Create the directory the FilePath refers to.

Raises	OSError	If the directory cannot be created.
See Also	`makedirs`

Sets the alwaysCreate variable.

Parameters	val	`True` or `False`, indicating whether opening this path will be required to create the file or not. (type: `bool`)
Returns	`None`

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

Returns A file-like object opened from this path.

Construct a path referring to a sibling of this path.

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: `bytes`)
Returns	a path object with the given extension suffix, `alwaysCreate` set to True. (type: `FilePath`)

Copies self to destination.

If self doesn't exist, an OSError is raised.

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)

t.p.f.FilePath(AbstractFilePath) : class documentation