Python API

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

Tip

In this page, you can find references for core Python API that are frequently used in programming. You can see how to use the Python API listed here in API Usage Examples.

Python modules that are not listed here can be found in 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.