ydotool 0.1.0__py3-none-any.whl

ydotool/__init__.py

@@ -0,0 +1,7 @@
+from importlib.metadata import version
+
+from .client import do_click, do_mousemove, do_type, do_key, do_wheel
+
+__all__ = ["do_click", "do_mousemove", "do_type", "do_key", "do_wheel"]
+
+__version__ = version("ydotool")

ydotool/client.py

@@ -0,0 +1,123 @@
+"""
+Python wrapper for ydotool CLI commands.
+
+Requires ydotool 1.0.4 to be installed and ydotoold daemon running.
+
+See:
+- https://github.com/ReimuNotMoe/ydotool
+- https://github.com/ReimuNotMoe/ydotool/releases/tag/v1.0.4
+"""
+
+import subprocess
+
+from .keycodes import get_keycodes
+from .mousecodes import get_mousecode
+
+def _run(*args: str) -> None:
+	subprocess.run(
+		["ydotool", *args],
+		check=True
+	)
+
+def do_click(button: str, action: str, repeat: int | None = None, next_delay: int | None = None) -> None:
+	"""
+	Perform mouse click action.
+
+	Args:
+		button: Button name ('left', 'right', 'middle', 'side',
+				'extra', 'forward', 'back', 'task').
+		action: Action name ('click', 'down', 'up').
+		repeat: Number of times to repeat the sequence (default: 1).
+		next_delay: Delay in milliseconds between events.
+					Full click takes 2x this value.
+
+	Raises:
+		ValueError: If button or action is invalid.
+	"""
+
+	mousecode = get_mousecode(button, action)
+
+	if mousecode:
+		args = []
+
+		if repeat and repeat > 1:
+			args.append(f"--repeat={repeat}")
+		if next_delay and next_delay > 0:
+			args.append(f"--next-delay={next_delay}")
+
+		_run("click", *args, mousecode)
+	else:
+		raise ValueError("Invalid button or action")
+
+def do_mousemove(x: int, y: int, absolute: bool = True) -> None:
+	"""
+	Move mouse cursor to coordinates.
+
+	Args:
+		x: X coordinate in pixels.
+		y: Y coordinate in pixels.
+		absolute: If True, move to absolute position.
+				  If False, move relative to current position.
+
+	Note:
+		For correct movement, disable mouse acceleration
+		and set mouse sensitivity to default
+		in your desktop environment settings.
+	"""
+
+	args = []
+
+	if absolute:
+		args.append("--absolute")
+
+	_run("mousemove", *args, str(x), str(y))
+
+def do_type(text: str, key_delay: int | None = None, key_hold: int | None = None) -> None:
+	"""
+	Type text string.
+
+	Args:
+		text: Text to type. Handles special characters automatically.
+		key_delay: Delay in milliseconds between key events (default: 20).
+		key_hold: Hold time in milliseconds for each key (default: 20).
+	"""
+
+	args = []
+
+	if key_delay and key_delay > 0:
+		args.append(f"--key-delay={key_delay}")
+	if key_hold and key_hold > 0:
+		args.append(f"--key-hold={key_hold}")
+
+	_run("type", *args, text)
+
+def do_key(keys: list[str]) -> None:
+	"""
+	Press keyboard keys in sequence.
+	Key names are defined in `keycodes.KEYCODES`
+
+	Args:
+		keys: List of 'key:state' strings where state is '1' (down)
+			  or '0' (up). Order matters for combinations.
+
+	Raises:
+		ValueError: If any key is invalid or format is wrong.
+	"""
+
+	keycodes = get_keycodes(keys)
+
+	if keycodes:
+		_run("key", *keycodes)
+	else:
+		raise ValueError("Invalid keys")
+
+def do_wheel(vertical: int = 0, horizontal: int = 0) -> None:
+	"""
+	Scroll mouse wheel.
+
+	Args:
+		vertical: Scroll ticks (positive=up, negative=down).
+		horizontal: Scroll ticks (positive=right, negative=left).
+	"""
+
+	_run("mousemove", "--wheel", str(horizontal), str(vertical))

ydotool/keycodes.py

