Metadata-Version: 2.4
Name: Lackey3
Version: 1.0.1
Summary: A Sikuli script implementation in Python with modern Lackey Studio IDE
Home-page: 
Author: TecHaonical, Jon Winsley
Author-email: jon.winsley@gmail.com
License: MIT
Keywords: automation testing sikuli lackey computer-vision ocr
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Classifier: Topic :: Desktop Environment
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: requests
Requires-Dist: pillow
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: keyboard
Requires-Dist: mouse
Requires-Dist: pyperclip
Requires-Dist: pytesseract
Requires-Dist: PySide6
Requires-Dist: pygments
Requires-Dist: jedi
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# Lackey3 #
## Pure-Python 3 Sikuli Automation Suite & Modern IDE ##

<p align="center">
  <img src="logo.png" width="180" height="180" alt="Lackey3 Logo">
</p>

[![Python 3.9+](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
[![Pure Python](https://img.shields.io/badge/JVM-Not%20Required-success.svg)](#)

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`:

```bash
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](https://github.com/UB-Mannheim/tesseract/wiki)
  * **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:

```bash
# 1. Direct CLI entry point
lackey_studio

# 2. Python module runner
python -m lackey_studio
```

Or from within a Python script / interactive shell:

```python
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:

```python
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:

```python
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 ###

```python
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_()`

```python
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](https://pixi.sh) to maintain reproducible, isolated developer environments.

```powershell
# 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](LICENSE.md) for full license text.
