Skip to content

Modules

EsaMdfier

Bases: Mdfier

A class to modify Markdown files and upload images to Esa.

Parameters:

Name Type Description Default
post_fullname Optional[str]

The full name of the post to modify.

 None
post_number Optional[int]

The number of the post to update.

 None
esa_team Optional[str]

The name of the Esa team. Defaults to None. you can set this param or the environment variable ESA_TEAM.

 None

Raises:

Type Description
ValueError

If esa_team param or the environment variable ESA_TEAM is not set.

Examples:

>>> from mdfy import MdImage, MdLink, MdText
>>> from mdfy_esa import EsaMdfier
>>> contents = [
...     MdText("This is a test article."),
...     MdImage(src="example/test_image.png"),
...     MdLink(url="example/dummy.pdf"),
... ]
>>> mdfier = EsaMdfier(post_fullname="note/me/My Test Article", esa_team="test_team")
>>> mdfier.write(contents=contents)
Source code in mdfy_esa/mdfy_esa.py 
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
class EsaMdfier(Mdfier):
    """A class to modify Markdown files and upload images to Esa.

    Args:
        post_fullname (Optional[str], optional): The full name of the post to modify.
        post_number (Optional[int], optional): The number of the post to update.
        esa_team (Optional[str], optional): The name of the Esa team. Defaults to None.
            you can set this param or the environment variable ESA_TEAM.

    Raises:
        ValueError: If esa_team param or the environment variable ESA_TEAM is not set.

    Examples:
        >>> from mdfy import MdImage, MdLink, MdText
        >>> from mdfy_esa import EsaMdfier
        >>> contents = [
        ...     MdText("This is a test article."),
        ...     MdImage(src="example/test_image.png"),
        ...     MdLink(url="example/dummy.pdf"),
        ... ]
        >>> mdfier = EsaMdfier(post_fullname="note/me/My Test Article", esa_team="test_team")
        >>> mdfier.write(contents=contents)
    """

    def __init__(
        self,
        post_fullname: Optional[str] = None,
        post_number: Optional[int] = None,
        esa_team: Optional[str] = None,
    ) -> None:
        """Initializes the EsaMdfier class.

        Args:
            post_fullname (Optional[str], optional): The path to the post to modify.
            post_number (Optional[int], optional): The number of the post to update.
            esa_team (Optional[str], optional): The name of the Esa team. Defaults to None.
        """
        self.post_fullname = post_fullname
        self.post_number = post_number
        if self.post_fullname is None and self.post_number is None:
            raise ValueError("Either post_fullname or post_number must be set. Please set one of them.")

        self.team = os.environ['ESA_TEAM'] if "ESA_TEAM" in os.environ else esa_team
        if self.team is None:
            raise ValueError("ESA_TEAM is not set. Please set esa_team param or the environment variable ESA_TEAM.")

        self.client = piyo.Client(current_team=self.team)

    def stringify_element(self, element: Union[MdElement, str]) -> str:
        """Converts the given element to a string.

        Args:
            element (Union[MdElement, str]): The element to convert.

        Returns:
            str: The converted string.
        """
        if isinstance(element, MdImage):
            url = self.client.upload_file(element.src)
            element.src = url
        elif isinstance(element, MdLink):
            parsed_result = urlparse(element.url)
            if parsed_result.scheme == "":
                url = self.client.upload_file(element.url)
            elif parsed_result.scheme == "file":
                url = self.client.upload_file(parsed_result.path)
            element.url = url
        return str(element)

    def write(
        self,
        contents: Union[List[Union[str, MdElement]], MdElement],
        post_params: Dict[str, Any] = {},
        **payloads: Optional[Dict[str, Any]],
    ) -> Dict[str, Any]:
        """post the given Markdown content to esa.io.

        Args:
            contents (Union[List[Union[str, MdElement]], MdElement]):
                The Markdown content to write to the file.
            post_params (Dict[str, Any], optional): Additional parameters for the post. see https://docs.esa.io/posts/102#POST%20/v1/teams/:team_name/posts. Defaults to {}.
            **payloads (Optional[Dict[str, Any]]): Additional parameters for piyo see https://github.com/argonism/piyo/blob/master/piyo/client.py#L112.
        """

        if not isinstance(contents, list):
            contents = [contents]

        markdown = ""
        for content in contents:
            content_md = self.stringify_element(content)
            markdown += content_md + "\n"

        if self.post_fullname:
            post_data = {"post": {"name": self.post_fullname, "body_md": markdown, **post_params}}
            return self.client.create_post(post_data, **payloads)
        elif self.post_number:
            update_data = {"post": {"body_md": markdown, **post_params}}
            return self.client.update_post(self.post_number, update_data, **payloads)
        else:
            raise ValueError("Either post_fullname or post_number must be set. Please set one of them.")

