Skip to content

Femscript Python API Documentation

The Femscript Python API allows seamless integration of Femscript code with Python. This API provides tools for parsing, executing, and interacting with Femscript, enabling you to bind Python functions, convert data between Python and Femscript, and handle Femscript tokens and AST (Abstract Syntax Tree).

Classes and Functions

TokenType

  • "Str"
  • "Int"
  • "Bool"
  • "None"
  • "List"
  • "Bytes"
  • "Scope"

class Token : TypedDict

  • Structure:

class Variable : TypedDict

  • Structure:

function var

Creates a Femscript variable.

def var(
    name: str,
    value: Optional[Any] = None,
    *,
    variables: Optional[list[Variable]] = None
) -> Variable
  • Parameters:
    • name: str - Name of the variable.
    • value: Any - Python object
    • variables: [Variable]? - Optional scope for nested variables.
  • Returns: Variable
  • Example: 
    1
2
3
    from femscript import Femscript, var

fs = Femscript("x + y", variables=[var("x", 35), var("y", 34)])

class Femscript

The Femscript class provides the primary interface for parsing and executing Femscript code. It allows defining variables, registering custom Python functions, and running Femscript scripts asynchronously.

class Femscript:
    def __init__(
        code: Optional[str] = None,
        *,
        variables: Optional[list[Variable]] = None,
        functions: Optional[list[Callable[[str, list[Token], list[Variable]], Token]]] = None
    ) -> None
  • Parameters:
    • code: str? - Femscript code to parse during initialization.
    • variables: [Variable]? - Predefined variables to add to the script's scope.
    • functions: [(str, [Token...], [Variable...]) -> Token]? - Custom Python functions to bind to Femscript.
  • Example: 
    1
2
3
    from femscript import Femscript, var

fs = Femscript("x + y", variables=[var("x", 35), var("y", 34)])

classmethod to_fs

Converts a Python object into a Femscript token.

@classmethod
def to_fs(obj: Any) -> Token
  • Parameters:
    • obj: Any - Python object to convert.
  • Returns: Token

classmethod to_py

Converts a Femscript token into a Python object.

@classmethod
def to_py(token: Token) -> Any
  • Parameters:
    • token: Token - Femscript token to convert.
  • Returns: Any

method add_variable

Adds or updates a variable in the script's scope.

def add_variable(self, variable: Variable) -> None
  • Parameters:
    • variable: Variable - A variable to add or update.

method wrap_function

Wraps a Python function to make it callable from Femscript.

def wrap_function(
    self,
    func: Optional[Callable[..., object]] = None,
    *,
    func_name: Optional[str] = None,
    with_name: Optional[bool] = False
) -> Callable
  • Parameters:
    • func: Callable? - The Python function to wrap.
    • func_name: str? - Name to use for the function in Femscript (default: Python function name)
    • with_name: bool? - If True, the function receives its Femscript name as the first argument.
  • Returns: Callable
  • Example: 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    fs = Femscript()

@fs.wrap_function()
def add(a: int, b: int) -> int:
    return a + b

@fs.wrap_function()
async def something(**kwargs) -> Any:
    # do something asynchronously
    ...

fs.wrap_function(print)

async method execute

Executes the parsed AST asynchronously.

async def execute(self, *, debug: bool = False) -> Any
  • Parameters:
    • debug: bool? - If True, the script execution environment includes the print and debug built-in functions.
  • Returns: Any
  • Example: 
    1
2
3
4
5
6
    from femscript import Femscript

fs = Femscript("x = 10; x")
result = await fs.execute()

print(result) # Outputs: 10

Examples

  1. Basic Execution 

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
    import asyncio
from femscript import Femscript, var

async def main() -> None:
    fs = Femscript("x = 35; x + y", variables=[var("y", 34)])
    result = await fs.execute()
    print(result) # Ouputs: 69

if __name__ == "__main__":
    asyncio.run(main())

  2. Binding Python Functions 

    1
2
3
4
5
6
7
8
9
    fs = Femscript("add(35, 34)")

@fs.wrap_function()
def add(a: int, b: int) -> int:
    return a + b

result = await fs.execute()

print(result) # Outputs: 69