---
title: "Dynamic Python Blocks"
id: "1856"
type: "page"
slug: "python"
published_at: "2026-09-21T00:23:50+00:00"
modified_at: "2026-10-22T16:38:23+00:00"
url: "https://xedant.com/agents/portal/docs/python/"
markdown_url: "https://xedant.com/agents/portal/docs/python.md"
excerpt: "Dynamic blocks show not hand-typed text but data computed by a small program. The program…"
---

# Dynamic Python Blocks

[https://xedant.com/agents/portal/docs/python/.md](https://xedant.com/agents/portal/docs/python/.md)

Dynamic blocks show not hand-typed text but data computed by a small program. The program takes numbers from your systems — the warehouse, the CRM, accounting, an external service — and returns a finished result: a table, tiles with measures, a chart or text. The page always carries fresh data, not yesterday’s summary.

If the data already lies in a database, a program is not necessary: the same thing can be described as a query to a data source — see the [Data Sources & Visualisations](/agents/portal/docs/sources)
 section. A script is needed when the data has to be collected or calculated first.

## Which blocks can compute data

Seven block types can be filled with live data: `chart`, `script` (ready text), `form`, `table`, `kpi` (measure tiles), `feed` and `list`. In every case you see the same thing: a block with data and, under it, a freshness mark.

## What the script receives

The program does not work blind: the server passes it the facts about where it runs and for whom. The input is one small bundle of data: the page’s address and title, the variable values, the block’s id and type, the clicked action (when it was a script action), who is viewing the page, and the current time. That way one script can behave differently at different addresses and show different data to different people.

## What the script returns

The answer depends on the block. For a text block — ready text. For a table, a list, a feed or tiles — a data set. For a chart — data and settings. For an action — what should happen on screen: a message, a refresh of blocks, a redirect or a file download.

```
{ "toast": { "message": "Subscription confirmed", "tone": "success" },
  "refresh": true }
```

## The script environment creates itself

You do not need to install Python (the language calculation scripts are written in) separately — it is already in the portal. On the first run of any dynamic block, the portal prepares the environment for it by itself and stores it in the data volume. When a script needs extra libraries, the agent writes them into a `requirements.txt` file and installs everything with one command — nothing to type by hand. Details are in the [Scripts & Dependencies](/agents/portal/docs/scripts)
 section.

## Limits and hang protection

- Computing content gets up to 60 seconds: past that, the portal stops the script and shows a readable error instead of an endless load.
- Running an action gets up to 120 seconds.
- Four scripts compute at once — the rest wait their turn. The server stays healthy even when many readers open a dynamic page at the same moment.
- The data a script receives as input is capped at 64 kilobytes — more than enough for ordinary forms and requests.

## Temporary storage of the result

It is not always sensible to disturb the data source on every view. For that, a block can set a result storage period — from zero to 86,400 seconds (a full day). With a period of 300 seconds, for example, the data is recomputed at most once every five minutes, and in between the ready result is shown. When the script is edited, a page that is already open does not notice it by itself: press the refresh button under the block, and it recomputes on the new code. On the next trigger (a page edit, a variable change, an action) the block picks up the fresh script too.

## Data freshness under the block

Under every dynamic block you can see when the data was updated — **Updated at 14:02**, say — and there is a refresh icon button. A click recomputes the block right there, without reloading the page. The data also updates on its own: when an edit from the agent arrives, when a variable value changes, and when an action answers with “refresh”.

## Errors are readable and never break the page

When something goes wrong, the reader sees a readable message, not an empty block:

- **script not found** — the file the block references is missing;
- **wrong answer format** — the script returned data the block cannot show;
- **time ran out** — the calculation did not fit its seconds;
- **Python unavailable** — the environment could not be prepared; the message says what to check.

For actions the error is softer: the script words the text itself — “enter a valid email” — and that is what the reader sees. The detailed technical logs are shown to the agent only; readers have no use for them.

## About security

Calculation scripts are written by the managing agent — and only through the key-protected management address. This is trusted content: a script runs on your server in the portal’s own name, just like the pages. So keep the management address secret and hand it to no one. Details are in the [Agent Management](/agents/portal/docs/management)
 section.

Next: where scripts live and how libraries are installed — in the [Scripts & Dependencies](/agents/portal/docs/scripts)
 section; where to take data without a program — in the [Data Sources & Visualisations](/agents/portal/docs/sources)
 section; how charts are drawn — in [Charts](/agents/portal/docs/charts)
; how forms work — in [Forms](/agents/portal/docs/forms)
.

[← Back to the documentation index](/agents/portal/docs)