initial reference documentation

docs/index.rst

@@ -28,6 +28,12 @@ Welcome to arsenic's documentation!
     howto/pytest
     howto/action_chains
 
+.. toctree::
+    :maxdepth: 2
+    :caption: Reference
+
+    reference/index
+
 
 Indices and tables
 ==================

docs/reference/actions.rst

@@ -0,0 +1,139 @@
+``arsenic.actions``
+###################
+
+APIs to construct actions to be used in :py:meth:`arsenic.session.Session.perform_actions`.
+
+.. py:module:: arsenic.actions
+
+.. py:function:: chain(*ticks):
+
+    Main API to construct actions for :py:meth:`arsenic.session.Session.perform_actions`.
+
+    :param ticks: A sequence of actions to chain.
+    :type ticks: :py:class:`Tick`
+    :return: An object which can be passed to :py:meth:`arsenic.session.Session.perform_actions`.
+
+
+.. py:class:: Button(Enum)
+
+    .. py:attribute:: left
+        Left mouse button.
+
+    .. py:attribute:: middle
+        Middle mouse button.
+
+    .. py:attribute:: right
+        Right mouse button.
+
+
+.. py:class:: Tick
+
+    Class holding an action tick, which can have multiple actions of different
+    devices.
+
+    You should not create instances of this class yourself, but rather use APIs
+    on :py:class:`Device` subclasses to create them.
+
+    :py:class:`Tick` can be used with the OR operator (``|``) to combine actions
+    of multiple devices.
+
+
+.. py:class:: Device
+
+    Abstract base class for devices.
+
+    .. py:method:: pause(duration):
+
+        Pause this device (do nothing) for a duration in milliseconds.
+
+        This is primarily used implicitly in action chains that have multiple
+        devices but not all devices perform an action on each tick.
+
+        :param int duration: Duration in milliseconds of the pause.
+        :rtype: :py:class:`Tick`
+
+
+.. py:class:: Pointer(Device)
+
+    Base class for pointer devices.
+
+    .. py:method:: move_to(element, duration=250) :
+
+        Moves the pointer to an element.
+
+        :param element: Element to move to.
+        :type element: :py:class:`arsenic.session.Element`
+        :param int duration: Duration in milliseconds of this action.
+        :rtype: :py:class:`Tick`
+
+    .. py:method:: move_by(x, y, duration=250):
+
+        Move the pointer by a given number of pixels relative to the viewport.
+
+        :param int x: Number of pixels to move in the x-axis.
+        :param int x: Number of pixels to move in the y-axis.
+        :param int duration: Duration in milliseconds for this action.
+        :rtype: :py:class:`Tick`
+
+    .. py:method:: down():
+
+        Holds the pointer down.
+
+        :rtype: :py:class:`Tick`
+
+    .. py:method:: up():
+
+        Lifts the pointer up.
+
+        :rtype: :py:class:`Tick`
+
+
+.. py:class:: Mouse(Pointer):
+
+    Mouse device.
+
+    .. py:method:: down(button=Button.left):
+
+        Hold down a mouse button.
+
+        :param button: Which button to hold down.
+        :type button: :py:class:`Button`
+        :rtype: :py:class:`Tick`
+
+    .. py:method:: up(button=Button.right):
+
+        Releases a mouse button.
+
+        :param button: Which button to release.
+        :type button: :py:class:`Button`
+        :rtype: :py:class:`Tick`
+
+
+.. py:class:: Pen(Pointer):
+
+    A pen device.
+
+
+.. py:class:: Touch(Pointer):
+
+    A touch device.
+
+
+.. py:class:: Keyboard(Device):
+
+    A keyboard device.
+
+    .. py:method:: down(key):
+
+        Holds down a specific key.
+
+        :param str key: Which key to hold down.
+        :rtype: :py:class:`Tick`
+
+    .. py:method:: up(key):
+
+        Releases a specific key.
+
+        :param str key: Which key to release.
+        :rtype: :py:class:`Tick`
+

docs/reference/browsers.rst

@@ -0,0 +1,41 @@
+``arsenic.browsers``
+####################
+
+.. py:module:: arsenic.browsers
+
+.. py:class:: Browser
+
+    Base browser class.
+
+    .. py:attribute:: session_class
+
+        Session class to use for this browser. Should be :py:class:`arsenic.session.Session`
+        or a subclass thereof.
+
+    .. py:attribute:: capabilities
+
+        A JSON serializable dictionary of capabilities to request.
+
+    .. py:attribute:: defaults
+
+        Default capabilities.
+
+    .. py:method:: __init__(**overrides):
+
+        When initializing a browser, you can override or extend the default
+        capabilities of the browser.
+
+
+.. py:class:: Firefox(Browser)
+
+    Firefox with default capabilities.
+
+
+.. py:class:: PhantomJS(Browser)
+
+    PhantomJS with default capabilities.
+
+
+.. py:class:: InternetExplorer(Browser)
+
+    Internet Explorer with default capabilities.

docs/reference/connection.rst

