||7 years ago|
|filething||7 years ago|
|.gitignore||7 years ago|
|README.md||7 years ago|
|setup.py||7 years ago|
Filesystem operations are one of those things in the Python standard library that just kind of suck.
filething is a thin light-weight wrapper library, to make filesystem operations in Python suck less. It's primarily meant for read-only stuff, and doesn't do anything to set file attributes and so on.
Theoretically cross-platform. Then again, Windows will probably be Windows and thus it may break there. I have no idea, I don't use Windows. All code is pure Python, anyway.
pip install filething
Done. You'll need
pip, of course.
First of all, import
Then there's a bunch of stuff you can do. To start working with a directory or file, create a
File object respectively.
To create a new
some_dir = filething.Directory("/path/to/directory")
To create a new
some_file = filething.File("/path/to/file")
Entering a non-existent (or inaccessible) path will result in a
filething.FilesystemException being raised.
Directory and File objects
File classes have some things in common.
The following attributes are automatically set on both
path: The path of the file or directory.
name: The name of the file or directory. This is generally the part after the last slash.
is_symlink: Boolean. Whether the file/directory is a symlink or not.
To learn more about a directory or file, you can use the
stat will give you the metadata for a file or directory, resolving a symlink if necessary.
symlink_stat only applies to symbolic links, and gives you metadata about the symlink itself.
Trying to use
symlink_stat on something that isn't a symlink, will raise a
symlink_stat function returns data in the same format as
stat. The below applies to both.
metadata = some_file.stat()
By default, the
stat data will be returned as a custom
Attributes object, with more human-meaningful names than what Python provides. The below is a list of available attributes, with a description (and their original name in
os.stat in parentheses). I'll assume that the metadata is stored in a
metadata variable, as above.
As with Python's
os.stat, the exact meaning and accuracy of
ctime differ across platforms and filesystems.
metadata.size (st_size): size of file, in bytes
metadata.lastaccessed (st_atime): time of most recent access
metadata.lastmodified (st_mtime): time of most recent content modification
metadata.uid (st_uid): user id of owner
metadata.gid (st_gid): group id of owner
metadata.mode (st_mode): protection bits
metadata.inode (st_ino): inode number
metadata.device (st_dev): device
metadata.links (st_nlink): number of hard links
metadata.ctime (st_ctime): platform dependent; time of most recent metadata change on Unix, or the time of creation on Windows
On some UNIX-like (eg. Linux):
- metadata.blockcount (st_blocks): number of 512-byte blocks allocated for file
- metadata.blocksize (st_blksize): filesystem blocksize for efficient file system I/O
- metadata.devicetype (st_rdev): type of device if an inode device
- metadata.userflags (st_flags): user defined flags for file
On some other UNIX-like (eg. FreeBSD):
- metadata.filegen (st_gen): file generation number
- metadata.creation (st_birthtime): time of file creation
On Mac OS:
- metadata.rsize (st_rsize): ?
- metadata.creator (st_creator): ?
- metadata.type (st_type): ?
- metadata.filetype (st_ftype): file type
- metadata.attributes (st_attrs): attributes
- metadata.objecttype (st_objtype): object type
You may access any of these attributes as either normal attributes, or as dictionary keys. The following are both valid:
filesize = metadata.size filesize = metadata['size']
Optionally, you may pass
True as a parameter to either
symlink_stat, to return the original data returned by
os.stat, without changing the attribute names. This does, however, mean that dictionary key access no longer works. Example:
metadata = some_file.stat(True) filesize = metadata.st_size # Valid filesize = metadata['st_size'] # Won't work!
There are some methods that are specific to directories, and only available on
Retrieving a child file/directory
You can use
get to retrieve a
Directory object for a child node. The type of node will automatically be detected, and either a
Directory object will be returned as appropriate. The child doesn't have to be a direct child; it will simply join together the paths, so you can even retrieve nodes outside the path of the current
FilesystemException will be raised if the path does not exist.
child_dir = some_dir.get("assets") deeper_child_file = some_dir.get("public/static/logo.png") outside_dir = some_dir.get("../configuration")
Listing all child nodes
You may retrieve a list of
Directory objects representing child nodes of the directory, by using
child_nodes = some_dir.get_children()
Alternatively, you may use
get_directories to only retrieve child files and directories, respectively. All files and directories will be wrapped in
You may use
File objects as actual Python file objects. There are three ways to do this:
As a context manager in read-only mode
The easiest way. The file object will be opened in
rb (binary reading) mode. It will be automatically closed.
some_file = filething.File("/some/file/on/my/system") with some_file as f: print f.read()
As a context manager in another mode
If you need to do more than just reading, you may define an explicit mode. The file will still be automatically closed.
some_file = filething.File("/some/file/on/my/system") with some_file("wb") as f: f.write("hi!")
As a normal function
If context managers are not an option for some reason, you may retrieve the corresponding Python file object through a regular method. If you don't specify a mode, it will default to
Note that when using this method, you need to manually close the file!
some_file = filething.File("/some/file/on/my/system") f = some_file.get_file_object("wb") f.write("hi!") f.close()