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

Exchange of file collections with LLMs.

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.

mimeogram.main()

Entrypoint.

Module mimeogram.acquirers

Content acquisition from various sources.

async mimeogram.acquirers.acquire(auxdata, sources)

Acquires content from multiple sources.

Parameters:

• auxdata (mimeogram.__.state.Globals)

• sources (collections.abc.Sequence[ str | pathlib.Path ])

Return type:

collections.abc.Sequence[ mimeogram.parts.Part ]

Module mimeogram.apply

Application of mimeograms.

class mimeogram.apply.Command(*, source='-', clip=None, mode=None, base=None, force=None)

Bases: CliCommand

Applies mimeogram to filesystem locations.

Variables:

• source (str) –

  Source file for mimeogram.

  Defaults to stdin if ‘–clip’ not specified.

• clip (bool | None) – Read mimeogram from clipboard instead of file or stdin.

• mode (mimeogram.updaters.ReviewModes | None) –

  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.

• base (pathlib.Path | None) –

  Base directory for relative locations.

  Defaults to current working directory.

• force (bool | None) – Override protected path checks.

provide_configuration_edits()

Provides edits against configuration from options.

Parameters:

self

Return type:

collections.abc.Iterable[ mimeogram.__.dictedits.Edit ]

class mimeogram.apply.ContentAcquirer

Bases: DataclassProtocol, Protocol

Acquires content for apply command.

abstract async acquire_clipboard()

Acquires content from clipboard.

Parameters:

self

Return type:

str

abstract async acquire_file(path)

Acquires content from file.

Parameters:

• self

• path (str | pathlib.Path)

Return type:

str

abstract async acquire_stdin()

Acquires content from standard input.

Parameters:

self

Return type:

str

abstract stdin_is_tty()

Checks if input is from a terminal.

Parameters:

self

Return type:

bool

class mimeogram.apply.StandardContentAcquirer

Bases: ContentAcquirer

Standard implementation of content acquisition.

async acquire_clipboard()

Parameters:

self

Return type:

str

async acquire_file(path)

Parameters:

• self

• path (str | pathlib.Path)

Return type:

str

async acquire_stdin()

Parameters:

self

Return type:

str

stdin_is_tty()

Parameters:

self

Return type:

bool

async mimeogram.apply.apply(auxdata, command, *, acquirer=absence.absent, parser=absence.absent, updater=absence.absent)

Applies mimeogram.

Parameters:

• auxdata (mimeogram.__.state.Globals)

• command (mimeogram.apply.Command)

• acquirer (mimeogram.apply.ContentAcquirer | absence.objects.AbsentSingleton)

• parser (collections.abc.Callable[ [ str ], collections.abc.Sequence[ mimeogram.parts.Part ] ] | absence.objects.AbsentSingleton)

• updater (collections.abc.Callable[ [ mimeogram.__.state.Globals, collections.abc.Sequence[ mimeogram.parts.Part ], mimeogram.updaters.ReviewModes ], collections.abc.Coroutine[ None, None, None ] ] | absence.objects.AbsentSingleton)

Return type:

typing_extensions.Never

Module mimeogram.cli

Command-line interface.

class mimeogram.cli.Cli(*, application, configfile=None, inscription=<factory>, command)

Bases: DataclassObject

Mimeogram: hierarchical data exchange between humans and LLMs.

Variables:

• application (mimeogram.__.application.Information)

• configfile (str | None)

• inscription (mimeogram.__.inscription.Control)

• command (mimeogram.create.Command | mimeogram.apply.Command | mimeogram.prompt.Command | mimeogram.cli.VersionCommand)

prepare_invocation_args()

Prepares arguments for initial configuration.

Parameters:

self

Return type:

collections.abc.Mapping[ str, typing_extensions.Any ]

class mimeogram.cli.VersionCommand

Bases: CliCommand

Prints version information.

provide_configuration_edits()

Provides edits against configuration from options.

Parameters:

self

Return type:

collections.abc.Iterable[ mimeogram.__.dictedits.Edit ]

mimeogram.cli.execute()

Entrypoint for CLI execution.

Module mimeogram.create

Creation of mimeograms.

class mimeogram.create.Command(*, sources, clip=None, count_tokens=None, edit=False, prepend_prompt=False, recurse=None, strict=None, tokenizer=None, tokenizer_variant=None, deterministic_boundary=None)

