py-flowtoken 0.3.1__py3-none-any.whl

py_flowtoken/__init__.py

@@ -0,0 +1,28 @@
+from .components import Component
+from .core import (
+    ANIMATIONS,
+    AnimatedImage,
+    AnimatedMarkdown,
+    AnimatedText,
+    Options,
+    TextStream,
+    Update,
+    asset_path,
+    assets,
+    tokenize,
+)
+
+__all__ = [
+    "Component",
+    "ANIMATIONS",
+    "AnimatedImage",
+    "AnimatedMarkdown",
+    "AnimatedText",
+    "Options",
+    "TextStream",
+    "Update",
+    "asset_path",
+    "assets",
+    "tokenize",
+]
+__version__ = "0.3.1"

py_flowtoken/adapters/django/__init__.py

@@ -0,0 +1,3 @@
+from .views import event_stream
+
+__all__ = ["event_stream"]

py_flowtoken/adapters/django/apps.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+
+from django.apps import AppConfig
+
+
+class FlowTokenConfig(AppConfig):
+    name = "py_flowtoken.adapters.django"
+    label = "py_flowtoken"
+    verbose_name = "Python FlowToken"
+    path = str(Path(__file__).resolve().parents[2])

py_flowtoken/adapters/django/templatetags/flowtoken.py

@@ -0,0 +1,46 @@
+from django import template
+from django.conf import settings
+from django.templatetags.static import static
+from django.urls import reverse
+from django.utils.html import format_html
+from django.utils.safestring import mark_safe
+
+from ....assets import asset_path
+from ....rendering import AnimatedImage, AnimatedMarkdown, AnimatedText
+
+register = template.Library()
+
+
+@register.simple_tag
+def flowtoken_asset_url(filename):
+    asset_path(filename)
+    mode = getattr(settings, "FLOWTOKEN_ASSET_MODE", "static")
+    if mode == "static":
+        return static("py_flowtoken/" + filename)
+    if mode == "route":
+        return reverse("py_flowtoken:asset", kwargs={"filename": filename})
+    raise ValueError("FLOWTOKEN_ASSET_MODE must be static or route")
+
+
+@register.simple_tag
+def flowtoken_assets():
+    return format_html(
+        '<link rel="stylesheet" href="{}"><script type="module" src="{}"></script>',
+        flowtoken_asset_url("flowtoken.css"),
+        flowtoken_asset_url("flowtoken.js"),
+    )
+
+
+@register.simple_tag
+def flowtoken_text(content="", **options):
+    return mark_safe(AnimatedText(content, **options).render())
+
+
+@register.simple_tag
+def flowtoken_markdown(content="", **options):
+    return mark_safe(AnimatedMarkdown(content, **options).render())
+
+
+@register.simple_tag
+def flowtoken_image(src, alt="", **options):
+    return mark_safe(AnimatedImage(src, alt, **options).render())

py_flowtoken/adapters/django/urls.py

@@ -0,0 +1,6 @@
+from django.urls import path
+
+from .views import asset
+
+app_name = "py_flowtoken"
+urlpatterns = [path("<str:filename>", asset, name="asset")]

py_flowtoken/adapters/django/views.py

@@ -0,0 +1,29 @@
+from django.http import Http404, HttpResponse, StreamingHttpResponse
+from django.views.decorators.cache import cache_control
+from django.views.decorators.http import require_safe
+
+from ...assets import asset_path
+from ...streaming import aiter_sse, iter_sse
+
+
+@require_safe
+@cache_control(public=True, max_age=3600)
+def asset(request, filename):
+    try:
+        content = asset_path(filename).read_bytes()
+    except ValueError as error:
+        raise Http404("Unknown FlowToken asset") from error
+    return HttpResponse(
+        content,
+        content_type="text/javascript" if filename.endswith(".js") else "text/css",
+    )
+
+
+def event_stream(events):
+    encoded = aiter_sse(events) if hasattr(events, "__aiter__") else iter_sse(events)
+    response = StreamingHttpResponse(
+        encoded, content_type="text/event-stream; charset=utf-8"
+    )
+    response.headers["Cache-Control"] = "no-cache"
+    response.headers["X-Accel-Buffering"] = "no"
+    return response

py_flowtoken/adapters/fasthtml.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+
+from fasthtml.common import Link, Script
+from starlette.responses import StreamingResponse
+from starlette.staticfiles import StaticFiles
+
+from ..assets import asset_path
+from ..streaming import aiter_sse, iter_sse
+
+
+def asset_tags(url_prefix="/flowtoken"):
+    prefix = url_prefix.rstrip("/")
+    return (
+        Link(rel="stylesheet", href=prefix + "/flowtoken.css"),
+        Script(src=prefix + "/flowtoken.js", type="module"),
+    )
+
+
+def mount_assets(app, url_prefix="/flowtoken"):
+    app.mount(
+        url_prefix.rstrip("/"),
+        StaticFiles(directory=str(Path(str(asset_path("flowtoken.js"))).parent)),
+        name="py_flowtoken",
+    )
+
+
+def event_stream(events):
+    encoded = aiter_sse(events) if hasattr(events, "__aiter__") else iter_sse(events)
+    return StreamingResponse(
+        encoded,
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )

py_flowtoken/adapters/flask.py

@@ -0,0 +1,82 @@
+from io import BytesIO
+from hashlib import sha256
+
+from flask import Blueprint, Response, abort, send_file, stream_with_context, url_for
+from markupsafe import Markup, escape
+
+from ..assets import asset_path
+from ..rendering import AnimatedImage, AnimatedMarkdown, AnimatedText
+from ..streaming import iter_sse
+
+
+def create_blueprint(url_prefix="/flowtoken"):
+    blueprint = Blueprint("py_flowtoken", __name__, url_prefix=url_prefix)
+
+    @blueprint.get("/<filename>")
+    def asset(filename):
+        try:
+            content = asset_path(filename).read_bytes()
+        except ValueError:
+            abort(404)
+        return send_file(
+            BytesIO(content),
+            download_name=filename,
+            mimetype="text/javascript" if filename.endswith(".js") else "text/css",
+            conditional=True,
+            etag=sha256(content).hexdigest(),
+            max_age=3600,
+        )
+
+    return blueprint
+
+
+def asset_url(filename):
+    asset_path(filename)
+    return url_for("py_flowtoken.asset", filename=filename)
+
+
+def asset_tags():
+    return Markup(
+        '<link rel="stylesheet" href="{}"><script type="module" src="{}"></script>'
+    ).format(escape(asset_url("flowtoken.css")), escape(asset_url("flowtoken.js")))
+
+
+def animated_text(content="", **options):
+    return Markup(AnimatedText(content, **options).render())
+
+
+def animated_markdown(content="", **options):
+    return Markup(AnimatedMarkdown(content, **options).render())
+
+
+def animated_image(src, alt="", **options):
+    return Markup(AnimatedImage(src, alt, **options).render())
+
+
+class FlowToken:
+    def __init__(self, app=None, *, url_prefix="/flowtoken"):
+        if app is not None:
+            self.init_app(app, url_prefix=url_prefix)
+
+    def init_app(self, app, *, url_prefix="/flowtoken"):
+        if "py_flowtoken" in app.extensions:
+            raise ValueError("py-flowtoken is already registered on this Flask app")
+        app.register_blueprint(create_blueprint(url_prefix))
+        app.jinja_env.globals.update(
+            flowtoken_assets=asset_tags,
+            flowtoken_asset_url=asset_url,
+            flowtoken_text=animated_text,
+            flowtoken_markdown=animated_markdown,
+            flowtoken_image=animated_image,
+        )
+        app.extensions["py_flowtoken"] = self
+
+
+def event_stream(events):
+    if hasattr(events, "__aiter__"):
+        raise TypeError("Flask event_stream requires a synchronous iterable")
+    return Response(
+        stream_with_context(iter_sse(events)),
+        content_type="text/event-stream; charset=utf-8",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )

