API — pyatv 0.0.1 documentation

# API

This page contains documentation for all public APIs in pyatv.

NOTE: Currently, the content on this page is far from complete. It will be updated as time goes. Feel free to help out.

## Module contents

Library for controlling an Apple TV.

class `pyatv.` `AppleTVDevice`

  Bases: `pyatv.AppleTVDevice`

  Representation of an Apple TV device used when connecting.

`pyatv.` `connect_to_apple_tv`(details, loop)

  Connect and logins to an Apple TV.

`pyatv.` `pair_with_apple_tv`(loop, pin_code, name)

  Initiate pairing process with an Apple TV.

`pyatv.` `scan_for_apple_tvs`(loop, timeout=5)

  Scan for Apple TVs using zeroconf (bonjour) and returns them.

## Submodules

## pyatv.const module

Constants used in the public API.

`pyatv.const.` `MEDIA_TYPE_MUSIC` = 3

  Media type is music

`pyatv.const.` `MEDIA_TYPE_TV` = 4

  Media type is TV

`pyatv.const.` `MEDIA_TYPE_UNKNOWN` = 1

  Media type is unknown

`pyatv.const.` `MEDIA_TYPE_VIDEO` = 2

  Media type is video

`pyatv.const.` `PLAY_STATE_FAST_BACKWARD` = 6

  Media is being rewinded

`pyatv.const.` `PLAY_STATE_FAST_FORWARD` = 5

  Media is being fast forwarded

`pyatv.const.` `PLAY_STATE_LOADING` = 2

  Media is loading/buffering

`pyatv.const.` `PLAY_STATE_NO_MEDIA` = 1

  No media is currently select/playing

`pyatv.const.` `PLAY_STATE_PAUSED` = 3

  Media is paused

`pyatv.const.` `PLAY_STATE_PLAYING` = 4

  Media is playing

## pyatv.exceptions module

Local exceptions used by library.

exception `pyatv.exceptions.` `AuthenticationError`

  Bases: `Exception`

  Thrown when login fails.

exception `pyatv.exceptions.` `InvalidDmapDataError`

  Bases: `Exception`

  Thrown when invalid DMAP data is parsed.

exception `pyatv.exceptions.` `NotSupportedError`

  Bases: `Exception`

  Thrown when trying to perform an action that is not supported.

exception `pyatv.exceptions.` `UnknownMediaKind`

  Bases: `Exception`

  Thrown when an unknown media kind is found.

exception `pyatv.exceptions.` `UnknownPlayState`

  Bases: `Exception`

  Thrown when an unknown play state is found.

exception `pyatv.exceptions.` `UnknownServerResponseError`

  Bases: `Exception`

  Thrown when somethins unknown is send back from the Apple TV.

## pyatv.helpers module

Various helper methods.

`pyatv.helpers.` `auto_connect`(handler, not_found=None, event_loop=None)

  Convenient method for connecting to a device.

  This is a convenience method that create an event loop, auto discovers devices, picks the first device found, connects to it and passes it to a user provided handler. An optional error handler can be provided that is called when no device was found. Very inflexible in many cases, but can be handys sometimes when trying things.

  Note 1: both handler and not_found must be coroutines Note 2: An optional loop can be passed if needed (mainly for testing)

## pyatv.interface module

API exposed by the library.

class `pyatv.interface.` `AppleTV`

  Bases: `object`

  Base class representing an Apple TV.

  `login`()

    Perform an explicit login.

    Not needed as login is performed automatically.

  `logout`()

    Perform an explicit logout.

    Must be done when session is no longer needed to not leak resources.

  `metadata`

    Return API for retrieving metadata from the Apple TV.

  `remote_control`

    Return API for controlling the Apple TV.

class `pyatv.interface.` `Metadata`

  Bases: `object`

  Base class for retrieving metadata from an Apple TV.

  `artwork`()

    Return artwork for what is currently playing (or None).

  `playing`()

    Return what is currently playing.

class `pyatv.interface.` `Playing`

  Bases: `object`

  Base class for retrieving what is currently playing.

  `album`

    Album of the currently playing song.

  `artist`

    Artist of the currently playing song.

  `media_type`

    What type of media is currently playing, e.g. video, music.

  `play_state`

    Current play state, e.g. playing or paused.

  `position`

    Current position in the playing media (seconds).

  `title`

    Title of the current media, e.g. movie or song name.

  `total_time`

    Total play time in seconds.

class `pyatv.interface.` `RemoteControl`

  Bases: `object`

  Base class for API used to control an Apple TV.

  `down`()

    Press key down.

  `left`()

    Press key left.

  `menu`()

    Press key menu.

  `next`()

    Press key next.

  `pause`()

    Press key play.

  `play`()

    Press key play.

  `play_url`(url, start_position=0, port=7000)

    Play media from an URL on the device.

  `previous`()

    Press key previous.

  `right`()

    Press key right.

  `select`()

    Press key select.

  `set_position`(pos)

    Seek in the current playing media.

  `topmenu`()

    Go to main menu (long press menu).

  `up`()

    Press key up.

`pyatv.interface.` `retrieve_commands`(obj, developer=False)

  Retrieve all commands and help texts from an API object.