wip

whitequark · whitequark · commit 579dccf51ab7 · 2024-02-15T19:55:06.000Z
diff --git a/amaranth/lib/meta.py b/amaranth/lib/meta.py
@@ -1,8 +1,4 @@
 from abc import abstractmethod, ABCMeta
-from collections.abc import Mapping
-from urllib.parse import urlparse
-
-import jsonschema
 
 
 __all__ = ["Annotation"]
@@ -13,72 +9,76 @@ class Annotation(metaclass=ABCMeta):
 
     A container for metadata that can be retrieved from a :class:`~amaranth.lib.wiring.Signature`
     object. Annotation instances can be exported as JSON objects, whose structure is defined using
-    the `JSON Schema <https://json-schema.org>`_ language.
-
-    Schema URLs
-    -----------
-
-    An ``Annotation`` schema must have a ``"$id"`` property, which holds an URL that serves as its
-    unique identifier. The suggested format of this URL is:
-
-        <protocol>://<domain>/schema/<package>/<version>/<path>.json
-
-    where:
-      * ``<domain>`` is a domain name registered to the person or entity defining the annotation;
-      * ``<package>`` is the name of the Python package providing the ``Annotation`` subclass;
-      * ``<version>`` is the version of the aforementioned package;
-      * ``<path>`` is a non-empty string specific to the annotation.
-
-    Attributes
-    ----------
-    schema : :class`Mapping`
-        Annotation schema.
+    the `JSON Schema`_ language.
     """
 
-    schema = property(abstractmethod(lambda: None)) # :nocov:
+    #: :class:`dict`: Schema of this annotation, expressed in the `JSON Schema`_ language.
+    #:
+    #: Subclasses of :class:`Annotation` must implement this class attribute.
+    schema = {}
 
     def __init_subclass__(cls, **kwargs):
         super().__init_subclass__(**kwargs)
-        if not isinstance(cls.schema, Mapping):
+
+        if not isinstance(cls.schema, dict):
             raise TypeError(f"Annotation schema must be a dict, not {cls.schema!r}")
 
         # The '$id' keyword is optional in JSON schemas, but we require it.
         if "$id" not in cls.schema:
             raise ValueError(f"'$id' keyword is missing from Annotation schema: {cls.schema}")
-        jsonschema.Draft202012Validator.check_schema(cls.schema)
+
+        try:
+            import jsonschema
+            jsonschema.Draft202012Validator.check_schema(cls.schema)
+        except ImportError:
+            # Amaranth was installed in some weird way and doesn't have jsonschema installed,
+            # despite it being a mandatory dependency. The schema will eventually get checked
+            # by the CI, so ignore the error here.
+            pass # :nocov:
 
     @property
     @abstractmethod
     def origin(self):
-        """Annotation origin.
+        """The Python object described by this :class:`Annotation` instance.
 
-        The Python object described by this :class:`Annotation` instance.
+        Subclasses of :class:`Annotation` must implement this property.
         """
         pass # :nocov:
 
     @abstractmethod
     def as_json(self):
-        """Translate to JSON.
+        """Convert to a JSON representation.
+
+        Subclasses of :class:`Annotation` must implement this property.
+
+        The JSON representation returned by this method must adhere to :data:`schema` and pass
+        validation by :meth:`validate`.
 
         Returns
         -------
-        :class:`Mapping`
-            A JSON representation of this :class:`Annotation` instance.
+        :class:`dict`
+            JSON representation of this annotation, expressed in Python primitive types
+            (:class:`dict`, :class:`list`, :class:`str`, :class:`int`, :class:`bool`).
         """
         pass # :nocov:
 
     @classmethod
     def validate(cls, instance):
-        """Validate a JSON object.
+        """Validate a JSON representation against :attr:`schema`.
 
-        Parameters
-        ----------
-        instance : :class:`Mapping`
-            The JSON object to validate.
+        Arguments
+        ---------
+        instance : :class:`dict`
+            The JSON representation to validate, either previously returned by :meth:`as_json`
+            or retrieved from an external source.
 
         Raises
         ------
         :exc:`jsonschema.exceptions.ValidationError`
-            If `instance` doesn't comply with :attr:`Annotation.schema`.
+            If :py:`instance` doesn't comply with :attr:`Annotation.schema`.
         """
