Python API

English | Français | 한국어 | 日本語

안내

API 레퍼런스는 Python Docstring에서 생성되었으므로, 영어로만 제공됩니다.

Tip

이 페이지에는 프로그래밍에 자주 사용되는 핵심 Python API에 대한 레퍼런스가 포함되어 있습니다. API 사용 예제를 통해 여기 나열된 Python API를 어떻게 사용하는지 확인할 수 있습니다.

여기에 없는 Python 모듈은 Advanced Reference에서 찾을 수 있습니다.

mmg.api

convert

convert(
    base_md: str,
    cfg: Config = None,
    skip_health_check: bool = False,
    force_convert: bool = False,
    print_log: bool = False,
    file_name: str = None,
    verbosity: int = 0,
) -> Dict[str, str]

Split the base markdown string into multiple markdowns based on the config.

Parameters:

Name	Type	Description	Default
`base_md`	`str`	The base markdown string to convert.	required
`cfg`	`Config`	The config to convert. If not given, the config will be extracted from the base_md. Defaults to None.	`None`
`skip_health_check`	`bool`	If True, skip the health check. Defaults to False.	`False`
`force_convert`	`bool`	If True, ignore the health check result and force to convert. This option is not working when `skip_health_check` is True. Defaults to False.	`False`
`print_log`	`bool`	If True, print the log. This option is not working when `skip_health_check` is True. Defaults to False.	`False`
`file_name`	`str`	The file name to show in the log. This option is not working when `print_log` is False. Defaults to None.	`None`
`verbosity`	`int`	The verbosity level from 0 to 2. This option is not working when `print_log` is False. Defaults to 0.	`0`

Returns:

Type	Description
`Dict[str, str]`	Dict[str, str]: A dictionary of converted markdowns. The key is the language tag, a.k.a. suffix.

convert_base_doc

convert_base_doc(
    base_doc: List[str],
    cfg: Config = None,
    skip_health_check: bool = False,
    force_convert: bool = False,
    print_log: bool = False,
    file_name: str = None,
    verbosity: int = 0,
) -> Dict[str, List[str]]

Split the base_doc into multiple markdowns based on the config.

Parameters:

Name	Type	Description	Default
`base_doc`	`List[str]`	The base markdown string to convert.	required
`cfg`	`Config`	The config to convert. If not given, the config will be extracted from the base_doc. Defaults to None.	`None`
`skip_health_check`	`bool`	If True, skip the health check. Defaults to False.	`False`
`force_convert`	`bool`	If True, ignore the health check result and force to convert. This option is not working when `skip_health_check` is True. Defaults to False.	`False`
`print_log`	`bool`	If True, print the log. This option is not working when `skip_health_check` is True. Defaults to False.	`False`
`file_name`	`str`	The file name to show in the log. This option is not working when `print_log` is False. Defaults to None.	`None`
`verbosity`	`int`	The verbosity level from 0 to 2. This option is not working when `print_log` is False. Defaults to 0.	`0`

Raises:

Type	Description
`BadConfigError`	If the health check failed.

Returns:

Type	Description
`Dict[str, List[str]]`	Dict[str, List[str]]: A dictionary of converted markdowns. The key is the language tag, a.k.a. suffix.

convert_base_jupyter

convert_base_jupyter(
    base_jn: Dict,
    cfg: Config = None,
    skip_health_check: bool = False,
    force_convert: bool = False,
    print_log: bool = False,
    file_name: str = None,
    verbosity: int = 0,
) -> Dict[str, Dict]

Split the base jupyter notebook into multiple markdowns based on the config.

Parameters:

Name	Type	Description	Default
`base_jn`	`Dict`	The base jupyter notebook to convert.	required
`cfg`	`Config`	The config to convert. If not given, the config will be extracted from the base_jn. Defaults to None.	`None`
`skip_health_check`	`bool`	If True, skip the health check. Defaults to False.	`False`
`force_convert`	`bool`	If True, ignore the health check result and force to convert. This option is not working when `skip_health_check` is True. Defaults to False.	`False`
`print_log`	`bool`	If True, print the log. This option is not working when `skip_health_check` is True. Defaults to False.	`False`
`file_name`	`str`	The file name to show in the log. This option is not working when `print_log` is False. Defaults to None.	`None`
`verbosity`	`int`	The verbosity level from 0 to 2. This option is not working when `print_log` is False. Defaults to 0.	`0`

Raises:

Type	Description
`BadConfigError`	If the health check failed.

Returns:

Type	Description
`Dict[str, Dict]`	Dict[str, Dict]: A dictionary of converted jupyter notebooks. The key is the language tag, a.k.a. suffix.

mmg.config

Config `dataclass`

Configuration class to control the behavior of MMG.

Parameters:

Name	Type	Description	Default
`lang_tags`	`List[str]`	A List of language tags to be used. Language tags are also used as suffixes.	`list()`
`no_suffix`	`str`	Prevents the suffix from being appended to the file name when creating the file. For example, setting `no_suffix` to 'en' will generate `FileName.md` instead of `FileName.en.md`. This option is useful for a README file on GitHub.	`None`

