Python API

The core names documented here are exported from ssmdconvert and listed in ssmdconvert.__all__.

Conversion

.. py:function:: convert(source: str | ~pathlib.Path, *, title: str | None = None, author: str | None = None, language: str | None = None, metadata_overrides: ~collections.abc.Mapping[str, ~typing.Any] | None = None, sequence_fallback_mode: ~typing.Literal[‘preserve’, ‘spell’] = ‘preserve’) -> ~ssmdconvert.models.ConversionResult :module: ssmdconvert

Convert a source path with the default adapters.

.. py:class:: Converter(adapters: ~collections.abc.Iterable[~ssmdconvert.adapters.base.InputAdapter] | None = None) :module: ssmdconvert :canonical: ssmdconvert.converter.Converter

Bases: :py:class:object

Convert source documents through the registered input adapters.

.. py:method:: Converter.adapter_for(source: str | ~pathlib.Path) -> ~ssmdconvert.adapters.base.InputAdapter :module: ssmdconvert

  Select the adapter that supports a source path.

.. py:method:: Converter.load(source: str | ~pathlib.Path) -> ~ssmdconvert.models.Document :module: ssmdconvert

  Load a source into the normalized document model.

.. py:method:: Converter.convert(source: str | ~pathlib.Path, *, title: str | None = None, author: str | None = None, language: str | None = None, metadata_overrides: ~collections.abc.Mapping[str, ~typing.Any] | None = None, sequence_fallback_mode: ~typing.Literal[‘preserve’, ‘spell’] = ‘preserve’) -> ~ssmdconvert.models.ConversionResult :module: ssmdconvert

  Convert a source into one combined SSMD document.

.. py:method:: Converter.convert_content(content: str, *, input_format: ~typing.Literal[‘text’, ‘markdown’, ‘html’], source_name: str = ‘’, title: str | None = None, language: str | None = None, metadata_overrides: ~collections.abc.Mapping[str, ~typing.Any] | None = None, sequence_fallback_mode: ~typing.Literal[‘preserve’, ‘spell’] = ‘preserve’) -> ~ssmdconvert.models.ConversionResult :module: ssmdconvert</p>

  Convert in-memory text, Markdown, or HTML into one SSMD document.

.. py:class:: ConversionResult(document: ~ssmdconvert.models.Document, ssmd: str) :module: ssmdconvert :canonical: ssmdconvert.models.ConversionResult

Bases: :py:class:object

Rendered SSMD and its normalized document.

.. py:attribute:: ConversionResult.document :module: ssmdconvert :type: ~ssmdconvert.models.Document

.. py:attribute:: ConversionResult.ssmd :module: ssmdconvert :type: str

Converter.convert() returns one combined SSMD document. Input paths ending in .ssmd or .ssmd.md are recognized case-insensitively and parsed as SSMD before being rendered.

Converter.convert(), the convenience convert(), and convert_content() accept sequence_fallback_mode, which may be spell or preserve. New conversions default to preserve; the selected value is written to generated SSMD front matter and normalized document metadata. This writer default does not change how consumers handle legacy SSMD documents where the field is absent.

result = convert("manuscript.md", sequence_fallback_mode="preserve")

metadata_overrides accepts a mapping of supported portable SSMD and bibliographic values in the Python conversion APIs. The CLI counterpart is --metadata-file PATH, a UTF-8 YAML mapping. Values merge in source, file, then explicit CLI order; the effective sequence_fallback_mode is applied last. For example:

result = convert(
    "manuscript.md",
    metadata_overrides={"voice_defaults": {"narrator": {"rate": "slow"}}},
)

</section>

Source-neutral models

.. py:class:: SourceInfo(format: str, media_type: str | None = None, path: ~pathlib.Path | None = None, name: str | None = None) :module: ssmdconvert :canonical: ssmdconvert.models.SourceInfo

Bases: :py:class:object

Source format and provenance, with a path only when locally available.

.. py:attribute:: SourceInfo.format :module: ssmdconvert :type: str

.. py:attribute:: SourceInfo.media_type :module: ssmdconvert :type: str | None

.. py:attribute:: SourceInfo.path :module: ssmdconvert :type: ~pathlib.Path | None

.. py:attribute:: SourceInfo.name :module: ssmdconvert :type: str | None

.. py:class:: Section(id: str, markdown: str, title: str | None = None, level: int = 1, source_ref: str | None = None) :module: ssmdconvert :canonical: ssmdconvert.models.Section

Bases: :py:class:object

A normalized, ordered portion of a source document.

.. py:attribute:: Section.id :module: ssmdconvert :type: str

.. py:attribute:: Section.markdown :module: ssmdconvert :type: str

.. py:attribute:: Section.title :module: ssmdconvert :type: str | None

.. py:attribute:: Section.level :module: ssmdconvert :type: int

.. py:attribute:: Section.source_ref :module: ssmdconvert :type: str | None

