Python FS - a pythonic file system wrapper for humans

An easy to use file system wrapper for Python that aims to simplify os, os.path, os.walk, shutils, fnmatch, etc.

Installation

Install with the Python Package Manager pip with the following command:

pip install pyfs

Or install from source:

git clone https://github.com/chaosmail/python-fs.git
cd python-fs
python setup.py install

Documentation

First, import the python-fs module.

import fs

fs.exists(path)

Returns True if the path exists. Returns False if path does not exist.

>>> fs.exists('test.txt')
True
>>> fs.exists('some_directory')
True

fs.mkdir(path, recursive=True [, mode])

Creates the directory specified in path.

>>> fs.mkdir('foo/bar/baz')
>>> fs.mkdir('other', recursive=False, mode=0644)

fs.isfile(path)

Returns True if the path exists and is a file. Returns False if path is a directory or does not exist.

>>> fs.isfile('test.txt')
True
>>> fs.isfile('some_directory')
False

fs.isdir(path)

Returns True if the path exists and is a directory. Returns False if path is a file or does not exist.

>>> fs.isdir('test.txt')
False
>>> fs.isdir('some_directory')
True

fs.stat(path)

Returns a stats object that contains meta data of path where path can be either a file or directory. Raises OSError exception if path does not exist.

>>> s = fs.stat('test.txt')
>>> s.st_atime
1428162423.839133
>>> s.st_mtime
1427919315.960152
>>> s.st_ctime
1427919315.960152

fs.ctime(path)

Platform dependent; returns time of most recent metadata change on Unix, or the time of creation on Windows of path where path can be either a file or directory. Raises OSError exception if path does not exist.

>>> fs.ctime('test.txt')
1427919315.960152

fs.atime(path)

Returns time of most recent access of path where path can be either a file or directory. Raises OSError exception if path does not exist.

>>> fs.atime('test.txt')
1428162423.839133

fs.mtime(path)

Returns time of most recent content modification of path where path can be either a file or directory. Raises OSError exception if path does not exist.

>>> fs.mtime('test.txt')
1427919315.960152

fs.mode(path)

Returns permission mode of path where path can be either a file or directory. Raises OSError exception if path does not exist.

>>> fs.mode('test.txt')
33252

fs.rename(oldPath, newPath)

Renames oldPath to new newPath where oldPath can be either a file or directory. Raises OSError exception if oldPath does not exist.

>>> fs.rename('old_test.txt', 'new_test.txt')
>>> fs.rename('old_directory', 'new_directory')

fs.truncate(path)

Removes all files from the path directory.

>>> fs.truncate('some_directory')

fs.chdir(path)

Changes the current directory to path.

>>> fs.chdir('some_directory')

fs.chown(path, user=None, group=None)

Changes the ownership of a path path to the owner user and group group. If user or group is None, the permission for this user or group stays unchanged. Raises PermissionError exception if the current user is not allowed to change the permission. Raises KeyError exception if the user or group don't exist. Raises FileNotFoundError if path does not exist.

>>> fs.chown('some_directory', user='ckoerner')
>>> fs.chown('/var/www', group='www-data')

fs.chmod(path, mode, op='+')

Sets the permissions mode of a path path.

>>> fs.chmod('some_directory', 0o755)

Example: Add exectuable permission to a script run.sh

>>> import stat
>>> fs.chmod('run.sh', fs.mode('run.sh') | stat.S_IEXEC)

Example: Set a 644 permission for a file keys.pem

>>> fs.chmod('keys.pem', 0o644)

fs.addpath(path)

Adds path path to the system path, so that modules can be imported from this path.

>>> fs.addpath('/foo/bar')
>>> import foo

fs.link(srcPath, destPath)

Creates a hard link from srcPath to destPath.

>>> fs.link('/some/dir', 'linkhere')

fs.symlink(srcPath, destPath)

Creates a symbolic link from srcPath to destPath.

>>> fs.symlink('/some/dir/file', 'symlinkhere')

fs.cwd()

Get the current working directory.

>>> fs.cwd()
'/path/to/directory'

fs.home()

Get the current home directory.

>>> fs.home()
'/home/ckoerner'

fs.abspath(path)

Returns the absolute path from a relative path where path can be either file or directory. Raises a ValueError if the directory path does not exist.