@@ -0,0 +1,54 @@
+``arsenic.connection``
+######################
+
+.. py:module:: arsenic.connection
+
+
+.. py:data:: WEB_ELEMENT
+
+    Constant string used to denote web elements in the web driver protocol.
+
+
+.. py:class:: Connection(session, prefix)
+
+    Connection class to use for communication with a webdriver. This class
+    operates with a ``prefix`` to make it easier to use internally.
+
+    :param session: Aiohttp client session.
+    :type session: :py:class:`aiohttp.client.ClientSession`
+    :param str prefix: Prefix for this connection.
+
+    .. py:method:: request(*, url, method, data=None, raw=False)
+
+        Coroutine to do an HTTP request. All arguments are keyword only.
+
+        :param str url: The URL to send the request to.
+        :param str method: HTTP method to use.
+        :param data: Optional data to send. Must be JSON serializable.
+        :param bool raw: Optional flag to get the raw response data instead of unwrapped data.
+
+    .. py:method:: upload_file(path):
+
+        Coroutine that uploads a file. This is used for remote webdrivers.
+        This is used internally by :py:meth:`arsenic.session.Element.send_file`.
+
+        This method is no-op by default.
+
+        :param path: The (local) path of the file to upload.
+        :type path: :py:class:`pathlib.Path`
+        :returns: A path indicating the remote path.
+        :rtype: :py:class:`pathlib.Path`
+
+    .. py:method:: prefixed(prefix):
+
+        Returns a new connection, inheriting the HTTP session, with the extra
+        prefix given.
+
+        :param str prefix: Prefix to add to the current prefix.
+        :rtype: :py:class:`Connection`
+
+
+.. py:class:: RemoteConnection
+
+    Connection class for remote webdrivers. Most notably, :py:meth:`Connection.upload_file`
+    is no longer a no-op operation.

docs/reference/errors.rst

@@ -0,0 +1,54 @@
+``arsenic.errors``
+##################
+
+.. py:exception:: ArsenicError
+
+    Base exception class used by arsenic.
+
+.. py:exception:: OperationNotSupported
+
+    Exception raised for operations not supported by a given webdriver and/or
+    browser.
+
+.. py:exception:: WebdriverError
+
+    Base class for webdriver-side errors.
+
+
+.. py:exception:: UnkownArsenicError
+
+    Exception used when there was a webdriver-side error, but arsenic could not
+    figure out what the error was.
+
+
+.. py:exception:: ArsenicTimeout
+
+    Raised when :py:meth:`arsenic.webdriver.WebDriver.wait`,
+    :py:meth:`arsenic.session.Session.wait` or a higher level wait API times out.
+
+
+The following are specific exceptions which may be returned from a webdriver.
+Consult the webdriver specification for details.
+
+.. py:exception:: NoSuchElement
+.. py:exception:: NoSuchFrame
+.. py:exception:: UnknownCommand
+.. py:exception:: StaleElementReference
+.. py:exception:: ElementNotVisible
+.. py:exception:: InvalidElementState
+.. py:exception:: UnknownError
+.. py:exception:: ElementNotInteractable
+.. py:exception:: ElementIsNotSelectable
+.. py:exception:: JavascriptError
+.. py:exception:: Timeout
+.. py:exception:: NoSuchWindow
+.. py:exception:: InvalidCookieDomain
+.. py:exception:: UnableToSetCookie
+.. py:exception:: UnexpectedAlertOpen
+.. py:exception:: NoSuchAlert
+.. py:exception:: ScriptTimeout
+.. py:exception:: InvalidElementCoordinates
+.. py:exception:: IMENotAvailable
+.. py:exception:: IMEEngineActivationFailed
+.. py:exception:: InvalidSelector
+.. py:exception:: MoveTargetOutOfBounds

docs/reference/http.rst

@@ -0,0 +1,19 @@
+``arsenic.http``
+################
+
+This module holds http authentication helpers.
+
+.. py:module:: arsenic.http
+
+.. py:class:: Auth
+
+    Abstract base class for authentication.
+
+    .. py:method:: get_headers
+
+        Abstract method which returns a dictionary of headers.
+
+
+.. py:class:: BasicAuth(username, password)
+
+    Basic auth implementation of the :py:class:`Auth` abstract class.

docs/reference/index.rst

@@ -0,0 +1,57 @@
+API Refrence
+############
+
+.. toctree::
+    :maxdepth: 2
+    :caption: APIs
+
+    services
+    browsers
+    session
+    keys
+    actions
+    errors
+    webdriver
+    connection
+    http
+    utils
+
+
+Main APIs
+*********
+
+.. py:module:: arsenic
+
+.. py:function:: get_session(service, browser, bind=''):
+
+    Async context manager API to start/stop a browser session.
+
+    :param service: The service which manages the browser instance.
+    :type service: :py:class:`arsenic.services.Service`
+    :param browser: The browser to start.
+    :type browser: :py:class:`arsenic.browsers.Browser`
+    :param str bind: Optional URL to bind the browser to.
+    :return: An async context manager.
+
+
+.. py:function:: start_session(service, browser, bind=''):
+
+    Coroutine to start new session.
+
+    :param service: The service which manages the browser instance.
+    :type service: :py:class:`arsenic.services.Service`
+    :param browser: The browser to start.
+    :type browser: :py:class:`arsenic.browsers.Browser`
+    :param str bind: Optional URL to bind the br
+    :return: An object which can be passed to :py:func:`stop_session` to stop the session.
+
+
+.. py:function:: stop_session(session):
+
+    Coroutine to stop a session.
+
+    :param session: The session to stop.
+    :type session: Object returned from :py:func:`start_session`.
+    :return: Nothing.
+
+