zen-timer 0.2.0__py3-none-any.whl

zen/__init__.py

@@ -0,0 +1 @@
+"""Zen - Deep-work terminal timer."""

zen/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point for the zen-timer application."""
+from zen.timer import app
+
+
+def main() -> None:
+    """Run the main application."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

zen/timer.py

@@ -0,0 +1,174 @@
+"""Zen - Deep-work terminal timer."""
+import time
+import typer
+# pylint: disable=import-outside-toplevel
+# Import rich lazily inside the command for faster --help execution
+
+app = typer.Typer(
+    help="🧘 Deep-work terminal timer for focus sessions.",
+    add_completion=False,
+    rich_markup_mode=None,
+)
+
+
+def version_callback(value: bool) -> None:
+    """Callback for the --version option."""
+    if value:
+        import importlib.metadata  # pylint: disable=import-outside-toplevel
+        try:
+            version = importlib.metadata.version("zen-timer")
+        except importlib.metadata.PackageNotFoundError:
+            version = "unknown"
+        print(f"zen-timer version {version}")
+        raise typer.Exit()
+
+
+@app.command()  # type: ignore[untyped-decorator]
+def focus(  # pylint: disable=too-many-statements,too-many-branches
+    minutes: int = typer.Argument(
+        25, min=1, max=1440, help="Minutes to focus for"
+    ),
+    is_break: bool = typer.Option(
+        False, "--break", help="Start a break session."
+    ),
+    silent: bool = typer.Option(
+        False, "--silent", help="Run without desktop notifications."
+    ),
+    version: bool = typer.Option(  # pylint: disable=unused-argument
+        None,
+        "--version",
+        callback=version_callback,
+        is_eager=True,
+        help="Show the application version and exit."
+    )
+) -> None:
+    """Start a deep-work focus session."""
+    # pylint: disable=too-many-locals
+    seconds = minutes * 60
+    console = None
+
+    try:
+        from rich.console import Console
+        from rich.progress import (
+            Progress, BarColumn, TextColumn, TimeRemainingColumn
+        )
+        from rich.panel import Panel
+
+        console = Console()
+        console.clear()
+        minute_str = "Minute" if minutes == 1 else "Minutes"
+        if is_break:
+            title_text = (
+                f"[bold green]☕ Break Time: {minutes} "
+                f"{minute_str}[/bold green]\n"
+                "[gray]Rest and recharge.[/gray]"
+            )
+            border_style = "green"
+            task_desc = "[green]Recharging..."
+            bar_complete_style = "green"
+        else:
+            title_text = (
+                f"[bold cyan]🧘 Zen Mode Activated: {minutes} "
+                f"{minute_str} of Deep Work[/bold cyan]\n"
+                "[gray]Do not disturb. No GUI, just flow.[/gray]"
+            )
+            border_style = "cyan"
+            task_desc = "[cyan]Flow State..."
+            bar_complete_style = "cyan"
+
+        title = Panel.fit(
+            title_text,
+            border_style=border_style,
+            padding=(1, 4)
+        )
+        console.print(title, justify="center")
+        console.print("\n")
+
+        with Progress(
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(
+                bar_width=None,
+                style="magenta",
+                complete_style=bar_complete_style,
+                finished_style=bar_complete_style
+            ),
+            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+            TimeRemainingColumn(),
+            console=console,
+            transient=False,
+            auto_refresh=False,  # Disable background thread for performance
+        ) as progress:
+            task = progress.add_task(task_desc, total=seconds)
+
+            start_time = time.monotonic()
+            last_second = -1
+
+            while True:
+                elapsed = time.monotonic() - start_time
+                remaining = seconds - elapsed
+
+                if remaining <= 0:
+                    progress.update(task, completed=seconds, refresh=True)
+                    break
+
+                # Only refresh UI when a full second has passed
+                current_second = int(elapsed)
+                if current_second > last_second:
+                    progress.update(
+                        task, completed=elapsed, refresh=True
+                    )
+                    last_second = current_second
+
+                # Recalculate elapsed to natively absorb loop execution
+                # overhead
+                elapsed = time.monotonic() - start_time
+                remaining = seconds - elapsed
+
+                # Drift-compensated sleep to maintain exact 1Hz refresh rate
+                sleep_interval = 1.0 - (elapsed % 1.0)
+                time.sleep(max(0, min(sleep_interval, remaining)))
+
+        console.print("\n")
+        if not silent:
+            console.bell()
+
+        if is_break:
+            completion = Panel.fit(
+                "[bold cyan]✨ Break complete. Ready to focus?[/bold cyan]",
+                border_style="cyan"
+            )
+        else:
+            completion = Panel.fit(
+                "[bold green]✨ Focus session complete. "
+                "Take a break.[/bold green]",
+                border_style="green"
+            )
+        console.print(completion, justify="center")
+    except KeyboardInterrupt as exc:
+        if is_break:
+            msg = "⏸️  Break paused. Rest is important too."
+        else:
+            msg = "⏸️  Session paused. Your focus still matters."
+
+        try:
+            if console is not None:
+                console.print("\n")
+                interrupted = Panel.fit(
+                    f"[bold yellow]{msg}[/bold yellow]",
+                    border_style="yellow"
+                )
+                console.print(interrupted, justify="center")
+            else:
+                print(f"\n{msg}")
+        except KeyboardInterrupt:
+            pass
+        raise typer.Exit(code=130) from exc
+
+
+def main() -> None:
+    """Main entrypoint for the CLI app."""
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

