add docstrings to the .pyi

Pylance finds these and displays them

autosar_data.pyi

@@ -1,3 +1,22 @@
+"""
+Provides functionality to read, modify and write Autosar arxml files,
+both separately and in projects consisting of multiple files.
+
+Classes:
+
+- ArxmlFile
+- AutosarModel
+- AutosarVersion
+- Element
+- ElementType
+- ValidSubElementInfo
+
+Variables:
+
+- __version__
+
+"""
+
 from .autosar_data import *
 from typing import Dict, List, FrozenSet, Literal, TypeAlias, Tuple, Union
 
@@ -10,50 +29,107 @@ ElementContent: TypeAlias = Union[Element, CharacterData]
 VersionSpecification: TypeAlias = Union[AutosarVersion, List[AutosarVersion]]
 
 class ArxmlFile:
+ """
+ Represents a file that is part of an AutosarModel
+ """
  def __repr__(self) -> str: ...
  def __str__(self) -> str: ...
  filename: str
+ """filename of the arxml file. Must be unique within the model."""
  version: AutosarVersion
- def check_version_compatibility(self, version: AutosarVersion) -> List[IncompatibleItemError]: ...
+ """Autosar version of the file"""
+ def check_version_compatibility(self, version: AutosarVersion) -> List[IncompatibleItemError]:
+ """
+ check if the elements in the file would be compatible with the given target version.
+ 
+ returns a list of compatibility errors, each of which is an IncompatibleElementError, IncompatibleAttributeError or IncompatibleAttributeValueError
+ """
+ ...
  model: AutosarModel
+ """the autosar data model which this file is part of"""
  elements_dfs: ArxmlFileElementsDfsIterator
- def serialize(self) -> str: ...
+ """dfs iterator over all elements in this file"""
+ def serialize(self) -> str:
+ """serialize the the file to a string. This string can be loaded as valid arxml if is written to disk."""
+ ...
  xml_standalone: bool
+ """contains the xml standalone attribute (if any) in the xml file header"""
 
 class ArxmlFileElementsDfsIterator:
+ """
+ A depth first search iterator over all elements contained in the file that created this iterator
+ """
  def __iter__(self) -> ArxmlFileElementsDfsIterator: ...
  def __next__(self) -> Tuple[int, Element]: ...
 
 class Attribute:
+ """
+ An attribute on an element
+ """
  attrname: AttributeName
+ """name of this attribute"""
  content: CharacterData
+ """content of the attribute - this data can be free-form text, a pre-defined enum value (str), or very rarely a float or int"""
 
 class AttributeIterator:
+ """
+ Iterates over all attributes on an element
+ """
  def __iter__(self) -> AttributeIterator: ...
  def __next__(self) -> Attribute : ...
 
 class AutosarDataError(Exception):
  pass
 
 class AutosarModel:
+ """
+ Autosar data model. It contains all elements.
+ """
  def __repr__(self) -> str: ...
  def __str__(self) -> str: ...
- def create_file(self, filename: str, version: AutosarVersion) -> ArxmlFile: ...
- def load_buffer(self, buffer: str, filename: str, strict: bool) -> Tuple[ArxmlFile, List[str]]: ...
- def load_file(self, filename: str, strict: bool) -> Tuple[ArxmlFile, List[str]]: ...
- def remove_file(self, arxmlfile: ArxmlFile) -> None: ...
- def serialize_files(self) -> Dict[str, str]: ...
- def write(self) -> None: ...
+ def create_file(self, filename: str, version: AutosarVersion) -> ArxmlFile:
+ """create a new file in the model"""
+ ...
+ def load_buffer(self, buffer: str, filename: str, strict: bool) -> Tuple[ArxmlFile, List[str]]:
+ """load a buffer (string) as arxml"""
+ ...
+ def load_file(self, filename: str, strict: bool) -> Tuple[ArxmlFile, List[str]]:
+ """load a file as arxml"""
+ ...
+ def remove_file(self, arxmlfile: ArxmlFile) -> None:
+ """remove a file from the model. Any elements belonging exclusively to that file will also be removed."""
+ ...
+ def serialize_files(self) -> Dict[str, str]:
+ """serialize all files individually, to generate a dict(filename, serialized content),"""
+ ...
+ def write(self) -> None:
+ """write all files in the model to disk"""
+ ...
  files: List[ArxmlFile]
