blu-react 0.0.1rc1__tar.gz

blu_react-0.0.1rc1/.gitignore

@@ -0,0 +1,8 @@
+/.venv/*
+!/.venv/.gitkeep
+/dist
+/docs/_build
+/docs/build
+
+.DS_Store
+__pycache__

blu_react-0.0.1rc1/.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+  - repo: https://github.com/PyCQA/autoflake
+    rev: v2.3.3
+    hooks:
+      - id: autoflake
+        args: [--in-place, --remove-all-unused-imports]
+  - repo: https://github.com/psf/black
+    rev: 24.1.1  # pin to a specific version
+    hooks:
+      - id: black
+        language_version: python3

blu_react-0.0.1rc1/.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python Debugger: Current File",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${file}",
+      "console": "integratedTerminal"
+    }
+  ]
+}

blu_react-0.0.1rc1/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true,
+  "python.analysis.typeCheckingMode": "strict",
+  "python.analysis.fixAll": [
+    "source.unusedImports"
+  ],
+  "python-envs.defaultEnvManager": "ms-python.python:venv",
+  "cursorpyright.analysis.typeCheckingMode": "strict"
+}

blu_react-0.0.1rc1/LICENSE

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

blu_react-0.0.1rc1/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: blu-react
+Version: 0.0.1rc1
+Summary: A full stack React framework for Python
+Project-URL: Homepage, https://github.com/johnlarson/blu
+Project-URL: Issues, https://github.com/johnlarson/blu/issues
+Author-email: John Larson <john.robert.larson@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.14
+Requires-Dist: aiofiles
+Requires-Dist: uvicorn
+Description-Content-Type: text/markdown
+
+
+
+# Blu
+
+*Blu is still in early testing and should not be used in production applications.*
+
+A full stack React framework for Python.
+
+
+```python
+from blu import client
+from blu.html import html, head, body, h1, button
+
+__client__ = True
+
+
+def __page__():
+    return html[
+        head,
+        body[
+            h1[
+                ClickCounter
+            ]
+        ]
+    ]
+    return ClickCounter
+
+
+@client
+def ClickCounter():
+    count, set_count = use_state(0)
+
+    def handle_click(e):
+        set_count(count + 1)
+    
+    return button(onClick=handle_click)[f"Clicks: {count}"]
+```
+
+## Installation
+
+```bash
+pip install -U blu
+```
+
+## Documentation
+
+Documentation available on readthedocs.io {TODO add link here.}

blu_react-0.0.1rc1/README.md

@@ -0,0 +1,47 @@
+
+
+# Blu
+
+*Blu is still in early testing and should not be used in production applications.*
+
+A full stack React framework for Python.
+
+
+```python
+from blu import client
+from blu.html import html, head, body, h1, button
+
+__client__ = True
+
+
+def __page__():
+    return html[
+        head,
+        body[
+            h1[
+                ClickCounter
+            ]
+        ]
+    ]
+    return ClickCounter
+
+
+@client
+def ClickCounter():
+    count, set_count = use_state(0)
+
+    def handle_click(e):
+        set_count(count + 1)
+    
+    return button(onClick=handle_click)[f"Clicks: {count}"]
+```
+
+## Installation
+
+```bash
+pip install -U blu
+```
+
+## Documentation
+
+Documentation available on readthedocs.io {TODO add link here.}

blu_react-0.0.1rc1/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

blu_react-0.0.1rc1/docs/_includes/client-element-call-notes.rst

@@ -0,0 +1,48 @@
+.. note::
+    
+    Calling a client element as a function does not immediately result in its rendering function being called; that call is deferred until the element is rendered on the client.
+
+.. note::
+    
+    Calling a client element as a function does not mutate the original client element; instead, it returns a copy of the original client element with the new render arguments.
+
+    .. code-block:: python
+
+        from blu import client
+        from blu.html import p
+
+        __client__ = True
+
+
+        @client
+        Greeting(name):
+            return p[f'Hello, {name}!']
+
+        original = Greeting('Adam')
+        copy = original('Brittany')
+
+        original  # <p>Hello, Adam!</p>
+        copy  # <p>Hello, Brittany!</p>
+
+.. note::
+
+    Calling a client element as a function completely replaces any existing render arguments.
+
+    .. code-block:: python
+
+        from blu import client
+        from blu.html import p
+
+        __client__ = True
+
+
+        @client
+        MyClientElement(a, b=2):
+            return p[f'{a},{b}']
+        
+
+        original = MyClientElement(3, b=4)
+        copy = original(1)
+
+        original  # <p>3,4</p>
+        copy  # <p>1,2</p>

blu_react-0.0.1rc1/docs/_includes/client-element-children.rst

@@ -0,0 +1,86 @@
+You can add children to an html element using square bracket notation:
+
+.. code-block:: python
+
+    from blu.html import div, p
+
+    div[
+        p['Hi.'],
+        p['Hello.']
+    ]
+
+.. code-block:: html
+
+    <div>
+        <p>Hi.</p>
+        <p>Hello.</p>
+    </div>
+
+.. note::
+
+    Using square bracket notation on an HTML element does not mutate the original; instead, it returns a copy with the new attributes.
+
+    .. code-block:: python
+
+        from blu.html import div
+
+        without_children = div
+        with_children = div['Hello, World!']
+
+        without_children  # <div></div>
+        with_children  # <div>Hello, World!</div>
+
+.. note::
+
+    When you set children on an HTML element, you completely replace any existing children, rather than appending to them:
+
+    .. code-block:: python
+
+        from blu.html import div
+
+        original = div['A', 'B']
+        
+        original['C', 'D']  # <div>CD</div>
+
+
+A child of an HTML element can be any of the following types:
+
+- Another :class:`blu.HTMLElement`.
+- A :py:class:`str`. In this case, it will be rendered as an HTML text node.
+- :py:data:`None`. Nothing is rendered in the place where a :py:data:`None` value is found.
+- A :py:class:`int`. This renders as a text node whose text is the :py:class:`str` representation of the integer.
+- A :py:class:`float`. This renders as a text node whose text is the :py:class:`str` representation of the float.
+- An :py:class:`Iterable <collections.abc.Iterable>` of valid children. This renders as all the child nodes contained in the :py:class:`Iterable <collections.abc.Iterable>`.
+- A :class:`blu.ClientElement` (see :ref:`Client-Side Rendering`).
+- A :class:`blu.Key`.
+
+.. code-block:: python
+
+    from blu.html import div, span, p
+
+    div[
+        span,
+        'Hello!',
+        None,
+        1,
+        1.0,
+        (
+            p,
+            'Hello again!',
+            None,
+            2,
+            2.0,
+        )
+    ]
+
+.. code-block:: html
+
+    <div>
+        <span></span>
+        Hello!11.0
+        <p></p>
+        Hello again!22.0
+    </div>
+
+
+.. include:: /_includes/iterables-must-use-keys-note.rst

blu_react-0.0.1rc1/docs/_includes/client-side-rendering-notes.rst

@@ -0,0 +1,129 @@
+.. note::
+
+    Why does the code in the previous example include the line ``__client__ = True``?
+    
+    By default, none of the `.py` files in your app will be sent to the user's web browser and therefore cannot be run client-side. To allow a module to run client-side, you must explicitly mark it by setting the module-level attribute ``__client__`` to ``True``.
+
+    In order for the client element to be rendered client-side, the code to do so must be available to the user's web browser, so the module where the client element is found, as well as any of its dependencies, must include ``__client__ = True``.
+
+    Because Blu checks for ``__client__ = True``, using static analysis, the module must include the exact text ``__client__ = True`` at the top level of its source code. For example, the following will *not* work:
+
+    .. code:: python
+
+        __client__ = 1 + 1 == 2
+
+
+    .. code:: python
+        
+        if 1 + 1 == 2:
+            __client__ = True
+
+    If you're familiar with full stack React frameworks for JavaScript, note that this is *not* the same as the ``"use client"`` directive in JavaScript React applications.
+
+.. note::
+    
+    Client elements cannot be created from asynchronous functions.
+
+    .. code-block:: python
+
+        from blu import client
+        from blu.html import p
+
+        # Wrong!
+        @client
+        async def Hello():
+            return p['Hello, World!']
+
+        
+        # Right.
+        @client
+        def Hello():
+            return p['Hello, World!']
+
+
+.. note::
+
+    Client-side code runs in a different environment than server-side code. If your client-side code uses an external library, make sure it is installed in the client environment by adding it to the list of client dependencies in ``app/__settings__.py`` (if the ``__settings__.py`` doesn't exist, create it)::
+
+        app/
+          __index__.py
+          __settings__.py
+
+    .. code-block:: python
+        :caption: app/__index__.py
+
+        import arrr
+        from blu import client
+
+        __client__ = True
+
+
+        def __page__():
+            return MyClientElement
+        
+
+        @client
+        def MyClientElement():
+            return p[
+                arrr.translate('Hello there. How are you?')
+            ]
+
+
+    .. code-block:: python
+        :caption: app/__settings__.py
+
+        CLIENT_REQUIREMENTS = ['arrr']
+
+
+.. note::
+
+    Client-side code runs in a different environment than server-side code. If your client-side code uses dependencies that aren't available on the server, make sure you check the environment before importing those dependencies:
+
+    .. code-block:: python
+        :caption: Wrong!
+        :emphasize-lines: 4
+
+        from blu import client
+        from blu.html import button
+        
+        from pyscript import window
+
+        __client__ = True
+
+
+        def __page__():
+            return GoToPyPIButton
+
+        
+        @client
+        def GoToPythonDotOrgButton():
+            return button(onClick=navigate_to_python_dot_org)
+
+        
+        def navigate_to_python_dot_org(e):
+            window.location = 'https://www.python.org'
+
+    .. code-block:: python
+        :caption: Right.
+        :emphasize-lines: 4-5
+
+        from blu import client, is_client
+        from blu.html import button
+        
+        if is_client:
+            from pyscript import window
+
+        __client__ = True
+
+
+        def __page__():
+            return GoToPythonDotOrgButton
+
+        
+        @client
+        def GoToPythonDotOrgButton():
+            return button(onClick=navigate_to_python_dot_org)
+
+        
+        def navigate_to_python_dot_org(e):
+            window.location = 'https://www.python.org'

blu_react-0.0.1rc1/docs/_includes/hook-note.rst

@@ -0,0 +1,3 @@
+.. note::
+
+    This function is a *hook*. For more information on hooks and the rules of calling them, see :ref:`note-on-hooks`.

blu_react-0.0.1rc1/docs/_includes/hooks.rst

@@ -0,0 +1,81 @@
+Blu is a React framework, and React provides a special type of function called a *hook*. These are the functions you import from Blu whose names start with ``use``. They are used for managing UI state and adding callbacks for lifecycle phases, and there are certain restrictions on how they can be used:
+
+1. A hook can only be called in the scope of a client element's rendering function body, or the scope of a custom hook's function body (a *custom hook* is any function whose name starts with ``use`` that calls other hooks).
+2. A client element rendering function or custom hook must call the same hooks in the same order *every time* the rendering function or custom hook is called. The best way to follow this rule is just to never call a hook in a conditional block or loop.
+
+Breaking either of these rules will result in undefined behavior.
+
+.. code-block:: python
+
+    from blu import client, use_ref
+    from blu.html import p
+
+
+    # Wrong! This function is not a client element or custom hook, so
+    # it can't call hooks.
+    def some_function():
+        some_ref = use_ref()
+    
+
+    # Right. This is a client element whose rendering function calls
+    # the use_ref hook.
+    @client
+    def SomeClientElement():
+        some_ref = use_ref()
+        return p['(client element content)']
+
+    
+    # Right. Because this function's name starts with "use", it is a
+    # valid custom hook and can call other hooks.
+    def use_some_hook():
+        return use_ref()
+
+    
+    # Wrong! Hook called in a conditional block.
+    @client
+    def SomeClientElement(some_condition):
+        if some_condition:
+            my_ref = use_ref()
+        else:
+            my_ref = None
+        return p['(client element content)']
+    
+    
+    # Wrong! Hook called in a conditional block.
+    def use_some_hook(some_condition):
+        if some_condition:
+            return None
+        else:
+            return use_ref()
+    
+
+    # Wrong! Hook called in a loop.
+    def use_some_hook(some_list):
+        result = []
+        for item in some_list:
+            result.append(use_ref())
+        return result
+    
+    
+    # Wrong! Hook called in a loop.
+    @client
+    def SomeClientElement(num_iterations):
+        i = 0
+        while i < num_iterations:
+            my_ref = use_ref()
+        return p['(client element content)']
+
+    
+    # Wrong! use_my_custom_hook is a custom hook, so it must *not* be
+    # called in a conditinal block.
+    @client
+    def SomeClientElement(some_condition):
+        if some_condition:
+            value = use_my_custom_hook()
+        else:
+            value = None
+        return p['(client element content)']
+
+
+    def use_my_custom_hook():
+        return use_ref()

blu_react-0.0.1rc1/docs/_includes/iterables-must-use-keys-note.rst

@@ -0,0 +1,59 @@
+.. note::
+
+    Items in :py:class:`Iterable <collections.abc.Iterable>` children (other than :py:class:`str`\ s and :py:class:`tuple`\ s) must be keyed:
+
+    .. code-block::
+
+        from blu import Key
+        from blu.html import div
+
+        PEOPLE = [
+            {'id': 0, 'name': 'Ana'},
+            {'id': 1, 'name': 'Bill'},
+            {'id': 2, 'name': 'Charlotte'},
+        ]
+
+        # Wrong!
+        div[
+            [
+                div[f'Hello, {person["name"]}!']
+                for person in PEOPLE
+            ],
+        ]
+
+        # Right.
+        div[
+            [
+                div(key=person['id'])[f'Hello, {person["name"]}!']
+                for person in PEOPLE
+            ],
+        ]
+
+        # Wrong!
+        div[
+            [f'Hello, {person["name"]}!' for person in PEOPLE],
+        ]
+
+        # Right.
+        div[
+            [
+                Key(person["id"])[
+                    f'Hello, {person["name"]}',
+                ]
+                for person in PEOPLE
+            ],
+        ]
+
+        # Right.
+        div[
+            (
+                'Hello, Ana!',
+                'Hello, Bill!',
+                'Hello, Charlotte!',
+            ),
+        ]
+
+        # Right.
+        div['Hello, Ana! Hello, Bill! Hello, Charlotte!']
+
+    The rationale here is that, in :ref:`client-side rendering <Client-Side Rendering>`, items in a sequence may be moved around in response to user interaction. Giving keys to these items allows React to maintain state and render efficiently even when an item's position in a sequence changes.

blu_react-0.0.1rc1/docs/_static/styles.css

@@ -0,0 +1,26 @@
+.custom-footer {
+  max-width: 940px;
+  margin-left: auto;
+  margin-right: auto;
+  display: flex;
+  flex-direction: row;
+}
+
+.custom-footer-spacer {
+  max-width: 220px;
+  width: 100%;
+  height: 10px;
+}
+
+.footer-nav {
+  width: 100%;
+  list-style-type: none;
+  padding: 0;
+  margin-left: 30px;
+  margin-right: 30px;
+  margin-bottom: 40px;
+  margin-top: 40px;
+  display: flex;
+  flex-direction: row;
+  justify-content: space-between;
+}

blu_react-0.0.1rc1/docs/_templates/layout.html

@@ -0,0 +1,30 @@
+{% extends "!layout.html" %}
+
+{% block document %}
+  {{ super() }}
+{% endblock %}
+{% block content %}
+  <div class="admonition warning">
+    <p class="admonition-title">Warning</p>
+    <p>Blu is still in early testing and should not be used in production applications.</p>
+  </div>
+  {{ super() }}
+{% endblock %}
+{% block footer %}
+  <div class="custom-footer">
+  <div class="custom-footer-spacer"></div>
+  <ul class="footer-nav">
+    {%- if prev %}
+      <li class="prev">
+        <a href="{{ prev.link|e }}">&lt; {{ prev.title }}</a>
+      </li>
+    {% endif %}
+    {%- if next %}
+      <li class="next">
+        <a href="{{ next.link|e }}">{{ next.title }} &gt;</a>
+      </li>
+    {%- endif %}
+  </ul>
+  </div>
+  {{ super() }}
+{% endblock %}

blu_react-0.0.1rc1/docs/api-reference/blu.html.rst

@@ -0,0 +1,4 @@
+``blu.html``
+============
+.. automodule:: blu.html
+    :special-members: __getattr__