Namespace

Summary

Package:

pyVHDLModel

Doc-string:

documented

File	Expected	Covered	Uncovered	Coverage
Namespace.py	31	26	5	83.9%

Source

pyVHDLModel/Namespace.pydocumentedundocumentedignoredexcludednot counted

"""
This module contains parts of an abstract document language model for VHDL.

A helper class to implement namespaces and scopes.
"""
...

K = TypeVar("K")
O = TypeVar("O")

class ExtendedKeyError(KeyError):
	"""
	A :exc:`KeyError` reporting which namespaces were searched.

	Raised when a name cannot be resolved. Besides the key (:data:`key`), it carries every namespace
	visited while walking outwards (:data:`searchedNamespaces`).
	"""
	key: str                                   #: The key that was not found.
	searchedNamespaces: tuple[Namespace, ...]  #: The namespaces that were searched for the key.

	def __init__(self, key: str, searchedNamespaces: tuple[Namespace, ...], message: str) -> None:
		"""
		Initializes an extended key error.

		:param key:                The key that was not found.
		:param searchedNamespaces: The namespaces that were searched for the key.
		:param message:            The error message.
		"""
		...

class Namespace(Generic[K, O]):
	"""
	Represents a namespace: the declared items visible in one declarative region.

	Namespaces nest, so a lookup that misses locally continues in the parent namespace
	(:data:`ParentNamespace`). That is what makes an entity's ports visible inside its architecture,
	and lets a process variable hide an outer signal.

	.. seealso::

	   * :class:`Concurrent declaration region <pyVHDLModel.Regions.ConcurrentDeclarationRegionMixin>`
	   * :class:`Sequential declaration region <pyVHDLModel.Regions.SequentialDeclarationRegionMixin>`
	"""
	_name:                   str                  #: The namespace's name.
	_parentNamespace:        Nullable[Namespace]  #: Reference to the enclosing namespace, ``None`` if outermost.
	_subNamespaces:          list[Namespace]      #: List of all nested namespaces, in the order they were linked.
	_elements:               dict[K, O]           #: All elements declared in this namespace, indexed by name.
	_imports:                dict[K, O]           #: All elements imported into this namespace, indexed by name.
	_sharesRegionWithParent: bool                 #: ``True`` if the parent namespace is the same declarative region.

	def __init__(
		self,
		name: str,
		parentNamespace: Nullable[Namespace] = None,
		sharesRegionWithParent: bool = False
	) -> None:
		"""
		Initializes a namespace.

		:param name:                   The namespace's name.
		:param parentNamespace:        Optional, reference to the enclosing namespace, or ``None`` for the outermost one.
		                               Default: ``None``. |br|
		                               This namespace is appended to the parent namespace's sub-namespaces.
		:param sharesRegionWithParent: Optional, ``True`` if the parent namespace is the same declarative region.
		                               Default: ``False``.
		:raises TypeError:             If parameter 'parentNamespace' is not of type :class:`Namespace`.
		"""
		...

	@readonly
	def Name(self) -> str:
		"""
		Read-only property to access the name (:attr:`_name`).

		:returns: The name.
		"""
		...

	@property
	def ParentNamespace(self) -> Nullable[Namespace]:
		"""
		Property to access the parent namespace (:attr:`_parentNamespace`).

		Assigning a namespace links both sides: this namespace leaves the sub-namespaces (:attr:`SubNamespaces`) of its
		previous parent namespace and is appended to the sub-namespaces of the new one. Assigning ``None`` unlinks this
		namespace from its parent namespace. Assigning the current parent namespace changes nothing.

		:returns:          The parent namespace, or ``None`` if this namespace is the outermost one.
		:raises TypeError: If the assigned value is not of type :class:`Namespace`.
		"""
		...

	@ParentNamespace.setter
	def ParentNamespace(self, parentNamespace: Nullable[Namespace]) -> None:
		...

	@readonly
	def SharesRegionWithParent(self) -> bool:
		"""
		Read-only property to access whether this namespace continues its parent's declarative region
		(:attr:`_sharesRegionWithParent`).

		.. hint::

		   An entity and its architecture form one VHDL declarative region, as do a package and its body,
		   even though each owns a namespace. A duplicate declaration is reported across such a link, while
		   a genuinely nested region - a process, a block - hides instead.

		:returns: ``True`` if the parent namespace is the same declarative region.
		"""
		...

	@readonly
	def SubNamespaces(self) -> list[Namespace]:
		"""
		Read-only property to access the sub namespaces (:attr:`_subNamespaces`).

		A sub-namespace is linked by assigning this namespace to its :attr:`ParentNamespace`. Several sub-namespaces may
		share a name, e.g. ``None`` for unlabeled processes.

		:returns: List of sub namespaces, in the order they were linked.
		"""
		...

	def AddElement(self, normalizedIdentifier: K, element: O, overloadable: bool = False) -> None:
		"""
		Add a declared item to this namespace, reporting a duplicate declaration.

		VHDL rejects two declarations sharing an identifier in one declarative region. A region can span
		more than one namespace - an entity and its architecture form one, as do a package and its body -
		so enclosing namespaces are searched too, but only while they share this one's region.

		Overloadable declarations are exempt: several subprograms may share a name as long as their
		signatures differ. Signatures are not compared yet, so two subprograms sharing a name are always
		accepted (see the overload-resolution finding).

		An item imported into a namespace (e.g. by a use clause) is no declaration of that namespace's region: it's kept
		apart (:meth:`AddImport`), so it never clashes with a declaration, and a lookup finds the declaration first.

		:param normalizedIdentifier:           The normalized (lower case) identifier being declared.
		:param element:                        The declared item.
		:param overloadable:                   ``True`` if this declaration may legally share its name.
		:raises UnhandledCriticalWarningError: If the identifier is already declared in the declarative region and no
		                                       :class:`~pyTooling.Warning.WarningCollector` collects the
		                                       :exc:`~pyVHDLModel.Exception.DuplicateDeclarationWarning`.
		"""
		...

	def RemoveElement(self, normalizedIdentifier: K, element: O) -> None:
		"""
		Remove a declared item from this namespace.

		:param normalizedIdentifier: The normalized (lower case) identifier of the declared item.
		:param element:              The declared item.
		:raises NotInNamespaceError: If the identifier isn't declared in this namespace.
		:raises NotInNamespaceError: If the identifier refers to another element, e.g. a duplicate declaration.
		"""
		...

	def AddImport(self, normalizedIdentifier: K, element: O) -> None:
		"""
		Add an item imported by a use clause to this namespace.

		An imported item is declared elsewhere, so it's kept apart from the declarations (:meth:`AddElement`): it never
		clashes with a declaration, and a lookup finds a declaration of the same identifier first. Importing another item
		for the same identifier replaces the imported item.

		:param normalizedIdentifier: The normalized (lower case) identifier of the imported item.
		:param element:              The imported item, e.g. a package or a component.
		"""
		...

	def RemoveImport(self, normalizedIdentifier: K, element: O) -> None:
		"""
		Remove an imported item from this namespace.

		Declarations of the same identifier are kept.

		:param normalizedIdentifier: The normalized (lower case) identifier of the imported item.
		:param element:              The imported item.
		:raises NotInNamespaceError: If the identifier isn't imported into this namespace.
		:raises NotInNamespaceError: If the identifier refers to another imported item.
		"""
		...

	def ClearImports(self) -> None:
		"""
		Remove all imported items from this namespace.

		The declarations (:meth:`Elements`) are kept.
		"""
		...

	@staticmethod
	def _IdentifierOf(element: O, normalizedIdentifier: K) -> str:
		"""
		Return the identifier of an element as declared, for its normalized identifier.

		:param element:              The named element.
		:param normalizedIdentifier: One of the element's normalized (lower case) identifiers.
		:returns:                    The identifier in its declared spelling.
		"""
		...

	def Elements(self) -> dict[K, O]:
		"""
		Return the elements declared in this namespace (:attr:`_elements`).

		:returns: Dictionary of declared elements, indexed by normalized identifier.
		"""
		...

	def Imports(self) -> dict[K, O]:
		"""
		Return the elements imported into this namespace (:attr:`_imports`).

		:returns: Dictionary of imported elements, indexed by normalized identifier.
		"""
		...

	def _LookupElement(self, normalizedIdentifier: K) -> O:
		"""
		Return the element of an identifier in this namespace: the declared element, else the imported element.

		:param normalizedIdentifier: The normalized (lower case) identifier.
		:returns:                    The declared or imported element.
		:raises KeyError:            If the identifier is neither declared nor imported in this namespace.
		"""
		...

	def FindComponent(self, componentSymbol: ComponentInstantiationSymbol) -> Component:
		...

	def FindSubtype(self, subtypeSymbol: Symbol) -> BaseType:
		...

	def FindObject(self, objectSymbol: Symbol) -> Obj:
		...