EAvatar ME’s documentation!¶

System Requirements¶

Installation¶

For desktop environments, such as Windows, OS X, etc, Avame is distributed as a portable application. Following are the usual steps to install Avame for these environments:

1. Download the distribution package for your environment.

   The package might be in different formats for various environments.

   • avame-x.y.x.zip for Windows
   • avame-x.y.z.tgz for Ubuntu
   • avame-x.y.z.dmg for OS X

   , where ‘x.y.z’ is the release version.

2. Uncompress the package to a suitable directory.

   Use the existing tool to uncompress the distribution package.

3. Delete the downloaded distribution package.

   This step is optional.

Launch the Application¶

Assume APPFOLDER is the installation folder of Avame application. You may launch Avame via command line or File manager or the like.

APPFOLDER\avame.exe

APPFOLDER/avame

APPFOLDER/avame

Application System Tray¶

As an agent, Avame works silently most of the time. The main UI is a system tray icon on the desktop environment of your choice. Through the tray icon, you may trigger a context menu illustrated as follow:

Open Web UI (Not working yet)¶

From the context menu, choose the ‘Open Web UI...’ option or input ‘http://127.0.0.1:5080/‘ in your browser’s address bar. Following figure illustrates the home page of the web UI (Fake):

Get Notified¶

Avame may notify you from time to time. The way how it notifies is platform-specific, though.

For Windows¶

System tray notification is used.

For OS X¶

Avame supports the notification center.

For Ubuntu¶

Recent Notices¶

In case that you missed some notifications from Avame, fear not. 10 most recent notices are kept in the context menu for your convenience:

Choose the notice you want to read, a message box should show up:

Application Folder¶

Open Folder¶

From the context menu, choose the ‘Open Folder...’ option to open Avame application folder.

What are Scripts¶

To tell Avame to do your jobs, you need to tell Avame how to do it imperatively. The instructions are expressed as a script in Python-like programming language. It sounds scary at the first place to writing scripts in a programming language for regular users. It ends up not so hard at all.

Differences from Regular Code¶

The syntax is intentionally very limited so that it’s more approachable than full-featured Python codes. The document is not intended to describe all the syntax as it’s a proper subset of Python’s. Compared to regular Python, following are removed features:

1. No import statement
2. No while control loop
3. No print statement
4. Names start with double underscores are prohibited, e.g. ‘__class__’.
5. No function definition
6. No class definition

Common Libraries¶

It’s not supported to import modules for scripts, so some standard libraries from Python runtime are selected and made available. The modules provided:

1. datetime
2. collections
3. calendar
4. heapq
5. bisect
6. array
7. queue or Queue
8. string
9. re
10. math
11. random
12. json
13. base64
14. binascii
15. hashlib
16. hmac

In addition to standard libraries, lxml is available for XML/HTML parsing.

Perform Actions¶

Besides the common libraries, scripts can perform various actions, each of which are explicitly registered functions and are intended for use by scripts.

The syntax to invoke an action is like follow:

ava.do(action_name, **kwargs)

, where action_name is in a format like ‘mod_name.func_name’. For example, ‘imap.check_gmail’ is the action name from imap module to check GMail.

ava.do function returns a task object whose essential methods are:

1. result(blocked=True, timeout=None)

   Wait for the task to finish and return the result (or raise an exception). By default, the method blocks the caller. But can be made to work asynchronously. If blocked is False and the task is not stopped, a Timeout exception is raised. If timeout parameter is given, a Timeout exception will be raised if expired.

2. stopped()

   Check if the task is finished or failed without blocking.

3. finished()

   Check if the task is completed successfully.

4. failed()

   Check if the task failed.

The execution of an action is represented as a task. Multiple tasks can be issued concurrently. At times, it’s needed to wait for tasks to finish. To coordinate tasks, a script may use following method to wait for tasks.

ava.wait(tasks, timeout=10)

,where tasks is a list of task objects; timeout is a timeout interval in seconds. There is an additional argument count which specify how many tasks to wait for before returning.

Built-in Actions¶

Loop Control¶

