Metadata-Version: 2.1
Name: autopy
Version: 4.0.0
Summary: A simple, cross-platform GUI automation library for Python.
Home-page: https://www.autopy.org
Author: Michael Sanders
Author-email: michael.sanders@fastmail.com
License: MIT OR Apache-2.0
Project-URL: Documentation, https://www.autopy.org/documentation/api-reference/
Project-URL: Code, https://github.com/autopilot-rs/autopy/
Project-URL: Issue Tracker, https://github.com/autopilot-rs/autopy/issues
Keywords: autopy,autopilot,GUI,automation,cross-platform,input,simulation
Platform: macOS
Platform: Windows
Platform: X11
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: MacOS X
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Description-Content-Type: text/markdown

For more information, see the [GitHub Repository](https://github.com/autopilot-rs/autopy).

[![Supported Python versions](https://img.shields.io/pypi/pyversions/autopy.svg)](https://pypi.python.org/pypi/autopy/)
[![Total downloads](https://pepy.tech/badge/autopy)](https://pepy.tech/project/autopy)

[![Travis Build Status](https://travis-ci.org/autopilot-rs/autopy.svg?branch=master)](https://travis-ci.org/autopilot-rs/autopy)
[![Appveyor Build Status](https://ci.appveyor.com/api/projects/status/2p5xap3tv4qkwsd1?svg=true)](https://ci.appveyor.com/project/msanders/autopy)

AutoPy Introduction and Tutorial
=================================

## Introduction

AutoPy is a simple, cross-platform GUI automation library for Python. It
includes functions for controlling the keyboard and mouse, finding colors and
bitmaps on-screen, and displaying alerts.

Currently supported on macOS, Windows, and X11 with the XTest extension.

## Getting Started

### Requirements

* Python 2.7, or Python 3.5 and up.
* Rust 1.23.0-nightly 2019-02-06 or later (unless using a binary wheel
  distribution).
* macOS 10.6 and up.
* Windows 7 and up.
* X11 with the XTest extension.

### Installation

First, see if a binary wheel is available for your machine by running:

    $ pip install -U autopy

If that fails, install [rustup](https://rustup.rs) and then run:

    $ rustup default nightly-2019-10-05
    $ pip install -U setuptools-rust
    $ pip install -U autopy

Another option is to build from the latest source on the GitHub repository:

    $ git clone git://github.com/autopilot-rs/autopy-rs.git
    $ cd autopy
    $ make
    $ make install

**Note**: AutoPy currently requires the `2019-10-05` Rust nightly in order to
build from source. This is to maintain compatibility with an older version of
PyO3, as the latest version has dropped Python 2 support. Python 2 support will
likely be dropped from AutoPy as well sometime later this year, depending on
how necessary it is to upgrade to a more recent version of PyO3 or Rust. In the
meantime, it may be necessary to install the required nightly via the following
when building locally:

```
rustup install nightly 2019-10-05 --force
```

This is due to rustup complaining that it doesn't include certain components
such as `rustfmt`.

Additional instructions for installing from source on Windows are available
[here](https://github.com/autopilot-rs/autopy/blob/master/scripts/windows-setup.md).

### Hello World

The following is the source for a "hello world" script in autopy. Running this
code will cause an alert dialog to appear on every major platform:

```python
import autopy


def hello_world():
    autopy.alert.alert("Hello, world")
hello_world()
```

![Cross platform alerts](https://github.com/autopilot-rs/autopy/raw/gh-pages/alerts.png)

## Tutorials

### Controlling the Mouse

AutoPy includes a number of functions for controlling the mouse. For a full
list, consult the [API
Reference](https://www.autopy.org/documentation/api-reference/mouse.html). E.g.,
to immediately "teleport" the mouse to the top left corner of the screen:

	>>> import autopy
	>>> autopy.mouse.move(1, 1)

To move the mouse a bit more realistically, we could use:

	>>> import autopy
	>>> autopy.mouse.smooth_move(1, 1)

Even better, we could write our own function to move the mouse across the screen
as a sine wave:

```python
import autopy
import math
import time
import random
import sys

TWO_PI = math.pi * 2.0


def sine_mouse_wave():
    """
    Moves the mouse in a sine wave from the left edge of
    the screen to the right.
    """
    width, height = autopy.screen.size()
    height /= 2
    height -= 10  # Stay in the screen bounds.

    for x in range(int(width)):
        y = int(height * math.sin((TWO_PI * x) / width) + height)
        autopy.mouse.move(x, y)
        time.sleep(random.uniform(0.001, 0.003))


sine_mouse_wave()
```

<a href="https://www.autopy.org/documentation/sine-wave"><img src="https://github.com/autopilot-rs/autopy/raw/gh-pages/sine-move-mouse-thumbnail.jpg" alt="Demonstration video"/></a>

### Controlling the Keyboard

The following will enter the keys from the string "Hello, world!" in the
currently focused input at 100 WPM:

```python
import autopy


autopy.key.type_string("Hello, world!", wpm=100)
```

Alternatively, individual keys can be entered using the following:

```python
import autopy


autopy.key.tap(autopy.key.Code.TAB, [autopy.key.Modifier.META])
autopy.key.tap("w", [autopy.key.Modifier.META])
```

### Working with Bitmaps

All of autopy's bitmap routines can be found in the module `autopy.bitmap`. A
useful way to explore autopy is to use Python's built-in `help()` function, for
example in `help(autopy.bitmap.Bitmap)`. AutoPy's functions are documented with
descriptive docstrings, so this should show a nice overview.

	>>> import autopy
	>>> autopy.bitmap.capture_screen()
	<Bitmap object at 0x12278>

This takes a screenshot of the main screen, copies it to a bitmap, displays its
memory address, and then immediately destroys it. Let's do something more
useful, like look at its pixel data:

	>>> import autopy
	>>> autopy.bitmap.capture_screen().get_color(1, 1)
	15921906

AutoPy uses a coordinate system with its origin starting at the top-left, so
this should return the color of pixel at the top-left corner of the screen. The
number shown looks a bit unrecognizable, but we can format it with Python's
built-in `hex` function:

	>>> import autopy
	>>> hex(autopy.bitmap.capture_screen().get_color(1, 1))
	'0xF2F2F2'

Alternatively, we can use:


	>>> import autopy
	>>> autopy.color.hex_to_rgb(autopy.screen.get_color(1, 1))
	(242, 242, 242)

which converts that hex value to a tuple of `(r, g, b)` values. (Note that
`autopy.screen.get_color()`, used here, is merely a more convenient and
efficient version of `autopy.bitmap.capture_screen().get_color()`.)

To save the screen capture to a file, we can use:

	>>> import autopy
	>>> autopy.bitmap.capture_screen().save('screengrab.png')

The filetype is either parsed automatically from the filename, or given as an
optional parameter. Currently only jpeg and png files are supported.

	>>> import autopy
	>>> autopy.bitmap.Bitmap.open('needle.png')
	<Bitmap object at 0x1001d5378>

Aside from analyzing a bitmap's pixel data, the main use for loading a bitmap is
finding it on the screen or inside another bitmap. For example, the following
prints the coordinates of the first image found in a bitmap (scanned from left
to right, top to bottom):

```python
import autopy


def find_image_example():
    needle = autopy.bitmap.Bitmap.open('needle.png')
    haystack = autopy.bitmap.Bitmap.open('haystack.png')

    pos = haystack.find_bitmap(needle)
    if pos:
        print("Found needle at: %s" % str(pos))

find_image_example()
```

It's also possible to do a bounded search by passing a tuple `((x, y), (width,
height))`:

```python
haystack.find_bitmap(needle, rect=((10, 10), (100, 100)))
```

## Projects using AutoPy

- [AutoPyDriverServer](https://github.com/daluu/autopydriverserver), AutoPy
  through WebDriver or a webdriver-compatible server.
- [guibot](https://github.com/intra2net/guibot), A tool for GUI automation using
  a variety of computer vision and desktop control backends.
- [spynner](https://github.com/kiorky/spynner), Programmatic web browsing
  module with AJAX support for Python.
- [SUMO](https://github.com/eclipse/sumo), An open source, highly portable,
  microscopic and continuous road traffic simulation package designed to handle
  large road networks.

## API Reference

Hope you enjoy using autopy! For a more in depth overview, see the [API
Reference](https://www.autopy.org/documentation/api-reference/).

## Contributing

If you are interested in this project, please consider contributing. Here are a
few ways you can help:

- [Report issues](https://github.com/autopilot-rs/autopy/issues).
- Fix bugs and [submit pull requests](https://github.com/autopilot-rs/autopy/pulls).
- Write, clarify, or fix documentation.
- Suggest or add new features.

## License

This project is licensed under either the [Apache-2.0](LICENSE-APACHE) or
[MIT](LICENSE-MIT) license, at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

