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.	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.