py_flowtoken/assets.py

@@ -0,0 +1,13 @@
+import html
+from importlib.resources import files
+
+
+def asset_path(name: str):
+    if name not in {"flowtoken.js", "flowtoken.css"}:
+        raise ValueError("Unknown asset")
+    return files("py_flowtoken").joinpath("static", "py_flowtoken", name)
+
+
+def assets(base_url: str = "/static/flowtoken") -> str:
+    base_url = html.escape(base_url.rstrip("/"), quote=True)
+    return f'<link rel="stylesheet" href="{base_url}/flowtoken.css"><script type="module" src="{base_url}/flowtoken.js"></script>'

py_flowtoken/components.py

@@ -0,0 +1,116 @@
+import re
+from dataclasses import dataclass
+from html.parser import HTMLParser
+from typing import Callable, Mapping
+
+from markdown_it import MarkdownIt
+from markdown_it.rules_inline import backtick
+
+
+def mask_code(source: str) -> str:
+    engine = MarkdownIt('commonmark')
+    ranges = []
+    offsets = [0]
+    for match in re.finditer('\n', source):
+        offsets.append(match.end())
+    offsets.append(len(source))
+    for token in engine.parse(source):
+        if token.type in ('fence', 'code_block'):
+            start, end = token.map
+            ranges.append((offsets[start], offsets[end]))
+    def capture_backticks(state, silent):
+        start, count = state.pos, len(state.tokens)
+        matched = backtick(state, silent)
+        if len(state.tokens) > count and state.tokens[-1].type == 'code_inline':
+            ranges.append((start, state.pos))
+        return matched
+
+    engine.inline.ruler.at('backticks', capture_backticks)
+    engine.inline.parse(source, engine, {}, [])
+    masked = list(source)
+    for start, end in ranges:
+        masked[start:end] = ['\n' if char == '\n' else ' ' for char in source[start:end]]
+    return ''.join(masked)
+
+
+@dataclass(frozen=True)
+class Component:
+    tag: str
+    attributes: Mapping[str, str | None]
+    content: str
+
+
+class ComponentParser(HTMLParser):
+    def __init__(self, source: str, renderers: Mapping[str, Callable[[Component], str]]):
+        super().__init__(convert_charrefs=False)
+        self.source = source
+        self.renderers = {key.lower(): value for key, value in renderers.items()}
+        self.offsets = [0]
+        for match in re.finditer('\n', source):
+            self.offsets.append(match.end())
+        self.active = None
+        self.depth = 0
+        self.replacements = []
+
+    def position(self):
+        line, column = self.getpos()
+        return self.offsets[line - 1] + column
+
+    def handle_starttag(self, tag, attrs):
+        if self.active and tag == self.active[0]:
+            self.depth += 1
+        elif not self.active and tag in self.renderers:
+            start = self.position()
+            self.active = (tag, dict(attrs), start, start + len(self.get_starttag_text()))
+            self.depth = 1
+
+    def handle_endtag(self, tag):
+        if self.active and tag == self.active[0]:
+            self.depth -= 1
+            if self.depth == 0:
+                name, attrs, start, content_start = self.active
+                end_start = self.position()
+                end = self.source.find('>', end_start) + 1
+                rendered = self.renderers[name](Component(name, attrs, self.source[content_start:end_start]))
+                if not isinstance(rendered, str):
+                    raise TypeError('Custom component renderers must return HTML strings')
+                self.replacements.append((start, end, rendered))
+                self.active = None
+
+    def handle_startendtag(self, tag, attrs):
+        if not self.active and tag in self.renderers:
+            start = self.position()
+            rendered = self.renderers[tag](Component(tag, dict(attrs), ''))
+            if not isinstance(rendered, str):
+                raise TypeError('Custom component renderers must return HTML strings')
+            self.replacements.append((start, start + len(self.get_starttag_text()), rendered))
+
+
+def extract_components(source: str, renderers: Mapping[str, Callable[[Component], str]]):
+    if not renderers:
+        return source, {}
+    for name in renderers:
+        if not re.fullmatch(r'[a-zA-Z][\w-]*', name):
+            raise ValueError('Invalid custom component tag')
+    parser = ComponentParser(source, renderers)
+    masked = mask_code(source)
+    parser.feed(masked)
+    limit = parser.active[2] if parser.active else len(source)
+    tail = masked.rfind('<', 0, limit)
+    if tail >= 0 and '>' not in masked[tail:limit]:
+        partial = masked[tail + 1:limit].lstrip('/').lower()
+        if any(name.lower().startswith(partial) or re.match(re.escape(name.lower())+r'\s', partial) for name in renderers):
+            limit = tail
+    output, rendered, cursor = [], {}, 0
+    prefix = 'PYFLOWTOKENCOMPONENT'
+    while prefix in source:
+        prefix += 'X'
+    for start, end, value in parser.replacements:
+        if end > limit:
+            break
+        marker = f'{prefix}{len(rendered)}END'
+        output.extend([source[cursor:start], marker])
+        rendered[marker] = value
+        cursor = end
+    output.append(source[cursor:limit])
+    return ''.join(output), rendered

py_flowtoken/core.py

@@ -0,0 +1,17 @@
+from .assets import asset_path, assets
+from .options import ANIMATIONS, Options
+from .rendering import AnimatedImage, AnimatedMarkdown, AnimatedText
+from .streaming import TextStream, Update, tokenize
+
+__all__ = [
+    "ANIMATIONS",
+    "AnimatedImage",
+    "AnimatedMarkdown",
+    "AnimatedText",
+    "Options",
+    "TextStream",
+    "Update",
+    "asset_path",
+    "assets",
+    "tokenize",
+]

py_flowtoken/options.py

