typstpy 0.0.1__py3-none-any.whl

typstpy/__init__.py

@@ -0,0 +1,18 @@
+from .functions import emph, figure, heading, image, par, strong, text
+from .param_types import Block, Content, Label, Length, Ratio, Relative
+
+__all__ = [
+    "emph",
+    "figure",
+    "heading",
+    "image",
+    "par",
+    "strong",
+    "text",
+    "Block",
+    "Content",
+    "Label",
+    "Length",
+    "Ratio",
+    "Relative",
+]

typstpy/functions.py

@@ -0,0 +1,269 @@
+from typing import Optional
+
+from cytoolz.curried import assoc, valfilter  # type:ignore
+from pymonad.reader import Pipe  # type:ignore
+
+from .param_types import Block, Content, Label, Length, Relative
+from .utils import RenderType, attach_func, render
+
+
+def text(
+    content: Block,
+    *,
+    font: Optional[str | tuple[str]] = None,
+    fallback: Optional[bool] = None,
+    size: Optional[Length] = None,
+) -> Block:
+    """Interface of `text` function in typst.
+
+    Args:
+        content (Block): Content in which all text is styled according to the other arguments.
+        font (Optional[str  |  tuple[str]], optional): A font family name or priority list of font family names. Defaults to None.
+        fallback (Optional[bool], optional): Whether to allow last resort font fallback when the primary font list contains no match. This lets Typst search through all available fonts for the most similar one that has the necessary glyphs. Defaults to None.
+        size (Optional[Length], optional): The size of the glyphs. Defaults to None.
+
+    Returns:
+        Block: Executable typst block.
+
+    Examples:
+        >>> text("Hello, World!", font="Arial", fallback=True)
+        '#text(font: "Arial", fallback: true)[Hello, World!]'
+        >>> text("Hello, World!", font=("Arial", "Times New Roman"), fallback=True)
+        '#text(font: ("Arial", "Times New Roman"), fallback: true)[Hello, World!]'
+        >>> text("Hello, World!", size=Length(12, "pt"))
+        '#text(size: 12pt)[Hello, World!]'
+    """
+    params = (
+        Pipe({"font": font, "fallback": fallback, "size": size})
+        .map(valfilter(lambda x: x is not None))
+        .flush()
+    )
+    if not params:
+        return content
+    return rf"#text({render(RenderType.DICT)(params)})[{content}]"
+
+
+def emph(content: Block) -> Block:
+    """Interface of `emph` function in typst.
+
+    Args:
+        content (Block): The content to emphasize.
+
+    Returns:
+        Block: Executable typst block.
+
+    Examples:
+        >>> emph("Hello, World!")
+        '#emph[Hello, World!]'
+    """
+    return rf"#emph[{content}]"
+
+
+def strong(content: Block, *, delta: Optional[int] = None) -> Block:
+    """Interface of `strong` function in typst.
+
+    Args:
+        content (Block): The content to strongly emphasize.
+        delta (Optional[int], optional): The delta to apply on the font weight. Defaults to None.
+
+    Returns:
+        Block: Executable typst block.
+
+    Examples:
+        >>> strong("Hello, World!")
+        '#strong[Hello, World!]'
+        >>> strong("Hello, World!", delta=300)
+        '#strong(delta: 300)[Hello, World!]'
+    """
+    params = Pipe({"delta": delta}).map(valfilter(lambda x: x is not None)).flush()
+    if not params:
+        return rf"#strong[{content}]"
+    return rf"#strong({render(RenderType.DICT)(params)})[{content}]"
+
+
+def par(
+    content: Block,
+    *,
+    leading: Optional[Length] = None,
+    justify: Optional[bool] = None,
+    linebreaks: Optional[str] = None,
+    first_line_indent: Optional[Length] = None,
+    hanging_indent: Optional[Length] = None,
+) -> Block:
+    """Interface of `par` function in typst.
+
+    Args:
+        content (Block): The contents of the paragraph.
+        leading (Optional[Length], optional): The spacing between lines. Defaults to None.
+        justify (Optional[bool], optional): Whether to justify text in its line. Defaults to None.
+        linebreaks (Optional[str], optional): How to determine line breaks. Options are "simple" and "optimized". Defaults to None.
+        first_line_indent (Optional[Length], optional): The indent the first line of a paragraph should have. Defaults to None.
+        hanging_indent (Optional[Length], optional): The indent all but the first line of a paragraph should have. Defaults to None.
+
+    Returns:
+        Block: Executable typst block.
+
+    Examples:
+        >>> par("Hello, World!", leading=Length(1.5, "em"))
+        '#par(leading: 1.5em)[Hello, World!]'
+        >>> par("Hello, World!", justify=True)
+        '#par(justify: true)[Hello, World!]'
+        >>> par("Hello, World!")
+        'Hello, World!'
+    """
+    if linebreaks and linebreaks not in ("simple", "optimized"):
+        raise ValueError(f"Invalid value for linebreaks: {linebreaks}.")
+    params = (
+        Pipe(
+            {
+                "leading": leading,
+                "justify": justify,
+                "linebreaks": linebreaks,
+                "first_line_indent": first_line_indent,
+                "hanging_indent": hanging_indent,
+            }
+        )
+        .map(valfilter(lambda x: x is not None))
+        .flush()
+    )
+    if not params:
+        return content
+    return rf"#par({render(RenderType.DICT)(params)})[{content}]"
+
+
+def heading(
+    content: Block,
+    *,
+    level: int = 1,
+    supplement: Optional[Content] = None,
+    numbering: Optional[str] = None,
+    label: Optional[Label] = None,
+) -> Block:
+    """Interface of `heading` function in typst.
+
+    Args:
+        content (Block): The heading's title.
+        level (int, optional): The absolute nesting depth of the heading, starting from one. Defaults to 1.
+        supplement (Optional[Content], optional): A supplement for the heading. Defaults to None.
+        numbering (Optional[str], optional): How to number the heading. Defaults to None.
+        label (Optional[Label], optional): Cross-reference for the heading. Defaults to None.
+
+    Returns:
+        Block: Executable typst block.
+
+    Examples:
+        >>> heading("Hello, World!", level=2, supplement=Content("Chapter"), label=Label("chap:chapter"))
+        '#heading(supplement: [Chapter], level: 2)[Hello, World!] <chap:chapter>'
+        >>> heading("Hello, World!", level=2)
+        '== Hello, World!'
+    """
+    params = (
+        Pipe({"supplement": supplement, "numbering": numbering})
+        .map(valfilter(lambda x: x is not None))
+        .flush()
+    )
+    if not params:
+        result = rf"{"="*level} {content}"
+    else:
+        result = rf"#heading({render(RenderType.DICT)(assoc(params,'level',level))})[{content}]"
+    if label:
+        result += f" {label}"
+    return result
+
+
+def image(
+    path: str,
+    *,
+    format: Optional[str] = None,
+    width: Optional[Relative] = None,
+    height: Optional[Relative] = None,
+    alt: Optional[str] = None,
+    fit: Optional[str] = None,
+) -> Block:
+    """Interface of `image` function in typst.
+
+    Args:
+        path (str): Path to an image file.
+        format (Optional[str], optional): The image's format. Detected automatically by default. Options are "png", "jpg", "gif", and "svg". Defaults to None.
+        width (Optional[Relative], optional): The width of the image. Defaults to None.
+        height (Optional[Relative], optional): The height of the image. Defaults to None.
+        alt (Optional[str], optional): A text describing the image. Defaults to None.
+        fit (Optional[str], optional): How the image should adjust itself to a given area (the area is defined by the width and height fields). Note that fit doesn't visually change anything if the area's aspect ratio is the same as the image's one. Options are "cover", "contain", and "stretch". Defaults to None.
+
+    Returns:
+        Block: Executable typst block.
+
+    Examples:
+        >>> image("image.png")
+        '#image("image.png")'
+        >>> image("image.png", format="png")
+        '#image("image.png", format: "png")'
+    """
+    if format and format not in ("png", "jpg", "gif", "svg"):
+        raise ValueError(f"Invalid value for format: {format}.")
+    if fit and fit not in ("cover", "contain", "stretch"):
+        raise ValueError(f"Invalid value for fit: {fit}.")
+    params = (
+        Pipe(
+            {"format": format, "width": width, "height": height, "alt": alt, "fit": fit}
+        )
+        .map(valfilter(lambda x: x is not None))
+        .flush()
+    )
+    if not params:
+        return rf"#image({render(RenderType.VALUE)(path)})"
+    return (
+        rf"#image({render(RenderType.VALUE)(path)}, {render(RenderType.DICT)(params)})"
+    )
+
+
+def _figure_caption(content: Block, *, separator: Optional[Content] = None) -> Content:
+    """Interface of `figure.caption` function in typst.
+
+    Args:
+        content (Block): The caption's body.
+        separator (Optional[Content], optional): The separator which will appear between the number and body. Defaults to None.
+
+    Returns:
+        Content: The caption's content.
+    """
+    params = (
+        Pipe({"separator": separator}).map(valfilter(lambda x: x is not None)).flush()
+    )
+    if not params:
+        return Content(content)
+    return Content(rf"#figure.caption({render(RenderType.DICT)(params)})[{content}]")
+
+
+@attach_func(_figure_caption, "caption")
+def figure(
+    content: Block, *, caption: Optional[Content] = None, label: Optional[Label] = None
+) -> Block:
+    """Interface of `figure` function in typst.
+
+    Args:
+        content (Block): The content of the figure. Often, an image.
+        caption (Optional[Content], optional): The figure's caption. Defaults to None.
+        label (Optional[Label], optional): Cross-reference for the figure. Defaults to None.
+
+    Returns:
+        Block: Executable typst block.
+
+    Examples:
+        >>> figure(image("image.png"))
+        '#figure(image("image.png"))'
+        >>> figure(image("image.png"), caption=Content("This is a figure."))
+        '#figure(image("image.png"), caption: [This is a figure.])'
+        >>> figure(image("image.png"), caption=Content("This is a figure."), label=Label("fig:figure"))
+        '#figure(image("image.png"), caption: [This is a figure.]) <fig:figure>'
+        >>> figure(image("image.png"), caption=figure.caption("This is a figure.", separator=Content("---")))
+        '#figure(image("image.png"), caption: figure.caption(separator: [---])[This is a figure.])'
+    """
+    params = Pipe({"caption": caption}).map(valfilter(lambda x: x is not None)).flush()
+    if not params:
+        result = rf"#figure({Content.examine_sharp(content)})"
+    else:
+        result = rf"#figure({Content.examine_sharp(content)}, {render(RenderType.DICT)(params)})"
+    if label:
+        result += f" {label}"
+    return result

