Version 1.0.0

[andrewsayre]

Description:

This version implements all of the functionality documented in the HEOS CLI Protocol specification (version at this time 1.21 dated 10/06/2024). There are breaking changes from previous versions. See notes below.

Fixes/improvements: 🐛

• Invocation of the command_error callbacks now occur outside of the held lock for commands so that other commands could be called within the callback.
• When matching players after a refresh, serial is first used (if available), before matching on player_id or name.
• Connection retry logic now implements a doubling incremental backoff with a maximum delay of 10min.

New: 🚀

const Module:

• Added service option constants (e.g. SERVICE_OPTION_THUMBS_UP)

'error' module:

• Added CommandAuthenticationError a subclass of CommandFailedError which is raised when an auth-related error occurs calling a command.

Heos class:

• Added get_group_info method to retrieve or refresh a specific group. If all groups are loaded, this will retrieve the cached instance, unless refresh=True.
• Added get_player_info function to retrieve a specific player and optionally refresh and update an existing instance.
• Added check_update that returns True is an update is available for the player, otherwise `False.
• Added player_get_queue to retrieve the specified player's queue items.
• Added player_play_queue to play a specific queue index on the specified player.
• Added player_remove_from_queue to remove one or more items from the specified player's queue
• Added player_save_queue to save the specified player's queue as a playlist.
• Added player_move_queue_item to move items in the specified player's queue.
• Added get_music_source_info to retrieve or refresh a specific music source.
• Added get_search_criteria to obtain search options for a given source.
• Added search to perform a search against a source with specific criteria.
• Added rename_playlist to rename a playlist.
• Added delete_playlist to delete a playlist.
• Added retrieve_metadata to retrieve album metadata.
• Added set_service_option to call a service option, such as thumbs up.
• Added multi_search to search multiple sources and criteria.
• Added add_search_to_queue to add items to the queue for the specified player based on the search string.

HeosGroup class:

• Added parameter refresh_base_info: bool = True to refresh method to include updating the base information about the group (name, id, leader, members) in addition to mute and volume.

HeosPlayer class:

• Added parameter refresh_base_info: bool = True to refresh to optionally pull the latest player information, such as name.
• Added group_id field to represent the group reference the player is a member of, otherwise None.
• Added check_update that returns True is an update is available for the player, otherwise `False.
• Added get_queue to retrieve the player's queue items.
• Added play_queue to play a specific queue index on the player.
• Added remove_from_queue to remove one or more items from the player's queue
• Added save_queue to save the current queue as a playlist.
• Added move_queue_item to move items in the queue.
• Added control property to indicate the volume control type when lineout is Fixed.
• Added add_search_to_queue to add items to the queue for the current player based on the search string.

HeosNowPlayingMedia class:

• New attribute options: Sequence[ServiceOption] to list available service options.

Media module:

• New class ServiceOption for describing a service option.
• BrowseResult now has options: Sequence[ServiceOption] attribute to list available service options.
• New classes ImageMetadata, AlbumMetadata, and RetreiveMetadataResult to represent album metadata.

Search module:

• New classes SearchCriteria, SearchResult, MultiSearchResult, and SearchStatistic to represent output of search commands.

types Module:

• Contains all of the enumeration types, centralized from the library.
• Added ConnectionState enum to replace connection state constants (e.g. STATE_CONNECTED)
• Added ControlType enum to replace play control constants (e.g. CONTROL_PLAY)
• Added NetworkType enum to replace network connection constants (e.g. NETWORK_TYPE_WIFI)
• Added SignalType enum to replace signal constants (e.g. SIGNAL_HEOS_EVENT)
• Added SignalHeosEvent enum to replace event constants (e.g. EVENT_CONNECTED)
• Added LineOutLevelType and VolumeControlType

Changed ⏸️

const module:

• Removed connection state const (e.g. STATE_CONNECTED). Use ConnectionState instead.
• Removed control consts (e.g. CONTROL_PLAY). Use ControlType instead.
• Removed network connection constants (e.g. NETWORK_TYPE_WIFI). Use NetworkType instead.
• Removed signal constants (.e.g SIGNAL_HEOS_EVENT). Use SignalType instead.
• Removed dispatched event consts (.e.g EVENT_CONNECTED). Use SignalHeosEvent instead.

Heos class:

• Function load_players now returns an instance of PlayerUpdateResult instead of a dictionary.

HeosPlayer class:

• Field lineout is now an enum of type LineOutLevelType

Checklist:

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• Tests have been added/updated. No exclusions in .coveragerc permitted.
• README.MD updated (if necessary)