@@ -0,0 +1,60 @@
+import html
+import math
+import re
+from dataclasses import dataclass
+
+from .policy import SCHEMA
+
+ANIMATIONS = {name: 'ft-'+name for name in SCHEMA['animations']}
+DEFAULTS = SCHEMA['defaults']
+
+
+def valid_easing(value: str) -> bool:
+    if value in ('ease', 'ease-in', 'ease-out', 'ease-in-out', 'linear', 'step-start', 'step-end'):
+        return True
+    match = re.fullmatch(r'cubic-bezier\(\s*(-?\d*\.?\d+)\s*,\s*(-?\d*\.?\d+)\s*,\s*(-?\d*\.?\d+)\s*,\s*(-?\d*\.?\d+)\s*\)', value)
+    if match:
+        points = [float(number) for number in match.groups()]
+        return all(math.isfinite(number) for number in points) and 0 <= points[0] <= 1 and 0 <= points[2] <= 1
+    match = re.fullmatch(r'steps\(\s*([1-9]\d*)\s*(?:,\s*(start|end|jump-start|jump-end|jump-none|jump-both)\s*)?\)', value)
+    return bool(match and (match[2] != 'jump-none' or int(match[1]) > 1))
+
+
+def dimension(value: str | None) -> str | None:
+    if value is not None and value != 'auto' and not re.fullmatch(r'\d+(?:\.\d+)?(?:px|rem|em|%|vh|vw)', value):
+        raise ValueError('Invalid image dimension')
+    return value
+
+
+@dataclass(frozen=True)
+class Options:
+    sep: str = DEFAULTS['sep']
+    animation: str | None = DEFAULTS['animation']
+    animation_duration: str = DEFAULTS['duration']
+    animation_timing_function: str = DEFAULTS['easing']
+    interval_ms: int = DEFAULTS['interval']
+    animate_initial: bool = DEFAULTS['animateInitial']
+
+    def __post_init__(self):
+        if self.sep not in SCHEMA['separators']:
+            raise ValueError('Invalid separator')
+        if self.animation is not None and not re.fullmatch(r'[a-zA-Z_][\w-]*', self.animation):
+            raise ValueError('Invalid animation name')
+        if not re.fullmatch(r'(?:\d+(?:\.\d+)?|\.\d+)(?:ms|s)', self.animation_duration):
+            raise ValueError('Invalid animation duration')
+        if not valid_easing(self.animation_timing_function):
+            raise ValueError('Invalid animation timing function')
+        if not isinstance(self.interval_ms, (int, float)) or not math.isfinite(self.interval_ms) or not 0 <= self.interval_ms <= 1000:
+            raise ValueError('interval_ms must be between 0 and 1000')
+        if not isinstance(self.animate_initial, bool):
+            raise ValueError('animate_initial must be a boolean')
+
+    def attributes(self) -> str:
+        values = {'data-sep':self.sep, 'data-animation':self.animation or 'none',
+            'data-duration':self.animation_duration, 'data-easing':self.animation_timing_function,
+            'data-interval':str(self.interval_ms), 'data-animate-initial':str(self.animate_initial).lower()}
+        return ' '.join(f'{key}="{html.escape(value, quote=True)}"' for key, value in values.items())
+
+    def style(self, index: int = 0) -> str:
+        name = ANIMATIONS.get(self.animation, self.animation) or 'none'
+        return f'animation-name:{name};animation-duration:{self.animation_duration};animation-timing-function:{self.animation_timing_function};animation-iteration-count:1;animation-fill-mode:both'

py_flowtoken/policy.py

