nemo-annotation 0.1.0__tar.gz

nemo_annotation-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.3
+Name: nemo-annotation
+Version: 0.1.0
+Summary: An annotation extension for Nemo.
+Author: Flynn
+Author-email: Flynn <leisure-zyf@qq.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Nemo Annotation
+
+> An annotation extension for Nemo.
+
+## Installation
+
+```sh
+pip install nemo_annotation
+```
+
+```sh
+uv add nemo_annotation
+```
+
+## Usage
+
+```sh
+[uv run] python -m nemo_annotation install[uninstall]
+nemo -q && nemo
+```
+
+## Current System Environment
+
+| Item | Version / Path | Notes |
+|------|---------------|-------|
+| Distribution | Ubuntu (Mint 22 "Zena" family) | `nemo` version carries `+zena` |
+| System Python | 3.12.3 | `/usr/bin/python3` |
+| Nemo core | 6.6.3+zena | The file manager itself |
+| nemo-python | 6.0.0+ds-1build3 | Python bindings, packaged by Ubuntu |
+| nemo-python maintainer | Debian Cinnamon Team | Upstream is Linux Mint |
+| nemo-python homepage | https://github.com/linuxmint/nemo-extensions/ | Source repository |
+
+## Dependencies
+
+| Package | Version requirement | Purpose |
+|---------|--------------------|---------|
+| `gir1.2-nemo-3.0` | >= 4.6~ | GObject Introspection data for Nemo |
+| `python3-gi` | — | System PyGObject (runtime) |
+| `libnemo-extension1` | >= 4.6~ | Nemo extension C shared library |
+| `libgtk-3-0t64` | >= 3.0.0 | GTK3 runtime |
+| `libpython3.12t64` | >= 3.12.1 | Python 3.12 runtime |
+
+## Version Compatibility Check
+
+| Check | Result | Conclusion |
+|-------|--------|------------|
+| Nemo core range required by `nemo-python` | `>= 4.6~` | 6.6.3 satisfies |
+| Current Nemo core | 6.6.3 | Above minimum requirement |
+| Documentation source | Installed with the `nemo-python 6.0.0` package | Matches the bindings |
+| Documentation vs. runtime API | Core interfaces stable | Usable |
+
+## GTK-Doc Documentation Location
+
+```bash
+/usr/share/gtk-doc/html/nemo-python/
+```
+
+Covered classes:
+
+- `class-nemo-python-column.html`
+- `class-nemo-python-column-provider.html`
+- `class-nemo-python-file-info.html`
+- `class-nemo-python-info-provider.html`
+- `class-nemo-python-location-widget-provider.html`
+- `class-nemo-python-menu.html`
+- `class-nemo-python-menu-item.html`
+- `class-nemo-python-menu-provider.html`
+- `class-nemo-python-property-page.html`
+- `class-nemo-python-property-page-provider.html`
+- `enum-nemo-python-operation-result.html`
+
+## Development Environment
+
+| Item | Value |
+|------|-------|
+| Project directory | `~/桌面/nemo-meta/` |
+| Virtual environment | `.venv` (managed by uv, based on system Python 3.12.3) |
+| IDE type stubs | `pygobject-stubs` + custom `Nemo.pyi` |
+| Extension install path | `~/.local/share/nemo-python/extensions/` |
+| Debugging method | `TMPDIR=/tmp/testing nemo --no-desktop` |
+
+## Key Version Risks
+
+| Risk | Notes |
+|------|-------|
+| `nemo-python` 6.0.0 vs `nemo` 6.6.3 | Bindings lag behind the core, but the dependency declaration is compatible |
+| Multiple versions in between | 6.0 → 6.2 → 6.4 → 6.6; core extension interfaces (Provider) are stable |
+| Want the latest API | Check the `.c` sources at the corresponding tag (e.g. 6.6.3) on GitHub |
+
+
+
+### Notes
+
+- **`nemo-python` 6.0.0** is the version packaged in the Ubuntu repositories. Its dependency declaration `>= 4.6~` means it is compatible with Nemo core 4.6 and above; your 6.6.3 satisfies this.
+- **The documentation version matches the bindings** — both come from the `nemo-python 6.0.0` package, so it is safe to use for generating `.pyi` stubs.
+- **For the latest upstream source**, look on GitHub for the `6.6.3` tag or similar, since the system bindings lag behind the core.

