Simple and efficient Template Engine for Python projects

These details have been verified by PyPI

Project links

Homepage

GitHub Statistics

Maintainers

marcosstefani

These details have not been verified by PyPI

Project description

Sucuri

Simple and efficient template engine for Python projects, inspired by PugJS.

Sucuri is designed to bring an elegant, indentation-based syntax to Python. By stripping away repetitive HTML tags and taking advantage of natural code structure, Sucuri gives developers a pristine, highly readable HTML rendering experience.

Powered natively by the Lark parser, Sucuri supports deep variable nesting, loops, conditionals, seamless macro injections, and is completely framework-independent. It plays just as well with modern frameworks like FastAPI, Django, and Flask as it does in native Python scripts.

📦 Installation

Install and update using pip:

pip install sucuri

🚀 Quick Start & Integration

Sucuri returns raw HTML strings that can be seamlessly injected into any existing web framework format. All you need is the template function from sucuri.rendering.

Vanilla Python

from sucuri.rendering import template

context = {"name": "World"}
html_output = template("my_template.suc", context)
print(html_output)

⚡ FastAPI Integration

Returns a raw HTMLResponse instantly!

from fastapi import FastAPI
from fastapi.responses import HTMLResponse
from sucuri.rendering import template

app = FastAPI()

@app.get("/")
def index():
    context = {"name": "FastAPI User"}
    html = template('templates/index.suc', context)
    return HTMLResponse(content=html, status_code=200)

🌶️ Flask Integration

Use Flask's render_template_string to wrap Sucuri's output.

from flask import Flask, render_template_string
from sucuri.rendering import template

app = Flask(__name__)

@app.route("/")
def index():
    context = {"name": "Flask User"}
    html = template('templates/index.suc', context)
    return render_template_string(html)

🎸 Django Integration

Return the compiled string through HttpResponse.

from django.http import HttpResponse
from sucuri.rendering import template

def index(request):
    context = {"name": "Django User"}
    html = template('templates/index.suc', context)
    return HttpResponse(html)

💻 Command Line Interface (CLI)

Sucuri provides a CLI to directly process .suc templates from your terminal—perfect for shell scripts and static site generation!

# Basic compilation (outputs to stdout)
sucuri build index.suc

# Compilation with output file
sucuri build index.suc -o index.html

# Compilation passing JSON context variables directly inline
sucuri build index.suc --context '{"title": "My Page"}' -o index.html

# Compilation using JSON data loaded from another file
sucuri build index.suc --context context.json -o index.html

📖 Syntax & Features

Basics & Indentation

A standard HTML file doesn't need brackets < >. Instead, Sucuri relies on tabs or spaces (kept strictly uniform) to determine tag hierarchies.

html
    body
        h1 Title
        a(href='#') This is my link

Output:

<html>
    <body>
        <h1>Title</h1>
        <a href="#">This is my link</a>
    </body>
</html>

Text

Texts can be described in two ways. Inline together with the tag declaration, or spanning multiple lines starting with the | pipe character.

h3 Hello!
    | Text
    | with
    | more than
    | one line

Output:

<h3>Hello!
    Text
    with
    more than
    one line
</h3>

Attributes

HTML attributes in Sucuri must be separated by space and enclosed strictly within parentheses (). Unlike standard Pug, they are on a single line and separated by spaces (not commas).

a(href='google.com') Google
a(class='button' href='google.com') Google
div(class='div-class')
input(type="checkbox" checked)

Output:

<a href="google.com">Google</a>
<a class="button" href="google.com">Google</a>
<div class="div-class"></div>
<input type="checkbox" checked>

CSS Shortcuts

Sucuri supports PugJS-style CSS shorthand for class and id attributes. Use .class-name and #id-name directly on any tag — or even without a tag name to implicitly create a <div>.

div.container
    p.card-text Text

#app.wrapper
    h1 Hello

section#main.content.active
    span Done

Output:

<div class="container">
    <p class="card-text">Text</p>
</div>
<div id="app" class="wrapper">
    <h1>Hello</h1>
</div>
<section id="main" class="content active">
    <span>Done</span>
</section>

Dynamic Variables (Context)

Variables passed by Python's context can be effortlessly embedded directly into your text with {}. Sucuri also resolves deeply nested context.

Python Context: {"user": {"name": "Alice", "id": 123}}

Sucuri:

div(class="profile")
    h1 Hello {user.name}!
    span User ID is {user.id}

Filters

Apply built-in transformations to any variable using the pipe | operator. Filters can be chained.

Filter	Description
`upper`	Converts text to UPPERCASE
`lower`	Converts text to lowercase
`title`	Capitalizes The First Letter Of Each Word
`safe`	Renders raw HTML without escaping (bypass XSS protection — use carefully!)

h1 {title | upper}
p {subtitle | lower}
span {author | title}
div {raw_html | safe}

Filters also work inside <for> loops via the # syntax:

<for item in products>
    li #item.name | title
<endfor>

Filters can be chained in sequence:

span {label | lower | title}

Control Flow

You can handle logic natively in .suc files.

If Conditions

Wrap standard comparisons using <if condition> and <endif>.

<if user.status != "banned">
  h1 User is active!
<endif>

For Loops

Iterate elegantly using <for item in list>. Access your iterated items dynamically using the hash # symbol (which also supports nested resolution like #item.id!).

Python Context: {"invoices": [{"id": 1}, {"id": 2}]}

ul
    <for inv in invoices>
        li Invoice Number: #inv.id
    <endfor>

📦 Preloaded Templates (Built-in Magic)

Instead of manually crafting standard HTML configurations like ul/li and table setups, Sucuri comes packed with pre-compiled macros for lists and tables to drastically speed up repetitive boilerplate code!

1. Lists & Checkboxes

Pass ANY variable containing an Array, and use the list() built-in to render an entire list matrix automatically.

Python Context: {"my_array": ["Apple", "Orange"], "opts": ["Apple"]}

Unordered List:

list(my_array class="ul-squares")

Result:

<ul class="ul-squares">
    <li> Apple </li>
    <li> Orange </li>
</ul>

Checkboxes: (Just provide the secondary array containing the checked values!)

list(my_array opts class="survey")

Result:

<input type="checkbox" id="ck-Apple" checked="checked">Apple
<input type="checkbox" id="ck-Orange">Orange

2. Tables

Need a comprehensive HTML table constructed in one go? The table() syntax takes header arrays, rows matrices, and footer arrays automatically!

Python Context:

context = {
    "heads": ["Name", "Age"],
    "rows": [["Alice", 21], ["Bob", 45]],
    "footers": ["End", "End"]
}

Sucuri:

table(heads rows footers class="table" id="tb-authors")

Result:

<table class="table" id="tb-authors">
    <thead>
        <tr>
            <th>Name</th>
            <th>Age</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Alice</td>
            <td>21</td>
        </tr>
        <tr>
            <td>Bob</td>
            <td>45</td>
        </tr>
    </tbody>
    <tfoot>
        <tr>
            <td>End</td>
            <td>End</td>
        </tr>
    </tfoot>
</table>

(Positional order: Headers array, Data Matrix array, Footer array.)

🧩 Modularity: Includes, Styles & Scripts

Sucuri acts efficiently as an asset distributor through macro tagging and external inclusions. The engine caches everything natively during execution.

Including Other `.suc` files

Declare your macro inclusions at the top using include, and instantiate them using the + sign.

modules/button.suc:

button(class='btn-primary') {text}

index.suc:

include modules/button

html
    body
        h1 Welcome
        +button

Passing Parameters to Macros

You can pass inline parameters to any macro directly at the call site using the () syntax. Parameters override context variables only for that macro invocation.

inc/card.suc:

div.card
    h2 {title}
    p {type}

index.suc:

include inc/card

+card(title="Warning" type="danger")
+card(title="Success" type="info")

Output:

<div class="card">
    <h2>Warning</h2>
    <p>danger</p>
</div>
<div class="card">
    <h2>Success</h2>
    <p>info</p>
</div>

Template Inheritance (`extends` / `block`)

Sucuri supports full template inheritance. A parent layout defines named block regions, and child templates extend it with extends, overriding only the blocks they need.

layout.suc:

html
    head
        title {title}
    body
        div(id="content")
            block content
        div(id="footer")
            block footer

page.suc:

extends layout

block content
    h1 Welcome to the Home Page
    p Here comes the content.

block footer
    p Page Footer

Python:

html = template("page.suc", {"title": "My Site"})

Output:

<html>
    <head>
        <title>My Site</title>
    </head>
    <body>
        <div id="content">
            <h1>Welcome to the Home Page</h1>
            <p>Here comes the content.</p>
        </div>
        <div id="footer">
            <p>Page Footer</p>
        </div>
    </body>
</html>

Blocks not overridden by the child template render their default content from the parent.

Injecting CSS Styles and JS Scripts

Need global JS or CSS appended without manually crafting raw headers/footers everywhere? Merely use style and script top-level declarations, supplying their raw path! They will be automatically wrapped in <style> and <script> HTML tags and beautifully appended to the file.

style static/css/global.css
script static/js/app.js

html
    body
        h1 Wow!

🔒 Security

XSS Protection

By default, all variables are automatically HTML-escaped before rendering. This prevents cross-site scripting (XSS) attacks from untrusted context values.

Python Context: {"msg": "<script>alert(1)</script>"}

h1 {msg}

Output:

<h1>&lt;script&gt;alert(1)&lt;/script&gt;</h1>

To render trusted raw HTML intentionally, use the safe filter:

div {html_content | safe}

Warning: Only use safe on content you fully control. Never apply it to user-supplied input.

⚙️ Advanced: Environment & Custom Filters

For greater control — custom filters, isolated environments, or multi-app setups — use the Environment class directly instead of the top-level template() function.

Registering Custom Filters

from sucuri import Environment

env = Environment()

@env.register_filter('exclaim')
def exclaim(val):
    return f"{val}!!!"

env.register_filter('reverse', lambda x: str(x)[::-1])

html = env.template("templates/index.suc", {"title": "Hello"})

Custom filters are used in templates exactly like built-in ones:

h1 {title | exclaim}
span {title | exclaim | reverse}

Custom filters also work inside loops:

<for item in items>
    li #item | exclaim
<endfor>

Multiple Environments

Each Environment instance has its own filter registry and base directory, making it safe to run isolated configurations side by side (e.g., multiple apps in the same process).

env_a = Environment(base_dir="templates/app_a")
env_b = Environment(base_dir="templates/app_b")

env_a.register_filter('shout', lambda v: v.upper() + "!")
# env_b has no 'shout' filter — fully isolated

🌐 Built-in Live Server

Sucuri ships with a zero-dependency reactive HTTP server. It watches your app's state and pushes HTML updates to every connected browser in real time — no page reload needed.

Starting the server

# Basic usage
sucuri serve app.py

# Custom host / port
sucuri serve app.py --host 0.0.0.0 --port 3000

# Disable CSRF token protection (see Security below)
sucuri serve app.py --public

SucuriApp

from sucuri.server import SucuriApp

app = SucuriApp(template_dir="templates")   # template_dir defaults to "."

Reactive State & Live Reload

app.state() creates a reactive dictionary. When any top-level key changes, all browsers connected via SSE receive the updated HTML fragment instantly — without a full page reload.

state = app.state({
    "products": [
        {"name": "Widget A", "price": "9.99"},
    ],
    "cart": {"count": 0, "total": "0.00"},
})

In your template, wrap reactive sections in watch blocks using the state key as the identifier:

