Last updated: February 2026

AutoWork Studio ("the App") is developed and maintained by DevAuto ("we", "us", or "our"). This Privacy Policy explains our commitment to your privacy and how we handle information.

No Data Collection

AutoWork Studio does not collect, store, transmit, or share any personal information or user data. The App operates entirely on your local device and does not communicate with external servers, cloud services, or third-party systems.

No Internet Connection Required

AutoWork Studio functions fully offline. The App does not make network requests, does not send telemetry or diagnostic data, and does not include analytics or tracking components.

Local Data & Permissions

All scripts, projects, and configurations created within AutoWork Studio are stored exclusively on your local device. If the App requires specific system permissions, they are used solely for local functionality. We have no access to your local data at any time.

Support & Communication

If you contact us via email for technical support or inquiries, we will only use your email address and the information provided to respond to your request. We do not share this information with third parties or use it for marketing purposes.

Children's Privacy

Our App is not directed to individuals under the age of 13 (or 16 in certain jurisdictions). As we do not collect any data, we do not knowingly collect personal information from children.

Third-Party Services

AutoWork Studio does not integrate with third-party services, advertising networks, or data brokers.

Your Rights

Since all data remains on your local device, you have full control over your information. You can delete your projects or the App at any time, which will remove all locally stored data.

Changes to This Policy

If we update this Privacy Policy, we will revise the date at the top of this page. Continued use of the App constitutes acceptance of any changes.

Contact

For questions regarding this Privacy Policy, contact: autowork.assistance@gmail.com

Signature

api.left_click(x, y)

Description

Performs a left mouse click at the given screen coordinates.

Parameters

x: horizontal screen position in pixels.

y: vertical screen position in pixels.

Example

import autowork as api

api.left_click(500, 320)

Signature

api.right_click(x, y)

Description

Performs a right mouse click at the given screen coordinates.

Parameters

x: horizontal screen position in pixels.

y: vertical screen position in pixels.

Example

import autowork as api

api.right_click(500, 320)

Signature

api.move_to(x, y, s=0, mode='linear')

Description

Moves the cursor to screen coordinates (x, y). You can choose duration and movement style.

Parameters

x (int): target horizontal position in pixels.

y (int): target vertical position in pixels.

s (float, default 0): movement duration in seconds.

mode (string, default 'linear'): movement style.

Mode values

linear: constant-speed movement from start to target.

smooth: eased movement (slower start/end, smoother transition).

human: human-like path with natural micro-variations.

Return value

Returns True on success.

Important notes

s must be greater than or equal to 0.

Invalid mode raises an error. Valid modes: linear, smooth, human.

Examples

import autowork as api

api.move_to(500, 320)

import autowork as api

api.move_to(900, 480, 1.0, 'linear')

import autowork as api

api.move_to(700, 400, 0.8, 'smooth')

import autowork as api

api.move_to(640, 360, 0.9, 'human')

import autowork as api

api.move_to(520, 330, 0.6, 'human')
api.left_click(520, 330)

Signature

api.hold(x, y, s)

Description

Moves the cursor to (x, y), presses left mouse down, waits for s seconds, then releases.

Parameters

x (int): target horizontal position in pixels.

y (int): target vertical position in pixels.

s (float): hold duration in seconds. Must be >= 0.

Return value

Returns True on success.

Examples

import autowork as api

api.hold(500, 320, 0.5)

import autowork as api

api.hold(800, 450, 2)

import autowork as api

api.move_to(600, 400, 0.4, 'smooth')
api.hold(600, 400, 1.2)

Signature

api.scroll(amount, min=0.01, max=0.05)

Description

Sends mouse wheel scroll events. The command executes a number of wheel steps based on amount.

Parameters

amount (int): number of scroll steps.

Positive values scroll up. Negative values scroll down.

min (float, default 0.01): minimum delay between steps in seconds.

max (float, default 0.05): maximum delay between steps in seconds.

Behavior details

If amount is 0, the command does nothing and returns immediately.

Delays between steps are randomized between min and max for more natural scrolling.

Validation rules

min and max must be >= 0.

min must be less than or equal to max.

Return value

Returns True on success.

Examples

import autowork as api

api.scroll(3)

import autowork as api

api.scroll(-5)

import autowork as api

api.scroll(8, 0.002, 0.01)

import autowork as api

api.scroll(4, 0.03, 0.08)

Signature

api.drag_to(x, y, s=1, mode='linear')

Description

Presses and holds the left mouse button, moves to (x, y), then releases the button.

Parameters

x (int): target horizontal position in pixels.

y (int): target vertical position in pixels.

s (float, default 1): drag duration in seconds. Must be >= 0.

mode (string, default 'linear'): movement style during drag.

Mode values

linear: constant-speed path.

smooth: eased movement.

human: human-like path with natural variation.

Return value

Returns True on success.

Examples

import autowork as api

api.drag_to(900, 450)

import autowork as api

api.drag_to(760, 380, 1.4, 'smooth')

import autowork as api

api.drag_to(640, 360, 1.1, 'human')

import autowork as api

api.move_to(450, 300, 0.4, 'smooth')
api.drag_to(900, 300, 0.9, 'linear')

Signature

api.mouse_down(button)

Description

Presses a mouse button and keeps it down.

Use this when you want to hold a button manually (for example before moving the mouse).

Parameter

button: which button to press. Use 'left', 'right', or 'middle'.

Return value

Returns True on success.

Examples

import autowork as api

api.mouse_down('left')

import autowork as api

api.mouse_down('right')

import autowork as api

api.mouse_down('left')
api.wait(1)
api.mouse_up('left')

Signature

api.mouse_up(button)

Description

Releases the button you choose.

Usually used after mouse_down.

Parameter

button: which button to release. Use 'left', 'right', or 'middle'.

Return value

Returns True on success.

Examples

import autowork as api

api.mouse_up('left')