nemo_annotation-0.1.0/README.md

@@ -0,0 +1,96 @@
+# Nemo Annotation
+
+> An annotation extension for Nemo.
+
+## Installation
+
+```sh
+pip install nemo_annotation
+```
+
+```sh
+uv add nemo_annotation
+```
+
+## Usage
+
+```sh
+[uv run] python -m nemo_annotation install[uninstall]
+nemo -q && nemo
+```
+
+## Current System Environment
+
+| Item | Version / Path | Notes |
+|------|---------------|-------|
+| Distribution | Ubuntu (Mint 22 "Zena" family) | `nemo` version carries `+zena` |
+| System Python | 3.12.3 | `/usr/bin/python3` |
+| Nemo core | 6.6.3+zena | The file manager itself |
+| nemo-python | 6.0.0+ds-1build3 | Python bindings, packaged by Ubuntu |
+| nemo-python maintainer | Debian Cinnamon Team | Upstream is Linux Mint |
+| nemo-python homepage | https://github.com/linuxmint/nemo-extensions/ | Source repository |
+
+## Dependencies
+
+| Package | Version requirement | Purpose |
+|---------|--------------------|---------|
+| `gir1.2-nemo-3.0` | >= 4.6~ | GObject Introspection data for Nemo |
+| `python3-gi` | — | System PyGObject (runtime) |
+| `libnemo-extension1` | >= 4.6~ | Nemo extension C shared library |
+| `libgtk-3-0t64` | >= 3.0.0 | GTK3 runtime |
+| `libpython3.12t64` | >= 3.12.1 | Python 3.12 runtime |
+
+## Version Compatibility Check
+
+| Check | Result | Conclusion |
+|-------|--------|------------|
+| Nemo core range required by `nemo-python` | `>= 4.6~` | 6.6.3 satisfies |
+| Current Nemo core | 6.6.3 | Above minimum requirement |
+| Documentation source | Installed with the `nemo-python 6.0.0` package | Matches the bindings |
+| Documentation vs. runtime API | Core interfaces stable | Usable |
+
+## GTK-Doc Documentation Location
+
+```bash
+/usr/share/gtk-doc/html/nemo-python/
+```
+
+Covered classes:
+
+- `class-nemo-python-column.html`
+- `class-nemo-python-column-provider.html`
+- `class-nemo-python-file-info.html`
+- `class-nemo-python-info-provider.html`
+- `class-nemo-python-location-widget-provider.html`
+- `class-nemo-python-menu.html`
+- `class-nemo-python-menu-item.html`
+- `class-nemo-python-menu-provider.html`
+- `class-nemo-python-property-page.html`
+- `class-nemo-python-property-page-provider.html`
+- `enum-nemo-python-operation-result.html`
+
+## Development Environment
+
+| Item | Value |
+|------|-------|
+| Project directory | `~/桌面/nemo-meta/` |
+| Virtual environment | `.venv` (managed by uv, based on system Python 3.12.3) |
+| IDE type stubs | `pygobject-stubs` + custom `Nemo.pyi` |
+| Extension install path | `~/.local/share/nemo-python/extensions/` |
+| Debugging method | `TMPDIR=/tmp/testing nemo --no-desktop` |
+
+## Key Version Risks
+
+| Risk | Notes |
+|------|-------|
+| `nemo-python` 6.0.0 vs `nemo` 6.6.3 | Bindings lag behind the core, but the dependency declaration is compatible |
+| Multiple versions in between | 6.0 → 6.2 → 6.4 → 6.6; core extension interfaces (Provider) are stable |
+| Want the latest API | Check the `.c` sources at the corresponding tag (e.g. 6.6.3) on GitHub |
+
+
+
+### Notes
+
+- **`nemo-python` 6.0.0** is the version packaged in the Ubuntu repositories. Its dependency declaration `>= 4.6~` means it is compatible with Nemo core 4.6 and above; your 6.6.3 satisfies this.
+- **The documentation version matches the bindings** — both come from the `nemo-python 6.0.0` package, so it is safe to use for generating `.pyi` stubs.
+- **For the latest upstream source**, look on GitHub for the `6.6.3` tag or similar, since the system bindings lag behind the core.

