From 95974b8f0758abebd2b9524d5b66d491da86fcdd Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 21 Jul 2024 15:34:43 +0200 Subject: [PATCH] Some more doc-strings. --- pyVHDLModel/DesignUnit.py | 26 ++++++++++++++++++---- pyVHDLModel/Exception.py | 45 ++++++++++++++++++++++----------------- pyVHDLModel/Type.py | 1 + 3 files changed, 48 insertions(+), 24 deletions(-) diff --git a/pyVHDLModel/DesignUnit.py b/pyVHDLModel/DesignUnit.py index 4bcf19a4a..6a909c7df 100644 --- a/pyVHDLModel/DesignUnit.py +++ b/pyVHDLModel/DesignUnit.py @@ -65,12 +65,23 @@ class Reference(ModelEntity): _symbols: List[Symbol] def __init__(self, symbols: Iterable[Symbol], parent: ModelEntity = None) -> None: + """ + Initializes a reference by taking a list of symbols and a parent reference. + + :param symbols: A list of symbols this reference references to. + :param parent: Reference to the logical parent in the model hierarchy. + """ super().__init__(parent) self._symbols = [s for s in symbols] @readonly def Symbols(self) -> List[Symbol]: + """ + Read-only property to access the symbols this reference references to (:attr:`_symbols`). + + :returns: A list of symbols. + """ return self._symbols @@ -83,11 +94,16 @@ class LibraryClause(Reference): .. code-block:: VHDL - library ieee; + library std, ieee; """ @readonly def Symbols(self) -> List[LibraryReferenceSymbol]: + """ + Read-only property to access the symbols this library clause references to (:attr:`_symbols`). + + :returns: A list of library reference symbols. + """ return self._symbols @@ -100,13 +116,12 @@ class UseClause(Reference): .. code-block:: VHDL - use ieee.numeric_std.all; + use std.text_io.all, ieee.numeric_std.all; """ @export class ContextReference(Reference): - # TODO: rename to ContextClause? """ Represents a context reference. @@ -129,7 +144,9 @@ class ContextReference(Reference): @export class DesignUnitWithContextMixin(metaclass=ExtendedType, mixin=True): - pass + """ + A mixin-class for all design units with a context. + """ @export @@ -176,6 +193,7 @@ def __init__(self, identifier: str, contextItems: Nullable[Iterable[ContextUnion :param identifier: Identifier (name) of the design unit. :param contextItems: A sequence of library, use or context clauses. :param documentation: Associated documentation of the design unit. + :param parent: Reference to the logical parent in the model hierarchy. """ super().__init__(parent) NamedEntityMixin.__init__(self, identifier) diff --git a/pyVHDLModel/Exception.py b/pyVHDLModel/Exception.py index 36cd8d4e0..a46cea51d 100644 --- a/pyVHDLModel/Exception.py +++ b/pyVHDLModel/Exception.py @@ -63,7 +63,7 @@ class LibraryExistsInDesignError(VHDLModelException): """ This exception is raised, when the library is already existing in the design. - Message: :pycode:`f"Library '{library.Identifier}' already exists in design."` + Message: :pycode:`f"Library '{library._identifier}' already exists in design."` """ _library: 'Library' @@ -74,11 +74,16 @@ def __init__(self, library: 'Library') -> None: :param library: The library that already exists in the design. """ - super().__init__(f"Library '{library.Identifier}' already exists in design.") + super().__init__(f"Library '{library._identifier}' already exists in design.") self._library = library @readonly def Library(self) -> 'Library': + """ + Read-only property to access the duplicate library (:attr:`_library`). + + :returns: Duplicate library (by name). + """ return self._library @@ -87,7 +92,7 @@ class LibraryRegisteredToForeignDesignError(VHDLModelException): """ This exception is raised, when the library is already registered to a foreign design. - Message: :pycode:`f"Library '{library.Identifier}' already registered in design '{library.Parent}'."` + Message: :pycode:`f"Library '{library._identifier}' already registered in design '{library.Parent}'."` """ _library: 'Library' @@ -98,7 +103,7 @@ def __init__(self, library: 'Library') -> None: :param library: The library that is already registered to another design. """ - super().__init__(f"Library '{library.Identifier}' already registered in design '{library.Parent}'.") + super().__init__(f"Library '{library._identifier}' already registered in design '{library.Parent}'.") self._library = library @readonly @@ -111,7 +116,7 @@ class LibraryNotRegisteredError(VHDLModelException): """ This exception is raised, when the library is not registered in the design. - Message: :pycode:`f"Library '{library.Identifier}' is not registered in the design."` + Message: :pycode:`f"Library '{library._identifier}' is not registered in the design."` """ _library: 'Library' @@ -122,7 +127,7 @@ def __init__(self, library: 'Library') -> None: :param library: The library that isn't registered in the design. """ - super().__init__(f"Library '{library.Identifier}' is not registered in the design.") + super().__init__(f"Library '{library._identifier}' is not registered in the design.") self._library = library @readonly @@ -135,7 +140,7 @@ class EntityExistsInLibraryError(VHDLModelException): """ This exception is raised, when the entity already existing in the library. - Message: :pycode:`f"Entity '{entity.Identifier}' already exists in library '{library.Identifier}'."` + Message: :pycode:`f"Entity '{entity._identifier}' already exists in library '{library._identifier}'."` """ _library: 'Library' @@ -148,7 +153,7 @@ def __init__(self, entity: 'Entity', library: 'Library') -> None: :param entity: The entity that already exists in the library. :param library: The library that already contains the entity. """ - super().__init__(f"Entity '{entity.Identifier}' already exists in library '{library.Identifier}'.") + super().__init__(f"Entity '{entity._identifier}' already exists in library '{library._identifier}'.") self._library = library self._entity = entity @@ -166,7 +171,7 @@ class ArchitectureExistsInLibraryError(VHDLModelException): """ This exception is raised, when the architecture already existing in the library. - Message: :pycode:`f"Architecture '{architecture.Identifier}' for entity '{entity.Identifier}' already exists in library '{library.Identifier}'."` + Message: :pycode:`f"Architecture '{architecture._identifier}' for entity '{entity._identifier}' already exists in library '{library._identifier}'."` """ _library: 'Library' @@ -181,7 +186,7 @@ def __init__(self, architecture: 'Architecture', entity: 'Entity', library: 'Lib :param entity: The entity the architecture refers to, which already exists in the library. :param library: The library that already contains the architecture. """ - super().__init__(f"Architecture '{architecture.Identifier}' for entity '{entity.Identifier}' already exists in library '{library.Identifier}'.") + super().__init__(f"Architecture '{architecture._identifier}' for entity '{entity._identifier}' already exists in library '{library._identifier}'.") self._library = library self._entity = entity self._architecture = architecture @@ -204,7 +209,7 @@ class PackageExistsInLibraryError(VHDLModelException): """ This exception is raised, when the package already existing in the library. - Message: :pycode:`f"Package '{package.Identifier}' already exists in library '{library.Identifier}'."` + Message: :pycode:`f"Package '{package._identifier}' already exists in library '{library._identifier}'."` """ _library: 'Library' @@ -217,7 +222,7 @@ def __init__(self, package: 'Package', library: 'Library') -> None: :param package: The package that already exists in the library. :param library: The library that already contains the package. """ - super().__init__(f"Package '{package.Identifier}' already exists in library '{library.Identifier}'.") + super().__init__(f"Package '{package._identifier}' already exists in library '{library._identifier}'.") self._library = library self._package = package @@ -235,7 +240,7 @@ class PackageBodyExistsError(VHDLModelException): """ This exception is raised, when the package body already existing in the library. - Message: :pycode:`f"Package body '{packageBody.Identifier}' already exists in library '{library.Identifier}'."` + Message: :pycode:`f"Package body '{packageBody._identifier}' already exists in library '{library._identifier}'."` """ _library: 'Library' @@ -248,7 +253,7 @@ def __init__(self, packageBody: 'PackageBody', library: 'Library') -> None: :param packageBody: The package body that already exists in the library. :param library: The library that already contains the package body. """ - super().__init__(f"Package body '{packageBody.Identifier}' already exists in library '{library.Identifier}'.") + super().__init__(f"Package body '{packageBody._identifier}' already exists in library '{library._identifier}'.") self._library = library self._packageBody = packageBody @@ -266,7 +271,7 @@ class ConfigurationExistsInLibraryError(VHDLModelException): """ This exception is raised, when the configuration already existing in the library. - Message: :pycode:`f"Configuration '{configuration.Identifier}' already exists in library '{library.Identifier}'."` + Message: :pycode:`f"Configuration '{configuration._identifier}' already exists in library '{library._identifier}'."` """ _library: 'Library' @@ -279,7 +284,7 @@ def __init__(self, configuration: 'Configuration', library: 'Library') -> None: :param configuration: The configuration that already exists in the library. :param library: The library that already contains the configuration. """ - super().__init__(f"Configuration '{configuration.Identifier}' already exists in library '{library.Identifier}'.") + super().__init__(f"Configuration '{configuration._identifier}' already exists in library '{library._identifier}'.") self._library = library self._configuration = configuration @@ -297,7 +302,7 @@ class ContextExistsInLibraryError(VHDLModelException): """ This exception is raised, when the context already existing in the library. - Message: :pycode:`f"Context '{context.Identifier}' already exists in library '{library.Identifier}'."` + Message: :pycode:`f"Context '{context._identifier}' already exists in library '{library._identifier}'."` """ _library: 'Library' @@ -310,7 +315,7 @@ def __init__(self, context: 'Context', library: 'Library') -> None: :param context: The context that already exists in the library. :param library: The library that already contains the context. """ - super().__init__(f"Context '{context.Identifier}' already exists in library '{library.Identifier}'.") + super().__init__(f"Context '{context._identifier}' already exists in library '{library._identifier}'.") self._library = library self._context = context @@ -328,7 +333,7 @@ class ReferencedLibraryNotExistingError(VHDLModelException): """ This exception is raised, when a library is referenced by a `library clause`, but doesn't exist in the design. - Message: :pycode:`f"Library '{librarySymbol.Name.Identifier}' referenced by library clause of context '{context.Identifier}' doesn't exist in design."` + Message: :pycode:`f"Library '{librarySymbol.Name._identifier}' referenced by library clause of context '{context._identifier}' doesn't exist in design."` """ _librarySymbol: Symbol @@ -341,7 +346,7 @@ def __init__(self, context: 'Context', librarySymbol: Symbol) -> None: :param context: The context that already exists in the library. :param librarySymbol: The library that already contains the context. """ - super().__init__(f"Library '{librarySymbol.Name.Identifier}' referenced by library clause of context '{context.Identifier}' doesn't exist in design.") + super().__init__(f"Library '{librarySymbol.Name._identifier}' referenced by library clause of context '{context._identifier}' doesn't exist in design.") self._librarySymbol = librarySymbol self._context = context diff --git a/pyVHDLModel/Type.py b/pyVHDLModel/Type.py index bacd45d2a..fde065b22 100644 --- a/pyVHDLModel/Type.py +++ b/pyVHDLModel/Type.py @@ -57,6 +57,7 @@ def __init__(self, identifier: str, documentation: Nullable[str] = None, parent: Initializes underlying ``BaseType``. :param identifier: Name of the type. + :param parent: Reference to the logical parent in the model hierarchy. """ super().__init__(parent) NamedEntityMixin.__init__(self, identifier)