mdedit 0.1.0__py3-none-any.whl

mdedit/__init__.py

@@ -0,0 +1,3 @@
+"""mdedit — a terminal Markdown viewer and editor built with Textual."""
+
+__version__ = "0.1.0"

mdedit/__main__.py

@@ -0,0 +1,40 @@
+"""Command-line entry point for mdedit."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from mdedit import __version__
+from mdedit.app import MDEditApp
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mdedit",
+        description="A terminal Markdown viewer and editor.",
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        default=None,
+        help="Markdown file to open (created on first save if it doesn't exist yet)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"mdedit {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    file_path = Path(args.file).expanduser() if args.file else None
+    app = MDEditApp(file_path=file_path)
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

mdedit/app.py

@@ -0,0 +1,55 @@
+"""The mdedit Textual application."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual import work
+from textual.app import App
+
+from mdedit.document import Document, DocumentError
+from mdedit.screens.editor import EditorScreen
+from mdedit.screens.quit_confirm import QuitConfirmScreen
+from mdedit.screens.welcome import WelcomeScreen
+
+
+class MDEditApp(App[None]):
+    """A terminal Markdown viewer/editor."""
+
+    TITLE = "mdedit"
+    CSS_PATH = "styles/mdedit.tcss"
+
+    def __init__(self, file_path: Path | None = None) -> None:
+        super().__init__()
+        self._initial_path = file_path
+
+    def on_mount(self) -> None:
+        if self._initial_path is not None:
+            self.open_path(self._initial_path)
+        else:
+            self.push_screen(WelcomeScreen())
+
+    def open_path(self, path: Path) -> None:
+        """Load ``path`` as a Document and switch to the editor screen."""
+        try:
+            document = Document.from_path(path)
+        except DocumentError as exc:
+            self.notify(str(exc), severity="error", timeout=6)
+            return
+        self.push_screen(EditorScreen(document))
+
+    @work
+    async def action_quit(self) -> None:
+        screen = self.screen
+        document = getattr(screen, "document", None)
+        if document is not None and document.dirty:
+            choice = await self.push_screen_wait(QuitConfirmScreen())
+            if choice == "cancel":
+                return
+            if choice == "save":
+                try:
+                    document.save()
+                except DocumentError as exc:
+                    self.notify(str(exc), severity="error", timeout=6)
+                    return
+        self.exit()

mdedit/document.py

@@ -0,0 +1,105 @@
+"""Core document model.
+
+This module is intentionally free of any Textual (or other UI-framework)
+imports. It is the seam between the on-disk file and whichever widget is
+currently displaying it (rendered view or source editor), so that a future
+"always-rendered" WYSIWYG editing mode could be layered in later behind the
+same narrow interface (``.text`` / ``.set_text()`` / ``.dirty``) without
+rewriting the screens or widgets that consume it today.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class DocumentError(Exception):
+    """Raised when a document fails to load or save."""
+
+
+class Document:
+    """An in-memory Markdown document, optionally backed by a file on disk."""
+
+    def __init__(self, path: Path | None = None, text: str = "") -> None:
+        self.path = path
+        self._text = text
+        self._saved_text = text
+        self._dirty = False
+
+    def __repr__(self) -> str:
+        return f"Document(path={self.path!r}, dirty={self._dirty!r})"
+
+    @classmethod
+    def from_path(cls, path: Path) -> Document:
+        """Load a document from ``path``.
+
+        If ``path`` does not exist, an empty new document is returned with
+        ``path`` pre-set (matching common editor UX: the file is created on
+        first save). Genuine I/O errors (permission denied, path is a
+        directory, etc.) raise :class:`DocumentError`.
+        """
+        path = Path(path)
+        if not path.exists():
+            return cls(path=path, text="")
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise DocumentError(f"Could not read {path}: {exc}") from exc
+        return cls(path=path, text=text)
+
+    @property
+    def text(self) -> str:
+        """The current in-memory content."""
+        return self._text
+
+    def set_text(self, new_text: str) -> None:
+        """Replace the in-memory content, updating the dirty flag."""
+        self._text = new_text
+        self._dirty = self._text != self._saved_text
+
+    @property
+    def dirty(self) -> bool:
+        """Whether the in-memory content differs from what's on disk."""
+        return self._dirty
+
+    @property
+    def is_new(self) -> bool:
+        """Whether this document has no backing file yet."""
+        return self.path is None
+
+    @property
+    def display_name(self) -> str:
+        """A short, human-readable name for status/title display."""
+        return self.path.name if self.path is not None else "untitled.md"
+
+    def save(self, path: Path | None = None) -> None:
+        """Write the current content to disk.
+
+        Pass ``path`` to save-as; otherwise saves to the document's existing
+        path. Raises :class:`DocumentError` if there is no path to save to,
+        or if the write fails.
+        """
+        target = path if path is not None else self.path
+        if target is None:
+            raise DocumentError("No path to save to")
+        target = Path(target)
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(self._text, encoding="utf-8")
+        except OSError as exc:
+            raise DocumentError(f"Could not write {target}: {exc}") from exc
+        self.path = target
+        self._saved_text = self._text
+        self._dirty = False
+
+    def reload(self) -> None:
+        """Discard in-memory changes and re-read the file from disk."""
+        if self.path is None:
+            raise DocumentError("Cannot reload a document with no path")
+        try:
+            text = self.path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise DocumentError(f"Could not read {self.path}: {exc}") from exc
+        self._text = text
+        self._saved_text = text
+        self._dirty = False