nemo_annotation-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "nemo-annotation"
+version = "0.1.0"
+description = "An annotation extension for Nemo."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+
+[[project.authors]]
+name = "Flynn"
+email = "leisure-zyf@qq.com"
+
+[project.scripts]
+main = "nemo_annotation:main"
+install = "nemo_annotation:install"
+uninstall = "nemo_annotation:uninstall"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"

nemo_annotation-0.1.0/pyproject.toml.orig

@@ -0,0 +1,19 @@
+[project]
+name = "nemo-annotation"
+version = "0.1.0"
+description = "An annotation extension for Nemo."
+readme = "README.md"
+authors = [
+    { name = "Flynn", email = "leisure-zyf@qq.com" }
+]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.scripts]
+main = "nemo_annotation:main"
+install = "nemo_annotation:install"
+uninstall = "nemo_annotation:uninstall"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"

nemo_annotation-0.1.0/src/nemo_annotation/__init__.py

@@ -0,0 +1,20 @@
+import os
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+#
+from .cli import install, uninstall
+
+
+def main() -> None:
+    print("Hello from nemo-meta!")
+    print(os.getcwd())
+
+
+def log(s):
+    print("[INFO]", datetime.now().strftime("%H:%M:%S"), f"[{__name__}]:", s)
+
+
+log(f"{sys.executable}, v{sys.version}.")

nemo_annotation-0.1.0/src/nemo_annotation/__main__.py

@@ -0,0 +1,9 @@
+import sys
+
+from .cli import install, uninstall
+
+if "install" in " ".join(sys.argv):
+    install()
+
+if "uninstall" in " ".join(sys.argv):
+    uninstall()

nemo_annotation-0.1.0/src/nemo_annotation/cli.py

@@ -0,0 +1,31 @@
+import subprocess
+from pathlib import Path
+
+nemo_annotation = Path(__file__).parent
+
+xx = [
+    [
+        nemo_annotation,
+        Path.home() / ".local/share/nemo-python/extensions/nemo_annotation",
+    ],
+    [
+        nemo_annotation / "main.py",
+        Path.home() / ".local/share/nemo-python/extensions/nemo_annotation_main.py",
+    ],
+]
+
+
+def install() -> None:
+    uninstall()
+    print("Installing nemo-meta extension...")
+    for src, tgt in xx:
+        subprocess.run(f"ln -s {src} {tgt}", shell=True, check=True)
+        print(tgt.exists(), tgt.resolve())
+
+
+def uninstall() -> None:
+    print("Uninstalling nemo-meta extension...")
+    for src, tgt in xx:
+        if tgt.parent == Path.home() / ".local/share/nemo-python/extensions":
+            tgt.unlink(missing_ok=True)
+            print(tgt.exists(), tgt.resolve())

nemo_annotation-0.1.0/src/nemo_annotation/main.py

