Metadata-Version: 2.4
Name: probo-ui
Version: 1.3.2
Summary: Python Rendered Objects for Backend-Oriented UI is A declarative, type-safe ,Python-Native template Rendering Framework and Meta-framework for Django.
Project-URL: Bug Tracker, https://github.com/MojahiD-0-YouneSS/probo/issues
Project-URL: Documentation, https://MojahiD-0-YouneSS.github.io/probo/
Project-URL: Funding, https://ko-fi.com/youness_mojahid
Author-email: Youness Mojahid <mojahidyouness0@gmail.com>
License: MIT License
        
        Copyright (c) 2025 YOUNESS MOJAHID
        
        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.
License-File: LICENSE
Classifier: Framework :: Django
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: beautifulsoup4>=4.14.2
Requires-Dist: bottle>=0.13.4
Requires-Dist: cssutils>=2.11.1
Requires-Dist: django>=4.2.27
Requires-Dist: lxml>=4.9.0
Requires-Dist: pytest-django>=4.11.1
Requires-Dist: pytest>=8.4.2
Requires-Dist: rich>=13.0.0
Requires-Dist: tinycss2>=1.2.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# 🐘 Probo UI
![PyPI](https://img.shields.io/pypi/v/probo-ui)
![Python](https://img.shields.io/pypi/pyversions/probo-ui)
![License](https://img.shields.io/github/license/MojahiD-0-YouneSS/probo)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://MojahiD-0-YouneSS.github.io/probo/)
![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen)
[![Discord](https://img.shields.io/badge/chat-Discord-5865F2)](https://discord.gg/jnZRbVasgd)
![Last Commit](https://img.shields.io/github/last-commit/MojahiD-0-YouneSS/probo)
![Repo Size](https://img.shields.io/github/repo-size/MojahiD-0-YouneSS/probo)
![Tests](https://img.shields.io/badge/Tests-792%20Passed-brightgreen?style=flat-square&logo=github)
[![APIs](https://img.shields.io/badge/APIs-550%20Ready-blue?style=flat-square&logo=python&logoColor=white)](https://MojahiD-0-YouneSS.github.io/probo/)

Probo UI stands for Python Rendered Objects for Backend-Oriented UI is A Python-Native server-side Template Rendering Framework and Meta-framework for Django.Write Type-Safe Template Components, structure in HTML and styling in CSS with extra Logic in pure Python.that transforms Python objects into performant HTML/CSS with help with HTMX, creating a seamless bridge between Django's backend logic and the frontend interface. No context switching. No template spaghetti.

## 📣 Version 1.3.1 is Live!

Probo UI has officially reached stable v1.3 status. It is a backend-first framework.

## u can chose how youre UI can be:

- **Note**: all reserved python keywords are notated with capital letters e.g: id -> Id, class -> Class, map -> Map. in rendering phase the apropriate notaion is applied.

-   **string based**

```python
from probo import (
    div, 
    span,
)

greeting_partial = div(span("Hello, Probo",Class='badge'))
```
- **object tree based**
        

```python
from probo import (
    DIV,
    SPAN,
    P,
)

greeting_partial = DIV(SPAN("Hello, Probo",Class='badge'))
greeting_partial.add(P('this is a paragraph'))
```

## Why Probo?

- use your python skill in making dynamic UI templates.
- Explicit, readable and reusable layout
- Easier refactoring than HTML templates (it's python)
- IDE-friendly & type-safe

*For the deeper reasoning behind these choices, see Purpose & Philosophy ↓*

## ⚡ Purpose & Philosophy

Traditional Django development often requires context-switching between Python (views.py) and HTML/Jinja (templates/). Logic gets split, and typos in templates cause runtime errors.

Probo UI solves this by bringing the Frontend into Python:

🧠 Type-Safe UI: Write HTML in Python. If your code compiles, your HTML is valid.

🎨 Just-In-Time (JIT) CSS: Styles live with components. Probo UI scans your active components and generates a minified CSS bundle on the fly. No unused styles.

🛡️ Logic Gates: Built-in State Management. Components automatically hide themselves if required data (like user.is_authenticated) or permissions are missing.

🔌 Django Native: Deep integration with Django Forms and Requests via the RDT (Request Data Transformer).

## Some ProboUI Architecture & Concepts

- **Push & Clear**: When creating HTML elements via the ```Element``` object, the final output is pushed to the ```element``` attribute. The content and attributes used in that specific session are then cleared to maintain a clean state. To allow for cumulative processing, arguments can be passed to the class to "stash" previous results, serving as the content for the subsequent execution chain.

- **SSDOM (Server-Side DOM)**: Unlike traditional string-based templates, ProboUI treats HTML as a live object tree in Python. This allows for direct manipulation of the structure, attributes, and children of a component after its definition but before it is finalized into a string.

- **State Management**: Enforces strict rendering constraints on components and elements via ```ComponentState``` and ```ElementState```. To render an element, a props dictionary must be passed and validated against the expected schema; the rendering only proceeds if the state is valid.

- **CSS Sharing**: Performance optimization where components can share the same CSS objects. This prevents the definition of redundant style objects and reduces memory overhead during large-scale renders.

- **Shared Execution**: An internal efficiency pattern where every HTML tag is generated by the same unified logic under the hood, ensuring zero logic duplication and a consistent output format across the entire framework.

- **Head Registry**: Instead of manually managing meta, link, and script tags, ProboUI uses a centralized registry. Developers use dedicated methods to register head elements, which the engine then constructs and optimizes automatically.

- **Template Switching**: The ```Template``` engine allows you to construct a page and then dynamically modify or rebase its structure based on an entirely different template hierarchy, providing extreme flexibility in multi-layout applications.

- **Base Template**: Provides a standardized, overrideable page structure that facilitates rapid development by allowing developers to inherit and manipulate a global foundation without starting from scratch.

- **Attribute Managers**: Utilizes the ```ElementAttributeManipulator``` to manage an element's attributes. This creates a clean separation of concerns between the element's core logic and its HTML attribute state.

- **SDH (Static/Dynamic Hierarchy)**: Employs ```StaticData``` and ```DynamicData``` classes to resolve content within ```ElementState```. The hierarchy prioritizes data in the order of Dynamic > Static > Content, which is used when binding these values to specific attribute values.

- **URL Component Mapping**: Implemented via the ```TemplateComponentMap``` (TCM), this concept maps components to specific URLs. It allows for effortless discovery and access via URL names or slugified versions, bypassing manual route registration.

- **Django Syntax**: Provides the ability to generate ProboUI output formatted as standard Django template syntax, allowing ProboUI components to be seamlessly embedded into existing .html templates within a Django environment.

- **HTMX Integration**: Native support for creating HTMX-based elements, enabling high-speed, dynamic UX updates (partial page refreshes) without writing custom JavaScript.

- **Routing Engine**: A built-in, Bottle-based server designed for rapid prototyping and testing of Python-based static web pages before production deployment.

- **Configs & Shortcuts**: Utilizes specialized data classes to group configuration info for each shortcut execution, streamlining the API and reducing repetitive boilerplate code.

- **Component Styling**: By linking CSS selectors directly to components and verifying their existence in the template, ProboUI prevents the delivery of "dead CSS" while still fully supporting standard CSS cascading.

- **Bootstrap 5 Support**: Native integration for BS5 design tokens and components, allowing developers to implement professional layouts using familiar utility classes and components with zero extra configuration.

- **Probo-CLI**: A command-line interface used to scaffold custom ProboUI packages as static web apps. It also enables "Django Mutation," automatically injecting the necessary Probo directories (components/, pages/, probo_tcm.py) into existing Django projects.

- **proxy element**: The ```ProxyElement``` provides a mechanism to embed external logic or third-party objects directly into the SSDOM. It facilitates the integration of arbitrary objects by accepting the object and an optional render callable, which is utilized if the object does not possess a native ```render``` method.



# Performance diagnostics

The following table demonstrates the **Linear Scaling ($O(n)$)** capability of the ProboUI engine. These benchmarks verify the efficiency of the "Unified Tree" architecture when handling massive data volumes.

### Benchmarking Environment
* **Environment:** GitHub Codespaces (Standard Tier)
* **Operations:** Each test includes full Tree Build, a `find` operation, a `add` (modification), and a full `render`.

| Elements | Total String Length | Build Phase | Manipulation | Render Phase | Total Time |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **100** | 3,989 chars | 0.0003s | 0.0001s | 0.0009s | **0.0014s** |
| **1,000** | 41,789 chars | 0.0076s | 0.0001s | 0.0087s | **0.0164s** |
| **10,000** | 437,789 chars | 0.0305s | 0.0001s | 0.0894s | **0.1200s** |
| **100,000** | 4,577,789 chars | 0.3335s | 0.001s | 0.8622s | **1.1959s** |
| **250,000** | 11,777,789 chars | 1.0517s | 0.0001s | 2.0606s | **3.1125s** |
| **500,000** | 23,777,789 chars | 1.9719s | 0.001s | 4.1436s | **6.1156s** |
| **750,000** | 35,777,789 chars | 3.8622s | 0.0001s | 6.1664s | **10.0287s** |
| **1,000,000** | 47.777.789 chars | 5.4940s | 0.0001s | 8.4081s | **13.9022s** |

### Observations

* **Constant-Time Manipulation:** The "modification" phase (finding and adding nodes) remains consistently under **0.001s** even with 1 million nodes in memory.
* **Memory Threshold:** The framework engine successfully generated roughly a **48 MB** HTML string. Scaling beyond 1.5 million elements typically hits the physical RAM limits of the containerized environment.
* **Linearity:** ProboUI scales linearly. Doubling the element count consistently doubles the time, with no exponential "cliffs," making it safe for enterprise-scale documents.

# 📦 Installation

```bash 
        pip install probo-ui
```

# 🚀 Quick Example

Here is how you implement a reusable component in probo-ui:

```python
from probo import (
    li,div,h1,ul,strong,
)
def user_card(username):

    user_id = f'User_789{username}1323'

    user_info = {'practical-info':['python','javascript','docker','django']}

    li_el = [li(info) for info in user_info['practical-info']]

    card = div(
        h1(username,strong(user_id)),
        ul(*li_el)
        Class='card',
        style='color:red;'
    )

    return card

# Render it
html= user_card("Admin")
print(html)
```
### Output: 
```html 
    <div class='card'><h1>Admin<strong>User_789Admin1323</strong></h1><ul><li>python</li><li>javascript</li><li>docker</li><li>django</li></ul></div>
```
in case of permission based
```python
from probo.components import (
    Component,ComponentState, ElementState,StateProps,
)
from probo import (
    div,h1,strong,ul,
)

def user_card(username):

    props = StateProps(required=True,prop_equal_to={'username':'admin'})
    
    user_id = f'User_789{username}1323'
    
    user_info = {'practical-info':['python','javascript','docker','django']}
    
    li_el = ElementState('li', d_state='practical-info',i_state=True, strict_dynamic=True,props=props,)
    
    user_comp_state = ComponentState(
        d_data=user_info,
        li_el,
    )

    card = Component(
        name="UserCard",
        template=div(
            h1(username,strong(user_id)),
            ul(li_el.placeholder)},
            Class='card'),
        # Inject Data
        state=user_comp_state,
        props={'username':username}
    )

    return card

# Render it
html= user_card("Admin").render()

html2= user_card("admin").render()
```

### Output: 
- print(html)
```html
    <div class='card'><h1>Admin<strong>User_789Admin1323</strong></h1><ul></ul></div>
```
- print(html2)
```html
    <div class='card'><h1>Admin<strong>User_789Admin1323</strong></h1><ul><li>python</li><li>javascript</li><li>docker</li><li>django</li></ul></div>
```
[ 🚀 Get Started → ](user_guide.md)

💬 Community & Support Need help? Have a question that isn't a bug? Join our <a href='https://discord.gg/jnZRbVasgd'>Discord</a> Server to chat with other probo-ui developers.