extract_config_from_md

extract_config_from_md(base_doc: List[str]) -> Config

Extract configuration from the base markdown string.

Parameters:

Name	Type	Description	Default
`base_doc`	`List[str]`	A list of strings extracted from the base markdown file.	required

Raises:

Type	Description
`BadConfigError`	If the configuration is duplicated.

Returns:

Name	Type	Description
`Config`	`Config`	A configuration extracted from the base markdown file.

mmg.health

DocChecker

HealthChecker

cli_log

cli_log(
    file_name: str = None, verbosity: int = 0
) -> List[str]

Return the log string of the CLI style.

Parameters:

Name	Type	Description	Default
`file_name`	`str`	The file name to show in the log. Defaults to None.	`None`
`verbosity`	`int`	The verbosity level from 0 to 2. Defaults to 0.	`0`

Returns:

Name	Type	Description
`str`	`List[str]`	The log string.

health_check

health_check(
    base: any, cfg: Config = None, extension: str = "md"
) -> HealthStatus

Check the health based on the current config.

Parameters:

Name	Type	Description	Default
`base`	`any`	The base file to check. Markdown(List[str]) or Jupyter(Dict).	required
`cfg`	`Config`	The config to check. If not given, the config will be extracted from the base_md.	`None`
`extension`	`str`	The extension of the base file. "md" or "ipynb". Defaults to "md".	`'md'`

Returns:

Name	Type	Description
`HealthStatus`	`HealthStatus`	The health status. (HEALTHY, UNHEALTHY, NOT_CHECKED)

mmg.toc

TocOptions

Bases: NamedTuple

Options parsed from a multilingual toc marker.

create_toc

create_toc(
    toc_options: TocOptions, doc: List[str]
) -> List[str]

Create a table of contents.

Parameters:

Name	Type	Description	Default
`toc_options`	`TocOptions`	(min_level, max_level, no_emoji, anchor). A plain 3-tuple is also accepted; `anchor` then falls back to the default.	required
`doc`	`List[str]`	The markdown string to parse.	required

Returns:

Type	Description
`List[str]`	List[str]: The table of contents. The lines carry no line ending.

parse_toc_options

parse_toc_options(toc_line: str) -> TocOptions

Parse the toc options.

Parameters:

Name	Type	Description	Default
`toc_line`	`str`	Example: `<!-- [[ multilingual toc: level=1~3, no-emoji ]] -->`	required

Raises:

Type	Description
`BadConfigError`	If the level option is not specified, if the level option is invalid, or if the anchor option is not a known style.

Returns:

Name	Type	Description
`TocOptions`	`TocOptions`	(min_level, max_level, no_emoji, anchor)

mmg.utils

flag_code_block_lines

flag_code_block_lines(doc: List[str]) -> List[bool]

Parse the markdwon string and find all code blocks. Marked lines will be skipped when parsing the MMG tags.

Parameters:

Name	Type	Description	Default
`doc`	`List[str]`	The markdown string to parse.	required

Returns:

Type	Description
`List[bool]`	List[bool]: A list of booleans indicating whether the line is in a code block. (True: in a code block, False: not in a code block)

get_indentation_level

get_indentation_level(line: str) -> int

Get the size of the indentation of a line.

Parameters:

Name	Type	Description	Default
`line`	`str`	The line to check.	required

Returns:

Name	Type	Description
`int`	`int`	The level of indentation. If the line is not indented, return 0.

get_size_of_code_block_backtick

get_size_of_code_block_backtick(line: str) -> int

Get the size of the backtick of a code block.

Parameters:

Name	Type	Description	Default
`line`	`str`	The line to check.	required

Returns:

Name	Type	Description
`int`	`int`	The size of the backtick. If the line is not a code block, return 0.

normalize_source_lines

normalize_source_lines(
    source: Union[str, List[str]],
) -> List[str]

Normalize the source field of a Jupyter cell into one line per element.

The nbformat spec allows source to be either a single string or a list of strings, and it does not require each list element to hold exactly one line. MMG parses documents line by line, so every Jupyter entry point must funnel the raw source through this function first. (Resolves the issue #35)

Line endings are preserved, so "".join() of the result reproduces the input.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[str]]`	The raw `source` field of a cell.	required

Returns:

Type	Description
`List[str]`	List[str]: A list in which each element holds exactly one line.

remove_emoji

remove_emoji(text: str) -> str

Remove all emojis from a given string.

remove_links

remove_links(text: str) -> str

Remove all links from a given string.

Python API

mmg.api

convert

convert_base_doc

convert_base_jupyter

mmg.config

Config dataclass

extract_config_from_md

mmg.health

DocChecker

HealthChecker

cli_log

health_check

mmg.toc

TocOptions

create_toc

parse_toc_options

mmg.utils

flag_code_block_lines

get_indentation_level

get_size_of_code_block_backtick

normalize_source_lines

remove_emoji

remove_links

Config `dataclass`