`os.path`

import os

Everything here is re-exported by os, so import os is enough and the names are called as os.*. Importing os.path on its own works too and reaches the same definitions.

Path string manipulation: joining, resolving, and comparing paths. Nothing in this file touches the filesystem except where explicitly documented (real_path(), and abs_path()’s optional strict mode): everything else here is pure string handling, so it works the same whether or not the path in question actually exists.

Functions

`join_paths()`

os.join_paths(...paths: list) -> string

Concatenates the given paths together into a format that is valid on the current operating system.

Example,

%> os.join_paths('/home/user', 'path/to/myfile.ext')
'/home/user/path/to/myfile.ext'

Parameters

string... — paths

Returns string

`real_path()`

os.real_path(path: string) -> string

Returns the original path to a relative path.

Parameters

path (string)

Returns string

Note: if the path is a file, see abs_path().

`abs_path()`

os.abs_path(path: string, strict: ?bool) -> string

Returns the absolute form of path: relative paths are resolved against the current working directory, and “.” / “..” segments are collapsed: purely as string manipulation, with no filesystem access at all by default. Unlike real_path(), this works even when path (or any part of it) doesn’t exist on disk, and it never resolves symbolic links; use real_path() when you need the true canonical path of something that already exists.

On Windows, a path that starts at a root without naming a drive, such as \\srv\\app or /srv/app, is on the working directory’s drive, and a UNC path such as \\\\server\\share\\app keeps \\\\server\\share as its root, which .. never climbs out of.

Parameters

path (string)
strict (?bool) — Default false. When true, the resolved path is checked against the filesystem and an Error is raised if nothing exists there.

Returns string

`dir_name()`

os.dir_name(path: string) -> string

Returns the parent directory of the pathname pointed to by path. Any trailing / characters are not counted as part of the directory name. If path is an empty string, or contains no / characters, dir_name() returns the string “.”, signifying the current directory.

On Windows, a drive (C:) or UNC share (\\\\server\\share) at the start of path stays whole: the parent of C:\\ is C:\\ itself, the parent of C:\\work is C:\\, and the parent of C:work is C:. The root’s parent is the root, just as / is its own parent elsewhere, so a loop that walks up until the parent stops changing ends there.

Parameters

path (string)

Returns string

`base_name()`

os.base_name(path: string) -> string

The base_name() function returns the last component from the pathname pointed to by path, deleting any trailing / characters. If path consists entirely of / characters, the string ‘/’ is returned. If path is an empty string, the string ‘.’ is returned.

Parameters

path (string)

Returns string

`relative_path()`

os.relative_path(base: string, target: string) -> string

Returns the relative path from base to target: the shortest ./..-based path such that, starting inside base, following it lands on target. Both arguments are first resolved with abs_path(), so neither has to already be absolute or exist on disk.

Example,

%> os.relative_path('/home/user/project', '/home/user/project/src/main.zu')
'src/main.zu'
%> os.relative_path('/home/user/project/src', '/home/user/other/lib.zu')
'../../other/lib.zu'
%> os.relative_path('/home/user/project', '/home/user/project')
'.'

Parameters

base (string)
target (string)

Returns string

`expand_user()`

os.expand_user(path: string) -> string

Expands a leading ~ in path into the current user’s home directory, the same way a shell would before running a command. A bare ~ and a ~/...-prefixed path are both expanded; a path that doesn’t start with ~ is returned unchanged.

Parameters

path (string)

Returns string

Note: expanding another user’s home directory (~other_user/...) isn’t supported; a path in that form is returned unchanged, the same fallback Python’s os.path.expanduser uses when it can’t resolve one either.

`path_contains()`

os.path_contains(base: string, candidate: string) -> bool

Returns true if the resolved form of candidate is base itself or lies somewhere underneath it, and false otherwise. This includes when candidate escapes base via .. segments. Both paths are resolved with abs_path() first, so relative paths and mixed separators are handled the same way abs_path() itself handles them.

Example,

%> os.path_contains('/home/user/project', '/home/user/project/src/main.zu')
true
%> os.path_contains('/home/user/project', '/home/user/project/../../etc/passwd')
false

Parameters