Python API

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

ご案内

APIリファレンスはPython Docstringから生成されたため、英語のみ提供されています。

Tip

このページでは、プログラミングで頻繁に使用されるコアPython APIのリファレンスを見つけることができます。ここにリストされているPython APIの使用方法については、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.	`field(default_factory=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

create_toc

create_toc(
    toc_options: Tuple[int, int, bool], doc: List[str]
) -> List[str]

Create a table of contents.

Parameters:

Name	Type	Description	Default
`toc_options`	`Tuple[int, int, bool]`	(min_level, max_level, no_emoji)	required
`doc`	`List[str]`	The markdown string to parse.	required

Returns:

Type	Description
`List[str]`	List[str]: The table of contents.

parse_toc_options

parse_toc_options(toc_line: str) -> Tuple[int, int, bool]

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. or If the level option is invalid.

Returns:

Type	Description
`Tuple[int, int, bool]`	Tuple[int, int, bool]: (min_level, max_level, no_emoji)

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.

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

create_toc

parse_toc_options

mmg.utils

flag_code_block_lines

get_indentation_level

get_size_of_code_block_backtick

remove_emoji

remove_links

Config `dataclass`