+ """a list of ArxmlFile objects containing all files in the model"""
  root_element: Element
- def get_element_by_path(self, autosar_path: str) -> Element: ...
+ """The root element of the model, <AUTOSAR>"""
+ def get_element_by_path(self, autosar_path: str) -> Element:
+ """get an identifiable element in the model by its Autosar path"""
+ ...
  elements_dfs: ElementsDfsIterator
- def sort(self) -> None: ...
+ """depth first dearch iterator over all elements in the model, regardless of their association with a file"""
+ def sort(self) -> None:
+ """sort the entire model in place. Takes all ordering constraints into account."""
+ ...
  identifiable_elements: List[str]
- def get_references_to(self, target_path: str) -> List[Element]: ...
- def check_references(self) -> List[Element]: ...
+ """List of all paths of identifiable elements in the model"""
+ def get_references_to(self, target_path: str) -> List[Element]:
+ """get all reference elements which refer to the given Autosar path"""
+ ...
+ def check_references(self) -> List[Element]:
+ """check all references in the model and return a list of elements containing invalid references"""
+ ...
 
 class AutosarVersion:
+ """
+ A version of the Autosar standard
+ """
  def __new__(cls, verstring: str) -> AutosarVersion: ...
  # this is the stupid result of method used by PyO3 to translate Rust enums
  Autosar_4_0_1: AutosarVersion
@@ -77,102 +153,226 @@ class AutosarVersion:
  Autosar_00051: AutosarVersion
 
 class ContentType:
+ """
+ The content type of an element
+ """
  # this is the stupid result of method used by PyO3 to translate Rust enums
  Elements: ContentType
  CharacterData: ContentType
  Mixed: ContentType
 
 class Element:
+ """
+ An element in the Autosar data model
+ """
  def __repr__(self) -> str: ...
  def __str__(self) -> str: ...
  def serialize(self) -> str: ...
  parent: Element
+ """reference to the parent of this element"""
  element_name: ElementName
+ """ElementName of this element, e.g. AUTOSAR or AR-PACKAGE"""
  element_type: ElementType
+ """Reference to the element type of the element in the specification"""
  item_name: str
+ """item name of an identifiable element, or None for elements which are not identifiable.
+
+ Setting this value renames the element and updates all references to it.
+ """
  is_identifiable: bool
+ """true if the element is identifiable, false otherwise"""
  is_reference: bool
+ """true if the element can contain a reference to another element"""
  path: str
+ """the full autosar path of an identifiable element"""
  model: AutosarModel
+ """reference to the model containing this element"""
  content_type: ContentType
- def create_sub_element(self, element_name: ElementName) -> Element: ...
- def create_sub_element_at(self, element_name: ElementName, position: int) -> Element: ...
- def create_named_sub_element(self, element_name: ElementName, item_name: str) -> Element: ...
- def create_named_sub_element_at(self, element_name: ElementName, item_name: str, position: int) -> Element: ...
- def create_copied_sub_element(self, other: Element) -> Element: ...
- def create_copied_sub_element_at(self, other: Element, position: int) -> Element: ...
- def move_element_here(self, move_element: Element) -> Element: ...
- def move_element_here_at(self, move_element: Element, position: int) -> Element: ...
- def remove_sub_element(self, element: Element) -> None: ...
+ """content type of the element: character data (<X>some text</X>), elements (<X><Y></Y></X>), or Mixed"""
+ def create_sub_element(self, element_name: ElementName) -> Element:
+ """create a sub element under this element with the given ElementName"""
+ ...
+ def create_sub_element_at(self, element_name: ElementName, position: int) -> Element:
+ """create a sub element under this element with the given ElementName at a specific position"""
+ ...
+ def create_named_sub_element(self, element_name: ElementName, item_name: str) -> Element:
+ """create a named sub element under this element with the given ElementName"""
+ ...
+ def create_named_sub_element_at(self, element_name: ElementName, item_name: str, position: int) -> Element:
+ """create a named sub element under this element with the given ElementName at a specific position"""
+ ...
+ def create_copied_sub_element(self, other: Element) -> Element:
+ """create a copy of some other element (with all of its children) as a child of this element"""
+ ...
+ def create_copied_sub_element_at(self, other: Element, position: int) -> Element:
+ """create a copy of some other element (with all of its children) as a child of this element at the given position"""
+ ...
+ def move_element_here(self, move_element: Element) -> Element:
+ """move an element from somewhere else in this model or from another model to become a child element"""
+ ...
+ def move_element_here_at(self, move_element: Element, position: int) -> Element:
+ """move an element from somewhere else in this model or from another model to become a child element at the given position"""
+ ...
+ def remove_sub_element(self, element: Element) -> None:
+ """remove a sub element and all of its content"""
+ ...
  reference_target: Element
