sec_parser.semantic_elements.composite_semantic_element
=======================================================

.. py:module:: sec_parser.semantic_elements.composite_semantic_element


Classes
-------

.. autoapisummary::

   sec_parser.semantic_elements.composite_semantic_element.CompositeSemanticElement


Module Contents
---------------

.. py:class:: CompositeSemanticElement(html_tag: sec_parser.processing_engine.html_tag.HtmlTag, inner_elements: tuple[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, Ellipsis] | None, *, processing_log: sec_parser.processing_engine.processing_log.ProcessingLog | None = None, log_origin: sec_parser.processing_engine.processing_log.LogItemOrigin | None = None)

   Bases: :py:obj:`sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement`


   CompositeSemanticElement acts as a container for other semantic elements,
   especially for cases where a single HTML root tag wraps multiple elements.
   This ensures structural integrity and enables various features like
   semantic segmentation visualization, and debugging by comparison with the
   original document.

   Why is this useful:
   ===================
   1. Some semantic elements, like XBRL tags (<ix>), may wrap multiple semantic
   elements. The container ensures that these relationships are not broken
   during parsing.
   2. Enables the parser to fully reconstruct the original HTML document, which
   opens up possibilities for features like semantic segmentation visualization
   (e.g. recreate the original document but put semi-transparent colored boxes
   on top, based on semantic meaning), serialization of parsed documents into
   an augmented HTML, and debugging by comparing to the original document.


   .. py:attribute:: _inner_elements
      :type:  tuple[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, Ellipsis]
      :value: ()



   .. py:property:: inner_elements
      :type: tuple[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, Ellipsis]



   .. py:method:: create_from_element(source: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, log_origin: sec_parser.processing_engine.processing_log.LogItemOrigin, *, inner_elements: list[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement] | None = None) -> CompositeSemanticElement
      :classmethod:


      Convert the semantic element into another semantic element type.



   .. py:method:: to_dict(*, include_previews: bool = False, include_contents: bool = False) -> dict[str, Any]


   .. py:method:: unwrap_elements(elements: collections.abc.Iterable[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement], *, include_containers: bool | None = None) -> list[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]
      :classmethod:


      Recursively flatten a list of AbstractSemanticElement objects.
      For each CompositeSemanticElement encountered, its inner_elements
      are also recursively flattened. The 'include_containers' parameter controls
      whether the CompositeSemanticElement itself is included in the flattened list.