>>> fs.abspath('test.txt')
'/path/to/file/test.txt'
>>> fs.abspath('some_directory')
'/path/to/file/some_directory'

fs.normalize(path)

Returns the normalized path from a path where path can be either file or directory.

>>> fs.normalize('test_dir/../test/test.txt')
'test/test.txt'

fs.rm(path)

Deletes the file path. Raises an OSError exception if the file does not exist or path is a directory.

>>> fs.rm('test.txt')

The Unix-like fs.unlink is the same as fs.rm.

fs.rmdir(path, recursive=True)

Deletes the directory path with all containing files and directories. Raises an OSError exception if the directory does not exist or path is a file.

>>> fs.rmdir('some_directory')

fs.rmfiles(paths)

Deletes an array of files paths. Raises an OSError exception if a file does not exist or an element of paths is a directory.

>>> fs.rmfiles(['test.txt', 'another_file.txt'])

Example: Remove all files from the current directory:

>>> fs.rmfiles( fs.list() )

Example: Remove all .pyc files from a directory:

>>> fs.rmfiles( fs.find('*.pyc') )

fs.rmdirs(paths, recursive=True)

Deletes an array of directories paths with all containing files and directories. Raises an OSError exception if a directory does not exist or an element of paths is a file.

>>> fs.rmdirs(['some_directory', 'some_other_dir'])

Example: Remove all directories from the current directory:

>>> fs.rmdirs( fs.listdirs() )

Example: Remove all directories that start with local_:

>>> fs.rmdirs( fs.finddirs('local_*') )

fs.touch(path)

Sets the modification timestamp of path to the current time or creates the file if path does not exist. Directories not supported on Windows.

>>> fs.touch('test.txt')

fs.list(path='.')

Generator that returns all files that are contained in the directory path. Raises an OSError exception if the directory path does not exist.

>>> files = fs.list()
>>> list(files)
['test.txt']
>>> files = fs.list('some_directory')
>>> list(files)
['/path/to/dir/some_directory/another_test.txt']

Example: Loop over all files in the current directory:

>>> for filename in fs.list():
		pass

fs.listdirs(path='.')

Generator that returns all directories that are contained in the directory path. Raises an OSError exception if the directory path does not exist.

>>> dirs = fs.listdirs()
>>> list(dirs)
['some_directory']
>>> dirs = fs.listdirs('some_directory')
>>> list(dirs)
[]

Example: Loop over all directories in the current directory:

>>> for dirname in fs.listdirs():
		pass

fs.find(pattern, path='.', exclude=None, recursive=True)

Generator that returns all files that match pattern and are contained in the directory path. Both pattern and exclude can be Unix shell-style wildcards or arrays of wildcards. Raises an OSError exception if the directory path does not exist.

>>> files = fs.find('*.txt')
>>> list(files)
['/path/to/file/test.txt', '/path/to/file/some_directory/another_test.txt']
>>> files = fs.find('*.txt', exclude='another*')
>>> list(files)
['/path/to/file/test.txt']

Example: Loop over all .csv files in the current directory:

>>> for filename in fs.find('*.csv', recursive=False):
		pass

Example: Loop over all .xls and .xlsx files in the current directory and all sub-directories:

>>> for filename in fs.find(['*.xls', '*.xlsx']):
		pass

Example: Loop over all .ini files in the config directory and all sub-directories except the ones starting with local_:

>>> for filename in fs.find('*.ini', path='config', exclude='local_*'):
		pass

Example: Find and get the Vagrantfile in the config directory:

>>> filename = next( fs.find('Vagrantfile', path='config'), None)

Example: Find the latest SQL file in the backups directory:

>>> filename = max( fs.find('*.sql', path='backup'), key=fs.ctime)

fs.finddirs(pattern, path='.', exclude=None, recursive=True)

Generator that returns all directories that match pattern and are contained in the directory path. Both pattern and exclude can be Unix shell-style wildcards or arrays of wildcards. Raises an OSError exception if the directory path does not exist.

>>> dirs = fs.finddirs('some*')
>>> list(dirs)
['/path/to/file/some_directory']
>>> dirs = fs.finddirs('some*', exclude='*directory')
>>> list(dirs)
[]

Example: Loop over all .git directories in the current directory and all subdirectories:

