Metadata-Version: 2.4
Name: ooklept
Version: 1.1
Summary: A Python DSL for HTML + CSS
Project-URL: Homepage, https://github.com/dr-sandipan-chowdhury/ooklept
Project-URL: Issues, https://github.com/dr-sandipan-chowdhury/ooklept/issues
Author-email: "Dr. Sandipan Chowdhury" <kindleofsandipan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Description-Content-Type: text/markdown

<p align="center">
<img src="https://raw.githubusercontent.com/dr-sandipan-chowdhury/ooklept/refs/heads/main/banner.png" alt="ooklept banner">
</p>

*`Image Source: Gemini`*

```
                      [ OOKLEPT ]
                     ( Egg Thief )
                           |
         +----------------+----------------+
         |                                 |
     [ oo- ]                         [ -klept ]
 (Combining Form)                 (Combining Form)
         |                                 |
   Ancient Greek                     Ancient Greek
    ᾠόν (ōión)                       κλέπτης (kléptēs)
     "an egg"                           "a thief"
```

---

<p align="center">
<img src="https://raw.githubusercontent.com/dr-sandipan-chowdhury/ooklept/refs/heads/main/logo.svg" alt="ooklept logo" width="200">
</p>


**ooklept** or '*egg thief*' refers to Python (🐍) the snake that steals bird's eggs (🪺/🥚).

Here, Python (the programming language) steals HTML and CSS to create a beautiful, strictly-typed Domain-Specific Language (DSL). It also steals PHP's legendary philosophy to let you build full-stack web apps with just raw Python. No template engines, no complex routing files, just pure Python.

---

## 🐍 Why Ooklept? The Philosophy

Modern web development often forces you to juggle HTML templates, CSS files, complex routing mechanisms, and JavaScript frameworks.

**Ooklept asks a simple question: What if we just used Python?**

1. **The PHP Philosophy (File-Based Routing):** In PHP, if you make a file called `about.php`, it's instantly available at `/about`. Ooklept steals this! You drop a Python file in a directory, and it instantly becomes a web route.
2. **Goodbye Template Languages:** Jinja and Django templates are great, but they aren't Python. You lose your IDE's autocomplete, type checking, and native syntax. With Ooklept, your HTML *is* Python.
3. **Batteries Included Server:** Powered by FastAPI under the hood, you don't need to configure a web server to get started.

---

## 🚀 Quick Start

Writing a web app in Ooklept is as simple as writing a single script.

Create a file named `index.py` in your project folder:

```python
# index.py
from ooklept import o

# Globals magically injected by the Ooklept server!
_GET = globals().get("_GET", {})
_POST = globals().get("_POST", {})

username = str(_POST.get("username", ""))

if username:
    o.h1("Hello")
    o.p(username)
else:
    # Use context managers for nesting HTML elements!
    with o.form(method="post"):
        o.input(name="username", placeholder="User Name")
        o.input(type="submit")

```

Now, serve your app:

```bash
python -m ooklept.serve .

```

Visit `http://127.0.0.1:8000` and watch the magic happen!

---

## 🏗️ Architecture: How the Magic Works

Ooklept might feel like magic, but it relies on some incredibly clever Python features. Here is a peek under the hood:

### 1. The HTML Builder (Context Variables)

How does `with o.form():` know that `o.input()` belongs inside it?
Ooklept uses Python's `contextvars` to keep track of the "current context." When you use the `with` statement on an element, it temporarily registers itself as the parent. Any new element created inside that `with` block automatically appends itself to the parent's children.

### 2. The Server & `runpy` Execution

When a user requests a URL like `/about`, FastAPI catches it and finds the `about.py` file. Instead of treating it like a standard module import, Ooklept uses Python's built-in `runpy.run_path()`.
This allows Ooklept to:

* Execute the script from top to bottom on every request.
* Inject `_GET` and `_POST` dictionaries directly into the script's global execution state (just like PHP does with `$_GET` and `$_POST`).
* Capture the top-level HTML tree and render it to a string.

---

## 📖 Syntax Guide: Writing HTML in Python

Ooklept provides a massive autogenerated library of HTML tags with full type-hinting support.

### Creating Elements

Import `o` from `ooklept`. Every tag is a function.

```python
from ooklept import o

o.h1("Welcome to Ooklept")
o.br() # Void tags are handled automatically!

```

### Attributes and Styling

You can chain methods like `.attr()`, `.class_()`, and `.style()` to build complex elements gracefully. Python IDEs will autocomplete valid CSS properties and HTML attributes!

```python
(
    o.div()
    .class_("container main-layout")
    .style(background_color="blue", text_align="center")
    .attr(id="hero-banner", data_custom="yes")
)

```

*Note: Because `class` is a reserved keyword in Python, we use `.class_()`.*

### Nesting Elements

Use the `with` statement to build trees of HTML:

```python
with o.div().class_("card"):
    o.img().attr(src="avatar.png", alt="User Avatar")
    with o.div().class_("card-body"):
        o.h2("John Doe")
        o.p("Software Engineer")

```

### Security First

You don't need to worry about Cross-Site Scripting (XSS). Ooklept uses `html.escape()` under the hood for all text and attributes, ensuring your data is safely encoded before it reaches the browser.

---

## 🤝 Contributing to Ooklept

Want to help us steal more eggs? We'd love your contributions! Since Ooklept is built to be a lightweight, strictly-typed DSL, here are a few ways you can help:

1. **Enhance the Server (`serve.py`)**: Help us add things like middleware, static file serving (CSS/JS files), or session management.
2. **Refine Type Hints (`webtypes.py`)**: Our CSS and HTML types are autogenerated, but web standards evolve. Help us keep them accurate.
3. **Build Components**: Start building reusable Python functions that return complex UI components (like Modals, Navbars, etc.) using Ooklept tags.

### Development Setup

1. Clone the repository.
2. Ensure you have Python 3.10+ installed (we rely heavily on modern typing features like `Unpack` and `TypedDict`).
3. Explore `base.py` to understand the `Element` class—it's the beating heart of the HTML generator!

---

*Built with ❤️ (and a bit of thievery) for Python developers.*