typstpy/param_types.py

@@ -0,0 +1,178 @@
+"""Classes in this module should only be used as parameter types in the `functions` module."""
+
+from itertools import starmap
+from typing import TypeAlias, Union
+
+from attrs import field, frozen
+from cytoolz.curried import curry, map  # type:ignore
+from pymonad.reader import Pipe  # type:ignore
+
+from .utils import FormatType, format
+
+Block: TypeAlias = str
+"""Executable typst block."""
+
+
+@frozen
+class Content:
+    content: Block = field()
+
+    @content.validator
+    def _check_content(self, attribute, value):
+        # todo: Check if the content is executable typst block.
+        pass
+
+    def _can_simplify(self) -> bool:
+        return self.content.startswith("#")
+
+    @staticmethod
+    def examine_sharp(content: Block) -> str:
+        return content.lstrip("#")
+
+    def __str__(self) -> str:
+        if self._can_simplify():
+            return Content.examine_sharp(self.content)
+        return f"[{self.content}]"
+
+
+@frozen
+class Label:
+    label: str = field()
+
+    @label.validator
+    def _check_label(self, attribute, value):
+        # todo: Check for illegal characters in label.
+        pass
+
+    def __str__(self) -> str:
+        return f"<{self.label}>"
+
+
+@frozen
+class Length:
+    value: float = field(repr=format(FormatType.FLOAT))
+    unit: str = field()
+
+    @unit.validator
+    def _check_unit(self, attribute, value):
+        if value not in ("pt", "mm", "cm", "em"):
+            raise ValueError(f"Invalid unit: {value}.")
+
+    def __pos__(self) -> "Length":
+        return self
+
+    def __neg__(self) -> "Length":
+        return Length(-self.value, self.unit)
+
+    def __add__(self, other: Union["Length", "Ratio", "_Relative"]) -> "_Relative":
+        if isinstance(other, (Length, Ratio)):
+            return _Relative((self, other), ("+", "+"))
+        elif isinstance(other, _Relative):
+            return _Relative((self,) + other.items, ("+",) + other.signs)
+        else:
+            raise TypeError(
+                f"Unsupported operand type(s) for +: 'Length' and '{type(other)}'."
+            )
+
+    def __sub__(self, other: Union["Length", "Ratio", "_Relative"]) -> "_Relative":
+        if isinstance(other, (Length, Ratio)):
+            return _Relative((self, other), ("+", "-"))
+        elif isinstance(other, _Relative):
+            return _Relative((self,) + other.items, ("+",) + other.inverse_signs)
+        else:
+            raise TypeError(
+                f"Unsupported operand type(s) for -: 'Length' and '{type(other)}'."
+            )
+
+    def __str__(self) -> str:
+        return f"{format(FormatType.FLOAT)(self.value)}{self.unit}"
+
+
+@frozen
+class Ratio:
+    value: float = field(repr=format(FormatType.FLOAT))
+
+    def __pos__(self) -> "Ratio":
+        return self
+
+    def __neg__(self) -> "Ratio":
+        return Ratio(-self.value)
+
+    def __add__(self, other: Union[Length, "Ratio", "_Relative"]) -> "_Relative":
+        if isinstance(other, (Length, Ratio)):
+            return _Relative((self, other), ("+", "+"))
+        elif isinstance(other, _Relative):
+            return _Relative((self,) + other.items, ("+",) + other.signs)
+        else:
+            raise TypeError(
+                f"Unsupported operand type(s) for +: 'Ratio' and '{type(other)}'."
+            )
+
+    def __sub__(self, other: Union[Length, "Ratio", "_Relative"]) -> "_Relative":
+        if isinstance(other, (Length, Ratio)):
+            return _Relative((self, other), ("+", "-"))
+        elif isinstance(other, _Relative):
+            return _Relative((self,) + other.items, ("+",) + other.inverse_signs)
+        else:
+            raise TypeError(
+                f"Unsupported operand type(s) for -: 'Ratio' and '{type(other)}'."
+            )
+
+    def __str__(self) -> str:
+        return f"{format(FormatType.FLOAT)(self.value)}%"
+
+
+@frozen
+class _Relative:
+    items: tuple[Length | Ratio, ...] = field()
+    signs: tuple[str, ...] = field()
+
+    @property
+    def inverse_signs(self) -> tuple[str, ...]:
+        def inverse(sign: str) -> str:
+            match sign:
+                case "+":
+                    return "-"
+                case "-":
+                    return "+"
+                case _:
+                    raise ValueError(f"Invalid sign: {sign}.")
+
+        return Pipe(self.signs).map(map(inverse)).map(tuple).flush()
+
+    def __add__(self, other: Union[Length, Ratio, "_Relative"]) -> "_Relative":
+        if isinstance(other, (Length, Ratio)):
+            return _Relative(self.items + (other,), self.signs + ("+",))
+        elif isinstance(other, _Relative):
+            return _Relative(self.items + other.items, self.signs + other.signs)
+        else:
+            raise TypeError(
+                f"Unsupported operand type(s) for +: 'Relative' and '{type(other)}'."
+            )
+
+    def __sub__(self, other: Union[Length, Ratio, "_Relative"]) -> "_Relative":
+        if isinstance(other, (Length, Ratio)):
+            return _Relative(self.items + (other,), self.signs + ("-",))
+        elif isinstance(other, _Relative):
+            return _Relative(self.items + other.items, self.signs + other.inverse_signs)
+        else:
+            raise TypeError(
+                f"Unsupported operand type(s) for -: 'Relative' and '{type(other)}'."
+            )
+
+    def __str__(self) -> str:
+        return (
+            Pipe(zip(self.signs, self.items))
+            .map(curry(starmap)(lambda x, y: f"{x}{y}"))
+            .map(lambda x: ("".join(x)).lstrip("+"))
+            .map(
+                lambda x: x.replace("+-", "-")
+                .replace("--", "+")
+                .replace("-+", "-")
+                .replace("++", "+")
+            )
+            .flush()
+        )
+
+
+Relative: TypeAlias = Length | Ratio | _Relative

