Epiphany's Python Console

Introduction

The Python Console is an Epiphany web browser extension which provides an interactive interface to Epiphany's Python API. In other words, the Python Console can do anything a Python-based Epiphany extension can do.

Limitations

The Python Console can do everything a Python-based Epiphany extension can do. At the moment this document was written, Epiphany does not come with an interface to XPCOM; this means that while the Python Console can access all of the Epiphany API (and all other Python libraries, for that matter), it has no control over the Mozilla API. Since Mozilla is used to render web pages, the end result is that the Python Console cannot change colors, add or remove HTML elements, or listen to arbitrary Mozilla signals. This limitation applies to Python extensions, as well.

Useful Documentation

This document is intended as a brief tutorial to familiarize the reader with Epiphany's Python Console. While hacking with the Python Console, the following references are essential:

• The Python Library Reference
• The PyGTK Reference Manual (again, available within Devhelp)
• The Epiphany Reference Manual (also available within Devhelp)

Unfortunately, Python-centric documentation of the Epiphany API does not exist at this point. The above-mentioned C API documentation should be sufficient.

A Sample Session

>> dir()
['__builtins__', '__history__', 'window']
>>> dir(window)                             # (shows window's attributes)
>>> window.set_title("Just testing...")     # (window title is changed)
>>> window.hide()                           # (window is hidden)
>>> window.show()                           # (window is shown)

>>> tab = window.get_active_tab()
>>> dir(tab)                                # (shows tab's attributes)

>>> embed = tab.get_embed()
>>> dir(embed)                              # (shows embed's attributes)

>>> embed.shistory_get_nth(0, False)
['file:///home/adam/python-console.xhtml', "Epiphany's Python Console"]

>>> z = embed.get_zoom()
>>> embed.set_zoom(3.0)                     # (page is zoomed to 300%)
>>> embed.set_zoom(z)                       # (page is zoomed back)

>>> embed.load_url('http://www.google.com') # (Google is loaded)
>>> embed.go_back()                         # (the previous page is loaded)]]>

The window Object

As shown in the Sample Session above, when the Python Console is initialized its environment contains a window variable. This variable is a Window representing the window from which the Python Console is started, and it is the most straightforward way to retrieve or set state information.

Window extends GtkWindow, so any GtkWindow methods may be called. In addition, get_notebook() will return the notebook in which Tabs are contained; get_statusbar() will return a Statusbar, and get_active_tab() and get_active_embed() will return the current Tab and Embed, respectively.

The tab Object

In the Sample Session above, a tab object (a Tab) is retrieved using window.get_active_tab(). From the tab object one may retrieve location, security level, title, zoom, and other status information.

The embed Object

In the Sample Session above, a embed object (an Embed) is retrieved using tab.get_embed(). This object is the bridge between Epiphany and Mozilla; with it, one may navigate web pages or retrieve status information. In the future (with PyXPCOM), the internal gtkmozembed object may be retrieved, which will permit direct interaction with Mozilla.

Global Objects

From within the Python Console, one may import epiphany to gain access to global Epiphany functions and variables. These are available from either the Shell, retrieved using epiphany.ephy_shell_get_default() or the more powerful epiphany.ephy_embed_shell_get_default():

• Bookmarks, using get_bookmarks(): interfaces to Epiphany's bookmarks model
• EmbedSingle, using get_embed_single(): can list cookies and passwords, and contains the useful open_window() method
• ExtensionsManager, using get_extensions_manager(): can list, load, and unload extensions
• History, using get_global_history(): interfaces to Epiphany's browser history
• Session, using get_session(): interfaces to Epiphany's session, which keeps track of currently-open windows and addresses.
• etc

Conclusion

At this point, you should be fiddling around with the console, comfortable with the dir() output and the Epiphany API.

Use the Python Console for little thought experiments. Connect to some signals using PyGTK, and see if they do what you expect. Once you've gotten a few lines of code to do something useful, consider fleshing out the idea into an extension. You've already done the hard part; using the extension interface with Python is absolutely trivial.