Lackey3

Pure-Python 3 Sikuli Automation Suite & Modern IDE

Developed by Jon Winsley and TecHaonical

---

Introduction

Lackey3 is a modernized, pure-Python 3 implementation of the SikuliX script automation API. It enables you to run scripts developed in SikuliX without requiring a Java Runtime Environment (JVM).

Lackey3 combines computer vision (OpenCV template matching), Optical Character Recognition (Tesseract OCR), low-level OS input emulation (mouse clicks, keyboard strokes), and application lifecycle management to provide seamless desktop graphical automation across Windows and macOS.

Key Python 3 Upgrades & Modern Features

• Native Python 3 Architecture: Fully rewritten and optimized for Python 3 (supporting Python 3.9 through Python 3.14+). Deprecated Python 2 legacy code has been completely removed.
• Type Annotations (PEP 561 / py.typed): Modern typing support for enhanced IDE autocompletion, static type checking with Mypy, and Pyright integration.
• Modern Lackey Studio IDE: PySide6 (Qt6)-based modern IDE replacing the legacy SikuliX Java IDE, featuring VSCode-like autocompletion (Jedi), real-time i18n (繁體中文, English, 简体中文, 日本語), a visual snipping tool, and an exhaustive interactive command guide.
• Packaged CLI Tool: Directly run lackey_studio from your terminal after pip install.
• Advanced Computer Vision: Multi-scale template matching via OpenCV (PyramidTemplateMatcher), similarity thresholds, and target offsets.
• Multilingual OCR Engine: Powered by pytesseract supporting English, Traditional Chinese (chi_tra), Simplified Chinese (chi_sim), Japanese (jpn), and more.
• Full Unicode & Special Input Support: Robust handling of CJK text, full-width punctuation, Emoji pasting, and macro-safe text operations without unintended hotkey triggers.

---

Installation

Install the latest version of Lackey3 via pip:

pip install Lackey3

System Requirements

• Python: Python 3.9 or higher (tested up to Python 3.14).
• Operating Systems:
  • Windows 10 / 11 / Server (x64)
  • macOS (Intel & Apple Silicon)
• Optional - Tesseract OCR: For OCR features (findText(), text(), waitText()), install Tesseract OCR (v3.05+) and ensure it is available in your system PATH:
  • Windows: Download installer from UB-Mannheim/tesseract
  • macOS: brew install tesseract

---

Lackey Studio IDE

Lackey3 comes bundled with Lackey Studio, a full-featured desktop IDE:

• Visual Snipping Tool: Dim the screen, drag to select any region, automatically save the cropped template image, and insert Pattern("image.png").similar(0.85) directly into your code.
• Intelligent IntelliSense: Real-time code completions and docstrings powered by Jedi, connected directly to your active Python environment.
• Multi-Language Internationalization (i18n): Switch on-the-fly between 繁體中文, English, 简体中文, and 日本語.
• Interactive Command Inspector: Detailed parameter explanations, return values, and one-click copyable realistic code examples for all Sikuli / Lackey commands.
• Sikuli Bundle Management: Open and save SikuliX .sikuli folders with automatic image migration and relative path rewriting.

Launching the IDE

After installation, launch Lackey Studio in any of the following ways:

# 1. Direct CLI entry point
lackey_studio

# 2. Python module runner
python -m lackey_studio

Or from within a Python script / interactive shell:

import lackey3
lackey3.studio()

---

Quick Start & Usage

1. Basic Sikuli-Compatible Automation

Lackey maps Sikuli functions (click, find, wait, type, etc.) into the global scope:

from lackey3 import *

# Open native application
App("notepad.exe").open()
wait(2.0)

# Type text into active window
type("Hello, Lackey3 on Python 3!\n")

# Unicode & Chinese support via paste
paste("繁體中文與 Emoji 🚀 支援！\n")

# Mouse interaction and image searching
if exists("save_icon.png"):
    click("save_icon.png")

2. Optical Character Recognition (OCR)

Recognize and click text on screen without requiring pre-captured image templates:

from lackey3 import *

screen = Screen()

# Extract all text visible on screen
content = screen.text()
print("Screen Text:", content)

# Search for specific text on screen and click it
target_match = screen.findText("Save")
if target_match:
    target_match.click()

3. Application Lifecycle Management

from lackey3 import App

app = App("notepad.exe").open(waitTime=2.0)
print(f"Notepad PID: {app.getPID()}, IsRunning: {app.isRunning()}")

win = app.waitForWindow(seconds=5.0)
if win:
    print(f"Window bounds: ({win.getX()}, {win.getY()}, {win.getW()}, {win.getH()})")
    app.focus()

# Close application gracefully
app.close()

---

Sikuli Function Remapping (Python Built-in Aliases)

Because Sikuli defines global functions type() and input(), importing Lackey via from lackey3 import * remaps standard Python built-ins to avoid collisions:

• Native Python type() is available as type_()
• Native Python input() is available as input_()
• Native Python sys.exit() is available as exit_()

from lackey3 import *

# Sikuli keystroke emulation:
type("Hello World")

# Native Python type checking:
var_type = type_(123)  # <class 'int'>

# Native Python console prompt:
user_val = input_("Enter value: ")

---

Development & Testing with Pixi

We use pixi to maintain reproducible, isolated developer environments.

# Run headless unit tests
pixi run test

# Run Lackey Studio IDE tests
pixi run test-studio

# Run end-to-end 40-step Notepad super automation test
pixi run test-notepad

# Run legacy integration test suites
pixi run test-all

# Launch Lackey Studio IDE
pixi run studio

# Build sdist and wheel distributions
pixi run build

# Validate distribution files
pixi run check

---

Contributing & License

Contributions, issues, and feature requests are welcome! Please feel free to check the issues page or submit pull requests.

This project is licensed under the terms of the MIT License. See LICENSE.md for full license text.