v0.6.0

Author: Paebbels

doc/Catalog.rst

@@ -0,0 +1,15 @@
+.. _CATALOG:
+
+Catalog
+#######
+
+.. attention::
+
+   🚧 This implementation is work in progress. 🚧
+
+.. code-block:: python
+
+   from pyEDAA.IPXACT.Catalog import Catalog
+
+   filePath = Path("Catalog.xml")
+   catalog = Catalog(filePath, parse=True)

doc/Component.rst

@@ -0,0 +1,23 @@
+.. _COMPONENT:
+
+Component
+#########
+
+.. attention::
+
+   🚧 This implementation is work in progress. 🚧
+
+.. code-block:: python
+
+   from pyEDAA.IPXACT.Component import Component
+
+   filePath = Path("Catalog.xml")
+   catalog = Component(filePath, parse=True)
+
+
+Features
+========
+
+* Extract filesets
+
+  * Extract files

doc/Design.rst

@@ -0,0 +1,15 @@
+.. _DESIGN:
+
+Design
+######
+
+.. attention::
+
+   🚧 This implementation is work in progress. 🚧
+
+.. code-block:: python
+
+   from pyEDAA.IPXACT.Design import Design
+
+   filePath = Path("Catalog.xml")
+   catalog = Design(filePath, parse=True)

doc/FurtherResources.rst

@@ -0,0 +1,39 @@
+.. _INTRO:
+
+Introduction
+############
+
+*pyEDAA.IPXACT* provides a Document Object Model (DOM) for reading and writing IP-XACT XML files.
+
+.. attention::
+
+   As IP-XACT defines a gigantic data model, only a portion of this data model is currently implemented. The
+   implementation focuses on the most valuable parts. Contributions are welcome.
+
+
+.. _INTRO/History:
+
+History
+=======
+
+The beginnings of this EDA² layer were released as :pypi:`pyIPXACT`. The package was then integrated into the EDA² layer
+family and renamed to pyEDAA.IPXACT. The embedded XML schema definitions are provided by
+`Accellera <https://www.accellera.org/>`__. As these schema files might be interesting for other users too, they have
+been extracted and provided in a standalone repository called :gh:`edaa-org/IPXACT-Schema`.
+
+
+.. _INTRO/Further:
+
+Further Resources
+=================
+
+* :pypi:`peakrdl-ipxact`
+
+  * :pypi:`ralbot-ipxact` was renamed to *peakrdl-ipxact*.
+
+* :pypi:`ipxact2systemverilog`
+* :gh:`iDoka/ipxact-cli-tools`
+* :gh:`olofk/ipyxact`
+* :gh:`kactus2`
+
+  * `research.tuni.fi/system-on-chip/tool <https://research.tuni.fi/system-on-chip/tools/>`__

doc/Introduction.rst

@@ -227,8 +227,10 @@ License
    :caption: Main Documentation
    :hidden:
 
-   Tutorial
-   FurtherResources
+   Introduction
+   Catalog
+   Component
+   Design
 
 .. raw:: latex
 

doc/index.rst

@@ -32,19 +32,19 @@
 from pathlib  import Path
 from sys      import version_info
 from textwrap import dedent
-from typing   import List, Dict
+from typing import List, Dict, Optional as Nullable, ClassVar
 
-from lxml.etree              import XMLParser, XML, XMLSchema, ElementTree, QName
+from lxml.etree import QName, _Element
 
 from pyTooling.Decorators    import export, readonly
 from pyTooling.Common        import getFullyQualifiedName
 
-from pyEDAA.IPXACT           import RootElement, VLNV, IPXACTException, __URI_MAP__, __DEFAULT_SCHEMA__, IPXACTSchema, Element
+from pyEDAA.IPXACT           import NamedElement, RootElement, VLNV, IPXACTException, __DEFAULT_SCHEMA__, IPXACTSchema, Element
 from pyEDAA.IPXACT.Component import Component
 
 
 @export
-class IpxactFile(Element):
+class IpxactFile(NamedElement):
 	"""Represents a IP-XACT file."""
 
 	_name:        str    #: Name
@@ -135,7 +135,8 @@ def ToXml(self, indent: int = 0, schema: IPXACTSchema = __DEFAULT_SCHEMA__):
 class Catalog(RootElement):
 	"""Represents an IP-XACT catalog."""
 
-	_description:            str
+	_rootTagName:            ClassVar[str] = "catalog"
+
 	_abstractionDefinitions: List
 	_abstractors:            List
 	_busInterfaces:          List