@@ -0,0 +1,234 @@
+import json
+import urllib.parse
+from datetime import datetime
+from functools import lru_cache
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from nemo_annotation import log
+
+if TYPE_CHECKING:
+    from nemo_annotation.types import GObject, Gtk, Nemo
+else:
+    from gi.repository import GObject, Gtk, Nemo
+
+
+META_FN = ".nemo_annotation.json"
+NAMESPACE = "NemoPython::NemoMeta"
+
+# 三个属性列的元数据：label 用于列表列标题，title/hint 用于属性页。
+META_TAGS = {
+    "creation_data": {
+        "label": "WHEN",
+        "title": "创建时间",
+        "hint": "YYYY-MM-DD HH:MM",
+    },
+    "description": {
+        "label": "DESC",
+        "title": "描述",
+        "hint": "简要说明",
+    },
+    "from": {
+        "label": "FROM",
+        "title": "来源",
+        "hint": "来源 / 出处",
+    },
+}
+
+
+@lru_cache(maxsize=8)
+def get_json(fn: str, mtime: float):
+    fp = Path(fn)
+    if fp.exists():
+        try:
+            data = json.loads(fp.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            log(f"忽略无法解析的元数据文件: {fn}")
+            return {}
+        return data if isinstance(data, dict) else {}
+    else:
+        return {}
+
+
+def local_path(file) -> Path | None:
+    """把 Nemo.FileInfo 还原成本地路径，非本地 URI 返回 None。"""
+    if file.get_uri_scheme() != "file":
+        return None
+    path = file.get_location().get_path()
+    if path is None:
+        uri = file.get_uri()
+        if not uri.startswith("file://"):
+            return None
+        path = urllib.parse.unquote(uri[7:])
+    return Path(path)
+
+
+def read_meta(fp: Path) -> dict:
+    """读取文件所在目录的 .nemo_annotation.json 中该文件的记录。"""
+    fm = fp.parent / META_FN
+    data = get_json(fm.resolve().as_posix(), fm.stat().st_mtime) if fm.exists() else {}
+    entry = data.get(fp.name, {}) if isinstance(data, dict) else {}
+    # 返回副本，避免属性页修改到 lru_cache 里共享的对象
+    return dict(entry) if isinstance(entry, dict) else {}
+
+
+def write_meta(fp: Path, values: dict) -> None:
+    """写入该文件的属性；空记录会被清掉，目录里其它文件的记录保持不变。"""
+    fm = fp.parent / META_FN
+    data = {}
+    if fm.exists():
+        try:
+            data = json.loads(fm.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            data = {}
+    if not isinstance(data, dict):
+        data = {}
+
+    entry = {k: v for k, v in values.items() if v}
+    if entry:
+        data[fp.name] = entry
+    else:
+        data.pop(fp.name, None)
+
+    if data:
+        tmp = fm.with_name(fm.name + ".tmp")
+        tmp.write_text(
+            json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+        )
+        tmp.replace(fm)
+    else:
+        fm.unlink(missing_ok=True)
+    get_json.cache_clear()
+
+
+class ColumnExtension(GObject.GObject, Nemo.ColumnProvider, Nemo.InfoProvider):
+    def __init__(self):
+        GObject.GObject.__init__(self)
+
+    def get_columns(self):
+        return [
+            Nemo.Column(
+                name=f"{NAMESPACE}::{k}",
+                attribute=k,
+                label=v["label"],
+                description=f"Get the {k}",
+            )
+            for k, v in META_TAGS.items()
+        ]
+
+    def update_file_info(self, file):
+        # trash://、smb://、mtp:// 等非本地 URI 直接跳过
+        fp = local_path(file)
+        if fp is None:
+            return
+
+        for k in META_TAGS:
+            file.add_string_attribute(k, "")
+
+        fm = fp.parent / META_FN
+        if fm.exists():
+            data: dict = get_json(fm.resolve().as_posix(), fm.stat().st_mtime)
+            log(fm)
+
+            for k, v in data.get(fp.name, {}).items():
+                file.add_string_attribute(k, v)
+                log(f"{k}: {v} ")
+
+
+class MetaPropertyPage(GObject.GObject, Nemo.PropertyPageProvider):
+    """显示 / 创建 / 修改三个属性列的属性页。"""
+
+    def __init__(self):
+        GObject.GObject.__init__(self)
+
+    def get_property_pages(self, files):
+        if len(files) != 1:
+            return
+
+        file = files[0]
+        fp = local_path(file)
+        if fp is None:
+            return
+
+        meta = read_meta(fp)
+        editable = file.can_write()
+
+        # 尚无记录时，为 creation_data 预填当前时间，方便直接“创建”。
+        if not meta.get("creation_data"):
+            meta["creation_data"] = datetime.now().strftime("%Y-%m-%d %H:%M")
+
+        self.property_label = Gtk.Label("属性标注")
+        self.property_label.show()
+
+        page = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12)
+        page.set_border_width(12)
+
+        header = Gtk.Label(xalign=0)
+        header.set_markup(f"<b>{GObject.markup_escape_text(fp.name)}</b>")
+        page.pack_start(header, False, False, 0)
+
+        grid = Gtk.Grid(column_spacing=12, row_spacing=8)
+        page.pack_start(grid, False, False, 0)
+
+        entries = {}
+        for row, (k, v) in enumerate(META_TAGS.items()):
+            label = Gtk.Label(xalign=0)
+            label.set_markup(f"{GObject.markup_escape_text(v['title'])} ({k})")
+            grid.attach(label, 0, row, 1, 1)
+
+            entry = Gtk.Entry()
+            entry.set_text(meta.get(k, "") or "")
+            entry.set_placeholder_text(v["hint"])
+            entry.set_hexpand(True)
+            entry.set_sensitive(editable)
+            grid.attach(entry, 1, row, 1, 1)
+            entries[k] = entry
+
+            if k == "creation_data":
+                now_btn = Gtk.Button(label="现在")
+                now_btn.set_tooltip_text("填入当前时间")
+                now_btn.set_sensitive(editable)
+                grid.attach(now_btn, 2, row, 1, 1)
+
+                def on_now(_btn, _entry=entry):
+                    _entry.set_text(datetime.now().strftime("%Y-%m-%d %H:%M"))
+
+                now_btn.connect("clicked", on_now)
+
+        status = Gtk.Label(xalign=0)
+        page.pack_start(status, False, False, 0)
+
+        buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=6)
+        buttons.set_halign(Gtk.Align.END)
+        page.pack_start(buttons, False, False, 0)
+
+        save_btn = Gtk.Button(label="保存")
+        save_btn.set_sensitive(editable)
+        buttons.pack_start(save_btn, False, False, 0)
+
+        def on_save(_btn=None):
+            values = {k: e.get_text().strip() for k, e in entries.items()}
+            try:
+                write_meta(fp, values)
+            except OSError as err:
+                status.set_text(f"保存失败：{err}")
+                return
+            # 让列视图重新读取属性
+            file.invalidate_extension_info()
+            status.set_text("已保存")
+
+        save_btn.connect("clicked", on_save)
+        for entry in entries.values():
+            entry.connect("activate", on_save)
+
+        page.show_all()
+        if not editable:
+            status.set_text("文件不可写，仅可查看")
+
+        return (
+            Nemo.PropertyPage(
+                name=NAMESPACE,
+                label=self.property_label,
+                page=page,
+            ),
+        )