zen_timer-0.2.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: zen-timer
+Version: 0.2.0
+Summary: 🧘 Deep-work timer. Simple terminal app for focus sessions. No GUI, just flow.
+Author-email: Shenal Diluksha <shenald@users.noreply.github.com>
+Maintainer-email: shenald-dev <shenald@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shenald-dev/zen
+Project-URL: Documentation, https://github.com/shenald-dev/zen#readme
+Project-URL: Repository, https://github.com/shenald-dev/zen
+Project-URL: Issues, https://github.com/shenald-dev/zen/issues
+Project-URL: Changelog, https://github.com/shenald-dev/zen/blob/main/CHANGELOG.md
+Keywords: zen,timer,pomodoro,focus,deep-work,cli,tui,productivity
+Classifier: Development Status :: 5 - Production/Stable
+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: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich<16.0.0,>=13.9.0
+Requires-Dist: typer<1.0.0,>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<10.0.0,>=8.0.0; extra == "dev"
+Requires-Dist: pytest-mock<4.0.0,>=3.14.0; extra == "dev"
+Requires-Dist: pytest-cov<8.0.0,>=5.0.0; extra == "dev"
+Requires-Dist: flake8<8.0.0,>=7.0.0; extra == "dev"
+Requires-Dist: pylint<5.0.0,>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+# README.md
+<div align="center">
+  <img src="assets/logo.png" alt="zen Logo" width="250" />
+  
+  <br/>
+
+  <h1>🧘‍♂️ zen</h1>
+  <p><b>Minimalist Terminal Deep-Work Timer</b></p>
+  <i>Simple terminal app for focus sessions. No GUI, just flow.</i>
+
+  <br/>
+  
+  [![PyPI version](https://img.shields.io/pypi/v/zen-timer.svg)](https://pypi.org/project/zen-timer/)
+  [![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+</div>
+
+---
+
+## 📑 Table of Contents
+- [🌟 Overview](#-overview)
+- [🚀 Enterprise Features](#-enterprise-features)
+- [⚡ Quick Start Guide](#-quick-start-guide)
+- [💻 Comprehensive Usage](#-comprehensive-usage)
+- [🤝 Contributing](#-contributing)
+
+---
+
+## 🌟 Overview
+
+**zen** is an ultra-minimalist, distraction-free terminal application built to safeguard developer focus. It ditches complex GUIs in favor of beautiful, native terminal progress indicators. Dive straight into flow state.
+
+---
+
+## 🚀 Enterprise Features
+
+- **🌊 Flow State**: Visually stunning, distraction-free TUI progress bar.
+- **⏱️ Flexible**: Fully configurable focus sessions and break reminders.
+- **🎨 Premium Aesthetic**: Powered by `Rich` and `Typer` to look incredible in any modern terminal emulator (iTerm, Kitty, Windows Terminal).
+- **🚀 Performance**: Lightning-fast startup with lazy-loaded imports and zero-overhead UI rendering.
+
+---
+
+## ⚡ Quick Start Guide
+
+### Installation
+
+Install via pip:
+```bash
+pip install zen-timer
+```
+---
+
+## 💻 Comprehensive Usage
+
+### Start a Session
+To start a default 25-minute Pomodoro session:
+```bash
+zen
+```
+### Advanced Usage
+
+**zen** supports additional CLI flags to customize your workflow:
+
+- **`--break`**: Run the timer as a break session instead of a focus session. Ideal for timing your rest periods between deep work blocks.
+  ```bash
+  zen 5 --break
+  ```
+
+- **`--silent`**: Run the timer without sending desktop notifications upon completion. Perfect for environments where notifications are distracting or unsupported.
+  ```bash
+  zen 25 --silent
+  ```
+
+You can also combine these flags for a silent break session:
+```bash
+zen 15 --break --silent
+```
+---
+
+## 🤝 Contributing
+Want to help safeguard developer focus? Let's flow together! 🌊
+- 🐛 **Found a bug?** Open an issue to let us know.
+- ✨ **Have a feature idea?** We are open to PRs! Keep the UI minimal and the code beautiful.
+- 🎨 **Documentation tweaks?** Always welcome!
+
+---
+> *Crafted by a Vibe Coder. Protect your focus.*

zen_timer-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+zen/__init__.py,sha256=37EU0-DX3f1MIZFVrQ5KvO4oTyEonvP_JUJx7FnpFeg,39
+zen/__main__.py,sha256=SaB5HGgJtJ8QGLJmWbpHRjCxM9LjoJ_9dANT3WbI160,194
+zen/timer.py,sha256=U4hzHH2u68On6yTDzYo8zggSB6HIqelzG7uB8kmsFdw,5919
+zen_timer-0.2.0.dist-info/licenses/LICENSE,sha256=S6mLu9vpRpkEYeoHLB7vV8Vh_LWbyvaUbV58jPLjegM,1089
+zen_timer-0.2.0.dist-info/METADATA,sha256=uVC2CXRIKbWXKNW4WHfHi5V7qlWuB_oH_u15W969rfE,4341
+zen_timer-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+zen_timer-0.2.0.dist-info/entry_points.txt,sha256=D7wSILFvXTbDFZ0_756H33tViF5-5TQ1VdABxi_JGRc,39
+zen_timer-0.2.0.dist-info/top_level.txt,sha256=J6Rg4whb3lEX-U2oo41FON0O6pN2eVNF_0BcX1FwlSY,4
+zen_timer-0.2.0.dist-info/RECORD,,

zen_timer-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zen_timer-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zen = zen.timer:main

zen_timer-0.2.0.dist-info/licenses/LICENSE

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

zen_timer-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zen