twisted.python.filepath.FilePath(AbstractFilePath)
class documentationtwisted.python.filepath
View Source
(View In Hierarchy)
Known subclasses: twisted.web.static.File, twisted.web.twcgi.CGIDirectory
Implements interfaces: twisted.python.filepath.IFilePath
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.
The type of path
when instantiating decides the mode of the
FilePath
.
That is, FilePath(b"/")
will return a bytes
mode FilePath
, and
FilePath(u"/")
will return a unicode
mode FilePath
.
FilePath("/")
will return a bytes
mode FilePath
on
Python 2, and a unicode
mode FilePath
on
Python 3.
Methods that return a new FilePath
use
the type of the given subpath to decide its mode. For example,
FilePath(b"/").child(u"tmp")
will return a
unicode
mode
FilePath
.
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
or unicode ) |
Instance Variable | statinfo 0 | (WARNING: statinfo is deprecated as of Twisted 15.0.0 and will become a
private attribute) 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 None
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 | sep | Return a filesystem separator. |
Method | asBytesMode | Return this FilePath in
bytes -mode. |
Method | asTextMode | Return this FilePath in
unicode -mode. |
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. |
Method | statinfo | FilePath.statinfo is deprecated. |
Method | _asBytesPath | Return the path of this FilePath as
bytes. |
Method | _asTextPath | Return the path of this FilePath as
text. |
Method | _getPathAsSameTypeAs | If pattern is bytes , return FilePath.path
as bytes .
Otherwise, return FilePath.path
as unicode . |
Inherited from AbstractFilePath:
Method | getContent | Retrieve the contents of the file at this 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. |
bool
)
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 None
or os.stat_result
)
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.
Return a filesystem separator.
Returns | The native filesystem separator. (type: The same type as self.path .) |
Return the path of this FilePath
as
bytes.
Parameters | encoding | The encoding to use if coercing to bytes .
If none is given, sys.getfilesystemencoding
is used. |
Returns | bytes |
Return the path of this FilePath
as
text.
Parameters | encoding | The encoding to use if coercing to unicode . If none
is given, sys.getfilesystemencoding
is used. |
Returns | unicode |
If pattern
is bytes
, return FilePath.path
as bytes
.
Otherwise, return FilePath.path
as unicode
.
Parameters | pattern | The new element of the path that FilePath.path
may need to be coerced to match. |
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
or unicode ) |
Returns | The child path. (type: FilePath
with a mode equal to the type of path .) | |
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. |
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: None
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. |
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 OSError
s
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 |
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 |
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 |
List the base names of the direct children of this FilePath
.
Returns | A list
of bytes /unicode 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
.
Parameters | ignoreExistingDirectory | Don't raise OSError
if directory already exists. (type: bool ) |
Returns | None |
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:
rename()
is atomic
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 ) |
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
or unicode ) |
Returns | a path object with the given extension suffix, alwaysCreate
set to True. (type: FilePath
with a mode equal to the type of extension ) |
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) |