all2md.utils.metadata

Metadata extraction and front matter utilities for all2md.

This module provides utilities for extracting document metadata and formatting it as front matter for prepending to Markdown output. Serialization now relies on PyYAML and tomli_w for robust YAML and TOML generation.

The metadata extraction supports various document properties like title, author, creation date, keywords, and format-specific metadata fields.

class all2md.utils.metadata.MetadataRenderPolicy

Bases: object

Configuration describing how document metadata should be rendered.

visibility: Literal['core', 'standard', 'extended', 'all'] = 'extended'

include_fields: Tuple[str, ...]

exclude_fields: Tuple[str, ...]

include_custom_fields: bool = True

field_aliases: Dict[str, str]

__init__(visibility: Literal['core', 'standard', 'extended', 'all']='extended', include_fields: Tuple[str, ...]=<factory>, exclude_fields: Tuple[str, ...]=<factory>, include_custom_fields: bool = True, field_aliases: Dict[str, str]=<factory>) → None

all2md.utils.metadata.prepare_metadata_for_render(metadata: DocumentMetadata | Mapping[str, Any] | None, policy: MetadataRenderPolicy | None = None) → Dict[str, Any]: Return metadata filtered for rendering according to the policy.

class all2md.utils.metadata.DocumentMetadata

Bases: object

Container for extracted document metadata.

Parameters:

title (str | None) – Document title
author (str | None) – Primary author or creator
subject (str | None) – Document subject or description
keywords (list[str] | None) – Document keywords or tags
creation_date (datetime | str | None) – Document creation date
modification_date (datetime | str | None) – Last modification date
creator (str | None) – Software/tool that created the document
producer (str | None) – Software/tool that produced the document
category (str | None) – Document category or type
language (str | None) – Document language
url (str | None) – Source URL of the document
source_path (str | None) – Original file path of the document
page_count (int | None) – Total number of pages (for paginated formats)
word_count (int | None) – Total word count in the document
sha256 (str | None) – SHA-256 hash of the source document
extraction_date (str | None) – Date and time when the document was converted
version (str | None) – Document version (e.g., from AsciiDoc revnumber)
custom (dict[str, Any]) – Custom metadata fields specific to document format

title: str | None = None

author: str | None = None

subject: str | None = None

keywords: List[str] | None = None

creation_date: datetime | str | None = None

modification_date: datetime | str | None = None

creator: str | None = None

producer: str | None = None

category: str | None = None

language: str | None = None

url: str | None = None

source_path: str | None = None

page_count: int | None = None

word_count: int | None = None

sha256: str | None = None

extraction_date: str | None = None

version: str | None = None

custom: Dict[str, Any]

to_dict() → Dict[str, Any]

Convert metadata to dictionary, excluding None values.

Returns:: Dictionary containing only non-None metadata fields
Return type:: dict

__init__(title: str | None = None, author: str | None = None, subject: str | None = None, keywords: List[str] | None = None, creation_date: datetime | str | None = None, modification_date: datetime | str | None = None, creator: str | None = None, producer: str | None = None, category: str | None = None, language: str | None = None, url: str | None = None, source_path: str | None = None, page_count: int | None = None, word_count: int | None = None, sha256: str | None = None, extraction_date: str | None = None, version: str | None = None, custom: Dict[str, ~typing.Any]=<factory>) → None

all2md.utils.metadata.format_yaml_frontmatter(metadata: DocumentMetadata | Dict[str, Any], policy: MetadataRenderPolicy | None = None) → str

Format metadata as YAML front matter.

This function creates a YAML front matter block using PyYAML for robust serialization of metadata structures.

Parameters:

metadata (DocumentMetadata or dict) – Metadata to format as YAML front matter
policy (MetadataRenderPolicy or None, optional) – Filtering policy describing which metadata fields to include

Returns:

YAML front matter string with — delimiters, or empty string if no metadata

Return type:

str

Examples

>>> metadata = DocumentMetadata(
...     title="My Document",
...     author="John Doe",
...     keywords=["python", "conversion"]
... )
>>> print(format_yaml_frontmatter(metadata))
---
title: My Document
author: John Doe
keywords: [python, conversion]
---

all2md.utils.metadata.format_toml_frontmatter(metadata: DocumentMetadata | Dict[str, Any], policy: MetadataRenderPolicy | None = None) → str

Format metadata as TOML front matter.

This function creates TOML front matter using tomli_w for standards-compliant serialization.

Parameters:

metadata (DocumentMetadata or dict) – Metadata to format as TOML front matter
policy (MetadataRenderPolicy or None, optional) – Filtering policy describing which metadata fields to include

Returns:

TOML front matter string with +++ delimiters, or empty string if no metadata

Return type:

str

Examples

