mixing.egress

Canonical egress: route a produced result to its destination.

Across mixing, every result-producing function takes a single output parameter whose role is constant — “what to do with the result” — while its type is open:

output value

behavior

None

return the in-memory result (object producers) or save next to the input (file producers); see below

a file path

write the result there; return the Path

a directory

write with an auto-derived name; return the Path

a callable

return output(result) — the general escape hatch

There are two flavors of producer, modeled by two helpers:

  • deliver() — object-first: output=None returns the in-memory object (e.g. an Audio). Used by editing functions that build a value you may want to keep chaining.

  • write_egress() — file-first: output=None saves to a default path (typically beside the input) and returns it. Used by file→file operations whose whole point is to produce a file.

Both accept the same output forms, so callers learn one mental model. Output is the shared type alias.

Module Attributes

Output

nothing, a filesystem path/dir, or a result-consuming sink.

Functions

is_path_output(output)

True if output denotes a filesystem path (str / os.PathLike).

is_sink(output)

True if output is a result-consuming callable (not a path).

resolve_output_path(output, *, default_name)

Resolve a path/dir output to a concrete file Path (parents created).

deliver(result, output, *, write, default_name)

Object-first egress: route an in-memory result to output.

write_egress(output, *, default_path, write)

File-first egress: for operations whose primary effect is writing a file.
mixing.egress.Output

nothing, a filesystem path/dir, or a result-consuming sink.

Type:

An egress target

alias of None | str | os.PathLike[str] | Callable[[Any], Any]

mixing.egress.deliver(result, output, *, write, default_name)[source]

Object-first egress: route an in-memory result to output.

  • None → return result unchanged (no I/O).

  • sink callable → return output(result).

  • path/dir → write(result, path) then return the Path.

Parameters:

  • result (Any) – the produced in-memory value (e.g. an Audio).

  • output (Union[None, str, PathLike[str], Callable[[Any], Any]]) – the egress target (see module docstring).

  • write (Callable[[Any, Path], Any]) – write(result, path) persists result to path.

  • default_name (str) – filename to use when output is a directory.

Return type:

Any

mixing.egress.is_path_output(output)[source]

True if output denotes a filesystem path (str / os.PathLike).

Return type:

bool

mixing.egress.is_sink(output)[source]

True if output is a result-consuming callable (not a path).

Return type:

bool

mixing.egress.resolve_output_path(output, *, default_name)[source]

Resolve a path/dir output to a concrete file Path (parents created).

A directory output (existing, or with a trailing separator) is joined with default_name. Only call this when output is a path — not None and not a sink.

Return type:

Path

mixing.egress.write_egress(output, *, default_path, write)[source]

File-first egress: for operations whose primary effect is writing a file.

  • None → write to default_path (e.g. beside the input) and return it.

  • sink callable → write to default_path, then return output(path).

  • path/dir → write to that file (dir → default_path’s name inside it).

Parameters:
Return type:

Any