docs(readme): fix broken Quick Example and document ASGI#24
Open
LoboGuardian wants to merge 2 commits into
Open
docs(readme): fix broken Quick Example and document ASGI#24LoboGuardian wants to merge 2 commits into
LoboGuardian wants to merge 2 commits into
Conversation
The headline example imported `HTeaPot` and used `app.wsgi_app`, neither of which exists — the package exports `htealeaf` (an alias of the Server class) and the app object is itself the WSGI/ASGI callable, so the snippet failed at import for every new user. It also omitted the required `enable_reactivity(app)` call, without which the reactive counter never wires up. Rewrite the example to mirror demo/demo_wsgi.py (verified-runnable), pass an explicit Store id to avoid instance collisions, add an ASGI section and a "Running the demo" section, note the Python >=3.10 requirement, and link docs/PY2JS.md.
The develop branch renamed the package to lowercase htealeaf, exports the app class as HteaLeaf (the htealeaf factory alias is gone), removed enable_reactivity in favour of SuperStore(app) wiring, and dropped Store.react() — stores are now read server-side with .read() and the client re-renders via DOM reconciliation. Store ids are auto-generated per instance since Az107#25, so the explicit id workaround is unnecessary. Also marks async-first architecture done in the roadmap and notes the session TTL work on feature/alb-28.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
While trying the framework, the README's headline Quick Example does not run:
HTeaPot— the package exportshtealeaf(an alias of theServerclass); there is noHTeaPotsymbol, so the import raisesImportError.application = app.wsgi_app— nowsgi_appattribute exists anywhere in the source. TheServerinstance is itself the WSGI/ASGI callable and is passed directly to the server (as indemo/demo_wsgi.py).enable_reactivity(app), without which the reactive runtime (_engine/helper.js) is never injected and the counter's buttons don't wire up.This is the first thing a new user copies, so it fails immediately.
Changes (README only)
demo/demo_wsgi.py:htealeaf(adapters.WSGI),enable_reactivity(app), and passingappstraight tomake_server.Store(..., id="counter")and note why (stores without an explicit id currently share one id).adapters.ASGI+uvicorn) and mention theCGIadapter.docs/PY2JS.md.All snippets were checked against the exported API in
src/HTeaLeaf/__init__.pyand the demos. No code behavior is changed.Note for maintainers
A couple of code-level issues make the counter only partially reactive today and are worth a follow-up (kept out of this doc PR):
Store.react()builds its class name from theidbuiltin instead of thepathargument, andStore.__init__(id=str(uuid4()))evaluates the default once at import so stores collide. Happy to open a separate PR for those.