__init__(post_fullname=None, post_number=None, esa_team=None)

Initializes the EsaMdfier class.

Parameters:

Name Type Description Default
post_fullname Optional[str]

The path to the post to modify.

 None
post_number Optional[int]

The number of the post to update.

 None
esa_team Optional[str]

The name of the Esa team. Defaults to None.

 None
Source code in mdfy_esa/mdfy_esa.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
def __init__(
    self,
    post_fullname: Optional[str] = None,
    post_number: Optional[int] = None,
    esa_team: Optional[str] = None,
) -> None:
    """Initializes the EsaMdfier class.

    Args:
        post_fullname (Optional[str], optional): The path to the post to modify.
        post_number (Optional[int], optional): The number of the post to update.
        esa_team (Optional[str], optional): The name of the Esa team. Defaults to None.
    """
    self.post_fullname = post_fullname
    self.post_number = post_number
    if self.post_fullname is None and self.post_number is None:
        raise ValueError("Either post_fullname or post_number must be set. Please set one of them.")

    self.team = os.environ['ESA_TEAM'] if "ESA_TEAM" in os.environ else esa_team
    if self.team is None:
        raise ValueError("ESA_TEAM is not set. Please set esa_team param or the environment variable ESA_TEAM.")

    self.client = piyo.Client(current_team=self.team)

stringify_element(element)

Converts the given element to a string.

Parameters:

Name Type Description Default
element Union[MdElement, str]

The element to convert.

 required

Returns:

Name Type Description
str str

The converted string.
Source code in mdfy_esa/mdfy_esa.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def stringify_element(self, element: Union[MdElement, str]) -> str:
    """Converts the given element to a string.

    Args:
        element (Union[MdElement, str]): The element to convert.

    Returns:
        str: The converted string.
    """
    if isinstance(element, MdImage):
        url = self.client.upload_file(element.src)
        element.src = url
    elif isinstance(element, MdLink):
        parsed_result = urlparse(element.url)
        if parsed_result.scheme == "":
            url = self.client.upload_file(element.url)
        elif parsed_result.scheme == "file":
            url = self.client.upload_file(parsed_result.path)
        element.url = url
    return str(element)

write(contents, post_params={}, **payloads)

post the given Markdown content to esa.io.

Parameters:

Name Type Description Default
contents Union[List[Union[str, MdElement]], MdElement]

The Markdown content to write to the file.

 required
post_params Dict[str, Any]

Additional parameters for the post. see https://docs.esa.io/posts/102#POST%20/v1/teams/:team_name/posts. Defaults to {}.

 {}
**payloads Optional[Dict[str, Any]]

Additional parameters for piyo see https://github.com/argonism/piyo/blob/master/piyo/client.py#L112.

 {}
Source code in mdfy_esa/mdfy_esa.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def write(
    self,
    contents: Union[List[Union[str, MdElement]], MdElement],
    post_params: Dict[str, Any] = {},
    **payloads: Optional[Dict[str, Any]],
) -> Dict[str, Any]:
    """post the given Markdown content to esa.io.

    Args:
        contents (Union[List[Union[str, MdElement]], MdElement]):
            The Markdown content to write to the file.
        post_params (Dict[str, Any], optional): Additional parameters for the post. see https://docs.esa.io/posts/102#POST%20/v1/teams/:team_name/posts. Defaults to {}.
        **payloads (Optional[Dict[str, Any]]): Additional parameters for piyo see https://github.com/argonism/piyo/blob/master/piyo/client.py#L112.
    """

    if not isinstance(contents, list):
        contents = [contents]

    markdown = ""
    for content in contents:
        content_md = self.stringify_element(content)
        markdown += content_md + "\n"

    if self.post_fullname:
        post_data = {"post": {"name": self.post_fullname, "body_md": markdown, **post_params}}
        return self.client.create_post(post_data, **payloads)
    elif self.post_number:
        update_data = {"post": {"body_md": markdown, **post_params}}
        return self.client.update_post(self.post_number, update_data, **payloads)
    else:
        raise ValueError("Either post_fullname or post_number must be set. Please set one of them.")