Skip to content

topmark.runtime.writer_options

topmark / runtime / writer_options

Persisted writer options loaded from TopMark TOML sources.

This module defines the non-layered writer preferences that may be authored in the same TOML document as layered TopMark configuration. These options are resolved separately from FrozenConfig and do not participate in config-layer merging.

WriterOptions dataclass 

WriterOptions(*, file_write_strategy=None)

Persisted writer preferences parsed from TOML.

Attributes:

Name Type Description
file_write_strategy FileWriteStrategy | None

Preferred file write strategy declared in the [writer] table. None means that the TOML source does not specify a writer preference.

apply_resolved_writer_options 

apply_resolved_writer_options(run_options, writer_options)

Overlay resolved persisted writer preferences onto runtime options.

Persisted writer preferences are applied only when the invocation has not already selected a conflicting execution-only output mode.

Precedence
  1. explicit runtime output routing (for example STDOUT)
  2. explicit runtime file write strategy
  3. resolved TOML writer preference
  4. otherwise keep the original runtime options unchanged

Parameters:

Name Type Description Default
run_options RunOptions

Execution-only runtime options for the current run.

 required
writer_options WriterOptions | None

Resolved persisted writer preferences, if any.

 required

Returns:

Type Description
RunOptions

Runtime options with the resolved writer preference applied when doing
RunOptions

so does not conflict with explicit runtime intent.
Source code in src/topmark/runtime/writer_options.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def apply_resolved_writer_options(
    run_options: RunOptions,
    writer_options: WriterOptions | None,
) -> RunOptions:
    """Overlay resolved persisted writer preferences onto runtime options.

    Persisted writer preferences are applied only when the invocation has not
    already selected a conflicting execution-only output mode.

    Precedence:
        1. explicit runtime output routing (for example STDOUT)
        2. explicit runtime file write strategy
        3. resolved TOML writer preference
        4. otherwise keep the original runtime options unchanged

    Args:
        run_options: Execution-only runtime options for the current run.
        writer_options: Resolved persisted writer preferences, if any.

    Returns:
        Runtime options with the resolved writer preference applied when doing
        so does not conflict with explicit runtime intent.
    """
    if writer_options is None or writer_options.file_write_strategy is None:
        return run_options

    if run_options.apply_changes is not True:
        return run_options

    if run_options.stdin_mode or run_options.output_target == OutputTarget.STDOUT:
        return run_options

    if run_options.file_write_strategy is not None:
        return run_options

    return replace(
        run_options,
        output_target=OutputTarget.FILE,
        file_write_strategy=writer_options.file_write_strategy,
    )

writer_options_to_toml_table 

writer_options_to_toml_table(writer_options)

Convert resolved writer options into a TopMark TOML table fragment.

Parameters:

Name Type Description Default
writer_options WriterOptions | None

The writer options to render as TOML.

 required

Returns:

Type Description
TomlTable

A TopMark TOML table fragment containing a [writer] section when
TomlTable

writer options are present, or an empty table otherwise.
Note

Export-only convenience for configuration dumps, documentation, and snapshots. Pairs with topmark.config.io.serializers.config_to_topmark_toml_table.

Source code in src/topmark/runtime/writer_options.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def writer_options_to_toml_table(
    writer_options: WriterOptions | None,
) -> TomlTable:
    """Convert resolved writer options into a TopMark TOML table fragment.

    Args:
        writer_options: The writer options to render as TOML.

    Returns:
        A TopMark TOML table fragment containing a `[writer]` section when
        writer options are present, or an empty table otherwise.

    Note:
        Export-only convenience for configuration dumps, documentation, and
        snapshots. Pairs with
        [topmark.config.io.serializers.config_to_topmark_toml_table][].
    """
    if writer_options is None:
        return {}

    writer_tbl: TomlTable = {}
    insert_if_present(
        writer_tbl,
        Toml.KEY_STRATEGY,
        writer_options.file_write_strategy,
    )

    if not writer_tbl:
        return {}

    return {Toml.SECTION_WRITER: writer_tbl}