ooklept 1.1

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"

---

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:

# 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:

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.

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!

(
    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:

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.