notesmgr 0.1.0__tar.gz

notesmgr-0.1.0/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Tom Björkholm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

notesmgr-0.1.0/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: notesmgr
+Version: 0.1.0
+Summary: Manager for small notes and AI prompts.
+Author: Tom Björkholm
+Author-email: Tom Björkholm <klausuler_linnet0q@icloud.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tom-bjorkholm/notesmgr
+Project-URL: Source code, https://github.com/tom-bjorkholm/notesmgr
+Project-URL: Documentation, https://github.com/tom-bjorkholm/notesmgr/blob/master/doc
+Keywords: notes,prompts,AI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Information Technology
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: argcomplete>=3.7.2
+Requires-Dist: edit-cfg-json-tk>=0.4.0
+Requires-Dist: edit-cfg-json>=0.4.0
+Requires-Dist: config-as-json>=1.7
+Requires-Dist: markdown>=3.11
+Requires-Dist: types-Markdown>=3.10.2.20260712
+Requires-Dist: packaging>=26.3
+Requires-Dist: send2trash>=2.1.0
+Requires-Dist: types-Send2Trash>=2.1.0.20260408
+Requires-Dist: versionreporter>=0.4
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+
+# notesmgr - Managing small notes and AI prompts
+
+## What it does
+
+`notesmgr` is a small desktop application that keeps small notes and AI
+prompts in order. It is made for the texts you keep coming back to: the
+prompts you paste into an AI assistant, snippets, checklists, and short
+notes.
+
+- Notes are ordinary text files in ordinary folders, so they can be kept
+  in git, synced, backed up and edited with any editor.
+- The notes of a folder are kept in an order of your choosing, and are
+  reordered with a button, a key or by dragging.
+- A note is edited in the editor you already use, such as Visual Studio
+  Code, and the note shown in `notesmgr` follows as you save.
+- Every folder has a template that each new note of the folder starts
+  from.
+- A note is copied to the clipboard with one key, either as it is
+  written or formatted, so that pasting it into Mail, Word or Slack keeps
+  headings, lists and bold text.
+- Notes written in markdown are shown formatted for reading.
+
+It runs on macOS, Microsoft Windows and Linux.
+
+## Installing
+
+`notesmgr` needs Python 3.12 or newer, with Tk (tkinter). Install it
+from [PyPI](https://pypi.org/project/notesmgr):
+
+On macOS and Linux:
+
+````sh
+pip3 install --upgrade notesmgr
+````
+
+On Microsoft Windows:
+
+````sh
+pip install --upgrade notesmgr
+````
+
+The Python from python.org has Tk built in on macOS and on Windows.
+On Linux Tk is often a package of its own, such as `python3-tk` on
+Debian and Ubuntu. Copying a note formatted needs `xclip` (X11) or
+`wl-copy` (Wayland) on Linux; without them the note is copied as
+plain text.
+
+## Getting started
+
+1. Start `notesmgr`.
+2. Choose `File` → `New project…` and pick a folder. It can be an empty
+   folder or one that already holds notes, which are then taken in.
+3. Press `New` (`Cmd+N` on mac, `Ctrl+N` elsewhere), give the note a
+   name, and write it in the editor that opens.
+4. Select the note in the tree to the left to read it, and press
+   `Copy raw` (`Cmd+C` / `Ctrl+C`) to put it on the clipboard.
+
+Next time, open the project with `File` → `Open project…`, or name it
+on the command line: `notesmgr ~/notes`.
+
+## Using notesmgr
+
+### The main window
+
+To the left is the tree of the project: its folders, and in each
+folder the template of the folder followed by its notes in their order.
+Subfolders come first, in alphabetical order.
+
+To the right is the selected note with a row of buttons above it. A
+note whose name ends with `.md` or `.md.txt` is shown formatted, and a
+note ending with `.txt` is shown exactly as it is written. When a note
+is changed by your editor or by any other program, the note shown
+follows about a second later.
+
+A new note or folder is made in the selected folder, in the folder of
+the selected note, or in the root folder of the project when nothing is
+selected.
+
+### Buttons and keyboard shortcuts
+
+Every button is also in the `Note` menu. On mac the shortcuts use `Cmd`,
+and on Windows and Linux they use `Ctrl`.
+
+| Button | Shortcut | What it does |
+| --- | --- | --- |
+| `Copy raw` | `Cmd+C` | Copies the note as it is written. When part of the note is selected, the key copies just that part. |
+| `Copy formatted` | `Cmd+Shift+C` | Copies the note formatted, for pasting into Mail, Word, Slack and the like. |
+| `Duplicate` | `Cmd+D` | Copies the note, under a name and into a folder you choose. |
+| `Edit` | `Cmd+E` | Opens the note in your editor. `Return` in the tree does the same. |
+| `New` | `Cmd+N` | Makes a note from the template of the folder and opens it in your editor. |
+| `Delete` | `Cmd+Backspace` | Moves the note to the trash, after asking. |
+| `Up` | `Cmd+Up` | Moves the note one place up. |
+| `Down` | `Cmd+Down` | Moves the note one place down. |
+
+The other shortcuts are:
+
+| Shortcut | What it does |
+| --- | --- |
+| `Cmd+Shift+N` | Makes a folder (`Folder` → `New folder…`). |
+| `Cmd++`, `Cmd+-`, `Cmd+0` | Draws the note and the tree larger, smaller, and in the normal size again (`View` menu). |
+| `Cmd+W` on mac, `Ctrl+Q` elsewhere | Quits. |
+| `Tab` | Goes from the tree to the buttons and on to the note. |
+
+The template of a folder is shown, edited and copied like any note,
+but it cannot be duplicated, deleted or moved: every folder has exactly
+one template.
+
+### Dragging
+
+Notes and folders can be dragged in the tree. A note dropped above or
+below another note is moved to that place, and a note dropped on a
+folder is moved to the end of that folder. A folder dropped on another
+folder is moved into it with everything it holds. While you drag, a
+line shows where a note would land and the folder that would take it is
+marked. `Escape` gives up the drag. A name that the other folder holds
+already is refused rather than moved.
+
+### Folders
+
+The `Folder` menu makes, renames and deletes folders of the project. A
+new folder starts with a copy of the template of the folder above it. A
+folder can be renamed at any time, and is deleted, to the trash, only
+when it holds no notes and no folders. The root folder of the project
+is renamed and deleted outside `notesmgr`.
+
+### Configuration
+
+`Configuration` → `Edit configuration…` edits the configuration of the
+open project, which is stored in `notesmgr.cfg` in the root folder of the
+project. It holds:
+
+- `editor`: the command that opens a note. `{file}` stands for the note,
+  and the note is put last when the command has no `{file}`, so `code`
+  and `code {file}` mean the same thing. For a new configuration it is
+  Visual Studio Code (`code`) when that is installed, otherwise the
+  editor that `$EDITOR` names, otherwise `open` on mac, Notepad on
+  Windows and `emacs` elsewhere.
+- `file_extension`: what new notes are called, one of `.md.txt` (the
+  default), `.md` and `.txt`. `.md.txt` is the default because many
+  systems do not see `.md` as a safe kind of file.
+- `max_note_size`: how many characters of a note are shown, from 2000 to
+  100000 and 25000 unless you say otherwise. A longer note is shown up to
+  there, with a warning above it.
+
+A configuration file looks like this:
+
+````json
+{
+    "editor": "code -n {file}",
+    "file_extension": "MD_TXT",
+    "max_note_size": 25000
+}
+````
+
+`Configuration` → `Save configuration as user wide…` makes the
+configuration of the project the one that every new project starts
+with. With no project open, `Edit configuration…` edits that user wide
+configuration.
+
+### Command line
+
+````sh
+notesmgr [PROJECT_FOLDER]
+notesmgr --version
+````
+
+Started with a folder, `notesmgr` opens the project in it. `--version`
+reports the versions of `notesmgr` and of the packages it uses, and
+which newer releases there are, just as `Help` → `Version information…`
+does.
+
+## Details
+
+This section says what `notesmgr` does in the cases where you might
+wonder.
+
+### The files of a project
+
+- `notesmgr.cfg` in the root folder holds the configuration of the
+  project.
+- Every folder holds one template, `template.md.txt`, `template.md` or
+  `template.txt` after the `file_extension` of the project.
+- Every folder holds a hidden `.notes_order.txt` that lists the notes of
+  the folder, one name per line, in the order they are shown. Folders
+  are not listed in it.
+- Every other file ending with `.txt`, `.md` or `.md.txt` is a note.
+
+All of these can be edited with any text editor while `notesmgr` is not
+looking. Deleting a note, a folder or a template always moves it to the
+trash of the operating system, so it can be taken back.
+
+### What opening a project puts in order
+
+- `.notes_order.txt` is repaired: names of notes that are gone are
+  removed, and notes it does not name are added at the end in
+  alphabetical order. A folder whose `.notes_order.txt` cannot be read or
+  written is reported, and its notes are shown in alphabetical order.
+- A folder without a template gets one: an empty one in the root
+  folder, and a copy of the template of the folder above it elsewhere.
+- A template whose extension is not the `file_extension` of the project
+  is renamed, and you are told so. Changing `file_extension` therefore
+  renames the templates the next time the project is opened.
+- A folder holding more than one template is the one thing `notesmgr`
+  cannot decide for you. You are asked which one to keep, and the others
+  go to the trash. Answering nothing leaves every file as it is, and the
+  project is not opened.
+
+### What a formatted note shows
+
+Headings, paragraphs, bold, italic, `~~struck through~~` text, code in a
+line and code blocks, lists nested as deeply as you like, tables, block
+quotes, horizontal lines, and the text of links. PNG and GIF images next
+to the note are drawn where the note shows them, and other images are
+named by their description. HTML in a note is shown as the text it is.
+A note that is not valid UTF-8 is not shown, and says why.
+
+### How `Copy formatted` works
+
+The note goes on the clipboard as rich text and as plain text, so that
+an application that takes formatting gets it, and a plain text field
+gets the note as it is written. A note that is not markdown is copied
+as preformatted text, so that a table lined up by hand stays lined up.
+It uses what the operating system already has: `textutil` and
+`osascript` on mac, the Windows clipboard itself, and `xclip` or
+`wl-copy` on Linux. When the tool it needs is missing, the note is
+copied as plain text and you are told why.
+
+### Where the user wide configuration is
+
+It is read from the file that `$NOTESMGR_CFG` names, when that file
+exists, otherwise from `~/.notesmgr.cfg`, and otherwise the built-in
+defaults are used. It is written to the file that `$NOTESMGR_CFG`
+names, whether that file exists yet or not, and to `~/.notesmgr.cfg`
+when the variable is not set.
+
+### What is remembered
+
+Nothing is remembered from one run to the next: not the last project,
+not the size of the window, and not the size of the text. Within one
+run, the folder chooser starts in the project opened last.
+
+## What notesmgr is built on
+
+`notesmgr` uses `config-as-json` and `edit-cfg-json-tk` for its
+configuration, `markdown` for reading notes written in markdown,
+`versionreporter` for the version report, `argcomplete` for the command
+line, and `Send2Trash` for moving files to the trash.
+
+## Source code
+
+Source code and tests are available at
+[https://github.com/tom-bjorkholm/notesmgr](https://github.com/tom-bjorkholm/notesmgr).
+
+## Test summary
+
+- Test result: 1489 passed, 13 deselected in 7s
+- No flake8 warnings.
+- No mypy errors found.
+- No pylint warnings.
+- No python layout warnings.
+- Built version(s): 0.1.0
+- Build and test using Python 3.14.7

notesmgr-0.1.0/README.md

@@ -0,0 +1,156 @@
+# notesmgr
+
+## What it does
+
+Notes manager is a very small application to keep small notes
+and AI prompts files ordered. The main intended functionality includes:
+
+- Keeping a project with folders of notes (that is small text files)
+- Keeping the notes in a defined order, and allowing them to be
+  reordered.
+- Opening an external editor to create and edit notes.
+- Keeping a template in each folder that will be prefilled into
+  each new notes file.
+
+## Using it
+
+If you want to use it, install it using pip from
+
+[https://pypi.org/project/notesmgr](https://pypi.org/project/notesmgr).
+
+There is no need to download anything from GitHub to use the application
+or to base your code on the library.
+
+### Installing on macOS and Linux
+
+````sh
+pip3 install --upgrade notesmgr
+````
+
+### Installing on Microsoft Windows
+
+````sh
+pip install --upgrade notesmgr
+````
+
+### Information for use
+
+To learn how to use notesmgr please see 
+[https://pypi.org/project/notesmgr](https://pypi.org/project/notesmgr)
+or [README_pypi.md](README_pypi.md).
+
+For the code documentation generated from the docstrings, see
+[doc/api.md](doc/api.md).
+
+## Cloning
+
+**Note: Repository is not yet uploaded to GitHub.**
+
+This repository uses submodules. Clone it with:
+
+```sh
+git clone --recurse-submodules git@github.com:tom-bjorkholm/notesmgr.git
+```
+
+If you already cloned without submodules, initialize them with:
+
+```sh
+git submodule update --init --recursive
+```
+
+To update the checked-out submodule revisions:
+
+```sh
+git submodule update --remote --merge
+```
+
+## Supported Python versions
+
+- Package runtime baseline: Python 3.12 or newer
+- Maintainer validation target: Python 3.12, 3.13, and 3.14
+- Main day-to-day development: usually the newest supported Python version
+
+## Development workflow
+
+On macOS and Linux, the normal workflow is:
+
+1. Run `./run_setup_build_environment.py` once after cloning or when the
+   build environment needs to be recreated.
+2. Run `./run_build.py` for the normal build-and-test cycle.
+3. Run `./run_clean_build.py` before review or release work that needs a
+   completely fresh build.
+
+The helper scripts are:
+
+- `run_setup_build_environment.py`
+  Create or refresh the build environment.
+- `run_build.py`
+  Build the package and run the configured checks in the project virtual
+  environment.
+- `run_clean.py`
+  Remove files generated by the build system.
+- `run_clean_build.py`
+  Perform a clean build from scratch. This is especially useful because some
+  duplicate-code diagnostics only appear on a clean build.
+- `run_pypi_build.py`
+  Create the distribution artifacts intended for PyPI publishing.
+- `run_static_checks.py`
+  Run mypy, flake8, python-layout and pylint on the named files only, for
+  fast iteration while editing. It does not update the virtual environment,
+  so imports from `./venv` are not refreshed.
+- `run_focus_sensitive_tests.py`
+  Run the GUI tests that need an unlocked display and an uninterrupted
+  focused window. These are excluded from the normal build, and the
+  computer must be left alone while they run.
+
+The standard verification suite includes pytest, pylint, flake8, mypy and
+python-layout. After a build, the generated reports can be browsed through
+`reports/index.html`.
+
+After running `run_build.py` or `run_clean_build.py`, you can manually test
+the built and installed application in the virtual environment `./venv`.
+
+## How the code is organised
+
+All code is in the single package `src/notesmgr`, and every source module
+has one test module in `test/test_notesmgr`. The code is split in two
+layers:
+
+- **Model, free of Tk.** Everything that has a right answer: which note
+  is at which place, whether a name can be used, how `.notes_order.txt`
+  is repaired, what the editor command line is, and what goes on the
+  clipboard. Examples are `project.py`, `project_ops.py`, `note_ops.py`,
+  `folder_ops.py`, `order_file.py`, `explorer_drop.py`, `note_blocks.py`
+  and `rich_clipboard.py`. These are tested without a display.
+- **View, thin Tk.** Widgets that show what the model says and call the
+  model: `main_window.py`, `explorer_tree.py`, `note_panel.py`,
+  `note_view.py`, `dialogs.py` and the others. They are tested with a real
+  Tk root window that is never shown.
+
+What cannot be done is raised as `NotesmgrError`, with a message meant for
+the user, and the view shows it in a message box. Anything else that fails
+inside a Tk callback is shown in a window with its traceback by
+`failure_report.py`, because a program started from a desktop has no
+terminal. On Windows, the `gui-scripts` entry point has no standard
+streams at all, so `console.py` shows command line errors in a window.
+
+The keyboard shortcuts are listed in `shortcuts.py`, one entry per action,
+and are shown as accelerators on the menu entries of the same actions.
+
+The implementation plan and the decisions taken step by step are in
+`.plans/initials_steps.md`.
+
+## Manual tests before a release
+
+Run `./run_focus_sensitive_tests.py` and leave the computer alone while
+it runs.
+
+## Test summary
+
+- Test result: 1489 passed, 13 deselected in 7s
+- No flake8 warnings.
+- No mypy errors found.
+- No pylint warnings.
+- No python layout warnings.
+- Built version(s): 0.1.0
+- Build and test using Python 3.14.7