refactor: AAA

Author: SilverRainZ

docs/_templates/version.rst

@@ -1,5 +1,5 @@
 
-:Date: :version.date.by-year:`📅{{ date }} <{{ date }}>`
+:Date: :version.date+by-year:`📅{{ date }} <{{ date }}>`
 :Download: :tag:`{{ title }}`
 
 {% for line in content %}

docs/changelog.rst

@@ -19,6 +19,8 @@ Change Log
 
    Change log here.
 
+:version.date#by-year:`2024`
+
 Version 2.x
 ===========
 

docs/usage.rst

@@ -145,19 +145,7 @@ Indices
 
 According to sphinx documentation, we use :ref:`sphinx:ref-role` to create reference to object indices, and the index name should prefixed with domain name.
 
-General Index
-~~~~~~~~~~~~~
-
-Index "``domain``-\ ``objtype``" (In this case, it is ``any-cat``) creates reference to object index which grouped by all referenceable field values.
-
-================== ==============
-``:ref:`any-cat``` :ref:`any-cat`
-================== ==============
-
-Field Specific Index
-~~~~~~~~~~~~~~~~~~~~
-
-Index "``domain``-\ ``objtype``.\ ``field``" will be created for all reference Fields (In this case, it is ``any-cat.name``, ``any-cat.id`` and ``any-cat.color``).
+Index "``domain``-\ ``objtype``.\ ``field``" will be created for all referenceable Fields (In this case, it is ``any-cat.name``, ``any-cat.id`` and ``any-cat.color``).
 
 These indices create reference to object index which grouped by specific field values.
 
@@ -166,6 +154,8 @@ These indices create reference to object index which grouped by specific field v
 ``:ref:`any-cat.id```   :ref:`any-cat.id`
 ======================= ===================
 
+.. todo: indexer
+
 .. _writing-template:
 
 Writing Template

src/sphinxnotes/any/domain.py

@@ -18,7 +18,7 @@
 from sphinx.util import logging
 from sphinx.util.nodes import make_refnode
 
-from .schema import Schema, Object
+from .schema import Schema, Object, RefType, Indexer, LiteralIndexer
 from .directives import AnyDirective
 from .roles import AnyRole
 from .indices import AnyIndex
@@ -49,9 +49,9 @@ class AnyDomain(Domain):
     roles: dict[str, RoleFunction] = {}
     #: A list of Index subclasses
     indices: list[type[AnyIndex]] = []
-    #: AnyDomain specific: type -> index class
+    #: AnyDomain specific: reftype -> index class
     _indices_for_reftype: dict[str, type[AnyIndex]] = {}
