API

Warning

The Python API for Mimeogram is currently unofficial and should be considered unstable. The package is primarily intended for use as a command-line tool. Any direct use of the Python modules may break without warning in future versions.

Package mimeogram

A toolkit for exchanging collections of files with Large Language Models (LLMs). Mimeogram bundles multiple files into a single clipboard-ready document while preserving directory structure and metadata, making it ideal for code reviews, project sharing, and LLM interactions.

Module mimeogram.acquirers

Content acquisition from various sources.

async mimeogram.acquirers.acquire(auxdata: Globals, sources: Sequence[str | Path]) → Sequence[Part]

Acquires content from multiple sources.

Module mimeogram.apply

Application of mimeograms.

class mimeogram.apply.Command(*, source: ~typing.Annotated[str, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Source file for mimeogram. Defaults to stdin if '--clip' not specified., help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None)] = '-', clip: ~typing.Annotated[bool | None, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Read mimeogram from clipboard instead of file or stdin., help_behavior_hint=None, aliases=('--clipboard', '--from-clipboard'), prefix_name=None, constructor_factory=None)] | None = None, mode: ~typing.Annotated[~mimeogram.updaters.ReviewModes | None, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Controls how changes are reviewed. 'silent': Apply without review. 'partitive': Review each change interactively. Partitive, if not specified and on a terminal. Silent, if not specified and not on a terminal., help_behavior_hint=None, aliases=('--review-mode', ), prefix_name=None, constructor_factory=None)] | None = None, base: ~typing.Annotated[~pathlib.Path | None, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Base directory for relative locations. Defaults to current working directory., help_behavior_hint=None, aliases=('--base-directory', ), prefix_name=None, constructor_factory=None)] | None = None, force: ~typing.Annotated[bool | None, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Override protected path checks., help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None)] | None = None)

Bases: CliCommand

Applies mimeogram to filesystem locations.

provide_configuration_edits() → Iterable[Edit]

Provides edits against configuration from options.

base: , help_behavior_hint=None, aliases=('--base-directory',), prefix_name=None, constructor_factory=None)]

clip: , help_behavior_hint=None, aliases=('--clipboard', '--from-clipboard'), prefix_name=None, constructor_factory=None)]

force: , help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None)]

mode: , help_behavior_hint=None, aliases=('--review-mode',), prefix_name=None, constructor_factory=None)]

source: , help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None)]

class mimeogram.apply.ContentAcquirer(*args, **kwargs)

Bases: Protocol

Acquires content for apply command.

abstract async acquire_clipboard() → str

Acquires content from clipboard.

abstract async acquire_file(path: str | Path) → str

Acquires content from file.

abstract async acquire_stdin() → str

Acquires content from standard input.

abstract stdin_is_tty() → bool

Checks if input is from a terminal.

class mimeogram.apply.StandardContentAcquirer

Bases: ContentAcquirer

Standard implementation of content acquisition.

async acquire_clipboard() → str

Acquires content from clipboard.

async acquire_file(path: str | Path) → str

Acquires content from file.

async acquire_stdin() → str

Acquires content from standard input.

stdin_is_tty() → bool

Checks if input is from a terminal.

async mimeogram.apply.apply(auxdata: Globals, command: Command, *, acquirer: ContentAcquirer | AbsentSingleton = absence.absent, parser: Callable[[str], Sequence[Part]] | AbsentSingleton = absence.absent, updater: Callable[[Globals, Sequence[Part], ReviewModes], Coroutine[None, None, None]] | AbsentSingleton = absence.absent) → Never

Applies mimeogram.

Module mimeogram.cli

Command-line interface.

class mimeogram.cli.Cli(*, application: ~mimeogram.__.application.Information, configfile: str | None = None, inscription: ~mimeogram.__.inscription.Control = Control(mode=<Modes.Rich: 'rich'>, level=None), command: ~mimeogram.create.Annotated[~mimeogram.create.Command, ~tyro.conf._confstruct._SubcommandConfig(name=create, default=<tyro._singleton.NonpropagatingMissingType object at 0x7f8bdee5a380>, description=None, prefix_name=False, constructor_factory=None)] | ~mimeogram.apply.Annotated[~mimeogram.apply.Command, ~tyro.conf._confstruct._SubcommandConfig(name=apply, default=<tyro._singleton.NonpropagatingMissingType object at 0x7f8bdee5a380>, description=None, prefix_name=False, constructor_factory=None)] | ~mimeogram.prompt.Annotated[~mimeogram.prompt.Command, ~tyro.conf._confstruct._SubcommandConfig(name=provide-prompt, default=<tyro._singleton.NonpropagatingMissingType object at 0x7f8bdee5a380>, description=None, prefix_name=False, constructor_factory=None)] | ~mimeogram.cli.Annotated[~mimeogram.cli.VersionCommand, ~tyro.conf._confstruct._SubcommandConfig(name=version, default=<tyro._singleton.NonpropagatingMissingType object at 0x7f8bdee5a380>, description=None, prefix_name=False, constructor_factory=None)])

