labapi.util.path.NotebookPath#

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

Bases: Sequence[str]

A structured path referencing a location in the notebook tree.

Behaves like a sequence of path segments (strings) and supports Unix-style path semantics including absolute/relative paths and .. parent navigation.

Paths can be constructed from a tree node, another NotebookPath, or raw slash-separated strings. Segments are normalised on construction: empty segments and . are discarded, and .. collapses the preceding segment (or is kept literally when at the root of a relative path).

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 | str, *parts: str, parent: NotebookPath | AbstractBaseTreeNode | None = None, )[source]#

Construct a NotebookPath.

The first argument part sets the base of the path; any additional positional parts are appended as extra segments.

Parameters:

part – The base of the path. Pass a tree node to create an absolute path rooted at that node’s location, a NotebookPath to extend it, or a slash-separated string (absolute strings start with /; others are relative).
parts – Additional slash-separated path segments appended after part. Segments are split on / and normalised.
parent – An absolute path (or node) that anchors a relative string path for later resolution. Must be absolute.

Raises:

PathError – If parent is not absolute.

Methods

`__init__`(part, *parts[, parent])	Construct a `NotebookPath`.
`count`(value)
`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`()	Return the path as a slash-separated string.

Attributes

`name`	The final segment of the path.
`parent`	The parent path (all segments except the last).
`parts`	All path segments except the last one.

to_string() → str[source]#

Return the path as a slash-separated string.

Absolute paths are prefixed with /; relative paths are not.

Returns:: The string representation of this path (e.g. "/Experiments/2024" or "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: str#

The final segment of the path.

Equivalent to the node’s display name when the path was built from a tree node. Returns "." for an empty path.

Returns:: The last path segment, or "." if the path is empty.

property parts: Sequence[str]#

All path segments except the last one.

Analogous to the parent directory in a file path.

Returns:: A sequence of segment strings, empty if the path has only one segment.

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.