memoryframes 0.1.6__tar.gz → 0.3.0__tar.gz

{memoryframes-0.1.6 → memoryframes-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: memoryframes
-Version: 0.1.6
+Version: 0.3.0
 Summary: Add your description here
 Author: David Brownell
 Author-email: David Brownell <github@DavidBrownell.com>

{memoryframes-0.1.6 → memoryframes-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "MemoryFrames"
-version = "0.1.6"
+version = "0.3.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:

memoryframes-0.3.0/src/MemoryFrames/PluginInfra/Note.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+    from MemoryFrames.PluginInfra.NoteSource import NoteSource
+
+
+# ----------------------------------------------------------------------
+@dataclass
+class Note:
+    """A note."""
+
+    id: UUID
+
+    source: NoteSource
+    source_data: object
+    """Opaque data provided by the NoteSource that created the note."""
+
+    metadata: dict[str, object] = field(repr=False)
+    content: str = field(repr=False)
+
+    metadata_hash: bytes = field(repr=False)
+    content_hash: bytes = field(repr=False)

memoryframes-0.3.0/src/MemoryFrames/PluginInfra/NoteSource.py

@@ -0,0 +1,36 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from MemoryFrames.PluginInfra.Note import Note
+
+
+# ----------------------------------------------------------------------
+class NoteSource:
+    """Base class for a plugin component that provides notes to MemoryFrames."""
+
+    # ----------------------------------------------------------------------
+    def __init__(self, observer: NoteSourceObserver) -> None:
+        self.observer = observer
+
+
+# ----------------------------------------------------------------------
+class NoteSourceObserver(ABC):
+    """Base class for an observer that receives event notifications from a NoteSource."""
+
+    # ----------------------------------------------------------------------
+    @abstractmethod
+    def OnNewNote(
+        self,
+        note: Note,
+        *,
+        is_initializing: bool,
+    ) -> None:
+        """Indicate that a note has been discovered."""
+        raise NotImplementedError()  # pragma: no cover
+
+    # ----------------------------------------------------------------------
+    @abstractmethod
+    def OnInitializationComplete(self, note_source: NoteSource) -> None:
+        """Indicate that the NoteSource has completed its initialization."""
+        raise NotImplementedError()  # pragma: no cover

memoryframes-0.3.0/src/MemoryFrames/PluginInfra/Plugin.py

@@ -0,0 +1,97 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+import pluggy
+
+from MemoryFrames import APP_NAME
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from threading import Event
+    from pathlib import Path
+
+    from MemoryFrames.PluginInfra.NoteSource import NoteSource, NoteSourceObserver
+    from MemoryFrames.PluginInfra.UserExperienceInfo import UserExperienceInfo
+
+
+# ----------------------------------------------------------------------
+@dataclass(frozen=True)
+class ThreadInfo:
+    """Information about a thread that is defined by a Plugin but created and managed by the application."""
+
+    description: str
+    thread_func: Callable[
+        [
+            Event  # Event set when the application is quitting
+        ],
+        None,
+    ]
+
+
+# ----------------------------------------------------------------------
+class Plugin(ABC):
+    """Base class for all MemoryFrames plugins."""
+
+    # ----------------------------------------------------------------------
+    def __init__(
+        self,
+        root_data_dir: Path,
+    ) -> None:
+        scrubbed_unique_name = self.unique_name
+
+        for invalid_char in ["<", ">", ":", '"', "/", "\\", "|", "?", "*", "."]:
+            scrubbed_unique_name = scrubbed_unique_name.replace(invalid_char, "_")
+
+        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}"
+
+    # ----------------------------------------------------------------------
+    def GetNoteSource(
+        self,
+        observer: NoteSourceObserver,  # noqa: ARG002
+        enqueue_thread_info_func: Callable[[ThreadInfo], None],  # noqa: ARG002
+    ) -> NoteSource | None:
+        """Return a NoteSource implemented by this plugin."""
+        return None
+
+
+# ----------------------------------------------------------------------
+@pluggy.HookspecMarker(APP_NAME)
+def GetPlugin(
+    root_data_dir: Path,
+    all_plugins_settings: dict[str, object],
+    user_experience_info: UserExperienceInfo,
+) -> Plugin:
+    """Return a Plugin instance."""
+    raise NotImplementedError()  # pragma: no cover

memoryframes-0.3.0/src/MemoryFrames/PluginInfra/README.md

@@ -0,0 +1 @@
+This directory contains all information, base classes, helper classes, etc. used when creating Plugins that customize MemoryFrames behavior.

memoryframes-0.3.0/src/MemoryFrames/PluginInfra/UserExperienceInfo.py

@@ -0,0 +1,22 @@
+import sys
+
+
+# ----------------------------------------------------------------------
+class UserExperienceInfo:
+    """Abstract base class for information associated with user experiences.
+
+    This information is passed to a Plugin on creation, where it uses the info to adjust its behavior
+    based on the information's derived type and associated data.
+    """
+
+    # ----------------------------------------------------------------------
+    def __init__(self) -> None:
+        # Ensure that only known classes inherit from this base class, as it is not a small thing
+        # to introduce a new user experience type (as all plugins, across the world, must be
+        # updated to support it.
+        if not sys.flags.optimize:
+            pass
+            # TODO: # Avoid circular import issues by importing here
+            # TODO: from MemoryFrames.PluginInfra.TextualUserExperienceInfo import TextualUserExperienceInfo
+
+            # TODO: assert isinstance(self, (TextualUserExperienceInfo,)), self