The only supported loop control for scripts is for statement. for loop is usually used to iterate a finite number of elements. In case a indefinite loop is needed, following construct can be used:

for it in ava.schedule:
    ...

ava.schedule is a special generator that returns counting number from 1 for each iteration. By default, the interval between intervals are 1 minute. Following are more examples:

for it in ava.schedule.every(1).minute

for it in ava.schedule.every(5).minutes

for it in ava.schedule.count(5).every().minute:
    ...

Example¶

Following script is for checking a GMail account with IMAP protocol every minute:

last_unseen = 0

for it in ava.schedule.every(1).minute:
    check_task = ava.do('imap.check_gmail',
                        username='username@gmail.com',
                        password='password')

    messages, unseen = check_task.result()
    if unseen > 0 and unseen != last_unseen:
        last_unseen = unseen
        ava.do('user.notify',
               message="You got %d new messages." % unseen,
               title="You Got Mails from GMail")

On Windows Platform¶

git checkout https://github.com/eavatar/eavatar-me avame

virtualenv --system-site-packages env
source env/Scripts/activate

pip install -r requirements/requirements_win32.txt

export PYTHONPATH="./src"

pyinstaller pack\avame.spec --clean -y

.\dist\avame\avame.exe

On OS X Platform¶

virtualenv --system-site-packages env
source env/bin/activate

git checkout https://github.com/eavatar/eavatar-me avame

CFLAGS='-std=c99' pip install gevent==1.0.2

pip install -r requirements/requirements_osx.txt

brew install libxml2
pip install lxml

export PYTHONPATH="./src"

pyinstaller pack/avame.spec --clean -y

./dist/avame/avame

open ./dist/EAvatar.app

On Ubuntu Platform¶

virtualenv --system-site-packages env
source env/bin/activate

git checkout https://github.com/eavatar/eavatar-me avame

sudo apt-get install libxml2-dev libxslt1-dev python-dev python-lxml
pip install -r requirements/requirements_gtk.txt

export PYTHONPATH="./src"

pyinstaller pack/avame.spec --clean -y

./dist/avame/avame

Where is my working folder for Avame?¶

Avame creates a per-user application folder when runs for the first time. The location is dependent on the operating system, following are the typical paths:

• Mac OS X:

  ~/Library/Application Support/avame

• Mac OS X (POSIX):

  ~/.avame

• Ubuntu:

  ~/.config/avame

• Win 7 (roaming):

  C:\Users\<user>\AppData\Roaming\avame

• Win 7 (not roaming):

  C:\Users\<user>\AppData\Local\avame

How do I add auto-run jobs when Avame starts?¶

Simply add the script file (with extension .py) to the subfolder ‘jobs’ under the Avame’s working folder, and then restart Avame. It will be started if it’s a correct script.

Event-driven, Non-blocking I/O¶

At the core of EAvatar, Gevent is used as the event-driven, non-blocking I/O engine. With the lightweight concurrency support and thread-like programming model, it a pleasure again to write asynchronous I/O codes.

Restrictive Execution of Python Codes¶

In addition to mainly developed in Python, EAvatar also uses Python as the domain-specific language(DSL) for describing jobs. A job is defined by a script in Python with very limited subset of features enabled.

A script is parsed into an abstract syntax tree with ast module, and then being walked through to detect invalid constructs such as ‘import’, ‘print’, ‘functiondef’, etc. Without complex constructs, it makes writing scripts more approachable for average users.

How Avame integrated with desktop environments¶

The main user interface for Avame is a so-called system tray icon or status icon on the desktop environment. Trying to avoid the bloated cross-platform GUI frameworks like QT, it takes a very different way to provide the desktop UI.

No cross-platform GUI frameworks are used for the desktop environments, an environment-by-environment integration is used instead.

• On Windows platform, Win32 API is used via PyWin32 package.
• On OS X platform, Cocoa is used via PyObjc package.
• On Ubuntu platform, GTK3 is used via PyGObject package.

A cross-platform web-based user interface is supported for user interactions that are more complex. To this end, Avame launches the default web browser when web UI is required.