Bases: object

Mimeogram: hierarchical data exchange between humans and LLMs.

prepare_invocation_args() → Mapping[str, Any]

Prepares arguments for initial configuration.

application: Information

command: NonpropagatingMissingType object at 0x7f8bdee5a380>, description=None, prefix_name=False, constructor_factory=None)]

configfile: str | None

inscription: Control

class mimeogram.cli.VersionCommand

Bases: CliCommand

Prints version information.

provide_configuration_edits() → Iterable[Edit]

Provides edits against configuration from options.

mimeogram.cli.execute()

Entrypoint for CLI execution.

Module mimeogram.create

Creation of mimeograms.

class mimeogram.create.Command(*, sources: ~typing.Annotated[list[str], Positional, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Filesystem locations or URLs., help_behavior_hint=None, aliases=None, prefix_name=False, constructor_factory=None)], clip: ~typing.Annotated[bool | None, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Copy mimeogram to clipboard., help_behavior_hint=None, aliases=('--clipboard', '--to-clipboard'), prefix_name=None, constructor_factory=None)] | None = None, edit: ~typing.Annotated[bool, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Spawn editor to capture an introductory message., help_behavior_hint=None, aliases=('-e', '--edit-message'), prefix_name=None, constructor_factory=None)] = False, prepend_prompt: ~typing.Annotated[bool, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Prepend mimeogram format instructions., help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None)] = False, recurse: ~typing.Annotated[bool | None, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Recurse into directories., help_behavior_hint=None, aliases=('-r', '--recurse-directories', '--recursive'), prefix_name=None, constructor_factory=None)] | None = None, strict: ~typing.Annotated[bool | None, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Fail on invalid contents? True, fail. False, skip., help_behavior_hint=None, aliases=('--fail-on-invalid',), prefix_name=None, constructor_factory=None)] | None = None)

Bases: CliCommand

Creates mimeogram from filesystem locations or URLs.

provide_configuration_edits() → Iterable[Edit]

Provides edits against configuration from options.

clip: , help_behavior_hint=None, aliases=('--clipboard', '--to-clipboard'), prefix_name=None, constructor_factory=None)]

edit: , help_behavior_hint=None, aliases=('-e', '--edit-message'), prefix_name=None, constructor_factory=None)]

prepend_prompt: , help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None)]

recurse: , help_behavior_hint=None, aliases=('-r', '--recurse-directories', '--recursive'), prefix_name=None, constructor_factory=None)]

sources: , help_behavior_hint=None, aliases=None, prefix_name=False, constructor_factory=None)]

strict: , help_behavior_hint=None, aliases=('--fail-on-invalid',), prefix_name=None, constructor_factory=None)]

async mimeogram.create.create(auxdata: ~mimeogram.__.state.Globals, command: ~mimeogram.create.Command, *, editor: ~collections.abc.Callable[[], ~collections.abc.Coroutine[None, None, str]] = <function _edit_message>, clipcopier: ~collections.abc.Callable[[str], ~collections.abc.Coroutine[None, None, None]] = <function _copy_to_clipboard>, prompter: ~collections.abc.Callable[[~mimeogram.__.state.Globals], ~collections.abc.Coroutine[None, None, str]] = <function _acquire_prompt>) → Never

Creates mimeogram.

Module mimeogram.differences

Content differences management.

class mimeogram.differences.ConsoleDisplay(*, context_lines: int = 3, inline_threshold: int = 24)

Bases: DifferencesDisplay

Default display of differences to console.

context_lines: int

inline_threshold: int

class mimeogram.differences.ConsoleInteractor(*args, **kwargs)

Bases: DifferencesInteractor

Default console-based interaction handler.