mdedit/screens/editor.py

@@ -0,0 +1,102 @@
+"""The main screen: a view/edit toggle over a single Document."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.screen import Screen
+from textual.widgets import ContentSwitcher, Footer, Header
+
+from mdedit.document import Document, DocumentError
+from mdedit.widgets.source_editor import SourceEditor
+from mdedit.widgets.status_bar import StatusBar
+from mdedit.widgets.viewer import DocumentViewer
+
+
+class EditorScreen(Screen):
+    """Displays a Document in either rendered (view) or source (edit) mode."""
+
+    BINDINGS = [
+        ("ctrl+t", "toggle_mode", "Toggle view/edit"),
+        ("ctrl+s", "save", "Save"),
+        ("ctrl+r", "reload", "Reload"),
+    ]
+
+    VIEW_ID = "viewer"
+    EDIT_ID = "editor"
+
+    DEFAULT_CSS = """
+    EditorScreen > Vertical {
+        height: 1fr;
+    }
+
+    EditorScreen ContentSwitcher {
+        height: 1fr;
+    }
+    """
+
+    def __init__(self, document: Document) -> None:
+        super().__init__()
+        self.document = document
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Vertical():
+            with ContentSwitcher(initial=self.VIEW_ID):
+                yield DocumentViewer(id=self.VIEW_ID, show_table_of_contents=True)
+                yield SourceEditor.for_document(self.document, id=self.EDIT_ID)
+            yield StatusBar()
+        yield Footer()
+
+    async def on_mount(self) -> None:
+        await self.query_one(DocumentViewer).load_document(self.document)
+        self._refresh_status()
+
+    @property
+    def mode(self) -> str:
+        switcher = self.query_one(ContentSwitcher)
+        return "EDIT" if switcher.current == self.EDIT_ID else "VIEW"
+
+    def _refresh_status(self) -> None:
+        self.query_one(StatusBar).update_status(self.document, self.mode)
+        self.title = self.document.display_name
+
+    async def action_toggle_mode(self) -> None:
+        switcher = self.query_one(ContentSwitcher)
+        if switcher.current == self.EDIT_ID:
+            # Leaving edit mode: sync the editor's text back into the
+            # Document before switching, so view mode always reflects the
+            # latest edits.
+            source = self.query_one(SourceEditor).text
+            self.document.set_text(source)
+            await self.query_one(DocumentViewer).load_document(self.document)
+            switcher.current = self.VIEW_ID
+        else:
+            switcher.current = self.EDIT_ID
+            self.query_one(SourceEditor).focus()
+        self._refresh_status()
+
+    def action_save(self) -> None:
+        # If currently in edit mode, make sure in-flight edits are captured
+        # before writing to disk.
+        if self.mode == "EDIT":
+            self.document.set_text(self.query_one(SourceEditor).text)
+        try:
+            self.document.save()
+        except DocumentError as exc:
+            self.notify(str(exc), severity="error")
+        else:
+            self.notify(f"Saved {self.document.display_name}")
+        self._refresh_status()
+
+    async def action_reload(self) -> None:
+        try:
+            self.document.reload()
+        except DocumentError as exc:
+            self.notify(str(exc), severity="error")
+            return
+        self.query_one(SourceEditor).text = self.document.text
+        if self.mode == "VIEW":
+            await self.query_one(DocumentViewer).load_document(self.document)
+        self.notify(f"Reloaded {self.document.display_name}")
+        self._refresh_status()

mdedit/screens/quit_confirm.py

@@ -0,0 +1,54 @@
+"""Modal shown when quitting with unsaved changes."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Button, Label
+
+
+class QuitConfirmScreen(ModalScreen[str]):
+    """Ask the user whether to save, discard, or cancel before quitting.
+
+    Dismisses with one of ``"save"``, ``"discard"``, or ``"cancel"``.
+    """
+
+    DEFAULT_CSS = """
+    QuitConfirmScreen {
+        align: center middle;
+    }
+
+    QuitConfirmScreen > Vertical {
+        width: auto;
+        height: auto;
+        border: thick $panel;
+        padding: 1 2;
+    }
+
+    QuitConfirmScreen Label {
+        width: 100%;
+        content-align: center middle;
+        padding-bottom: 1;
+    }
+
+    QuitConfirmScreen Horizontal {
+        width: auto;
+        height: auto;
+    }
+
+    QuitConfirmScreen Button {
+        margin: 0 1;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        with Vertical():
+            yield Label("You have unsaved changes. Save before quitting?")
+            with Horizontal():
+                yield Button("Save", id="save", variant="success")
+                yield Button("Discard", id="discard", variant="error")
+                yield Button("Cancel", id="cancel")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        self.dismiss(event.button.id)

mdedit/screens/welcome.py

@@ -0,0 +1,47 @@
+"""Shown on startup when no file was given on the command line."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.screen import Screen
+from textual.widgets import Footer, Header, Input, Static
+
+
+class WelcomeScreen(Screen):
+    """Prompt for a Markdown file path to open (or create)."""
+
+    DEFAULT_CSS = """
+    WelcomeScreen {
+        align: center middle;
+    }
+
+    WelcomeScreen > Vertical {
+        width: 60;
+        height: auto;
+        border: thick $panel;
+        padding: 1 2;
+    }
+
+    WelcomeScreen Static {
+        padding-bottom: 1;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Vertical():
+            yield Static("mdedit — open or create a Markdown file")
+            yield Input(placeholder="path/to/file.md", id="path-input")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one(Input).focus()
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        value = event.value.strip()
+        if not value:
+            return
+        self.app.open_path(Path(value).expanduser())

mdedit/styles/mdedit.tcss

@@ -0,0 +1,6 @@
+/* Global styles for mdedit. Most widgets rely on Textual's defaults; this
+   file only overrides what needs project-specific tweaks. */
+
+Screen {
+    background: $surface;
+}

mdedit/widgets/source_editor.py

@@ -0,0 +1,25 @@
+"""The editable, syntax-highlighted source view of a Document."""
+
+from __future__ import annotations
+
+from textual.widgets import TextArea
+
+from mdedit.document import Document
+
+
+class SourceEditor(TextArea):
+    """A TextArea configured for editing Markdown source."""
+
+    @classmethod
+    def for_document(cls, document: Document, id: str | None = None) -> SourceEditor:
+        """Build a SourceEditor pre-populated with ``document``'s text."""
+        editor = cls.code_editor(
+            document.text,
+            language="markdown",
+            theme="monokai",
+            soft_wrap=True,
+            tab_behavior="indent",
+            id=id,
+        )
+        editor.show_line_numbers = False
+        return editor