import autowork as api

api.mouse_up('middle')

Signature

api.key_down(key)

Description

Presses a key down and keeps it held until you release it with api.key_up.

Parameter

key: key name or character. Examples: 'a', 'enter', 'ctrl', 'shift', 'f5'.

Return value

Returns True on success.

Examples

import autowork as api

api.key_down('w')
api.wait(1)
api.key_up('w')

import autowork as api

api.key_down('ctrl')
api.press('c')
api.key_up('ctrl')

Signature

api.key_up(key)

Description

Releases a key that is currently down.

Parameter

key: key name or character. Same format used by api.key_down.

Return value

Returns True on success.

Examples

import autowork as api

api.key_up('shift')

import autowork as api

api.key_down('enter')
api.wait(0.2)
api.key_up('enter')

Signature

api.press(key, mode='instant')

Description

Presses and releases one key automatically.

Parameters

key: key name or character (for example 'a', 'enter', 'f5').

mode: 'instant' or 'human'.

'instant' sends key down/up immediately. 'human' adds a short realistic hold before release.

Return value

Returns True on success.

Examples

import autowork as api

api.press('enter')

import autowork as api

api.press('a', 'human')

Signature

api.hotkey(*keys)

Description

Presses multiple keys as a combo, then releases them in reverse order.

Parameters

*keys: one or more keys as separate arguments.

Example format: 'ctrl', 'shift', 's'.

Return value

Returns True on success.

Examples

import autowork as api

api.hotkey('ctrl', 'c')

import autowork as api

api.hotkey('ctrl', 'shift', 's')

Signature

api.hold_key(name, s)

Description

Holds one key for a specific number of seconds, then releases it.

Parameters

name: key name or character.

s: hold time in seconds (must be >= 0).

Return value

Returns True on success.

Examples

import autowork as api

api.hold_key('w', 1)

import autowork as api

api.hold_key('space', 0.5)

Signature

api.type(text, min=0, max=0)

Description

Types the provided text character by character.

Parameters

text: text to type.

min: minimum delay (seconds) between characters.

max: maximum delay (seconds) between characters.

Use min=0 and max=0 for instant typing. If you use delays, min and max must be >= 0 and min <= max.

Return value

Returns True on success.

Examples

import autowork as api

api.type('Hello from AutoWork')

import autowork as api

api.type('This looks more human', 0.03, 0.08)

Signature

api.cursor_position()

Description

Returns the current cursor coordinates on screen.

Parameters

No parameters.

Return value

Returns a tuple (x, y).

Examples

import autowork as api

x, y = api.cursor_position()
print(x, y)

import autowork as api

x, y = api.cursor_position()
api.left_click(x, y)

Signature

api.clipboard(text)

Description

Replaces the current clipboard content with the text you provide.

Parameters

text: text to copy to clipboard.

Return value

Returns True on success.

Examples

import autowork as api

api.clipboard('Hello from AutoWork')

import autowork as api

api.clipboard('hello')
api.hotkey('ctrl', 'v')

Signature

api.find_image(x, y, x2, y2, path, similarity=80, direction='lr_tb', first_match=True)

Description

Searches a screenshot area for a template image (OpenCV match) and returns the center of the match.

If no match is found, it returns (-1, -1).

How area coordinates work

x, y and x2, y2 define the search rectangle on screen.

You can think of them as opposite corners of the area to scan.

Order does not matter: the command automatically normalizes min/max internally.

Example: (300, 200, 1200, 800) and (1200, 800, 300, 200) scan the same area.

Parameters

x, y, x2, y2: screen area corners in pixels.

path: file path of the image you want to find.

similarity: threshold from 0 to 100. Higher means stricter match.

direction: match ordering mode when multiple matches exist.

first_match: if True, returns first match by direction; if False, picks best score first.

Direction options

lr_tb: left to right, then top to bottom.

rl_tb: right to left, then top to bottom.

lr_bt: left to right, then bottom to top.

rl_bt: right to left, then bottom to top.

tb_lr: top to bottom, then left to right.

bt_lr: bottom to top, then left to right.

tb_rl: top to bottom, then right to left.

bt_rl: bottom to top, then right to left.

For most scripts, keep default lr_tb.

Path on Windows (important)

If your path uses backslashes \, use a raw string with r"...".

This avoids escape issues like \n or \t being interpreted as special characters.

import autowork as api

# Recommended on Windows:
template = r"C:\Users\USER\Desktop\templates\play_button.png"

You can also use forward slashes:

template = "C:/Users/USER/Desktop/templates/play_button.png"

Return value

Returns a tuple (x, y) of the matched image center, or (-1, -1) if not found.

Examples

import autowork as api

pos = api.find_image(
    0, 0, 1920, 1080,
    r"C:\Users\USER\Desktop\templates\ok_button.png"
)
print(pos)

import autowork as api

x, y = api.find_image(
    300, 200, 1500, 900,
    r"C:\Users\USER\Desktop\templates\play.png",
    similarity=90
)

if (x, y) != (-1, -1):
    api.left_click(x, y)
else:
    print('not found')

import autowork as api

pos = api.find_image(
    200, 120, 1700, 980,
    r"C:\Users\USER\Desktop\templates\icon.png",
    similarity=85,
    direction='tb_lr',
    first_match=False
)
print(pos)

Signature

api.find_all_images(x, y, x2, y2, path, similarity=80)

Description

Searches the target screen area and returns all matches for the template image.

Unlike find_image, this command returns every match, not only one.

How area coordinates work

x, y and x2, y2 are opposite corners of the search area.

Order does not matter: the command normalizes the area internally.

Parameters

x, y, x2, y2: search area corners in pixels.

path: template image file to find.

similarity: threshold from 0 to 100 (default 80).

Return value

Returns a list of tuples [(x, y), ...], one for each detected match center.

If nothing is found, it returns an empty list [].

Notes