async mimeogram.differences.select_segments(target: Target, revision: str, display: DifferencesDisplay | AbsentSingleton = absence.absent, interactor: DifferencesInteractor | AbsentSingleton = absence.absent) → str

Selects which diff hunks to apply.

Module mimeogram.display

System pager interaction.

mimeogram.display.discover_pager() → Callable[[str], None]

Discovers pager and returns executor function.

mimeogram.display.display_content(content: str, *, suffix: str = '.txt', pager_discoverer: ~collections.abc.Callable[[], ~collections.abc.Callable[[str], None]] = <function discover_pager>) → None

Displays content via discovered pager.

Module mimeogram.edit

System editor interaction.

mimeogram.edit.discover_editor() → Callable[[str], str]

Discovers editor and returns executor function.

mimeogram.edit.edit_content(content: str = '', *, suffix: str = '.md', editor_discoverer: ~collections.abc.Callable[[], ~collections.abc.Callable[[str], str]] = <function discover_editor>) → str

Edits content via discovered editor.

Module mimeogram.exceptions

Family of exceptions for package API.

• Omniexception: Base for all package exceptions

• Omnierror: Base for all package errors

exception mimeogram.exceptions.ContentAcquireFailure(location: str | Path)

Bases: Omnierror

Failure to acquire content from location.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.ContentDecodeFailure(location: str | Path, charset: str)

Bases: Omnierror

Failure to decode content as character set from location.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.ContentUpdateFailure(location: str | Path)

Bases: Omnierror

Failure to update content at location.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.DifferencesProcessFailure(reason: str)

Bases: Omnierror

Failure during diff processing.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.EditorFailure(cause: str | Exception)

Bases: Omnierror

Failure while operating editor.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.LocationInvalidity(location: str | Path)

Bases: Omnierror

Invalid location.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.MimeogramFormatEmpty

Bases: Omnierror

Attempt to format empty mimeogram.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.MimeogramParseFailure(reason: str)

Bases: Omnierror

Failure to parse mimeogram content.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.Omnierror

Bases: Omniexception, Exception

Base for error exceptions raised by package API.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.Omniexception

Bases: BaseException

Base for all exceptions raised by package API.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.PagerFailure(cause: str | Exception)

Bases: Omnierror

Failure while operating pager.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.ProgramAbsenceError(species: str)

Bases: Omnierror

Could not discover valid editor.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.TextualMimetypeInvalidity(location: str | Path, mimetype: str)

Bases: Omnierror

Invalid textual MIME type for content at location.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.UrlSchemeNoSupport(url: str)

Bases: Omnierror

Unsupported URL scheme.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.exceptions.UserOperateCancellation(cause: BaseException)

Bases: Omniexception

Operation cancelled by user.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

Module mimeogram.formatters

Formatting of mimeogram bundles.

mimeogram.formatters.format_mimeogram(parts: Sequence[Part], message: str | None = None) → str

Formats parts into mimeogram.

mimeogram.formatters.format_part(part: Part, boundary: str) → str

Formats part with boundary marker and headers.

Module mimeogram.interactions

User interactions and automations.

class mimeogram.interactions.GenericInteractor(*, prompter: ~collections.abc.Callable[[~mimeogram.parts.Target, str, bool], str] = <function _prompt_action>, cdisplayer: ~collections.abc.Callable[[~mimeogram.parts.Target, str], ~collections.abc.Coroutine[None, None, None]] = <function _display_content>, ddisplayer: ~collections.abc.Callable[[~mimeogram.parts.Target, str], ~collections.abc.Coroutine[None, None, None]] = <function _display_differences>, editor: ~collections.abc.Callable[[~mimeogram.parts.Target, str], ~collections.abc.Coroutine[None, None, str]] = <function _edit_content>, sselector: ~collections.abc.Callable[[~mimeogram.parts.Target, str], ~collections.abc.Coroutine[None, None, str]] = <function _select_segments>, validator: ~collections.abc.Callable[[~mimeogram.parts.Target, str], None] = <function _validate_choice>)

Bases: PartInteractor

Default console-based interaction handler.

cdisplayer: Callable[[Target, str], Coroutine[None, None, None]]

ddisplayer: Callable[[Target, str], Coroutine[None, None, None]]

editor: Callable[[Target, str], Coroutine[None, None, str]]

prompter: Callable[[Target, str, bool], str]