@@ -0,0 +1,92 @@
+import html
+import json
+import re
+from html.parser import HTMLParser
+from importlib.resources import files
+from urllib.parse import unquote, urlsplit
+
+SCHEMA = json.loads(files('py_flowtoken').joinpath('schema.json').read_text())
+
+
+def safe_url(value: str) -> str | None:
+    value = value.strip()
+    if re.search(r'[\x00-\x20\x7f]', value):
+        return None
+    try:
+        parsed = urlsplit(value)
+        if parsed.scheme and parsed.scheme.lower() not in SCHEMA['protocols']:
+            return None
+        if parsed.scheme in ('http', 'https') or value.startswith('//'):
+            if not parsed.hostname or re.search(r'[\s%\[\]<>]', unquote(parsed.hostname)):
+                return None
+            parsed.port
+    except ValueError:
+        return None
+    return value
+
+
+def safe_style(value: str) -> str:
+    result = []
+    for declaration in value.split(';'):
+        name, separator, content = declaration.partition(':')
+        name, content = name.strip().lower(), content.strip()
+        if separator and name in SCHEMA['styles'] and re.fullmatch(r'[\w\s#.,()%/-]+', content) and not re.search(r'url|expression|javascript', content, re.I):
+            result.append(f'{name}:{content}')
+    return ';'.join(result)
+
+
+class SemanticHTML(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.output = []
+        self.stack = []
+
+    def handle_starttag(self, tag, attrs):
+        if tag not in SCHEMA['tags']:
+            return
+        values = {}
+        for name, value in attrs:
+            if name == 'style':
+                clean = safe_style(value or '')
+                if clean:
+                    values[name] = clean
+            elif name in SCHEMA['attributes']:
+                if name in ('href', 'src'):
+                    value = safe_url(value or '')
+                    if value is None:
+                        continue
+                values[name] = value
+        if tag == 'input':
+            values.update(type='checkbox', disabled=None)
+        if tag == 'button':
+            values['type'] = 'button'
+        if tag == 'a' and values.get('target') == '_blank':
+            values['rel'] = 'noopener noreferrer'
+        attributes = ''.join(f' {name}' if value is None else f' {name}="{html.escape(value, quote=True)}"' for name, value in values.items())
+        self.output.append(f'<{tag}{attributes}>')
+        if tag not in SCHEMA['voidTags']:
+            self.stack.append(tag)
+
+    def handle_startendtag(self, tag, attrs):
+        self.handle_starttag(tag, attrs)
+        self.handle_endtag(tag)
+
+    def handle_endtag(self, tag):
+        if tag in self.stack:
+            while self.stack:
+                opened = self.stack.pop()
+                self.output.append(f'</{opened}>')
+                if opened == tag:
+                    break
+
+    def handle_data(self, data):
+        self.output.append(html.escape(data))
+
+
+def sanitize_html(value: str) -> str:
+    parser = SemanticHTML()
+    parser.feed(value)
+    parser.close()
+    for tag in reversed(parser.stack):
+        parser.output.append(f'</{tag}>')
+    return ''.join(parser.output)

py_flowtoken/rendering.py

@@ -0,0 +1,114 @@
+import html
+from collections.abc import Callable, Mapping
+
+from markdown_it import MarkdownIt
+from mdit_py_plugins.tasklists import tasklists_plugin
+from pygments import highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import TextLexer, get_lexer_by_name
+from pygments.token import Text
+from pygments.util import ClassNotFound
+
+from .components import Component, extract_components
+from .options import Options, dimension
+from .policy import SCHEMA, safe_url, sanitize_html
+
+
+class Renderable:
+    def __html__(self):
+        return self.render()
+
+    def __ft__(self):
+        from fastcore.xml import NotStr
+        return NotStr(self.render())
+
+
+def identity(value):
+    return f' id="{html.escape(value, quote=True)}"' if value else ''
+
+
+class AnimatedText(Renderable):
+    def __init__(self, content: str = '', *, id: str | None = None, **options):
+        self.content, self.id = content, id
+        self.options = Options(**options)
+
+    def render(self) -> str:
+        return f'<span class="ft-text" data-flowtoken="text" {self.options.attributes()}{identity(self.id)}>{html.escape(self.content)}</span>'
+
+
+class AnimatedMarkdown(Renderable):
+    def __init__(self, content: str = '', *, id: str | None = None, code_style: str = 'default',
+                 img_height: str = '20rem', img_width: str | None = None, object_fit: str = 'contain',
+                 custom_components: Mapping[str, Callable[[Component], str]] | None = None,
+                 trusted_html: bool = False, **options):
+        for key, value in SCHEMA['markdownDefaults'].items():
+            argument = {'duration':'animation_duration','easing':'animation_timing_function'}.get(key, key)
+            options.setdefault(argument, value)
+        self.options = Options(**options)
+        self.content, self.id = content, id
+        self.formatter = HtmlFormatter(style=code_style, nowrap=True, noclasses=True)
+        self.code_style = code_style
+        self.img_height, self.img_width = dimension(img_height), dimension(img_width)
+        if object_fit not in ('cover','contain','fill','none','scale-down'):
+            raise ValueError('Invalid image fit')
+        self.object_fit, self.custom_components, self.trusted_html = object_fit, custom_components or {}, trusted_html
+
+    def render(self) -> str:
+        source, components = extract_components(self.content, self.custom_components)
+        engine = MarkdownIt('commonmark', {'html': self.trusted_html, 'linkify':True}).enable(['table','strikethrough','linkify'])
+        engine.use(tasklists_plugin)
+
+        def render_fence(tokens, index, options, env):
+            token = tokens[index]
+            language = token.info.strip().split(maxsplit=1)[0] if token.info.strip() else ''
+            try:
+                lexer = get_lexer_by_name(language, stripnl=False, ensurenl=False) if language else TextLexer(stripnl=False, ensurenl=False)
+            except ClassNotFound:
+                lexer = TextLexer(stripnl=False, ensurenl=False)
+            body = highlight(token.content, lexer, self.formatter)
+            language_class = f' class="language-{html.escape(language, quote=True)}"' if language else ''
+            background = html.escape(self.formatter.style.background_color, quote=True)
+            foreground = self.formatter.style.style_for_token(Text)['color'] or '000000'
+            return f'<div class="ft-code" data-ft-code data-ft-source="{html.escape(token.content, quote=True)}" data-ft-theme="{html.escape(self.code_style, quote=True)}" style="background-color:{background};color:#{foreground}"><button type="button" data-ft-copy aria-label="Copy code">Copy code</button><pre><code{language_class}>{body}</code></pre></div>\n'
+
+        def render_image(tokens, index, options, env):
+            token = tokens[index]
+            source = token.attrGet('src') or ''
+            if safe_url(source) is None:
+                return html.escape(token.content)
+            image = AnimatedImage(source, token.content, height=self.img_height, width=self.img_width, object_fit=self.object_fit, animation=self.options.animation, animation_duration=self.options.animation_duration, animation_timing_function=self.options.animation_timing_function)
+            return image.render()
+
+        def render_link(tokens, index, options, env):
+            token = tokens[index]
+            target = safe_url(token.attrGet('href') or '')
+            if target is None:
+                token.attrs.pop('href', None)
+            token.attrSet('target', '_blank')
+            token.attrSet('rel', 'noopener noreferrer')
+            return engine.renderer.renderToken(tokens, index, options, env)
+
+        engine.renderer.rules.update(fence=render_fence, code_block=render_fence, image=render_image, link_open=render_link)
+        rendered = engine.render(source)
+        for marker, component in components.items():
+            rendered = rendered.replace(f"<p>{marker}</p>", component).replace(marker, component)
+        body = sanitize_html(rendered)
+        return f'<div class="ft-markdown" data-flowtoken="markdown" {self.options.attributes()}{identity(self.id)}>{body}</div>'
+
+
+class AnimatedImage(Renderable):
+    def __init__(self, src: str, alt: str = '', *, height: str | None = '20rem', width: str | None = None,
+                 object_fit: str = 'contain', animation: str | None = 'fadeIn',
+                 animation_duration: str = '0.25s', animation_timing_function: str = 'ease-out'):
+        if safe_url(src) is None:
+            raise ValueError('Unsafe image source')
+        if object_fit not in ('cover','contain','fill','none','scale-down'):
+            raise ValueError('Invalid image fit')
+        self.src, self.alt = src, alt
+        self.height, self.width, self.object_fit = dimension(height), dimension(width), object_fit
+        self.options = Options(animation=animation, animation_duration=animation_duration,
+                               animation_timing_function=animation_timing_function)
+
+    def render(self):
+        sizing = ';'.join(f'{key}:{value}' for key, value in [('height',self.height),('width',self.width),('max-width','100%'),('object-fit',self.object_fit)] if value)
+        return f'<img class="ft-image" data-ft-image {self.options.attributes()} src="{html.escape(self.src, quote=True)}" alt="{html.escape(self.alt, quote=True)}" style="{sizing}">'

py_flowtoken/schema.json

@@ -0,0 +1,131 @@
+{
+  "animations": [
+    "fadeIn",
+    "slideUp",
+    "wave",
+    "elastic",
+    "bounceIn",
+    "rotateIn",
+    "colorTransition",
+    "fadeAndScale",
+    "slideInFromLeft",
+    "blurIn",
+    "typewriter",
+    "highlight",
+    "blurAndSharpen",
+    "dropIn"
+  ],
+  "separators": [
+    "word",
+    "char",
+    "diff"
+  ],
+  "defaults": {
+    "sep": "word",
+    "animation": "fadeIn",
+    "duration": "0.25s",
+    "easing": "ease-out",
+    "interval": 35,
+    "animateInitial": true
+  },
+  "markdownDefaults": {
+    "sep": "diff",
+    "duration": "1s",
+    "easing": "ease-in-out"
+  },
+  "tags": [
+    "div",
+    "p",
+    "span",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "strong",
+    "em",
+    "s",
+    "del",
+    "blockquote",
+    "ul",
+    "ol",
+    "li",
+    "a",
+    "img",
+    "pre",
+    "code",
+    "hr",
+    "br",
+    "table",
+    "thead",
+    "tbody",
+    "tr",
+    "th",
+    "td",
+    "input",
+    "button",
+    "mark",
+    "section",
+    "article",
+    "aside",
+    "figure",
+    "figcaption"
+  ],
+  "attributes": [
+    "id",
+    "class",
+    "title",
+    "href",
+    "src",
+    "alt",
+    "width",
+    "height",
+    "start",
+    "type",
+    "checked",
+    "disabled",
+    "target",
+    "rel",
+    "colspan",
+    "rowspan",
+    "aria-label",
+    "data-ft-key",
+    "data-ft-code",
+    "data-ft-copy",
+    "data-ft-image",
+    "data-ft-state",
+    "data-ft-theme",
+    "data-ft-source",
+    "data-animation",
+    "data-duration",
+    "data-easing",
+    "data-interval",
+    "data-sep",
+    "data-animate-initial"
+  ],
+  "styles": [
+    "text-align",
+    "color",
+    "background",
+    "background-color",
+    "font-weight",
+    "font-style",
+    "text-decoration",
+    "height",
+    "width",
+    "max-width",
+    "object-fit"
+  ],
+  "protocols": [
+    "http",
+    "https",
+    "mailto"
+  ],
+  "voidTags": [
+    "img",
+    "hr",
+    "br",
+    "input"
+  ]
+}

py_flowtoken/static/py_flowtoken/flowtoken.css

@@ -0,0 +1,26 @@
+.ft-text,.ft-markdown{white-space:pre-wrap;overflow-wrap:anywhere}
+.ft-markdown{white-space:normal}
+.ft-leaf,.ft-chunk{display:contents}
+.ft-token{display:inline-block;max-width:100%;overflow-wrap:anywhere;animation-fill-mode:both}
+.ft-markdown pre{white-space:pre;overflow:auto;margin:0;padding:1rem}
+.ft-markdown pre .ft-token{white-space:pre;overflow-wrap:normal}
+.ft-code{position:relative;border:1px solid #ddd;border-radius:.4rem;overflow:hidden;margin:1rem 0}
+.ft-code [data-ft-copy]{position:absolute;right:.5rem;top:.5rem;z-index:1;border:1px solid #aaa;border-radius:.3rem;padding:.25rem .5rem;background:#fff;color:#222;cursor:pointer}
+.ft-image{max-width:100%;object-fit:contain}
+.ft-image[data-ft-state=pending]{opacity:0}
+.ft-image[data-ft-state=error]{opacity:1}
+@keyframes ft-fadeIn{from{opacity:0}to{opacity:1}}
+@keyframes ft-slideUp{from{opacity:0;transform:translateY(10%)}to{opacity:1;transform:translateY(0)}}
+@keyframes ft-wave{0%,100%{transform:translateY(0)}50%{transform:translateY(-10%)}}
+@keyframes ft-elastic{0%,100%{transform:scale(1)}10%{transform:scale(1.2)}}
+@keyframes ft-bounceIn{0%,40%,80%,100%{transform:translateY(0)}20%{transform:translateY(-10%)}60%{transform:translateY(-5%)}}
+@keyframes ft-rotateIn{from{opacity:0;transform:rotate(-360deg)}to{opacity:1;transform:rotate(0)}}
+@keyframes ft-colorTransition{from{color:red}to{color:black}}
+@keyframes ft-fadeAndScale{from{opacity:0;transform:scale(.5)}to{opacity:1;transform:scale(1)}}
+@keyframes ft-slideInFromLeft{from{opacity:0;transform:translateX(-100%)}to{opacity:1;transform:translateX(0%)}}
+@keyframes ft-blurIn{from{opacity:0;filter:blur(5px)}to{opacity:1;filter:blur(0)}}
+@keyframes ft-typewriter{from{clip-path:inset(0 100% 0 0)}to{clip-path:inset(0)}}
+@keyframes ft-highlight{from{background-color:yellow}to{background-color:transparent}}
+@keyframes ft-blurAndSharpen{from{filter:blur(5px);opacity:0}to{filter:blur(0);opacity:1}}
+@keyframes ft-dropIn{from{opacity:0;transform:translateY(-10%)}to{opacity:1;transform:translateY(0)}}
+@media(prefers-reduced-motion:reduce){.ft-token,.ft-image{animation:none!important;transform:none!important;filter:none!important}.ft-image[data-ft-state=pending]{opacity:0}}

py_flowtoken/static/py_flowtoken/flowtoken.js

@@ -0,0 +1 @@
+var o={animations:["fadeIn","slideUp","wave","elastic","bounceIn","rotateIn","colorTransition","fadeAndScale","slideInFromLeft","blurIn","typewriter","highlight","blurAndSharpen","dropIn"],separators:["word","char","diff"],defaults:{sep:"word",animation:"fadeIn",duration:"0.25s",easing:"ease-out",interval:35,animateInitial:!0},markdownDefaults:{sep:"diff",duration:"1s",easing:"ease-in-out"},tags:["div","p","span","h1","h2","h3","h4","h5","h6","strong","em","s","del","blockquote","ul","ol","li","a","img","pre","code","hr","br","table","thead","tbody","tr","th","td","input","button","mark","section","article","aside","figure","figcaption"],attributes:["id","class","title","href","src","alt","width","height","start","type","checked","disabled","target","rel","colspan","rowspan","aria-label","data-ft-key","data-ft-code","data-ft-copy","data-ft-image","data-ft-state","data-ft-theme","data-ft-source","data-animation","data-duration","data-easing","data-interval","data-sep","data-animate-initial"],styles:["text-align","color","background","background-color","font-weight","font-style","text-decoration","height","width","max-width","object-fit"],protocols:["http","https","mailto"],voidTags:["img","hr","br","input"]};var N=Object.fromEntries(o.animations.map(i=>[i,`ft-${i}`]));function l(i,t="word"){if(t==="word")return i.split(/(\s+)/u).filter(Boolean);if(t==="char")return Array.from(i);if(t==="diff")return i?[i]:[];throw new Error("Invalid separator")}function d(i,t={}){let s=i.dataset,e={...o.defaults,sep:s.sep??o.defaults.sep,animation:s.animation??o.defaults.animation,duration:s.duration??o.defaults.duration,easing:s.easing??o.defaults.easing,interval:Number(s.interval??o.defaults.interval),animateInitial:s.animateInitial!=="false",reducedMotion:matchMedia("(prefers-reduced-motion: reduce)").matches,...t};if(!o.separators.includes(e.sep))throw new Error("Invalid separator");if(!Number.isFinite(e.interval)||e.interval<0||e.interval>1e3)throw new Error("Invalid interval");if(typeof e.animateInitial!="boolean")throw new Error("Invalid animateInitial");if(e.animation!==null&&!/^[a-zA-Z_][\w-]*$/.test(e.animation))throw new Error("Invalid animation");if(!/^(?:\d+(?:\.\d+)?|\.\d+)(?:ms|s)$/.test(e.duration))throw new Error("Invalid duration");if(!CSS.supports("animation-timing-function",e.easing))throw new Error("Invalid easing");return e}function f(i,t){t.reducedMotion||!t.animation||t.animation==="none"||(i.style.animationName=N[t.animation]||t.animation,i.style.animationDuration=t.duration,i.style.animationTimingFunction=t.easing,i.style.animationIterationCount="1",i.style.animationFillMode="both",i.addEventListener("animationend",()=>{i.style.animationName="none"},{once:!0}))}var c=class{constructor(t,s,e=()=>{}){this.element=t,this.options=s,this.notify=e,this.target="",this.parts=[],this.nodes=[],this.frame=null,this.lastPaint=0,this.disposed=!1,this.waiters=[]}seed(t,s=!0){if(s){this.setText(t);return}this.target=t,this.parts=l(t,this.options.sep),this.flush(!1)}configure(t){let s=this.options.sep!==t.sep;if(this.options=t,s&&(this.parts=l(this.target,t.sep),this.nodes=[],this.element.replaceChildren(),this.flush(!1)),t.reducedMotion||!t.animation||t.animation==="none")for(let e of this.element.querySelectorAll(".ft-token"))e.style.animationName="none";this.immediate&&this.flush()}get immediate(){return this.options.reducedMotion||!this.options.animation||this.options.animation==="none"||this.options.interval===0}setText(t){if(this.check(t),t===this.target)return;if(t.startsWith(this.target)){this.append(t.slice(this.target.length));return}let s=l(t,this.options.sep);this.notify("before-render");let e=0;for(;e<this.nodes.length&&e<s.length&&this.nodes[e].textContent===s[e];)e++;for(let r of this.nodes.splice(e))r.remove();this.target=t,this.parts=s,this.notify("render"),this.start()}append(t){if(this.check(t),!!t){if(this.notify("before-render"),this.target+=t,this.options.sep==="diff")this.parts.push(t);else{let s=Math.max(0,this.parts.length-1),e=(this.parts[s]||"")+t,r=l(e,this.options.sep);this.parts.length=s;for(let n of r)this.parts.push(n);if(s<this.nodes.length){let n=this.nodes[s];if(r[0]&&r[0].startsWith(n.textContent)&&this.isWhitespace(r[0])===this.isWhitespace(n.textContent)){n.textContent=r[0];for(let a of this.nodes.splice(s+1))a.remove()}else for(let a of this.nodes.splice(s))a.remove()}}this.notify("render"),this.start()}}check(t){if(this.disposed)throw new Error("FlowToken has been destroyed");if(typeof t!="string")throw new TypeError("Expected text")}isWhitespace(t){return/^\s+$/u.test(t)}makeNode(t,s){if(this.isWhitespace(t))return document.createTextNode(t);if(this.options.sep!=="diff"){let r=document.createElement("span");return r.className="ft-token",r.textContent=t,s&&f(r,this.options),r}let e=document.createElement("span");e.className="ft-chunk",e.dataset.ftChunk="";for(let r of l(t,"word"))if(this.isWhitespace(r))e.append(document.createTextNode(r));else{let n=document.createElement("span");n.className="ft-token",n.textContent=r,s&&f(n,this.options),e.append(n)}return e}reveal(t){this.notify("before-render");let s=!1;for(;this.nodes.length<this.parts.length;){let e=this.parts[this.nodes.length];if(s&&!this.isWhitespace(e))break;let r=this.makeNode(e,t);this.element.append(r),this.nodes.push(r),this.isWhitespace(e)||(s=!0)}this.notify("render")}start(){if(this.immediate){this.flush(!this.options.reducedMotion);return}if(this.frame===null){if(this.nodes.length===this.parts.length){this.complete();return}this.frame=requestAnimationFrame(t=>{this.frame=null,!this.disposed&&((!this.lastPaint||t-this.lastPaint>=this.options.interval)&&(this.reveal(!0),this.lastPaint=t),this.start())})}}flush(t=!1){for(this.frame!==null&&cancelAnimationFrame(this.frame),this.frame=null;!this.disposed&&this.nodes.length<this.parts.length;)this.reveal(t);this.complete()}complete(){for(let t of this.waiters.splice(0))t();this.notify("idle")}whenIdle(){return this.disposed||this.nodes.length===this.parts.length?Promise.resolve():new Promise(t=>this.waiters.push(t))}destroy(){this.frame!==null&&cancelAnimationFrame(this.frame),this.frame=null,this.disposed=!0,this.complete()}};function C(i){try{if(i=i.trim(),/[\u0000-\u0020\u007f]/u.test(i))return null;let t=new URL(i,"https://flowtoken.invalid/");return o.protocols.includes(t.protocol.slice(0,-1))?i:null}catch{return null}}function I(i){return i.split(";").flatMap(t=>{let s=t.indexOf(":");if(s<0)return[];let e=t.slice(0,s).trim().toLowerCase(),r=t.slice(s+1).trim();return!o.styles.includes(e)||/url|expression|javascript/i.test(r)||!/^[\w\s#.,()%/-]+$/.test(r)?[]:[`${e}:${r}`]}).join(";")}function E(i){let t=new DOMParser().parseFromString(i,"text/html"),s=t.querySelector('[data-flowtoken="markdown"]');if(!s)throw new Error("Expected AnimatedMarkdown.render() output");for(let e of[...s.querySelectorAll("*")]){if(e.classList.contains("ft-token")||e.hasAttribute("data-ft-token")){e.replaceWith(t.createTextNode(e.textContent));continue}if(!o.tags.includes(e.tagName.toLowerCase())){e.replaceWith(t.createTextNode(e.textContent));continue}for(let r of[...e.attributes])if(r.name==="style"){let n=I(r.value);n?e.setAttribute("style",n):e.removeAttribute("style")}else o.attributes.includes(r.name)?["href","src"].includes(r.name)&&C(r.value)===null&&e.removeAttribute(r.name):e.removeAttribute(r.name);e.tagName==="INPUT"&&(e.type="checkbox",e.disabled=!0),e.tagName==="BUTTON"&&(e.type="button"),e.tagName==="A"&&e.target==="_blank"&&(e.rel="noopener noreferrer")}return s.normalize(),s}function b(i){return i.nodeType!==Node.ELEMENT_NODE?null:i.getAttribute("data-ft-key")||i.id||(i.tagName==="IMG"?`image:${i.getAttribute("src")}`:null)}function w(i,t,s){return t.nodeType===Node.TEXT_NODE?s.has(i):!s.has(i)&&i?.nodeType===t.nodeType&&i.nodeName===t.nodeName&&b(i)===b(t)}function x(i,t,s){let e=i.firstChild;for(let r of[...t.childNodes]){let n=e,a=b(r);if(a&&!w(n,r,s.leaves)&&(n=[...i.childNodes].find(v=>b(v)===a&&w(v,r,s.leaves))||e),n&&w(n,r,s.leaves))n!==e&&i.insertBefore(n,e),r.nodeType===Node.TEXT_NODE?s.leaves.get(n).setText(r.textContent):(s.attributes(n,r),n.hasAttribute("data-ft-copy")||x(n,r,s),s.behaviors.bind(n)),e=n.nextSibling;else{let v=s.hydrate(r);i.insertBefore(v,e)}}for(;e;){let r=e.nextSibling;s.remove(e),e.remove(),e=r}}var u=class{constructor(t){this.options=t,this.bound=new Map}bind(t){t.hasAttribute("data-ft-copy")&&this.copy(t),t.tagName==="IMG"&&this.image(t)}copy(t){if(this.bound.has(t))return;let s={controller:new AbortController,timer:null};this.bound.set(t,s),t.addEventListener("click",async()=>{let e=t.closest("[data-ft-code]");try{if(await navigator.clipboard.writeText(e?.dataset.ftSource??e?.querySelector("code")?.textContent??""),s.controller.signal.aborted)return;t.textContent="Copied!",t.setAttribute("aria-label","Copied!")}catch{if(s.controller.signal.aborted)return;t.textContent="Copy failed",t.setAttribute("aria-label","Copy failed; try again")}clearTimeout(s.timer),s.timer=setTimeout(()=>{t.textContent="Copy code",t.setAttribute("aria-label","Copy code")},2e3)},{signal:s.controller.signal})}image(t){let s=t.getAttribute("src");if(this.bound.get(t)?.source===s)return;this.release(t);let r={source:s,controller:new AbortController};this.bound.set(t,r),t.dataset.ftState="pending";let n=()=>{t.dataset.ftState="loaded",f(t,d(t,this.options))},a=()=>{t.dataset.ftState="error",t.style.animationName="none"};t.addEventListener("load",n,{once:!0,signal:r.controller.signal}),t.addEventListener("error",a,{once:!0,signal:r.controller.signal}),t.complete&&(t.naturalWidth?n():a())}release(t){let s=this.bound.get(t);s&&(s.controller.abort(),clearTimeout(s.timer),this.bound.delete(t))}releaseTree(t){this.release(t);for(let s of t.querySelectorAll?.("*")||[])this.release(s)}destroy(){for(let t of[...this.bound.keys()])this.release(t)}};var p=class{constructor(t,s){this.element=t,this.overrides={...s},this.options=d(t,s),this.disposed=!1}event(t){t==="before-render"&&this.element.setAttribute("aria-busy","true"),t==="idle"&&this.element.setAttribute("aria-busy","false"),this.element.dispatchEvent(new Event(`flowtoken:${t}`))}check(){if(this.disposed)throw new Error("FlowToken has been destroyed")}configure(t){this.check();let s={...this.overrides,...t},e=d(this.element,s);this.overrides=s,this.options=e}finishDestroy(){this.disposed=!0,this.element.setAttribute("aria-busy","false"),this.element.dispatchEvent(new Event("flowtoken:destroy"))}},m=class extends p{constructor(t,s={}){super(t,s);let e=t.textContent||"";t.replaceChildren(),this.renderer=new c(t,this.options,r=>this.event(r)),this.renderer.seed(e,this.options.animateInitial)}get text(){return this.renderer.target}setText(t){this.check(),this.renderer.setText(t)}append(t){this.check(),this.renderer.append(t)}flush(){this.check(),this.renderer.flush()}whenIdle(){return this.renderer.whenIdle()}configure(t){super.configure(t),this.renderer.configure(this.options)}destroy(){this.disposed||(this.renderer.destroy(),this.finishDestroy())}},y=class extends p{constructor(t,s={}){super(t,s),this.leaves=new Map,this.behaviors=new u(this.options);let e=[...t.childNodes];t.replaceChildren(...e.map(r=>this.hydrate(r))),this.settle()}hydrate(t){if(t.nodeType===Node.TEXT_NODE){let e=document.createElement("span");e.className="ft-leaf";let r=new c(e,this.options,n=>{n!=="idle"?this.event(n):this.settle()});return this.leaves.set(e,r),r.seed(t.textContent,this.options.animateInitial),e}if(t.nodeType!==Node.ELEMENT_NODE)return t.cloneNode();let s=t.cloneNode(!1);if(t.hasAttribute("data-ft-copy"))s.textContent=t.textContent;else for(let e of t.childNodes)s.append(this.hydrate(e));return this.behaviors.bind(s),s}attributes(t,s){for(let e of[...t.attributes])e.name!=="style"&&e.name!=="data-ft-state"&&!s.hasAttribute(e.name)&&t.removeAttribute(e.name);for(let e of s.attributes)e.name!=="style"&&t.getAttribute(e.name)!==e.value&&t.setAttribute(e.name,e.value);for(let e of o.styles){let r=s.style.getPropertyValue(e);r?t.style.setProperty(e,r):t.style.removeProperty(e)}}remove(t){let s=[t,...t.querySelectorAll?.(".ft-leaf")||[]];for(let e of s){let r=this.leaves.get(e);r&&(r.destroy(),this.leaves.delete(e))}this.behaviors.releaseTree(t)}setRenderedHTML(t){this.check();let s=E(t);this.options=d(s,this.overrides),this.behaviors.options=this.options;for(let e of this.leaves.values())e.configure(this.options);this.event("before-render"),x(this.element,s,this),this.event("render"),this.settle()}settle(){this.leaves&&[...this.leaves.values()].every(t=>t.nodes.length===t.parts.length)&&this.event("idle")}whenIdle(){return Promise.all([...this.leaves.values()].map(t=>t.whenIdle()))}flush(){this.check();for(let t of this.leaves.values())t.flush();this.settle()}configure(t){super.configure(t),this.behaviors.options=this.options;for(let s of this.leaves.values())s.configure(this.options)}destroy(){if(!this.disposed){for(let t of this.leaves.values())t.destroy();this.leaves.clear(),this.behaviors.destroy(),this.finishDestroy()}}},g=class extends p{constructor(t,s={}){super(t,s),this.behaviors=new u(this.options),this.behaviors.bind(t)}configure(t){super.configure(t),this.behaviors.options=this.options}destroy(){this.disposed||(this.behaviors.destroy(),this.finishDestroy())}};var h=new WeakMap;function T(i,t={}){if(!h.has(i)){let s=i.hasAttribute("data-ft-image")?new g(i,t):i.dataset.flowtoken==="markdown"?new y(i,t):new m(i,t);h.set(i,s),i.addEventListener("flowtoken:destroy",()=>{h.get(i)===s&&h.delete(i)},{once:!0})}return h.get(i)}function H(i){let t=h.get(i);h.delete(i),t?.destroy()}function k(i=document){i.matches?.("[data-flowtoken], [data-ft-image]")&&T(i);for(let t of i.querySelectorAll("[data-flowtoken], [data-ft-image]"))t.hasAttribute("data-ft-image")&&t.closest('[data-flowtoken="markdown"]')||T(t)}typeof document<"u"&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",()=>k(),{once:!0}):k(),document.addEventListener("htmx:afterSwap",i=>k(i.detail?.target||i.target)));export{g as FlowImage,y as FlowMarkdown,m as FlowToken,N as animations,T as mount,k as mountAll,l as tokenize,H as unmount};

py_flowtoken/streaming.py

@@ -0,0 +1,89 @@
+import json
+import re
+from dataclasses import dataclass, field
+
+
+def tokenize(text: str, sep: str = "word") -> list[str]:
+    if sep == "word":
+        return [part for part in re.split(r"(\s+)", text) if part]
+    if sep == "char":
+        return list(text)
+    if sep == "diff":
+        return [text] if text else []
+    raise ValueError('sep must be "word", "char", or "diff"')
+
+
+@dataclass(frozen=True)
+class Update:
+    text: str
+    delta: str
+    reset: bool
+    revision: int
+
+    def as_dict(self):
+        return {
+            "text": self.text,
+            "delta": self.delta,
+            "reset": self.reset,
+            "revision": self.revision,
+        }
+
+    def sse(self, event: str = "flowtoken") -> str:
+        if not re.fullmatch(r"[\w-]+", event):
+            raise ValueError("Invalid SSE event name")
+        return f"event: {event}\ndata: {json.dumps(self.as_dict(), ensure_ascii=False)}\n\n"
+
+
+@dataclass
+class TextStream:
+    text: str = ""
+    revision: int = 0
+    chunks: list[str] = field(default_factory=list)
+
+    def __post_init__(self):
+        if self.text and not self.chunks:
+            self.chunks = [self.text]
+
+    def update(self, text: str) -> Update:
+        if not isinstance(text, str):
+            raise TypeError('Expected text')
+        if text == self.text:
+            return Update(self.text, '', False, self.revision)
+        if text.startswith(self.text):
+            return self.append(text[len(self.text):])
+        self.text = text
+        self.chunks.clear()
+        if text:
+            self.chunks.append(text)
+        self.revision += 1
+        return Update(text, text, True, self.revision)
+
+    def append(self, delta: str) -> Update:
+        if not isinstance(delta, str):
+            raise TypeError('Expected text delta')
+        if delta:
+            self.text += delta
+            self.chunks.append(delta)
+            self.revision += 1
+        return Update(self.text, delta, False, self.revision)
+
+    def tokens(self, sep: str = "diff") -> list[str]:
+        return self.chunks.copy() if sep == "diff" else tokenize(self.text, sep)
+
+
+def encode_event(event: Update | str | bytes) -> str | bytes:
+    if isinstance(event, Update):
+        return event.sse()
+    if isinstance(event, (str, bytes)):
+        return event
+    raise TypeError("Stream events must be Update, str, or bytes")
+
+
+def iter_sse(events):
+    for event in events:
+        yield encode_event(event)
+
+
+async def aiter_sse(events):
+    async for event in events:
+        yield encode_event(event)

py_flowtoken-0.3.1.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: py-flowtoken
+Version: 0.3.1
+Summary: A Python adaptation of FlowToken for animated text and Markdown streaming without React
+Project-URL: Repository, https://github.com/jcllobet/py-flowtoken
+Project-URL: Documentation, https://github.com/jcllobet/py-flowtoken#readme
+Project-URL: Issues, https://github.com/jcllobet/py-flowtoken/issues
+Project-URL: Upstream, https://github.com/Ephibbs/flowtoken
+Author: py-flowtoken contributors
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.10
+Requires-Dist: linkify-it-py<3,>=2
+Requires-Dist: markdown-it-py<4,>=3
+Requires-Dist: mdit-py-plugins<0.5,>=0.4
+Requires-Dist: pygments<3,>=2.19
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: hatchling<2,>=1.27; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django<5.3,>=5.2; extra == 'django'
+Provides-Extra: fasthtml
+Requires-Dist: python-fasthtml>=0.14.17; extra == 'fasthtml'
+Provides-Extra: flask
+Requires-Dist: flask<4,>=3.1; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# py-flowtoken
+
+Smooth, word-by-word text and Markdown streaming for **FastHTML, Flask, and Django**. Python 3.10+. No React or Node runtime required.
+
+## Install
+
+```sh
+pip install py-flowtoken
+```
+
+Choose your framework to install its dependencies and follow the setup guide:
+
+| Framework | Install | Setup |
+| --- | --- | --- |
+| FastHTML | `pip install "py-flowtoken[fasthtml]"` | [FastHTML guide](https://github.com/jcllobet/py-flowtoken/blob/main/docs/fasthtml.md) |
+| Flask | `pip install "py-flowtoken[flask]"` | [Flask guide](https://github.com/jcllobet/py-flowtoken/blob/main/docs/flask.md) |
+| Django | `pip install "py-flowtoken[django]"` | [Django guide](https://github.com/jcllobet/py-flowtoken/blob/main/docs/django.md) |
+
+![FlowToken animation demo](https://nextjs-omega-five-46.vercel.app/demo.gif)
+
+*Demo from [FlowToken](https://github.com/Ephibbs/flowtoken), the original library this package adapts.*
+
+## Try it with FastHTML
+
+Install the FastHTML extra above, then save this as `demo.py`:
+
+```python
+from fasthtml.common import FastHTML
+from py_flowtoken import AnimatedText
+from py_flowtoken.adapters.fasthtml import asset_tags, mount_assets
+
+app = FastHTML(hdrs=asset_tags())
+mount_assets(app)
+
+@app.get('/')
+def home():
+    return AnimatedText('Hello from Python, one word at a time.', id='answer')
+```
+
+Run `uvicorn demo:app --reload` and open **http://127.0.0.1:8000**. The text animates as the page loads.
+
+## Stream updates
+
+Connect incoming text to the browser renderer:
+
+```javascript
+import {mount} from '/flowtoken/flowtoken.js';
+
+const view = mount(document.getElementById('answer'));
+view.setText('Hello');
+view.setText('Hello world');
+```
+
+Use `setText(snapshot)` for the full current text, or `append(chunk)` for new text only. Existing words stay in place; corrections update the changed portion. The [streaming guide](https://github.com/jcllobet/py-flowtoken/blob/main/docs/streaming.md) connects a Python generator to the browser with SSE.
+
+## Configure text or Markdown
+
+```python
+from py_flowtoken import AnimatedMarkdown
+
+answer = AnimatedMarkdown(
+    '**Hello**, world!',
+    id='answer',
+    sep='word',
+    animation='fadeIn',
+    animation_duration='0.25s',
+    interval_ms=35,
+    code_style='monokai',
+)
+```
+
+Use `sep='word'` for word-by-word animation, `'char'` for characters, or `'diff'` for appended chunks. Text defaults to word mode; Markdown defaults to diff mode. Set `animation=None` to disable animation. Reduced-motion preferences are respected automatically.
+
+Markdown includes tables, task lists, syntax highlighting, code-copy buttons, images, and Python custom tags. See the [API and configuration reference](https://github.com/jcllobet/py-flowtoken/blob/main/docs/api.md) for animation names, image sizing, custom components, and lifecycle methods.
+
+[MIT license](https://github.com/jcllobet/py-flowtoken/blob/main/LICENSE). An independent Python adaptation of [Ephibbs/flowtoken](https://github.com/Ephibbs/flowtoken), not an official release from its maintainers.

py_flowtoken-0.3.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+py_flowtoken/__init__.py,sha256=VxLo3hcfJses0CCjRah9kCpjUV4hM_2F0RjrskRgxqA,446
+py_flowtoken/assets.py,sha256=1UopjvYj07Cmb5Dhw_MNj2TttlLtraTm5fWGqfGNnPY,499
+py_flowtoken/components.py,sha256=Y8EBDYwyEpDczJVbc9MIv9BOgSslP3xEy1ldA6G6UXs,4515
+py_flowtoken/core.py,sha256=_JlCAlSTW2napG6FsxBT20s71owAYzz1zpy0PO89_Do,394
+py_flowtoken/options.py,sha256=hr5NiAQjSS7GDkjaVZpI83L1jl-Br70TDKdLaAGe1zg,3053
+py_flowtoken/policy.py,sha256=OLg6nXFyHNlUChjCgOuzCLeE3oG1GA_NwRwn3vVmUqI,3148
+py_flowtoken/rendering.py,sha256=30RcVbZ8ut_sTl8bwAlDTghY5P1-wVpJBXgO3-1hCDU,6380
+py_flowtoken/schema.json,sha256=MaxscG1nRc_llzTJitHT_SuQqLNTp0NPR3cxn64INd4,1887
+py_flowtoken/streaming.py,sha256=3hQyKjvEEIZt2n9pFhMSutU3fGtHeKP6053JDzExXWU,2538
+py_flowtoken/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+py_flowtoken/adapters/fasthtml.py,sha256=PdYRyDEIOjOqW0NKJMeMq_fiZEMEsxNG2Nef9czBdfM,958
+py_flowtoken/adapters/flask.py,sha256=RzLtFdja2dnJOPxpzEPoVX3XHNBg0LyJDhyEEQvV1CM,2644
+py_flowtoken/adapters/django/__init__.py,sha256=UqTSy2-UXsCNo1ffgbkb-fQJG22sFrsmJNioDDFw07Y,60
+py_flowtoken/adapters/django/apps.py,sha256=5e0V8jyTMu5hgpdKy-VaFdu5TzajaUyLRpp31qq6oTY,255
+py_flowtoken/adapters/django/urls.py,sha256=QiqBANoqe7iVurzZOZtY_AVPjEM9CJlCCy8DTkiPvWI,142
+py_flowtoken/adapters/django/views.py,sha256=kVsX8ANBNRaW6TPwpBWNvHmPCPUjETT7rHw9k5Yczy0,974
+py_flowtoken/adapters/django/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+py_flowtoken/adapters/django/templatetags/flowtoken.py,sha256=SUW1GvaflzLBjRLy06LjxGpi358xyy4w3bVWGzAOvP0,1410
+py_flowtoken/static/py_flowtoken/flowtoken.css,sha256=Q1AEF87tXfViDXnS3lfJTlEIf8LcFza6bLYa392rSaA,2207
+py_flowtoken/static/py_flowtoken/flowtoken.js,sha256=e36KbCg8VkWLOk9c6ZB_T9FG6NKULiruAyh37zedH2M,14170
+py_flowtoken-0.3.1.dist-info/METADATA,sha256=ujJ7IUyLm8p8QolTrZm-APkEvGFTqt4IFnXkMf3kYQg,4155
+py_flowtoken-0.3.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+py_flowtoken-0.3.1.dist-info/licenses/LICENSE,sha256=au4mobkA9c4PK76n_idRfoUBONsdbcNyuowHBo8lA84,1082
+py_flowtoken-0.3.1.dist-info/licenses/NOTICE,sha256=8_wuejU6HAs5Ps_Dn-xkHZfXeiPR-Dxm147lMCSe9Ec,571
+py_flowtoken-0.3.1.dist-info/RECORD,,

py_flowtoken-0.3.1.dist-info/WHEEL

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

py_flowtoken-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 py-flowtoken contributors
+
+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.

py_flowtoken-0.3.1.dist-info/licenses/NOTICE

@@ -0,0 +1,11 @@
+py-flowtoken is an independent Python adaptation of FlowToken by Ephibbs
+and contributors: https://github.com/Ephibbs/flowtoken
+
+The named animation effects and their keyframe definitions are adapted from
+FlowToken. The README demonstration GIF comes from the original FlowToken
+README: https://nextjs-omega-five-46.vercel.app/demo.gif
+
+Python rendering, framework adapters, streaming state, and the browser
+renderer are implemented in this repository. No upstream React runtime is
+included in the distribution. py-flowtoken is released under the MIT License
+in LICENSE.