Python Tool API

Extract tracing tags from Python source files and generate LOBSTER activity or implementation artifacts.

API

from lobster.tools.python.python import PythonToolConfig, lobster_python
lobster_python(config: PythonToolConfig)

Configuration Dataclass

from lobster.tools.python.python import PythonToolConfig, lobster_python

config = PythonToolConfig(
   files=["src"],
   activity=False,
   out="python.lobster",
   single=False,
   only_tagged_functions=False,
   parse_decorator=None,
   parse_versioned_decorator=None,
)

PythonToolConfig fields:

  • files: Sequence[str] - List of files and/or directories. Directories are scanned recursively for .py files.

  • activity: bool - When True, emits activity items instead of implementation items.

  • out: Optional[str] - Output .lobster path. If None, output is written to stdout.

  • single: bool - Disables multiprocessing and parses files sequentially.

  • only_tagged_functions: bool - Keeps only extracted items that have at least one tracing target.

  • parse_decorator: Optional[Tuple[str, str]] - Decorator name plus argument name for deriving trace tags.

  • parse_versioned_decorator: Optional[Tuple[str, str, str]] - Decorator name, tag argument name, and version argument name.

Stable API Function

lobster_python(config: PythonToolConfig) -> None

Runs parsing and writes LOBSTER output according to the provided configuration.

Example

from lobster.tools.python.python import PythonToolConfig, lobster_python

lobster_python(PythonToolConfig(
   files=["src", "tests"],
   out="python_trace.lobster",
   activity=False,
   single=True,
))

Behavioral Notes

  • parse_decorator and parse_versioned_decorator are mutually exclusive.

  • Parse failures in input files are reported to stdout and may produce partial output.

  • Invalid input paths raise ValueError.

Core Goals

  • Parse Python .py files and extract implementation or activity items.

  • Convert inline lobster-trace tags and decorator-provided tags into tracing targets.

  • Support folder-based scanning with optional sequential or multiprocessing execution.

  • Produce a LOBSTER artifact consumable by downstream report tools.

Error Conditions

  • Invalid file or directory input path → ValueError.

  • Invalid decorator configuration (both parse options set) → ValueError.

  • File decode problems while reading sources → UnicodeDecodeError is reported and file is skipped.

  • Python parser syntax errors in source files → parser error is reported and output may be incomplete.