flync.sdk¶

This page is a full reference of the SDK for developers and contributors to FLYNC.

FLYNC Workspace¶

class FLYNCWorkspace(name: str, workspace_path: Path | str = '', configuration: WorkspaceConfiguration | None = None)¶

Bases: object

Workspace class managing documents, objects, and diagnostics.

This class provides methods to ingest documents, run analysis, and expose semantic and source APIs for use by the SDK and language server.

Attributes:

name (str): Name of the workspace.

documents (Dict[str, Document]): Mapping of document URIs to Document objects.

objects (Dict[ObjectId, SemanticObject]): Semantic objects indexed by ObjectId.

sources (Dict[ObjectId, SourceRef]): Source references indexed by ObjectId.

dependencies (Dict[ObjectId, Set[ObjectId]]): Dependency graph.

reverse_deps (Dict[ObjectId, Set[ObjectId]]): Reverse dependency graph.

_diagnostics (list[Diagnostic]): Collected diagnostics.

property load_errors¶

Flattened list of all validation errors across all loaded documents.

Returns:: list[ErrorDetails]: All per-document errors concatenated into a single list.

classmethod load_model(flync_model: FLYNCModel, workspace_name: str | None = 'generated_workspace', file_path: Path | str = '', workspace_config: WorkspaceConfiguration | None = None) → FLYNCWorkspace¶

loads a workspace object from a FLYNC Object.

Args:

flync_model (str): the FLYNC object from which the workspace will be created.

workspace_name (str): The name of the workspace.

file_path (str | Path): The path of the workspace files.

Returns: FLYNCWorkspace

classmethod safe_load_workspace(workspace_name: str, workspace_path: Path | str, workspace_config: WorkspaceConfiguration | None = None) → FLYNCWorkspace¶

loads a workspace object from a location of the Yaml Configuration.

In case this fails, the workspace will still be created, but with an empty model.

Args:

workspace_name (str): The name of the workspace.

workspace_path (str | Path): The path of the workspace files.

Returns: FLYNCWorkspace

classmethod load_workspace(workspace_name: str, workspace_path: Path | str, workspace_config: WorkspaceConfiguration | None = None) → FLYNCWorkspace¶

loads a workspace object from a location of the Yaml Configuration.

Args:

workspace_name (str): The name of the workspace.

workspace_path (str | Path): The path of the workspace files.

Returns: FLYNCWorkspace

generate_configs(uri: Path | str | None = None)¶

Save the workspace to the given path.

Creates the output directory (if it does not exist) and writes a simple representation of the workspace. If a FLYNCModel has been loaded via load_flync_model, it attempts to serialize the model to JSON.

Args:

uri (str | Path | None): Optional argument to save specific file: instead of the entire workspace.

Returns: None

is_path_supported(path: Path | str)¶

Return whether a path is a directory or a recognised FLYNC file.

Args:: path (PathType): The path to check.
Returns:: bool: True if the path is a directory or a FLYNC file.

is_flync_file(path: Path | str)¶

Return whether a path has a recognised FLYNC file extension.

Args:: path (PathType): The path to check.
Returns:: bool: True if the path’s combined suffixes are in allowed_extensions.

name_form_file(file_name: str | Path) → str¶

Strip all recognised FLYNC file extensions from a filename.

Iterates over every extension in allowed_extensions and removes it as a suffix, leaving the bare stem. If a pathlib.Path is passed, only its name component is used.

Args:: file_name (str | Path): The filename or path to strip.
Returns:: str: The filename with all FLYNC extensions removed (e.g. "my_ecu.flync.yaml" → "my_ecu").

fill_path_from_object(model_object: FLYNCBaseModel, object_path: str) → str¶

Replace placeholder segments in an object path with concrete keys.

Traverses the workspace’s root model following object_path, substituting [] with the actual list index and {} with the actual dict key when model_object is found.

Args:

model_object (FLYNCBaseModel): The model instance to locate. object_path (str): Dot-separated path containing [] or {}

placeholders.

Returns:

str: The resolved dot-separated path with concrete index/key: values.

document_id_from_path(doc_path: Path) → str¶

Return the workspace-relative string identifier for a document path.

Args:: doc_path (Path): An absolute path to a document file.
Returns:: str: The path relative to the workspace root, as a string.

static new_object_path(current_path: str, new_object_name: int | str) → str¶

Extend a dot-separated object path with a new segment.

Args:: current_path (str): The existing dot-separated path. new_object_name (int | str): The segment to append.
Returns:: str: The extended path string.

update_objects_path(current_paths: list[str], new_object_name: str) → list[str]¶

Extend every path in a list with a new segment.

Args:: current_paths (list[str]): Existing dot-separated paths. new_object_name (str): The segment to append to each path.
Returns:: list[str]: New list of extended path strings.

add_list_item_object_path(item_name, current_object_paths, idx)¶

Build the object path(s) for a single list item.

Depending on list_objects_mode, the item may be registered under its numeric index, its name, or both:

INDEX: appends the zero-based integer index as a path segment.
NAME: appends item_name as an additional path segment when the name is non-empty. For external (folder-based) lists the name comes from the file/directory stem; for inline lists it comes from the model’s name attribute.

Both flags are active by default, so a list item is accessible under two IDs simultaneously (e.g. controllers.0 and controllers.my_ctrl).

Args:

