htmy 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

htmy/function_component.py

@@ -4,25 +4,22 @@ import asyncio
 from collections.abc import Callable, Coroutine
 from typing import Any, Protocol, TypeAlias, overload
 
-from .typing import AsyncComponent, Component, Context, SyncComponent, T
+from .typing import AsyncComponent, Component, Context, SyncComponent
+from .typing import T as TProps
+from .typing import U as TSelf
 
-# -- Typing for "full" function components.
+# -- Typing for "full" function components and context only method components.
 
-_SyncFunctionComponent: TypeAlias = Callable[[T, Context], Component]
+_SyncFunctionComponent: TypeAlias = Callable[[TProps, Context], Component]
 """
 Protocol definition for sync function components that have both a properties and a context argument.
 """
 
-_AsyncFunctionComponent: TypeAlias = Callable[[T, Context], Coroutine[Any, Any, Component]]
+_AsyncFunctionComponent: TypeAlias = Callable[[TProps, Context], Coroutine[Any, Any, Component]]
 """
 Protocol definition for async function components that have both a properties and a context argument.
 """
 
-_FunctionComponent: TypeAlias = _SyncFunctionComponent[T] | _AsyncFunctionComponent[T]
-"""
-Function component type that has both a properties and a context argument.
-"""
-
 # -- Typing for context-only function components.
 
 _ContextOnlySyncFunctionComponent: TypeAlias = Callable[[Context], Component]
@@ -55,22 +52,22 @@ class _DecoratedContextOnlyAsyncFunctionComponent(SyncComponent, Protocol):
     def __call__(self) -> SyncComponent: ...
 
 
-_ContextOnlyFunctionComponent: TypeAlias = (
-    _ContextOnlySyncFunctionComponent | _ContextOnlyAsyncFunctionComponent
-)
+# -- Typing for "full" method components.
+
+_SyncMethodComponent: TypeAlias = Callable[[TSelf, TProps, Context], Component]
 """
-Function component type that only accepts a context argument.
+Protocol definition for sync method components that have both a properties and a context argument.
 """
 
-_DecoratedContextOnlyFunction: TypeAlias = (
-    _DecoratedContextOnlySyncFunctionComponent | _DecoratedContextOnlyAsyncFunctionComponent
-)
+_AsyncMethodComponent: TypeAlias = Callable[[TSelf, TProps, Context], Coroutine[Any, Any, Component]]
 """
-Protocol definition for sync or async components that are also callable, and return a sync
-or async component when called.
+Protocol definition for async method components that have both a properties and a context argument.
 """
 
 
+# -- Component decorators.
+
+
 class ComponentDecorators:
     """
     Function component decorators.
@@ -78,18 +75,18 @@ class ComponentDecorators:
 
     __slots__ = ()
 
-    # -- FunctionComponent decorator.
+    # -- Function component decorator.
 
     @overload
-    def __call__(self, func: _SyncFunctionComponent[T]) -> Callable[[T], SyncComponent]: ...
+    def __call__(self, func: _SyncFunctionComponent[TProps]) -> Callable[[TProps], SyncComponent]: ...
 
     @overload
-    def __call__(self, func: _AsyncFunctionComponent[T]) -> Callable[[T], AsyncComponent]: ...
+    def __call__(self, func: _AsyncFunctionComponent[TProps]) -> Callable[[TProps], AsyncComponent]: ...
 
     def __call__(
         self,
-        func: _FunctionComponent[T],
-    ) -> Callable[[T], SyncComponent] | Callable[[T], AsyncComponent]:
+        func: _SyncFunctionComponent[TProps] | _AsyncFunctionComponent[TProps],
+    ) -> Callable[[TProps], SyncComponent] | Callable[[TProps], AsyncComponent]:
         """
         Decorator that converts the decorated function into one that must be called with
         the function component's properties and returns a component instance.
@@ -104,7 +101,7 @@ class ComponentDecorators:
         def my_component(props: int, context: Context) -> Component:
             return html.p(f"Value: {props}")
 
-        async def render():
+        async def render() -> str:
            return await Renderer().render(
                my_component(42)
            )
@@ -121,7 +118,7 @@ class ComponentDecorators:
 
         if asyncio.iscoroutinefunction(func):
 
-            def async_wrapper(props: T) -> AsyncComponent:
+            def async_wrapper(props: TProps) -> AsyncComponent:
                 # This function must be async, in case the renderer inspects it to decide how to handle it.
                 async def component(context: Context) -> Component:
                     return await func(props, context)  # type: ignore[no-any-return]
@@ -132,7 +129,7 @@ class ComponentDecorators:
             return async_wrapper
         else:
 
-            def sync_wrapper(props: T) -> SyncComponent:
+            def sync_wrapper(props: TProps) -> SyncComponent:
                 def component(context: Context) -> Component:
                     return func(props, context)  # type: ignore[return-value]
 
@@ -142,15 +139,15 @@ class ComponentDecorators:
             return sync_wrapper
 
     @overload