.. py:class:: Document(source: ~ssmdconvert.models.SourceInfo, sections: list[~ssmdconvert.models.Section], metadata: dict[str, ~typing.Any] = ) :module: ssmdconvert :canonical: ssmdconvert.models.Document</p>

Bases: :py:class:object

Source-neutral document model passed between adapters and renderers.

.. py:attribute:: Document.source :module: ssmdconvert :type: ~ssmdconvert.models.SourceInfo

.. py:attribute:: Document.sections :module: ssmdconvert :type: list[~ssmdconvert.models.Section]

.. py:attribute:: Document.metadata :module: ssmdconvert :type: dict[str, ~typing.Any]

SourceInfo.path is populated when the source is locally available. Bundle-loaded provenance keeps its source name, format, and media type, but has no local path.

</section>

Books and chapters

.. py:class:: Book(source: ~ssmdconvert.models.SourceInfo, metadata: ~collections.abc.Mapping[str, ~typing.Any], chapters: tuple[~ssmdconvert.models.BookChapter, …], source_sha256: str, source_chapter_count: int | None = None) :module: ssmdconvert :canonical: ssmdconvert.models.Book

Bases: :py:class:object

Chapter-aware representation of a source book.

.. py:attribute:: Book.source :module: ssmdconvert :type: ~ssmdconvert.models.SourceInfo

.. py:attribute:: Book.metadata :module: ssmdconvert :type: ~collections.abc.Mapping[str, ~typing.Any]

.. py:attribute:: Book.chapters :module: ssmdconvert :type: tuple[~ssmdconvert.models.BookChapter, …]

.. py:attribute:: Book.source_sha256 :module: ssmdconvert :type: str

.. py:attribute:: Book.source_chapter_count :module: ssmdconvert :type: int | None

.. py:class:: BookChapter(id: str, source_number: int, title: str, ssmd: str, source_id: str | None = None, href: str | None = None, source_parent_id: str | None = None, parent_id: str | None = None, level: int = 1, char_count: int | None = None, diagnostics: tuple[~collections.abc.Mapping[str, ~typing.Any], …] = ()) :module: ssmdconvert :canonical: ssmdconvert.models.BookChapter

Bases: :py:class:object

One source chapter represented as a standalone SSMD document.

.. py:attribute:: BookChapter.id :module: ssmdconvert :type: str

.. py:attribute:: BookChapter.source_number :module: ssmdconvert :type: int

.. py:attribute:: BookChapter.title :module: ssmdconvert :type: str

.. py:attribute:: BookChapter.ssmd :module: ssmdconvert :type: str

.. py:attribute:: BookChapter.source_id :module: ssmdconvert :type: str | None

.. py:attribute:: BookChapter.href :module: ssmdconvert :type: str | None

.. py:attribute:: BookChapter.source_parent_id :module: ssmdconvert :type: str | None

.. py:attribute:: BookChapter.parent_id :module: ssmdconvert :type: str | None

.. py:attribute:: BookChapter.level :module: ssmdconvert :type: int

.. py:attribute:: BookChapter.char_count :module: ssmdconvert :type: int | None

.. py:attribute:: BookChapter.diagnostics :module: ssmdconvert :type: tuple[~collections.abc.Mapping[str, ~typing.Any], …]

.. py:class:: BookInspection(source: ~ssmdconvert.models.SourceInfo, metadata: ~collections.abc.Mapping[str, ~typing.Any], chapters: tuple[~ssmdconvert.models.BookInspectionChapter, …]) :module: ssmdconvert :canonical: ssmdconvert.models.BookInspection

Bases: :py:class:object

Source metadata and ordered chapter inventory for a book.

.. py:attribute:: BookInspection.source :module: ssmdconvert :type: ~ssmdconvert.models.SourceInfo

.. py:attribute:: BookInspection.metadata :module: ssmdconvert :type: ~collections.abc.Mapping[str, ~typing.Any]

.. py:attribute:: BookInspection.chapters :module: ssmdconvert :type: tuple[~ssmdconvert.models.BookInspectionChapter, …]

.. py:class:: BookInspectionChapter(id: str, source_number: int, title: str, source_id: str | None = None, href: str | None = None, source_parent_id: str | None = None, parent_id: str | None = None, level: int = 1, char_count: int | None = None, diagnostics: tuple[~collections.abc.Mapping[str, ~typing.Any], …] = ()) :module: ssmdconvert :canonical: ssmdconvert.models.BookInspectionChapter

Bases: :py:class:object

Inventory metadata for one source chapter.

.. py:attribute:: BookInspectionChapter.id :module: ssmdconvert :type: str

.. py:attribute:: BookInspectionChapter.source_number :module: ssmdconvert :type: int

.. py:attribute:: BookInspectionChapter.title :module: ssmdconvert :type: str

.. py:attribute:: BookInspectionChapter.source_id :module: ssmdconvert :type: str | None

.. py:attribute:: BookInspectionChapter.href :module: ssmdconvert :type: str | None

.. py:attribute:: BookInspectionChapter.source_parent_id :module: ssmdconvert :type: str | None

