DOCSEARCHbyAlgolia
Submit Docs

RPA for Python

repository·master·Indexed 26 days ago

https://github.com/tebelorg/rpa-python

A robotic process automation library and Python wrapper for TagUI designed to automate repetitive tasks on websites, desktop applications, and the command line. It provides a flat API for web automation using XPath/CSS selectors, visual automation via image recognition, OCR for text extraction, and keyboard and mouse control. The library supports Windows, macOS, Linux, and Raspberry Pi.

Tokens
12.9K
Snippets
42
Records
90
Agent score
89%

What's inside rpa-python

  1. Overview of RPA for Python

    master

    RPA for Python is a Python wrapper around TagUI, an open-source robotic process automation (RPA) tool. It provides a single, flat function-based API via import rpa as r to perform:

    • Website automation
    • Computer-vision automation
    • OCR (Optical Character Recognition)
    • Keyboard and mouse automation

    The wrapper operates in "live mode" by managing a TagUI subprocess. Each Python call is sent as an instruction to the subprocess's stdin, and results are retrieved from stdout or temporary output files.

  2. Understand the TagUI live-mode instruction protocol

    master

    When using TagUI in 'live mode' (launched via tagui rpa_python <browser_option>), the library uses a synchronous request/response protocol over stdin/stdout to synchronize instructions with the TagUI subprocess.

    Protocol Workflow:

    1. ID Tracking: Every instruction is assigned an incrementing integer ID (_tagui_id), starting at 0.
    2. Echo Markers: Before an instruction is sent, the library writes two echo lines to stdin to mark the start and end of the instruction:
      • echo "[RPA][<id>] - <escaped instruction text>"
      • echo "[RPA][<id>] - listening for inputs"
    3. Synchronization: The library waits for TagUI to echo back the [RPA][<id>] - listening for inputs marker on stdout before proceeding. This confirms the previous instruction has fully executed.
    4. Data Retrieval: For instructions that return values (like read(), url(), or dom()), the library uses a file-based exchange: it instructs TagUI to dump <variable> to rpa_python.txt, then polls for, reads, and deletes that file to retrieve the content.
    5. Termination: The close() method sends echo "[RPA][FINISHED]" followed by done to exit the subprocess.

  4. Interact with Web and Desktop UIs using TagUI

    master

    TagUI provides several families of functions for interacting with user interfaces:

    • Existence Checks: Use exist() or present() to verify if elements are on screen.
    • Clicking: Use click(), rclick() (right click), or dclick() (double click).
    • Hovering: Use hover() to move the mouse over an element.
    • Input & Selection: Use type() for text input or select() for dropdowns/selections.
    • Reading & Screenshots: Use read() to extract data or snap() to take screenshots.
    • Tables & Files: Use table() for table data or upload() for file uploads.
    • Navigation: Use url() to navigate to a new address or query the current URL.
    • Context Switching: Use frame() or popup() to switch between iframes or browser tabs.
    • State Reading: Use count(), title(), text(), or timer() to read page/application states.
    • JavaScript/Shell Execution: Use dom() or run() to execute JS or shell commands directly.

  6. Manage the TagUI process lifecycle

    master

    The TagUI lifecycle is managed through a sequence of process control functions. To use TagUI, you must first install it, initialize the subprocess, send instructions, and finally close the process to clean up resources.

    Key lifecycle tasks:

    • Setup: Download and install TagUI for your current OS.
    • Init: Start the TagUI subprocess and wait for it to become ready.
    • Send: Dispatch individual instructions to the running TagUI process.
    • Close: Terminate the TagUI subprocess and perform cleanup.
    • Pack: Bundle a TagUI installation for offline deployment.
    • Update: Build a self-extracting update script for offline deployment.

  7. Update offline TagUI installations with tagui.update()

    master

    Use tagui.update() to prepare an update for air-gapped or offline machines that already have RPA for Python installed. This function downloads the latest tagui.py and TagUI "delta" files, zips and base64-encodes them, and generates a standalone update.py script. This generated script contains all necessary logic to decode, unzip, and install the updates locally without requiring an internet connection on the target machine.

    Workflow:

    1. Run r.update() on an online machine to generate update.py.
    2. Transfer the update.py file to the offline machine (via USB, email, etc.).
    3. Execute the script on the offline machine using python update.py.
    import rpa as r
r.update()
# After running the above, copy or email the generated update.py to the offline machine, then:
# python update.py

  9. Retrieve values from TagUI using the dump protocol

    master

    To retrieve data from the browser (such as text, URLs, or DOM elements), the library follows a specific pattern:

    1. Execute a TagUI expression that assigns the desired value to a TagUI-side variable.
    2. Send the command: send('dump <variable> to rpa_python.txt').
    3. The library then uses _tagui_output() to poll for the existence of rpa_python.txt, reads its contents, and deletes the file.

    This pattern is used internally by high-level functions like read(), url(), title(), text(), mouse_xy(), and dom().

  10. Prepare an offline deployment with tagui.pack()

    master

    Use tagui.pack() on a machine with internet access to bundle the local TagUI installation and the rpa-python source into two files required for air-gapped (offline) deployment:

    1. rpa_python.zip: Contains a full TagUI installation, including the SikuliX/Jython dependency required for visual automation.
    2. rpa.py: A renamed copy of tagui.py.

    pack() automatically triggers an init(False, False) and close() cycle to ensure TagUI is fully installed and all delta files are synced before zipping. It also ensures dependencies like the SikuliX Jython jar (and the Visual C++ Redistributable on Windows) are downloaded.

    Deployment Steps:

    1. Run r.pack() on an internet-connected machine.
    2. Copy the generated rpa_python.zip and rpa.py to the offline target machine.
    3. On the offline machine, run import rpa as r; r.init(). The init() function will automatically detect rpa_python.zip in the same directory and perform the setup.

  12. Configure OS-specific settings for RPA for Python

    master

    Depending on your operating system, you may need to perform additional setup for visual automation:

    • Windows: If visual automation is faulty, set your display zoom level to 100% or the recommended percentage.
    • macOS: Due to security restrictions, you may need to install PHP manually and address specific issues with PhantomJS or Java popups.
    • Linux: Visual automation requires installing OpenCV and Tesseract.
    • Raspberry Pi: Follow this setup guide for low-cost automation servers.