htmy.core
AsyncFunctionComponentWrapper
Bases: Generic[T]
Base class FunctionComponent
wrappers.
Source code in htmy/core.py
htmy(context)
async
Renders the component.
BaseTag
Bases: ABC
Base tag class.
Tags are always synchronous.
If the content of a tag must be calculated asynchronously, then the content can be implemented as a separate async component or be resolved in an async parent component. If a property of a tag must be calculated asynchronously, then the tag can be wrapped in an async component that resolves the async content and then passes the value to the tag.
Source code in htmy/core.py
ContextAware
Base class with utilities for safe context use.
Features:
- Register subclass instance in a context.
- Load subclass instance from context.
- Wrap components within a subclass instance context.
Subclass instance registration:
Direct subclasses are considered the "base context type". Subclass instances are registered in contexts under their own type and also under their "base context type".
Example:
class ContextDataDefinition(ContextAware):
# This is the "base context type", instances of this class and its subclasses
# will always be registered under this type.
...
class ContextDataImplementation(ContextDataDefinition):
# Instances of this class will be registered under `ContextDataDefinition` (the
# "base context type") and also under this type.
...
class SpecializedContextDataImplementation(ContextDataImplementation):
# Instances of this class will be registered under `ContextDataDefinition` (the
# "base context type") and also under this type, but they will not be registered
# under `ContextDataImplementation`, since that's not the base context type.
...
Source code in htmy/core.py
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 |
|
from_context(context, default=None)
classmethod
Looks up an instance of this class from the given contexts.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The context the instance should be loaded from. |
required |
default
|
Self | None
|
The default to use if no instance was found in the context. |
None
|
Source code in htmy/core.py
in_context(*children)
Creates a context provider component that renders the given children using this instance in its context.
to_context()
Creates a context with this instance in it.
See the context registration rules in the class documentation for more information.
Source code in htmy/core.py
ErrorBoundary
Bases: Fragment
Error boundary component for graceful error handling.
If an error occurs during the rendering of the error boundary's subtree, the fallback component will be rendered instead.
Source code in htmy/core.py
__init__(*children, fallback=None, errors=None)
Initialization.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
*children
|
ComponentType
|
The wrapped children components. |
()
|
fallback
|
Component | None
|
The fallback component to render in case an error occurs during children rendering. |
None
|
errors
|
Container[type[Exception]] | None
|
An optional set of accepted error types. Only accepted errors are swallowed and rendered with the fallback. If an error is not in this set but one of its base classes is, then the error will still be accepted and the fallbak rendered. By default all errors are accepted. |
None
|
Source code in htmy/core.py
fallback_component(error)
Returns the fallback component for the given error.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
error
|
Exception
|
The error that occurred during the rendering of the error boundary's subtree. |
required |
Raises:
Type | Description |
---|---|
Exception
|
The received error if it's not accepted. |
Source code in htmy/core.py
Formatter
Bases: ContextAware
The default, context-aware property name and value formatter.
Important: the default implementation looks up the formatter for a given value by checking
its type, but it doesn't do this check with the base classes of the encountered type. For
example the formatter will know how to format datetime
object, but it won't know how to
format a MyCustomDatetime(datetime)
instance.
One reason for this is efficiency: always checking the base classes of every single value is a
lot of unnecessary calculation. The other reason is customizability: this way you could use
subclassing for fomatter selection, e.g. with LocaleDatetime(datetime)
-like classes.
Property name and value formatters may raise a SkipProperty
error if a property should be skipped.
Source code in htmy/core.py
341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 |
|
__init__(*, default_formatter=str, name_formatter=None)
Initialization.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
default_formatter
|
Callable[[Any], str]
|
The default property value formatter to use if no formatter could be found for a given value. |
str
|
name_formatter
|
Callable[[str], str] | None
|
Optional property name formatter (for replacing the default name formatter). |
None
|
Source code in htmy/core.py
_base_formatters()
Factory that creates the default value formatter mapping.
Source code in htmy/core.py
_format_name(name)
add(key, formatter)
format(name, value)
Formats the given name-value pair.
Returns an empty string if the property name or value should be skipped.
See SkipProperty
for more information.
Source code in htmy/core.py
format_name(name)
format_value(value)
Formats the given value.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
value
|
Any
|
The property value to format. |
required |
Raises:
Type | Description |
---|---|
SkipProperty
|
If the property should be skipped. |
Source code in htmy/core.py
Fragment
Fragment utility component that simply wraps some children components.
Source code in htmy/core.py
__init__(*children)
Initialization.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
*children
|
ComponentType
|
The wrapped children. |
()
|
SafeStr
Bases: Text
String subclass whose instances shouldn't get escaped during rendering.
Note: any operation on SafeStr
instances will result in plain str
instances which
will be rendered normally. Make sure the str
to SafeStr
conversion (SafeStr(my_string)
)
takes when there's no string operation afterwards.
Source code in htmy/core.py
SkipProperty
Bases: Exception
Exception raised by property formatters if the property should be skipped.
Source code in htmy/core.py
format_property(_)
classmethod
Property formatter that raises a SkipProperty
error regardless of the received value.
SyncFunctionComponentWrapper
Bases: Generic[T]
Base class FunctionComponent
wrappers.
Source code in htmy/core.py
htmy(context)
Renders the component.
Tag
Bases: TagWithProps
Base class for tags with both properties and children.
Source code in htmy/core.py
child_separator
property
The child separator to use.
__init__(*children, **props)
Initialization.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
*children
|
ComponentType
|
Children components. |
()
|
**props
|
PropertyValue
|
Tag properties. |
{}
|
htmy(context)
Renders the component.
Source code in htmy/core.py
TagConfig
TagWithProps
Bases: BaseTag
Base class for tags with properties.
Source code in htmy/core.py
__init__(**props)
_htmy_format_props(context)
Formats tag properties.
Text
WildcardTag
Bases: Tag
Tag that can have both children and properties, and whose tag name can be set.
Source code in htmy/core.py
__init__(*children, htmy_name, htmy_child_separator=None, **props)
Initialization.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
*children
|
ComponentType
|
Children components. |
()
|
htmy_name
|
str
|
The tag name to use for this tag. |
required |
htmy_child_separator
|
ComponentType | None
|
The child separator to use (if any). |
None
|
**props
|
PropertyValue
|
Tag properties. |
{}
|
Source code in htmy/core.py
WithContext
Bases: Fragment
A simple, static context provider component.
Source code in htmy/core.py
__init__(*children, context)
Initialization.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
*children
|
ComponentType
|
The children components to wrap in the given context. |
()
|
context
|
Context
|
The context to make available to children components. |
required |
Source code in htmy/core.py
XBool
Bases: Enum
Utility for the valid formatting of boolean XML (and HTML) attributes.
See this article for more information: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#boolean_attributes
Source code in htmy/core.py
format()
component(func)
Decorator that converts the given function into a component.
Internally this is achieved by wrapping the function in a pre-configured
FunctionComponentWrapper
subclass.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
func
|
FunctionComponent[T]
|
The decorated function component. |
required |
Returns:
Type | Description |
---|---|
type[SyncFunctionComponentWrapper[T]] | type[AsyncFunctionComponentWrapper[T]]
|
A pre-configured |
Source code in htmy/core.py
xml_format_string(value)
Escapes <
, >
, and &
characters in the given string, unless it's a SafeStr
.