html
  body
    watch products
      <for p in products>
      div.card
        span.name {p.name}
        span.price $ {p.price}
      <endfor>

    watch cart
      p Items: {cart.count} — Total: $ {cart.total}

Each watch block renders as a <div data-suc-watch="key"> wrapper. When the server detects a change to that key, only that wrapper is replaced in the DOM.

Triggering a re-render from a route handler:

# Direct assignment to a top-level key triggers automatically
state.data["products"].append({"name": "New", "price": "1.00"})
state.notify("products")   # manual notify for nested mutations

Routes

GET

@app.get("/")
def index():
    return app.render("shop.suc", state.data)   # template → HTML string

@app.get("/ping")
def ping():
    return {"status": "ok"}   # dict → JSON response

POST / PUT / DELETE

Mutation handlers receive a request object as their first positional argument:

@app.post("/api/price")
def update_price(request):
    new_price = request.json.get("price")
    state.data["products"][0]["price"] = new_price
    state.notify("products")
    return {"ok": True}

@app.put("/api/item")
def replace_item(request):
    ...

@app.delete("/api/item")
def remove_item(request):
    ...

Dynamic routes

Use <param> placeholders in the path. GET handlers receive params as keyword arguments; mutation handlers receive them after request:

@app.get("/api/product/<index>")
def get_product(index):
    return state.data["products"][int(index)]

@app.post("/api/product/<index>/price")
def update_price_by_index(request, index):
    state.data["products"][int(index)]["price"] = request.json["price"]
    state.notify("products")
    return {"ok": True}

@app.delete("/api/product/<index>")
def delete_product(request, index):
    state.data["products"].pop(int(index))
    state.notify("products")
    return {"ok": True}

Response Helpers

By default, routes return str (HTML 200) or dict (JSON 200). For any other status code, redirect, or raw bytes, import the helpers from sucuri.server:

from sucuri.server import SucuriApp, Response, redirect

`Response(body, status=200, content_type=None)`

Wraps any return value with a custom HTTP status code or content type.

@app.post("/api/login")
def login(request):
    if not valid_credentials(request.json):
        return Response({"error": "unauthorized"}, status=401)
    return {"ok": True}

@app.get("/api/item/<id>")
def get_item(id):
    item = find(id)
    if item is None:
        return Response("<h1>Not found</h1>", status=404)
    return item

@app.get("/report")
def report():
    pdf_bytes = generate_pdf()
    return Response(pdf_bytes, status=200, content_type="application/pdf")

Argument	Type	Default	Description
`body`	`str`, `dict`, or `bytes`	—	Response body
`status`	`int`	`200`	HTTP status code
`content_type`	`str \| None`	`None`	Forces a specific Content-Type; auto-detected when `None`

`redirect(url, status=302)`

Returns an HTTP redirect. Works from any GET or mutation handler.

@app.get("/old-path")
def old_path():
    return redirect("/new-path")          # 302 Found

@app.get("/permanent")
def permanent():
    return redirect("/new-path", status=301)  # 301 Moved Permanently

@app.post("/api/login")
def login(request):
    # authenticate…
    return redirect("/dashboard")

Request Object

Attribute	Type	Description
`request.body`	`bytes`	Raw request body
`request.json`	`dict`	Parsed JSON body (`{}` on failure)
`request.form`	`dict`	Parsed form data (see below)

`request.form`

Populated for application/x-www-form-urlencoded and multipart/form-data requests.

Scenario	Value type
Single-value field	`str`
Repeated field name	`list[str]`
File upload field (`filename=`)	`bytes`

@app.post("/api/register")
def register(request):
    name  = request.form["name"]        # str
    tags  = request.form.get("tags")    # list[str] if sent multiple times
    photo = request.form.get("photo")   # bytes if it's a file field
    ...

To submit a form from JavaScript using the correct Content-Type:

fetch("/api/register", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
    "X-Sucuri-Token": window.__sucuri_token || ""
  },
  body: new URLSearchParams(new FormData(formElement)).toString()
});