Results are sorted top-to-bottom, then left-to-right.

Overlapping high-score pixels of the same object are merged into a single match.

Path formatting rules are the same as find_image.

Examples

import autowork as api

matches = api.find_all_images(
    0, 0, 1920, 1080,
    r"C:\Users\USER\Desktop\templates\coin.png",
    similarity=88
)

print(len(matches))

import autowork as api

matches = api.find_all_images(
    0, 0, 1920, 1080,
    r"C:\Users\USER\Desktop\templates\coin.png"
)

if matches:
    first = matches[0]   # first is (x, y)
    x = first[0]
    y = first[1]
    print(x, y)
else:
    print('not found')

import autowork as api

matches = api.find_all_images(
    250, 160, 1650, 940,
    r"C:\Users\USER\Desktop\templates\reward.png"
)

if not matches:
    print('not found')
else:
    for x, y in matches:
        api.left_click(x, y)

Signature

api.compare_image(x, y, x2, y2, path)

Description

Captures the target area on screen and compares it with the image file.

Returns an integer score from 0 to 100, where higher means more similar.

How area coordinates work

x, y and x2, y2 are opposite corners of the area to capture.

Order does not matter (the area is normalized internally).

If area width or height is zero, the result is 0.

Parameters

x, y, x2, y2: area corners in pixels.

path: template image path.

Return value

Returns an integer similarity score in range 0..100.

When something is invalid (missing file, invalid area, decode/capture error), it returns 0.

When to use it

Use compare_image when you need a confidence score.

Use find_image when you need exact coordinates of a match.

Examples

import autowork as api

score = api.compare_image(
    300, 180, 900, 620,
    r"C:\Users\USER\Desktop\templates\panel.png"
)
print(score)

import autowork as api

score = api.compare_image(
    0, 0, 1920, 1080,
    r"C:\Users\USER\Desktop\templates\main_screen.png"
)

if score >= 90:
    print('screen matches')
else:
    print('different screen')

Signature

api.read_image(x, y, x2, y2)

Description

Captures a screen area and reads the text inside it.

Returns plain text. If no text is detected, returns an empty string.

How area coordinates work

x, y and x2, y2 are opposite corners of the area to scan.

Order does not matter because the command normalizes the area internally.

Parameters

x, y, x2, y2: screen area corners in pixels.

Return value

Returns a string.

If multiple lines are found, they are joined with line breaks.

Language support

Accents and Unicode characters are supported in the returned text.

Recognition quality for specific languages (for example Russian, Chinese, Arabic) depends on the OCR models available in your runtime.

In practice: test your target language with real screenshots before building a full automation flow.

Notes

The area must be non-empty (width and height greater than zero).

For best results, capture a tight area around the text.

Examples

import autowork as api

text = api.read_image(400, 250, 1200, 520)
print(text)

import autowork as api

text = api.read_image(300, 180, 900, 380)

if text.strip() == '':
    print('no text found')
else:
    print(text)

Signature

api.find_text(x, y, x2, y2, text, direction='lr_tb', first_match=True)

Description

Scans the target area, searches for the requested text, and returns the center point of the match.

If no match is found, it returns (-1, -1).

Text matching is case-insensitive and checks if your query is contained in detected text.

How area coordinates work

x, y and x2, y2 are opposite corners of the scan area.

Order does not matter; the area is normalized internally.

Parameters

x, y, x2, y2: area corners in pixels.

text: text to find. Must be non-empty.

direction: controls which match is preferred when multiple matches exist.

first_match: if True, returns the first match by direction; if False, prefers higher confidence first.

If text is empty (for example ''), the command raises an error.

Direction options

lr_tb: left to right, then top to bottom.

rl_tb: right to left, then top to bottom.

lr_bt: left to right, then bottom to top.

rl_bt: right to left, then bottom to top.

tb_lr: top to bottom, then left to right.

bt_lr: bottom to top, then left to right.

tb_rl: top to bottom, then right to left.

bt_rl: bottom to top, then right to left.

Return value

Returns a tuple (x, y) for the matched text center, or (-1, -1) if not found.

Examples

import autowork as api

x, y = api.find_text(
    0, 0, 1920, 1080,
    'Sign in'
)

if (x, y) != (-1, -1):
    api.left_click(x, y)
else:
    print('not found')

import autowork as api

pos = api.find_text(
    250, 160, 1650, 940,
    'play',
    direction='tb_lr',
    first_match=False
)

print(pos)

Signature

api.get_color(x, y)

Description

Captures one pixel at coordinate (x, y) and returns its color in RGB format.

Parameters

x: horizontal screen coordinate in pixels.

y: vertical screen coordinate in pixels.

Return value

Returns a tuple (r, g, b).

Each channel is an integer from 0 to 255.

Errors

If the pixel cannot be captured, the command raises an error.

Examples

import autowork as api

r, g, b = api.get_color(500, 320)
print(r, g, b)

import autowork as api

r, g, b = api.get_color(640, 360)

if (r, g, b) == (255, 255, 255):
    print('white pixel')
else:
    print('different color')

Signature

api.screenshot(x, y, x2, y2, path, exist_ok=True)

Description

Captures the selected screen area and saves it to disk.

The image is written as PNG data.

How area coordinates work

x, y and x2, y2 are opposite corners of the capture area.

Order does not matter; the command normalizes min/max internally.

Important: width and height must be greater than zero, so x != x2 and y != y2.

Parameters

x, y, x2, y2: area corners in pixels.

path: destination file path.

exist_ok: if False, writing to an existing file raises an error.

Return value

Returns True on success.

Edge cases

Empty area (zero width or height) raises an error.

Empty path raises an error.

If destination already exists and exist_ok=False, raises an error.

If destination path points to a directory, raises an error.

If parent directory does not exist, raises an error.

Screen capture failures raise an error.

Save/write failures raise an error.

Examples

import autowork as api

