htmy下載 - htmy源代碼下載

htmy

網站數據

v0.3.6

下載

源代碼：https：//github.com/volfpeter/htmy

文檔和示例：https：//volfpeter.github.io/htmy

`htmy`

異步，純淨的python渲染引擎。

關鍵功能

首先，您可以充分利用現代異步工具。
強大的，類似於反應的上下文支持，因此您可以避免支撐。
與裝飾器語法的同步和異步函數組件。
所有基線HTML標籤內置。
使用自定義工具的降級支持。
異步，基於JSON的國際化。
內置的，易於使用的ErrorBoundary組件，用於優雅的錯誤處理。
未經封閉式：使用您選擇的後端，CSS和JS框架，即您想要使用它們的方式。
從渲染引擎到組件，格式和上下文管理，一切都可以自定義。
自動和可自定義的屬性名稱轉換從蛇盒轉換為烤肉箱。
全型。

安裝

該包在PYPI上可用，可以安裝：

$ pip install htmy

概念

從渲染引擎本身到內置組件，整個庫都是圍繞一些簡單的協議和少數簡單的公用事業類構建的。這意味著您可以輕鬆自定義，擴展或替換庫中的所有內容。是的，甚至是渲染引擎。其餘部分將繼續按預期工作。

另外，庫不依賴高級Python功能，例如元組或描述符。也沒有復雜的基礎類別。即使是初級工程師也可以理解，開發和調試與htmy構建的應用程序。

成分

每個具有同步或異步htmy(context: Context) -> Component方法是htmy組件（從技術上講是HTMYComponentType ）。字符串也是組件，也是HTMYComponentType或字符串對象的列表或元組。

使用此方法名稱可以使您的任何業務對象（從TypedDicts或pydantic模型到ORM類）轉換為組件，而不必擔心名稱與其他工具相撞。

異步支持使得可以在組件中加載數據或執行異步業務邏輯。在某些情況下，這可以減少您需要編寫的樣板量，還可以自由以任何方式分配渲染和非渲染邏輯。

例子：

 from dataclasses import dataclass

from htmy import Component , Context , html

@ dataclass ( frozen = True , kw_only = True , slots = True )
class User :
    username : str
    name : str
    email : str

    async def is_admin ( self ) -> bool :
        return False

class UserRow ( User ):
    async def htmy ( self , context : Context ) -> Component :
        role = "admin" if await self . is_admin () else "restricted"
        return html . tr (
            html . td ( self . username ),
            html . td ( self . name ),
            html . td ( html . a ( self . email , href = f"mailto: { self . email } " )),
            html . td ( role )
        )

@ dataclass ( frozen = True , kw_only = True , slots = True )
class UserRows :
    users : list [ User ]
    def htmy ( self , context : Context ) -> Component :
        # Note that a list is returned here. A list or tuple of `HTMYComponentType | str` objects is also a component.
        return [ UserRow ( username = u . username , name = u . name , email = u . email ) for u in self . users ]

user_table = html . table (
    UserRows (
        users = [
            User ( username = "Foo" , name = "Foo" , email = "[email protected]" ),
            User ( username = "Bar" , name = "Bar" , email = "[email protected]" ),
        ]
    )
)

htmy還提供了一個@component Decorator，可用於同步或異步my_component(props: MyProps, context: Context) -> Component函數將它們轉換為組件（保留props鍵入）。

這是與上述相同的示例，但具有函數組件：

 from dataclasses import dataclass

from htmy import Component , Context , component , html

@ dataclass ( frozen = True , kw_only = True , slots = True )
class User :
    username : str
    name : str
    email : str

    async def is_admin ( self ) -> bool :
        return False

@ component
async def user_row ( user : User , context : Context ) -> Component :
    # The first argument of function components is their "props", the data they need.
    # The second argument is the rendering context.
    role = "admin" if await user . is_admin () else "restricted"
    return html . tr (
        html . td ( user . username ),
        html . td ( user . name ),
        html . td ( html . a ( user . email , href = f"mailto: { user . email } " )),
        html . td ( role )
    )

@ component
def user_rows ( users : list [ User ], context : Context ) -> Component :
    # Nothing to await in this component, so it's sync.
    # Note that we only pass the "props" to the user_row() component (well, function component wrapper).
    # The context will be passed to the wrapper during rendering.
    return [ user_row ( user ) for user in users ]

user_table = html . table (
    user_rows (
        [
            User ( username = "Foo" , name = "Foo" , email = "[email protected]" ),
            User ( username = "Bar" , name = "Bar" , email = "[email protected]" ),
        ]
    )
)

內置組件

htmy為HTML和其他用例都有豐富的內置實用程序和組件：

html模塊：一組基線HTML標籤。
md ：用於加載，解析，轉換和渲染Markdown內容的MarkdownParser實用程序和MD組件。
i18n ：基於JSON的異步實用程序。
BaseTag ， TagWithProps ， Tag ， WildcardTag ：自定義XML標籤的基類。
ErrorBoundary ， Fragment ， SafeStr ， WithContext ：用於錯誤處理的實用程序，組件包裝器，上下文提供商和格式。
Snippet ：用於從文件系統加載和自定義文檔摘要的實用程序類。
etree.ETreeConverter ：將XML轉換為組件樹的實用程序，並支持自定義HTMY組件。

渲染