item_name (str | None): Name of the list item, or None /: empty string when the item has no name.

current_object_paths (list[str]): Parent path(s) to extend. idx (int): Zero-based position of the item in the list.

Returns:

list[str]: New list of object paths for this item.

get_object(id: ObjectId) → SemanticObject¶

Retrieve a semantic object by its ObjectId.

Args:

id (ObjectId):: Identifier of the semantic object.

Returns:

SemanticObject:: The requested semantic object.

list_objects() → list[ObjectId]¶

Return a list of all ObjectIds present in the workspace.

Returns:

list[ObjectId]:: List of object identifiers.

get_source(id: ObjectId) → SourceRef¶

Retrieve the source reference for a given ObjectId.

Args:

id (ObjectId):: Identifier of the object.

Returns:

SourceRef:: The source reference associated with the object.

objects_at(uri: str, line: int, character: int) → list[ObjectId]¶

Return the list of ObjectIds located at the specified position in a document.

Args:

uri (str):: Document URI.
line (int):: 1-based line number, consistent with the Position values stored during YAML parsing.
character (int):: 1-based character offset within the line.

Returns:

list[ObjectId]:: List of object identifiers at the given position.

Configuration module for FLYNC SDK.

Provides WorkspaceConfiguration and ListObjectsMode, which control how a FLYNCWorkspace is loaded, validated, and serialized.

class ListObjectsMode(*values)¶

Bases: IntFlag

Flags controlling how list items are keyed in the workspace object map.

Flags can be combined with |. The default is INDEX | NAME.

Attributes:

INDEX: Register each list item under its zero-based integer index: (e.g. controllers.0).
NAME: Register each list item under its name — the file/directory stem: for folder-based lists, or the model’s name attribute for inline YAML lists. Items without a name are skipped.

class WorkspaceConfiguration(flync_file_extension: str = '.flync.yaml', allowed_extensions: set[str] = <factory>, exclude_unset: bool = True, root_model: Type[FLYNCBaseModel] = <class 'flync.model.flync_model.FLYNCModel'>, map_objects: bool = False)¶

Bases: object

Configuration object for the FLYNC SDK workspace.

Attributes:

flync_file_extension (str): The primary file extension used when: writing FLYNC configuration files. Defaults to ".flync.yaml".
allowed_extensions (set[str]): Set of file extensions recognized as: FLYNC files. Defaults to {".flync.yaml", ".flync.yml"}.
exclude_unset (bool): When True, fields that were not explicitly: set on a model are omitted from serialized output.
root_model (Type[FLYNCBaseModel]): The root Pydantic model class used: to validate workspace contents.
map_objects (bool): tells the workspace if it should map all objects: in the workspace (reduces performance).
list_objects_mode (ListObjectsMode): Controls how objects are keyed: when listed. Defaults to INDEX | NAME.

root_model¶: alias of FLYNCModel

classmethod create_from_config(existing_config: WorkspaceConfiguration, **configs) → WorkspaceConfiguration¶

Create a new configuration by overriding fields on an existing one.

Converts existing_config to a dict, applies configs on top, then constructs and returns a new WorkspaceConfiguration.

Args:

existing_config (WorkspaceConfiguration): The base configuration: to copy from.

**configs: Field names and new values to override.

Returns:

WorkspaceConfiguration: A new instance with the overrides applied.

Document¶

class Document(uri: Path | str, text: str, needs_compose: bool)¶

Bases: object

Represents a YAML document with parsing capabilities.

Attributes:

uri (str): The unique identifier for the document.

text (str): The raw YAML content.

ast (Any | None): The parsed abstract syntax tree, or None if not parsed.

compose_ast (Any | None): The composed ruamel.yaml AST used for source-position tracking, or None if not parsed.

parse()¶

Parse the YAML text into an abstract syntax tree.

Sets ast via yaml.load and compose_ast via yaml.compose, both derived from text.

Returns: None

update_text(text: str)¶

Update the document’s text and re-parse it.

Args:: text (str): The new YAML content.

Returns: None

Utils & Helpers¶

Field utility helpers for the FLYNC SDK.

Provides functions for extracting metadata and display names from Pydantic model fields.

get_metadata(meta: Iterable[object], cls: type[T]) → T | None¶

Return the first metadata object of the specified type.

Args:: meta: An iterable of metadata objects. cls: The class type to search for.
Returns:: An instance of cls if found; otherwise, None.

get_name(named_object: T, attr_name: str, fallback_name: str | None = None) → str¶

Retrieve a display name for an object.

Looks up attr_name on named_object. Falls back to fallback_name if the attribute is absent or falsy, and finally to the class name if that is also absent.

Args:: named_object: The object whose name should be retrieved. attr_name: The attribute name to look up on the object. fallback_name: Optional fallback value when the attribute is missing.
Returns:: The resolved display name string.

dump_flync_workspace(flync_model: FLYNCModel, output_path: str | Path, workspace_name: str | None, workspace_config: WorkspaceConfiguration | None = None) → None¶

Generate a FLYNC workspace from a FLYNCModel object.

Args:

flync_model (FLYNCModel): The: FLYNC model to generate the workspace from.
output_path (str | pathlib.Path): The path where the workspace: will be created.

workspace_name (str | None): Optional name for the workspace. workspace_config (WorkspaceConfiguration | None): Optional

workspace configuration. Uses defaults if None.

Returns:

None