Custom Error Handlers

Register handlers for any HTTP error code with @app.error(code). The handler for 500 receives the exception as its first argument; all other codes are called with no arguments.

@app.error(404)
def not_found():
    return """
    <html><body>
      <h1>404 — Not found</h1>
      <a href="/">Go back</a>
    </body></html>
    """

@app.error(500)
def server_error(exc):
    return {"error": str(exc), "type": type(exc).__name__}

Handlers follow the same return convention as routes: a str is sent as text/html, a dict as application/json, both with the appropriate error status code.

Static Files

Any file placed inside template_dir/static/ is served automatically at /static/<path>.

templates/
  static/
    css/
      style.css    →  GET /static/css/style.css
    js/
      app.js       →  GET /static/js/app.js
    logo.png       →  GET /static/logo.png

Path traversal outside static/ is blocked with a 403.

CSRF Token Protection

By default, every non-GET request must include an X-Sucuri-Token header with the current token. The token rotates after each successful authenticated request and is broadcast to all connected SSE clients immediately.

// The current token is always available in the browser as:
window.__sucuri_token

// Usage in fetch calls:
fetch("/api/update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Sucuri-Token": window.__sucuri_token || ""
  },
  body: JSON.stringify({ price: "19.99" })
});

To disable protection (e.g. for fully public APIs or during development):

sucuri serve app.py --public
# or
SUCURI_PUBLIC=1 sucuri serve app.py

Warning: Never use --public in production if your endpoints mutate state.

Default Favicon

When your app does not provide a favicon, the server automatically serves the Sucuri logo at /favicon.ico. To override it, place your own file in template_dir/static/ with any of these names (checked in order):

static/favicon.ico
static/favicon.svg
static/favicon.png

Project details

These details have been verified by PyPI

Project links

Homepage

GitHub Statistics

Maintainers

marcosstefani

These details have not been verified by PyPI

Release history Release notifications | RSS feed

1.0.26

Jun 1, 2026

1.0.25

May 31, 2026

1.0.24

May 28, 2026

1.0.23

May 26, 2026

1.0.22

May 26, 2026

1.0.21

May 25, 2026

1.0.20

May 25, 2026

1.0.19

May 25, 2026

1.0.18

May 25, 2026

1.0.17

May 25, 2026

1.0.16

May 25, 2026

1.0.15

May 24, 2026

1.0.14

May 24, 2026

1.0.13

May 24, 2026

1.0.12

May 24, 2026

This version

1.0.11

May 24, 2026

1.0.10

May 21, 2026

1.0.9

May 19, 2026

1.0.8

May 19, 2026

1.0.7

May 19, 2026

1.0.6

May 18, 2026

1.0.5

May 18, 2026

1.0.4

May 18, 2026

1.0.3

May 18, 2026

1.0.2

May 18, 2026

1.0.1

May 16, 2026

0.2.6

Feb 4, 2019

0.2.5

Nov 3, 2018

0.2.4

Jul 22, 2018

0.2.2

Apr 25, 2018

0.2.1

Apr 3, 2018

0.2.0

Mar 24, 2018

0.1.9

Mar 23, 2018

0.1.8

Mar 22, 2018

0.1.7

Mar 21, 2018

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sucuri-1.0.11.tar.gz (41.0 kB view details)

Uploaded May 24, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sucuri-1.0.11-py2.py3-none-any.whl (30.3 kB view details)

Uploaded May 24, 2026 Python 2Python 3

File details

Details for the file sucuri-1.0.11.tar.gz.

File metadata

Download URL: sucuri-1.0.11.tar.gz
Upload date: May 24, 2026
Size: 41.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for sucuri-1.0.11.tar.gz
Algorithm	Hash digest
SHA256	`7937997335f04f99268a8ede57ebde3cf821ceba3eb471591e1a5083c70ebc33`
MD5	`44f51f94f8690e56e4781e30f9a36b65`
BLAKE2b-256	`c22c32e081b02d8e3ccaf6d0261fd81026c5f2924601aa4692576db4c1b790e9`

