> ## Documentation Index
> Fetch the complete documentation index at: https://help.bots.lt/llms.txt
> Use this file to discover all available pages before exploring further.

# BLP Syntax & Variables

> Understanding the Restricted Python environment and built-in global variables.

Bots.LT uses a custom execution environment called **BLP** (Bots.LT Python). BLP is built on top of standard Python 3, but with specific security restrictions to ensure safe and blazing-fast execution on our cloud platform.

## What is Restricted Python?

When you write commands in Bots.LT, you are writing Python code. However, you cannot use operations that could compromise the server:

* `import` statements are blocked.
* `open()`, `eval()`, and `exec()` are blocked.
* `time.sleep()` is blocked.
* Infinite loops (`while True`) are blocked to prevent execution timeouts.

Instead of importing modules, Bots.LT injects safe **Built-in Objects and Variables** directly into your code.

***

## Global Variables

Whenever a command runs, the following variables are automatically available in your code. You **do NOT** need to define or import them.

### Context Variables

| Variable        | Type    | Description                                                                                               |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `u` / `chat_id` | Integer | The Telegram ID of the user or group that triggered the command. Both are identical and interchangeable.  |
| `message`       | DotDict | The raw Telegram Message object. Supports dot notation (e.g., `message.text`, `message.from.first_name`). |
| `call`          | DotDict | The Telegram CallbackQuery object (if triggered by an inline button). Otherwise `None`.                   |
| `user`          | DotDict | The Telegram User object of the sender. Supports dot notation (e.g., `user.id`, `user.username`).         |
| `command`       | String  | The exact command string that was triggered (e.g., `"/start"`).                                           |
| `params`        | String  | Any text that comes *after* the command. For example, if user sends `/start 123`, `params` is `"123"`.    |
| `msg`           | String  | The text of the message or the callback data (if inline button clicked).                                  |

### Bot Details

| Variable       | Type   | Description                                                |
| -------------- | ------ | ---------------------------------------------------------- |
| `bot_id`       | String | The unique identifier of your bot on the Bots.LT platform. |
| `bot_token`    | String | Your bot's private BotFather token.                        |
| `bot_username` | String | The Telegram username of your bot (without the `@`).       |
| `bot_name`     | String | The display name of your bot.                              |

```python BLP Example theme={null}
# Using injected variables
Bot.sendMessage(chat_id=u, text=f"Hello, {user.first_name}! You sent {command} with params {params}.")

# Handling callbacks
if call:
    Bot.answerCallbackQuery(callback_query_id=call.id, text="Loading...")
```

***

## The `Bot` Object

In BLP, the Telegram engine is injected as the `Bot` object. This object handles all API calls like `Bot.sendMessage`.

> **Note:** For convenience and flexibility, **`Bot` and `bot` are 100% interchangeable aliases**. Every method that works on `Bot` also works identically on `bot`.

```python BLP Example theme={null}
Bot.sendMessage(chat_id=u, text="Hello!")
# is exactly the same as:
bot.sendMessage(chat_id=u, text="Hello!")
```

***

## Built-in Modules

We provide safe wrappers for common Python functionalities directly in the global scope.

| Module/Function           | Description                                                       |
| ------------------------- | ----------------------------------------------------------------- |
| `time`                    | A safe wrapper. `time.time()` returns the current UNIX timestamp. |
| `re` / `regex`            | The standard Python regular expressions module.                   |
| `hashlib`                 | For generating hashes (MD5, SHA256, etc.).                        |
| `base64`                  | For base64 encoding and decoding.                                 |
| `jsondumps(obj)`          | Safely converts a Python dictionary/list to a JSON string.        |
| `bf_json(string)`         | Safely parses a JSON string into a Python dictionary.             |
| `encodeURIComponent(str)` | URL-encodes a string.                                             |
| `decodeURIComponent(str)` | URL-decodes a string.                                             |
| `isNumeric(val)`          | Returns `True` if the value can be converted to a float/int.      |

```python BLP Example theme={null}
# Using built-ins
current_ts = time.time()
encoded = base64.b64encode(b"Hello").decode('utf-8')
json_str = jsondumps({"status": "ok"})
```

***

## Data Storage Scopes

You do not need an external database. Bots.LT provides a blazing-fast built-in Key-Value (KV) store accessible via three scopes:

| Scope  | Description                                      | Usage                                      |
| ------ | ------------------------------------------------ | ------------------------------------------ |
| `User` | Data is saved for the specific user (`chat_id`). | `User.saveData("balance", 100)`            |
| `Bot`  | Data is saved globally for the entire bot.       | `Bot.saveData("total_users", 5000)`        |
| `Api`  | Data shared across multiple bots owned by you.   | `Api.saveData("dev_api_key", "secret123")` |

*See the **Data Storage & Wait States** section for more details on these scopes.*