api.screenshot(
    300, 180, 1400, 900,
    r"C:\Users\USER\Desktop\capture.png"
)

import autowork as api

api.screenshot(
    0, 0, 1920, 1080,
    r"C:\Users\USER\Desktop\full.png",
    exist_ok=False
)

Signature

api.fs.info(path)

Description

Returns a dictionary with information about the given path.

Works for existing and non-existing paths.

Parameters

path: target file or folder path.

Return value

Returns a dictionary with these keys:

path: original input path string.

absolute_path: resolved absolute path.

exists: True if path exists, otherwise False.

is_file: True if path is a file.

is_dir: True if path is a directory.

name: last path element (file/folder name).

suffix: file extension (example .txt), empty for folders.

parent: parent directory path.

size: file size in bytes (folders return 0).

created_at: creation timestamp (float) or None.

modified_at: modification timestamp (float) or None.

Notes

If path is empty, the function returns a valid dictionary with default values (no exception).

Examples

import autowork as api

info = api.fs.info(r"C:\Users\USER\Desktop\project\main.py")
print(info['exists'], info['is_file'], info['size'])

import autowork as api

data = api.fs.info(r"C:\Users\USER\Desktop\docs")

if data['exists'] and data['is_dir']:
    print('folder ready')
else:
    print('folder not found')

Signature

api.fs.exists(path)

Description

Returns True if the given path exists, otherwise False.

It works for both files and folders.

Parameters

path: file or folder path to check.

Return value

Returns a boolean:

True = path exists.

False = path does not exist.

Notes

If path is None or an empty string, it returns False (no exception).

Examples

import autowork as api

ok = api.fs.exists(r"C:\Users\USER\Desktop\project\main.py")
print(ok)

import autowork as api

folder = r"C:\Users\USER\Desktop\output"

if api.fs.exists(folder):
    print('folder exists')
else:
    print('folder missing')

Signature

api.fs.list(path, recursive=False, pattern='*')

Description

Scans a directory and returns metadata entries for matched items.

Items are sorted with folders first, then files, by name.

Parameters

path: base directory to scan. Must exist and be a directory.

recursive: if True, scans subfolders too. Default is False.

pattern: glob filter (examples: '*', '*.py', '*.json').

Return value

Returns a list of dictionaries. Each dictionary contains:

name, path, absolute_path, is_file, is_dir, size, created_at, modified_at.

For directories, size is 0.

Errors

Path is empty: raises an error.

Path does not exist: raises an error.

Path is not a directory: raises an error.

Insufficient permissions: may raise an error.

File system I/O failures during scan: may raise an error.

Examples

import autowork as api

items = api.fs.list(r"C:\Users\USER\Desktop\project")
print(len(items))

import autowork as api

items = api.fs.list(
    r"C:\Users\USER\Desktop\project",
    recursive=True,
    pattern='*.py'
)

for item in items:
    print(item['name'], item['is_file'], item['size'])

Signature

api.fs.username()

Description

Returns the current user profile name, usually the same name used in C:\Users\<name>.

Use it to build portable user paths without hardcoding usernames.

Parameters

No parameters.

Return value

Returns a string with the active profile username.

Example return: "Profile1".

Errors

If the username cannot be resolved from the system profile/environment, it raises an error.

Examples

import autowork as api

user = api.fs.username()
desktop = f"C:/Users/{user}/Desktop"
print(desktop)

import autowork as api

user = api.fs.username()
project = f"C:/Users/{user}/Desktop/AutoWork/main.py"

if api.fs.exists(project):
    print("found")
else:
    print("missing")

Signature

api.fs.list_processes()

Description

Returns a sorted list of running process entries.

Each entry includes process ID, name, and executable path (when available).

Parameters

No parameters.

Return value

Returns a list of dictionaries with:

pid (int), name (string), path (string or None).

Some processes may have path = None.

Errors

This command is supported only on Windows.

If process listing fails, it raises an error.

Examples

import autowork as api

procs = api.fs.list_processes()

for i in range(min(10, len(procs))):
    print(procs[i]['name'], procs[i]['pid'])

import autowork as api

procs = api.fs.list_processes()

for p in procs:
    if 'edge' in p['name'].lower():
        print(p['pid'], p['name'], p['path'])
        break

Signature

api.fs.kill(pid=None, name=None, tree=True, force=True, timeout=3)

Description

Terminates a process using Windows taskkill.

You must choose exactly one target: pid or name.

Parameters

pid: process ID (integer > 0).

name: process image name (example 'notepad.exe').

tree: if True, kills child processes too (/T).

force: if True, forces termination (/F).

timeout: command timeout in seconds, must be a number >= 0.

Return value

Returns a dictionary:

ok (bool), code (int), target (string), message (string).

Even if the kill fails, the function still returns this dictionary with ok=False.

Edge cases

Windows only: on other OS it raises an error.

Exactly one target is required: passing both pid and name (or neither) raises an error.

pid must be integer and > 0; invalid values raise an error.

Cannot kill the current AutoWork process by PID (raises error).

timeout must be numeric and >= 0; invalid values raise an error.

Non-existing target usually returns ok=False with a system message.

Examples

import autowork as api

result = api.fs.kill(pid=1234)
print(result)

import autowork as api

result = api.fs.kill(name='notepad.exe', tree=True, force=True)
print(result['ok'], result['message'])

Signature

api.fs.play(path, args=None, wait=False, cwd=None)

Description

Runs executable/script files or opens non-executable files with the default app.

Returns True if launch/open command is started successfully.

Parameters

path: target file path to run/open.

args: optional arguments (None, list/tuple, or string).

wait: if True, waits for process completion (supported only for executable/script types).

cwd: optional working directory for process execution.

Supported behavior by file type

.py: executed with current Python interpreter.

.exe, .bat, .cmd: executed directly.

Other extensions (example .mp3, .mp4, .txt): opened via default Windows app.