See more details on using hashes here.

Provenance

The following attestation bundles were made for sucuri-1.0.11.tar.gz:

Publisher: publish-pypi.yml on marcosstefani/sucuri

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: sucuri-1.0.11.tar.gz
- Subject digest: 7937997335f04f99268a8ede57ebde3cf821ceba3eb471591e1a5083c70ebc33
- Sigstore transparency entry: 1616157900
- Sigstore integration time: May 24, 2026
Source repository:
- Permalink: marcosstefani/sucuri@c684e377ce5eb4eb8dc1f33a98f0294c85dd490a
- Branch / Tag: refs/tags/v1.0.11
- Owner: https://github.com/marcosstefani
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-pypi.yml@c684e377ce5eb4eb8dc1f33a98f0294c85dd490a
- Trigger Event: push

File details

Details for the file sucuri-1.0.11-py2.py3-none-any.whl.

File metadata

Download URL: sucuri-1.0.11-py2.py3-none-any.whl
Upload date: May 24, 2026
Size: 30.3 kB
Tags: Python 2, Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for sucuri-1.0.11-py2.py3-none-any.whl
Algorithm	Hash digest
SHA256	`1ae5bbca66e71edd6c541914bc87546fc798507f8aa61af4ae416e696c3cd367`
MD5	`e260e08e3d90954420d72cab853fd97e`
BLAKE2b-256	`c7962e1ebf2e6205cd29dc5ccf402cded4d8f3c71150eddfbaa3bbec9f4d3c81`

See more details on using hashes here.

Provenance

The following attestation bundles were made for sucuri-1.0.11-py2.py3-none-any.whl:

Publisher: publish-pypi.yml on marcosstefani/sucuri

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: sucuri-1.0.11-py2.py3-none-any.whl
- Subject digest: 1ae5bbca66e71edd6c541914bc87546fc798507f8aa61af4ae416e696c3cd367
- Sigstore transparency entry: 1616157926
- Sigstore integration time: May 24, 2026
Source repository:
- Permalink: marcosstefani/sucuri@c684e377ce5eb4eb8dc1f33a98f0294c85dd490a
- Branch / Tag: refs/tags/v1.0.11
- Owner: https://github.com/marcosstefani
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-pypi.yml@c684e377ce5eb4eb8dc1f33a98f0294c85dd490a
- Trigger Event: push

sucuri 1.0.11

Navigation

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Project description

Sucuri

📦 Installation

🚀 Quick Start & Integration

Vanilla Python

⚡ FastAPI Integration

🌶️ Flask Integration

🎸 Django Integration

💻 Command Line Interface (CLI)

📖 Syntax & Features

Basics & Indentation

Text

Attributes

CSS Shortcuts

Dynamic Variables (Context)

Filters

Control Flow

If Conditions

For Loops

📦 Preloaded Templates (Built-in Magic)

1. Lists & Checkboxes

2. Tables

🧩 Modularity: Includes, Styles & Scripts

Including Other .suc files

Passing Parameters to Macros

Template Inheritance (extends / block)

Injecting CSS Styles and JS Scripts

🔒 Security

XSS Protection

⚙️ Advanced: Environment & Custom Filters

Registering Custom Filters

Multiple Environments

🌐 Built-in Live Server

Starting the server

SucuriApp

Reactive State & Live Reload

Routes

GET

POST / PUT / DELETE

Dynamic routes

Response Helpers

Response(body, status=200, content_type=None)

redirect(url, status=302)

Request Object

request.form

Custom Error Handlers

Static Files

CSRF Token Protection

Default Favicon

Project details

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Including Other `.suc` files

Template Inheritance (`extends` / `block`)

`Response(body, status=200, content_type=None)`

`redirect(url, status=302)`

`request.form`