mdedit/widgets/status_bar.py

@@ -0,0 +1,33 @@
+"""A small status bar: filename, dirty indicator, current mode."""
+
+from __future__ import annotations
+
+from textual.reactive import reactive
+from textual.widgets import Static
+
+from mdedit.document import Document
+
+
+class StatusBar(Static):
+    """Shows the open file's name, dirty state, and view/edit mode."""
+
+    # Deliberately NOT docked: EditorScreen's Footer already docks to the
+    # bottom of the screen, and a second bottom-docked widget in the same
+    # container overlaps it exactly rather than stacking above it. Instead
+    # StatusBar is a normal flow child placed just above the Footer, inside
+    # a wrapping Vertical (see EditorScreen).
+    DEFAULT_CSS = """
+    StatusBar {
+        height: 1;
+        background: $panel;
+        color: $text-muted;
+        padding: 0 1;
+    }
+    """
+
+    mode: reactive[str] = reactive("VIEW")
+
+    def update_status(self, document: Document, mode: str) -> None:
+        self.mode = mode
+        dirty = " •" if document.dirty else ""
+        self.update(f"{document.display_name}{dirty}  —  {mode}")

mdedit/widgets/viewer.py

@@ -0,0 +1,15 @@
+"""The read-only rendered view of a Document."""
+
+from __future__ import annotations
+
+from textual.widgets import MarkdownViewer
+
+from mdedit.document import Document
+
+
+class DocumentViewer(MarkdownViewer):
+    """A MarkdownViewer bound to a :class:`~mdedit.document.Document`."""
+
+    async def load_document(self, document: Document) -> None:
+        """Render ``document``'s current text."""
+        await self.document.update(document.text)