-    def function(self, func: _SyncFunctionComponent[T]) -> Callable[[T], SyncComponent]: ...
+    def function(self, func: _SyncFunctionComponent[TProps]) -> Callable[[TProps], SyncComponent]: ...
 
     @overload
-    def function(self, func: _AsyncFunctionComponent[T]) -> Callable[[T], AsyncComponent]: ...
+    def function(self, func: _AsyncFunctionComponent[TProps]) -> Callable[[TProps], AsyncComponent]: ...
 
     def function(
         self,
-        func: _FunctionComponent[T],
-    ) -> Callable[[T], SyncComponent] | Callable[[T], AsyncComponent]:
+        func: _SyncFunctionComponent[TProps] | _AsyncFunctionComponent[TProps],
+    ) -> Callable[[TProps], SyncComponent] | Callable[[TProps], AsyncComponent]:
         """
         Decorator that converts the decorated function into one that must be called with
         the function component's properties and returns a component instance.
@@ -167,7 +164,7 @@ class ComponentDecorators:
         def my_component(props: int, context: Context) -> Component:
             return html.p(f"Value: {props}")
 
-        async def render():
+        async def render() -> str:
            return await Renderer().render(
                my_component(42)
            )
@@ -182,7 +179,7 @@ class ComponentDecorators:
         """
         return self(func)
 