nemo_annotation-0.1.0/src/nemo_annotation/nemo.pyi

@@ -0,0 +1,131 @@
+"""Type declarations for the ``gi.repository.Nemo`` API documented here."""
+
+from collections.abc import Sequence
+from enum import IntEnum
+from typing import Any, Protocol
+
+class GObject: ...
+
+class Column:
+    name: str
+    attribute: str
+    label: str
+    description: str
+    xalign: float
+
+    def __init__(
+        self,
+        name: str,
+        attribute: str,
+        label: str,
+        description: str,
+    ) -> None: ...
+
+class FileInfo(Protocol):
+    def is_gone(self) -> bool: ...
+    def get_file_type(self) -> Any: ...
+    def get_location(self) -> Any: ...
+    def get_name(self) -> str: ...
+    def get_uri(self) -> str: ...
+    def get_activation_uri(self) -> str: ...
+    def get_parent_info(self) -> FileInfo | None: ...
+    def get_parent_location(self) -> Any: ...
+    def get_parent_uri(self) -> str: ...
+    def get_mount(self) -> Any: ...
+    def get_uri_scheme(self) -> str: ...
+    def get_mime_type(self) -> str: ...
+    def is_mime_type(self, mimetype: str) -> bool: ...
+    def is_directory(self) -> bool: ...
+    def can_write(self) -> bool: ...
+    def add_emblem(self, emblem_name: str) -> None: ...
+    def get_string_attribute(self, attribute_name: str) -> str | None: ...
+    def add_string_attribute(self, attribute_name: str, value: str) -> None: ...
+    def invalidate_extension_info(self) -> None: ...
+
+class Menu:
+    def __init__(self) -> None: ...
+    def append_item(self, item: MenuItem) -> None: ...
+    def get_items(self) -> list[MenuItem]: ...
+
+class MenuItem:
+    name: str
+    label: str
+    tip: str
+    icon: str
+    menu: Menu | None
+    priority: bool
+    sensitive: bool
+
+    def __init__(
+        self,
+        name: str,
+        label: str,
+        tooltip: str,
+        icon: str,
+    ) -> None: ...
+    def activate(self) -> None: ...
+    def set_submenu(self, menu: Menu | None) -> None: ...
+
+class PropertyPage:
+    name: str
+    label: Any
+    page: Any
+
+    def __init__(self, name: str, label: Any, page: Any) -> None: ...
+
+class ColumnProvider(Protocol):
+    def get_columns(self) -> list[Column]: ...
+
+class InfoProvider(Protocol):
+    def update_file_info(self, file: FileInfo) -> None: ...
+    def update_file_info_full(
+        self,
+        provider: InfoProvider,
+        handle: Any,
+        closure: Any,
+        file: FileInfo,
+    ) -> OperationResult | None: ...
+    def cancel_update(self, provider: InfoProvider, handle: Any) -> None: ...
+
+class LocationWidgetProvider(Protocol):
+    def get_widget(self, uri: str, window: Any) -> Any: ...
+
+class MenuProvider(Protocol):
+    def get_file_items(
+        self,
+        window: Any,
+        files: Sequence[FileInfo],
+    ) -> list[MenuItem]: ...
+    def get_file_items_full(
+        self,
+        provider: MenuProvider,
+        window: Any,
+        files: Sequence[FileInfo],
+    ) -> list[MenuItem]: ...
+    def get_background_items(
+        self,
+        window: Any,
+        folder: FileInfo,
+    ) -> list[MenuItem]: ...
+    def get_background_items_full(
+        self,
+        provider: MenuProvider,
+        window: Any,
+        folder: FileInfo,
+    ) -> list[MenuItem]: ...
+
+class PropertyPageProvider(Protocol):
+    def get_pages(self, files: Sequence[FileInfo]) -> list[PropertyPage]: ...
+
+class OperationResult(IntEnum):
+    COMPLETE = ...
+    IN_PROGRESS = ...
+    FAILED = ...
+
+def info_provider_update_complete_invoke(
+    provider: InfoProvider,
+    handle: Any,
+    closure: Any,
+    result: OperationResult = OperationResult.COMPLETE,
+) -> None: ...
+def menu_provider_emit_items_updated_signal(provider: MenuProvider) -> None: ...

nemo_annotation-0.1.0/src/nemo_annotation/types.pyi

@@ -0,0 +1,19 @@
+class Nemo:
+    from .nemo import (
+        Column,
+        ColumnProvider,
+        FileInfo,
+        InfoProvider,
+        LocationWidgetProvider,
+        Menu,
+        MenuItem,
+        MenuProvider,
+        OperationResult,
+        PropertyPage,
+        PropertyPageProvider,
+    )
+
+class GObject:
+    from .nemo import GObject
+
+class Gtk:...