notesmgr 0.1.0__py3-none-any.whl

notesmgr/clipboard_windows.py

@@ -0,0 +1,198 @@
+#! /usr/local/bin/python3
+"""Putting a formatted copy of a note on the clipboard of Windows."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+
+import ctypes
+import sys
+from typing import Sequence
+from notesmgr.clipboard_tool import RichText
+from notesmgr.errors import NotesmgrError
+
+HEADER = 'Version:0.9\r\nStartHTML:{start:010d}\r\nEndHTML:{end:010d}\r\n' \
+    'StartFragment:{first:010d}\r\nEndFragment:{last:010d}\r\n'
+"""What says where the pieces of an HTML Format payload begin and end.
+
+Every number is a count of bytes from the very start of the payload,
+written with as many digits as it can ever need, so that filling the
+numbers in does not move what they point at.
+"""
+
+OPENING = '<html><body>\r\n<!--StartFragment-->'
+"""What stands before the piece of the payload that is pasted."""
+
+CLOSING = '<!--EndFragment-->\r\n</body></html>'
+"""What stands after the piece of the payload that is pasted."""
+
+HTML_FORMAT = 'HTML Format'
+"""What the clipboard of Windows calls the shape that keeps markup."""
+
+UNICODE_TEXT = 13
+"""What the clipboard of Windows calls plain text, as CF_UNICODETEXT."""
+
+MOVEABLE = 0x0002
+"""How memory that is handed over to the clipboard is allocated."""
+
+NOT_WINDOWS = 'This is the clipboard of Microsoft Windows, and this is ' \
+    'no Microsoft Windows.'
+"""What is said when the clipboard of Windows is asked for elsewhere."""
+
+NOT_OPENED = 'The clipboard is held by another program just now.'
+"""What is said when the clipboard could not be opened at all."""
+
+NO_MEMORY = 'There is not memory enough to copy the note.'
+"""What is said when the memory for a copy could not be had."""
+
+NOT_TAKEN = 'The clipboard did not take the copy of the note.'
+"""What is said when the clipboard refused a shape of the copy."""
+
+
+def byte_length(text: str) -> int:
+    """Return how many bytes a text is when it is written as UTF-8."""
+    return len(text.encode('utf-8'))
+
+
+def cf_html(fragment: str) -> str:
+    """Return the HTML Format payload that Windows takes a copy in.
+
+    The header says where the document begins and ends and where the
+    piece of it that is pasted begins and ends. All four are counted
+    in bytes rather than in characters, so a note holding anything
+    but plain ASCII is counted as the UTF-8 that it is written as.
+
+    Args:
+        fragment: The HTML of the note, as it goes inside a body.
+
+    Returns:
+        The payload, header and document together.
+    """
+    head = byte_length(HEADER.format(start=0, end=0, first=0, last=0))
+    first = head + byte_length(OPENING)
+    last = first + byte_length(fragment)
+    return HEADER.format(start=head, end=last + byte_length(CLOSING),
+                         first=first, last=last) + OPENING + fragment + \
+        CLOSING
+
+
+def html_bytes(fragment: str) -> bytes:
+    """Return the formatted shape of a copy as Windows holds it."""
+    return cf_html(fragment).encode('utf-8') + b'\0'
+
+
+def text_bytes(text: str) -> bytes:
+    """Return the plain shape of a copy as Windows holds it."""
+    return text.encode('utf-16-le') + b'\0\0'
+
+
+def declare_memory(kernel32: ctypes.CDLL) -> None:
+    """Tell ctypes what the functions that hand out memory take."""
+    kernel32.GlobalAlloc.restype = ctypes.c_void_p
+    kernel32.GlobalAlloc.argtypes = [ctypes.c_uint, ctypes.c_size_t]
+    kernel32.GlobalLock.restype = ctypes.c_void_p
+    kernel32.GlobalLock.argtypes = [ctypes.c_void_p]
+    kernel32.GlobalUnlock.argtypes = [ctypes.c_void_p]
+    kernel32.GlobalFree.argtypes = [ctypes.c_void_p]
+
+
+def moveable_memory(kernel32: ctypes.CDLL, data: bytes) -> int:
+    """Return a handle to memory holding the given bytes.
+
+    The clipboard takes over the memory it is given, so what is
+    allocated here is moveable, as the clipboard asks, and is not
+    freed again by notesmgr once the clipboard has it. Memory that
+    was had but could not be written to is freed here instead.
+
+    Args:
+        kernel32: The library of Windows that hands out memory.
+        data: What the memory is to hold.
+
+    Returns:
+        The handle to give to the clipboard.
+
+    Raises:
+        NotesmgrError: The memory could not be had or written to.
+    """
+    declare_memory(kernel32)
+    handle = kernel32.GlobalAlloc(MOVEABLE, len(data))
+    if not handle:
+        raise NotesmgrError(NO_MEMORY)
+    place = kernel32.GlobalLock(handle)
+    if not place:
+        kernel32.GlobalFree(handle)
+        raise NotesmgrError(NO_MEMORY)
+    ctypes.memmove(place, data, len(data))
+    kernel32.GlobalUnlock(handle)
+    return int(handle)
+
+
+def hand_over(user32: ctypes.CDLL, kernel32: ctypes.CDLL, named: int,
+              data: bytes) -> None:
+    """Give one shape of a copy to the clipboard, which then owns it.
+
+    Memory that the clipboard did not take is still notesmgr's own,
+    and is freed again rather than left behind.
+
+    Args:
+        user32: The library of Windows that owns the clipboard.
+        kernel32: The library of Windows that hands out memory.
+        named: What the clipboard calls the shape.
+        data: What the shape holds.
+
+    Raises:
+        NotesmgrError: The memory for the shape could not be had, or
+            the clipboard did not take it.
+    """
+    handle = moveable_memory(kernel32, data)
+    if not user32.SetClipboardData(named, handle):
+        kernel32.GlobalFree(handle)
+        raise NotesmgrError(NOT_TAKEN)
+
+
+def write_clipboard(user32: ctypes.CDLL, kernel32: ctypes.CDLL,
+                    shapes: Sequence[tuple[int, bytes]]) -> None:
+    """Put every shape of one copy on the clipboard in one session.
+
+    The clipboard is emptied once and then filled with every shape,
+    because opening it a second time would take away what the first
+    session put there.
+
+    Args:
+        user32: The library of Windows that owns the clipboard.
+        kernel32: The library of Windows that hands out memory.
+        shapes: What each shape of the copy is called and holds.
+
+    Raises:
+        NotesmgrError: The clipboard could not be opened, the memory
+            for a shape could not be had, or the clipboard did not
+            take a shape.
+    """
+    user32.SetClipboardData.restype = ctypes.c_void_p
+    user32.SetClipboardData.argtypes = [ctypes.c_uint, ctypes.c_void_p]
+    if not user32.OpenClipboard(None):
+        raise NotesmgrError(NOT_OPENED)
+    try:
+        user32.EmptyClipboard()
+        for named, data in shapes:
+            hand_over(user32, kernel32, named, data)
+    finally:
+        user32.CloseClipboard()
+
+
+def copy_to_clipboard(payload: RichText) -> None:
+    """Put a formatted copy of a note on the clipboard of Windows.
+
+    Args:
+        payload: The copy to put there.
+
+    Raises:
+        NotesmgrError: This is no Windows, or Windows did not take
+            the copy.
+    """
+    if sys.platform != 'win32':
+        raise NotesmgrError(NOT_WINDOWS)
+    user32 = ctypes.windll.user32
+    named = user32.RegisterClipboardFormatW(HTML_FORMAT)
+    write_clipboard(user32, ctypes.windll.kernel32,
+                    ((named, html_bytes(payload.html)),
+                     (UNICODE_TEXT, text_bytes(payload.text))))

notesmgr/cmd_line.py

@@ -0,0 +1,63 @@
+#! /usr/local/bin/python3
+"""The command line of the notesmgr application."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+
+import argparse
+from pathlib import Path
+from typing import NamedTuple, Optional
+import argcomplete
+
+PROGRAM_NAME = 'notesmgr'
+"""Name that the command line help calls this program."""
+
+DESCRIPTION = 'Manage small notes and AI prompts.'
+"""What the command line help says this program is for."""
+
+FOLDER_HELP = 'Project folder to open at start up.'
+"""What the command line help says about the project folder."""
+
+VERSION_HELP = 'Report the versions of notesmgr and of what it uses.'
+"""What the command line help says about the version flag."""
+
+
+class CommandLine(NamedTuple):
+    """What the command line asked notesmgr to do."""
+
+    project: Optional[Path]
+    show_version: bool
+
+
+def argument_parser() -> argparse.ArgumentParser:
+    """Return the parser that reads the notesmgr command line."""
+    parser = argparse.ArgumentParser(prog=PROGRAM_NAME,
+                                     description=DESCRIPTION)
+    parser.add_argument('project', nargs='?', default=None, type=Path,
+                        metavar='PROJECT_FOLDER', help=FOLDER_HELP)
+    parser.add_argument('--version', dest='show_version', default=False,
+                        action='store_true', help=VERSION_HELP)
+    return parser
+
+
+def parse_command_line(argv: Optional[list[str]] = None) -> CommandLine:
+    """Return what the given command line, or sys.argv, asked for.
+
+    Whether the named folder holds a project is not decided here. A
+    graphical application says that in a window of its own, and not on
+    an error stream that a program started from a desktop has not got.
+
+    Args:
+        argv: Command line arguments, or None for the ones this
+            program was started with.
+
+    Returns:
+        What was asked for.
+    """
+    parser = argument_parser()
+    argcomplete.autocomplete(parser)
+    parsed = parser.parse_args(argv)
+    assert isinstance(parsed.project, (Path, type(None)))
+    assert isinstance(parsed.show_version, bool)
+    return CommandLine(project=parsed.project,
+                       show_version=parsed.show_version)

