Python API

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

Note

La référence de l'API est générée à partir de Python Docstring, donc elle n'est disponible qu'en anglais.

Tip

Dans cette page, vous pouvez trouver des références pour les API Python de base qui sont fréquemment utilisées en programmation. Vous pouvez voir comment utiliser les API Python listées ici dans Exemples d'Utilisation de l'API.

Les modules Python qui ne sont pas listés ici peuvent être trouvés dans 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`