>>> for dir in fs.finddirs('.git'):
		pass

fs.open(path, mode='r')

Returns a file object of a file path. Raises an IOError exception if the file path does not exist.

>>> file = fs.open('text.txt')

Example: Loop through the lines of a file

>>> file = fs.open('config.ini', 'r')
>>> for line in file:
		pass

fs.write(path, content, encoding='UTF-8', append=False, raw=False)

Writes the content content of a file path.

>>> fs.write('text.txt', 'test')

Example: Append content to a file

>>> fs.write('text.txt', 'test', append=True)

Example: Download an image from an url using requests and save it to local disc:

>>> import requests
>>> res = requests.get(url, stream=True)
>>> fs.write(path, res.raw, raw=True)

fs.read(path, encoding='UTF-8')

Reads and returns the content of a file path. Raises an IOError exception if the file path does not exist.

>>> fs.read('text.txt')
u'test'

fs.put(path, obj)

Writes an object obj to a file path. Raises an IOError exception if the file path does not exist.

>>> fs.put('array.dat', [1,2,3,4])

Example: Save a trained SVM classifier using sklearn to local disc:

>>> from sklearn import svm
>>> X = [[0, 0], [1, 1]]
>>> y = [0, 1]
>>> clf = svm.SVC()
>>> clf.fit(X, y)
SVC(C=1.0, cache_size=200, class_weight=None, coef0=0.0, degree=3, gamma=0.0,
  kernel='rbf', max_iter=-1, probability=False, random_state=None,
  shrinking=True, tol=0.001, verbose=False)
>>> fs.put('svm.dat', clf)

fs.get(path, encoding='UTF-8')

Reads and returns an object from a file path. Raises an IOError exception if the file path does not exist.

>>> fs.get('array.dat')
[1,2,3,4]

Example: Read a trained SVM classifier using sklearn from local disc:

>>> clf = fs.get('svm.dat')
>>> clf.predict([[2., 2.]])
array([1])

fs.sep

The character used by the operating system to separate pathname components. This is '/' for POSIX and '\\' for Windows.

>>> fs.sep
'/'

fs.join(paths)

Joins an array of parts with fs.sep.

>>> fs.join([fs.sep, 'path', 'to', 'directory'])
'/path/to/directory'

Additionally, you can also pass the path elements as arguments fs.join(path, path, ...).

>>> fs.join(fs.sep, 'path', 'to', 'directory')
'/path/to/directory'

fs.extname(path)

Returns the extension name of a file path.

>>> fs.extname('/path/to/file/test.txt')
'.txt'

fs.basename(path, ext="")

Returns the base name of a file path.

>>> fs.basename('/path/to/file/test.txt')
'test.txt'
>>> fs.basename('/path/to/file/test.txt', '.txt')
'test'

fs.dirname(path)

Returns the directory name of a file path.

>>> fs.dirname('/path/to/file/test.txt')
'/path/to/file'

fs.add_suffix(path, suffix="")

Adds suffix to filename path and returns the new filename.

>>> fs.add_suffix('/path/to/file/test.txt', suffix='_new')
'/path/to/file/test_new.txt'

fs.add_prefix(path, prefix="")

Adds prefix to filename path and returns the new filename.

>>> fs.add_prefix('/path/to/file/test.txt', prefix='new_')
'/path/to/file/new_test.txt'

Changelog

0.0.8

• Added fs.add_suffix() and fs.add_prefix()

0.0.7

• Added fs.addpath() to add a path to the system path
• Added fs.basename(path, ext=False) to automatically return filename without extension

0.0.6

• Added fs.home() to retrieve the home directory
• Added fs.chown(), fs.chmod(), fs.link() and fs.symlink()
• Added fs.mode() as shortcut for fs.stat(path).st_mode
• Added fs.cd() alias for fs.chdir()

0.0.5

• Added fs.put() to store object to disc
• Added fs.get() to load object from disc

0.0.4

• Fixed errors with fs.find() for recurive=False
• Added tests for fs.find() and fs.finddirs()
• Added coverage badge

0.0.3

• Fixed python3 error with fs.read()
• Added tests for fs.write() and fs.read()

0.0.2

• Fixed installation error from missing README.md file

0.0.1

• Initial upload to PyPi

License

This software is provided under the MIT License.