Skip to content

topmark.presentation.shared.paths

topmark / presentation / shared / paths

Shared human-facing path presentation helpers.

This module contains frontend-neutral display helpers for path labels used by human-facing renderers. These helpers intentionally model presentation policy, not machine-readable path serialization.

get_display_path 

get_display_path(ctx)

Return the user-facing path to display for a processing result.

TopMark may process content-on-STDIN by writing it to a temporary file. In that mode, ProcessingContext.path points at the temporary file on disk, but users expect messages to refer to the logical filename supplied via --stdin-filename.

This helper centralizes that policy so all human-facing renderers display the same path labels.

Parameters:

Name Type Description Default
ctx ProcessingContext

Processing context to render.

 required

Returns:

Type Description
str

The logical filename in STDIN content mode, otherwise the actual file path.
Source code in src/topmark/presentation/shared/paths.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def get_display_path(
    ctx: ProcessingContext,
) -> str:
    """Return the user-facing path to display for a processing result.

    TopMark may process *content-on-STDIN* by writing it to a temporary file.
    In that mode, `ProcessingContext.path` points at the temporary file on disk,
    but users expect messages to refer to the logical filename supplied via
    `--stdin-filename`.

    This helper centralizes that policy so all human-facing renderers display
    the same path labels.

    Args:
        ctx: Processing context to render.

    Returns:
        The logical filename in STDIN content mode, otherwise the actual file path.
    """
    if ctx.run_options.stdin_mode and bool(ctx.run_options.stdin_filename):
        return ctx.run_options.stdin_filename
    return str(ctx.path)

render_path_display_text 

render_path_display_text(ctx)

Render a short TEXT path label for headings and guidance messages.

This helper formats get_display_path() for human-facing TEXT output and annotates STDIN-backed content with (via STDIN) when a synthetic filename is available.

Parameters:

Name Type Description Default
ctx ProcessingContext

Processing context containing the path to display.

 required

Returns:

Type Description
str

Short TEXT label for per-file headings and guidance messages.
Source code in src/topmark/presentation/shared/paths.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def render_path_display_text(ctx: ProcessingContext) -> str:
    """Render a short TEXT path label for headings and guidance messages.

    This helper formats
    [`get_display_path()`][topmark.presentation.shared.paths.get_display_path]
    for human-facing TEXT output and annotates STDIN-backed content with `(via STDIN)`
    when a synthetic filename is available.

    Args:
        ctx: Processing context containing the path to display.

    Returns:
        Short TEXT label for per-file headings and guidance messages.
    """
    path: str = get_display_path(ctx)
    if ctx.run_options.stdin_mode and bool(ctx.run_options.stdin_filename):
        return f"'{path}' (via STDIN)"

    return f"'{path}'"