notesmgr/commands.py

@@ -0,0 +1,307 @@
+#! /usr/local/bin/python3
+"""What the buttons and the menu entries do to the open project."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+
+import tkinter
+from functools import partial
+from pathlib import Path
+from typing import Callable, NamedTuple, Optional, Sequence, Union
+from notesmgr import folder_ops, note_ops
+from notesmgr.actions import Selected, offered
+from notesmgr.config import NoteExtension
+from notesmgr.dialogs import NameFolder, ask_name, ask_name_folder, \
+    ask_yes_no, show_error, show_info
+from notesmgr.editor_command import launch_editor
+from notesmgr.errors import NotesmgrError
+from notesmgr.explorer_drop import Drop, drop_item
+from notesmgr.note_file import is_plain_note, note_stem
+from notesmgr.project import Project, folder_paths, is_project
+from notesmgr.session import Session
+
+NOTE_TITLE = 'Note'
+"""What a window asking about or reporting about a note is called."""
+
+FOLDER_TITLE = 'Folder'
+"""What a window asking about a folder of the project is called."""
+
+DUPLICATE_TITLE = 'Duplicate note'
+"""What the window asking where to copy a note is called."""
+
+ASK_NEW_NOTE = 'What is the new note to be called?'
+"""What the user is asked when making a note."""
+
+ASK_DELETE_NOTE = 'Move the note {name} to the trash?'
+"""What the user is asked before a note is taken away."""
+
+ASK_NEW_FOLDER = 'What is the new folder to be called?'
+"""What the user is asked when making a folder."""
+
+ASK_RENAME_FOLDER = 'What is the folder {name} to be called?'
+"""What the user is asked when renaming a folder."""
+
+ASK_DELETE_FOLDER = 'Move the folder {name} to the trash?'
+"""What the user is asked before a folder is taken away."""
+
+COPY_SUFFIX = ' copy'
+"""What is put after the name of a note to name a copy of it."""
+
+
+def shown_folder(root: Path, folder: Path) -> str:
+    """Return how a folder of a project is named to the user.
+
+    The root folder is named by itself and every folder below it by
+    the way down to it, so that two folders of the same name in
+    different places are told apart.
+
+    Args:
+        root: The root folder of the project.
+        folder: The folder of the project to name.
+
+    Returns:
+        The name to show, which names the folder again through
+        folder_of() when the user has chosen it.
+    """
+    return str(folder.relative_to(root.parent))
+
+
+def folder_of(root: Path, shown: str) -> Path:
+    """Return the folder that a name shown to the user stands for."""
+    return root.parent / shown
+
+
+class WindowHooks(NamedTuple):
+    """What the commands ask the window that holds them to do.
+
+    The window owns the tree and the menus, so it is what shows the
+    project again once a command has changed it, and what offers the
+    actions that can be used on what is selected now.
+    """
+
+    reopen: Callable[[Optional[Path]], None]
+    offer: Callable[[frozenset[str]], None]
+
+
+class Commands:
+    """What the buttons and the menu entries do to the open project.
+
+    Each command asks the user what it needs, has the model do it,
+    and has the window show the project as it now stands with what
+    was made or moved selected in it. What could not be done is put
+    to the user in the words the model said it in, and the project
+    is left exactly as it was.
+    """
+
+    def __init__(self, window: Union[tkinter.Tk, tkinter.Toplevel],
+                 session: Session, hooks: WindowHooks) -> None:
+        """Get ready to act upon a project, with nothing selected yet.
+
+        Args:
+            window: The window that the questions are asked over.
+            session: What the run knows, which is the open project.
+            hooks: What the commands ask the window to do.
+        """
+        self.window = window
+        self.session = session
+        self.hooks = hooks
+        self.selection: Optional[Path] = None
+
+    def select(self, path: Optional[Path]) -> None:
+        """Take what the explorer has selected as what to act upon."""
+        self.selection = path
+
+    def note_shown(self, shown: bool) -> None:
+        """Offer afresh what can be done with what is selected.
+
+        Args:
+            shown: Whether the panel has a note to act on, which a
+                program other than notesmgr can take away at any time.
+        """
+        self.hooks.offer(offered(self.selected(shown)))
+
+    def selected(self, shown: bool) -> Selected:
+        """Return what is selected, as far as it says what can be done."""
+        path = self.selection
+        plain = shown and path is not None and is_plain_note(path.name)
+        return Selected(note=shown, plain=plain,
+                        project=self.session.project is not None,
+                        folder=self.chosen_folder() is not None)
+
+    def report_error(self, message: str) -> None:
+        """Tell the user what could not be done, and why it could not."""
+        show_error(self.window, NOTE_TITLE, message)
+
+    def report_notice(self, message: str) -> None:
+        """Tell the user of something that was done in another way."""
+        show_info(self.window, NOTE_TITLE, message)
+
+    def chosen_folder(self) -> Optional[Path]:
+        """Return the folder that is selected, None when none is.
+
+        The root folder of a project is the project itself rather
+        than a folder in it to be renamed or taken away, so it
+        counts as no folder here.
+        """
+        path = self.selection
+        if path is None or not path.is_dir() or is_project(path):
+            return None
+        return path
+
+    def note_folder(self) -> Optional[Path]:
+        """Return the folder that a new note or folder goes into.
+
+        That is the selected folder, the folder of the selected note,
+        and the root folder of the project while nothing is selected.
+        """
+        project = self.session.project
+        if project is None:
+            return None
+        path = self.selection
+        if path is None:
+            return project.root
+        return path if path.is_dir() else path.parent
+
+    def plain_note(self) -> Optional[Path]:
+        """Return the selected note that is no template, None for none."""
+        path = self.selection
+        if path is None or not is_plain_note(path.name) or not path.is_file():
+            return None
+        return path
+
+    def _extension(self) -> Optional[NoteExtension]:
+        """Return the extension the notes of the open project carry."""
+        config = self.session.config()
+        return None if config is None else config.file_extension
+
+    def done(self, doing: Callable[[], Optional[Path]]) -> Optional[Path]:
+        """Do what changes the project, and show it as it now stands.
+
+        Args:
+            doing: What is to be done, giving what is to be selected
+                afterwards and None when it leaves nothing to select.
+
+        Returns:
+            What was made or moved, None when the operation could not
+            be done at all or left nothing to select.
+        """
+        try:
+            given = doing()
+        except NotesmgrError as error:
+            self.report_error(str(error))
+            return None
+        self.hooks.reopen(given)
+        return given
+
+    def edit(self, note: Path) -> None:
+        """Open a note in the editor that the project is configured with."""
+        config = self.session.config()
+        if config is None:
+            return
+        try:
+            launch_editor(config.editor, note)
+        except NotesmgrError as error:
+            self.report_error(str(error))
+
+    def new_note(self) -> None:
+        """Make a note from the template and open it in the editor."""
+        folder = self.note_folder()
+        extension = self._extension()
+        if folder is None or extension is None:
+            return
+        typed = ask_name(self.window, NOTE_TITLE, ASK_NEW_NOTE)
+        if typed is None:
+            return
+        made = self.done(partial(note_ops.new_note, folder, typed, extension))
+        if made is not None:
+            self.edit(made)
+
+    def duplicate_note(self) -> None:
+        """Copy the selected note into a folder of the project."""
+        note = self.plain_note()
+        project = self.session.project
+        extension = self._extension()
+        if note is None or project is None or extension is None:
+            return
+        given = self._ask_copy(note, project)
+        if given is not None:
+            folder = folder_of(project.root, given.folder)
+            self.done(partial(note_ops.duplicate_note, note, folder,
+                              given.name, extension))
+
+    def _ask_copy(self, note: Path, project: Project) \
+            -> Optional[NameFolder]:
+        """Ask what a copy of a note is called and where it is put."""
+        root = project.root
+        given = NameFolder(name=note_stem(note.name) + COPY_SUFFIX,
+                           folder=shown_folder(root, note.parent))
+        return ask_name_folder(self.window, DUPLICATE_TITLE, given,
+                               self._folder_names(project))
+
+    @staticmethod
+    def _folder_names(project: Project) -> Sequence[str]:
+        """Return the folders of a project as they are named to the user."""
+        return [shown_folder(project.root, path)
+                for path in folder_paths(project.tree)]
+
+    def delete_note(self) -> None:
+        """Move the selected note to the trash, once the user is sure."""
+        note = self.plain_note()
+        if note is None:
+            return
+        if ask_yes_no(self.window, NOTE_TITLE,
+                      ASK_DELETE_NOTE.format(name=note.name)):
+            self.done(partial(note_ops.delete_note, note))
+
+    def move_up(self) -> None:
+        """Move the selected note one place up in its folder."""
+        self.move(-1)
+
+    def move_down(self) -> None:
+        """Move the selected note one place down in its folder."""
+        self.move(1)
+
+    def move(self, offset: int) -> None:
+        """Move the selected note so many places in its folder."""
+        note = self.plain_note()
+        if note is not None:
+            self.done(partial(note_ops.shift_note, note, offset))
+
+    def drop(self, item: Path, drop: Drop) -> None:
+        """Move what was dragged in the tree to where it was dropped.
+
+        Args:
+            item: The note or the folder that was dragged.
+            drop: Where it was dropped, as the tree worked it out.
+        """
+        self.done(partial(drop_item, item, drop))
+
+    def new_folder(self) -> None:
+        """Make a folder in the folder that is selected."""
+        parent = self.note_folder()
+        extension = self._extension()
+        if parent is None or extension is None:
+            return
+        typed = ask_name(self.window, FOLDER_TITLE, ASK_NEW_FOLDER)
+        if typed is None:
+            return
+        self.done(partial(folder_ops.new_folder, parent, typed, extension))
+
+    def rename_folder(self) -> None:
+        """Give the selected folder another name."""
+        folder = self.chosen_folder()
+        if folder is None:
+            return
+        asked = ASK_RENAME_FOLDER.format(name=folder.name)
+        typed = ask_name(self.window, FOLDER_TITLE, asked, folder.name)
+        if typed is not None:
+            self.done(partial(folder_ops.rename_folder, folder, typed))
+
+    def delete_folder(self) -> None:
+        """Move the selected folder to the trash, once the user is sure."""
+        folder = self.chosen_folder()
+        if folder is None:
+            return
+        if ask_yes_no(self.window, FOLDER_TITLE,
+                      ASK_DELETE_FOLDER.format(name=folder.name)):
+            self.done(partial(folder_ops.delete_folder, folder))