AutoParser¶

AutoParser 是解析化学文件的主要入口。它会展开路径和 glob，根据扩展名候选及文件内容探测 reader，并返回包含成功解析文件的 FileBatchModelDisk。

Python

from molop import AutoParser

batch = AutoParser("water_mp2.out", n_jobs=1)
print(len(batch), batch[0].detected_format_id)

输出

Text Only

1 orcaout

扩展名如 .out 存在歧义时使用 parser_detection="orcaout"。路径规范化、frame 选择和失败文件处理见解析文件。

需要为每个输入路径保留明确结果时，使用 return_report=True：

Python

from molop import AutoParser, ParseOptions

report = AutoParser(
    ["water_mp2.out", "missing.out"],
    parse_options=ParseOptions(only_last_frame=True),
    return_report=True,
)

for outcome in report.outcomes:
    print(outcome.file_path, outcome.status)

输出

Text Only

/absolute/path/missing.out missing
/absolute/path/water_mp2.out ok

outcome 状态包括 ok、empty、missing、skipped、unsupported、mismatch 和 error。 reader warning 与可序列化失败信息保留在各 outcome 中；report.batch 仍是只包含成功文件的 FileBatchModelDisk。

如果不需要构造成功文件集合，可以使用顶层迭代接口逐条消费结果：

Python

from molop import iter_parse_outcomes

for outcome in iter_parse_outcomes(["water_mp2.out", "missing.out"], n_jobs=2):
    print(outcome.input_index, outcome.file_path, outcome.status)

输出

Text Only

0 /absolute/path/water_mp2.out ok
1 /absolute/path/missing.out missing

迭代结果按完成顺序产生，并保留 input_index；重复输入路径会产生重复结果。消费者提前关闭迭代器会回收 worker 和结果流。设置 fail_fast=True 会在首个非 ok 结果处抛出 BatchParseError，并取消剩余工作。

The Entrypoint of MolOP

Parameters:

Name	Type	Description	Default
`file_path`	`PathInput`	A path, glob pattern, or iterable containing paths and glob patterns.	required
`total_charge`	`int \| None`	forced charge of the molecule, if not given, will use the charge written in the file or 0.	`None`
`total_multiplicity`	`int \| None`	forced multiplicity of the molecule, if not given, will use the charge written in the file or 1.	`None`
`n_jobs`	`int`	number of jobs to use, if -1, use cpu with default max number.	`-1`
`only_extract_structure`	`bool`	if True, only extract the structure, else extract the whole file.	`False`
`only_last_frame`	`bool`	if True, only extract the last frame, else extract all frames.	`False`
`capture_source_evidence`	`bool`	if True, capture format-supported source evidence while parsing.	`False`
`source_encoding`	`str`	Text encoding used for strict source decoding and byte offsets.	`'utf-8'`
`release_file_content`	`bool`	if True, release the file content after parsing, else keep the file content in memory.	`True`
`parser_detection`	`str`	if “auto”, use the file extension to detect the parser, else use the given format id.	`'auto'`
`parse_options`	`ParseOptions \| None`	immutable parsing options; when provided, these take precedence over individual options.	`None`
`return_report`	`bool`	if True, return the successful batch together with one structured outcome per input.	`False`

Returns:

Name	Type	Description
`FileBatchModelDisk`	`FileBatchModelDisk[FileDiskObj] \| BatchParseResult[FileBatchModelDisk[FileDiskObj], FileDiskObj]`	Parsed files sorted by absolute file path.

How to use¶

Python

from molop import AutoParser

parser = AutoParser("/path/to/file")  # parse one file
parser = AutoParser("/path/to/files/*.log")  # parse one glob pattern
parser = AutoParser(["a.log", "group_b/*.log"])  # parse multiple inputs

Source code in src/molop/io/__init__.py

Python

def AutoParser(
    file_path: PathInput,
    *,
    total_charge: int | None = None,
    total_multiplicity: int | None = None,
    n_jobs: int = -1,
    only_extract_structure=False,
    only_last_frame=False,
    capture_source_evidence: bool = False,
    source_encoding: str = "utf-8",
    release_file_content: bool = True,
    parser_detection: str = "auto",
    parse_options: ParseOptions | None = None,
    return_report: bool = False,
) -> (
    FileBatchModelDisk["FileDiskObj"]
    | BatchParseResult[FileBatchModelDisk["FileDiskObj"], "FileDiskObj"]
):
    """
    The Entrypoint of MolOP

    Parameters:
        file_path (PathInput):
            A path, glob pattern, or iterable containing paths and glob patterns.
        total_charge (int | None):
            forced charge of the molecule, if not given, will use the charge written in the file or 0.
        total_multiplicity (int | None):
            forced multiplicity of the molecule, if not given, will use the charge written in the file or 1.
        n_jobs (int):
            number of jobs to use, if -1, use cpu with default max number.
        only_extract_structure (bool):
            if True, only extract the structure, else extract the whole file.
        only_last_frame (bool):
            if True, only extract the last frame, else extract all frames.
        capture_source_evidence (bool):
            if True, capture format-supported source evidence while parsing.
        source_encoding (str):
            Text encoding used for strict source decoding and byte offsets.
        release_file_content (bool):
            if True, release the file content after parsing, else keep the file content in memory.
        parser_detection (str):
            if "auto", use the file extension to detect the parser, else use the given format id.
        parse_options (ParseOptions | None):
            immutable parsing options; when provided, these take precedence over individual options.
        return_report (bool):
            if True, return the successful batch together with one structured outcome per input.

    Returns:
        FileBatchModelDisk: Parsed files sorted by absolute file path.

    How to use
    ----------
    ```python
    from molop import AutoParser

    parser = AutoParser("/path/to/file")  # parse one file
    parser = AutoParser("/path/to/files/*.log")  # parse one glob pattern
    parser = AutoParser(["a.log", "group_b/*.log"])  # parse multiple inputs
    ```
    """
    files = _normalize_file_paths(file_path)
    parser = FileBatchParserDisk(n_jobs=n_jobs)
    if return_report:
        return parser.parse_with_report(
            files,
            total_charge=total_charge,
            total_multiplicity=total_multiplicity,
            only_extract_structure=only_extract_structure,
            only_last_frame=only_last_frame,
            capture_source_evidence=capture_source_evidence,
            source_encoding=source_encoding,
            release_file_content=release_file_content,
            parser_detection=parser_detection,
            parse_options=parse_options,
        )
    return parser.parse(
        files,
        total_charge=total_charge,
        total_multiplicity=total_multiplicity,
        only_extract_structure=only_extract_structure,
        only_last_frame=only_last_frame,
        capture_source_evidence=capture_source_evidence,
        source_encoding=source_encoding,
        release_file_content=release_file_content,
        parser_detection=parser_detection,
        parse_options=parse_options,
    )