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.

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.

provide_configuration_edits()

Provides edits against configuration from options.

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

Bases: Protocol

Acquires content for apply command.

abstract async acquire_clipboard()

Acquires content from clipboard.

abstract async acquire_file(path)

Acquires content from file.

abstract async acquire_stdin()

Acquires content from standard input.

abstract stdin_is_tty()

Checks if input is from a terminal.

class mimeogram.apply.StandardContentAcquirer

Bases: ContentAcquirer

Standard implementation of content acquisition.

async acquire_clipboard()

Acquires content from clipboard.

async acquire_file(path)

Acquires content from file.

async acquire_stdin()

Acquires content from standard input.

stdin_is_tty()

Checks if input is from a terminal.

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

Applies mimeogram.

Module mimeogram.cli

Command-line interface.

class mimeogram.cli.Cli(*, application, configfile=None, inscription=Control(mode=<Modes.Rich: 'rich'>, level=None), command)

Bases: object

Mimeogram: hierarchical data exchange between humans and LLMs.

prepare_invocation_args()

Prepares arguments for initial configuration.

class mimeogram.cli.VersionCommand

Bases: CliCommand

Prints version information.

provide_configuration_edits()

Provides edits against configuration from options.

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)

Bases: CliCommand

Creates mimeogram from filesystem locations or URLs.

provide_configuration_edits()

Provides edits against configuration from options.

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

Creates mimeogram.

Module mimeogram.differences

Content differences management.

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

Bases: DifferencesDisplay

Default display of differences to console.

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

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.

Module mimeogram.display

System pager interaction.

mimeogram.display.discover_pager()

Discovers pager and returns executor function.

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

Displays content via discovered pager.

Module mimeogram.edit

System editor interaction.

mimeogram.edit.discover_editor()

Discovers editor and returns executor function.

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

Edits content via discovered editor.

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

Bases: Omniexception, Exception

Base for error exceptions raised by package API.

exception mimeogram.exceptions.Omniexception

Bases: 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)

Formats parts into mimeogram.

mimeogram.formatters.format_part(part, boundary)

Formats part with boundary marker and headers.

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.

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

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()

Provides edits against configuration from options.

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

Bases: Protocol

Configuration for content differences display.

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)

Parses mimeogram.

mimeogram.parsers.parse_part(ptext)

Parses mimeogram part.

Module mimeogram.parts

Mimeogram parts.

class mimeogram.parts.LineSeparators(value)

Bases: Enum

Line separators for various platforms.

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: object

Part of mimeogram.

class mimeogram.parts.Resolutions(value)

Bases: Enum

Available resolutions for each part.

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

Bases: object

Target information for mimeogram part.

Module mimeogram.prompt

Mimeogram prompt text for LLMs.

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

Bases: CliCommand

Provides LLM prompt text for mimeogram format.

provide_configuration_edits()

Provides edits against configuration from options.

async mimeogram.prompt.acquire_prompt(auxdata)

Acquires prompt text from package data.

async mimeogram.prompt.provide_prompt(auxdata)

Provides mimeogram prompt text.

Module mimeogram.tokenizers

Language model tokenizers.

class mimeogram.tokenizers.Tiktoken(*, codec)

Bases: Tokenizer

Tokenization via ‘tiktoken’ package.

async count(text)

Counts number of tokens in text.

async classmethod from_variant(name=absence.absent)

Produces instance from name of variant.

class mimeogram.tokenizers.Tokenizer(*args, **kwargs)

Bases: Protocol

Language model tokenizer.

abstract async count(text)

Counts number of tokens in text.

abstract async classmethod from_variant(name=absence.absent)

Produces instance from name of variant.

class mimeogram.tokenizers.Tokenizers(value)

Bases: Enum

Language model 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: object

Manages queued file updates for batch application.

async apply()

Applies all queued updates with parallel async fanout.

enqueue(part, target, content)

Adds a file update to queue.

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

Bases: object

Backup and restore filesystem state.

async restore()

Restores files to original contents in reverse order.

async save(part, path)

Saves original file content if it exists.

class mimeogram.updaters.ReviewModes(value)

Bases: Enum

Controls how updates are reviewed and applied.

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

Updates filesystem locations from mimeogram.

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

Updates filesystem location from mimeogram part.

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.

classmethod from_configuration(auxdata)

Initializes protection cache for current platform.

verify(path)

Verifies if a path should be protected using cached data.

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

Bases: object

Rule for path protection.

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

Discovers system and user locations based on platform.

mimeogram.fsprotect.cache.provide_credentials_locations(rules)

Provides common locations for credentials and other secrets.

mimeogram.fsprotect.cache.provide_project_locations(rules)

Provides IDE and VCS locations relative to project.