Metadata-Version: 2.4
Name: duckframework
Version: 2.0.0
Summary: Duck is a powerful, open-source, full-fledged Python-based web server, framework, and reverse proxy designed for building modern, customizable web applications — from small sites to large-scale platforms.
Author-email: Brian Musakwa <digreatbrian@gmail.com>
Maintainer-email: Brian Musakwa <digreatbrian@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://duckframework.com
Project-URL: Source, https://github.com/duckframework/duck
Project-URL: Issues, https://github.com/duckframework/duck/issues
Project-URL: Funding, https://duckframework.xyz/contribute
Project-URL: Documentation, https://docs.duckframework.com
Keywords: Python,web framework,web server,reverse proxy,HTTP/2,WSGI,ASGI,Django integration,Flask,Tornado,FastAPI,microservices,middleware,high-performance,async,Duck framework,routing,load balancing,HTTP proxy,web application
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: Django>=5.1.5
Requires-Dist: Jinja2>=3.1.5
Requires-Dist: watchdog>=4.0.1
Requires-Dist: requests>=2.31.0
Requires-Dist: h2>=4.2.0
Requires-Dist: msgpack>=1.1.1
Requires-Dist: diskcache
Requires-Dist: colorama
Requires-Dist: tzdata
Requires-Dist: click
Requires-Dist: asgiref>=3.8.1
Requires-Dist: psutil>=7.0.0
Requires-Dist: rich>=14.1.0
Requires-Dist: setproctitle
Requires-Dist: pyJWT
Requires-Dist: pynacl
Dynamic: license-file