sselector: Callable[[Target, str], Coroutine[None, None, str]]

validator: Callable[[Target, str], None]

async mimeogram.interactions.interact(target: Target, interactor: PartInteractor | AbsentSingleton = absence.absent) → tuple[Resolutions, str]

Performs interaction for part.

Module mimeogram.interfaces

Abstract bases and interfaces.

class mimeogram.interfaces.CliCommand(*args, **kwargs)

Bases: Protocol

CLI command.

abstract provide_configuration_edits() → Iterable[Edit]

Provides edits against configuration from options.

class mimeogram.interfaces.DifferencesDisplay(*args, **kwargs)

Bases: Protocol

Configuration for content differences display.

context_lines: int

inline_threshold: int

class mimeogram.interfaces.DifferencesInteractor(*args, **kwargs)

Bases: Protocol

Interactions with content differences.

class mimeogram.interfaces.PartInteractor(*args, **kwargs)

Bases: Protocol

Interactions with mimeogram parts.

Module mimeogram.parsers

Parsers for mimeograms and their constituents.

mimeogram.parsers.parse(mgtext: str) → Sequence[Part]

Parses mimeogram.

mimeogram.parsers.parse_part(ptext: str) → Part

Parses mimeogram part.

Module mimeogram.parts

Mimeogram parts.

class mimeogram.parts.LineSeparators(value)

Bases: Enum

Line separators for various platforms.

classmethod detect_bytes(content: bytes, limit=1024) → LineSeparators | None

Detects newline characters in bytes array.

nativize(content: str) → str

Nativizes specific variety newline characters in text.

normalize(content: str) → str

Normalizes specific variety newline characters in text.

classmethod normalize_universal(content: str) → str

Normalizes all varieties of newline characters in text.

CR = '\r'

CRLF = '\r\n'

LF = '\n'

class mimeogram.parts.Part(*, location: str, mimetype: str, charset: str, linesep: LineSeparators, content: str)

Bases: object

Part of mimeogram.

charset: str

content: str

linesep: LineSeparators

location: str

mimetype: str

class mimeogram.parts.Resolutions(value)

Bases: Enum

Available resolutions for each part.

Apply = 'apply'

Ignore = 'ignore'

class mimeogram.parts.Target(*, part: Part, destination: Path, protection: Status)

Bases: object

Target information for mimeogram part.

destination: Path

part: Part

protection: Status

Module mimeogram.prompt

Mimeogram prompt text for LLMs.

class mimeogram.prompt.Command(*, clip: ~typing.Annotated[bool | None, ~tyro.conf._confstruct._ArgConfig(name=None, metavar=None, help=Copy prompt to clipboard., help_behavior_hint=None, aliases=('--clipboard', '--to-clipboard'), prefix_name=None, constructor_factory=None)] | None = None)

Bases: CliCommand

Provides LLM prompt text for mimeogram format.

provide_configuration_edits() → Iterable[Edit]

Provides edits against configuration from options.

clip: , help_behavior_hint=None, aliases=('--clipboard', '--to-clipboard'), prefix_name=None, constructor_factory=None)]

async mimeogram.prompt.acquire_prompt(auxdata: Globals) → str

Acquires prompt text from package data.

async mimeogram.prompt.provide_prompt(auxdata: Globals) → None

Provides mimeogram prompt text.

Module mimeogram.updaters

File content updates.

class mimeogram.updaters.Queue(*, updates: list[tuple[~mimeogram.parts.Part, ~pathlib.Path, str]] = <factory>, reverter: ~mimeogram.updaters.Reverter = <factory>)

Bases: object

Manages queued file updates for batch application.

async apply() → None

Applies all queued updates with parallel async fanout.

enqueue(part: Part, target: Path, content: str) → None

Adds a file update to queue.

reverter: Reverter

updates: list[tuple[Part, Path, str]]

class mimeogram.updaters.Reverter(*, originals: dict[~pathlib.Path, str] = <factory>, revisions: list[~pathlib.Path] = <factory>)

Bases: object

Backup and restore filesystem state.

async restore() → None

Restores files to original contents in reverse order.

async save(part: Part, path: Path) → None

Saves original file content if it exists.

originals: dict[Path, str]

revisions: list[Path]

class mimeogram.updaters.ReviewModes(value)

Bases: Enum

Controls how updates are reviewed and applied.

Partitive = 'partitive'

Silent = 'silent'