- def get_sub_element(self, name_str: str) -> Element: ...
- def get_sub_element_at(self, position: int) -> Element: ...
+ """returns the target of the reference, if the element contains a reference"""
+ def get_sub_element(self, name_str: str) -> Element:
+ """get a sub element by its element name. If there are several then this returns the first of them"""
+ ...
+ def get_sub_element_at(self, position: int) -> Element:
+ """get an element by its position among the content of this element"""
+ ...
  position: int
+ """the position of this element in the content of its parent"""
  sub_elements: ElementsIterator
+ """an iterator over all sub elements in the content of this element. It skips character data content items"""
  elements_dfs: ElementsDfsIterator
+ """dpeth first search iterator for this element and all of its sub elements"""
  character_data: CharacterData
- def remove_character_data(self) -> None: ...
- def insert_character_content_item(self, chardata: str, position: int) -> None: ...
- def remove_character_content_item(self, position: int) -> None: ...
+ """character content of this element, if any. For elements with ContentType=Element, or empty elements this is None"""
+ def remove_character_data(self) -> None:
+ """remove the character data"""
+ ...
+ def insert_character_content_item(self, chardata: str, position: int) -> None:
+ """for elements with ElementType mixed, this allows character data to be inserted at any point in the content of this element"""
+ ...
+ def remove_character_content_item(self, position: int) -> None:
+ """remove one character content item from the given position"""
+ ...
  content_item_count: int
+ """number of content items (character data and/or sub elements)"""
  content: ElementContentIterator
+ """iterator over all content of this element"""
  attributes: AttributeIterator
- def attribute_value(self, attrname: AttributeName) -> CharacterData: ...
- def set_attribute(self, attrname: AttributeName, chardata: CharacterData) -> None: ...
- def set_attribute_string(self, attrname: AttributeName, value: str) -> None: ...
- def remove_attribute(self, attrname: AttributeName) -> None: ...
- def sort(self) -> None: ...
- def list_valid_sub_elements(self) -> List[ValidSubElementInfo]: ...
+ """iterator over all attributes of this element"""
+ def attribute_value(self, attrname: AttributeName) -> CharacterData:
+ """get the attribute value of a specific attribute. Returns None if that attribute is not set"""
+ ...
+ def set_attribute(self, attrname: AttributeName, chardata: CharacterData) -> None:
+ """set the given attribute to the provided value. If the attribute is valid for this element it will be created or modified as needed."""
+ ...
+ def set_attribute_string(self, attrname: AttributeName, value: str) -> None:
+ """like set_attribute, but the input will be converted to the target data type as needed"""
+ ...
+ def remove_attribute(self, attrname: AttributeName) -> None:
+ """remove an attribute from the element"""
+ ...
+ def sort(self) -> None:
+ """sort this element and all of its sub elements"""
+ ...
+ def list_valid_sub_elements(self) -> List[ValidSubElementInfo]:
+ """provide information about valid sub elements as a list of ValidSubElementInfo"""
+ ...
  file_membership: Tuple[bool, FrozenSet[ArxmlFile]]
