Type and documentation improvements to JSON-LD API

rdflib/plugins/shared/jsonld/context.py

@@ -5,14 +5,8 @@
 # https://github.com/RDFLib/rdflib-jsonld/blob/feature/json-ld-1.1/rdflib_jsonld/context.py
 from __future__ import annotations
 
-from collections import namedtuple
 from collections.abc import Collection, Generator
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Optional,
-    Union,
-)
+from typing import TYPE_CHECKING, Any, NamedTuple, Optional, Union
 from urllib.parse import urljoin, urlsplit
 
 from rdflib.namespace import RDF
@@ -73,27 +67,45 @@ class Defined(int):
 
 
 class Context:
+    """
+    A JSON-LD context, which contains term definitions
+    """
+
+    _base: str | None
+    _alias: dict[str, list[str]]
+    _lookup: dict[tuple[str, Any, Defined | str, bool], Term]
+    _prefixes: dict[str, Any]
+    _context_cache: dict[str, Any]
+
+    version: float
+    language: str | None
+    doc_base: str | None
+    vocab: str | None
+    active: bool
+    propagate: bool
+    terms: dict[str, Any]
+    parent: Context | None
+
     def __init__(
         self,
         source: _ContextSourceType = None,
         base: str | None = None,
         version: float | None = 1.1,
     ):
-        self.version: float = version or 1.1
+        self.version = version or 1.1
         self.language = None
-        self.vocab: str | None = None
-        self._base: str | None
+        self.vocab = None
         self.base = base
         self.doc_base = base
-        self.terms: dict[str, Any] = {}
+        self.terms = {}
         # _alias maps NODE_KEY to list of aliases
-        self._alias: dict[str, list[str]] = {}
-        self._lookup: dict[tuple[str, Any, Defined | str, bool], Term] = {}
-        self._prefixes: dict[str, Any] = {}
+        self._alias = {}
+        self._lookup = {}
+        self._prefixes = {}
         self.active = False
-        self.parent: Context | None = None
+        self.parent = None
         self.propagate = True
-        self._context_cache: dict[str, Any] = {}
+        self._context_cache = {}
         if source:
             self.load(source)
 
@@ -668,9 +680,35 @@ def to_dict(self) -> dict[str, Any]:
         return r
 
 
-Term = namedtuple(
-    "Term",
-    "id, name, type, container, index, language, reverse, context," "prefix, protected",
-)
-
-Term.__new__.__defaults__ = (UNDEF, UNDEF, UNDEF, UNDEF, False, UNDEF, False, False)
+class Term(NamedTuple):
+    """
+    Describes how a JSON key should be interpreted when parsed as RDF
+    """
+
+    #: The IRI or CURIE of the term.
+    id: str
+    #: The name of the term, ie an alias for the id.
+    name: str
+    #: The type of the term, such as @id, @json, @none or @vocab
+    type: Defined | str = UNDEF
+    #: The container type, such as @graph, @id, @index, @language, @list, @set or @type,
+    container: Collection[Any] | str | Defined = UNDEF
+    #: A predicate IRI that should be used to interpret keys of this object,
+    #: when used alongside `@container: @index`.
+    #: See https://www.w3.org/TR/json-ld11/#property-based-data-indexing
+    index: str | Defined | None = None
+    #: The language to be used for values of this term
+    language: str | Defined | None = UNDEF
+    #: Indicates that this term is a reverse property, so subject and object are swapped.
+    #: https://www.w3.org/TR/json-ld11/#reverse-properties
+    reverse: bool = False
+    #: A scoped context used inside values that use this term.
+    #: See https://www.w3.org/TR/json-ld11/#scoped-contexts
+    context: Any = UNDEF
+    #: If true, indicates that this should be used during compaction.
+    #: If false, indicates that this term cannot be used in compaction.
+    #: See https://www.w3.org/TR/json-ld11/#compact-iris
+    prefix: bool | None = None
+    #: If true, marks the term as protected, meaning it cannot be overridden by a subcontext.
+    #: See https://www.w3.org/TR/json-ld11/#protected-term-definitions
+    protected: bool = False