-    #: AnyDomain specific: type -> Schema instance
+    #: AnyDomain specific: objtype -> Schema instance
     _schemas: dict[str, Schema] = {}
 
     initial_data: dict[str, Any] = {
@@ -120,7 +120,7 @@ def resolve_xref(
         logger.debug('[any] resolveing xref of %s', (typ, target))
 
         reftype = RefType.parse(typ)
-        objtype, objfield, objidx = reftype.objtype, reftype.field, reftype.index
+        objtype, objfield, objidx = reftype.objtype, reftype.field, reftype.indexer
         objids = set()
         if objidx:
             pass  # no need to lookup objds
@@ -142,10 +142,7 @@ def resolve_xref(
         if len(objids) > 1 or objidx is not None:
             # Mulitple objects found or reference index explicitly,
             # create link to indices page.
-            (
-                todocname,
-                anchor,
-            ) = self._get_index_anchor(typ, target)
+            (todocname, anchor) = self._get_index_anchor(typ, target)
             if not has_explicit_title:
                 newtitle = schema.render_ambiguous_reference(title)
             logger.debug(
@@ -181,43 +178,47 @@ def add_schema(cls, schema: Schema) -> None:
         # Add to schemas dict
         cls._schemas[schema.objtype] = schema
 
-        # Generates reftypes for all referenceable fields
-        # For later use when generating roles and indices.
-        reftypes = [str(RefType(schema.objtype, None, None))]
-        for name, field in schema.fields(all=False):
-            if not field.ref:
-                continue
-
-            # Field is unique , use ``:objtype.field:`` to reference.
-            if field.uniq:
-                reftype = str(RefType(schema.objtype, name, None))
-                reftypes.append(reftype)
-                continue
-
-        for name, field in schema.fields(all=False):
-            # Field is not unique, link to index page.
-            for indexer in field.indexers:
-                reftype = str(RefType(schema.objtype, name, indexer.name))
-                reftypes.append(reftype)
-
-                # FIXME: name and content can not be index now
-                index = AnyIndex.derive(schema, name, indexer)
-                cls.indices.append(index)
-                cls._indices_for_reftype[reftype] = index
-
-        for reftype in reftypes:
-            field = RefType.parse(reftype).field
-            # Create role for referencing object by field
-            cls.roles[reftype] = AnyRole.derive(schema, field)(
+        def mkrole(reftype: RefType):
+            """Create and register role for referencing object (by field/index)."""
+            role =  AnyRole(
                 # Emit warning when missing reference (node['refwarn'] = True)
                 warn_dangling=True,
                 # Inner node (contnode) would be replaced in resolve_xref method,
                 # so fix its class.
                 innernodeclass=literal,
             )
+            cls.roles[str(reftype)] = role
+            logger.debug(f'[any] make role {reftype} →  {type(role)}')
+
+        def mkindex(reftype: RefType, indexer: Indexer):
+            """Create and register index."""
+            index = AnyIndex.derive(schema, reftype.field, indexer)
+            cls.indices.append(index)
+            cls._indices_for_reftype[str(reftype)] = index
+            logger.debug(f'[any] make index {reftype} →  {type(index)}')
+
+        # Generates reftypes, roles, indexers for all fields.
+        reftypes = [RefType(schema.objtype)]
+        mkrole(reftypes[0]) # create reference role, FIXME: ambiguous reference
+        for name, field in schema.fields():
+            if field.ref:
+                reftype = RefType(schema.objtype, field=name)
+                reftypes.append(reftype)
+                mkrole(reftype)   # create a role to reference object
+                if len(field.indexers) == 0:
+                    # Create a fallback indexer, for possible ambiguous reference
+                    # (if field is not unique).
+                    mkindex(reftype, LiteralIndexer())
+
+            for indexer in field.indexers:
+                reftype = RefType(schema.objtype, field=name, indexer=indexer.name)
+                reftypes.append(reftype)
+                # Create role and index for reference objects by index.
+                mkrole(reftype)
+                mkindex(reftype, indexer)
 
         # TODO: document
-        cls.object_types[schema.objtype] = ObjType(schema.objtype, *reftypes)
+        cls.object_types[schema.objtype] = ObjType(schema.objtype, *[ str(x) for x in reftypes])
         # Generates directive for creating object.
         cls.directives[schema.objtype] = AnyDirective.derive(schema)
 
@@ -238,42 +239,11 @@ def warn_missing_reference(
     if domain and domain.name != AnyDomain.name:
         return None
 
-    objtype = RefType.parse(node['reftype']).objtype
+    reftype = RefType.parse(node['reftype'])
     target = node['reftarget']
 
-    msg = f'undefined {objtype}: {target}'
-    logger.warning(msg, location=node, type='ref', subtype=objtype)
+    msg = f'undefined reftype {reftype}: {target}'
+    logger.warning(msg, location=node, type='ref', subtype=reftype.objtype)
     return True
 
 
-class RefType(object):
-    """Reference type, used as role name and node['reftype'] and
-    and *typ* argument of :meth:`AnyDomain.resolve_xref` method."""
-
-    #: :attr:`ObjType.lname`
-    objtype: str
-    #: :attr:`.schema.Field.name`
-    field: str | None
-    #: :attr:`.schema.Indexer.name`
-    index: str | None
-
-    def __init__(self, objtype: str, field: str | None, index: str | None):
-        self.objtype = objtype
-        self.field = field
-        self.index = index
-
-    @classmethod
-    def parse(cls, reftype: str):
-        v = reftype.split('.', maxsplit=2)
-        objtype = v[0]
-        field = v[1] if len(v) > 1 else None
-        index = v[2][3:] if len(v) > 2 else None  # skip "by-"
-        return cls(objtype, field, index)
-
-    def __str__(self):
-        s = self.objtype
-        if self.field is not None:
-            s += '.' + self.field
-        if self.index is not None:
-            s += '.' + 'by-' + self.index
-        return s

src/sphinxnotes/any/indices.py

@@ -16,7 +16,7 @@
 from docutils import core, nodes
 from docutils.parsers.rst import roles
 
-from .schema import Schema, Value, Indexer, Category
+from .schema import Schema, Value, Indexer, Category, RefType
 
 logger = logging.getLogger(__name__)
 
@@ -36,23 +36,13 @@ def derive(
         cls, schema: Schema, field: str | None, indexer: Indexer
     ) -> type['AnyIndex']:
         """Generate an AnyIndex child class for indexing object."""
-        # TODO: add Indexer.name
-        if field:
-            typ = f'Any{schema.objtype.title()}{field.title()}IndexBy{indexer.name.title()}'
-            name = schema.objtype + '.' + field + '.by-' + indexer.name  # TODO: RefType
-            localname = f'{schema.objtype.title()} {field.title()} Reference Index by {indexer.name.title()}'
-        else:
-            typ = f'Any{schema.objtype.title()}IndexBy{indexer.name.title()}'
-            name = schema.objtype + '.by-' + indexer.name  # TODO: RefType
-            localname = (
-                f'{schema.objtype.title()} Reference Index by {indexer.name.title()}'
-            )
+        reftype = RefType(schema.objtype, field=field, indexer=indexer.name)
         return type(
-            typ,
+            reftype.index_classname(),
             (cls,),
             {
-                'name': name,
-                'localname': localname,
+                'name': reftype.index_name(),
+                'localname': reftype.index_localname(),
                 'shortname': 'references',
                 'schema': schema,
                 'field': field,

src/sphinxnotes/any/roles.py

@@ -25,11 +25,7 @@ class AnyRole(XRefRole):
     objtype.
     """
 
-    @classmethod
-    def derive(cls, schema: Schema, field: str | None = None) -> type['AnyRole']:
-        """Generate an AnyRole child class for referencing object."""
-        return type(
-            'Any%s%sRole' % (schema.objtype.title(), field.title() if field else ''),
-            (cls,),
-            {},
-        )
+    # NOTE: derive is not necessary for now.
+    # @classmethod
+    # def derive(cls) -> type['AnyRole']:
+    #     pass

src/sphinxnotes/any/schema.py

@@ -354,7 +354,7 @@ class Forms:
     required: bool = False
     form: Form = Forms.PLAIN
     indexers: list[Indexer] = dataclasses.field(
-        default_factory=lambda: [LiteralIndexer()]
+        default_factory=lambda: []
     )
 
     def value_of(self, rawval: str | None) -> Value:
@@ -438,7 +438,7 @@ def __init__(
             else:
                 has_unique = field.uniq
 
-    def fields(self, all=True) -> list[tuple[str, Field]]:
+    def fields(self, exclude_name: bool = False, exclude_content: bool = False) -> list[tuple[str, Field]]:
         """Return all fields of schema, including name and content.
 
         .. note::
@@ -448,9 +448,9 @@ def fields(self, all=True) -> list[tuple[str, Field]]:
         """
 
         fields = list(self.attrs.items())
-        if all and self.content is not None:
+        if not exclude_content and self.content is not None:
             fields.insert(0, (self.CONTENT_KEY, self.content))
-        if all and self.name is not None:
+        if not exclude_name and self.name is not None:
             fields.insert(0, (self.NAME_KEY, self.name))
         return fields
 
@@ -631,3 +631,87 @@ def __eq__(self, other: Any) -> bool:
         if not isinstance(other, Schema):
             return False
         return pickle.dumps(self) == pickle.dumps(other)
+
+class RefType(object):
+    """Reference type, object can be referenced:
+
+    - by type *objtype*
+    - by field *objtype*.*field*
+    - by field index *objtype*.*field*+by-*index*
+    """
+
+    #: Object type, same to :attr:`Schema.objtype`.
+    objtype: str
+    #: Name of field, see :attr:`.schema.Field.name`.
+    field: str | None
+    #: Name of indexer, see :attr:`.schema.Indexer.name`.
+    indexer: str | None
+
+    def __init__(self, objtype: str, field: str | None = None, indexer: str | None = None):
+        self.objtype = objtype
+        self.field = field
+        self.indexer = indexer
+
+    @classmethod
+    def parse(cls, reftype: str):
+        """Format: <objtype>[.<field>[+<action>]]. Possible action:
+
+        - by-<indexer>
+        """
+
+        if '+' in reftype:
+            reftype, action = reftype.split('+', 1)
+            if action.startswith('by-'):
+                index = action[3:]
+            else:
+                raise ValueError(f'unknown action {action} in RefType {reftype}')
+        else:
+            index = None
+
+        if '.' in reftype:
+            objtype, field = reftype.split('.', 1)
+        else:
+            objtype, field = reftype, None
+
+        return cls(objtype, field, index)
+
+
+    def __str__(self):
+        """Used as key of role and index inside :cls:`AnyDomain`."""
+        s = self.objtype
+        if self.field:
+            s += '.' + self.field
+        if self.indexer:
+            s += '+' + 'by-' + self.indexer
+        return s
+
+
+    def index_name(self) -> str:
+        """Used as :attr:`AnyIndex.name`."""
+        s = self.objtype
+        if self.field:
+            s += '.' + self.field
+        if self.indexer and self.indexer != LiteralIndexer.name:
+            s += '+' + 'by-' + self.indexer
+        return s
+
+
+    def index_localname(self) -> str:
+        """Used as :attr:`AnyIndex.localname`."""
+        if self.field:
+            localname = f'{self.objtype.title()} {self.field.title()} Reference Index'
+        else:
+            localname = f'{self.objtype.title()} Reference Index'
+        if self.indexer and self.indexer != LiteralIndexer.name:
+            localname += 'by ' + self.indexer.title()
+        return localname
+
+    def index_classname(self) -> str:
+        """Used as name of :attr:`AnyIndex` sub-class."""
+        if self.field:
+            clsname = f'Any{self.objtype.title()}{self.field.title()}Index'
+        else:
+            clsname = f'Any{self.objtype.title()}Index'
+        if self.indexer and self.indexer != LiteralIndexer.name:
+            clsname += 'By' + self.indexer.title()
+        return clsname