memoryframes 0.4.0__tar.gz → 0.6.0__tar.gz

{memoryframes-0.4.0 → memoryframes-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: memoryframes
-Version: 0.4.0
+Version: 0.6.0
 Summary: Add your description here
 Author: David Brownell
 Author-email: David Brownell <github@DavidBrownell.com>
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: dbrownell-common>=0.16.0
 Requires-Dist: pluggy>=1.6.0
 Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: rtyaml>=1.0.0
 Requires-Dist: textual>=6.8.0
 Requires-Dist: typer>=0.20.0
 Requires-Dist: typer-config>=1.4.3

{memoryframes-0.4.0 → memoryframes-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "MemoryFrames"
-version = "0.4.0"
+version = "0.6.0"
 #          ^^^^^
 # Wheel names will be generated according to this value. Do not manually modify this value; instead
 # update it according to committed changes by running this command from the root of the repository:
@@ -17,6 +17,7 @@ dependencies = [
     "dbrownell-common>=0.16.0",
     "pluggy>=1.6.0",
     "python-frontmatter>=1.1.0",
+    "rtyaml>=1.0.0",
     "textual>=6.8.0",
     "typer>=0.20.0",
     "typer-config>=1.4.3",
@@ -32,6 +33,9 @@ classifiers = [
 [project.license]
 text = "MIT"
 
+[project.scripts]
+memoryframes = "MemoryFrames.__main__:app"
+
 [project.urls]
 Homepage = "https://github.com/davidbrownell/MemoryFrames"
 Documentation = "https://github.com/davidbrownell/MemoryFrames"
@@ -47,6 +51,7 @@ dev = [
     "dbrownell-commitemojis>=0.2.0",
     "pre-commit>=4.5.0",
     "py-minisign>=0.13.0",
+    "pyfakefs>=5.10.2",
     "pytest>=9.0.2",
     "pytest-cov>=7.0.0",
     "ruff>=0.14.9",
@@ -54,7 +59,7 @@ dev = [
 ]
 
 [tool.pytest.ini_options]
-addopts = "--verbose -vv --capture=no --cov=MemoryFrames --cov-report html --cov-report term --cov-report xml:coverage.xml --cov-fail-under=95.0"
+addopts = "--verbose -vv --capture=no --cov=MemoryFrames --cov-report html --cov-report term --cov-report xml:coverage.xml --cov-fail-under=75.0"
 python_files = [
     "**/*Test.py",
 ]

memoryframes-0.6.0/src/MemoryFrames/AppState.py

@@ -0,0 +1,94 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import auto, Enum
+from typing import TYPE_CHECKING
+
+import pluggy
+
+from MemoryFrames import APP_NAME
+from MemoryFrames.PluginInfra import Plugin as PluginModule
+
+if TYPE_CHECKING:
+    from MemoryFrames.PluginInfra.Plugin import Plugin
+    from MemoryFrames.PluginInfra.Settings import Settings
+    from MemoryFrames.PluginInfra.UserExperienceInfo import UserExperienceInfo
+
+
+# ----------------------------------------------------------------------
+class AppStateObserver(ABC):
+    """Observer for AppState changes."""
+
+    # ----------------------------------------------------------------------
+    class EventType(Enum):
+        """Value signaling progress during the creation of an AppState instance."""
+
+        LoadingPlugins = auto()
+
+    # ----------------------------------------------------------------------
+    @abstractmethod
+    def OnEvent(self, event_type: EventType) -> None:
+        """Invoke when a processing event begins."""
+        raise NotImplementedError()  # pragma: no cover
+
+    # ----------------------------------------------------------------------
+    @abstractmethod
+    def OnException(self, exception: Exception) -> None:
+        """Invoke when an exception occurs during processing."""
+        raise NotImplementedError()  # pragma: no cover
+
+
+# ----------------------------------------------------------------------
+@dataclass(frozen=True)
+class AppState:
+    """MemoryFrames application state."""
+
+    # ----------------------------------------------------------------------
+    plugins: list[Plugin]
+
+    # ----------------------------------------------------------------------
+    @classmethod
+    def Create(
+        cls,
+        settings: Settings,
+        user_experience_info: UserExperienceInfo,
+        observer: AppStateObserver,
+    ) -> AppState | None:
+        """Create an AppState instance."""
+
+        # Load the plugins
+        observer.OnEvent(AppStateObserver.EventType.LoadingPlugins)
+
+        try:
+            plugins = LoadPlugins(settings, user_experience_info)
+        except Exception as ex:
+            observer.OnException(ex)
+            return None
+
+        # We want the highest priority plugins first, and then sort by name. We apply the negative so
+        # that higher priority values appear first while still maintaining ascending order for names.
+        plugins.sort(key=lambda plugin: (-(plugin.PLUGIN_PRIORITY or 0), plugin.NAME))
+
+        return cls(plugins)
+
+
+# ----------------------------------------------------------------------
+def LoadPlugins(
+    settings: Settings,
+    user_experience_info: UserExperienceInfo,
+) -> list[Plugin]:
+    """Load the plugins.
+
+    This is implemented as a separate function to make it easier to monkey-patch during testing.
+    """
+
+    plugin_manager = pluggy.PluginManager(APP_NAME)
+
+    plugin_manager.add_hookspecs(PluginModule)
+    plugin_manager.load_setuptools_entrypoints(APP_NAME)
+
+    plugins: list[Plugin] = plugin_manager.hook.GetPlugin(
+        settings=settings,
+        user_experience_info=user_experience_info,
+    )
+
+    return plugins

{memoryframes-0.4.0 → memoryframes-0.6.0}/src/MemoryFrames/PluginInfra/Plugin.py

@@ -1,7 +1,6 @@
-from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from functools import cached_property
-from typing import TYPE_CHECKING
+from typing import ClassVar, TYPE_CHECKING
 
 import pluggy
 
@@ -13,6 +12,7 @@ if TYPE_CHECKING:
     from pathlib import Path
 
     from MemoryFrames.PluginInfra.NoteSource import NoteSource, NoteSourceObserver
+    from MemoryFrames.PluginInfra.Settings import Settings
     from MemoryFrames.PluginInfra.UserExperienceInfo import UserExperienceInfo
 
 
@@ -31,14 +31,31 @@ class ThreadInfo:
 
 
 # ----------------------------------------------------------------------
-class Plugin(ABC):
+class Plugin:
     """Base class for all MemoryFrames plugins."""
 
+    # ----------------------------------------------------------------------
+    NAME: ClassVar[str] = ""
+    """The name of the plugin."""
+
+    AUTHOR: ClassVar[str] = ""
+    """The author of the plugin. This value will be used in the plugin's unique name."""
+
+    DESCRIPTION: ClassVar[str] = ""
+    """The description of the plugin."""
+
+    PLUGIN_PRIORITY: ClassVar[int] = 0
+    """The priority of the plugin. Higher values indicate higher priority, which will cause the plugin to appear before other lower priority plugins."""
+
     # ----------------------------------------------------------------------
     def __init__(
         self,
         root_data_dir: Path,
     ) -> None:
+        assert self.__class__.NAME, "Derived classes must set the NAME class variable"
+        assert self.__class__.AUTHOR, "Derived classes must set the AUTHOR class variable"
+        assert self.__class__.DESCRIPTION, "Derived classes must set the DESCRIPTION class variable"
+
         scrubbed_unique_name = self.unique_name
 
         for invalid_char in ["<", ">", ":", '"', "/", "\\", "|", "?", "*", "."]:
@@ -47,34 +64,10 @@ class Plugin(ABC):
         self.working_dir = root_data_dir / scrubbed_unique_name
 
     # ----------------------------------------------------------------------
-    @property
-    @abstractmethod
-    def name(self) -> str:
-        """The name of the plugin."""
-        raise NotImplementedError()  # pragma: no cover
-
-    @property
-    @abstractmethod
-    def author(self) -> str:
-        """The author of the plugin. This value will be used in the plugin's unique name."""
-        raise NotImplementedError()  # pragma: no cover
-
-    @property
-    @abstractmethod
-    def description(self) -> str:
-        """The description of the plugin."""
-        raise NotImplementedError()  # pragma: no cover
-
-    @property
-    @abstractmethod
-    def plugin_priority(self) -> int:
-        """The priority of the plugin. Higher values indicate higher priority, which will cause the plugin to appear before other lower priority plugins."""
-        raise NotImplementedError()  # pragma: no cover
-
     @cached_property
     def unique_name(self) -> str:
         """The unique name of the plugin."""
-        return f"{self.author}_{self.name}"
+        return f"{self.__class__.AUTHOR}_{self.__class__.NAME}"
 
     # ----------------------------------------------------------------------
     def GetNoteSource(
@@ -89,8 +82,7 @@ class Plugin(ABC):
 # ----------------------------------------------------------------------
 @pluggy.HookspecMarker(APP_NAME)
 def GetPlugin(
-    root_data_dir: Path,
-    all_plugins_settings: dict[str, object],
+    settings: Settings,
     user_experience_info: UserExperienceInfo,
 ) -> Plugin:
     """Return a Plugin instance."""

memoryframes-0.6.0/src/MemoryFrames/PluginInfra/Settings.py

@@ -0,0 +1,86 @@
+from typing import cast, TYPE_CHECKING
+
+import rtyaml
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from MemoryFrames.PluginInfra.Plugin import Plugin
+
+
+# ----------------------------------------------------------------------
+class Settings:
+    """Settings used by MemoryFrames and its plugins."""
+
+    # ----------------------------------------------------------------------
+    @classmethod
+    def DeserializeOrCreate(
+        cls,
+        content_dir: Path,
+        working_dir: Path,
+        *,
+        verbose: bool,
+        debug: bool,
+    ) -> Settings:
+        """Deserialize settings from disk or create default settings if necessary."""
+
+        settings_filename = cls._GetSettingsFilename(working_dir)
+
+        if settings_filename.is_file():
+            with settings_filename.open("r", encoding="utf-8") as f:
+                settings = rtyaml.load(f)
+        else:
+            settings = {}
+
+        return cls(
+            content_dir,
+            working_dir,
+            cast(dict[str, object], settings),
+            verbose=verbose,
+            debug=debug,
+        )
+
+    # ----------------------------------------------------------------------
+    def __init__(
+        self,
+        content_dir: Path,
+        working_dir: Path,
+        settings: dict[str, object],
+        *,
+        verbose: bool,
+        debug: bool,
+    ) -> None:
+        if debug is True:
+            verbose = True
+
+        # Commit results
+        self.content_dir = content_dir
+        self.working_dir = working_dir
+
+        self.verbose = verbose
+        self.debug = debug
+
+        self._settings = settings
+
+    # ----------------------------------------------------------------------
+    def Serialize(self) -> None:
+        """Serialize settings to disk."""
+
+        settings_filename = self._GetSettingsFilename(self.working_dir)
+
+        with settings_filename.open("w", encoding="utf-8") as f:
+            rtyaml.dump(self._settings, f)
+
+    # ----------------------------------------------------------------------
+    def GetPluginSettings(self, plugin: type[Plugin]) -> dict[str, object]:
+        """Return the settings associated with the provided Plugin."""
+
+        return cast(dict[str, object], self._settings.get(f"{plugin.AUTHOR}_{plugin.NAME}", {}))
+
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    @staticmethod
+    def _GetSettingsFilename(working_dir: Path) -> Path:
+        return working_dir / "settings.yaml"

{memoryframes-0.4.0 → memoryframes-0.6.0}/src/MemoryFrames/PluginInfra/TextualUserExperienceInfo.py

@@ -4,7 +4,7 @@ from MemoryFrames.PluginInfra.UserExperienceInfo import UserExperienceInfo
 
 if TYPE_CHECKING:
     from textual.app import App
-    from textual.containers import Vertical
+    from textual.containers import VerticalScroll
 
 
 # ----------------------------------------------------------------------
@@ -15,7 +15,7 @@ class TextualUserExperienceInfo(UserExperienceInfo):
     def __init__(
         self,
         app: App,
-        hierarchy_container: Vertical,
+        hierarchy_container: VerticalScroll,
     ) -> None:
         super().__init__()
 

memoryframes-0.6.0/src/MemoryFrames/TextualUserExperience.py

@@ -0,0 +1,150 @@
+import traceback
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from dbrownell_Common.Types import override
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Footer, Header, Label, LoadingIndicator
+
+from MemoryFrames import APP_NAME, __version__
+from MemoryFrames.AppState import AppState, AppStateObserver as AppStateObserverBase
+from MemoryFrames.PluginInfra.TextualUserExperienceInfo import TextualUserExperienceInfo
+
+if TYPE_CHECKING:
+    from MemoryFrames.PluginInfra.Settings import Settings
+
+
+# ----------------------------------------------------------------------
+def Execute(settings: Settings) -> None:
+    """Execute the Textual user experience."""
+
+    _App(settings).run()
+
+
+# ----------------------------------------------------------------------
+# ----------------------------------------------------------------------
+# ----------------------------------------------------------------------
+class _App(App):
+    CSS_PATH = Path(__file__).with_suffix(".tcss")
+
+    # ----------------------------------------------------------------------
+    def __init__(self, settings: Settings) -> None:
+        super().__init__()
+
+        self._settings = settings
+
+        self._user_experience = TextualUserExperienceInfo(
+            self.app,
+            VerticalScroll(id="hierarchies"),
+        )
+
+        # The app state is initialized in `on_mount`
+        self._app_state: AppState | None = None
+
+        self.title = "Memory Frames"
+        assert self.title.replace(" ", "") == APP_NAME, (self.title, APP_NAME)
+
+    # ----------------------------------------------------------------------
+    def compose(self) -> ComposeResult:
+        yield Header()
+
+        with Horizontal(id="viewport"):
+            yield self._user_experience.hierarchy_container
+
+        with Horizontal(id="footer"):
+            yield Footer()
+            yield Label(__version__)
+
+    # ----------------------------------------------------------------------
+    def on_mount(self) -> None:
+        # ----------------------------------------------------------------------
+        def OnLoaded(app_state: AppState | None) -> None:
+            if app_state is None:
+                return
+
+            assert self._app_state is None
+            self._app_state = app_state
+
+        # ----------------------------------------------------------------------
+
+        self.push_screen(
+            _LoadingModal(self._settings, self._user_experience),
+            OnLoaded,
+        )
+
+
+# ----------------------------------------------------------------------
+class _LoadingModal(ModalScreen[AppState]):
+    CSS_PATH = Path(__file__).with_suffix(".tcss")
+
+    # ----------------------------------------------------------------------
+    def __init__(
+        self,
+        settings: Settings,
+        user_experience_info: TextualUserExperienceInfo,
+    ) -> None:
+        super().__init__()
+
+        self._settings = settings
+        self._user_experience_info = user_experience_info
+
+        self._status_label = Label("Loading...")
+
+    # ----------------------------------------------------------------------
+    def compose(self) -> ComposeResult:
+        yield LoadingIndicator()
+        yield self._status_label
+
+    # ----------------------------------------------------------------------
+    def on_mount(self) -> None:
+        loading_module = self
+
+        # ----------------------------------------------------------------------
+        def Execute() -> None:
+            current_event: AppStateObserverBase.EventType | None = None
+
+            # ----------------------------------------------------------------------
+            class AppStateObserver(AppStateObserverBase):
+                # ----------------------------------------------------------------------
+                @override
+                def OnEvent(self, event_type: AppStateObserver.EventType) -> None:
+                    nonlocal current_event
+                    current_event = event_type
+
+                    if event_type == AppStateObserver.EventType.LoadingPlugins:
+                        msg = "Loading plugins..."
+                    elif event_type == AppStateObserver.EventType.StartingThreads:
+                        msg = "Starting threads..."
+                    else:
+                        assert False, event_type  # noqa: B011, PT015
+
+                    loading_module._status_label.content = msg  # noqa: SLF001
+
+                # ----------------------------------------------------------------------
+                @override
+                def OnException(self, exception: Exception) -> None:
+                    if loading_module._settings.debug:  # noqa: SLF001
+                        msg = "".join(traceback.format_exception(exception))
+                    else:
+                        msg = str(exception)
+
+                    if current_event == AppStateObserver.EventType.LoadingPlugins:
+                        loading_module.app.panic(msg)
+                        return
+
+                    # Display in a toast
+                    loading_module.notify(msg, severity="error", timeout=10)
+
+            # ----------------------------------------------------------------------
+
+            app_state = AppState.Create(self._settings, self._user_experience_info, AppStateObserver())
+
+            # Return the results
+            self.app.call_from_thread(lambda: self.dismiss(app_state))
+
+        # ----------------------------------------------------------------------
+
+        self.run_worker(Execute, thread=True)

memoryframes-0.6.0/src/MemoryFrames/TextualUserExperience.tcss

@@ -0,0 +1,33 @@
+$version_length: 15;
+
+#footer {
+    height: 1;
+
+    Footer {
+        padding-right: $version_length;
+    }
+
+    Label {
+        background: $footer-background;
+        dock: right;
+        text-align: center;
+        width: $version_length;
+    }
+}
+
+_LoadingModal {
+    align: center middle;
+    background: $panel;
+    height: 2;
+    padding: 1;
+
+    LoadingIndicator {
+        height: 1;
+        margin-bottom: 1;
+    }
+
+    Label {
+        text-align: center;
+        width: 100%;
+    }
+}

memoryframes-0.6.0/src/MemoryFrames/__main__.py

@@ -0,0 +1,107 @@
+import os
+
+from enum import Enum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from typer.core import TyperGroup
+
+from MemoryFrames import TextualUserExperience
+from MemoryFrames.PluginInfra.Settings import Settings
+
+
+# ----------------------------------------------------------------------
+class NaturalOrderGrouper(TyperGroup):  # noqa: D101
+    # ----------------------------------------------------------------------
+    def list_commands(self, *args, **kwargs) -> list[str]:  # noqa: ARG002, D102
+        return list(self.commands.keys())  # pragma: no cover
+
+
+# ----------------------------------------------------------------------
+app = typer.Typer(
+    cls=NaturalOrderGrouper,
+    help=__doc__,
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+    pretty_exceptions_enable=False,
+)
+
+
+# ----------------------------------------------------------------------
+def _GetWorkingDir() -> Path:
+    data_dir = Path.home()
+
+    if os.name == "nt":  # noqa: SIM108
+        data_dir = data_dir / "AppData" / "Local"
+    else:
+        data_dir = data_dir / ".local" / "share"
+
+    data_dir /= "MemoryFrames"
+
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    return data_dir
+
+
+# ----------------------------------------------------------------------
+class _ExperienceType(str, Enum):
+    Textual = "Textual"
+
+
+# ----------------------------------------------------------------------
+@app.command("EntryPoint", no_args_is_help=False)
+def EntryPoint(
+    content_dir: Annotated[
+        Path,
+        typer.Option(
+            "--content-dir",
+            exists=True,
+            file_okay=False,
+            help="Directory containing notes to load.",
+            resolve_path=True,
+        ),
+    ] = Path.cwd(),  # noqa: B008
+    working_dir: Annotated[
+        Path,
+        typer.Option(
+            "--working-dir",
+            file_okay=False,
+            help="Directory to use for settings and other persisted data.",
+            resolve_path=True,
+        ),
+    ] = _GetWorkingDir(),  # noqa: B008
+    experience: Annotated[
+        _ExperienceType,
+        typer.Option("--experience", case_sensitive=False, help="The user experience to use."),
+    ] = _ExperienceType.Textual,
+    verbose: Annotated[  # noqa: FBT002
+        bool,
+        typer.Option("--verbose", help="Write verbose information to the terminal."),
+    ] = False,
+    debug: Annotated[  # noqa: FBT002
+        bool,
+        typer.Option("--debug", help="Write debug information to the terminal."),
+    ] = False,
+) -> None:
+    """Run MemoryFrames."""
+
+    content_dir.mkdir(parents=True, exist_ok=True)
+    working_dir.mkdir(parents=True, exist_ok=True)
+
+    settings = Settings.DeserializeOrCreate(content_dir, working_dir, verbose=verbose, debug=debug)
+
+    if experience == _ExperienceType.Textual:
+        user_experience_func = TextualUserExperience.Execute
+    else:
+        assert False, experience  #  noqa: B011, PT015  # pragma: no cover
+
+    user_experience_func(settings)
+
+
+# ----------------------------------------------------------------------
+# ----------------------------------------------------------------------
+# ----------------------------------------------------------------------
+if __name__ == "__main__":
+    app()  # pragma: no cover