htmy.HTMY是庫的內置，默認的渲染器。

如果您在諸如FastApi之類的異步網絡框架中使用庫，那麼您已經處於異步環境中，因此您可以簡單地渲染組件： await HTMY().render(my_root_component) 。

如果您試圖在同步環境中運行渲染器，例如本地腳本或CLI，則首先需要將渲染器包裝在異步任務中，並使用asyncio.run()執行該任務：

 import asyncio

from htmy import HTMY , html

async def render_page () -> None :
    page = (
        html . DOCTYPE . html ,
        html . html (
            html . body (
                html . h1 ( "Hello World!" ),
                html . p ( "This page was rendered by " , html . code ( "htmy" )),
            ),
        )
    )

    result = await HTMY (). render ( page )
    print ( result )


if __name__ == "__main__" :
    asyncio . run ( render_page ())

情境

從上面的代碼示例中可以看到，每個組件都有一個context: Context參數，我們迄今尚未使用。上下文是一種與組件的整個子樹共享數據的方法，而無需“支撐鑽探”。

上下文（從技術上講， Mapping ）完全由渲染器管理。上下文提供商組件（具有同步或異步htmy_context() -> Context方法的任何類）將新數據添加到上下文中，以使其可用於其子樹中的組件，並且組件可以簡單地從上下文中獲取所需的東西。

上下文中可以使用的內容沒有限制，可以用於應用程序所需的任何內容，例如使當前用戶，UI首選項，主題或格式用於組件。實際上，內置組件（如果包含一個組件）將其Formatter從上下文中獲取，以便可以自定義標記屬性名稱和值格式。

這是一個示例上下文提供商和消費者實施：

 import asyncio

from htmy import HTMY , Component , ComponentType , Context , component , html

class UserContext :
    def __init__ ( self , * children : ComponentType , username : str , theme : str ) -> None :
        self . _children = children
        self . username = username
        self . theme = theme

    def htmy_context ( self ) -> Context :
        # Context provider implementation.
        return { UserContext : self }

    def htmy ( self , context : Context ) -> Component :
        # Context providers must also be components, as they just
        # wrap some children components in their context.
        return self . _children

    @ classmethod
    def from_context ( cls , context : Context ) -> "UserContext" :
        user_context = context [ cls ]
        if isinstance ( user_context , UserContext ):
            return user_context

        raise TypeError ( "Invalid user context." )

@ component
def welcome_page ( text : str , context : Context ) -> Component :
    # Get user information from the context.
    user = UserContext . from_context ( context )
    return (
        html . DOCTYPE . html ,
        html . html (
            html . body (
                html . h1 ( text , html . strong ( user . username )),
                data_theme = user . theme ,
            ),
        ),
    )

async def render_welcome_page () -> None :
    page = UserContext (
        welcome_page ( "Welcome back " ),
        username = "John" ,
        theme = "dark" ,
    )

    result = await HTMY (). render ( page )
    print ( result )

if __name__ == "__main__" :
    asyncio . run ( render_welcome_page ())

當然，您可以依靠內置上下文相關的實用程序（例如ContextAware或WithContext類），以方便且打字的上下文使用較少的樣板代碼。

格式化

如前所述，內置Formatter類別負責標記屬性名稱和值格式。您可以僅通過擴展此類或在其實例中添加新規則，然後將自定義實例添加到上下文中，直接在HTMY或HTMY.render()或上下文提供商組件中添加自定義實例，然後將自定義實例添加到上下文中。

這些是默認標籤屬性格式規則：

除非屬性名稱以下劃線啟動或結束，否則下劃線將轉換為屬性名稱中的破折號（ _ > - ），在這種情況下，刪除了前導和尾隨下劃線並保留其餘的屬性名稱。例如， data_theme="dark"將轉換為data-theme="dark" ，但是_data_theme="dark"最終將以data_theme =“ dark”中的文本中的data_theme="dark" 。更重要的是class_="text-danger" ， _class="text-danger" ， _class__="text-danger"均轉換為class="text-danger" ， _for="my-input"或for_="my_input"將變成for="my-input" 。
bool屬性值轉換為字符串（ "true"和"false" ）。
XBool.true屬性值將轉換為一個空字符串，然後跳過XBool.false值（僅呈現屬性名稱）。
date和datetime屬性值轉換為ISO字符串。

誤差邊界

如果您希望應用程序優雅地失敗（例如顯示錯誤消息），而不是增加HTTP錯誤，則該ErrorBoundary組件很有用。

錯誤邊界包裹組件組件子樹。當渲染器遇到ErrorBoundary組件時，它將嘗試渲染其包裹的內容。如果在ErrorBoundary的子樹中的任何時刻渲染失敗，並且渲染器將自動歸還給您分配給ErrorBoundary的fallback屬性的組件。

可選地，您可以定義錯誤邊界可以處理哪些錯誤，從而使您對錯誤處理進行良好的控制。

同步還是異步？

通常，如果必須等待一些異步調用，則應是異步。

如果組件執行潛在的“長期運行”同步呼叫，則強烈建議將呼叫的呼叫委託給工人線程等待它（從而使組件異步）。例如，可以使用anyio的to_thread實用程序， starlette 's（或fastapi 's） run_in_threadpool()等。這裡的目標是避免阻止Asyncio事件循環，因為這可能導致性能問題。

在所有其他情況下，最好使用同步組件。