Skylib module containing file path manipulation functions.

NOTE: The functions in this module currently only support paths with Unix-style path separators (forward slash, "/"); they do not handle Windows-style paths with backslash separators or drive letters.

Macros and Functions

paths.basename

Returns the basename (i.e., the file portion) of a path.

Note that if p ends with a slash, this function returns an empty string. This matches the behavior of Python's os.path.basename, but differs from the Unix basename command (which would return the path segment preceding the final slash).

Example usage (generated)

load("@bazel_skylib//lib:paths.bzl", "paths")

paths.basename(
    # The path whose basename should be returned.
    p = None,
)

p

The path whose basename should be returned.


paths.dirname

Returns the dirname of a path.

The dirname is the portion of p up to but not including the file portion (i.e., the basename). Any slashes immediately preceding the basename are not included, unless omitting them would make the dirname empty.

Example usage (generated)

load("@bazel_skylib//lib:paths.bzl", "paths")

paths.dirname(
    # The path whose dirname should be returned.
    p = None,
)

p

The path whose dirname should be returned.


paths.is_absolute

Returns True if path is an absolute path.

Example usage (generated)

load("@bazel_skylib//lib:paths.bzl", "paths")

paths.is_absolute(
    # A path (which is a string).
    path = None,
)

path

A path (which is a string).


paths.join

Joins one or more path components intelligently.

This function mimics the behavior of Python's os.path.join function on POSIX platform. It returns the concatenation of path and any members of others, inserting directory separators before each component except the first. The separator is not inserted if the path up until that point is either empty or already ends in a separator.

If any component is an absolute path, all previous components are discarded.

Example usage (generated)

load("@bazel_skylib//lib:paths.bzl", "paths")

paths.join(
    # A path segment.
    path = None,
)

path

A path segment.

others

Additional path segments.


paths.normalize

Normalizes a path, eliminating double slashes and other redundant segments.

This function mimics the behavior of Python's os.path.normpath function on POSIX platforms; specifically:

  • If the entire path is empty, "." is returned.
  • All "." segments are removed, unless the path consists solely of a single "." segment.
  • Trailing slashes are removed, unless the path consists solely of slashes.
  • ".." segments are removed as long as there are corresponding segments earlier in the path to remove; otherwise, they are retained as leading ".." segments.
  • Single and double leading slashes are preserved, but three or more leading slashes are collapsed into a single leading slash.
  • Multiple adjacent internal slashes are collapsed into a single slash.

Example usage (generated)

load("@bazel_skylib//lib:paths.bzl", "paths")

paths.normalize(
    # A path.
    path = None,
)

path

A path.


paths.relativize

Returns the portion of path that is relative to start.

Because we do not have access to the underlying file system, this implementation differs slightly from Python's os.path.relpath in that it will fail if path is not beneath start (rather than use parent segments to walk up to the common file system root).

Relativizing paths that start with parent directory references only works if the path both start with the same initial parent references.

Example usage (generated)

load("@bazel_skylib//lib:paths.bzl", "paths")

paths.relativize(
    # The path to relativize.
    path = None,
    # The ancestor path against which to relativize.
    start = None,
)

path

The path to relativize.

start

The ancestor path against which to relativize.


paths.replace_extension

Replaces the extension of the file at the end of a path.

If the path has no extension, the new extension is added to it.

Example usage (generated)

load("@bazel_skylib//lib:paths.bzl", "paths")

paths.replace_extension(
    # The path whose extension should be replaced.
    p = None,
    # The new extension for the file
    new_extension = None,
)

p

The path whose extension should be replaced.

new_extension

The new extension for the file. The new extension should begin with a dot if you want the new filename to have one.


paths.split_extension

Splits the path p into a tuple containing the root and extension.

Leading periods on the basename are ignored, so path.split_extension(".bashrc") returns (".bashrc", "").

Example usage (generated)

load("@bazel_skylib//lib:paths.bzl", "paths")

paths.split_extension(
    # The path whose root and extension should be split.
    p = None,
)

p

The path whose root and extension should be split.