Bases: CliCommand

Creates mimeogram from filesystem locations or URLs.

Variables:

• sources (list[ str ]) – Filesystem locations or URLs.

• clip (bool | None) – Copy mimeogram to clipboard.

• count_tokens (bool | None) – Count total tokens in mimeogram.

• edit (bool) – Spawn editor to capture introductory message.

• prepend_prompt (bool) – Prepend mimeogram format instructions.

• recurse (bool | None) – Recurse into directories.

• strict (bool | None) – Fail on invalid contents? True, fail. False, skip.

• tokenizer (mimeogram.tokenizers.Tokenizers | None) – Which tokenizer to use for counting?

• tokenizer_variant (str | None) –

  Which tokenizer variant to use for counting?

  ’tiktoken’: ‘cl100k_base’, ‘o200k_base’, etc….

  Not all tokenizers have variants. If not specified, then the default variant is used.

• deterministic_boundary (bool | None) –

  Use deterministic boundary for reproducible output.

  When enabled, the MIME boundary marker will be a hash of the content, making output reproducible and diff-friendly. Useful for testing, CI, and batch processing.

provide_configuration_edits()

Provides edits against configuration from options.

Parameters:

self

Return type:

collections.abc.Iterable[ mimeogram.__.dictedits.Edit ]

async mimeogram.create.create(auxdata, command, *, editor=<function _edit_message>, clipcopier=<function _copy_to_clipboard>, prompter=<function _acquire_prompt>)

Creates mimeogram.

Parameters:

• auxdata (mimeogram.__.state.Globals)

• command (mimeogram.create.Command)

• editor (collections.abc.Callable[ [ ], collections.abc.Coroutine[ None, None, str ] ])

• clipcopier (collections.abc.Callable[ [ str ], collections.abc.Coroutine[ None, None, None ] ])

• prompter (collections.abc.Callable[ [ mimeogram.__.state.Globals ], collections.abc.Coroutine[ None, None, str ] ])

Return type:

typing_extensions.Never

Module mimeogram.differences

Content differences management.

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

Bases: DifferencesDisplay

Default display of differences to console.

Variables:

• context_lines (int)

• inline_threshold (int)

class mimeogram.differences.ConsoleInteractor

Bases: DifferencesInteractor

Default console-based interaction handler.

async mimeogram.differences.select_segments(target, revision, display=absence.absent, interactor=absence.absent)

Selects which diff hunks to apply.

Parameters:

• target (mimeogram.parts.Target)

• revision (str)

• display (mimeogram.interfaces.DifferencesDisplay | absence.objects.AbsentSingleton)

• interactor (mimeogram.interfaces.DifferencesInteractor | absence.objects.AbsentSingleton)

Return type:

str

Module mimeogram.display

System pager interaction.

mimeogram.display.discover_pager()

Discovers pager and returns executor function.

Return type:

collections.abc.Callable[ [ str ], None ]

mimeogram.display.display_content(content, *, suffix='.txt', pager_discoverer=<function discover_pager>)

Displays content via discovered pager.

Parameters:

• content (str)

• suffix (str)

• pager_discoverer (collections.abc.Callable[ [ ], collections.abc.Callable[ [ str ], None ] ])

Module mimeogram.edit

System editor interaction.

mimeogram.edit.discover_editor()

Discovers editor and returns executor function.

Return type:

collections.abc.Callable[ [ str ], str ]

mimeogram.edit.edit_content(content='', *, suffix='.md', editor_discoverer=<function discover_editor>)

Edits content via discovered editor.

Parameters:

• content (str)

• suffix (str)

• editor_discoverer (collections.abc.Callable[ [ ], collections.abc.Callable[ [ str ], str ] ])

Return type:

str

Module mimeogram.exceptions

Family of exceptions for package API.

exception mimeogram.exceptions.ContentAcquireFailure(location)

Bases: Omnierror

Failure to acquire content from location.

exception mimeogram.exceptions.ContentDecodeFailure(location, charset)

Bases: Omnierror

Failure to decode content as character set from location.

exception mimeogram.exceptions.ContentUpdateFailure(location)

Bases: Omnierror

Failure to update content at location.