@@ -0,0 +1,219 @@
+"""
+Keyboard key code mappings based on `/usr/include/linux/input-event-codes.h`
+
+All codes are decimal integers corresponding to `KEY_*` constants
+in the Linux kernel header.
+
+Unusual keys have not been added here.
+"""
+
+# exclamation         = shift + 1               ( ! ) = ( shift ) + ( 1 )
+# at                  = shift + 2               ( @ ) = ( shift ) + ( 2 )
+# hash                = shift + 3               ( # ) = ( shift ) + ( 3 )
+# dollar              = shift + 4               ( $ ) = ( shift ) + ( 4 )
+# percent             = shift + 5               ( % ) = ( shift ) + ( 5 )
+# caret               = shift + 6               ( ^ ) = ( shift ) + ( 6 )
+# ampersand           = shift + 7               ( & ) = ( shift ) + ( 7 )
+# asterisk            = shift + 8               ( * ) = ( shift ) + ( 8 )
+# leftparenthesis     = shift + 9               ( ( ) = ( shift ) + ( 9 )
+# rightparenthesis    = shift + 0               ( ) ) = ( shift ) + ( 0 )
+# underscore          = shift + minus           ( _ ) = ( shift ) + ( - )
+# plus                = shift + equal           ( + ) = ( shift ) + ( = )
+# leftcurlybracket    = shift + leftbracket     ( { ) = ( shift ) + ( [ )
+# rightcurlybracket   = shift + rightbracket    ( } ) = ( shift ) + ( ] )
+# verticalbar         = shift + backslash       ( | ) = ( shift ) + ( \ )
+# colon               = shift + semicolon       ( : ) = ( shift ) + ( ; )
+# doublequote         = shift + apostrophe      ( " ) = ( shift ) + ( ' )
+# less                = shift + comma           ( < ) = ( shift ) + ( , )
+# greater             = shift + dot             ( > ) = ( shift ) + ( . )
+# question            = shift + slash           ( ? ) = ( shift ) + ( / )
+# tilde               = shift + grave           ( ~ ) = ( shift ) + ( ` )
+
+KEYCODES = {
+	"0": "11",
+	"1": "2",
+	"2": "3",
+	"3": "4",
+	"4": "5",
+	"5": "6",
+	"6": "7",
+	"7": "8",
+	"8": "9",
+	"9": "10",
+
+	"a": "30",
+	"b": "48",
+	"c": "46",
+	"d": "32",
+	"e": "18",
+	"f": "33",
+	"g": "34",
+	"h": "35",
+	"i": "23",
+	"j": "36",
+	"k": "37",
+	"l": "38",
+	"m": "50",
+	"n": "49",
+	"o": "24",
+	"p": "25",
+	"q": "16",
+	"r": "19",
+	"s": "31",
+	"t": "20",
+	"u": "22",
+	"v": "47",
+	"w": "17",
+	"x": "45",
+	"y": "21",
+	"z": "44",
+
+	"esc": "1",
+	"backspace": "14",
+	"tab": "15",
+	"enter": "28",
+	"space": "57",
+	"capslock": "58",
+
+	"ctrl": "29",
+	"leftctrl": "29",
+	"rightctrl": "97",
+
+	"shift": "42",
+	"leftshift": "42",
+	"rightshift": "54",
+
+	"alt": "56",
+	"leftalt": "56",
+	"rightalt": "100",
+
+	"super": "125",
+	"leftsuper": "125",
+	"rightsuper": "126",
+
+	"menu": "127",
+	"compose": "127",
+
+	"f1": "59",
+	"f2": "60",
+	"f3": "61",
+	"f4": "62",
+	"f5": "63",
+	"f6": "64",
+	"f7": "65",
+	"f8": "66",
+	"f9": "67",
+	"f10": "68",
+	"f11": "87",
+	"f12": "88",
+
+	"up": "103",
+	"down": "108",
+	"left": "105",
+	"right": "106",
+
+	"home": "102",
+	"end": "107",
+	"pageup": "104",
+	"pagedown": "109",
+
+	"insert": "110",
+	"delete": "111",
+
+	"printscreen": "99",
+
+	"scrolllock": "70",
+
+	"pause": "119",
+
+	"numlock": "69",
+
+	"minus": "12",
+	"equal": "13",
+	"leftbracket": "26",
+	"rightbracket": "27",
+	"semicolon": "39",
+	"apostrophe": "40",
+	"grave": "41",
+	"backslash": "43",
+	"comma": "51",
+	"dot": "52",
+	"slash": "53",
+
+	"np0": "82",
+	"np1": "79",
+	"np2": "80",
+	"np3": "81",
+	"np4": "75",
+	"np5": "76",
+	"np6": "77",
+	"np7": "71",
+	"np8": "72",
+	"np9": "73",
+
+	"npasterisk": "55",
+	"npminus": "74",
+	"npplus": "78",
+	"npdot": "83",
+	"npenter": "96",
+	"npslash": "98",
+	"npequal": "117",
+
+	"mute": "113",
+	"volumedown": "114",
+	"volumeup": "115",
+	"micmute": "248",
+
+	"power": "116",
+	"sleep": "142",
+	"wakeup": "143",
+
+	"playpause": "164",
+	"nextsong": "163",
+	"previoussong": "165",
+
+	"back": "158",
+	"forward": "159",
+	"homepage": "172",
+	"search": "217",
+	"refresh": "173",
+
+	"stop": "166",
+
+	"brightnessup": "224",
+	"brightnessdown": "225",
+
+	"browser": "150",
+	"mail": "155",
+	"calc": "140",
+}
+
+def _split_key(key_str: str) -> tuple[str, str] | None:
+	if key_str.count(":") != 1:
+		return None
+	key, state = key_str.split(":")
+	if state in ("0", "1"):
+		return key, state
+	return None
+
+def get_keycode(key: str) -> str | None:
+	return KEYCODES.get(key)
+
+def get_keycodes(keys: list[str]) -> list[str] | None:
+	keycodes_list = []
+
+	for key_str in keys:
+		key_and_state = _split_key(key_str)
+
+		if not key_and_state:
+			return None
+		
+		key, state = key_and_state
+		keycode = get_keycode(key)
+
+		if not keycode:
+			return None
+
+		keycodes_list.append(f"{keycode}:{state}")
+
+	return keycodes_list