Edge cases

Windows only: on other OS it raises an error.

Empty or missing path raises an error.

If target path does not exist, raises an error.

args must be None, list/tuple, or string; other types raise an error.

wait=True is allowed only for .py/.exe/.bat/.cmd; otherwise raises an error.

args for non-executable file types are not allowed and raise an error.

Examples

import autowork as api

api.fs.play(
    r"C:\Users\USER\Desktop\scripts\task.py",
    wait=True
)

import autowork as api

api.fs.play(r"C:\Users\USER\Desktop\media\song.mp3")

import autowork as api

api.fs.play(
    r"C:\Users\USER\Desktop\tools\app.exe",
    args=['--mode', 'fast'],
    wait=False
)

Signature

api.fs.play_sound(path, volume=100)

Description

Starts audio playback in background.

If another sound is already playing from this API, it is stopped first, then the new one starts.

Parameters

path: audio file path.

volume: number from 0 to 100.

Supported audio extensions

.wav, .mp3, .wma, .mid, .midi, .aac, .m4a.

Return value

Returns True on success.

Edge cases

Windows only: on other OS it raises an error.

Empty path raises an error.

Missing path raises an error.

If path points to a directory, raises an error.

Unsupported extension raises an error.

volume must be numeric and between 0 and 100; invalid values raise an error.

If underlying audio command fails, raises an error.

Playback is also stopped automatically when the script process exits.

Examples

import autowork as api

api.fs.play_sound(r"C:\Users\USER\Desktop\media\ping.mp3")

import autowork as api

api.fs.play_sound(
    r"C:\Users\USER\Desktop\media\notify.wav",
    volume=40
)

Signature

api.fs.stop_sound()

Description

Stops and closes the active audio playback started with fs.play_sound.

If no sound is currently active, it simply returns success.

Parameters

No parameters.

Return value

Returns True.

Edge cases

Windows only: on other OS it raises an error.

Safe to call even if no sound is playing.

Examples

import autowork as api

api.fs.stop_sound()

import autowork as api

api.fs.play_sound(r"C:\Users\USER\Desktop\media\track.mp3", volume=60)
api.wait(2)
api.fs.stop_sound()

Signature

api.fs.read_text(path, encoding='utf-8')

Description

Reads the target file using the selected encoding and returns its full text content.

Parameters

path: text file path.

encoding: file encoding (default utf-8).

Return value

Returns a string.

Edge cases

Empty path raises an error.

Missing file path raises an error.

If path is a directory, raises an error.

Invalid/unsupported encoding may raise an error.

Decode failures (wrong encoding for file content) may raise an error.

Examples

import autowork as api

text = api.fs.read_text(r"C:\Users\USER\Desktop\project\main.py")
print(text)

import autowork as api

text = api.fs.read_text(
    r"C:\Users\USER\Desktop\data\legacy.txt",
    encoding='cp1252'
)
print(text)

Signature

api.fs.write_text(path, text, encoding='utf-8', append=False)

Description

Writes text content to a file.

If append=False (default), file content is replaced.

If append=True, text is appended at the end.

Parameters

path: destination file path.

text: content to write (converted to string internally).

encoding: output encoding (default utf-8).

append: append mode when True.

Return value

Returns True on success.

Edge cases

Empty path raises an error.

If path points to a directory, raises an error.

If parent directory does not exist, raises an error.

Invalid/unsupported encoding may raise an error.

Write permission or I/O failures may raise an error.

Examples

import autowork as api

api.fs.write_text(
    r"C:\Users\USER\Desktop\notes.txt",
    'Hello from AutoWork'
)

import autowork as api

api.fs.write_text(
    r"C:\Users\USER\Desktop\notes.txt",
    '\nSecond line',
    append=True
)

Signature

api.fs.read_json(path, encoding='utf-8')

Description

Reads file text using the selected encoding, then parses it as JSON.

Returns Python data like dict, list, str, int, bool, etc.

Parameters

path: JSON file path.

encoding: text encoding used to read the file (default utf-8).

Return value

Returns parsed JSON data.

Edge cases

Empty path raises an error.

Missing file path raises an error.

If path is a directory, raises an error.

If encoding is wrong for file content, raises a decode error.

If file content is not valid JSON, raises a JSON parse error.

Examples

import autowork as api

data = api.fs.read_json(r"C:\Users\USER\Desktop\config.json")
print(data['version'], data['active'])

import autowork as api

items = api.fs.read_json(r"C:\Users\USER\Desktop\users.json")
for item in items:
    print(item['id'], item['name'])

Signature

api.fs.write_json(path, data, indent=2, ensure_ascii=False, encoding='utf-8')

Description

Serializes Python data to JSON and writes it to file.

It overwrites file content (not append).

Parameters

path: destination file path.

data: JSON-serializable Python data (dict, list, etc.).

indent: indentation spaces (default 2).

ensure_ascii: if True, non-ASCII chars are escaped (\uXXXX).

encoding: file encoding (default utf-8).

Return value

Returns True on success.

Edge cases

Empty path raises an error.

If path points to a directory, raises an error.

If parent directory does not exist, raises an error.

If data is not JSON-serializable, raises an error.

If indent cannot be converted to integer, raises an error.

Invalid encoding/output issues may raise write errors.

Examples

import autowork as api

payload = {
    'version': '1.0',
    'active': True
}

api.fs.write_json(
    r"C:\Users\USER\Desktop\config.json",
    payload
)

import autowork as api

data = {'name': 'Málaga', 'ok': True}

api.fs.write_json(
    r"C:\Users\USER\Desktop\out.json",
    data,
    indent=0,
    ensure_ascii=True
)

Signature

api.fs.create_folder(path, parents=True, exist_ok=True)

Description

Creates a directory at the target path.

Can create parent directories automatically.

Parameters

path: folder path to create.

parents: if True, missing parent folders can be created.