exception mimeogram.exceptions.DifferencesProcessFailure(reason)

Bases: Omnierror

Failure during diff processing.

exception mimeogram.exceptions.EditorFailure(cause)

Bases: Omnierror

Failure while operating editor.

exception mimeogram.exceptions.LocationInvalidity(location)

Bases: Omnierror

Invalid location.

exception mimeogram.exceptions.MimeogramFormatEmpty

Bases: Omnierror

Attempt to format empty mimeogram.

exception mimeogram.exceptions.MimeogramParseFailure(reason)

Bases: Omnierror

Failure to parse mimeogram content.

exception mimeogram.exceptions.Omnierror(*posargs, **nomargs)

Bases: Omniexception, Exception

Base for error exceptions raised by package API.

exception mimeogram.exceptions.Omniexception(*posargs, **nomargs)

Bases: Object, BaseException

Base for all exceptions raised by package API.

exception mimeogram.exceptions.PagerFailure(cause)

Bases: Omnierror

Failure while operating pager.

exception mimeogram.exceptions.ProgramAbsenceError(species)

Bases: Omnierror

Could not discover valid editor.

exception mimeogram.exceptions.TextualMimetypeInvalidity(location, mimetype)

Bases: Omnierror

Invalid textual MIME type for content at location.

exception mimeogram.exceptions.TokenizerVariantInvalidity(name, variant)

Bases: Omnierror

Invalid tokenizer variant.

exception mimeogram.exceptions.UrlSchemeNoSupport(url)

Bases: Omnierror

Unsupported URL scheme.

exception mimeogram.exceptions.UserOperateCancellation(cause)

Bases: Omniexception

Operation cancelled by user.

Module mimeogram.formatters

Formatting of mimeogram bundles.

mimeogram.formatters.format_mimeogram(parts, message=None, deterministic_boundary=False)

Formats parts into mimeogram.

Parameters:

• parts (collections.abc.Sequence[ mimeogram.parts.Part ])

• message (str | None)

• deterministic_boundary (bool)

Return type:

str

mimeogram.formatters.format_part(part, boundary)

Formats part with boundary marker and headers.

Parameters:

• part (mimeogram.parts.Part)

• boundary (str)

Return type:

str

Module mimeogram.interactions

User interactions and automations.

class mimeogram.interactions.GenericInteractor(*, prompter=<function _prompt_action>, cdisplayer=<function _display_content>, ddisplayer=<function _display_differences>, editor=<function _edit_content>, sselector=<function _select_segments>, validator=<function _validate_choice>)

Bases: PartInteractor

Default console-based interaction handler.

Variables:

• prompter (collections.abc.Callable[ [ mimeogram.parts.Target, str, bool ], str ])

• cdisplayer (collections.abc.Callable[ [ mimeogram.parts.Target, str ], collections.abc.Coroutine[ None, None, None ] ])

• ddisplayer (collections.abc.Callable[ [ mimeogram.parts.Target, str ], collections.abc.Coroutine[ None, None, None ] ])

• editor (collections.abc.Callable[ [ mimeogram.parts.Target, str ], collections.abc.Coroutine[ None, None, str ] ])

• sselector (collections.abc.Callable[ [ mimeogram.parts.Target, str ], collections.abc.Coroutine[ None, None, str ] ])

• validator (collections.abc.Callable[ [ mimeogram.parts.Target, str ], None ])

async mimeogram.interactions.interact(target, interactor=absence.absent)

Performs interaction for part.

Parameters:

• target (mimeogram.parts.Target)

• interactor (mimeogram.interfaces.PartInteractor | absence.objects.AbsentSingleton)

Return type:

tuple[ mimeogram.parts.Resolutions, str ]

Module mimeogram.interfaces

Abstract bases and interfaces.

class mimeogram.interfaces.CliCommand

Bases: DataclassProtocol, Protocol

CLI command.

abstract provide_configuration_edits()

Provides edits against configuration from options.

Parameters:

self

Return type:

collections.abc.Iterable[ mimeogram.__.dictedits.Edit ]

class mimeogram.interfaces.DifferencesDisplay(*, context_lines=3, inline_threshold=24)

Bases: DataclassProtocol, Protocol

Configuration for content differences display.

Variables:

• context_lines (int)

• inline_threshold (int)

