Metadata-Version: 2.4
Name: lombik
Version: 0.2.0
Summary: Flask scaffold engine
Author: David Plajner
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Flask
Requires-Dist: Flask-SQLAlchemy
Requires-Dist: Flask-Migrate
Requires-Dist: Flask-WTF
Requires-Dist: Flask-Session
Requires-Dist: Flask-Caching
Requires-Dist: Flask-Limiter
Requires-Dist: python-dotenv
Requires-Dist: click
Requires-Dist: SQLAlchemy
Requires-Dist: Werkzeug
Dynamic: license-file

# Lombik  
#### A scaffold engine for Flask

Lombik exists to remove the boring bits and to get you right into the developing zone. At it's core it was created to build tools faster. 

It leans heavily into a **hypermedia-first approach**, using Jinja2, template filters, HTMX, and Tailwind to keep logic close to the UI and reduce frontend complexity.

---

## What you get out of the box

- Structure
Each module created comes with a routes.py to define pages, queries.py to serve data from the database and actions.py to interact with the database.
`routes.py` would call the main page for example `templates/core/index.html`
`queries.py` reads data and in most cases displays it. Most commonly htmx get endpoints are stored here and are served from `templates/core/partials/active_users.html` inside index.
`actions.py` modifies data in the database. All post, put, patch and delete routes live here.
Creating a new module is easily done from the command line `module settings` which will create a new folder for settigns inside blueprints. 

- To be continued..

---

## Template filters (the fun part)

Lombik ships with a set of Jinja filters designed to keep your templates clean and expressive.

### Dates & time handling

Instead of formatting timestamps in Python, you do it directly in the template:

{{ created_at | localtime }}        → 2026-05-19 05:15  
{{ created_at | onlydate }}         → 2026-05-19  
{{ created_at | onlytime }}         → 05:15  
{{ created_at | shortdatetime }}    → May 19 05:15  
{{ created_at | timesince }}        → Just now // 2 minutes ago // 21 hours ago etc.

Everything defaults to `localtime`, meaning UTC from the backend is automatically shown in the user’s timezone.

Lombik expects the user’s timezone to be available via `g`. To change: `lombik/filters/_localize.`

---

### String helpers

Make frontend less painful

{{ g.user.full_name | proper }}

john_doe → John Doe

{{ g.user.first_name | possessive }}

john → john's  
lucas → lucas'  

You can chain them:

{{ g.user.full_name | proper | possessive }}

john_doe → John Doe's  

You can also normalize user input:

{{ user_input | normalize }}

Hello, world → hello_world
email@example.com → email_example_com


---

## Installation

pip install lombik

---

## Create a project

1. `lombik createapp myapp`
2. `cd myapp`
3. `flask run --debug`

This generates a full application structure so you can start immediately.

---

## Add modules

1. `lombik module new_module`

Creates a new module in blueprints that is registered automatically in app.py with the default file structure and a few core imports.
The following names are prohibited by default: "core", "auth".

---

## Database setup

Lombik uses MySQL by default.

1. Update your `.env` with your database credentials (at least dev for development)
2. Initialize the database:

`flask initdb`

3. Create your admin user:

`flask superuser`

After that, you can log in and start building further. Don't forget to `from lombik.wrappers import login_required` to add `@login_required` to all routes that you want to protect.

Note: the auth system is intentionally simple. It’s meant for development scaffolding, not necessarily production security.

---

## Models

When adding new models, be sure to register them:

`models/__init__.py`

Otherwise they won’t be picked up.