exist_ok: if True, returns success when folder already exists.

Return value

Returns True on success.

Edge cases

Empty path raises an error.

If target exists as a file, raises an error.

If target folder already exists and exist_ok=False, raises an error.

If parents=False and parent does not exist, raises an error.

OS/permission failures during mkdir raise an error.

Examples

import autowork as api

api.fs.create_folder(r"C:\Users\USER\Desktop\data\logs")

import autowork as api

api.fs.create_folder(
    r"C:\Users\USER\Desktop\new_folder",
    exist_ok=False
)

Signature

api.fs.move(src, dst, overwrite=False)

Description

Moves source file/folder to destination path.

Can also be used as rename when source and destination are in the same parent.

Parameters

src: source path (file or folder).

dst: destination path.

overwrite: if True, existing destination is removed first.

Return value

Returns True on success.

Edge cases

Empty src or dst raises an error.

Missing source path raises an error.

If destination exists and overwrite=False, raises an error.

If destination exists and overwrite=True, destination file/folder is deleted first.

If destination parent is missing, it is created automatically when needed.

Examples

import autowork as api

api.fs.move(
    r"C:\Users\USER\Desktop\old.txt",
    r"C:\Users\USER\Desktop\archive\old.txt"
)

import autowork as api

api.fs.move(
    r"C:\Users\USER\Desktop\build_new",
    r"C:\Users\USER\Desktop\build_current",
    overwrite=True
)

Signature

api.fs.copy(src, dst, overwrite=False)

Description

Copies source file/folder to destination.

When source is a folder, the destination becomes that folder copy (not only its contents).

Parameters

src: source path (file or folder).

dst: destination path.

overwrite: if True, existing destination is removed first.

Return value

Returns True on success.

Edge cases

Empty src or dst raises an error.

Missing source path raises an error.

If destination exists and overwrite=False, raises an error.

If destination exists and overwrite=True, destination file/folder is deleted first.

Unsupported source path type raises an error.

Permission or file system I/O failures may raise errors.

Examples

import autowork as api

api.fs.copy(
    r"C:\Users\USER\Desktop\notes.txt",
    r"C:\Users\USER\Desktop\backup\notes.txt"
)

import autowork as api

api.fs.copy(
    r"C:\Users\USER\Desktop\screenshot",
    r"C:\Users\USER\Desktop\gang244\screenshot",
    overwrite=True
)

Signature

api.fs.delete(path, recursive=False)

Description

Deletes a file or directory.

For directories, recursive controls whether non-empty folders are removed.

Parameters

path: file/folder path to delete.

recursive: if True, deletes directory tree; if False, removes only empty directory.

Return value

Returns True on success.

Edge cases

Empty path raises an error.

Missing path raises an error.

Directory + recursive=False: non-empty directory deletion raises an error.

Unsupported path type raises an error.

Permission/file system I/O failures may raise errors.

Examples

import autowork as api

api.fs.delete(r"C:\Users\USER\Desktop\temp.txt")

import autowork as api

api.fs.delete(
    r"C:\Users\USER\Desktop\old_build",
    recursive=True
)

Signature

api.fs.rename(path, new_name)

Description

Renames a file/folder without moving it to another directory.

Only the last name segment changes; parent path stays the same.

Parameters

path: existing file/folder path.

new_name: new name only (not a full path).

Return value

Returns True on success.

Edge cases

Empty path or new_name raises an error.

If source path does not exist, raises an error.

If new_name contains / or \, raises an error (name only required).

If destination name already exists in same parent, raises an error.

Permission/file system errors may raise exceptions.

Examples

import autowork as api

api.fs.rename(
    r"C:\Users\USER\Desktop\report_old.txt",
    'report_final.txt'
)

import autowork as api

api.fs.rename(
    r"C:\Users\USER\Desktop\build_temp",
    'build_release'
)

Signature

api.actions(action_map)

Description

actions starts multiple callables at the same time (multi-threading), waits for all of them, then returns a report.

This command is blocking: your script continues only after every action has finished.

How it works (simple)

1. You pass a dictionary: {'name': callable, ...}.

2. Each callable runs in its own thread.

3. For each action, AutoWork stores either a success result or an error message.

4. When all actions end, you get one dictionary with all outcomes.

Parameters

action_map: dictionary where:

key = action name (converted to string internally).

value = callable (function or lambda).

Return value

Returns a dictionary in this format:

{
  'action_name': {'ok': True, 'result': ...},
  'other_action': {'ok': False, 'error': 'ErrorType: message'}
}

Important behavior

Actions start almost at the same time, but exact scheduling order is not guaranteed.

If one action fails, the others continue; the failure is captured in that action result.

Result order follows the same order as your input dictionary.

If you pass an empty dictionary, it returns {}.

Edge cases

If action_map is not a dictionary, it raises an error.

If an action name is empty after trim (example ' '), it raises an error.

If any value is not callable, it raises an error.

If an action raises an exception, actions does not crash globally: that action returns {'ok': False, 'error': ...}.

Long-running actions delay the final return because actions waits for all threads.

Shared variables are allowed, but race conditions are possible if multiple actions write to the same data.

Action threads are tied to the script process; when script execution stops, those threads stop too.

Best practices

Prefer small named functions instead of very long lambdas.

Keep actions independent when possible.

If multiple actions modify shared data, use synchronization (for example Python locks).

Examples

import autowork as api

result = api.actions({
    'a': lambda: (print('A start'), api.wait(1), print('A end')),
    'b': lambda: (print('B start'), api.wait(1), print('B end'))
})

print(result)

import autowork as api

def mouse_task():
    api.move_to(600, 340, 0.4, 'human')
    api.left_click(600, 340)
    return 'mouse done'

def key_task():
    api.wait(0.2)
    api.hotkey('ctrl', 's')
    return 'save sent'