typstpy/utils.py

@@ -0,0 +1,88 @@
+from enum import Enum, auto
+from typing import Any, Callable, Optional
+
+from cytoolz.curried import curry, map  # type:ignore
+
+# region render
+
+
+class RenderType(Enum):
+    KEY = auto()
+    VALUE = auto()
+    DICT = auto()
+
+
+def _render(render_type: RenderType) -> Callable[[Any], str]:
+    def render_key(key: str) -> str:
+        return key.replace("_", "-")
+
+    def render_value(value: Any) -> str:
+        match value:
+            case bool():
+                return "true" if value else "false"
+            case str():
+                return f'"{value}"'
+            case tuple():
+                return f"({', '.join(map(render_value, value))})"
+            case _:
+                return str(value)
+
+    def render_dict(params: dict[str, Any]) -> str:
+        if not params:
+            return ""
+        return ", ".join(
+            f"{render_key(k)}: {render_value(v)}" for k, v in params.items()
+        )
+
+    match render_type:
+        case RenderType.KEY:
+            return render_key
+        case RenderType.VALUE:
+            return render_value
+        case RenderType.DICT:
+            return render_dict
+
+
+@curry
+def render(render_type: RenderType, target: Any) -> str:
+    return _render(render_type)(target)
+
+
+# endregion
+# region format
+
+
+class FormatType(Enum):
+    FLOAT = auto()
+
+
+def _format(format_type: FormatType) -> Callable[[Any], str]:
+    def format_float(value: float) -> str:
+        return f"{value:.2f}".rstrip("0").rstrip(".")
+
+    match format_type:
+        case FormatType.FLOAT:
+            return format_float
+
+
+@curry
+def format(format_type: FormatType, target: Any) -> str:
+    return _format(format_type)(target)
+
+
+# endregion
+# region decorator
+
+
+def attach_func(func: Callable, name: Optional[str] = None) -> Callable:
+    def wrapper(_func: Callable) -> Callable:
+        _name = name if name else _func.__name__
+        if _name.startswith("_"):
+            raise ValueError(f"Invalid name: {_name}.")
+        setattr(_func, _name, func)
+        return _func
+
+    return wrapper
+
+
+# endregion

