Collection plexapi.collection

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

Bases: plexapi.base.PlexPartialObject, plexapi.mixins.AdvancedSettingsMixin, plexapi.mixins.SmartFilterMixin, plexapi.mixins.HubsMixin, plexapi.mixins.RatingMixin, plexapi.mixins.ArtMixin, plexapi.mixins.PosterMixin, plexapi.mixins.ThemeMixin, plexapi.mixins.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.
• 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).
• 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.
• 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’
• updatedAt (datetime) – Datetime the collection was updated.
• userRating (float) – Rating of the collection (0.0 - 10.0) equaling (0 stars - 5 stars).

listType

Returns the listType for the collection.

metadataType

Returns the type of metadata in the collection.

isVideo

Returns True if this is a video collection.

isAudio

Returns True if this is an audio collection.

isPhoto

Returns True if this is a photo collection.

filters()

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

section()

Returns the LibrarySection this collection belongs to.

item(title)

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()

Returns a list of all items in the collection.

visibility()

Returns the ManagedHub for this collection.

get(title)

Alias to item().

filterUserUpdate(user=None)

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)

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)

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)

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)

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)

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)

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(**kwargs)

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()

Delete the collection.

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

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:

• plexapi.exceptions.BadRequest – When no items are included to create the collection.
• plexapi.exceptions.BadRequest – When mixing media types in the collection.

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)

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

metadataDirectory

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