.. py:attribute:: BookInspectionChapter.parent_id :module: ssmdconvert :type: str | None

.. py:attribute:: BookInspectionChapter.level :module: ssmdconvert :type: int

.. py:attribute:: BookInspectionChapter.char_count :module: ssmdconvert :type: int | None

.. py:attribute:: BookInspectionChapter.diagnostics :module: ssmdconvert :type: tuple[~collections.abc.Mapping[str, ~typing.Any], …]

.. py:function:: inspect_book(source: str | ~pathlib.Path) -> ~ssmdconvert.models.BookInspection :module: ssmdconvert

Return EPUB metadata and its ordered source chapter inventory.

.. py:function:: convert_book(source: str | ~pathlib.Path, *, chapters: str | None = ‘all’, language: str | None = None, metadata_overrides: ~collections.abc.Mapping[str, ~typing.Any] | None = None, sequence_fallback_mode: ~typing.Literal[‘preserve’, ‘spell’] = ‘preserve’, speech_semantics: ~typing.Literal[‘freeze’, ‘preserve’] = ‘freeze’) -> ~ssmdconvert.models.Book :module: ssmdconvert

Convert selected EPUB chapters to standalone SSMD in source order.

BookChapter.id is the canonical chapter identity. source_id and source_parent_id preserve source navigation identifiers; parent_id refers to the canonical parent chapter ID when present in the inventory. Book.source_sha256 is captured during conversion.

convert_book() defaults to sequence_fallback_mode=preserve, accepts an optional language override and metadata_overrides mapping, and records effective metadata in Book.metadata and portable keys in each generated chapter. Source language is retained by default; absent source language stays absent unless supplied. For example:

book = convert_book(
    "novel.epub",
    language="de-DE",
    metadata_overrides={"voice_defaults": {"narrator": {"rate": "slow"}}},
)

Bundles

.. py:function:: write_book_bundle(book: ~ssmdconvert.models.Book, output: str | ~pathlib.Path, *, format: ~typing.Literal[‘directory’, ‘zip’], overwrite: bool = False) -> ~pathlib.Path :module: ssmdconvert

Write a complete directory or ZIP bundle atomically beside its destination.

.. py:function:: load_book_bundle(source: str | ~pathlib.Path) -> ~ssmdconvert.models.Book :module: ssmdconvert

Load and strictly validate a directory or ZIP book bundle.

.. py:function:: validate_book_bundle(source: str | ~pathlib.Path) -> None :module: ssmdconvert

Validate a book bundle using the same strict loader as deserialization.

The writer requires format="directory" or format="zip". Existing destinations are refused unless overwrite=True is supplied. See Bundle format for atomic replacement, validation, and resource limits.

Errors

.. py:class:: SSMDConvertError :module: ssmdconvert :canonical: ssmdconvert.errors.SSMDConvertError

Bases: :py:class:Exception

Base error.

.. py:class:: UnsupportedInputError :module: ssmdconvert :canonical: ssmdconvert.errors.UnsupportedInputError

Bases: :py:class:~ssmdconvert.errors.SSMDConvertError

No input adapter accepts the source.

.. py:class:: MissingDependencyError :module: ssmdconvert :canonical: ssmdconvert.errors.MissingDependencyError

Bases: :py:class:~ssmdconvert.errors.SSMDConvertError

An optional adapter/enricher dependency is not installed.

.. py:class:: BookError :module: ssmdconvert :canonical: ssmdconvert.errors.BookError

Bases: :py:class:~ssmdconvert.errors.SSMDConvertError

A book inspection or conversion failed.

.. py:class:: UnsupportedBookSourceError :module: ssmdconvert :canonical: ssmdconvert.errors.UnsupportedBookSourceError

Bases: :py:class:~ssmdconvert.errors.BookError

The book API does not support this source format.

.. py:class:: ChapterSelectionError :module: ssmdconvert :canonical: ssmdconvert.errors.ChapterSelectionError

Bases: :py:class:~ssmdconvert.errors.BookError

A chapter selection is malformed or unavailable.

.. py:class:: BookBundleError :module: ssmdconvert :canonical: ssmdconvert.errors.BookBundleError

Bases: :py:class:~ssmdconvert.errors.BookError

A book bundle could not be read or written.

.. py:class:: BookBundleValidationError :module: ssmdconvert :canonical: ssmdconvert.errors.BookBundleValidationError

Bases: :py:class:~ssmdconvert.errors.BookBundleError

A book bundle has invalid structure or content.

SSMD analysis and speech workflows

SSMD report, context lookup, TXT projection, speech audit, annotation, and freeze are user-facing CLI workflows. The former optional SpeechPreparationOptions / prepare_ssmd_for_speech engine and its direct spokenform runtime dependency have been removed; ttsready>=0.2,<0.3 supplies generic preparation through its public Python API.

See SSMD analysis and speech workflows for command usage, cache ownership, source mapping, safe write-back, and migration from the removed ttsready CLI.

Version

.. py:data:: version :module: ssmdconvert :value: ‘0.1.4’

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

</section> </div>