labapi.util.path.NotebookPath#

class labapi.util.path.NotebookPath(
part: NotebookPath | AbstractBaseTreeNode | EscapedSegment,
*parts: EscapedSegment,
parent: NotebookPath | AbstractBaseTreeNode | None = None,
)[source]#

Bases: Sequence[UnescapedSegment]

A structured path referencing a location in the notebook tree.

Supports absolute and relative paths, plus .. parent navigation.

Empty segments and . are discarded; .. collapses the preceding segment, or is kept at the root of a relative path.

If a node name contains a literal /, write it as \/ in a path string, e.g. r"Reports\/2024". Iteration, indexing, name, and parts return node names. str() adds escapes back so the result can be parsed again.

Examples:

# From a tree node (always absolute)
path = NotebookPath(folder)             # e.g. /Experiments/2024

# From a string
path = NotebookPath("/Experiments/2024")  # absolute
path = NotebookPath("2024/Results")        # relative

# Combine with /
path = NotebookPath(notebook) / "Experiments" / "2024"
__init__(
part: NotebookPath | AbstractBaseTreeNode | EscapedSegment,
*parts: EscapedSegment,
parent: NotebookPath | AbstractBaseTreeNode | None = None,
)[source]#

Construct a NotebookPath.

Additional parts are appended to part.

Parameters:

  • part – A tree node creates an absolute path, a NotebookPath is copied, and a string is parsed as path syntax.

  • parts – Additional path strings appended after part. / separates segments unless it is escaped as \/.

  • parent – Absolute path or node used later to resolve a relative string path. Must be absolute.

Raises:

PathError – If parent is not absolute.

Methods

__init__(part, *parts[, parent])

Construct a NotebookPath.

count(value)

escape(*parts)

Add path escapes.

index(value, [start, [stop]])

Raises ValueError if the value is not present.

is_absolute()

Return whether this path is absolute.

is_relative_to(other)

Return whether this path is located inside other.

relative_to(other)

Return this path made relative to other.

resolve([parent, recurse])

Return an absolute version of this path.

startswith(other)

Return whether this path starts with another path's segments.

to_string([escape])

Return the path as a slash-separated string.

unescape(part)

Remove path escapes.

Attributes

name

The final node name.

parent

The parent path (all segments except the last).

parts

All node names except the last one.
static escape(
*parts: UnescapedSegment,
) → tuple[EscapedSegment, ...][source]#

Add path escapes.

static unescape(
part: EscapedSegment,
) → UnescapedSegment[source]#

Remove path escapes.

to_string(escape=False) → str[source]#

Return the path as a slash-separated string.

By default, names are joined as-is. Pass escape=True to match str(path).

Returns:

Examples include "/Experiments/2024" and "2024/Results".

is_absolute() → bool[source]#

Return whether this path is absolute.

An absolute path is rooted at the notebook level and begins with / in its string form.

Returns:

True if the path is absolute, False if relative.

resolve(
parent: NotebookPath | None = None,
recurse: bool = False,
) → NotebookPath[source]#

Return an absolute version of this path.

If the path is already absolute it is returned unchanged. Otherwise the path is resolved against parent (if given) or against the parent anchor stored at construction time.

Parameters:

  • parent – An absolute path to resolve against. Ignored when the path is already absolute or has a stored parent anchor.

  • recurse – If True, parent itself is resolved before use.

Returns:

A new absolute NotebookPath.

Raises:

PathError – If the path is relative and no parent is available to resolve against.

startswith(
other: NotebookPath,
) → bool[source]#

Return whether this path starts with another path’s segments.

Compares raw segments without resolving either path.

Parameters:

other – The prefix path to test against.

Returns:

True if the leading segments of this path equal all segments of other.

is_relative_to(
other: NotebookPath | AbstractBaseTreeNode,
) → bool[source]#

Return whether this path is located inside other.

Unanchored relative paths are considered to be relative to any absolute path.

Parameters:

other – The candidate ancestor path or tree node.

Returns:

True if this path is equal to or below other.

relative_to(
other: NotebookPath | AbstractBaseTreeNode,
) → NotebookPath[source]#

Return this path made relative to other.

The result is a new relative NotebookPath whose parent anchor is set to the resolved form of other, so it can be resolved back to an absolute path later.

Parameters:

other – The ancestor path or tree node to relativise against.

Returns:

A relative NotebookPath from other to this path.

Raises:

PathError – If this path is not located inside other.

property name: UnescapedSegment#

The final node name.

Returns "." for an empty path.

property parts: Sequence[UnescapedSegment]#

All node names except the last one.

Analogous to the parent directory in a file path.

property parent: NotebookPath#

The parent path (all segments except the last).

Resolves the path first, then appends .. to obtain the parent.

Returns:

An absolute NotebookPath pointing to the parent location.

count(
value,
) → integer -- return number of occurrences of value#
index(
value[,
start[,
stop,]]
) → integer -- return first index of value.#

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.