Skip to content

topmark.utils.path

topmark / utils / path

Filesystem path utilities.

This module contains helpers for working with filesystem paths while preserving stable behavior across case-sensitive and case-insensitive filesystems.

canonicalize_existing_path 

canonicalize_existing_path(path)

Return a path using canonical filesystem casing.

The path is expected to exist and refer to a filesystem object.

The returned path refers to the same filesystem object as path but, on case-insensitive filesystems, uses the directory-entry spelling stored on disk rather than the spelling used by the caller.

Parameters:

Name Type Description Default
path Path

Existing filesystem path.

 required

Returns:

Type Description
Path

A path using canonical filesystem casing when it can be determined.
Source code in src/topmark/utils/path.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def canonicalize_existing_path(path: Path) -> Path:
    """Return a path using canonical filesystem casing.

    The path is expected to exist and refer to a filesystem object.

    The returned path refers to the same filesystem object as ``path`` but, on
    case-insensitive filesystems, uses the directory-entry spelling stored on
    disk rather than the spelling used by the caller.

    Args:
        path: Existing filesystem path.

    Returns:
        A path using canonical filesystem casing when it can be determined.
    """
    # The path must exist; `resolve(strict=True)` establishes filesystem identity
    # before reconstructing canonical directory-entry casing.
    resolved: Path = path.resolve(strict=True)

    parts: tuple[str, ...] = resolved.parts
    if not parts:
        return resolved

    current: Path = Path(parts[0])

    for part in parts[1:]:
        try:
            entry_name: str = next(
                (
                    candidate.name
                    for candidate in current.iterdir()
                    if candidate.name.casefold() == part.casefold()
                ),
                part,
            )
        except OSError:
            return resolved

        current = current / entry_name

    return current

canonical_processing_path 

canonical_processing_path(path)

Return the canonical processing path for an existing filesystem target.

Existing filesystem inputs are identified by their resolved processing target. Symlink spelling is therefore not preserved for processing identity or for generated filesystem-related header metadata.

Parameters:

Name Type Description Default
path Path

Existing filesystem path selected for processing.

 required

Returns:

Type Description
Path

The canonical processing path for the selected filesystem target.
Source code in src/topmark/utils/path.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def canonical_processing_path(path: Path) -> Path:
    """Return the canonical processing path for an existing filesystem target.

    Existing filesystem inputs are identified by their resolved processing
    target. Symlink spelling is therefore not preserved for processing identity
    or for generated filesystem-related header metadata.

    Args:
        path: Existing filesystem path selected for processing.

    Returns:
        The canonical processing path for the selected filesystem target.
    """
    return canonicalize_existing_path(path)

format_posix_path 

format_posix_path(path)

Return a POSIX-style string representation of a filesystem path.

Parameters:

Name Type Description Default
path Path

Path to serialize.

 required

Returns:

Type Description
str

POSIX-style path string.
Source code in src/topmark/utils/path.py 
86
87
88
89
90
91
92
93
94
95
def format_posix_path(path: Path) -> str:
    """Return a POSIX-style string representation of a filesystem path.

    Args:
        path: Path to serialize.

    Returns:
        POSIX-style path string.
    """
    return path.as_posix()

format_machine_path 

format_machine_path(path)

Serialize a filesystem path for machine-readable output.

All machine-readable TopMark payloads use POSIX separators on all platforms so JSON and NDJSON output remain stable across operating systems.

Parameters:

Name Type Description Default
path Path

Path to serialize.

 required

Returns:

Type Description
str

POSIX-style path string for machine-readable output.
Source code in src/topmark/utils/path.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def format_machine_path(path: Path) -> str:
    """Serialize a filesystem path for machine-readable output.

    All machine-readable TopMark payloads use POSIX separators on all platforms
    so JSON and NDJSON output remain stable across operating systems.

    Args:
        path: Path to serialize.

    Returns:
        POSIX-style path string for machine-readable output.
    """
    return format_posix_path(path)

format_header_metadata_path 

format_header_metadata_path(path)

Serialize a filesystem path for generated TopMark header metadata.

Header metadata is written into source files and should remain stable across operating systems. Use POSIX separators for relative and absolute path fields generated in TopMark headers.

Parameters:

Name Type Description Default
path Path

Path to serialize.

 required

Returns:

Type Description
str

POSIX-style path string for generated header metadata.
Source code in src/topmark/utils/path.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
def format_header_metadata_path(path: Path) -> str:
    """Serialize a filesystem path for generated TopMark header metadata.

    Header metadata is written into source files and should remain stable across
    operating systems. Use POSIX separators for relative and absolute path
    fields generated in TopMark headers.

    Args:
        path: Path to serialize.

    Returns:
        POSIX-style path string for generated header metadata.
    """
    return format_posix_path(path)

format_config_source_path 

format_config_source_path(source)

Format real and synthetic config source identifiers for TOML export.

Synthetic config sources use bracketed identifiers such as <built-in topmark defaults>. These should remain stable identifiers in exported output rather than being normalized relative to the current working directory.

Parameters:

Name Type Description Default
source Path | SyntheticConfigSource

Real filesystem path or synthetic config source identifier.

 required

Returns:

Type Description
str

POSIX-style path string for real filesystem paths, or the stable label
str

for synthetic config sources.
Source code in src/topmark/utils/path.py 
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def format_config_source_path(source: Path | SyntheticConfigSource) -> str:
    """Format real and synthetic config source identifiers for TOML export.

    Synthetic config sources use bracketed identifiers such as
    `<built-in topmark defaults>`. These should remain stable identifiers in
    exported output rather than being normalized relative to the current working
    directory.

    Args:
        source: Real filesystem path or synthetic config source identifier.

    Returns:
        POSIX-style path string for real filesystem paths, or the stable label
        for synthetic config sources.
    """
    return source.label if isinstance(source, SyntheticConfigSource) else format_posix_path(source)