class mimeogram.interfaces.DifferencesInteractor

Bases: DataclassProtocol, Protocol

Interactions with content differences.

class mimeogram.interfaces.PartInteractor

Bases: DataclassProtocol, Protocol

Interactions with mimeogram parts.

Module mimeogram.parsers

Parsers for mimeograms and their constituents.

mimeogram.parsers.parse(mgtext)

Parses mimeogram.

Parameters:

mgtext (str)

Return type:

collections.abc.Sequence[ mimeogram.parts.Part ]

mimeogram.parsers.parse_part(ptext)

Parses mimeogram part.

Parameters:

ptext (str)

Return type:

mimeogram.parts.Part

Module mimeogram.parts

Mimeogram parts.

class mimeogram.parts.LineSeparators(value)

Bases: Enum

Line separators for various platforms.

Variables:

• CR (mimeogram.parts.LineSeparators)

• CRLF (mimeogram.parts.LineSeparators)

• LF (mimeogram.parts.LineSeparators)

classmethod detect_bytes(content, limit=1024)

Detects newline characters in bytes array.

nativize(content)

Nativizes specific variety newline characters in text.

normalize(content)

Normalizes specific variety newline characters in text.

classmethod normalize_universal(content)

Normalizes all varieties of newline characters in text.

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

Bases: DataclassObject

Part of mimeogram.

Variables:

• location (str)

• mimetype (str)

• charset (str)

• linesep (mimeogram.parts.LineSeparators)

• content (str)

class mimeogram.parts.Resolutions(value)

Bases: Enum

Available resolutions for each part.

Variables:

• Apply (mimeogram.parts.Resolutions)

• Ignore (mimeogram.parts.Resolutions)

class mimeogram.parts.Target(*, part, destination, protection)

Bases: DataclassObject

Target information for mimeogram part.

Variables:

• part (mimeogram.parts.Part)

• destination (pathlib.Path)

• protection (mimeogram.fsprotect.core.Status)

Module mimeogram.prompt

Mimeogram prompt text for LLMs.

class mimeogram.prompt.Command(*, clip=None)

Bases: CliCommand

Provides LLM prompt text for mimeogram format.

Variables:

clip (bool | None) – Copy prompt to clipboard.

provide_configuration_edits()

Provides edits against configuration from options.

Parameters:

self

Return type:

collections.abc.Iterable[ mimeogram.__.dictedits.Edit ]

async mimeogram.prompt.acquire_prompt(auxdata)

Acquires prompt text from package data.

Parameters:

auxdata (mimeogram.__.state.Globals)

Return type:

str

async mimeogram.prompt.provide_prompt(auxdata)

Provides mimeogram prompt text.

Parameters:

auxdata (mimeogram.__.state.Globals)

Module mimeogram.tokenizers

Language model tokenizers.

class mimeogram.tokenizers.Tiktoken(*, codec)

Bases: Tokenizer

Tokenization via ‘tiktoken’ package.

Variables:

codec (tiktoken.core.Encoding)

async count(text)

Parameters:

• self

• text (str)

Return type:

int

async classmethod from_variant(name=absence.absent)

Parameters:

• selfclass

• name (str | absence.objects.AbsentSingleton)

Return type:

typing_extensions.Self

class mimeogram.tokenizers.Tokenizer

Bases: DataclassProtocol, Protocol

Language model tokenizer.

abstract async count(text)

Counts number of tokens in text.

Parameters:

• self

• text (str)

Return type:

int

abstract async classmethod from_variant(name=absence.absent)

Produces instance from name of variant.

Parameters:

• selfclass

• name (str | absence.objects.AbsentSingleton)

Return type:

typing_extensions.Self

class mimeogram.tokenizers.Tokenizers(value)

Bases: Enum

Language model tokenizers.

Variables:

• AnthropicApi (mimeogram.tokenizers.Tokenizers)

• Tiktoken (mimeogram.tokenizers.Tokenizers)

async classmethod produce(name, variant=absence.absent)

Produces tokenizer from name and optional variant.

Module mimeogram.updaters

File content updates.

class mimeogram.updaters.Queue(*, updates=<factory>, reverter=<factory>)

Bases: DataclassObject

Manages queued file updates for batch application.

Variables:

• updates (list[ tuple[ mimeogram.parts.Part, pathlib.Path, str ] ])

