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

# Python Integration

> Extend LoT actions with Python functions for complex calculations and data processing

## Overview

While LoT handles most IoT automation elegantly, some tasks need the full power of a programming language. Python integration lets you call Python functions directly from your LoT actions—no external services, no network calls, no containers. Your Python code runs inside the broker alongside your actions.

<Tip>
  **Think of Python as a specialist you can call for help.** Your LoT action handles the routine work (reading sensors, routing messages, checking thresholds), but when it encounters something complex—statistical analysis, regex parsing, or calling an external library—it hands the task to Python and gets the result back instantly.
</Tip>

***

## When to Use Python vs. LoT

Before diving into syntax, understand when Python makes sense:

| Use Python For                         | Use LoT For                          |
| -------------------------------------- | ------------------------------------ |
| Complex calculations (statistics, ML)  | Simple math (+, -, \*, /)            |
| Regex and advanced string parsing      | String concatenation                 |
| Data validation with complex rules     | Basic conditionals (IF/THEN)         |
| External library calls (numpy, pandas) | MQTT operations (PUBLISH, GET TOPIC) |
| JSON transformation and restructuring  | Field extraction (GET JSON)          |

<Info>
  If you can do it in LoT, do it in LoT. Python adds overhead—use it when LoT's built-in operations aren't enough.
</Info>

***

## In This Page

| Section                                         | Description                               |
| ----------------------------------------------- | ----------------------------------------- |
| [CALL PYTHON Syntax](#call-python-syntax)       | Basic syntax for calling Python functions |
| [Parameter Passing](#parameter-passing)         | Pass data from LoT to Python              |
| [Return Value Handling](#return-value-handling) | Handle Python return values in LoT        |
| [Error Handling](#error-handling)               | Gracefully handle Python errors           |
| [Best Practices](#best-practices)               | Performance and reliability tips          |

***

## CALL PYTHON Syntax

```lot theme={null}
CALL PYTHON "ScriptName.function_name"
    WITH (parameter1, parameter2, ...)
    RETURN AS {variable_name}
```

## Parameter Passing

### Single Parameter

```lot theme={null}
CALL PYTHON "Processor.validate" 
    WITH (PAYLOAD) 
    RETURN AS {result}
```

### Multiple Parameters

```lot theme={null}
SET "min_val" WITH (GET TOPIC "config/min")
SET "max_val" WITH (GET TOPIC "config/max")

CALL PYTHON "Validator.check_range" 
    WITH (PAYLOAD, {min_val}, {max_val}) 
    RETURN AS {result}
```

## Return Value Handling

Python functions can return simple values or complex JSON objects. The `RETURN AS` clause captures the result into a LoT variable.

### Simple Values

For basic calculations, return a single value:

**Python function:**

```python theme={null}
def add_numbers(a, b):
    return float(a) + float(b)
```

**LoT action calling the function:**

```lot theme={null}
CALL PYTHON "Calculator.add_numbers" WITH (5, 3) RETURN AS {result}
PUBLISH TOPIC "math/result" WITH {result}
```

### JSON Objects

For richer data, return a dictionary—it becomes JSON that LoT can parse:

**Python function returning a dictionary:**

```python theme={null}
def analyze_data(value):
    return {
        "original": float(value),
        "doubled": float(value) * 2,
        "squared": float(value) ** 2
    }
```

**LoT action extracting fields from the result:**

```lot theme={null}
CALL PYTHON "Analyzer.analyze_data" WITH (5) RETURN AS {result}

PUBLISH TOPIC "analysis/full" WITH {result}
PUBLISH TOPIC "analysis/doubled" WITH (GET JSON "doubled" IN {result} AS DOUBLE)
```

## Error Handling

```lot theme={null}
CALL PYTHON "Calculator.safe_division" WITH (10, 2) RETURN AS {result}

SET "success" WITH (GET JSON "success" IN {result} AS BOOL)

IF {success} EQUALS TRUE THEN
    PUBLISH TOPIC "calculation/result" WITH (GET JSON "result" IN {result} AS DOUBLE)
ELSE
    PUBLISH TOPIC "calculation/error" WITH (GET JSON "error" IN {result} AS STRING)
```

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Functions Fast" icon="bolt">
    Target execution times under 100ms. Long-running Python functions block your action and can delay message processing. For heavy computations, consider offloading to an external service.
  </Accordion>

  <Accordion title="Always Handle Errors" icon="shield">
    Wrap Python logic in try/except blocks and return structured error responses. This lets your LoT action gracefully handle failures instead of crashing.
  </Accordion>

  <Accordion title="Return JSON-Serializable Types" icon="code">
    Return dictionaries, lists, strings, numbers, and booleans. Custom objects and classes won't serialize properly. When in doubt, convert to a dictionary.
  </Accordion>

  <Accordion title="Validate Input Parameters" icon="check">
    Python functions receive parameters as strings by default. Always convert types explicitly (e.g., `float(value)`, `int(count)`) and validate ranges before processing.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Operations Reference" icon="gear" href="./operations">
    Review all available LoT operations.
  </Card>

  <Card title="Actions Overview" icon="bolt" href="./overview">
    Return to the Actions overview for pattern guidance.
  </Card>
</CardGroup>