pywinston 0.1.2

Self-voicing IDE and personal productivity environment for blind users

Winston

Self-voicing IDE and productivity environment for blind developers

Winston is a Python-based framework that provides an accessible, keyboard-driven development environment with integrated speech synthesis, code intelligence, and productivity tools designed specifically for blind users on Windows.

✨ Features

🎤 Self-Voicing IDE

• Full speech synthesis integration with JAWS and NVDA
• Announce code structure, indentation, and line numbers
• Speech-controlled navigation and editing
• Real-time spoken feedback for all operations

🐍 Python Development

• Syntax-aware editor with code intelligence
• Live reload - Edit code and reload without restarting (Control+F5)
• Integrated debugger with speech support
• Code completion via Jedi
• Goto definition across files
• Type checking with mypy integration
• Code folding for navigating large files

🤖 AI Integration

• Claude Code integration for AI-assisted development
• GPT integration for code generation and Q&A
• Natural language programming assistance

📅 Productivity Applets

• Google Calendar - Manage events with full speech support
• Gmail - Read and compose emails
• Google Contacts - Contact management with autocomplete
• File Explorer - Navigate filesystem with speech
• Console - Execute shell commands with output capture
• JSON Editor - Edit JSON with validation and formatting

⚡ Developer Experience

• Hotkey-driven - Everything accessible via keyboard
• Modular architecture - Easy to extend with custom applets
• Live reload workflow - Rapid iterative development
• Comprehensive type hints - Full mypy static type checking
• Google-style docstrings - Self-documenting codebase

🚀 Quick Start

Prerequisites

• Windows 10/11 (Winston uses Windows COM APIs)
• Python 3.10+ (modern type hints required)
• Screen reader (JAWS or NVDA recommended)

Installation

Option 1: Install from Source (Recommended for Development)

# Clone repository
git clone https://github.com/chris14257/winston.git
cd winston

# Install in editable mode with all dependencies
pip install -e .

# Run Winston
winston

Option 2: Quick Development Setup

# Clone and navigate to repository
git clone https://github.com/chris14257/winston.git
cd winston

# Install dependencies manually
pip install -r requirements.txt

# Run directly from source
python -m winston.churchill

First run:

• Winston beeps (350Hz, 200ms) on startup
• Root dialog opens with list of available applets
• Navigate with arrow keys, press Control+Return to open

Basic Usage

Launch Winston:

# If installed via pip
winston

# Or run as module
python -m winston.churchill

Essential Hotkeys:

• Control+Alt+E - Open file explorer
• Control+Alt+C - Open Claude Code integration
• Control+F5 - Reload current module (in pycoder)
• Control+W - Close current applet
• Control+Q - Quit Winston

See Getting Started Guide for detailed instructions.

📚 Documentation

• Getting Started - Installation, configuration, basic usage
• Winston Implementation Guide - Type hints, architecture, development workflows
• Development Workflow - Commit practices, testing protocols, WIP features
• Pip Installation Plan - Roadmap for pip installability

🎯 Core Applets

Applet	Hotkey	Description
Explorer	Control+Alt+E	File system navigation and management
Editor	(auto)	Multi-line text editing with speech
Pycoder	(auto)	Python IDE with code intelligence
Clauder	Control+Alt+C	Claude Code AI integration
Diary	Control+Alt+D	Google Calendar management
Console	Control+Alt+X	Shell command execution
Debugger	(context)	Python debugger with speech

Full list in GETTING_STARTED.md.

🔧 Development Workflow

Winston enables rapid iterative development without restarting:

# 1. Edit code in pycoder
@KeyHandler.hotkey("Control+Shift+T")
def command_my_feature(self, modified_name: str) -> None:
    """My new feature."""
    self.say_strings("Feature works!")

# 2. Press Control+F5 to reload
# Winston says "reloaded"

# 3. Test immediately - changes are live!
# Press Control+Shift+T
# Hear: "Feature works!"

What can be reloaded:

