Collection plexapi.collection

class plexapi.collection.Collection(server, data, initpath=None, parent=None)[source]

Bases: PlexPartialObject, AdvancedSettingsMixin, SmartFilterMixin, HubsMixin, RatingMixin, ArtMixin, PosterMixin, ThemeMixin, CollectionEditMixins

Represents a single Collection.

Variables:

  • TAG (str) – ‘Directory’

  • TYPE (str) – ‘collection’

  • addedAt (datetime) – Datetime the collection was added to the library.

  • art (str) – URL to artwork image (/library/metadata/<ratingKey>/art/<artid>).

  • artBlurHash (str) – BlurHash string for artwork image.

  • audienceRating (float) – Audience rating.

  • childCount (int) – Number of items in the collection.

  • collectionFilterBasedOnUser (int) – Which user’s activity is used for the collection filtering.

  • collectionMode (int) – How the items in the collection are displayed.

  • collectionPublished (bool) – True if the collection is published to the Plex homepage.

  • collectionSort (int) – How to sort the items in the collection.

  • content (str) – The filter URI string for smart collections.

  • contentRating (str) Content rating (PG-13; NR; TV-G)

  • fields (List<Field>) – List of field objects.

  • guid (str) – Plex GUID for the collection (collection://XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX).

  • images (List<Image>) – List of image objects.

  • index (int) – Plex index number for the collection.

  • key (str) – API URL (/library/metadata/<ratingkey>).

  • labels (List<Label>) – List of label objects.

  • lastRatedAt (datetime) – Datetime the collection was last rated.

  • librarySectionID (int) – LibrarySection ID.

  • librarySectionKey (str) – LibrarySection key.

  • librarySectionTitle (str) – LibrarySection title.

  • maxYear (int) – Maximum year for the items in the collection.

  • minYear (int) – Minimum year for the items in the collection.

  • rating (float) – Collection rating (7.9; 9.8; 8.1).

  • ratingCount (int) – The number of ratings.

  • ratingKey (int) – Unique key identifying the collection.

  • smart (bool) – True if the collection is a smart collection.

  • subtype (str) – Media type of the items in the collection (movie, show, artist, or album).

  • summary (str) – Summary of the collection.

  • theme (str) – URL to theme resource (/library/metadata/<ratingkey>/theme/<themeid>).

  • thumb (str) – URL to thumbnail image (/library/metadata/<ratingKey>/thumb/<thumbid>).

  • thumbBlurHash (str) – BlurHash string for thumbnail image.

  • title (str) – Name of the collection.

  • titleSort (str) – Title to use when sorting (defaults to title).

  • type (str) – ‘collection’

  • ultraBlurColors (UltraBlurColors) – Ultra blur color object.

  • updatedAt (datetime) – Datetime the collection was updated.

  • userRating (float) – Rating of the collection (0.0 - 10.0) equaling (0 stars - 5 stars).

property listType

Returns the listType for the collection.

property metadataType

Returns the type of metadata in the collection.

property isVideo

Returns True if this is a video collection.

property isAudio

Returns True if this is an audio collection.

property isPhoto

Returns True if this is a photo collection.

filters()[source]

Returns the search filter dict for smart collection. The filter dict be passed back into search() to get the list of items.

section()[source]

Returns the LibrarySection this collection belongs to.

item(title)[source]

Returns the item in the collection that matches the specified title.

Parameters:

title (str) – Title of the item to return.

Raises:

plexapi.exceptions.NotFound – When the item is not found in the collection.

items()[source]

Returns a list of all items in the collection.

visibility()[source]

Returns the ManagedHub for this collection.

get(title)[source]

Alias to item().

filterUserUpdate(user=None)[source]

Update the collection filtering user advanced setting.

Parameters:

user (str) – One of the following values: “admin” (Always the server admin user), “user” (User currently viewing the content)

Example

collection.updateMode(user="user")
modeUpdate(mode=None)[source]

Update the collection mode advanced setting.

Parameters:

mode (str) – One of the following values: “default” (Library default), “hide” (Hide Collection), “hideItems” (Hide Items in this Collection), “showItems” (Show this Collection and its Items)

Example

collection.updateMode(mode="hide")
sortUpdate(sort=None)[source]

Update the collection order advanced setting.

Parameters:

sort (str) – One of the following values: “release” (Order Collection by release dates), “alpha” (Order Collection alphabetically), “custom” (Custom collection order)

Example

collection.sortUpdate(sort="alpha")
addItems(items)[source]

Add items to the collection.

Parameters:

items (List) – List of Audio, Video, or Photo objects to be added to the collection.

Raises:

plexapi.exceptions.BadRequest – When trying to add items to a smart collection.

removeItems(items)[source]

Remove items from the collection.

Parameters:

items (List) – List of Audio, Video, or Photo objects to be removed from the collection.

Raises:

plexapi.exceptions.BadRequest – When trying to remove items from a smart collection.

moveItem(item, after=None)[source]

Move an item to a new position in the collection.

Parameters:

  • item (obj) – Audio, Video, or Photo object to be moved in the collection.

  • after (obj) – Audio, Video, or Photo object to move the item after in the collection.

Raises:

plexapi.exceptions.BadRequest – When trying to move items in a smart collection.

updateFilters(libtype=None, limit=None, sort=None, filters=None, **kwargs)[source]

Update the filters for a smart collection.

Parameters:

  • libtype (str) – The specific type of content to filter (movie, show, season, episode, artist, album, track, photoalbum, photo, collection).

  • limit (int) – Limit the number of items in the collection.

  • sort (str or list, optional) – A string of comma separated sort fields or a list of sort fields in the format column:dir. See search() for more info.

  • filters (dict) – A dictionary of advanced filters. See search() for more info.

  • **kwargs (dict) – Additional custom filters to apply to the search results. See search() for more info.

Raises:

plexapi.exceptions.BadRequest – When trying update filters for a regular collection.

edit(title=None, titleSort=None, contentRating=None, summary=None, **kwargs)[source]

Edit the collection.

Parameters:

  • title (str, optional) – The title of the collection.

  • titleSort (str, optional) – The sort title of the collection.

  • contentRating (str, optional) – The summary of the collection.

  • summary (str, optional) – The summary of the collection.

delete()[source]

Delete the collection.

classmethod create(server, title, section, items=None, smart=False, limit=None, libtype=None, sort=None, filters=None, **kwargs)[source]

Create a collection.

Parameters:

  • server (PlexServer) – Server to create the collection on.

  • title (str) – Title of the collection.

  • section (LibrarySection, str) – The library section to create the collection in.

  • items (List) – Regular collections only, list of Audio, Video, or Photo objects to be added to the collection.

  • smart (bool) – True to create a smart collection. Default False.

  • limit (int) – Smart collections only, limit the number of items in the collection.

  • libtype (str) – Smart collections only, the specific type of content to filter (movie, show, season, episode, artist, album, track, photoalbum, photo).

  • sort (str or list, optional) – Smart collections only, a string of comma separated sort fields or a list of sort fields in the format column:dir. See search() for more info.

  • filters (dict) – Smart collections only, a dictionary of advanced filters. See search() for more info.

  • **kwargs (dict) – Smart collections only, additional custom filters to apply to the search results. See search() for more info.

Raises:
Returns:

A new instance of the created Collection.

Return type:

Collection

sync(videoQuality=None, photoResolution=None, audioBitrate=None, client=None, clientId=None, limit=None, unwatched=False, title=None)[source]

Add the collection as sync item for the specified device. See sync() for possible exceptions.

Parameters:

  • videoQuality (int) – idx of quality of the video, one of VIDEO_QUALITY_* values defined in sync module. Used only when collection contains video.

  • photoResolution (str) – maximum allowed resolution for synchronized photos, see PHOTO_QUALITY_* values in the module sync. Used only when collection contains photos.

  • audioBitrate (int) – maximum bitrate for synchronized music, better use one of MUSIC_BITRATE_* values from the module sync. Used only when collection contains audio.

  • client (MyPlexDevice) – sync destination, see sync().

  • clientId (str) – sync destination, see sync().

  • limit (int) – maximum count of items to sync, unlimited if None.

  • unwatched (bool) – if True watched videos wouldn’t be synced.

  • title (str) – descriptive title for the new SyncItem, if empty the value would be generated from metadata of current photo.

Raises:

  • BadRequest – When collection is not allowed to sync.

  • Unsupported – When collection content is unsupported.

Returns:

A new instance of the created sync item.

Return type:

SyncItem

property metadataDirectory

Returns the Plex Media Server data directory where the metadata is stored.