mdedit-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: mdedit
+Version: 0.1.0
+Summary: A terminal Markdown viewer and editor built with Textual
+Project-URL: Homepage, https://github.com/matplo/mdedit
+Project-URL: Repository, https://github.com/matplo/mdedit
+Author-email: matplo <ploskon@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: editor,markdown,terminal,textual,tui
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals
+Classifier: Topic :: Text Editors
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.7
+Requires-Dist: textual[syntax]<9,>=8.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: textual-dev; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mdedit
+
+A terminal Markdown viewer and editor, built with
+[Textual](https://github.com/Textualize/textual) and
+[Rich](https://github.com/Textualize/rich).
+
+Open a `.md` file to a fully rendered view (headings, tables, code blocks,
+lists, block quotes...) and press a single key to toggle into a
+syntax-highlighted source editor for the same file — then toggle back to see
+your changes rendered.
+
+## Install
+
+```bash
+pip install git+https://github.com/matplo/mdedit
+```
+
+## Usage
+
+```bash
+mdedit path/to/file.md   # open (or create) a file
+mdedit                   # start with a prompt to open/create a file
+```
+
+### Key bindings
+
+| Key      | Action                          |
+|----------|----------------------------------|
+| `ctrl+t` | Toggle between view and edit mode |
+| `ctrl+s` | Save                              |
+| `ctrl+r` | Reload from disk                  |
+| `ctrl+q` | Quit (prompts if unsaved changes) |
+
+> **Note:** if `ctrl+s` doesn't seem to do anything in your terminal, it may
+> be intercepted by terminal flow control (XON/XOFF). Run `stty -ixon` in
+> your shell first, or use the Save option from the command palette
+> (`ctrl+p`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+ruff format --check .
+```
+
+### Releasing to PyPI
+
+Releases publish automatically via GitHub Actions using
+[trusted publishing](https://docs.pypi.org/trusted-publishers/) (no API
+token stored anywhere). To cut a release:
+
+1. Bump `__version__` in `src/mdedit/__init__.py`, commit it.
+2. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`
+3. The `Publish to PyPI` workflow builds the sdist/wheel and uploads them.
+
+## Roadmap
+
+v1 is intentionally scoped to a single-file, toggle-based view/edit
+experience. Not yet included (candidates for a future version):
+
+- Always-rendered, true WYSIWYG editing (edit directly on rendered text,
+  no separate source view)
+- Split-pane side-by-side edit + preview
+- Browser-style navigation history, bookmarks, remote/URL loading
+- Multiple open files / tabs
+
+## License
+
+MIT

mdedit-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+mdedit/__init__.py,sha256=6nvmAQxGX91qhslvshvDCMrgguixzp8tG-rPVmkkuW4,98
+mdedit/__main__.py,sha256=n881eX_eppF5E8swG6W3AILLKPmTCEPhskvMZ85vbl0,952
+mdedit/app.py,sha256=I8mlNXIvADdQKDhkkYlpeTygzk0J0p-YIgJpu17fzG0,1724
+mdedit/document.py,sha256=IrGoyotEJRtDSrwKl7LopBFARFyqO5T7X4JGcvOtKyc,3762
+mdedit/screens/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mdedit/screens/editor.py,sha256=seYYo8aeAwqdYtw5JEtdwMW7yhu_pfTU12I84M8i5oo,3516
+mdedit/screens/quit_confirm.py,sha256=SSPYApFmlSBYffKrw8v7xagnaBOI6Dclzk2C1iqZSuw,1419
+mdedit/screens/welcome.py,sha256=OYVLLdfvWi2gCPcAcL0tFe70euCl44T27PCxXujKBjE,1195
+mdedit/styles/mdedit.tcss,sha256=xzIOl1pQDoesI2MYjaDa6pLlB2vohxpLfw8qLtbat-4,175
+mdedit/widgets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mdedit/widgets/source_editor.py,sha256=lpvyxfHiW2vKU9KV_O9yKGq8cp1f4wT4LzW_1Svyocs,728
+mdedit/widgets/status_bar.py,sha256=rjgb0zIwn2TUCYcARptv9HaO3sT4DuJyEuhK61RAxoY,1063
+mdedit/widgets/viewer.py,sha256=NuJeOV9WaiR86nimG0W3svP5H6IQ6D5hntfrLxxVHJc,445
+mdedit-0.1.0.dist-info/METADATA,sha256=mJ3fyFNL0v7MQwtiol9mDKgjw9mMAs6lfHswCLoI4QE,3217
+mdedit-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mdedit-0.1.0.dist-info/entry_points.txt,sha256=rWiWFUVHpkV3IK_qIKvx1oqF-VnZzrslwz2NRkEGBek,48
+mdedit-0.1.0.dist-info/licenses/LICENSE,sha256=FdvapQASUK3J-7zKooV8mCVgxSTQvLoNS4JV7YAiDvw,1063
+mdedit-0.1.0.dist-info/RECORD,,

mdedit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mdedit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mdedit = mdedit.__main__:main

mdedit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matplo
+
+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.