result = api.actions({
    'mouse': mouse_task,
    'keyboard': key_task
})

print(result)

import autowork as api

def ok_task():
    api.wait(0.3)
    return 123

def bad_task():
    raise RuntimeError('boom')

result = api.actions({
    'ok': ok_task,
    'bad': bad_task
})

print(result['ok'])   # {'ok': True, 'result': 123}
print(result['bad'])  # {'ok': False, 'error': 'RuntimeError: boom'}

import time
import autowork as api

start = time.perf_counter()

api.actions({
    'w1': lambda: api.wait(2),
    'w2': lambda: api.wait(3)
})

elapsed = time.perf_counter() - start
print(elapsed)  # around 3 seconds, not 5

import autowork as api

result = api.actions({
    'read': lambda: api.fs.read_text(r"C:\Users\USER\Desktop\notes.txt"),
    'sleep': lambda: api.wait(0.5)
})

if result['read']['ok']:
    content = result['read']['result']
    print(content)
else:
    print(result['read']['error'])

Signature

api.wait(s)

Description

Suspends the current script flow for s seconds.

It uses high-precision timing, useful for reliable automation pacing.

Parameters

s: wait duration in seconds (int or float).

Return value

Returns True when waiting is complete.

Edge cases

s must be numeric (or convertible to float); invalid values raise an error.

If s < 0, raises an error.

If s == 0, returns immediately with True.

wait is blocking: code after it runs only after the delay ends.

Examples

import autowork as api

print('start')
api.wait(1.5)
print('after 1.5s')

import autowork as api

api.left_click(500, 320)
api.wait(0.3)
api.type('hello')

import autowork as api

while True:
    print('tick')
    api.wait(0.1)

import autowork as api

result = api.actions({
    'short': lambda: api.wait(1),
    'long': lambda: api.wait(2)
})

print(result)

Signature

api.window.list()

Description

Returns a list of top-level windows with detailed information.

This is the full list (system windows, hidden windows, utility windows, app windows).

Parameters

No parameters.

Return value

Returns list[dict].

Each window dictionary includes:

hwnd, title, class_name, pid, thread_id, process_name, process_path, is_visible, is_enabled, is_minimized, is_maximized, is_foreground, owner_hwnd, show_cmd, show_cmd_name, style, exstyle, rect.

rect is a nested dictionary with: left, top, right, bottom, width, height.

Some fields can be None (for example process_name/process_path when process data is not accessible).

Behavior details

Results are sorted with visible windows first, then by title, then by hwnd.

Useful when you need exact window handles (hwnd) for commands like focus/minimize/resize/move/close.

Edge cases

Windows only: on other OS it raises an error.

If low-level window enumeration fails, raises an error.

Individual windows that fail during metadata read are skipped (the call still returns remaining windows).

Returned data is a snapshot: hwnd/process states can change right after reading.

Examples

import autowork as api

wins = api.window.list()

for i in range(min(10, len(wins))):
    print(wins[i]['hwnd'], wins[i]['title'], wins[i]['pid'])

import autowork as api

wins = api.window.list()

hwnd_cmd = None
for w in wins:
    if 'cmd' in (w['title'] or '').lower():
        hwnd_cmd = w['hwnd']
        break

print(hwnd_cmd)

Signature

api.window.list_visible()

Description

Returns a filtered window list focused on normal app windows, closer to what users expect from taskbar windows.

Includes minimized windows too.

Parameters

No parameters.

Return value

Returns list[dict] with the same fields as api.window.list().

Filter rules (real behavior)

A window is included only if all conditions are true:

is_visible == True

is_enabled == True

owner_hwnd == 0 (owner-less top-level window)

title is not empty

WS_EX_TOOLWINDOW flag is not set

Edge cases

Windows only: on other OS it raises an error (propagated from window.list()).

If full enumeration fails, raises an error.

Some windows can be skipped if metadata parsing fails during filtering.

This is still a snapshot: windows can open/close/minimize immediately after you get the list.

Examples

import autowork as api

wins = api.window.list_visible()

for w in wins:
    print(w['hwnd'], w['title'], w['is_minimized'])

import autowork as api

wins = api.window.list_visible()
target = None

for w in wins:
    if 'minecraft' in (w['title'] or '').lower():
        target = w
        break

print(target)

Signature

api.window.focus(hwnd)

Description

Tries to bring the target window to the front and make it the active input window.

If the window is minimized, it is restored automatically before focusing.

Parameters

hwnd: target window handle (integer).

Return value

Returns True on success.

Edge cases

Windows only: on other OS it raises an error.

hwnd must be an integer and > 0, otherwise it raises an error.

If hwnd is not a valid existing window, it raises an error.

Windows focus policies can block foreground changes in some moments; if all retries fail, it raises an error.

This command does not resize the window.

Examples

import autowork as api

wins = api.window.list_visible()
target_hwnd = None

for w in wins:
    if 'minecraft' in (w['title'] or '').lower():
        target_hwnd = w['hwnd']
        break

if target_hwnd is not None:
    api.window.focus(target_hwnd)

import autowork as api

api.window.focus(66988)

Signature

api.window.maximize(hwnd)

Description

Maximizes the target window using system window state.

It uses best-effort logic to preserve previous foreground focus if focus changes during maximize.

Parameters

hwnd: target window handle (integer).

Return value

Returns True on success.

Edge cases

Windows only: on other OS it raises an error.

hwnd must be an integer and > 0.

If hwnd is not a valid window, it raises an error.

If maximize call fails and window is not actually maximized, it raises an error.

If the window is already maximized, the command can still return success.

This command does not guarantee final focus on that window (focus may be restored to previous foreground).

Examples

import autowork as api

api.window.maximize(66988)

import autowork as api

target = None
for w in api.window.list_visible():
    if 'edge' in (w['title'] or '').lower():
        target = w['hwnd']
        break

if target:
    api.window.maximize(target)

Signature

