feat: Improve the douki structure to allow support for more programming languages (#21)

Author: xmnlab

pyproject.toml

@@ -114,7 +114,7 @@ quote-style = "single"
 [tool.vulture]
 exclude = ["tests"]
 ignore_decorators = []
-ignore_names = []
+ignore_names = ["cwd", "paths", "excludes"]
 make_whitelist = true
 min_confidence = 80
 paths = ["./"]

src/douki/_base/__init__.py

@@ -0,0 +1,7 @@
+"""
+title: 'Language-agnostic components: YAML parsing, syncing, etc.'
+"""
+
+from douki._base.language import BaseLanguage, get_language
+
+__all__ = ['BaseLanguage', 'get_language']

src/douki/_base/config.py

@@ -0,0 +1,46 @@
+"""
+title: Abstract base configuration for language plugins.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import List
+
+
+class BaseConfig(ABC):
+    """
+    title: Abstract configuration loader for a language backend.
+    summary: >-
+      Each language plugin subclasses this to define how exclude patterns and
+      source files are discovered.
+    """
+
+    @abstractmethod
+    def load_exclude_patterns(self, cwd: Path) -> List[str]:
+        """
+        title: Load exclude patterns from a config file.
+        parameters:
+          cwd:
+            type: Path
+        returns:
+          type: List[str]
+        """
+        ...  # pragma: no cover
+
+    @abstractmethod
+    def collect_files(
+        self, paths: List[Path], excludes: List[str]
+    ) -> List[Path]:
+        """
+        title: Expand paths into source files, filtering excluded ones.
+        parameters:
+          paths:
+            type: List[Path]
+          excludes:
+            type: List[str]
+        returns:
+          type: List[Path]
+        """
+        ...  # pragma: no cover

src/douki/_base/defaults.py

@@ -0,0 +1,64 @@
+"""
+title: Language-agnostic defaults for Douki.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Tuple
+
+
+@dataclass
+class LanguageDefaults:
+    """
+    title: Per-language defaults for docstring field values.
+    summary: >-
+      Each language plugin provides an instance of this class. Fields whose
+      values match these defaults are omitted from the emitted YAML.
+    attributes:
+      visibility:
+        type: str
+      mutability:
+        type: str
+      scope_function:
+        type: str
+        description: Default scope for stand-alone functions.
+      scope_method:
+        type: str
+        description: Default scope for class methods.
+      file_extensions:
+        type: Tuple[str, Ellipsis]
+        description: File extensions to collect (e.g. ('.py',)).
+      config_files:
+        type: Tuple[str, Ellipsis]
+        description: Config files to search for exclude patterns.
+      field_defaults:
+        type: Dict[str, Any]
+        description: >-
+          Mapping of top-level YAML key to the default value that should be
+          omitted when emitting.
+    """
+
+    visibility: str = 'public'
+    mutability: str = 'mutable'
+    scope_function: str = 'static'
+    scope_method: str = 'instance'
+    file_extensions: Tuple[str, ...] = ()
+    config_files: Tuple[str, ...] = ()
+    field_defaults: Dict[str, Any] = field(default_factory=dict)
+
+    def get_field_defaults(self) -> Dict[str, Any]:
+        """
+        title: >-
+          Return the mapping of top-level YAML key to the default value that
+          should be omitted.
+        returns:
+          type: Dict[str, Any]
+        """
+        defaults = {
+            'visibility': self.visibility,
+            'mutability': self.mutability,
+            'scope': self.scope_function,
+        }
+        defaults.update(self.field_defaults)
+        return defaults

src/douki/_base/language.py

@@ -0,0 +1,98 @@
+"""
+title: Language plugin interface.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Dict, Optional, Type
+
+from douki._base.config import BaseConfig
+
+
+class BaseLanguage(ABC):
+    """
+    title: Abstract base class for a language plugin.
+    summary: >-
+      Plugins subclass this to bind their language-specific extractor, sync
+      logic, and configuration.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        title: The name of the language (e.g. 'python').
+        returns:
+          type: str
+        """
+        ...  # pragma: no cover
+
+    @property
+    @abstractmethod
+    def config(self) -> BaseConfig:
+        """
+        title: Configuration loader for this language.
+        returns:
+          type: BaseConfig
+        """
+        ...  # pragma: no cover
+
+    @abstractmethod
+    def sync_source(
+        self, source: str, *, migrate: Optional[str] = None
+    ) -> str:
+        """
+        title: Synchronize docstrings in the given source code.
+        parameters:
+          source:
+            type: str
+          migrate:
+            type: Optional[str]
+            optional: true
+        returns:
+          type: str
+        """
+        ...  # pragma: no cover
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+_REGISTRY: Dict[str, Type[BaseLanguage]] = {}
+
+
+def register_language(lang_class: Type[BaseLanguage]) -> None:
+    """
+    title: Register a language plugin class.
+    parameters:
+      lang_class:
+        type: Type[BaseLanguage]
+    """
+    # Create a temporary instance just to get its name
+    instance = lang_class()
+    _REGISTRY[instance.name] = lang_class
+
+
+def get_language(name: str) -> BaseLanguage:
+    """
+    title: Get an initialized language plugin by name.
+    parameters:
+      name:
+        type: str
+    returns:
+      type: BaseLanguage
+    """
+    if name not in _REGISTRY:
+        raise ValueError(f"Language '{name}' is not registered.")
+    return _REGISTRY[name]()
+
+
+def get_registered_language_names() -> list[str]:
+    """
+    title: Return a list of registered language plugin names.
+    returns:
+      type: list[str]
+    """
+    return list(_REGISTRY.keys())