68 lines
1.7 KiB
Markdown
68 lines
1.7 KiB
Markdown
---
|
|
layout: default
|
|
parent: For developers
|
|
title: Agent Guide - Python Extensions
|
|
nav_order: 4
|
|
---
|
|
|
|
# Agent Guide - Python Extensions
|
|
|
|
This guide is for AI agents or developers using AI to build **traditional (Python) LNbits extensions**. It defines what to change, what not to change, and the expected structure.
|
|
|
|
## Hard Rules (Non-Negotiable)
|
|
|
|
- Do **not** change core LNbits files.
|
|
- Only edit files inside your extension folder.
|
|
- Do **not** add new Python dependencies unless explicitly approved.
|
|
|
|
## Extension Folder Layout (Python)
|
|
|
|
Your extension lives under:
|
|
|
|
```
|
|
lnbits/extensions/<ext_id>/
|
|
```
|
|
|
|
Typical files to edit:
|
|
|
|
- `views.py` (HTML routes)
|
|
- `views_api.py` (API routes)
|
|
- `crud.py` / `models.py` (storage logic + models)
|
|
- `migrations.py` (DB schema)
|
|
- `templates/<ext_id>/` (HTML)
|
|
- `static/` (JS/CSS/images)
|
|
- `config.json`, `manifest.json`, `README.md`
|
|
|
|
## What You Can Do
|
|
|
|
Python extensions can:
|
|
|
|
- Define their own database schema via `migrations.py`
|
|
- Run long-running background tasks via `*_start()` and `*_stop()` hooks
|
|
- Access LNbits internal services directly in Python
|
|
- Expose custom API routes under `/<ext_id>/api/v1/...`
|
|
|
|
## What You Must Not Do
|
|
|
|
- Do not modify core services or routes.
|
|
- Do not patch LNbits internals for your extension.
|
|
- Avoid direct DB access outside your own schema.
|
|
|
|
## Background Tasks
|
|
|
|
Implement background tasks by exposing:
|
|
|
|
```
|
|
def <ext_id>_start():
|
|
def <ext_id>_stop():
|
|
```
|
|
|
|
Use `register_invoice_listener` or `wait_for_paid_invoices` if you need to react to payments.
|
|
|
|
## Testing Checklist
|
|
|
|
- Extension loads without errors.
|
|
- Migrations apply cleanly.
|
|
- Routes are registered under `/<ext_id>/...`.
|
|
- Background tasks start/stop cleanly.
|