typstpy-0.0.1.dist-info/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 chenjunhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typstpy-0.0.1.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.1
+Name: typstpy
+Version: 0.0.1
+Summary: Python interface to generate Typst code.
+License: MIT
+Author: chenjunhan
+Author-email: beibingyangliuying@foxmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: attrs (>=24.2.0,<25.0.0)
+Requires-Dist: cytoolz (>=0.12.3,<0.13.0)
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: pymonad (>=2.4.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# python-typst
+
+`python-typst` is a library for generating executable typst code (See [typst repository](https://github.com/typst/typst) and [typst documentation](https://typst.app/docs/) for more information).
+It is written primarily in functional programming paradigm with some OOP content.
+
+This package provides the interfaces in a way that is as close as possible to typst's native functions.
+Through `python-typst` and other data processing packages, you can generate data reports quickly.
+
+Contributions are welcome.
+
+## Installation
+
+## Examples
+
+```python
+>>> from typstpy import emph, figure, heading, image, par, strong, text, Block, Content, Label, Length, Ratio, Relative
+>>> text("Hello, World!", font="Arial", fallback=True)
+'#text(font: "Arial", fallback: true)[Hello, World!]'
+>>> text("Hello, World!", font=("Arial", "Times New Roman"), fallback=True)
+'#text(font: ("Arial", "Times New Roman"), fallback: true)[Hello, World!]'
+>>> text("Hello, World!", size=Length(12, "pt"))
+'#text(size: 12pt)[Hello, World!]'
+>>> emph("Hello, World!")
+'#emph[Hello, World!]'
+>>> strong("Hello, World!")
+'#strong[Hello, World!]'
+>>> strong("Hello, World!", delta=300)
+'#strong(delta: 300)[Hello, World!]'
+>>> par("Hello, World!", leading=Length(1.5, "em"))
+'#par(leading: 1.5em)[Hello, World!]'
+>>> par("Hello, World!", justify=True)
+'#par(justify: true)[Hello, World!]'
+>>> par("Hello, World!")
+'Hello, World!'
+>>> heading("Hello, World!", level=2, supplement=Content("Chapter"), label=Label("chap:chapter"))
+'#heading(supplement: [Chapter], level: 2)[Hello, World!] <chap:chapter>'
+>>> heading("Hello, World!", level=2)
+'== Hello, World!'
+>>> image("image.png")
+'#image("image.png")'
+>>> image("image.png", format="png")
+'#image("image.png", format: "png")'
+>>> figure(image("image.png"))
+'#figure(image("image.png"))'
+>>> figure(image("image.png"), caption=Content("This is a figure."))
+'#figure(image("image.png"), caption: [This is a figure.])'
+>>> figure(image("image.png"), caption=Content("This is a figure."), label=Label("fig:figure"))
+'#figure(image("image.png"), caption: [This is a figure.]) <fig:figure>'
+>>> figure(image("image.png"), caption=figure.caption("This is a figure.", separator=Content("---")))
+'#figure(image("image.png"), caption: figure.caption(separator: [---])[This is a figure.])'
+```
+
+## ChangeLog
+

typstpy-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+typstpy/__init__.py,sha256=VPpR_5JxwsXXlhAHNizkF6Upxotk7L6kB4zdnOo0TWc,351
+typstpy/functions.py,sha256=Hmil81Dex7T0wlWGRmaxVjnqyxrh4ic1Qmhfv3kI-A4,10439
+typstpy/param_types.py,sha256=a16Fb3DiYJvqI_h1pnBWb24cPBckr38VEcg8xWCUsXo,5879
+typstpy/utils.py,sha256=dLYTZFpOIqMVwZ22lamNcMAtifMpd18vhfZblPGigh4,2132
+typstpy-0.0.1.dist-info/LICENSE.txt,sha256=fNIn9UAyIuqgCgEHHGPcmDoRAZFt5wLULxMvZCv2-rk,1086
+typstpy-0.0.1.dist-info/METADATA,sha256=Mwzi3yL1fMMbRBJzdoj2KIdTCwZ4ttMDZwkjexLI-sI,2893
+typstpy-0.0.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+typstpy-0.0.1.dist-info/RECORD,,

typstpy-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any