ydotool/mousecodes.py

@@ -0,0 +1,35 @@
+"""
+Mouse button and action code mappings for ydotool.
+
+ydotool 1.0.4 uses hexadecimal bit masks for mouse buttons:
+- Lower bits (0x00-0x07): button identifier
+- Upper bits (0x40=DOWN, 0x80=UP, 0xC0=CLICK): action
+
+0x can be omitted.
+"""
+
+MOUSECODES = {
+	"left": "0",
+	"right": "1",
+	"middle": "2",
+	"side": "3",
+	"extra": "4",
+	"forward": "5",
+	"back": "6",
+	"task": "7",
+}
+
+ACTIONCODES = {
+	"click": "C",
+	"down": "4",
+	"up": "8",
+}
+
+def get_mousecode(button: str, action: str) -> str | None:
+	buttoncode = MOUSECODES.get(button)
+	actioncode = ACTIONCODES.get(action)
+
+	if buttoncode and actioncode:
+		return f"{actioncode}{buttoncode}"
+
+	return None

ydotool-0.1.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: ydotool
+Version: 0.1.0
+Summary: Python wrapper for ydotool
+Keywords: ydotool,wayland,uinput,automation
+Author: astalunavortex
+Author-email: astalunavortex <astalunavortex@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: pytest>=8 ; extra == 'dev'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/astalunavortex/ydotool-py
+Project-URL: Repository, https://github.com/astalunavortex/ydotool-py
+Project-URL: Issues, https://github.com/astalunavortex/ydotool-py/issues
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# ydotool-py
+
+[![PyPI version](https://img.shields.io/pypi/v/ydotool.svg)](https://pypi.org/project/ydotool/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ydotool.svg)](https://pypi.org/project/ydotool/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-gren.svg)](https://opensource.org/licenses/MIT)
+
+Python wrapper for [ydotool](https://github.com/ReimuNotMoe/ydotool) - a generic command-line automation tool that works on **Wayland**, **X11**, and even **TTY**.
+
+Unlike `pyautogui`, `ydotool` operates at the kernel level via `/dev/uinput`, making it compatible with any Linux desktop environment.
+
+## Features
+
+- **Mouse**: move, click, scroll
+- **Keyboard**: type text, press keys, hotkey combinations
+
+## Installation
+
+### 1. Install ydotool
+
+```bash
+# Debian/Ubuntu
+sudo apt install ydotool
+
+# Arch Linux
+sudo pacman -S ydotool
+
+# Fedora
+sudo dnf install ydotool
+```
+If your distro doesn't have `ydotool`, you can build it from source [ydotool](https://github.com/ReimuNotMoe/ydotool)
+
+### 2. Start the daemon
+
+```bash
+# Enable for current user
+systemctl --user enable --now ydotool.service
+
+# Or run manually
+ydotoold
+```
+
+### 4. Install Python package
+
+```bash
+# Add with uv
+uv add ydotool
+
+# Or install with pip
+pip install ydotool
+```
+
+## Quick Start
+
+```python
+from ydotool import do_click, do_mousemove, do_type, do_key, do_wheel
+
+# Move mouse and click
+do_mousemove(500, 300)
+do_click('left', 'click')
+
+# Type text
+do_type("Hello, Wayland!")
+
+# Press key combination (Ctrl+S)
+do_key(['ctrl:1', 's:1', 's:0', 'ctrl:0'])
+
+# Scroll down
+do_wheel(vertical=-3)
+
+# Double-click
+do_click('left', 'click', repeat=2)
+```
+
+## API Reference
+
+### Mouse Control
+
+#### `do_click(button, action, repeat=None, next_delay=None)`
+
+Perform mouse click action.
+
+- **button**: `'left'`, `'right'`, `'middle'`, `'side'`, `'extra'`, `'forward'`, `'back'`
+- **action**: `'click'`, `'down'`, `'up'`
+- **repeat**: Number of repetitions
+- **next_delay**: Delay between events in milliseconds
+
+```python
+do_click('left', 'click')               # Single left click
+do_click('right', 'click', repeat=2)    # Double right click
+do_click('left', 'down')                # Press and hold
+do_click('left', 'up')                  # Release
+```
+
+#### `do_mousemove(x, y, absolute=True)`
+
+Move mouse cursor.
+
+```python
+do_mousemove(500, 300)                    # Absolute position
+do_mousemove(100, -50, absolute=False)    # Relative movement
+```
+
+#### `do_wheel(vertical=0, horizontal=0)`
+
+Scroll mouse wheel.
+
+```python
+do_wheel(vertical=3)      # Scroll up
+do_wheel(vertical=-5)     # Scroll down
+do_wheel(horizontal=2)    # Scroll right
+```
+
+### Keyboard Control
+
+#### `do_type(text, key_delay=None, key_hold=None)`
+
+Type text string. Handles special characters automatically.
+
+```python
+do_type("Hello, World!")
+do_type("Slow typing", key_delay=100)
+```
+
+#### `do_key(keys)`
+
+Press keyboard keys in sequence.
+
+Keys are specified as `'keyname:state'` where state is `'1'` (down) or `'0'` (up).
+
+```python
+# Press Enter
+do_key(['enter:1', 'enter:0'])
+
+# Ctrl+S
+do_key(['ctrl:1', 's:1', 's:0', 'ctrl:0'])
+
+# Alt+Tab
+do_key(['alt:1', 'tab:1', 'tab:0', 'alt:0'])
+```
+
+See [keycodes.py](src/ydotool/keycodes.py) for the complete list of key names.
+
+
+## Troubleshooting
+
+### "Failed to connect to ydotoold"
+
+Make sure the daemon is running:
+
+```bash
+systemctl --user status ydotool.service
+# or
+pgrep -a ydotoold
+```
+
+### "Permission denied" on `/dev/uinput`
+
+Check udev rules and log out/in:
+
+```bash
+ls -l /dev/uinput
+# Should show your user has access
+```
+
+### Mouse coordinates are wrong
+
+Disable mouse acceleration and set mouse sensetivity to default in your desktop environment settings.
+
+### Keys not working
+
+Check that you're using the correct format: `'keyname:state'` (e.g., `'ctrl:1'`, not just `'ctrl'`).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) for details.
+
+[ydotool](https://github.com/ReimuNotMoe/ydotool) is licensed under [AGPL-3.0](https://github.com/ReimuNotMoe/ydotool/blob/master/LICENSE).

ydotool-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ydotool/__init__.py,sha256=-OszjBgP8xWVGwjZ27vGWn4rbGkxRly9kMPA5GgAkVw,217
+ydotool/client.py,sha256=C7LV_QurYgenqVZKb4ETgByU3wlBijjoAgHA3Jl92uU,2956
+ydotool/keycodes.py,sha256=KfnSuv5SFdV6Xm6G_VQjCwfGMEzFShmZAfemN2xqmS4,4471
+ydotool/mousecodes.py,sha256=d1i7FDzivDMOPE3zd4ommNEUkGk8NYAhg7qBz5H0ivM,653
+ydotool-0.1.0.dist-info/licenses/LICENSE,sha256=YStTElrmK_rQ1i_Z1Ltz589jy9cdXTDvA8MRpGV1fyg,1071
+ydotool-0.1.0.dist-info/WHEEL,sha256=cmC5s21ojypbVslldL7IJq3hjZH-tINy4rziKePFsG0,81
+ydotool-0.1.0.dist-info/METADATA,sha256=gLYx7tFcDI4WIzcRpeJs3z_7ZsNx8fVcANKNpYayJYw,4996
+ydotool-0.1.0.dist-info/RECORD,,

ydotool-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.23
+Root-Is-Purelib: true
+Tag: py3-none-any

ydotool-0.1.0.dist-info/licenses/LICENSE

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