AutoParser¶

AutoParser is the main entry point for parsing chemical files. It expands paths and glob patterns, probes extension candidates against file content, and returns a FileBatchModelDisk containing successfully parsed files.

Python

from molop import AutoParser

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

Output

Text Only

1 orcaout

Use parser_detection="orcaout" when an extension such as .out is ambiguous. See Parse files for path normalization, frame selection, and failure handling.

Set return_report=True when every supplied path needs an explicit outcome:

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)

Output

Text Only

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

Outcomes use ok, empty, missing, skipped, unsupported, mismatch, or error. Reader warnings and serializable failure details remain attached to each outcome; report.batch retains the existing successful-file FileBatchModelDisk.

Use the top-level iterator when a successful-file batch should not be retained:

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)

Output

Text Only

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

Iterator results arrive in completion order and retain input_index; repeated input paths produce repeated outcomes. Closing the iterator early releases workers and the result stream. Set fail_fast=True to raise BatchParseError at the first non-ok result and cancel remaining work.

The Entrypoint of MolOP

参数：

名称	类型	描述	默认
`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.	`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`

返回：

名称	类型	描述
`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

源代码位于： 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,
    )