| Name | astreum JSON |
| Version |
0.2.30
JSON |
| download |
| home_page | None |
| Summary | Python library to interact with the Astreum blockchain and its Lispeum virtual machine. |
| upload_time | 2025-07-24 19:16:56 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# lib
Python library to interact with the Astreum blockchain and its Lispeum virtual machine.
[View on PyPI](https://pypi.org/project/astreum/)
## Configuration
When initializing an `astreum.Node`, pass a dictionary with any of the options below. Only the parameters you want to override need to be present – everything else falls back to its default.
### Core Configuration
| Parameter | Type | Default | Description |
| --------------------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `machine-only` | bool | `True` | When **True** the node starts in *machine‑only* mode: no storage subsystem and no relay networking – only the Lispeum VM. Set to **False** to enable storage and relay features. |
| `relay_secret_key` | hex string | Auto‑generated | Ed25519 private key that identifies the node on the network. If omitted, a fresh keypair is generated and kept in‑memory. |
| `validation_secret_key` | hex string | `None` | X25519 private key that lets the node participate in the validation route. Leave unset for a non‑validator node. |
| `storage_path` | string | `None` | Directory where objects are persisted. If *None*, the node uses an in‑memory store. |
| `storage_get_relay_timeout` | float | `5` | Seconds to wait for an object requested from peers before timing‑out. |
### Networking
| Parameter | Type | Default | Description |
| --------------- | ----------------------- | ------- | ----------------------------------------------------------------------------------- |
| `use_ipv6` | bool | `False` | Listen on IPv6 as well as IPv4. |
| `incoming_port` | int | `7373` | UDP port the relay binds to. |
| `bootstrap` | list\[tuple\[str, int]] | `[]` | Initial peers used to join the network, e.g. `[ ("bootstrap.astreum.org", 7373) ]`. |
> **Note**
> The peer‑to‑peer *route* used for object discovery is always enabled.
> If `validation_secret_key` is provided the node automatically joins the validation route too.
### Example
```python
from astreum.node import Node
config = {
"machine-only": False, # run full node
"relay_secret_key": "ab…cd", # optional – hex encoded
"validation_secret_key": "12…34", # optional – validator
"storage_path": "./data/node1",
"storage_get_relay_timeout": 5,
"incoming_port": 7373,
"use_ipv6": False,
"bootstrap": [
("bootstrap.astreum.org", 7373),
("127.0.0.1", 7374)
]
}
node = Node(config)
# … your code …
```
## Lispeum Machine Quickstart
The Lispeum virtual machine (VM) is embedded inside `astreum.Node`. You feed it Lispeum source text, and the node tokenizes, parses, and **evaluates** the resulting AST inside an isolated environment.
```python
from astreum.node import Node
from astreum.machine.tokenizer import tokenize
from astreum.machine.parser import parse
# 1. Spin‑up a stand‑alone VM (machine‑only node).
node = Node({"machine-only": True})
# 2. Create an environment.
env_id = node.machine_create_environment()
# 3. Convert Lispeum source → Expr AST.
source = '(+ 1 (* 2 3))'
expr, _ = parse(tokenize(source))
# 4. Evaluate
result = node.machine_expr_eval(env_id=env_id, expr=expr) # -> Expr.Integer(7)
print(result.value) # 7
```
### Handling errors
Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
* Unterminated string literals are caught by `tokenize`.
* Unexpected or missing parentheses are caught by `parse`.
Catch the exception to provide developer‑friendly diagnostics:
```python
try:
tokens = tokenize(bad_source)
expr, _ = parse(tokens)
except ParseError as e:
print("Parse failed:", e)
```
---
## Testing
```bash
source venv/bin/activate
python3 -m unittest discover -s tests
```
Raw data
{
"_id": null,
"home_page": null,
"name": "astreum",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "\"Roy R. O. Okello\" <roy@stelar.xyz>",
"download_url": "https://files.pythonhosted.org/packages/8a/30/aecde39c19d6688aaf1df665dace5f3f3b1b5d93193e23ce865601f0e029/astreum-0.2.30.tar.gz",
"platform": null,
"description": "# lib\n\nPython library to interact with the Astreum blockchain and its Lispeum virtual machine.\n\n[View on PyPI](https://pypi.org/project/astreum/)\n\n## Configuration\n\nWhen initializing an `astreum.Node`, pass a dictionary with any of the options below. Only the parameters you want to override need to be present \u2013 everything else falls back to its default.\n\n### Core Configuration\n\n| Parameter | Type | Default | Description |\n| --------------------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `machine-only` | bool | `True` | When **True** the node starts in *machine\u2011only* mode: no storage subsystem and no relay networking \u2013 only the Lispeum VM. Set to **False** to enable storage and relay features. |\n| `relay_secret_key` | hex string | Auto\u2011generated | Ed25519 private key that identifies the node on the network. If omitted, a fresh keypair is generated and kept in\u2011memory. |\n| `validation_secret_key` | hex string | `None` | X25519 private key that lets the node participate in the validation route. Leave unset for a non\u2011validator node. |\n| `storage_path` | string | `None` | Directory where objects are persisted. If *None*, the node uses an in\u2011memory store. |\n| `storage_get_relay_timeout` | float | `5` | Seconds to wait for an object requested from peers before timing\u2011out. |\n\n### Networking\n\n| Parameter | Type | Default | Description |\n| --------------- | ----------------------- | ------- | ----------------------------------------------------------------------------------- |\n| `use_ipv6` | bool | `False` | Listen on IPv6 as well as IPv4. |\n| `incoming_port` | int | `7373` | UDP port the relay binds to. |\n| `bootstrap` | list\\[tuple\\[str, int]] | `[]` | Initial peers used to join the network, e.g. `[ (\"bootstrap.astreum.org\", 7373) ]`. |\n\n> **Note**\n> The peer\u2011to\u2011peer *route* used for object discovery is always enabled.\n> If `validation_secret_key` is provided the node automatically joins the validation route too.\n\n### Example\n\n```python\nfrom astreum.node import Node\n\nconfig = {\n \"machine-only\": False, # run full node\n \"relay_secret_key\": \"ab\u2026cd\", # optional \u2013 hex encoded\n \"validation_secret_key\": \"12\u202634\", # optional \u2013 validator\n \"storage_path\": \"./data/node1\",\n \"storage_get_relay_timeout\": 5,\n \"incoming_port\": 7373,\n \"use_ipv6\": False,\n \"bootstrap\": [\n (\"bootstrap.astreum.org\", 7373),\n (\"127.0.0.1\", 7374)\n ]\n}\n\nnode = Node(config)\n# \u2026 your code \u2026\n```\n\n## Lispeum Machine Quickstart\n\nThe Lispeum virtual machine (VM) is embedded inside `astreum.Node`. You feed it Lispeum source text, and the node tokenizes, parses, and **evaluates** the resulting AST inside an isolated environment.\n\n```python\nfrom astreum.node import Node\nfrom astreum.machine.tokenizer import tokenize\nfrom astreum.machine.parser import parse\n\n# 1. Spin\u2011up a stand\u2011alone VM (machine\u2011only node).\nnode = Node({\"machine-only\": True})\n\n# 2. Create an environment.\nenv_id = node.machine_create_environment()\n\n# 3. Convert Lispeum source \u2192 Expr AST.\nsource = '(+ 1 (* 2 3))'\nexpr, _ = parse(tokenize(source))\n\n# 4. Evaluate\nresult = node.machine_expr_eval(env_id=env_id, expr=expr) # -> Expr.Integer(7)\n\nprint(result.value) # 7\n```\n\n### Handling errors\n\nBoth helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:\n\n* Unterminated string literals are caught by `tokenize`.\n* Unexpected or missing parentheses are caught by `parse`.\n\nCatch the exception to provide developer\u2011friendly diagnostics:\n\n```python\ntry:\n tokens = tokenize(bad_source)\n expr, _ = parse(tokens)\nexcept ParseError as e:\n print(\"Parse failed:\", e)\n```\n\n---\n\n## Testing\n\n```bash\nsource venv/bin/activate\npython3 -m unittest discover -s tests\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library to interact with the Astreum blockchain and its Lispeum virtual machine.",
"version": "0.2.30",
"project_urls": {
"Homepage": "https://github.com/astreum/lib",
"Issues": "https://github.com/astreum/lib/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f30847808bc273056b52f5defb5c5c2d8807b69c6709e5e92a59f45fad84e85c",
"md5": "00634ddbfe10aef14b74d3e678cd3504",
"sha256": "6fc5345fa4a69ffeef8997ab79d2925481382c1daa5f05e2479f9f0c1adc552b"
},
"downloads": -1,
"filename": "astreum-0.2.30-py3-none-any.whl",
"has_sig": false,
"md5_digest": "00634ddbfe10aef14b74d3e678cd3504",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 36307,
"upload_time": "2025-07-24T19:16:55",
"upload_time_iso_8601": "2025-07-24T19:16:55.235346Z",
"url": "https://files.pythonhosted.org/packages/f3/08/47808bc273056b52f5defb5c5c2d8807b69c6709e5e92a59f45fad84e85c/astreum-0.2.30-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8a30aecde39c19d6688aaf1df665dace5f3f3b1b5d93193e23ce865601f0e029",
"md5": "f66b1e18153215ee4b093ef3433a6ff7",
"sha256": "99f0e5e4f94b9d3089371686e9a2e41aea3df341ee2ff960ecb8671b6809e5dd"
},
"downloads": -1,
"filename": "astreum-0.2.30.tar.gz",
"has_sig": false,
"md5_digest": "f66b1e18153215ee4b093ef3433a6ff7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 31843,
"upload_time": "2025-07-24T19:16:56",
"upload_time_iso_8601": "2025-07-24T19:16:56.385118Z",
"url": "https://files.pythonhosted.org/packages/8a/30/aecde39c19d6688aaf1df665dace5f3f3b1b5d93193e23ce865601f0e029/astreum-0.2.30.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 19:16:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "astreum",
"github_project": "lib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "astreum"
}