api.window.minimize(hwnd)

Description

Minimizes the target window.

Parameters

hwnd: target window handle (integer).

Return value

Returns True on success.

Edge cases

Windows only: on other OS it raises an error.

hwnd must be an integer and > 0.

If hwnd is not a valid window, it raises an error.

If window is already minimized, it can still return success.

If minimize request fails and window is not minimized, it raises an error.

Examples

import autowork as api

api.window.minimize(66988)

import autowork as api

for w in api.window.list_visible():
    if 'cmd' in (w['title'] or '').lower():
        api.window.minimize(w['hwnd'])
        break

Signature

api.window.resize(hwnd, width, height)

Description

Changes window size and keeps current x,y position.

Parameters

hwnd: target window handle (integer).

width: new width (integer, > 0).

height: new height (integer, > 0).

Return value

Returns True on success.

Edge cases

Windows only: on other OS it raises an error.

hwnd must be integer and > 0.

width and height must be integers and > 0.

If hwnd is invalid, it raises an error.

If current rect cannot be read, it raises an error.

If resize operation fails, it raises an error.

Real minimum/maximum size can still be constrained by the target app/OS.

Examples

import autowork as api

api.window.resize(66988, 1280, 720)

import autowork as api

for w in api.window.list_visible():
    if 'vscode' in (w['title'] or '').lower():
        api.window.resize(w['hwnd'], 1400, 900)
        break

Signature

api.window.move(hwnd, x, y)

Description

Moves window to new top-left coordinates and preserves current width/height.

Parameters

hwnd: target window handle (integer).

x: new left position (integer).

y: new top position (integer).

Return value

Returns True on success.

Edge cases

Windows only: on other OS it raises an error.

hwnd must be integer and > 0.

x and y must be integers.

If hwnd is invalid, it raises an error.

If current rect cannot be read, it raises an error.

If move operation fails, it raises an error.

Final visible position can be constrained by monitor/work-area rules.

Examples

import autowork as api

api.window.move(66988, 100, 80)

import autowork as api

for w in api.window.list_visible():
    if 'chatgpt' in (w['title'] or '').lower():
        api.window.move(w['hwnd'], 300, 120)
        break

Signature

api.window.close(hwnd)

Description

Sends a standard close message to the target window (WM_CLOSE).

This is a graceful close request, not a force kill.

Parameters

hwnd: target window handle (integer).

Return value

Returns True if the close message is posted successfully.

Important behavior

window.close does not guarantee immediate process termination.

The target app may show save-confirmation dialogs or ignore/handle close with custom logic.

Edge cases

Windows only: on other OS it raises an error.

hwnd must be an integer and > 0, otherwise it raises an error.

If hwnd is invalid/non-existing, it raises an error.

If posting the close message fails, it raises an error.

Examples

import autowork as api

wins = api.window.list_visible()
target = None

for w in wins:
    if 'notepad' in (w['title'] or '').lower():
        target = w
        break

if target:
    api.window.close(target['hwnd'])

import autowork as api

hwnd = 123456
api.window.close(hwnd)
api.wait(0.3)

still_open = False
for w in api.window.list():
    if w['hwnd'] == hwnd:
        still_open = True
        break

print(still_open)

Signature

api.is_mouse_pressed(button)

Description

Checks if a mouse button is currently being held down.

What it returns

Returns True while the selected mouse button is down. Returns False otherwise.

Parameter

button: 'left', 'right', or 'middle'.

Examples

import autowork as api

print(api.is_mouse_pressed('left'))

import autowork as api

while True:
    if api.is_mouse_pressed('right'):
        print('Right button is down')
    api.wait(0.1)

Signature

api.is_mouse_released(button)

Description

Detects the exact moment a mouse button goes from down to up.

What it returns

Returns True only once on the transition pressed -> released.

Parameter

button: 'left', 'right', or 'middle'.

Examples

import autowork as api

while True:
    if api.is_mouse_released('left'):
        print('Left released')
    api.wait(0.1)

import autowork as api

if api.is_mouse_released('middle'):
    print('Middle released now')

Signature

api.is_mouse_just_pressed(button)

Description

Detects the exact moment a mouse button goes from up to down.

What it returns

Returns True only once on the transition released -> pressed.

Parameter

button: 'left', 'right', or 'middle'.

Examples

import autowork as api

while True:
    if api.is_mouse_just_pressed('left'):
        print('Clicked once')
    api.wait(0.1)

import autowork as api

if api.is_mouse_just_pressed('right'):
    print('Shortcut triggered')

Signature

api.is_key_pressed(key)

Description

Checks if a keyboard key is currently being held down.

What it returns

Returns True while the key is down. Returns False when not pressed.

Parameter

key: key name or character (for example 'w', 'space', 'enter').

Examples

import autowork as api

print(api.is_key_pressed('space'))

import autowork as api

while True:
    if api.is_key_pressed('w'):
        print('W held')
    api.wait(0.1)

Signature

api.is_key_released(key)

Description

Detects the exact moment a key goes from down to up.

What it returns

Returns True only once on the transition pressed -> released.

Parameter

key: key name or character (same format used by api.press).

Examples

import autowork as api

while True:
    if api.is_key_released('enter'):
        print('Enter released')
    api.wait(0.1)

import autowork as api

if api.is_key_released('a'):
    print('A released now')

Signature

api.is_key_just_pressed(key)

Description

Detects the exact moment a key goes from up to down.

What it returns

Returns True only once on the transition released -> pressed.

Parameter

key: key name or character (for example 'f8', 'esc', 'a').

Examples

import autowork as api

while True:
    if api.is_key_just_pressed('f8'):
        print('F8 pressed once')
    api.wait(0.1)

import autowork as api

while True:
    if api.is_key_just_pressed('q'):
        print('Q pressed')
    if api.is_key_just_pressed('esc'):
        break
    api.wait(0.1)