@@ -145,10 +146,13 @@ class Catalog(RootElement):
 	_designs:                List
 	_generatorChains:        List
 
-	def __init__(self, vlnv: VLNV, description: str):
-		super().__init__(vlnv)
-
-		self._description =             description
+	def __init__(
+		self,
+		catalogFile: Nullable[Path] = None,
+		parse: bool = False,
+		vlnv: Nullable[VLNV] = None,
+		description: Nullable[str] = None
+	):
 		self._abstractionDefinitions =  []
 		self._abstractors =             []
 		self._busInterfaces =           []
@@ -158,73 +162,27 @@ def __init__(self, vlnv: VLNV, description: str):
 		self._designs =                 []
 		self._generatorChains =         []
 
-	@classmethod
-	def FromFile(cls, filePath : Path):
-		"""Constructs an instance of ``Catalog`` from a file."""
-
-		if not filePath.exists():
-			raise IPXACTException(f"IPXACT file '{filePath}' not found.") from FileNotFoundError(str(filePath))
-
-		try:
-			with filePath.open("rb") as fileHandle:
-				content = fileHandle.read()
-		except OSError as ex:
-			raise IPXACTException(f"Couldn't open '{filePath}'.") from ex
-
-		xmlParser = XMLParser(remove_blank_text=True, encoding="utf-8")
-		root =      XML(content, parser=xmlParser, base_url=filePath.resolve().as_uri())  # - relative paths are not supported
-		rootTag =   QName(root.tag)
-
-		if rootTag.localname != "catalog":
-			raise IPXACTException("The input IP-XACT file is not a catalog file.")
-
-		namespacePrefix = root.prefix
-		namespaceURI = root.nsmap[namespacePrefix]
-		if namespaceURI in __URI_MAP__:
-			ipxactSchema = __URI_MAP__[namespaceURI]
+		super().__init__(catalogFile, parse, vlnv, description)
+
+	def Parse(self, element: _Element) -> None:
+		elementLocalname = QName(element).localname
+		if elementLocalname == "catalogs":
+			for ipxactFileElement in element:
+				self.AddItem(IpxactFile.FromXml(ipxactFileElement))
+		elif elementLocalname == "abstractionDefinitions":
+			pass
+		elif elementLocalname == "components":
+			pass
+		elif elementLocalname == "abstractors":
+			pass
+		elif elementLocalname == "designs":
+			pass
+		elif elementLocalname == "designConfigurations":
+			pass
+		elif elementLocalname == "generatorChains":
+			pass
 		else:
-			raise IPXACTException(f"The input IP-XACT file uses an unsupported namespace: '{namespaceURI}'.")
-
-		try:
-			with ipxactSchema.LocalPath.open("rb") as fileHandle:
-				schema = fileHandle.read()
-		except OSError as ex:
-			raise IPXACTException(f"Couldn't open IP-XACT schema '{ipxactSchema.LocalPath}' for {namespacePrefix} ({namespaceURI}).") from ex
-
-		schemaRoot = XML(schema, parser=xmlParser, base_url=ipxactSchema.LocalPath.as_uri())
-		schemaTree =  ElementTree(schemaRoot)
-		xmlSchema =   XMLSchema(schemaTree)
-
-		try:
-			xmlSchema.assertValid(root)
-		except Exception as ex:
-			raise IPXACTException("The input IP-XACT file is not valid.") from ex
-
-		items = []
-		for rootElements in root:
-			element = QName(rootElements)
-			if element.localname == "vendor":
-				vendor = rootElements.text
-			elif element.localname == "library":
-				library = rootElements.text
-			elif element.localname == "name":
-				name = rootElements.text
-			elif element.localname == "version":
-				version = rootElements.text
-			elif element.localname == "description":
-				description = rootElements.text
-			elif element.localname == "catalogs":
-				for ipxactFileElement in rootElements:
-					items.append(IpxactFile.FromXml(ipxactFileElement))
-			else:
-				raise IPXACTException(f"Unsupported tag '{element.localname}' at root-level.")
-
-		vlnv = VLNV(vendor=vendor, library=library, name=name, version=version)
-		catalog = cls(vlnv, description=description)
-		for item in items:
-			catalog.AddItem(item)
-
-		return catalog
+			raise IPXACTException(f"Unsupported tag '{elementLocalname}' at root-level.")
 
 	def AddItem(self, item) -> None:
 		if isinstance(item, IpxactFile):