• reverter (mimeogram.updaters.Reverter)

async apply()

Applies all queued updates with parallel async fanout.

Parameters:

self

enqueue(part, target, content)

Adds a file update to queue.

Parameters:

• self

• part (mimeogram.parts.Part)

• target (pathlib.Path)

• content (str)

class mimeogram.updaters.Reverter(*, originals=<factory>, revisions=<factory>)

Bases: DataclassObject

Backup and restore filesystem state.

Variables:

• originals (dict[ pathlib.Path, str ])

• revisions (list[ pathlib.Path ])

async restore()

Restores files to original contents in reverse order.

Parameters:

self

async save(part, path)

Saves original file content if it exists.

Parameters:

• self

• part (mimeogram.parts.Part)

• path (pathlib.Path)

class mimeogram.updaters.ReviewModes(value)

Bases: Enum

Controls how updates are reviewed and applied.

Variables:

• Silent (mimeogram.updaters.ReviewModes)

• Partitive (mimeogram.updaters.ReviewModes)

async mimeogram.updaters.update(auxdata, parts, mode, base=absence.absent, interactor=absence.absent, protector=absence.absent)

Updates filesystem locations from mimeogram.

Parameters:

• auxdata (mimeogram.__.state.Globals)

• parts (collections.abc.Sequence[ mimeogram.parts.Part ])

• mode (mimeogram.updaters.ReviewModes)

• base (pathlib.Path | absence.objects.AbsentSingleton)

• interactor (mimeogram.interfaces.PartInteractor | absence.objects.AbsentSingleton)

• protector (mimeogram.fsprotect.core.Protector | absence.objects.AbsentSingleton)

async mimeogram.updaters.update_part(auxdata, target, mode, interactor=absence.absent)

Updates filesystem location from mimeogram part.

Parameters:

• auxdata (mimeogram.__.state.Globals)

• target (mimeogram.parts.Target)

• mode (mimeogram.updaters.ReviewModes)

• interactor (mimeogram.interfaces.PartInteractor | absence.objects.AbsentSingleton)

Return type:

tuple[ mimeogram.parts.Resolutions, str ]

Subpackage mimeogram.fsprotect

Filesystem location protection.

Helps prevent dangerous modifications to sensitive paths.

Module mimeogram.fsprotect.cache

Cache for filesystem protection checks.

class mimeogram.fsprotect.cache.Cache(*, rules, defaults_disablement, rules_supercession)

Bases: Protector

Cache of protected paths and patterns for platform.

Variables:

• rules (dict[ mimeogram.fsprotect.core.Reasons, mimeogram.fsprotect.cache.Rule ])

• defaults_disablement (frozenset[ str ])

• rules_supercession (frigid.dictionaries.Dictionary[ pathlib.Path, tuple[ frozenset[ str ], frozenset[ str ] ] ])

classmethod from_configuration(auxdata)

Initializes protection cache for current platform.

Parameters:

• selfclass

• auxdata (mimeogram.__.state.Globals)

Return type:

typing_extensions.Self

verify(path)

Verifies if a path should be protected using cached data.

Parameters:

• self

• path (pathlib.Path)

Return type:

mimeogram.fsprotect.core.Status

class mimeogram.fsprotect.cache.Rule(*, paths, patterns=frozenset({}))

Bases: DataclassObject

Rule for path protection.

Variables:

• paths (frozenset[ pathlib.Path ])

• patterns (frozenset[ str ])

mimeogram.fsprotect.cache.discover_platform_locations(auxdata, rules)

Discovers system and user locations based on platform.

Parameters:

• auxdata (mimeogram.__.state.Globals)

• rules (dict[ mimeogram.fsprotect.core.Reasons, mimeogram.fsprotect.cache.Rule ])

mimeogram.fsprotect.cache.provide_credentials_locations(rules)

Provides common locations for credentials and other secrets.

Parameters:

rules (dict[ mimeogram.fsprotect.core.Reasons, mimeogram.fsprotect.cache.Rule ])

mimeogram.fsprotect.cache.provide_project_locations(rules)

Provides IDE and VCS locations relative to project.

Parameters:

rules (dict[ mimeogram.fsprotect.core.Reasons, mimeogram.fsprotect.cache.Rule ])