- def add_to_file(self, file: ArxmlFile) -> None: ...
- def remove_from_file(self, file: ArxmlFile) -> None: ...
+ """file membership information: the tuple (is_local, set(ArxmlFile)) tells if there is a restriction to file membership attached to this element, and which files the element is part of"""
+ def add_to_file(self, file: ArxmlFile) -> None:
+ """add the element to a file. if necessary all parent elements of this element also become part of the file"""
+ ...
+ def remove_from_file(self, file: ArxmlFile) -> None:
+ """remove this element from a file. Does not affect parent elements. When an element is no longer part of any file it is deleted."""
+ ...
  xml_path: str
+ """a path listing all xml elements from the root of the model to the element. This is intended for display. e.g. in error messages"""
 
 class ElementContentIterator:
+ """
+ Iterates over all content in an element
+
+ Content items an be sub elements or character data
+ """
  def __iter__(self) -> ElementContentIterator: ...
  def __next__(self) -> ElementContent: ...
 
 class ElementType:
+ """
+ Type of an Element in the specification
+ """
  is_named: bool
+ """Elements of this type must have a SHORT-NAME"""
  is_ref: bool
+ """elements of this type must contain an autosar path in their character data, and have a DEST attribute"""
  is_ordered: bool
+ """ordered elements may not be sorted, since the sub element order is semantically meaningful"""
  splittable: List[AutosarVersion]
- def splittable_in(self, version: AutosarVersion) -> bool: ...
- def reference_dest_value(self, target: ElementType) -> EnumItem: ...
- def find_sub_element(self, target_name: ElementName, version: VersionSpecification) -> ElementType: ...
+ """a list of AutosarVersions in which this element is splittable"""
+ def splittable_in(self, version: AutosarVersion) -> bool:
+ """is this element splittable in a particular AutosarVersion"""
+ ...
+ def reference_dest_value(self, target: ElementType) -> EnumItem:
+ """helper to determine the correct value for the DEST attribute when setting a reference"""
+ ...
+ def find_sub_element(self, target_name: ElementName, version: VersionSpecification) -> ElementType:
+ """find the ElementType of the named sub element in the specification of this ElementType"""
+ ...
 
 class ElementsDfsIterator:
+ """
+ Dpeth first search iterator starting at the element which created the iterator
+ """
  def __iter__(self) -> ElementsDfsIterator: ...
  def __next__(self) -> Tuple[int, Element]: ...
 
 class ElementsIterator:
+ """
+ Iterator over all sub elements of an element
+ """
  def __iter__(self) -> ElementsIterator: ...
  def __next__(self) -> Element: ...
 
 class IncompatibleAttributeError:
+ """
+ Information about an attribute that is incompatible with a given target version
+ """
  def __repr__(self) -> str: ...
  def __str__(self) -> str: ...
  element: Element
+ """Element which contains the incompatible attribute"""
  attribute: AttributeName
+ """Incompatible attribute"""
  allowed_versions: List[AutosarVersion]
+ """list of versions in which the attribute is permitted on this element"""
 
 class IncompatibleAttributeValueError:
+ """
+ Information about an attribute value that is incompatible with a given target version
+ """
  def __repr__(self) -> str: ...
  def __str__(self) -> str: ...
  element: Element
+ """Element which contains the incompatible attribute value"""
  attribute: AttributeName
+ """Attribute which contains the invalid value"""
  attribute_value: str
+ """The incompatible attribute value"""
  allowed_versions: List[AutosarVersion]
+ """list of versions in which the attribute value is permitted on this attribute"""
 
 class IncompatibleElementError:
+ """
+ Information about an element that is incompatible with a given target version
+ """
  def __repr__(self) -> str: ...
  def __str__(self) -> str: ...
  element: Element
+ """incompatible element"""
  allowed_versions: List[AutosarVersion]
+ """list of versions in which this element is compatible"""
 
 class ValidSubElementInfo:
+ """
+ Details about a particular sub element
+ """
  element_name: str
+ """name of the potential sub element"""
  is_named: bool
+ """is the sub element named, i.e. does it need to be created with create_named_sub_element"""
  is_allowed: bool
+ """is the sub element currently allowed, given the existing content of the element. Note that some sub elements are mutually exclusive"""
 
-version: str
+__version__: str
+"""
+Version of the running autosar_data module.
+It contains a semver string of the form 'x.y.z'
+"""