py2openai 0.9.5

Create OpenAI-compatible function schemas from python functions

Py2OpenAI

A Python library that automatically converts Python functions to OpenAI function calling schemas.

Read the documentation!

OpenAI Function Schema Generator

Convert Python functions to OpenAI-compatible function schemas automatically.

Installation

pip install py2openai

Basic Usage

from py2openai import create_schema
from typing import Literal

def get_weather(
    location: str,
    unit: Literal["C", "F"] = "C",
    detailed: bool = False,
) -> dict[str, str | float]:
    """Get the weather for a location.

    Args:
        location: City or address to get weather for
        unit: Temperature unit (Celsius or Fahrenheit)
        detailed: Include extended forecast
    """
    return {"temp": 22.5, "conditions": "sunny"}

# Create schema
schema = create_schema(get_weather)

# The schema.model_dump_openai() returns a TypedDict with the complete OpenAI tool definition:
# OpenAIFunctionTool = TypedDict({
#     "type": Literal["function"],
#     "function": OpenAIFunctionDefinition
# })

# Use with OpenAI
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What's the weather in London?"}],
    tools=[schema.model_dump_openai()],  # Schema includes the type: "function" wrapper
    tool_choice="auto"
)

Note: This library supports the OpenAI API v1 format (openai>=1.0.0). For older versions of the OpenAI package that use the legacy functions API, you'll need to unwrap the function definition using schema.model_dump_openai()["function"].

## Supported Types

### Basic Types
```python
def func(
    text: str,              # -> "type": "string"
    number: int,            # -> "type": "integer"
    amount: float,          # -> "type": "number"
    enabled: bool,          # -> "type": "boolean"
    anything: Any,          # -> "type": "string"
) -> None: ...

Container Types

def func(
    items: list[str],                    # -> "type": "array", "items": {"type": "string"}
    numbers: set[int],                   # -> same as list
    mapping: dict[str, Any],            # -> "type": "object", "additionalProperties": true
    nested: list[dict[str, int]],       # -> nested array/object types
    sequence: Sequence[str],            # -> "type": "array"
    collection: Collection[int],        # -> "type": "array"
) -> None: ...

Enums and Literals

class Color(Enum):
    RED = "red"
    BLUE = "blue"

def func(
    color: Color,                       # -> "type": "string", "enum": ["red", "blue"]
    mode: Literal["fast", "slow"],      # -> "type": "string", "enum": ["fast", "slow"]
) -> None: ...

Optional and Union Types

def func(
    opt1: str | None,                   # -> "type": "string"
    opt2: int | None,                   # -> "type": "integer"
    union: str | int,                   # -> "type": "string" (first type)
) -> None: ...

Custom Types

@dataclass
class User:
    name: str
    age: int

def func(
    user: User,                         # -> "type": "object"
    data: JsonDict,                     # -> "type": "object"
) -> None: ...

Type Aliases

JsonValue = dict[str, Any] | list[Any] | str | int | float | bool | None
JsonDict = dict[str, JsonValue]

def func(
    data: JsonDict,                     # -> "type": "object"
    values: list[JsonValue],            # -> "type": "array"
) -> None: ...

Recursive Types

def func(
    tree: dict[str, "dict[str, Any] | str"],  # -> "type": "object"
    nested: dict[str, list["dict[str, Any]"]], # -> "type": "object"
) -> None: ...

Generated Schema Example

{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the weather for a location.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City or address to get weather for"
                },
                "unit": {
                    "type": "string",
                    "enum": ["C", "F"],
                    "description": "Temperature unit (Celsius or Fahrenheit)",
                    "default": "C"
                },
                "detailed": {
                    "type": "boolean",
                    "description": "Include extended forecast",
                    "default": false
                }
            },
            "required": ["location"]
        }
    }
}

Schema Generators

Module Schemas

You can generate schemas for all public functions in a module using create_schemas_from_module:

from py2openai import create_schemas_from_module
import math

# Generate schemas for all public functions
schemas = create_schemas_from_module(math)

# Generate schemas for specific functions only
schemas = create_schemas_from_module(math, include_functions=['sin', 'cos'])

# Import module by string name
schemas = create_schemas_from_module('math')

Class Schemas

Generate schemas for all public methods in a class using create_schemas_from_class:

from py2openai import create_schemas_from_class

class Calculator:
    def add(self, x: int, y: int) -> int:
        """Add two numbers.

        Args:
            x: First number
            y: Second number

        Returns:
            Sum of x and y
        """
        return x + y

    @classmethod
    def multiply(cls, x: int, y: int) -> int:
        """Multiply two numbers.

        Args:
            x: First number
            y: Second number

        Returns:
            Product of x and y
        """
        return x * y

    @staticmethod
    def divide(x: float, y: float) -> float:
        """Divide two numbers.

        Args:
            x: Numerator
            y: Denominator

        Returns:
            Result of x divided by y
        """
        return x / y

# Generate schemas for all public methods
schemas = create_schemas_from_class(Calculator)

# Access individual method schemas
add_schema = schemas['Calculator.add']
multiply_schema = schemas['Calculator.multiply']
divide_schema = schemas['Calculator.divide']

The schema generators support:

• Regular instance methods
• Class methods
• Static methods
• Async methods
• Property methods
• All supported type annotations
• Method docstrings for descriptions
• Default values
• Return type hints