• ✅ All applets (winston/applets/*.py)
• ✅ Most utility modules
• ❌ Core framework (requires restart)

See Control+F5 Workflow for details.

🏗️ Architecture

Winston is built on a modular architecture:

winston/
├── framework.py         # Core: Anchor, Carousel, COMThread
├── dialog.py            # Base Dialog class with KeyHandler
├── subdialogs.py        # FormDialog, TableDialog, Applet
├── elements.py          # UI element types
├── churchill.py         # Application launcher (entry point)
├── clem.py              # Main event loop (pythoncom)
├── debugging.py         # Debugger, inspector, logger
├── google_api.py        # Google OAuth and API utilities
└── applets/             # Modular functionality
    ├── clauder.py       # Claude Code integration
    ├── explorer.py      # File explorer
    ├── pycoder.py       # Python IDE
    ├── diary.py         # Google Calendar
    └── ...

Key Patterns:

• pythoncom main loop - Windows message pump for COM integration
• asyncio on threads - Async I/O without blocking main loop
• Duck typing validation - element_attributes() instead of ABCs
• Protocol classes - Type hints for structural typing
• Live reload - Module cache invalidation for hot reloading

See Architecture Notes for in-depth coverage.

🤝 Contributing

Winston is under active development. Contributions welcome!

Development Setup

# Clone repository
git clone https://github.com/chris14257/winston.git
cd winston

# Install in editable mode with development dependencies
pip install -e ".[dev]"

# Run type checker
python -m mypy winston --config-file=winston/mypy.ini

# Make changes and test with Control+F5
# Commit when working

Contribution Guidelines

1. Follow typing standards - See WINSTON_IMPLEMENTATION.md
2. Add comprehensive docstrings - Google style required
3. Test your changes - Create test scripts in winston/scratch/
4. Run mypy - Fix all type errors before committing
5. Commit with attribution - Use template from claude.md

See claude.md for complete development workflow.

🎓 Learning Winston

For New Users

• Start with Getting Started Guide
• Explore winston/applets/template.py - Demonstrates all key patterns
• Read module docstrings - Winston is self-documenting

For Developers

• Read WINSTON_IMPLEMENTATION.md
• Study the type hints and docstrings throughout codebase
• Check claude.md for development practices
• Review recent commits for examples

For Contributors

• Fork the repository
• Create feature branch
• Follow typing and docstring standards
• Test with Control+F5 workflow
• Submit pull request

🌟 Design Philosophy

Winston follows these principles:

1. Accessibility First - Every feature designed for screen reader users
2. Keyboard-Driven - All functionality accessible via hotkeys
3. Speech Integrated - Continuous spoken feedback
4. Rapid Iteration - Live reload for fast development cycles
5. Type Safety - Comprehensive type hints with mypy validation
6. Self-Documenting - Google-style docstrings throughout
7. Modular - Applet architecture for extensibility

🔮 Future Plans

Short Term

• Pip installability - pip install winston-ide (see plan)
• Cross-platform test framework - Test without Windows dependencies
• Runtime type checking - Enable typeguard in development mode
• More applets - Email (mail.py), Jupyter (notebook.py)

Long Term

• Cross-platform support - macOS and Linux versions
• Plugin system - Third-party applet distribution
• Speech synthesis abstraction - Support multiple TTS engines
• Remote debugging - Debug code on remote systems

See WIP sections in claude.md for active work.

📊 Project Status

Current Version: 0.1.0 (Alpha)

Maturity:

• ✅ Core framework stable
• ✅ Major applets working (explorer, pycoder, clauder, diary)
• ✅ Type hints complete across codebase
• ⚠️ Some applets incomplete (mail, notebook, souper)
• ⚠️ Windows-only (platform-specific dependencies)
• ⚠️ Not yet pip-installable (manual setup required)

Type Checking:

• Total modules: 24 (all typed)
• mypy errors: 257 (down from 546 baseline, 52.9% reduction)
• Most errors are from untyped dependencies or legitimate duck typing

See mypy progress in claude.md for details.

🙏 Acknowledgments

Winston builds on these excellent projects:

• pywin32 - Windows COM integration
• Jedi - Python code intelligence
• Google APIs - Calendar, Gmail, Contacts
• Claude Code - AI-assisted development
• JAWS/NVDA - Screen reader integration

Named after Winston Churchill for resilience and reliability.

📄 License

MIT License - see LICENSE file for details.

🐛 Bug Reports & Questions

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Browse winston/docs/ directory or source code

🚀 Why Winston?

Winston provides blind developers with a complete development environment that doesn't compromise on accessibility or functionality:

• No visual dependencies - Everything navigable by keyboard and speech
• Professional-grade tools - Real debugger, type checking, AI integration
• Rapid development - Live reload workflow matches sighted IDEs
• Extensible - Easy to add new tools and productivity features
• Open source - Customize to your workflow

Join us in making development accessible to everyone! 🎉

---

Made with ❤️ for the blind developer community