# Duck Framework
[![Python >=3.10](https://img.shields.io/badge/python->=3.10-blue.svg)](https://www.python.org/downloads/release/python-3100/)
[![GitHub stars](https://img.shields.io/github/stars/duckframework/duck?style=social)](https://github.com/duckframework/duck/stargazers)
[![License](https://img.shields.io/github/license/duckframework/duck)](https://github.com/duckframework/duck/blob/main/LICENSE)
[![Build Status](https://img.shields.io/github/actions/workflow/status/duckframework/duck/docs.yml?branch=main)](https://github.com/duckframework/duck/actions)
[![Open Issues](https://img.shields.io/github/issues/duckframework/duck)](https://github.com/duckframework/duck/issues)
[![Contributors](https://img.shields.io/github/contributors/duckframework/duck)](https://github.com/duckframework/duck/graphs/contributors)
[![HTTPS](https://img.shields.io/badge/HTTPS-supported-brightgreen.svg)](#)
[![HTTP/2](https://img.shields.io/badge/HTTP--2-supported-brightgreen.svg)](#)
[![WebSocket](https://img.shields.io/badge/WebSocket-supported-brightgreen.svg)](#)
[![Async Views](https://img.shields.io/badge/Async-WSGI%2FASGI-blue.svg)](#)
[![Task Automation](https://img.shields.io/badge/Task-Automation-blueviolet.svg)](#)
[![Content Compression](https://img.shields.io/badge/Compression-gzip%2C%20brotli%2C%20deflate-blue.svg)](#)
[![SSL Auto-Renewal](https://img.shields.io/badge/SSL-Auto%20Renewal-brightgreen.svg)](#)
[![Resumable Downloads](https://img.shields.io/badge/Downloads-Resumable-orange.svg)](#)
[![Security](https://img.shields.io/badge/Security-DoS%2C%20SQLi%2C%20CmdInj-red.svg)](#)
[![Auto Reload](https://img.shields.io/badge/AutoReload-DuckSight-yellow.svg)](#)
[![Django Integration](https://img.shields.io/badge/Django-Integration-blue.svg)](#)
[![Monitoring](https://img.shields.io/badge/Monitoring-CPU%2FRAM%2FDisk%2FI%2FO-brightgreen.svg)](#)

**Duck Framework** is an open-source Python web framework and web server with built-in reactive UI and real-time WebSocket support. Build high-performance, scalable, server-side reactive web applications — without separate frontend frameworks or complex JavaScript stacks.

---

## Real world apps built with Duck framework:

1. [Snip - URL Shortener](https://snip.duckframework.com)
2. [Quill - AI Design Generator](https://quill.duckframework.com)
3. [Counter - Simple Counter App](https://duckframework.com/counterapp)

---

## Duck simplifies web development with:

1. [**Built-in HTTPS support**](https://docs.duckframework.com/main/https-and-http2) for secure connections  
2. **Native HTTP/2 support** with **HTTP/1** backward compatibility [link](https://docs.duckframework.com/main/https-and-http2)  
3. Hassle-free **free SSL certificate generation** with **automatic renewal** [link](https://docs.duckframework.com/main/free-ssl-certificate)  
4. [**Lively Component System**](https://docs.duckframework.com/main/lively-components) — with `VDom Diffing` (support for fast UI's) 
5. [**WebSocket support**](https://docs.duckframework.com/main/websocket) — modern websocket implementation with `per-message compression`.
6. Built-in [task automation](https://docs.duckframework.com/main/automations) — no need for [cron jobs](https://en.m.wikipedia.org/wiki/Cron)  
7. Automatic **content compression** using `gzip`, `deflate` or `brotli`
8. Support for **chunked transfer encoding**  
9. Easy integration with existing **Django** projects using [`django-add`](https://docs.duckframework.com/main/django-integration) command.
10. Organized routing with **Duck** [`Blueprints`](https://docs.duckframework.com/main/blueprint)
11. Full support for **async views** or asynchronous code even in [`WSGI`](https://docs.duckframework.com/main/wsgi) environment
12. Dynamic project generation with `makeproject` (`mini`, `normal`, or `full`)  
13. Runs on both [`WSGI`](https://docs.duckframework.com/main/wsgi) and [`ASGI`](https://docs.duckframework.com/main/asgi) environments, can even run `async` protocols like `HTTP/2` or `WebSockets` on `WSGI`.  
14. High-performance with low-latency response times  
15. **Resumable downloads** for large files  
16. Protection against **DoS**, **SQL Injection**, **Command Injection**, and other threats  
17. **Auto-reload** in debug mode for rapid development  
18. [**Free production SSL**](https://docs.duckframework.com/main/free-ssl-certificate) — no certificate costs  
19. **Automatic SSL renewal** using `certbot` plus Duck automation system
20. Comes with built-in web development tools and helpers  
21. [Log management](https://docs.duckframework.com/main/logging) with `duck logs` and file-based logging by default  
22. Real-time [system monitoring](https://docs.duckframework.com/main/monitoring) for CPU, RAM, Disk usage, and I/O activity with `duck monitor`
23. Easily generate app sitemap using command [`duck sitemap`](https://docs.duckframework.com/main/sitemap) or just use 
       the builtin blueprint [`duck.etc.apps.essentials.blueprint.Sitemap`](https://docs.duckframework.com/main/sitemap) for dynamic cached sitemap serving.
24. Comes with independant [micro applications](https://docs.duckframework.com/main/microapps) which runs on their own servers for micro services support.
25. Highly **customizable** to fit any use case  

And more — see [feature list](https://duckframework.com/features)

## Upcoming Features

1. **HTTP/3 with QUIC** – Faster, modern transport for improved performance.  
2. **QUIC WebTransport** – A next-gen alternative to WebSockets for real-time communication.  
3. **Component Pre-rendering System** – A system to preload components in the background thread to reduce initial load times of component trees.
4. **Customizable Dashboards** – Tailor interfaces to your workflow and preferences.  
5. **MQTT (Message Queuing Telementry Transport) Integration** – Run your own broker and manage IoT devices with ease.  
6. **Duck WebApp to APK** – Easily convert a Duck web application to APK.
7. **DuckSight Hot Reload** – Instead of full reload on file changes, implement **hot reload** for the **DuckSight Reloader**. This is faster and efficient than full reload.
8. **Internal Updates** – Implement logic for listing and securely applying updates when available, utilizing cryptographic code signing (using standards like TUF) to verify GitHub-sourced updates, protecting against rollbacks, and man-in-the-middle exploits.
9. ~~**Worker Processes** – Use of worker processes to utilize all available CPU cores for improved request handling.~~
10. **Complete Reverse Proxy Server** – **Duck** only acts as reverse proxy for  Django only. Need to make Duck a full-fledged reverse proxy server with optional sticky sessions.
11. ~~**Component Mutation Observer** – Need to build an optional component mutation observer for keeping track of child changes for fastest re-render (approx. 75x fast on unchanged children).~~
12. **MCP (Model Context Protocol) Server** – Need to make it easy for creating MCP servers for easy AI communication. 
13. **JWT (JSON-based Web Token) Authentication** – Need  to add JWT authentication persistent logins.
14. **...and more** – [Request a feature](./feature_request.md)

---

## 🦆 Fun Facts

- The **Duck** official website is powered by the **Duck** framework itself—showcasing a true "dogfooding" approach!
- [**Duck's Lively components**](https://docs.duckframework.com/main/lively-components) bring you a **Lively UI** that's exceptionally fast and responsive, eliminating slow page re-rendering for a seamless user experience.

---

## AI Assistance

All AI-assisted functionality is grouped under the `ai` directory in the root of this repository.

This directory includes:
- AI integration logic
- Supporting utilities and helpers
- Configuration and usage examples

Refer to it for a deeper understanding of how AI is incorporated into the project.

### Vibe Coding

When vibe-coding, point your AI assistant to the ai directory in the root repository, or provide its files directly for best results.

**Example prompts:**
```
Using the guidelines in the `ai` directory of https://github.com/duckframework/duck, create a project named `xyz`.
Using the guidelines in the `ai` directory of https://github.com/duckframework/duck, improve my project `xyz`.
Using the guidelines in the `ai` directory of https://github.com/duckframework/duck, improve my project UI — make it modern and beautiful.
```

---

## Getting Started

**Install latest version from Github using:**

```sh
pip install git+https://github.com/duckframework/duck.git
```

**Or install from `PyPi` using:**

```sh
pip install duckframework
```

---

## Project Creation

```sh
duck makeproject myproject
```

This creates a `normal` project named `myproject`. You can also create other project types using:

- `--full` for a full-featured project  
- `--mini` for a simplified starter project

### Full Project

The full version includes everything **Duck** offers. Recommended for experienced developers.

```sh
duck makeproject myproject --full
```

### Mini Project

Beginner-friendly. Lightweight version with essential functionality.

```sh
duck makeproject myproject --mini
```

---

## Simple Startup

```sh
duck makeproject myproject
cd myproject
duck runserver   # or: python3 web/main.py
```

This starts the server at **http://localhost:8000**   

**Duck** serves a basic site by default — explore more at [Documentation](https://docs.duckframework.com/main)

---

## Understanding the Project

Duck generates a set of files and directories as you build your application. This section walks through the core ones you'll interact with most.

---

### `web/main.py`

The entry point for your Duck application. You can run it directly with `python web/main.py`, or use the `duck runserver` command instead.

```py
#!/usr/bin/env python
"""
Main script for creating and running the Duck application.
"""

from duck.app import App

app = App(port=8000, addr="0.0.0.0", domain="localhost")

if __name__ == "__main__":
    app.run()
```

---

### `web/urls.py`

Defines the URL routes for your application. Each route maps a static or dynamic path to a **view** — a callable that handles incoming requests for that path.

By default, `urlpatterns` is an empty list. Add your own routes to wire up the app.

**HTTP route example:**

```py
from duck.urls import path
from duck.http.response import HttpResponse

def home(request):
    return HttpResponse("Hello world")

urlpatterns = [
    path('/', home, name="home"),
]
```

**WebSocket route example:**

```py
from duck.urls import path
from duck.contrib.websockets import WebSocketView

class SomeWebSocket(WebSocketView):
    async def on_receive(self, data: bytes, opcode):
        # Handle incoming WebSocket data
        await self.send_text("Some text")

        # Other available send methods:
        # send_json, send_binary, send_ping, send_pong, send_close

urlpatterns = [
    path('/some_endpoint', SomeWebSocket, name="some_ws_endpoint"),
]
```

---

### `web/views.py`

An optional file for organising your view functions. Import it as a module in `urls.py` to keep your routes clean.

```py
# web/urls.py
from duck.urls import path
from . import views

urlpatterns = [
    path('/', views.home, name="home"),
]
```

---

### `web/ui/`

Contains all frontend logic — components, pages, templates, and static files.

---

#### `web/ui/pages/`

Duck recommends building UI with **Pages** — Python classes that represent full HTML pages. Pages unlock the [Lively Component System](https://docs.duckframework.com/main/lively-components), which enables fast navigation and real-time interactivity without JavaScript or full page reloads.

**What is an HTML Component?**

A component is a Python class that represents an HTML element. You configure it with props and style, then render it to HTML.

```py
from duck.html.components import InnerComponent

class Button(InnerComponent):
    def get_element(self):
        return "button"

btn = Button(text="Hello world")

print(btn.render())  # <button>Hello world</button>
```

Duck ships with many built-in components — `Button`, `Navbar`, `Modal`, `Input`, and more — available under `duck.html.components`.

**Creating Pages**

Subclass `duck.html.components.page.Page` to create a page. The recommended pattern is a `BasePage` that defines the shared layout, with individual pages overriding only what they need.

```py
# web/ui/pages/base.py
from duck.html.components.container import FlexContainer
from duck.html.components.page import Page

class BasePage(Page):
    def on_create(self):
        super().on_create()
        self.set_title("MySite")
        self.set_description("Some base description ...")

        # Set up the root layout container
        self.main = FlexContainer(flex_direction="column")
        self.add_to_body(self.main)

        self.build_layout(self.main)

    def build_layout(self, main):
        # Override in subclasses to define page-specific layout
        pass
```

```py
# web/ui/pages/home.py
from duck.html.components.container import Container
from web.ui.pages.base import BasePage

class HomePage(BasePage):
    def build_layout(self, main):
        main.add_child(Container(text="Hello world"))
```

**Using Pages in views:**

```py
# web/views.py
from duck.shortcuts import to_response

def home(request):
    return to_response(HomePage(request))
```

> Pages automatically enable fast client-side navigation via Lively. Unlike templates, switching between pages does not trigger a full reload.

---

#### `web/ui/components/`

Where your custom reusable components live. The example below shows a feedback form with real-time UI updates powered by Lively.

```py
# web/ui/components/form.py
from duck.html.components.form import Form
from duck.html.components.input import Input, InputWithLabel
from duck.html.components.textarea import TextArea
from duck.html.components.button import Button
from duck.html.components.label import Label

class MyFeedbackForm(Form):
    def on_create(self):
        super().on_create()

        # Status label for displaying feedback or errors
        self.label = Label(text="")

        self.add_children([
            self.label,
            InputWithLabel(
                label_text="Your name",
                input=Input(name="name", type="text", placeholder="Enter your name", required=True),
            ),
            InputWithLabel(
                label_text="Your message",
                input=TextArea(name="message", placeholder="Your message", required=True),
            ),
            Button(text="Submit", props={"type": "submit"}),
        ])

        # Bind submit event — update_targets lists components to re-render on the client
        self.bind("submit", self.on_form_submit, update_self=True, update_targets=[self.label])

    async def on_form_submit(self, form, event, form_inputs, ws):
        name = form_inputs.get("name").strip()
        message = form_inputs.get("message").strip()

        # Validate and persist the message here

        # Patch the label in-place on the client
        self.label.text = "Your message has been received"
        self.label.color = "green"
```

---

#### `web/ui/templates/`

Prefer classic server-rendered templates? Store them here. Duck supports both **Django** and **Jinja2** template engines.

```django
{# web/ui/templates/home.html #}
{% extends 'base.html' %}

{% block main %}
  Hello world!
{% endblock main %}
```

```py
# web/views.py
from duck.shortcuts import render, async_render

def home(request):
    return render("home.html", engine="django")  # or engine="jinja2"

async def async_home(request):
    return await async_render("home.html", engine="django")
```

> You can also use HTML components inside templates. See [Lively Components](https://docs.duckframework.com/main/lively-components) for details.

#### `web/ui/static/`

This directory contains all the static files like css/js files, images or videos for your application.

> Instead of hard-coding static file URLs in components or templates, use the `static` function in `duck.shortcuts` module.

```py
# views.py
from duck.shortcuts import static

def home(request):
    # Instead of:
    my_image_url = "/static/images/my-image.png"
    
    # Do this instead:
    my_image_url = static("images/my-image.png")
    
    return "Hello world" # Anything here.
```

> The same applies with hard-coding internal URLs, use the `resolve()` function in `duck.shortcuts`.

---

## Django Integration

If you have an existing **Django** project and want production features like **HTTPS**, **HTTP/2**, and **resumable downloads**, Duck makes it easy.  

Unlike `nginx` setups, **Duck** simplifies this with a few commands.

### Benefits

- Native [HTTP/2 & HTTPS](https://docs.duckframework.com/main/https-and-http2) implementation. 
- Extra built-in security [middleware](https://docs.duckframework.com/main/middlewares) (DoS, SQLi, etc.)  
- Duck and Django run in the same Python environment (faster communication)  
- Auto-compressed responses  
- Resumable large downloads  
- Fast and [Reactive Lively components](https://docs.duckframework.com/main/lively-components) - for beautiful & responsive UI.
- [Free SSL with renewal](https://docs.duckframework.com/main/free-ssl-certificate)
- and more

### Usage

```sh
duck makeproject myproject
cd myproject
duck django-add "path/to/your/django_project"
duck runserver -dj
```

### Notes:

- Follow instructions provided by `django-add` command carefully  
- Make sure your Django project defines at least one `urlpattern`
- Once setup, you’re good to go!

---

## Useful Links

1. [Official Website](https://duckframework.com)    
2. [Documentation](https://docs.duckframework.com)
3. [Lively UI Documentation](https://docs.duckframework.com/main/lively-components)

---

## 🚀 Premium Duck Components Coming Soon!
>  
> All our UI components are currently free and open source. Stay tuned for upcoming Pro Packs featuring advanced dashboards, e-commerce, and integrations!
>
> ⭐ Star this repo to get notified on release!


## Contributing & Issues

**Duck** is open to all forms of contribution — financial or technical.

### Sponsorship/Donations:  

Support development on [Patreon](https://patreon.com/duckframework)  

### Report issues:  

Use the [GitHub Issues page](https://github.com/duckframework/duck/issues)

---

> **Duck is updated regularly** — check the repo for improvements and bug fixes.
