motimer 0.1.2

A timer and stopwatch widget for marimo notebooks

motimer

An anywidget timer and stopwatch built for marimo notebooks. Useful for productivity, time management, trainings, and interactive demos.

Features

• Timer Widget: Countdown timer with customizable duration and audio alerts
• Stopwatch Widget: Precision stopwatch with start, stop, and reset functionality
• Multiple Themes: Light, dark, and auto themes to match your environment
• Interactive Controls: Easy-to-use buttons with modern UI design
• Real-time Updates: Live synchronization between widget state and Python variables
• Seamless Integration: Built as anywidgets for smooth marimo notebook integration

Installation

pip install motimer

# Or install from Github repository (development version)
pip install git+https://github.com/parmsam/motimer.git

Usage

Timer Widget

import marimo as mo
from motimer import TimerWidget

# Create a timer with default 5-minute duration
timer = TimerWidget()
timer_ui = mo.ui.anywidget(timer)

# Or set a custom initial time (10 minutes = 600 seconds)
timer = TimerWidget(initial_time=600)
timer_ui = mo.ui.anywidget(timer)

# Set time programmatically
timer.set_time(hours=0, minutes=2, seconds=30)

# Control timer programmatically
timer.start()  # Start the timer
timer.stop()   # Pause the timer
timer.reset()  # Reset to initial time

# Set theme
timer.theme = 'dark'  # 'light', 'dark', or 'auto'

# Display the widget
timer_ui

Stopwatch Widget

import marimo as mo
from motimer import StopwatchWidget

# Create and display a stopwatch
stopwatch = StopwatchWidget()
stopwatch.theme = 'light'  # 'light', 'dark', or 'auto'
stopwatch_ui = mo.ui.anywidget(stopwatch)

# Control stopwatch programmatically
stopwatch.start()  # Start the stopwatch
stopwatch.stop()   # Pause the stopwatch  
stopwatch.reset()  # Reset to 00:00.00

# Display the widget
stopwatch_ui

Accessing Widget State

You can access the current state of both widgets from Python:

# Timer state
mo.md(f"""
**Timer Status:**
- Time remaining: {timer.remaining_time // 60}m {timer.remaining_time % 60}s
- Is running: {timer.is_running}
- Timer finished: {'Yes' if timer.remaining_time == 0 and not timer.is_running else 'No'}
""")

# Stopwatch state  
mo.md(f"""
**Stopwatch Status:**
- Elapsed time: {stopwatch.elapsed_time / 1000:.2f} seconds
- Is running: {stopwatch.is_running}
""")

Widget Features

Timer Widget

• Customizable Duration: Set initial time via constructor or set_time() method
• Programmatic Control: Start, stop, and reset timer from Python code
• Audio Alerts: Plays a beep sound when timer reaches zero
• Visual Feedback: Modern gradient design with smooth animations
• Theme Support: Adapts to light/dark themes
• Python Integration: Access remaining time and running state from Python

Stopwatch Widget

• High Precision: Tracks time in milliseconds with centisecond display
• Programmatic Control: Start, stop, and reset stopwatch from Python code
• Start/Stop/Reset: Full control over timing operations
• Real-time Updates: Smooth 10ms update intervals for precise timing
• State Synchronization: Elapsed time and running state accessible from Python
• Theme Support: Matches your preferred color scheme

API Reference

TimerWidget

TimerWidget(initial_time=300)  # 300 seconds = 5 minutes default

# Properties
timer.remaining_time  # int: remaining seconds
timer.is_running      # bool: whether timer is active
timer.initial_time    # int: initial duration in seconds
timer.theme          # str: 'light', 'dark', or 'auto'

# Methods
timer.set_time(hours=0, minutes=5, seconds=0)  # Set timer duration
timer.start()         # Start the timer programmatically
timer.stop()          # Stop/pause the timer programmatically  
timer.reset()         # Reset timer to initial time

StopwatchWidget

StopwatchWidget()

# Properties  
stopwatch.elapsed_time  # int: elapsed time in milliseconds
stopwatch.is_running    # bool: whether stopwatch is active
stopwatch.last_updated  # float: timestamp of last update
stopwatch.theme        # str: 'light', 'dark', or 'auto'

# Methods
stopwatch.start()       # Start the stopwatch programmatically
stopwatch.stop()        # Stop/pause the stopwatch programmatically
stopwatch.reset()       # Reset stopwatch to 00:00.00

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Built with ❤️ using marimo and anywidget