async mimeogram.updaters.update(auxdata: Globals, parts: Sequence[Part], mode: ReviewModes, base: Path | AbsentSingleton = absence.absent, interactor: PartInteractor | AbsentSingleton = absence.absent, protector: Protector | AbsentSingleton = absence.absent) → None

Updates filesystem locations from mimeogram.

async mimeogram.updaters.update_part(auxdata: Globals, target: Target, mode: ReviewModes, interactor: PartInteractor | AbsentSingleton = absence.absent) → tuple[Resolutions, str]

Updates filesystem location from mimeogram part.

Package mimeogram.fsprotect

A subpackage providing filesystem protection features to prevent dangerous modifications to sensitive paths.

Module mimeogram.fsprotect.cache

Cache for filesystem protection checks.

class mimeogram.fsprotect.cache.Cache(*, rules: dict[Reasons, Rule], defaults_disablement: frozenset[str], rules_supercession: Dictionary[Path, tuple[frozenset[str], frozenset[str]]])

Bases: Protector

Cache of protected paths and patterns for platform.

classmethod from_configuration(auxdata: Globals) → Cache

Initializes protection cache for current platform.

verify(path: Path) → Status

Verifies if a path should be protected using cached data.

defaults_disablement: frozenset[str]

rules: dict[Reasons, Rule]

rules_supercession: Dictionary[Path, tuple[frozenset[str], frozenset[str]]]

class mimeogram.fsprotect.cache.Rule(*, paths: frozenset[Path], patterns: frozenset[str] = frozenset({}))

Bases: object

Rule for path protection.

paths: frozenset[Path]

patterns: frozenset[str]

mimeogram.fsprotect.cache.discover_platform_locations(auxdata: Globals, rules: dict[Reasons, Rule]) → None

Discovers system and user locations based on platform.

mimeogram.fsprotect.cache.provide_credentials_locations(rules: dict[Reasons, Rule]) → None

Provides common locations for credentials and other secrets.

mimeogram.fsprotect.cache.provide_project_locations(rules: dict[Reasons, Rule]) → None

Provides IDE and VCS locations relative to project.

Module mimeogram.fsprotect.core

Core entities for filesystem protection.

class mimeogram.fsprotect.core.Protector(*args, **kwargs)

Bases: Protocol

Filesystem protection checker.

abstract verify(path: Path) → Status

Verifies if a path should be protected.

class mimeogram.fsprotect.core.Reasons(value)

Bases: Enum

Reasons why location may be protected.

Concealment = 'Hidden file or directory'

Credentials = 'Credentials or secrets location'

CustomAddition = 'User-specified custom location'

OsDirectory = 'Operating system directory'

PlatformSensitive = 'Platform-sensitive location'

UserConfiguration = 'User configuration directory'

VersionControl = 'Version control internals'

class mimeogram.fsprotect.core.Status(*, path: Path, reason: Reasons | None = None, active: bool = False)

Bases: object

Protection status for location.

active: bool

property description: str

Human-readable description of protection.

path: Path

reason: Reasons | None

Module mimeogram.fsprotect.home

Sensitive filesystem locations relative to user homes.

mimeogram.fsprotect.home.discover_sensitive_locations() → frozenset[str]

Discovers sensitive locations relative to user home.

Module mimeogram.fsprotect.macos

Sensitive filesystem locations on macOS.

mimeogram.fsprotect.macos.discover_system_paths() → frozenset[Path]

Discovers system paths.

mimeogram.fsprotect.macos.discover_user_paths() → frozenset[Path]

Discovers user-specific paths.

Module mimeogram.fsprotect.project

Sensitive filesystem locations relative to project directory.

mimeogram.fsprotect.project.discover_sensitive_locations() → frozenset[str]

Discovers sensitive directories in project context.

Module mimeogram.fsprotect.unix

Sensitive filesystem locations on Unix/POSIX/Linux.

mimeogram.fsprotect.unix.discover_system_paths() → frozenset[Path]

Discovers Unix and other relevant system paths.

Module mimeogram.fsprotect.windows

Sensitive filesystem locations on Windows.

mimeogram.fsprotect.windows.discover_system_paths() → frozenset[Path]

Discovers system paths via standard Windows mechanisms.

mimeogram.fsprotect.windows.discover_user_paths() → frozenset[Path]

Discovers Windows user-specific paths that should be protected.