-    # -- ContextOnlyFunctionComponent decorator.
+    # -- Context-only function component decorator.
 
     @overload
     def context_only(
@@ -196,7 +193,7 @@ class ComponentDecorators:
 
     def context_only(
         self,
-        func: _ContextOnlyFunctionComponent,
+        func: _ContextOnlySyncFunctionComponent | _ContextOnlyAsyncFunctionComponent,
     ) -> _DecoratedContextOnlySyncFunctionComponent | _DecoratedContextOnlyAsyncFunctionComponent:
         """
         Decorator that converts the decorated function into a component.
@@ -204,19 +201,16 @@ class ComponentDecorators:
         If used on an async function, the resulting component will also be async;
         otherwise it will be sync.
 
-        The decorated function will be both a component object and a callable that returns a
-        component object, so it can be used in the component tree both with and without the
-        call signature:
+        Example:
 
         ```python
         @component.context_only
         def my_component(ctx):
             return "Context only function component."
 
-        async def render():
+        async def render() -> str:
            return await Renderer().render(
-               my_component(),  # With call signature.
-               my_component,  # Without call signature.
+               my_component()
            )
         ```
 
@@ -231,9 +225,139 @@ class ComponentDecorators:
             func.htmy = func  # type: ignore[union-attr]
             return func  # type: ignore[return-value]
 
+        # This assignment adds support for context-only function components without call signature.
         wrapper.htmy = func  # type: ignore[attr-defined]
         return wrapper  # type: ignore[return-value]
 
+    # -- Method component decorator.
+
+    @overload
+    def method(
+        self, func: _SyncMethodComponent[TSelf, TProps]
+    ) -> Callable[[TSelf, TProps], SyncComponent]: ...
+
+    @overload
+    def method(
+        self, func: _AsyncMethodComponent[TSelf, TProps]
+    ) -> Callable[[TSelf, TProps], AsyncComponent]: ...
+
+    def method(
+        self,
+        func: _SyncMethodComponent[TSelf, TProps] | _AsyncMethodComponent[TSelf, TProps],
+    ) -> Callable[[TSelf, TProps], SyncComponent] | Callable[[TSelf, TProps], AsyncComponent]:
+        """
+        Decorator that converts the decorated method into one that must be called with
+        the method component's properties and returns a component instance.
+
+        If used on an async method, the resulting component will also be async;
+        otherwise it will be sync.
+
+        Example:
+
+        ```python
+        @dataclass
+        class MyBusinessObject:
+            message: str
+
+            @component.method
+            def paragraph(self, props: int, context: Context) -> Component:
+                return html.p(f"{self.message} {props}")
+
+
+        async def render() -> str:
+            return await Renderer().render(
+                MyBusinessObject("Hi!").paragraph(42)
+            )
+        ```
+
+        Arguments:
+            func: The decorated method.
+
+        Returns:
+            A method that must be called with the method component's properties and
+            returns a component instance. (Or loosly speaking, an `HTMYComponentType` which
+            can be "instantiated" with the method component's properties.)
+        """
+        if asyncio.iscoroutinefunction(func):
+
+            def async_wrapper(self: TSelf, props: TProps) -> AsyncComponent:
+                # This function must be async, in case the renderer inspects it to decide how to handle it.
+                async def component(context: Context) -> Component:
+                    return await func(self, props, context)  # type: ignore[no-any-return]
+
+                component.htmy = component  # type: ignore[attr-defined]
+                return component  # type: ignore[return-value]
+
+            return async_wrapper
+        else:
+
+            def sync_wrapper(self: TSelf, props: TProps) -> SyncComponent:
+                def component(context: Context) -> Component:
+                    return func(self, props, context)  # type: ignore[return-value]
+
+                component.htmy = component  # type: ignore[attr-defined]
+                return component  # type: ignore[return-value]
+
+            return sync_wrapper
+
+    # -- Context-only function component decorator.
+
+    @overload
+    def context_only_method(
+        self, func: _SyncFunctionComponent[TSelf]
+    ) -> Callable[[TSelf], SyncComponent]: ...
+
+    @overload
+    def context_only_method(
+        self, func: _AsyncFunctionComponent[TSelf]
+    ) -> Callable[[TSelf], AsyncComponent]: ...
+
+    def context_only_method(
+        self,
+        func: _SyncFunctionComponent[TSelf] | _AsyncFunctionComponent[TSelf],
+    ) -> Callable[[TSelf], SyncComponent] | Callable[[TSelf], AsyncComponent]:
+        """
+        Decorator that converts the decorated method into one that must be called
+        without any arguments and returns a component instance.
+
+        If used on an async method, the resulting component will also be async;
+        otherwise it will be sync.
+
+        Example:
+
+        ```python
+        @dataclass
+        class MyBusinessObject:
+            message: str
+
+            @component.context_only_method
+            def paragraph(self, context: Context) -> Component:
+                return html.p(f"{self.message} Goodbye!")
+
+
+        async def render() -> str:
+            return await Renderer().render(
+                MyBusinessObject("Hello!").paragraph()
+            )
+        ```
+
+        Arguments:
+            func: The decorated method.
+
+        Returns:
+            A method that must be called without any arguments and returns a component instance.
+            (Or loosly speaking, an `HTMYComponentType` which can be "instantiated" by calling
+            the method.)
+        """
+        # A context only method component must be implemented in the same way as
+        # a function component. The self argument replaces the props argument
+        # and it is added automatically by Python when the method is called.
+        # Even the type hint must be the same.
+        # This implementation doesn't make the function itself a component though,
+        # so the call signature is always necessary (unlike for context-only function
+        # components).
+        return self(func)
+
 
 component = ComponentDecorators()
 """

{htmy-0.6.0.dist-info → htmy-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: htmy
-Version: 0.6.0
+Version: 0.7.0
 Summary: Async, pure-Python rendering engine.
 License: MIT
 Author: Peter Volf

{htmy-0.6.0.dist-info → htmy-0.7.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
 htmy/__init__.py,sha256=Us5P9Y6ZSp38poIz88bsAh2Hxuze5jE3V_uMtMyuH-E,1880
 htmy/core.py,sha256=OoL11j2V-CfePC0dbkC2A5GbdK942b5Huszw3rLo7fc,15124
 htmy/etree.py,sha256=yKxom__AdsJY-Q1kbU0sdTMr0ZF5dMSVBKxayntNFyQ,3062
-htmy/function_component.py,sha256=ff9gTV577SOzxlAiRcMNNIPy70ptYIxr46cC6yu-xi0,7803
+htmy/function_component.py,sha256=iSp5cGrErmIsc-VfNq053_J2m-Nuu_k2xK9UxvEnlw8,12431
 htmy/html.py,sha256=7UohfPRtl-3IoSbOiDxazsSHQpCZ0tyRdNayQISPM8A,21086
 htmy/i18n.py,sha256=brNazQjObBFfbnViZCpcnxa0qgxQbJfX7xJAH-MqTW8,5124
 htmy/io.py,sha256=iebJOZp7L0kZ9SWdqMatKtW5VGRIkEd-eD0_vTAldH8,41
@@ -15,7 +15,7 @@ htmy/renderer/default.py,sha256=lVMGuRybpFZ0u7pMB3IGOsFxw_rY8KqFQzWcNlmKCVI,1078
 htmy/snippet.py,sha256=dkHEOuULGsgawIMnSz99hghvNu8pLVGAQMQSlrn9ibY,10260
 htmy/typing.py,sha256=0spTpz_JWql2yy_lSlRx0uqgXar7fxwyBqWeIzltvKU,3111
 htmy/utils.py,sha256=Kp0j9G8CBeRiyFGmz-CoDiLtXHfpvHzlTVsWeDhIebM,1935
-htmy-0.6.0.dist-info/LICENSE,sha256=rFtoGU_3c_rlacXgOZapTHfMErN-JFPT5Bq_col4bqI,1067
-htmy-0.6.0.dist-info/METADATA,sha256=E0Fm8_Vg1MMGHc3bW1YZxZII5YX2R-FOTZYml1zI8PI,18306
-htmy-0.6.0.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
-htmy-0.6.0.dist-info/RECORD,,
+htmy-0.7.0.dist-info/LICENSE,sha256=rFtoGU_3c_rlacXgOZapTHfMErN-JFPT5Bq_col4bqI,1067
+htmy-0.7.0.dist-info/METADATA,sha256=5fzJ6L_K2WKV8-G-wa5a34IquAwdO5_v-DOWErOPRHg,18306
+htmy-0.7.0.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+htmy-0.7.0.dist-info/RECORD,,