astreum 0.2.0__tar.gz → 0.2.3__tar.gz

{astreum-0.2.0/src/astreum.egg-info → astreum-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.2.0
+Version: 0.2.3
 Summary: Python library to interact with the Astreum blockchain and its Lispeum virtual machine.
 Author-email: "Roy R. O. Okello" <roy@stelar.xyz>
 Project-URL: Homepage, https://github.com/astreum/lib
@@ -16,7 +16,7 @@ Requires-Dist: cryptography==44.0.2
 Requires-Dist: blake3==1.0.4
 Dynamic: license-file
 
-# Astreum Python Library
+# lib
 
 Python library to interact with the Astreum blockchain and its Lispeum virtual machine.
 
@@ -28,19 +28,13 @@ When initializing an `astreum.Node`, pass a dictionary with any of the options b
 
 ### 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.                                                    |
+| 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
 
@@ -79,7 +73,7 @@ node = Node(config)
 
 ## 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 *session* (lexical environment).
+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
@@ -89,16 +83,15 @@ from astreum.machine.parser import parse
 # 1. Spin‑up a stand‑alone VM (machine‑only node).
 node = Node({"machine-only": True})
 
-# 2. Create a fresh session (environment).
-session_id = node.machine_session_create()
+# 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 inside that session.
-env = node.sessions[session_id]           # fetch the Env
-result = node.machine_expr_eval(env, expr)  # -> Expr.Integer(7)
+# 4. Evaluate
+result = node.machine_expr_eval(env_id=env_id, expr=expr)  # -> Expr.Integer(7)
 
 print(result.value)  # 7
 ```
@@ -107,23 +100,8 @@ print(result.value)  # 7
 
 Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
 
-* Unterminated string literals are caught by `tokenize` fileciteturn1file1
-* Unexpected or missing parentheses are caught by `parse` fileciteturn1file0
-
-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)
-```
-
-Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
-
-* Unterminated string literals are caught by `tokenize` fileciteturn1file1
-* Unexpected or missing parentheses are caught by `parse` fileciteturn1file0
+* Unterminated string literals are caught by `tokenize`.
+* Unexpected or missing parentheses are caught by `parse`.
 
 Catch the exception to provide developer‑friendly diagnostics:
 
@@ -140,5 +118,6 @@ except ParseError as e:
 ## Testing
 
 ```bash
+
 python3 -m unittest discover -s tests
 ```

astreum-0.2.3/README.md

@@ -0,0 +1,105 @@
+# 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
+
+python3 -m unittest discover -s tests
+```

{astreum-0.2.0 → astreum-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "astreum"
-version = "0.2.0"
+version = "0.2.3"
 authors = [
   { name="Roy R. O. Okello", email="roy@stelar.xyz" },
 ]

astreum-0.2.3/src/astreum/__init__.py

@@ -0,0 +1 @@
+from .node import Node, Expr

astreum-0.2.3/src/astreum/lispeum/__init__.py

@@ -0,0 +1,2 @@
+from .parser import parse
+from .tokenizer import tokenize

{astreum-0.2.0 → astreum-0.2.3}/src/astreum/lispeum/parser.py

@@ -1,7 +1,8 @@
 from typing import List, Tuple
-from astreum.machine.error import ParseError
-from astreum.node import Expr
+from ..node import Expr
 
+class ParseError(Exception):
+    pass
 
 def parse(tokens: List[str]) -> Tuple[Expr, List[str]]:
     if not tokens:

{astreum-0.2.0 → astreum-0.2.3}/src/astreum/lispeum/storage.py

@@ -9,7 +9,7 @@ import struct
 from typing import Dict, Tuple, Any, List, Optional
 
 from astreum.lispeum.expression import Expr
-from .utils import hash_data
+from ..crypto.blake30 import hash_data
 
 
 def expr_to_objects(expr: Any) -> Tuple[bytes, Dict[bytes, bytes]]:

{astreum-0.2.0 → astreum-0.2.3}/src/astreum/lispeum/tokenizer.py

@@ -3,8 +3,8 @@
 # Tokenizer function
 from typing import List
 
-from astreum.machine.error import ParseError
-
+class ParseError(Exception):
+    pass
 
 def tokenize(input: str) -> List[str]:
     tokens = []

{astreum-0.2.0 → astreum-0.2.3}/src/astreum/node.py

@@ -6,10 +6,10 @@ from pathlib import Path
 from typing import Tuple, Dict, Union, Optional, List
 from datetime import datetime, timedelta, timezone
 import uuid
-from astreum import format
+from .format import encode, decode
 from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
 from cryptography.hazmat.primitives import serialization
-from astreum.crypto import ed25519, x25519
+from .crypto import ed25519, x25519
 from enum import IntEnum
 import blake3
 import struct
@@ -29,11 +29,11 @@ class ObjectRequest:
         self.hash = hash
 
     def to_bytes(self):
-        return format.encode([self.type.value, self.data, self.hash])
+        return encode([self.type.value, self.data, self.hash])
 
     @classmethod
     def from_bytes(cls, data: bytes):
-        type_val, data_val, hash_val = format.decode(data)
+        type_val, data_val, hash_val = decode(data)
         return cls(type=ObjectRequestType(type_val[0]), data=data_val, hash=hash_val)
 
 class ObjectResponseType(IntEnum):
@@ -52,11 +52,11 @@ class ObjectResponse:
         self.hash = hash
 
     def to_bytes(self):
-        return format.encode([self.type.value, self.data, self.hash])
+        return encode([self.type.value, self.data, self.hash])
 
     @classmethod
     def from_bytes(cls, data: bytes):
-        type_val, data_val, hash_val = format.decode(data)
+        type_val, data_val, hash_val = decode(data)
         return cls(type=ObjectResponseType(type_val[0]), data=data_val, hash=hash_val)
 
 class MessageTopic(IntEnum):
@@ -71,11 +71,11 @@ class Message:
     topic: MessageTopic
     
     def to_bytes(self):
-        return format.encode([self.body, [self.topic.value]])
+        return encode([self.body, [self.topic.value]])
 
     @classmethod
     def from_bytes(cls, data: bytes):
-        body, topic = format.decode(data)
+        body, topic = decode(data)
         return cls(body=body, topic=MessageTopic(topic[0]))
 
 class Envelope:
@@ -90,6 +90,7 @@ class Envelope:
         encrypted_bytes = b'\x01' if self.encrypted else b'\x00'
 
         self.message = message
+        message_bytes = message.to_bytes()
 
         self.sender = sender
         self.sender_bytes = sender.public_bytes()
@@ -119,14 +120,14 @@ class Envelope:
             return count
 
         while True:
-            envelope_bytes = format.encode([
+            envelope_bytes = encode([
                 encrypted_bytes,
                 message_bytes,
                 self.nonce,
                 self.sender_bytes,
                 timestamp_int
             ])
-            envelope_hash = utils.blake3_hash(envelope_bytes)
+            envelope_hash = blake3.blake3(envelope_bytes).digest()
             if count_leading_zero_bits(envelope_hash) >= difficulty:
                 self.hash = envelope_hash
                 break
@@ -135,7 +136,7 @@ class Envelope:
     def to_bytes(self):
         encrypted_bytes = b'\x01' if self.encrypted else b'\x00'
         
-        return format.encode([
+        return encode([
             encrypted_bytes,
             self.message.to_bytes(),
             self.nonce,
@@ -145,7 +146,7 @@ class Envelope:
 
     @classmethod
     def from_bytes(cls, data: bytes):
-        encrypted_bytes, message_bytes, nonce, sender_bytes, timestamp_int = format.decode(data)
+        encrypted_bytes, message_bytes, nonce, sender_bytes, timestamp_int = decode(data)
         return cls(
             encrypted=(encrypted_bytes == b'\x01'),
             message=Message.from_bytes(message_bytes),
@@ -278,7 +279,7 @@ class Expr:
             return f"(fn ({params_str}) {body_str})"
 
     class Error:
-        def __init__(self, message: str, origin: 'Expr' | None = None):
+        def __init__(self, message: str, origin: Optional['Expr'] = None):
             self.message = message
             self.origin  = origin
 
@@ -288,9 +289,9 @@ class Expr:
             return f'(error "{self.message}" in {self.origin})'
 
 class Env:
-    def __init__(self, parent: 'Env' = None):
+    def __init__(self, parent_id: uuid.UUID = None):
         self.data: Dict[str, Expr] = {}
-        self.parent = parent
+        self.parent_id = parent_id
 
     def put(self, name: str, value: Expr):
         self.data[name] = value
@@ -459,7 +460,7 @@ class Node:
                             self.peers[envelope.sender].timestamp = datetime.now(timezone.utc)
                             continue
 
-                        is_validator_flag = format.decode(envelope.message.body)
+                        is_validator_flag = decode(envelope.message.body)
 
                         if envelope.sender not in self.peers:
                             self._send_ping(addr)
@@ -514,7 +515,7 @@ class Node:
                                     nearest = self._get_closest_local_peer(object_hash)
                                     if nearest:
                                         nearest_key, nearest_peer = nearest
-                                        peer_info = format.encode([
+                                        peer_info = encode([
                                             nearest_key.public_bytes(
                                                 encoding=serialization.Encoding.Raw,
                                                 format=serialization.PublicFormat.Raw
@@ -533,7 +534,7 @@ class Node:
                                 # --------------  OBJECT_PUT  --------------
                                 case ObjectRequestType.OBJECT_PUT:
                                     # Ensure the hash is present / correct.
-                                    obj_hash = object_request.hash or blake3.blake3(object_request.data).digest()
+                                    obj_hash = object_request.hash or blake30.blake3(object_request.data).digest()
 
                                     nearest = self._get_closest_local_peer(obj_hash)
                                     # If a strictly nearer peer exists, forward the PUT.
@@ -548,7 +549,7 @@ class Node:
                                         self.outgoing_queue.put((fwd_env.to_bytes(), nearest[1].address))
                                     else:
                                         # We are closest → remember who can provide the object.
-                                        provider_record = format.encode([
+                                        provider_record = encode([
                                             envelope.sender.public_bytes(),
                                             encode_ip_address(*addr)
                                         ])
@@ -567,13 +568,13 @@ class Node:
                             
                             match object_response.type:
                                 case ObjectResponseType.OBJECT_FOUND:
-                                    if object_response.hash != blake3.blake3(object_response.data).digest():
+                                    if object_response.hash != blake30.blake3(object_response.data).digest():
                                         continue
                                     self.object_request_queue.remove(object_response.hash)
                                     self._local_object_put(object_response.hash, object_response.data)
 
                                 case ObjectResponseType.OBJECT_PROVIDER:
-                                    _provider_public_key, provider_address = format.decode(object_response.data)
+                                    _provider_public_key, provider_address = decode(object_response.data)
                                     provider_ip, provider_port = decode_ip_address(provider_address)
                                     object_request_message = Message(topic=MessageTopic.OBJECT_REQUEST, body=object_hash)
                                     object_request_envelope = Envelope(message=object_request_message, sender=self.relay_public_key)
@@ -582,7 +583,7 @@ class Node:
                                 case ObjectResponseType.OBJECT_NEAREST_PEER:
                                     # -- decode the peer info sent back
                                     nearest_peer_public_key_bytes, nearest_peer_address = (
-                                        format.decode(object_response.data)
+                                        decode(object_response.data)
                                     )
                                     nearest_peer_public_key = X25519PublicKey.from_public_bytes(
                                         nearest_peer_public_key_bytes
@@ -648,12 +649,12 @@ class Node:
                 print(f"Error in _peer_manager_thread: {e}")
 
     def _send_ping(self, addr: Tuple[str, int]):
-        is_validator_flag = format.encode([1] if self.validation_secret_key else [0])
+        is_validator_flag = encode([1] if self.validation_secret_key else [0])
         ping_message = Message(topic=MessageTopic.PING, body=is_validator_flag)
         ping_envelope = Envelope(message=ping_message, sender=self.relay_public_key)
         self.outgoing_queue.put((ping_envelope.to_bytes(), addr))
 
-    def _get_closest_local_peer(self, hash: bytes) -> Optional[(X25519PublicKey, Peer)]:
+    def _get_closest_local_peer(self, hash: bytes) -> Optional[Tuple[X25519PublicKey, Peer]]:
         # Find the globally closest peer using XOR distance
         closest_peer = None
         closest_distance = None
@@ -694,44 +695,48 @@ class Node:
 
     # MACHINE
     def _machine_setup(self):
-        self.sessions: Dict[uuid.UUID, Env] = {}
-        self.lock = threading.Lock()
-
-    def machine_session_create(self) -> uuid.UUID:
-        session_id = uuid.uuid4()
-        with self.lock:
-            self.sessions[session_id] = Env()
-        return session_id
-    
-    def machine_session_delete(self, session_id: str) -> bool:
-        with self.lock:
-            if session_id in self.sessions:
-                del self.sessions[session_id]
-                return True
-            else:
-                return False
-
-    def machine_expr_get(self, session_id: uuid.UUID, name: str) -> Optional[Expr]:
-        with self.lock:
-            env = self.sessions.get(session_id)
-        if env is None:
-            return None
-        return env.get(name)
+        self.environments: Dict[uuid.UUID, Env] = {}
+        self.machine_environments_lock = threading.Lock()
+
+    def machine_create_environment(self, parent_id: Optional[uuid.UUID] = None) -> uuid.UUID:
+        env_id = uuid.uuid4()
+        with self.machine_environments_lock:
+            while env_id in self.environments:
+                env_id = uuid.uuid4()
+            self.environments[env_id] = Env(parent_id=parent_id)
+        return env_id
+
+    def machine_delete_environment(self, env_id: uuid.UUID) -> bool:
+        with self.machine_environments_lock:
+            removed = self.environments.pop(env_id, None)
+        return removed is not None
+
+    def machine_expr_get(self, env_id: uuid.UUID, name: str) -> Optional[Expr]:
+        with self.machine_environments_lock:
+            cur = self.environments.get(env_id)
+            while cur is not None:
+                if name in cur.data:
+                    return cur.data[name]
+                if cur.parent_id:
+                    cur = self.environments.get(cur.parent_id)
+                else:
+                    cur = None
+        return None
         
-    def machine_expr_put(self, session_id: uuid.UUID, name: str, expr: Expr):
-        with self.lock:
-            env = self.sessions.get(session_id)
+    def machine_expr_put(self, env_id: uuid.UUID, name: str, expr: Expr):
+        with self.machine_environments_lock:
+            env = self.environments.get(env_id)
         if env is None:
             return False
         env.put(name, expr)
         return True
 
-    def machine_expr_eval(self, env: Env, expr: Expr) -> Expr:
+    def machine_expr_eval(self, env_id: uuid.UUID, expr: Expr) -> Expr:
         if isinstance(expr, Expr.Boolean) or isinstance(expr, Expr.Integer) or isinstance(expr, Expr.String) or isinstance(expr, Expr.Error):
             return expr
         
         elif isinstance(expr, Expr.Symbol):
-            value = env.get(expr.value)
+            value = self.machine_expr_get(env_id=env_id, name=expr.value)
             if value:
                 return value
             else:
@@ -741,24 +746,26 @@ class Node:
             if len(expr.elements) == 0:
                 return expr 
             if len(expr.elements) == 1:
-                return self.machine_expr_eval(expr=expr.elements[0], env=env)
+                return self.machine_expr_eval(expr=expr.elements[0], env_id=env_id)
             first = expr.elements[0]
             if isinstance(first, Expr.Symbol):
-                first_symbol_value = env.get(first.value)
+                first_symbol_value = self.machine_expr_get(env_id=env_id, name=first.value)
                 
                 if first_symbol_value and not isinstance(first_symbol_value, Expr.Function):
-                    evaluated_elements = [self.evaluate_expression(e, env) for e in expr.elements]
+                    evaluated_elements = [self.machine_expr_eval(env_id=env_id, expr=e) for e in expr.elements]
                     return Expr.ListExpr(evaluated_elements)
                 
                 elif first.value == "def":
+                    args = expr.elements[1:]
                     if len(args) != 2:
                         return Expr.Error(message=f"'def' expects exactly 2 arguments, got {len(args)}", origin=expr)
                     if not isinstance(args[0], Expr.Symbol):
                         return Expr.Error(message="first argument to 'def' must be a symbol", origin=args[0])
-                    result = self.machine_expr_eval(env=env, expr=args[1])
+                    result = self.machine_expr_eval(env_id=env_id, expr=args[1])
                     if isinstance(result, Expr.Error):
                         return result
-                    env.put(name=args[0].value, value=result)
+                    
+                    self.machine_expr_put(env_id=env_id, name=args[0].value, expr=result)
                     return result
 
                 # # List
@@ -901,7 +908,7 @@ class Node:
                         return Expr.Error(message="'+' expects at least 1 argument", origin=expr)
                     evaluated_args = []
                     for arg in args:
-                        val = self.evaluate_expression(arg, env)
+                        val = self.machine_expr_eval(env_id==env_id, expr=arg)
                         if isinstance(val, Expr.Error):
                             return val
                         evaluated_args.append(val)
@@ -1010,7 +1017,7 @@ class Node:
                 #     return Expr.Integer(dividend % divisor)
 
             else:
-                evaluated_elements = [self.evaluate_expression(e, env) for e in expr.elements]
+                evaluated_elements = [self.machine_expr_eval(env_id=env_id, expr=e) for e in expr.elements]
                 return Expr.ListExpr(evaluated_elements)
             
         elif isinstance(expr, Expr.Function):

{astreum-0.2.0 → astreum-0.2.3/src/astreum.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astreum
-Version: 0.2.0
+Version: 0.2.3
 Summary: Python library to interact with the Astreum blockchain and its Lispeum virtual machine.
 Author-email: "Roy R. O. Okello" <roy@stelar.xyz>
 Project-URL: Homepage, https://github.com/astreum/lib
@@ -16,7 +16,7 @@ Requires-Dist: cryptography==44.0.2
 Requires-Dist: blake3==1.0.4
 Dynamic: license-file
 
-# Astreum Python Library
+# lib
 
 Python library to interact with the Astreum blockchain and its Lispeum virtual machine.
 
@@ -28,19 +28,13 @@ When initializing an `astreum.Node`, pass a dictionary with any of the options b
 
 ### 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.                                                    |
+| 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
 
@@ -79,7 +73,7 @@ node = Node(config)
 
 ## 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 *session* (lexical environment).
+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
@@ -89,16 +83,15 @@ from astreum.machine.parser import parse
 # 1. Spin‑up a stand‑alone VM (machine‑only node).
 node = Node({"machine-only": True})
 
-# 2. Create a fresh session (environment).
-session_id = node.machine_session_create()
+# 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 inside that session.
-env = node.sessions[session_id]           # fetch the Env
-result = node.machine_expr_eval(env, expr)  # -> Expr.Integer(7)
+# 4. Evaluate
+result = node.machine_expr_eval(env_id=env_id, expr=expr)  # -> Expr.Integer(7)
 
 print(result.value)  # 7
 ```
@@ -107,23 +100,8 @@ print(result.value)  # 7
 
 Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
 
-* Unterminated string literals are caught by `tokenize` fileciteturn1file1
-* Unexpected or missing parentheses are caught by `parse` fileciteturn1file0
-
-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)
-```
-
-Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
-
-* Unterminated string literals are caught by `tokenize` fileciteturn1file1
-* Unexpected or missing parentheses are caught by `parse` fileciteturn1file0
+* Unterminated string literals are caught by `tokenize`.
+* Unexpected or missing parentheses are caught by `parse`.
 
 Catch the exception to provide developer‑friendly diagnostics:
 
@@ -140,5 +118,6 @@ except ParseError as e:
 ## Testing
 
 ```bash
