API Reference

This page provides complete API documentation for lynguine server mode.

Client API

ServerClient

class lynguine.client.ServerClient(server_url='http://127.0.0.1:8765', timeout=30.0, auto_start=False, idle_timeout=0, max_retries=3, retry_delay=1.0)[source]

Bases: object

Client for lynguine server mode.

Provides a simple interface to connect to a running lynguine server and perform operations without incurring startup costs.

Example

client = ServerClient(’http://127.0.0.1:8765’) df = client.read_data(interface_file=’config.yml’, directory=’.’)

Initialize the server client

Parameters:

server_url (str) – URL of the lynguine server (default: http://127.0.0.1:8765)
timeout (float) – Request timeout in seconds (default: 30.0)
auto_start (bool) – Auto-start server if not running (default: False)
idle_timeout (int) – Server idle timeout in seconds when auto-starting (0=disabled, default: 0)
max_retries (int) – Maximum number of retries for failed requests (default: 3)
retry_delay (float) – Base delay between retries in seconds, uses exponential backoff (default: 1.0)

Raises:

ImportError – If requests library is not installed

Parameters:

server_url (str) – URL of the lynguine server (default: 'http://127.0.0.1:8765')
timeout (float) – Request timeout in seconds (default: 30.0)
auto_start (bool) – Auto-start server if not running (default: False)
idle_timeout (int) – Server idle timeout in seconds when auto-starting (default: 0 = disabled)
max_retries (int) – Maximum number of retries for failed requests (default: 3)
retry_delay (float) – Base delay between retries in seconds, uses exponential backoff (default: 1.0)

Example:

from lynguine.client import ServerClient

# Basic usage
client = ServerClient()
df = client.read_data(interface_file='config.yml')
client.close()

# With auto-start and retry logic
client = ServerClient(
    auto_start=True,
    idle_timeout=300,
    max_retries=3,
    retry_delay=1.0
)

# As context manager
with ServerClient(auto_start=True) as client:
    df = client.read_data(interface_file='config.yml')

__init__(server_url='http://127.0.0.1:8765', timeout=30.0, auto_start=False, idle_timeout=0, max_retries=3, retry_delay=1.0)[source]

Initialize the server client

Parameters:

server_url (str) – URL of the lynguine server (default: http://127.0.0.1:8765)
timeout (float) – Request timeout in seconds (default: 30.0)
auto_start (bool) – Auto-start server if not running (default: False)
idle_timeout (int) – Server idle timeout in seconds when auto-starting (0=disabled, default: 0)
max_retries (int) – Maximum number of retries for failed requests (default: 3)
retry_delay (float) – Base delay between retries in seconds, uses exponential backoff (default: 1.0)

Raises:

ImportError – If requests library is not installed

ping()[source]

Test connectivity to the server

Returns:: True if server is reachable, False otherwise
Return type:: bool

health_check()[source]

Get server health status (with automatic retry on failure)

Returns:

Server health information

Raises:

requests.HTTPError – If request fails
RuntimeError – If server is not available after retries

Return type:

Dict[str, Any]

read_data(interface_file=None, directory='.', interface_field=None, data_source=None)[source]

Read data via the lynguine server (with automatic retry on failure)

Either provide interface_file (to load from a lynguine interface config) or provide data_source (to read directly from a data source).

Parameters:

interface_file (str | None) – Path to lynguine interface YAML file
directory (str) – Directory for resolving relative paths (default: ‘.’)
interface_field (str | None) – Optional field name within interface
data_source (Dict[str, Any] | None) – Direct data source specification (dict with ‘type’, ‘filename’, etc.)

Returns:

DataFrame containing the data

Raises:

ValueError – If neither interface_file nor data_source is provided
RuntimeError – If server is not available after retries
requests.HTTPError – If request fails

Return type:

DataFrame

close()[source]

Close the client session

Note: Does NOT stop auto-started servers by design. Auto-started servers remain running for other clients and will shut down via idle timeout if configured.

__enter__()[source]: Context manager entry

__exit__(exc_type, exc_val, exc_tb)[source]: Context manager exit

create_session(interface_file, directory='.', interface_field=None, timeout=3600)[source]

Create a stateful session by loading interface file.

Parameters:

interface_file (str) – Path to lynguine interface YAML file
directory (str) – Directory for resolving relative paths
interface_field (str | None) – Optional field within interface
timeout (int) – Session timeout in seconds (0 = no timeout)

Returns:

Session object

Return type:

Session

list_sessions()[source]: List all sessions

get_session(session_id)[source]

Get an existing session by ID

Parameters:: session_id (str)
Return type:: Session

delete_session(session_id)[source]

Delete a session

Parameters:: session_id (str)

get_interface_field(interface_file, field, directory='.')[source]

Extract a field value from an interface configuration file.

Loads the interface file and extracts a single field without loading the full CustomDataFrame data. Optimized for lamd’s mdfield utility.

Parameters:

interface_file (str) – Path to interface YAML file
field (str) – Field name to extract (e.g., ‘title’, ‘author’)
directory (str) – Working directory for resolving paths (default: ‘.’)

Returns:

Field value (any type) or None if field not found

Raises:

RuntimeError – If server is not available after retries
requests.HTTPError – If request fails

Return type:

Any

Example

>>> client = ServerClient(auto_start=True)
>>> title = client.get_interface_field('_lamd.yml', 'title')
>>> print(title)
'My Document Title'

extract_talk_field(field, markdown_file, config_files=None)[source]

Extract a field from markdown frontmatter with config fallback.

Wraps lynguine.util.talk.talk_field() functionality, providing: - Markdown frontmatter parsing - Fallback to interface config files - Array formatting for categories - Environment variable expansion

Optimized for lamd’s mdfield utility integration.

Parameters:

field (str) – Field name to extract (e.g., ‘title’, ‘author’, ‘venue’)
markdown_file (str) – Path to markdown file with YAML frontmatter
config_files (list | None) – List of config files for fallback (default: [])

Returns:

Field value as string (empty string if not found)

Raises:

RuntimeError – If server is not available after retries
requests.HTTPError – If request fails

Return type:

str

Example

>>> client = ServerClient(auto_start=True)
>>> title = client.extract_talk_field(
...     field='title',
...     markdown_file='my-talk.md',
...     config_files=['_lamd.yml']
... )
>>> print(title)
'My Talk Title'

Methods

ping()

Test connectivity to the server.

returns:: True if server is reachable, False otherwise
rtype:: bool

if client.ping():
    print("Server is online")

health_check()

Get server health status with automatic retry on failure.

returns:: Server health information dictionary
rtype:: Dict[str, Any]
raises RuntimeError:: If server is not available after retries
raises requests.HTTPError:: If request fails

health = client.health_check()
print(health['status'])  # 'ok'

read_data()

Read data via the lynguine server with automatic retry on failure.

param interface_file:: Path to lynguine interface YAML file
type interface_file:: Optional[str]
param directory:: Directory for resolving relative paths (default: '.')
type directory:: str
param interface_field:: Optional field name within interface
type interface_field:: Optional[str]
param data_source:: Direct data source specification (dict with ‘type’, ‘filename’, etc.)
type data_source:: Optional[Dict[str, Any]]
returns:: DataFrame containing the data
rtype:: pd.DataFrame
raises ValueError:: If neither interface_file nor data_source is provided
raises RuntimeError:: If server is not available after retries
raises requests.HTTPError:: If request fails

# Using interface file
df = client.read_data(
    interface_file='config.yml',
    directory='.'
)

# Using direct data source
df = client.read_data(
    data_source={'type': 'fake', 'nrows': 10, 'cols': ['name']}
)

close()

Close the client session.

Note

Does NOT stop auto-started servers by design. Auto-started servers remain running for other clients and will shut down via idle timeout if configured.

client.close()

Convenience Function

lynguine.client.create_client(server_url='http://127.0.0.1:8765')[source]

Create a lynguine server client

Parameters:: server_url (str) – URL of the lynguine server
Returns:: ServerClient instance
Return type:: ServerClient

Example:

from lynguine.client import create_client

client = create_client('http://127.0.0.1:8765')

Server API

Starting the Server

# Basic usage
python -m lynguine.server

# Custom host and port
python -m lynguine.server --host 127.0.0.1 --port 8765

# With idle timeout (auto-shutdown after inactivity)
python -m lynguine.server --idle-timeout 300  # 5 minutes

lynguine.server.run_server(host='127.0.0.1', port=8765, idle_timeout=0)[source]

Start the lynguine HTTP server

Checks if a server is already running on the specified host:port and prevents duplicate instances.

Parameters:

host (str) – Host address to bind to (default: 127.0.0.1 for localhost only)
port (int) – Port number to listen on (default: 8765)
idle_timeout (int) – Seconds of inactivity before auto-shutdown (0 = disabled)

Raises:

RuntimeError – If port is already in use

Parameters:

host (str) – Host address to bind to (default: '127.0.0.1' for localhost only)
port (int) – Port number to listen on (default: 8765)
idle_timeout (int) – Seconds of inactivity before auto-shutdown (default: 0 = disabled)

Raises:

RuntimeError – If port is already in use

Example:

from lynguine.server import run_server

# Start server programmatically
run_server(host='127.0.0.1', port=8765, idle_timeout=300)

Server Endpoints

The server provides the following HTTP/REST API endpoints:

GET /api/health

Returns server health status.

Response:

{
  "status": "ok"
}

GET /api/ping

Tests server connectivity.

Response:

{
  "message": "pong"
}

GET or POST /api/status

Returns detailed server diagnostics.

Response:

{
  "status": "ok",
  "server": "lynguine-server",
  "version": "0.2.0",
  "pid": 12345,
  "uptime_seconds": 125.3,
  "memory": {
    "rss_mb": 117.5,
    "percent": 1.2
  },
  "cpu_percent": 0.5,
  "idle_timeout": {
    "enabled": true,
    "timeout_seconds": 300,
    "idle_seconds": 45.2,
    "remaining_seconds": 254.8
  },
  "endpoints": [
    "GET  /api/health",
    "GET  /api/ping",
    "GET  /api/status",
    "POST /api/read_data",
    "POST /api/write_data",
    "POST /api/compute"
  ]
}

POST /api/read_data

Reads data via lynguine.

Request:

{
  "interface_file": "config.yml",
  "directory": ".",
  "interface_field": null,
  "data_source": null
}

Or with direct data source:

{
  "data_source": {
    "type": "fake",
    "nrows": 10,
    "cols": ["name", "email"]
  }
}

Response:

{
  "status": "success",
  "data": {
    "records": [...],
    "shape": [10, 2]
  }
}

POST /api/write_data

Writes data via lynguine.

Request:

{
  "data": {
    "records": [...],
    "columns": ["name", "age"]
  },
  "output": {
    "type": "csv",
    "filename": "output.csv"
  }
}

Response:

{
  "status": "success",
  "message": "Wrote 10 records to output.csv"
}

POST /api/compute

Runs compute operations (placeholder for compute framework integration).

Request:

{
  "operation": "test_compute",
  "data": {
    "records": [...]
  },
  "params": {
    "param1": "value1"
  }
}

Response:

{
  "status": "success",
  "operation": "test_compute",
  "message": "Compute operation completed"
}

Utility Functions

lynguine.server.check_server_running(host, port)[source]

Check if a lynguine server is already running on the specified host:port

This checks both: 1. If the port is in use (socket check) 2. If a lynguine server lockfile exists

Parameters:

host (str) – Host address to check
port (int) – Port number to check

Returns:

Tuple of (is_running: bool, type: str) where type is ‘lynguine’, ‘other’, or ‘none’

Return type:

tuple[bool, str]

Parameters:

host (str) – Server host address
port (int) – Server port number

Returns:

Tuple of (is_running: bool, server_type: str)

Return type:

tuple[bool, str]

Example:

from lynguine.server import check_server_running

is_running, server_type = check_server_running('127.0.0.1', 8765)
if is_running:
    if server_type == 'lynguine':
        print("Lynguine server is running")
    else:
        print("Another application is using the port")

Error Handling

The client automatically handles the following errors with retry logic:

Connection Errors

requests.ConnectionError: Server not reachable
requests.Timeout: Request timed out
Behavior: Retry with exponential backoff

Server Errors (5xx)

HTTP 500-599 status codes
Behavior: Retry with exponential backoff

Client Errors (4xx)

HTTP 400-499 status codes (e.g., bad request, not found)
Behavior: Immediate failure, no retry

Example with error handling:

from lynguine.client import ServerClient
import requests

client = ServerClient(auto_start=True, max_retries=3)

try:
    df = client.read_data(interface_file='config.yml')
except requests.HTTPError as e:
    # 4xx error - bad request
    print(f"Client error: {e.response.status_code}")
except RuntimeError as e:
    # Server not available after retries
    print(f"Server unavailable: {e}")
finally:
    client.close()

Performance Considerations

Connection Pooling

The client uses requests.Session() for connection pooling, which reuses TCP connections for better performance.

Timeout Configuration

The timeout parameter controls how long to wait for a response:

Too short: May cause premature timeouts on slow operations
Too long: May delay error detection
Recommended: 30-60 seconds for most use cases

Retry Strategy

Exponential backoff with base delay:

Attempt 1: Immediate
Attempt 2: retry_delay * 2^0 = 1s (default)
Attempt 3: retry_delay * 2^1 = 2s
Attempt 4: retry_delay * 2^2 = 4s

Total delay for 3 retries with 1s base: ~7s

API Reference

Client API

ServerClient

Methods

ping()

health_check()

read_data()

close()

Convenience Function

Server API

Starting the Server

Server Endpoints

Utility Functions

Error Handling

Connection Errors

Server Errors (5xx)

Client Errors (4xx)

Performance Considerations

Connection Pooling

Timeout Configuration

Retry Strategy

See Also