fs.path

Useful functions for FS path manipulation.

This is broadly similar to the standard os.path module but works with paths in the canonical format expected by all FS objects (that is, separated by forward slashes and with an optional leading slash).

class fs.path.PathMap

Dict-like object with paths for keys.

A PathMap is like a dictionary where the keys are all FS paths. It has two main advantages over a standard dictionary. First, keys are normalized automatically:

>>> pm = PathMap()
>>> pm["hello/world"] = 42
>>> print pm["/hello/there/../world"]
42

Second, various dictionary operations (e.g. listing or clearing values) can be efficiently performed on a subset of keys sharing some common prefix:

# list all values in the map
pm.values()

# list all values for paths starting with "/foo/bar"
pm.values("/foo/bar")

Under the hood, a PathMap is a trie-like structure where each level is indexed by path name component. This allows lookups to be performed in O(number of path components) while permitting efficient prefix-based operations.

clear(root='/')

Clear all entries beginning with the given root path.

get(path, default=None)

Get the value stored under the given path, or the given default.

iteritems(root='/', m=None)

Iterate over all (key,value) pairs beginning with the given root.

iterkeys(root='/', m=None)

Iterate over all keys beginning with the given root path.

iternames(root='/')

Iterate over all names beneath the given root path.

This is basically the equivalent of listdir() for a PathMap - it yields the next level of name components beneath the given path.

itervalues(root='/', m=None)

Iterate over all values whose keys begin with the given root path.

pop(path, default=None)

Pop the value stored under the given path, or the given default.

fs.path.abspath(path)

Convert the given path to an absolute path.

Since FS objects have no concept of a ‘current directory’ this simply adds a leading ‘/’ character if the path doesn’t already have one.

fs.path.basename(path)

Returns the basename of the resource referenced by a path.

This is always equivalent to the ‘tail’ component of the value returned by pathsplit(path).

Parameters:path – A FS path
>>> basename('foo/bar/baz')
'baz'
>>> basename('foo/bar')
'bar'
>>> basename('foo/bar/')
''
fs.path.dirname(path)

Returns the parent directory of a path.

This is always equivalent to the ‘head’ component of the value returned by pathsplit(path).

Parameters:path – A FS path
>>> dirname('foo/bar/baz')
'foo/bar'
>>> dirname('/foo/bar')
'/foo'
>>> dirname('/foo')
'/'
fs.path.forcedir(path)

Ensure the path ends with a trailing forward slash

Parameters:path – An FS path
>>> forcedir("foo/bar")
'foo/bar/'
>>> forcedir("foo/bar/")
'foo/bar/'
fs.path.isabs(path)

Return True if path is an absolute path.

fs.path.isdotfile(path)

Detects if a path references a dot file, i.e. a resource who’s name starts with a ‘.’

Parameters:path – Path to check
>>> isdotfile('.baz')
True
>>> isdotfile('foo/bar/.baz')
True
>>> isdotfile('foo/bar.baz')
False
fs.path.isprefix(path1, path2)

Return true is path1 is a prefix of path2.

Parameters:
  • path1 – An FS path
  • path2 – An FS path
>>> isprefix("foo/bar", "foo/bar/spam.txt")
True
>>> isprefix("foo/bar/", "foo/bar")
True
>>> isprefix("foo/barry", "foo/baz/bar")
False
>>> isprefix("foo/bar/baz/", "foo/baz/bar")
False
fs.path.issamedir(path1, path2)

Return true if two paths reference a resource in the same directory.

Parameters:
  • path1 – An FS path
  • path2 – An FS path
>>> issamedir("foo/bar/baz.txt", "foo/bar/spam.txt")
True
>>> issamedir("foo/bar/baz/txt", "spam/eggs/spam.txt")
False
fs.path.iswildcard(path)

Check if a path ends with a wildcard

>>> is_wildcard('foo/bar/baz.*')
True
>>> is_wildcard('foo/bar')
False
fs.path.iteratepath(path, numsplits=None)

Iterate over the individual components of a path.

Parameters:path – Path to iterate over
Numsplits:Maximum number of splits
fs.path.join(*paths)

Joins any number of paths together, returning a new path string.

This is a simple alias for the pathjoin function, allowing it to be used as fs.path.join in direct correspondence with os.path.join.

Parameters:paths – Paths to join are given in positional arguments
fs.path.normpath(path)

Normalizes a path to be in the format expected by FS objects.

This function removes trailing slashes, collapses duplicate slashes, and generally tries very hard to return a new path in the canonical FS format. If the path is invalid, ValueError will be raised.

Parameters:path – path to normalize
Returns:a valid FS path
>>> normpath("/foo//bar/frob/../baz")
'/foo/bar/baz'
>>> normpath("foo/../../bar")
Traceback (most recent call last)
    ...
BackReferenceError: Too many backrefs in 'foo/../../bar'
fs.path.ospath(path)

Replace path separators in an OS path if required

fs.path.pathcombine(path1, path2)

Joins two paths together.

This is faster than pathjoin, but only works when the second path is relative, and there are no backreferences in either path.

>>> pathcombine("foo/bar", "baz")
'foo/bar/baz'
fs.path.pathjoin(*paths)

Joins any number of paths together, returning a new path string.

Parameters:paths – Paths to join are given in positional arguments
>>> pathjoin('foo', 'bar', 'baz')
'foo/bar/baz'
>>> pathjoin('foo/bar', '../baz')
'foo/baz'
>>> pathjoin('foo/bar', '/baz')
'/baz'
fs.path.pathsplit(path)

Splits a path into (head, tail) pair.

This function splits a path into a pair (head, tail) where ‘tail’ is the last pathname component and ‘head’ is all preceding components.

Parameters:path – Path to split
>>> pathsplit("foo/bar")
('foo', 'bar')
>>> pathsplit("foo/bar/baz")
('foo/bar', 'baz')
>>> pathsplit("/foo/bar/baz")
('/foo/bar', 'baz')
fs.path.recursepath(path, reverse=False)

Returns intermediate paths from the root to the given path

Parameters:reverse – reverses the order of the paths
>>> recursepath('a/b/c')
['/', u'/a', u'/a/b', u'/a/b/c']
fs.path.relativefrom(base, path)

Return a path relative from a given base path, i.e. insert backrefs as appropriate to reach the path from the base.

Parameters:
  • base_path – Path to a directory
  • path – Path you wish to make relative
>>> relativefrom("foo/bar", "baz/index.html")
'../../baz/index.html'
fs.path.relpath(path)

Convert the given path to a relative path.

This is the inverse of abspath(), stripping a leading ‘/’ from the path if it is present.

Parameters:path – Path to adjust
>>> relpath('/a/b')
'a/b'
fs.path.split(path)

Splits a path into (head, tail) pair.

This is a simple alias for the pathsplit function, allowing it to be used as fs.path.split in direct correspondence with os.path.split.

Parameters:path – Path to split
fs.path.splitext(path)

Splits the extension from the path, and returns the path (up to the last ‘.’ and the extension).

Parameters:path – A path to split
>>> splitext('baz.txt')
('baz', 'txt')
>>> splitext('foo/bar/baz.txt')
('foo/bar/baz', 'txt')