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 asfs.path.join
in direct correspondence withos.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 asfs.path.split
in direct correspondence withos.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')