>>> metadata = DocumentMetadata(
...     title="My Document",
...     author="John Doe",
...     keywords=["python", "conversion"]
... )
>>> print(format_toml_frontmatter(metadata))
+++
title = "My Document"
author = "John Doe"
keywords = ["python", "conversion"]
+++

all2md.utils.metadata.format_json_frontmatter(metadata: DocumentMetadata | Dict[str, Any], policy: MetadataRenderPolicy | None = None) → str

Format metadata as JSON front matter.

This function creates JSON front matter with proper escaping and formatting.

Parameters:

metadata (DocumentMetadata or dict) – Metadata to format as JSON front matter
policy (MetadataRenderPolicy or None, optional) – Filtering policy describing which metadata fields to include

Returns:

JSON front matter string with ```json delimiters, or empty string if no metadata

Return type:

str

Examples

>>> metadata = DocumentMetadata(
...     title="My Document",
...     author="John Doe",
...     keywords=["python", "conversion"]
... )
>>> print(format_json_frontmatter(metadata))
\`\`\`json
{
  "title": "My Document",
  "author": "John Doe",
  "keywords": ["python", "conversion"]
}
\`\`\`

all2md.utils.metadata.safe_extract_property(obj: Any, primary_attr: str, fallback_attr: str | None = None) → str | None

Safely extract a string property from an object with optional fallback.

Parameters:

obj (Any) – Object to extract property from
primary_attr (str) – Primary attribute name to check
fallback_attr (str | None) – Optional fallback attribute name if primary is not found or empty

Returns:

Non-empty string value, or None if not found or empty

Return type:

str | None

all2md.utils.metadata.extract_keywords_from_string(keywords_str: str) → List[str]

Extract and clean keywords from a delimited string.

Parameters:: keywords_str (str) – String containing keywords separated by commas or semicolons
Returns:: List of cleaned keyword strings
Return type:: list[str]

all2md.utils.metadata.map_properties_to_metadata(props_obj: Any, field_mapping: Mapping[str, str | List[str]], custom_handlers: Dict[str, Any] | None = None) → DocumentMetadata

Map properties from a document object to DocumentMetadata using field mappings.

Parameters:

props_obj (Any) – Object containing document properties (e.g., core_properties, metadata dict)
field_mapping (dict[str, str | list[str]]) – Mapping from DocumentMetadata fields to property names. Values can be single strings or lists of fallback names.
custom_handlers (dict[str, Any] | None) – Optional custom handling functions for specific fields

Returns:

Populated metadata object

Return type:

DocumentMetadata

Examples

>>> # For DOCX/PPTX core_properties
>>> mapping = {
...     'title': 'title',
...     'author': 'author',
...     'subject': 'subject',
...     'keywords': 'keywords'
... }
>>> metadata = map_properties_to_metadata(props, mapping)

>>> # For PDF with fallbacks
>>> mapping = {
...     'title': ['title', 'Title'],
...     'author': ['author', 'Author']
... }
>>> metadata = map_properties_to_metadata(pdf_meta, mapping)

all2md.utils.metadata.extract_dict_metadata(metadata_dict: Dict[str, Any], field_mapping: Mapping[str, str | List[str]]) → DocumentMetadata

Extract metadata from a dictionary (useful for PDF and similar formats).

Parameters:

metadata_dict (dict[str, Any]) – Dictionary containing metadata key-value pairs
field_mapping (dict[str, str | list[str]]) – Mapping from DocumentMetadata fields to dictionary keys

Returns:

Populated metadata object

Return type:

DocumentMetadata

all2md.utils.metadata.prepend_metadata_if_enabled(content: str, metadata: DocumentMetadata | None, extract_metadata: bool, policy: MetadataRenderPolicy | None = None) → str

Prepend metadata to content if extraction is enabled.

Parameters:

content (str) – The markdown content
metadata (DocumentMetadata | None) – The extracted metadata
extract_metadata (bool) – Whether metadata extraction is enabled
policy (MetadataRenderPolicy or None, optional) – Policy controlling which metadata fields are prepended

Returns:

Content with metadata prepended if enabled, otherwise unchanged content

Return type:

str

all2md.utils.metadata.enrich_metadata_with_conversion_info(metadata: DocumentMetadata, input_data: Any, content: str = '', page_count: int | None = None) → DocumentMetadata

Enrich metadata with conversion-specific information.

Adds fields like extraction_date, source_path, sha256, word_count, and page_count to the metadata based on the input and content.

Parameters:

metadata (DocumentMetadata) – The metadata object to enrich
input_data (Any) – The input data (file path, bytes, or file object)
content (str, default "") – The extracted text content for word count calculation
page_count (int | None, default None) – Number of pages (for paginated formats)

Returns:

The enriched metadata object

Return type:

DocumentMetadata