# 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 /

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 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 remove any leading or trailing slashes, collapses duplicate slashes, replaces backward with forward slashes, and generally tries very hard to return a new path string the canonical FS format. If the path is invalid, ValueError will be raised.

Parameters: path – path to normalize a valid FS path
>>> normpath(r"foo\bar\baz")
'foo/bar/baz'

>>> normpath("/foo//bar/frob/../baz")
'/foo/bar/baz'

>>> normpath("foo/../../bar")
Traceback (most recent call last)
...
ValueError: too many backrefs in path 'foo/../../bar'

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


fs.opener

fs.remote