+
 python3 -m unittest discover -s tests
 ```

{astreum-0.2.0 → astreum-0.2.3}/src/astreum.egg-info/SOURCES.txt

@@ -41,7 +41,6 @@ src/astreum/lispeum/expression.py
 src/astreum/lispeum/parser.py
 src/astreum/lispeum/storage.py
 src/astreum/lispeum/tokenizer.py
-src/astreum/lispeum/utils.py
 src/astreum/lispeum/special/__init__.py
 src/astreum/lispeum/special/definition.py
 src/astreum/lispeum/special/list/__init__.py
@@ -57,4 +56,5 @@ src/astreum/lispeum/special/number/__init__.py
 src/astreum/lispeum/special/number/addition.py
 src/astreum/machine/__init__.py
 src/astreum/machine/environment.py
-src/astreum/machine/error.py
+src/astreum/machine/error.py
+tests/test_node_machine.py

astreum-0.2.3/tests/test_node_machine.py

@@ -0,0 +1,56 @@
+import unittest
+from src.astreum.node import Node, Expr
+from src.astreum.lispeum import tokenize, parse
+
+
+class TestNodeMachine(unittest.TestCase):
+    """Integration tests for the Lispeum VM embedded in astreum.Node."""
+
+    def setUp(self):
+        # Spin‑up a stand‑alone VM
+        self.node = Node({"machine-only": True})
+        self.env_id = self.node.machine_create_environment()
+        self.env = self.node.environments[self.env_id]
+
+    # ---------- helpers --------------------------------------------------
+    def _eval(self, source: str) -> Expr:
+        """Tokenize → parse → eval a Lispeum snippet inside the current env."""
+        tokens = tokenize(source)
+        expr, _ = parse(tokens)
+        return self.node.machine_expr_eval(env_id=self.env_id, expr=expr)
+
+    # ---------- core tests ----------------------------------------------
+    def test_int_addition(self):
+        """(+ 2 3) ⇒ 5"""
+        result = self._eval("(+ 2 3)")
+        self.assertEqual(result.value, 5)
+
+    def test_variable_definition_and_lookup(self):
+        """(def numero 42) then numero ⇒ 42"""
+        self._eval("(def numero 42)")
+        lookup_result = self._eval("numero")
+        self.assertEqual(lookup_result.value, 42)
+
+    def test_session_isolation(self):
+        """Variables defined in one session must not leak into another."""
+        # Define in first env
+        self._eval("(def a 1)")
+
+        # Create second session
+        other_env = self.node.machine_create_environment()
+
+        tokens = tokenize("a")
+        expr, _ = parse(tokens)
+        result_other = self.node.machine_expr_eval(env_id=other_env, expr=expr)
+
+        # Expect an Expr.Error or any non‑1 value
+        self.assertTrue(
+            isinstance(result_other, Expr.Error) or getattr(result_other, "value", None) != 1,
+            "Variable 'a' leaked across sessions"
+        )
+
+        self.node.machine_delete_environment(other_env)
+
+
+if __name__ == "__main__":
+    unittest.main()

astreum-0.2.0/README.md

@@ -1,126 +0,0 @@
-# Astreum Python Library
-
-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 *session* (lexical 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 a fresh session (environment).
-session_id = node.machine_session_create()
-
-# 3. Convert Lispeum source → Expr AST.
-source = '(+ 1 (* 2 3))'
-expr, _ = parse(tokenize(source))
-
-# 4. Evaluate inside that session.
-env = node.sessions[session_id]           # fetch the Env
-result = node.machine_expr_eval(env, 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` fileciteturn1file1
-* Unexpected or missing parentheses are caught by `parse` fileciteturn1file0
-
-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)
-```
-
-Both helpers raise `ParseError` (from `astreum.machine.error`) when something goes wrong:
-
-* Unterminated string literals are caught by `tokenize` fileciteturn1file1
-* Unexpected or missing parentheses are caught by `parse` fileciteturn1file0
-
-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
-python3 -m unittest discover -s tests
-```

astreum-0.2.0/src/astreum/__init__.py

@@ -1 +0,0 @@
-from node import Node

astreum-0.2.0/src/astreum/lispeum/__init__.py

@@ -1,2 +0,0 @@
-from parser import parse
-from tokenizer import tokenize

astreum-0.2.0/src/astreum/lispeum/utils.py

@@ -1,17 +0,0 @@
-"""
-Utility functions for the Lispeum module.
-"""
-
-import blake3
-
-def hash_data(data: bytes) -> bytes:
-    """
-    Hash data using BLAKE3.
-    
-    Args:
-        data: Data to hash
-        
-    Returns:
-        32-byte BLAKE3 hash
-    """
-    return blake3.blake3(data).digest()

astreum-0.2.0/src/astreum/machine/error.py

@@ -1,2 +0,0 @@
-class ParseError(Exception):
-    pass