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

load_flync_model(flync_model: FLYNCBaseModel, file_path: Path | str = '')

Load a FLYNCModel into the workspace.

This is a placeholder implementation that stores the model for later use.

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.

has_object(id: ObjectId) → bool

Checks if a specific key exists within a dictionary of objects.

Args:

id (ObjectId):

Identifier of the semantic object.

Returns:

bool:

True if the key is found, False otherwise.

list_objects() → list[ObjectId]

Return a list of all ObjectIds present in the workspace.

Returns:

list[ObjectId]:

List of object identifiers.

get_definition(object_id: ObjectId, field_name: str) → ObjectId | None

Resolve and return definition identifiers for a given field reference.

Args:

object_id (ObjectId):

Identifier of the semantic object.

field_name (str)

The field name of referencing object

Returns:

ObjectId

A list of object identifiers that match the resolved reference criteria. The list may be empty if no definitions are found or if the field has no valid reference metadata.

get_references_of(object_id: ObjectId) → list[ObjectId]

Return all ObjectIds that reference the given object.

Iterates over every semantic object in the workspace and checks whether any of its fields are defined by the same model as the target object. For each matching field, the concrete path to that field is collected via find_path_from_field.

Args:

object_id (ObjectId):

The id of the object whose references should be found.

Returns:

list[ObjectId]:

A list of ObjectIds representing all fields across the workspace that reference the given object.

find_path_from_field(object_id: ObjectId, refs: list[ObjectId], semantic_obj: SemanticObject, field: str, info: FieldInfo)

Resolve the concrete ObjectId path for a field and append it to refs.

Tries to build the path as <semantic_obj.id>.<field>, falling back to <semantic_obj.id>.<info.alias> when the first candidate is not present in the workspace. Raises if neither candidate exists.

Args:

object_id (ObjectId):

The id of the target object being referenced (used in the error message when the path cannot be resolved).

refs (list[ObjectId]):

Accumulator list to which the resolved path is appended.

semantic_obj (SemanticObject):

The semantic object that owns the field being inspected.

field (str):

The field name on semantic_obj’s model.

info:

The Pydantic FieldInfo for the field, used to access the field alias as a fallback path segment.

Raises:

ValueError:

If neither the field name nor its alias resolves to a known object in the workspace.

get_semantic_object_from_model(model: FLYNCBaseModel) → SemanticObject | None

Find and return the semantic object that corresponds to a validated Flync object.

Args:

model (FLYNCBaseModel):

Validated Flync model.

Returns:

SemanticObject | None:

Optional semantic object that corresponds to Flync object.

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, list_objects_mode: ListObjectsMode = <ListObjectsMode.INDEX|NAME: 3>)

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.

get_field_name_from_alias(model: type[BaseModel], alias: str)

Resolve a field name from its alias in a Pydantic model.

Args:

model (type[BaseModel]): The Pydantic model class to inspect. alias (str): The alias of the field to look up.

Returns:

str: The actual field name corresponding to the given alias.

If no field with the alias exists, the alias itself is returned.

is_union(tp) → bool

Determine whether a given type annotation represents a Union type.

class Factory

Bases: object

Factory class for managing and generating model-specific factory instances.

class FLYNCFactory

Bases: ModelFactory[FLYNCBaseModel]

Specialized factory class for creating instances of FLYNCBaseModel subclasses.

classmethod get_provider_map()

Map types to callables which accept no arguments and return a random value of the given type.

Notes:

• This method is distinct to allow overriding.

Returns:

a dictionary mapping types to callables.

classmethod build(**kwargs)

Build an instance of the factory’s __model__

Parameters:

• factory_use_construct – A boolean that determines whether validations will be made when instantiating the model. This is supported only for pydantic models.

• kwargs – Any kwargs. If field_meta names are set in kwargs, their values will be used.

Returns:

An instance of type T.

class ExternalConnectionFactory

Bases: FLYNCFactory

Factory for ExternalConnection model.

classmethod build(**kwargs)

Build an instance of the factory’s __model__

Parameters:

• factory_use_construct – A boolean that determines whether validations will be made when instantiating the model. This is supported only for pydantic models.

• kwargs – Any kwargs. If field_meta names are set in kwargs, their values will be used.

Returns:

An instance of type T.

class BASET1Factory

Bases: FLYNCFactory

Factory for BASET1 model.

classmethod build(**kwargs)

Build an instance of the factory’s __model__

Parameters:

• factory_use_construct – A boolean that determines whether validations will be made when instantiating the model. This is supported only for pydantic models.

• kwargs – Any kwargs. If field_meta names are set in kwargs, their values will be used.

Returns:

An instance of type T.

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

generate_external_node(node: str | type[FLYNCBaseModel], node_path: Path | str, workspace_config: WorkspaceConfiguration | None = None, **override_values)

Generate external node.

generate_node(ws: FLYNCWorkspace, node_paths: list[str] = [], **override_values)

Generate node.