+        import jsonschema
         jsonschema.validate(instance, schema=cls.schema)
+
+    def __repr__(self):
+        return f"<{type(self).__module__}.{type(self).__qualname__} for {self.origin!r}>"
diff --git a/amaranth/lib/wiring.py b/amaranth/lib/wiring.py
@@ -672,7 +672,7 @@ class Signature(metaclass=SignatureMeta):
     An interface object is a Python object that has a :py:`signature` attribute containing
     a :class:`Signature` object, as well as an attribute for every member of its signature.
     Signatures and interface objects are tightly linked: an interface object can be created out
-    of a signature, and the signature is used when :func:`connect` ing two interface objects
+    of a signature, and the signature is used when :func:`connect`\\ ing two interface objects
     together. See the :ref:`introduction to interfaces <wiring-intro1>` for a more detailed
     explanation of why this is useful.
 
@@ -720,7 +720,7 @@ def annotations(self, obj, /):
 
         Returns
         -------
-        iterator of :class:`meta.Annotation`
+        iterable of :class:`Annotation`
         """
         return ()
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -2,10 +2,11 @@
 sys.path.insert(0, os.path.abspath("."))
 
 import time
-import amaranth
+from importlib.metadata import version as package_version
+
 
 project = "Amaranth language & toolchain"
-version = amaranth.__version__.replace(".editable", "")
+version = package_version('amaranth').replace(".editable", "")
 release = version.split("+")[0]
 copyright = time.strftime("2020—%Y, Amaranth project contributors")
 
@@ -24,7 +25,10 @@
 
 root_doc = "cover"
 
-intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "jsonschema": (f"https://python-jsonschema.readthedocs.io/en/v{package_version('jsonschema')}/", None),
+}
 
 todo_include_todos = True
 
diff --git a/docs/stdlib.rst b/docs/stdlib.rst
@@ -3,7 +3,7 @@ Standard library
 
 The :mod:`amaranth.lib` module, also known as the standard library, provides modules that falls into one of the three categories:
 
-1. Modules that will used by essentially all idiomatic Amaranth code, and are necessary for interoperability. This includes :mod:`amaranth.lib.enum` (enumerations), :mod:`amaranth.lib.data` (data structures), and :mod:`amaranth.lib.wiring` (interfaces and components).
+1. Modules that will used by essentially all idiomatic Amaranth code, or which are necessary for interoperability. This includes :mod:`amaranth.lib.enum` (enumerations), :mod:`amaranth.lib.data` (data structures), :mod:`amaranth.lib.wiring` (interfaces and components), and :mod:`amaranth.lib.meta` (metadata).
 2. Modules that abstract common functionality whose implementation differs between hardware platforms. This includes :mod:`amaranth.lib.cdc`.
 3. Modules that have essentially one correct implementation and are of broad utility in digital designs. This includes :mod:`amaranth.lib.coding`, :mod:`amaranth.lib.fifo`, and :mod:`amaranth.lib.crc`.
 
@@ -17,6 +17,7 @@ The Amaranth standard library is separate from the Amaranth language: everything
    stdlib/enum
    stdlib/data
    stdlib/wiring
+   stdlib/meta
    stdlib/cdc
    stdlib/coding
    stdlib/fifo
diff --git a/docs/stdlib/meta.rst b/docs/stdlib/meta.rst
@@ -0,0 +1,137 @@
+Metadata
+########
+
+.. py:module:: amaranth.lib.meta
+
+The :mod:`amaranth.lib.meta` module provides a way to annotate objects in an Amaranth design and
+exchange these annotations with external tools in a standardized format.
+
+.. _JSON Schema: https://json-schema.org
+
+.. testsetup::
+
+    from amaranth import *
+    from amaranth.lib import wiring
+    from amaranth.lib.wiring import In, Out
+
+
+Introduction
+------------
+
+Many Amaranth designs stay entirely within the Amaranth ecosystem, using the facilities it provides
+to define, test, and build hardware. In this case, the design is available for exploration using
+Python code, and metadata is not necessary. However, if an Amaranth design needs to fit into
+an existing ecosystem, or, conversely, to integrate components developed for another ecosystem,
+metadata can be used to exchange structured information about the design.
+
+Consider a simple :ref:`component <wiring>`:
+
+.. testcode::
+
+    class Adder(wiring.Component):
+        a: In(unsigned(32))
+        b: In(unsigned(32))
+        o: Out(unsigned(33))
+
+        def elaborate(self, platform):
+            m = Module()
+            m.d.comb += self.o.eq(self.a + self.b)
+            return m
+
+..
+    TODO: link to Verilog backend doc when we have it
+
+While it can be easily converted to Verilog, external tools will find the interface of
+the resulting module opaque unless they parse its Verilog source (a difficult and unrewarding task),
+or are provided with a description of it. Components can describe their signature with JSON-based
+metadata:
+
+.. doctest::
+
+    >>> adder = Adder()
+    >>> adder.metadata # doctest: +ELLIPSIS
+    <amaranth.lib.wiring.ComponentMetadata for <Adder object at ...>>
+    >>> adder.metadata.as_json() # doctest: +SKIP
+    {
+        'interface': {
+            'members': {
+                'a': {
+                    'type': 'port',
+                    'name': 'a',
+                    'dir': 'in',
+                    'width': 32,
+                    'signed': False,
+                    'reset': '0'
+                },
+                'b': {
+                    'type': 'port',
+                    'name': 'b',
+                    'dir': 'in',
+                    'width': 32,
+                    'signed': False,
+                    'reset': '0'
+                },
+                'o': {
+                    'type': 'port',
+                    'name': 'o',
+                    'dir': 'out',
+                    'width': 33,
+                    'signed': False,
+                    'reset': '0'
+                }
+            },
+            'annotations': {}
+        }
+    }
+
+.. testcode::
+    :hidden:
+
+    # The way doctest requires this object to be formatted is truly hideous, even with +NORMALIZE_WHITESPACE.
+    assert adder.metadata.as_json() == {'interface': {'members': {'a': {'type': 'port', 'name': 'a', 'dir': 'in', 'width': 32, 'signed': False, 'reset': '0'}, 'b': {'type': 'port', 'name': 'b', 'dir': 'in', 'width': 32, 'signed': False, 'reset': '0'}, 'o': {'type': 'port', 'name': 'o', 'dir': 'out', 'width': 33, 'signed': False, 'reset': '0'}}, 'annotations': {}}}
+
+
+All metadata in Amaranth must adhere to a schema in the `JSON Schema`_ language, which is integral
+to its definition, and can be used to validate the generated JSON:
+
+.. doctest::
+
+    >>> wiring.ComponentMetadata.validate(adder.metadata.as_json())
+
+
+Defining annotations
+--------------------
+
+.. todo:: Write this.
+
+
+Publishing schemas
+------------------
+
+.. todo:: Write this
+
+An ``Annotation`` schema must have a ``"$id"`` property, which holds an URL that serves as its
+unique identifier. The suggested format of this URL is:
+
+    <protocol>://<domain>/schema/<package>/<version>/<path>.json
+
+where:
+    * ``<domain>`` is a domain name registered to the person or entity defining the annotation;
+    * ``<package>`` is the name of the Python package providing the ``Annotation`` subclass;
+    * ``<version>`` is the version of the aforementioned package;
+    * ``<path>`` is a non-empty string specific to the annotation.
+
+
+Reference
+---------
+
+.. todo::
+
+    Write this.
+
+.. autoclass:: Annotation
+    :no-members:
+    :members: validate, origin, as_json
+
+    .. autoattribute:: schema
+        :annotation: = { "$id": "...", ... }
diff --git a/docs/stdlib/wiring.rst b/docs/stdlib/wiring.rst
@@ -1,3 +1,5 @@
+.. _wiring:
+
 Interfaces and connections
 ##########################
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -15,9 +15,9 @@ license = {file = "LICENSE.txt"}
 requires-python = "~=3.8"
 dependencies = [
   "importlib_resources; python_version<'3.9'", # for amaranth._toolchain.yosys
+  "jsonschema~=4.20.0", # for amaranth.lib.meta
   "pyvcd>=0.2.2,<0.5", # for amaranth.sim.pysim
   "Jinja2~=3.0", # for amaranth.build
-  "jsonschema~=4.20.0", # for amaranth.lib.meta
 ]
 
 [project.optional-dependencies]

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _wiring:`
	`2`	`+`
`1`	`3`	`Interfaces and connections`
`2`	`4`	`##########################`
`3`	`5`