fs.path

Useful functions for working with PyFilesystem paths.

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

See Paths for an explanation of PyFilesystem paths.

fs.path.abspath(path: Text) → Text[source]

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.

Parameters

path (str) – A PyFilesytem path.

Returns

An absolute path.

Return type

str

fs.path.basename(path: Text) → Text[source]

Return the basename of the resource referenced by a path.

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

Parameters

path (str) – A PyFilesytem path.

Returns

the name of the resource at the given path.

Return type

str

Example

>>> basename('foo/bar/baz')
'baz'
>>> basename('foo/bar')
'bar'
>>> basename('foo/bar/')
''
fs.path.combine(path1: Text, path2: Text) → Text[source]

Join two paths together.

This is faster than join(), but only works when the second path is relative, and there are no back references in either path.

Parameters
  • path1 (str) – A PyFilesytem path.

  • path2 (str) – A PyFilesytem path.

Returns

The joint path.

Return type

str

Example

>>> combine("foo/bar", "baz")
'foo/bar/baz'
fs.path.dirname(path: Text) → Text[source]

Return the parent directory of a path.

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

Parameters

path (str) – A PyFilesytem path.

Returns

the parent directory of the given path.

Return type

str

Example

>>> dirname('foo/bar/baz')
'foo/bar'
>>> dirname('/foo/bar')
'/foo'
>>> dirname('/foo')
'/'
fs.path.forcedir(path: Text) → Text[source]

Ensure the path ends with a trailing forward slash.

Parameters

path (str) – A PyFilesytem path.

Returns

The path, ending with a slash.

Return type

str

Example

>>> forcedir("foo/bar")
'foo/bar/'
>>> forcedir("foo/bar/")
'foo/bar/'
>>> forcedir("foo/spam.txt")
'foo/spam.txt/'
fs.path.frombase(path1: Text, path2: Text) → Text[source]

Get the final path of path2 that isn’t in path1.

Parameters
  • path1 (str) – A PyFilesytem path.

  • path2 (str) – A PyFilesytem path.

Returns

the final part of path2.

Return type

str

Example

>>> frombase('foo/bar/', 'foo/bar/baz/egg')
'baz/egg'
fs.path.isabs(path: Text) → bool[source]

Check if a path is an absolute path.

Parameters

path (str) – A PyFilesytem path.

Returns

True if the path is absolute (starts with a '/').

Return type

bool

fs.path.isbase(path1: Text, path2: Text) → bool[source]

Check if path1 is a base of path2.

Parameters
  • path1 (str) – A PyFilesytem path.

  • path2 (str) – A PyFilesytem path.

Returns

True if path2 starts with path1

Return type

bool

Example

>>> isbase('foo/bar', 'foo/bar/baz/egg.txt')
True
fs.path.isdotfile(path: Text) → bool[source]

Detect if a path references a dot file.

Parameters

path (str) – Path to check.

Returns

True if the resource name starts with a '.'.

Return type

bool

Example

>>> isdotfile('.baz')
True
>>> isdotfile('foo/bar/.baz')
True
>>> isdotfile('foo/bar.baz')
False
fs.path.isparent(path1: Text, path2: Text) → bool[source]

Check if path1 is a parent directory of path2.

Parameters
  • path1 (str) – A PyFilesytem path.

  • path2 (str) – A PyFilesytem path.

Returns

True if path1 is a parent directory of path2

Return type

bool

Example

>>> isparent("foo/bar", "foo/bar/spam.txt")
True
>>> isparent("foo/bar/", "foo/bar")
True
>>> isparent("foo/barry", "foo/baz/bar")
False
>>> isparent("foo/bar/baz/", "foo/baz/bar")
False
fs.path.issamedir(path1: Text, path2: Text) → bool[source]

Check if two paths reference a resource in the same directory.

Parameters
  • path1 (str) – A PyFilesytem path.

  • path2 (str) – A PyFilesytem path.

Returns

True if the two resources are in the same directory.

Return type

bool

Example

>>> issamedir("foo/bar/baz.txt", "foo/bar/spam.txt")
True
>>> issamedir("foo/bar/baz/txt", "spam/eggs/spam.txt")
False
fs.path.iswildcard(path: Text) → bool[source]

Check if a path ends with a wildcard.

Parameters

path (str) – A PyFilesystem path.

Returns

True if path ends with a wildcard.

Return type

bool

Example

>>> iswildcard('foo/bar/baz.*')
True
>>> iswildcard('foo/bar')
False
fs.path.iteratepath(path: Text) → List[Text][source]

Iterate over the individual components of a path.

Parameters

path (str) – Path to iterate over.

Returns

A list of path components.

Return type

list

Example

>>> iteratepath('/foo/bar/baz')
['foo', 'bar', 'baz']
fs.path.join(*paths: Text) → Text[source]

Join any number of paths together.

Parameters

*paths (str) – Paths to join, given as positional arguments.

Returns

The joined path.

Return type

str

Example

>>> join('foo', 'bar', 'baz')
'foo/bar/baz'
>>> join('foo/bar', '../baz')
'foo/baz'
>>> join('foo/bar', '/baz')
'/baz'
fs.path.normpath(path: Text) → Text[source]

Normalize a path.

This function simplifies a path by collapsing back-references and removing duplicated separators.

Parameters

path (str) – Path to normalize.

Returns

A valid FS path.

Return type

str

Example

>>> normpath("/foo//bar/frob/../baz")
'/foo/bar/baz'
>>> normpath("foo/../../bar")
Traceback (most recent call last):
    ...
fs.errors.IllegalBackReference: path 'foo/../../bar' contains back-references outside of filesystem
fs.path.parts(path: Text) → List[Text][source]

Split a path in to its component parts.

Parameters

path (str) – Path to split in to parts.

Returns

List of components

Return type

list

Example

>>> parts('/foo/bar/baz')
['/', 'foo', 'bar', 'baz']
fs.path.recursepath(path: Text, reverse: bool = False) → List[Text][source]

Get intermediate paths from the root to the given path.

Parameters
  • path (str) – A PyFilesystem path

  • reverse (bool) – Reverses the order of the paths (default False).

Returns

A list of paths.

Return type

list

Example

>>> recursepath('a/b/c')
['/', '/a', '/a/b', '/a/b/c']
fs.path.relativefrom(base: Text, path: Text) → Text[source]

Return a path relative from a given base path.

Insert backrefs as appropriate to reach the path from the base.

Parameters
  • base (str) – Path to a directory.

  • path (str) – Path to make relative.

Returns

the path to base from path.

Return type

str

>>> relativefrom("foo/bar", "baz/index.html")
'../../baz/index.html'
fs.path.relpath(path: Text) → Text[source]

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 (str) – A path to adjust.

Returns

A relative path.

Return type

str

Example

>>> relpath('/a/b')
'a/b'
fs.path.split(path: Text) → Tuple[Text, Text][source]

Split 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 (str) – Path to split

Returns

a tuple containing the head and the tail of the path.

Return type

(str, str)

Example

>>> split("foo/bar")
('foo', 'bar')
>>> split("foo/bar/baz")
('foo/bar', 'baz')
>>> split("/foo/bar/baz")
('/foo/bar', 'baz')
fs.path.splitext(path: Text) → Tuple[Text, Text][source]

Split the extension from the path.

Parameters

path (str) – A path to split.

Returns

A tuple containing the path and the extension.

Return type

(str, str)

Example

>>> splitext('baz.txt')
('baz', '.txt')
>>> splitext('foo/bar/baz.txt')
('foo/bar/baz', '.txt')
>>> splitext('foo/bar/.foo')
('foo/bar/.foo', '')