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:
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:
- class mimeogram.apply.ContentAcquirer¶
Bases:
DataclassProtocol
,Protocol
Acquires content for apply command.
- abstract async acquire_clipboard()¶
Acquires content from clipboard.
- Parameters:
self
- Return type:
- abstract async acquire_file(path)¶
Acquires content from file.
- Parameters:
self
path (str | pathlib.Path)
- Return type:
- abstract async acquire_stdin()¶
Acquires content from standard input.
- Parameters:
self
- Return type:
- class mimeogram.apply.StandardContentAcquirer¶
Bases:
ContentAcquirer
Standard implementation of content acquisition.
- async acquire_file(path)¶
- Parameters:
self
path (str | pathlib.Path)
- Return type:
- 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:
- 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:
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:
- 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.
- 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:
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:
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.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.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.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:
- mimeogram.formatters.format_part(part, boundary)¶
Formats part with boundary marker and headers.
- Parameters:
part (mimeogram.parts.Part)
boundary (str)
- Return type:
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:
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:
- class mimeogram.interfaces.DifferencesDisplay(*, context_lines=3, inline_threshold=24)¶
Bases:
DataclassProtocol
,Protocol
Configuration for content differences display.
Module mimeogram.parsers
¶
Parsers for mimeograms and their constituents.
Module mimeogram.parts
¶
Mimeogram parts.
- class mimeogram.parts.LineSeparators(value)¶
Bases:
Enum
Line separators for various platforms.
- Variables:
- 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:
- async mimeogram.prompt.acquire_prompt(auxdata)¶
Acquires prompt text from package data.
- Parameters:
auxdata (mimeogram.__.state.Globals)
- Return type:
- 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)
- class mimeogram.tokenizers.Tokenizer¶
Bases:
DataclassProtocol
,Protocol
Language model tokenizer.
- abstract async count(text)¶
Counts number of tokens in text.
- 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 ])
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)
interactor (mimeogram.interfaces.PartInteractor | absence.objects.AbsentSingleton)
- Return type:
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 ])
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 ])
- 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 ])