From 07b3abc4c899d6b55b57be103ea22fd132e9171a Mon Sep 17 00:00:00 2001 From: Michael Shepanski Date: Fri, 24 Feb 2017 11:18:54 -0500 Subject: [PATCH] Document Settings; Cleanup style a bit --- docs/_static/custom.css | 7 ++ docs/conf.py | 3 + docs/global.rst | 2 + docs/modules/audio.rst | 6 +- docs/modules/base.rst | 6 +- docs/modules/client.rst | 6 +- docs/modules/config.rst | 6 +- docs/modules/exceptions.rst | 6 +- docs/modules/library.rst | 6 +- docs/modules/media.rst | 6 +- docs/modules/myplex.rst | 6 +- docs/modules/notify.py | 5 -- docs/modules/notify.rst | 7 ++ docs/modules/photo.rst | 6 +- docs/modules/playlist.rst | 6 +- docs/modules/playqueue.rst | 6 +- docs/modules/server.rst | 6 +- docs/modules/settings.rst | 138 ++++++++++++++++++++++++++++++++++++ docs/modules/sync.rst | 6 +- docs/modules/utils.rst | 6 +- docs/modules/video.rst | 9 ++- docs/toc.rst | 1 + plexapi/notify.py | 26 ++++--- plexapi/settings.py | 52 +++++++++++--- tools/listsettings.py | 23 ++++++ 25 files changed, 301 insertions(+), 56 deletions(-) create mode 100644 docs/_static/custom.css create mode 100644 docs/global.rst delete mode 100644 docs/modules/notify.py create mode 100644 docs/modules/notify.rst create mode 100644 docs/modules/settings.rst create mode 100644 tools/listsettings.py diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 00000000..52b9ada8 --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,7 @@ +.modname { + font-size: 0.8em; + opacity: 0.4; +} +.modname::before { + content: '- '; +} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index bd288096..b0101c65 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -134,12 +134,15 @@ todo_include_todos = False # html_theme = 'alabaster' html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_static_path = ['_static'] +html_context = {'css_files': ['_static/custom.css']} html_theme_options = { 'collapse_navigation': False, 'display_version': False, #'navigation_depth': 3, } + # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. diff --git a/docs/global.rst b/docs/global.rst new file mode 100644 index 00000000..3c650a1a --- /dev/null +++ b/docs/global.rst @@ -0,0 +1,2 @@ +.. role:: modname + :class: modname diff --git a/docs/modules/audio.rst b/docs/modules/audio.rst index 1aeb937c..33820298 100644 --- a/docs/modules/audio.rst +++ b/docs/modules/audio.rst @@ -1,5 +1,7 @@ -Audio (plexapi.audio) ---------------------- +.. include:: ../global.rst + +Audio :modname:`plexapi.audio` +------------------------------ .. automodule:: plexapi.audio :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/base.rst b/docs/modules/base.rst index eb05ed25..fe0d210b 100644 --- a/docs/modules/base.rst +++ b/docs/modules/base.rst @@ -1,5 +1,7 @@ -Base (plexapi.base) ---------------------- +.. include:: ../global.rst + +Base :modname:`plexapi.base` +------------------------------ .. automodule:: plexapi.base :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/client.rst b/docs/modules/client.rst index 9209f9ce..2fe69a9d 100644 --- a/docs/modules/client.rst +++ b/docs/modules/client.rst @@ -1,5 +1,7 @@ -Client (plexapi.client) ------------------------ +.. include:: ../global.rst + +Client :modname:`plexapi.client` +-------------------------------- .. automodule:: plexapi.client :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/config.rst b/docs/modules/config.rst index 12f330d3..44a61b16 100644 --- a/docs/modules/config.rst +++ b/docs/modules/config.rst @@ -1,5 +1,7 @@ -Config (plexapi.config) ------------------------ +.. include:: ../global.rst + +Config :modname:`plexapi.config` +-------------------------------- .. automodule:: plexapi.config :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/exceptions.rst b/docs/modules/exceptions.rst index e4567517..299eb5bd 100644 --- a/docs/modules/exceptions.rst +++ b/docs/modules/exceptions.rst @@ -1,5 +1,7 @@ -Exceptions (plexapi.exceptions) -------------------------------- +.. include:: ../global.rst + +Exceptions :modname:`plexapi.exceptions` +---------------------------------------- .. automodule:: plexapi.exceptions :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/library.rst b/docs/modules/library.rst index f7f31283..1bb88388 100644 --- a/docs/modules/library.rst +++ b/docs/modules/library.rst @@ -1,5 +1,7 @@ -Library (plexapi.library) -------------------------- +.. include:: ../global.rst + +Library :modname:`plexapi.library` +---------------------------------- .. automodule:: plexapi.library :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/media.rst b/docs/modules/media.rst index cc1d1916..d0a15f8b 100644 --- a/docs/modules/media.rst +++ b/docs/modules/media.rst @@ -1,5 +1,7 @@ -Media (plexapi.media) ---------------------- +.. include:: ../global.rst + +Media :modname:`plexapi.media` +------------------------------ .. automodule:: plexapi.media :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/myplex.rst b/docs/modules/myplex.rst index 88e3c109..7c2f8469 100644 --- a/docs/modules/myplex.rst +++ b/docs/modules/myplex.rst @@ -1,5 +1,7 @@ -MyPlex (plexapi.myplex) ------------------------ +.. include:: ../global.rst + +MyPlex :modname:`plexapi.myplex` +-------------------------------- .. automodule:: plexapi.myplex :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/notify.py b/docs/modules/notify.py deleted file mode 100644 index 26609610..00000000 --- a/docs/modules/notify.py +++ /dev/null @@ -1,5 +0,0 @@ -Notify (plexapi.notify) ---------------------- -.. automodule:: plexapi.notify - :members: - :show-inheritance: \ No newline at end of file diff --git a/docs/modules/notify.rst b/docs/modules/notify.rst new file mode 100644 index 00000000..c81271a5 --- /dev/null +++ b/docs/modules/notify.rst @@ -0,0 +1,7 @@ +.. include:: ../global.rst + +Notify :modname:`plexapi.notify` +-------------------------------- +.. automodule:: plexapi.notify + :members: + :show-inheritance: \ No newline at end of file diff --git a/docs/modules/photo.rst b/docs/modules/photo.rst index 56e23503..42edb714 100644 --- a/docs/modules/photo.rst +++ b/docs/modules/photo.rst @@ -1,5 +1,7 @@ -Photo (plexapi.photo) ---------------------- +.. include:: ../global.rst + +Photo :modname:`plexapi.photo` +------------------------------ .. automodule:: plexapi.photo :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/playlist.rst b/docs/modules/playlist.rst index 88df8e14..c49b21af 100644 --- a/docs/modules/playlist.rst +++ b/docs/modules/playlist.rst @@ -1,5 +1,7 @@ -Playlist (plexapi.playlist) ---------------------------- +.. include:: ../global.rst + +Playlist :modname:`plexapi.playlist` +------------------------------------ .. automodule:: plexapi.playlist :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/playqueue.rst b/docs/modules/playqueue.rst index 66593691..3d4def60 100644 --- a/docs/modules/playqueue.rst +++ b/docs/modules/playqueue.rst @@ -1,5 +1,7 @@ -Playqueue (plexapi.playqueue) ------------------------------ +.. include:: ../global.rst + +Playqueue :modname:`plexapi.playqueue` +-------------------------------------- .. automodule:: plexapi.playqueue :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/server.rst b/docs/modules/server.rst index f775bb02..2ded0734 100644 --- a/docs/modules/server.rst +++ b/docs/modules/server.rst @@ -1,5 +1,7 @@ -Server (plexapi.server) ------------------------ +.. include:: ../global.rst + +Server :modname:`plexapi.server` +-------------------------------- .. automodule:: plexapi.server :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/settings.rst b/docs/modules/settings.rst new file mode 100644 index 00000000..7595cd06 --- /dev/null +++ b/docs/modules/settings.rst @@ -0,0 +1,138 @@ +.. include:: ../global.rst + +Settings :modname:`plexapi.settings` +------------------------------------ +.. automodule:: plexapi.settings + :members: + :show-inheritance: + + +Misc Settings +--------------------------- +* **AcceptedEULA** (bool): Has the user accepted the EULA. +* **AllowHighOutputBitrates** (bool): +* **BackgroundQueueIdlePaused** (bool): +* **ButlerTaskGenerateMediaIndexFiles** (bool): +* **CertificateVersion** (int): (default: 2) +* **DisableHlsAuthorization** (bool): +* **GenerateIndexFilesDuringAnalysis** (bool): +* **GracenoteUser** (text): +* **LanguageInCloud** (bool): Use language preferences from plex.tv. +* **LastAutomaticMappedPort** (int): +* **MachineIdentifier** (text): A unique identifier for the machine. +* **ManualPortMappingMode** (bool): +* **ManualPortMappingPort** (int): (default: 32400) +* **PlexMetricsUrl** (text): (default: https://metrics.plex.tv) +* **PlexOnlineMail** (text): +* **PlexOnlineUrl** (text): (default: https://plex.tv) +* **PublishServerOnPlexOnlineKey** (bool): Publish server on Plex Online. Publishing a server makes it automatically available on your client devices without any configuration of your router. +* **SyncMyPlexLoginGCDeferral** (int): (default: 14400) +* **SyncPagingItemsLimit** (int): (default: 100) +* **TranscoderCanOnlyRemuxVideo** (bool): The transcoder can only remux video. +* **TranscoderVideoResolutionLimit** (text): Maximum video output resolution for the transcoder. (default: 0x0) +* **WanPerStreamMaxUploadRate** (int): Limit remote stream bitrate. Set the maximum bitrate of a remote stream from this server. +* **WanTotalMaxUploadRate** (int): External network total upload limit (kbps). Speed at which to limit the total bandwidth not on the local network in kilobits per second. Use 0 to set no limit. + +Butler Settings +--------------------------- +* **ButlerDatabaseBackupPath** (text): Backup directory. The directory in which database backups are stored. (default: /var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-in Support/Databases) +* **ButlerEndHour** (int): Time at which tasks stop running. The time at which the background maintenance tasks stop running. (default: 5; available: 0:Midnight|1:1 am|2:2 am|3:3 am|4:4 am|5:5 am|6:6 am|7:7 am|8:8 am|9:9 am|10:10 am|11:11 am|12:Noon|13:1 pm|14:2 pm|15:3 pm|16:4 pm|17:5 pm|18:6 pm|19:7 pm|20:8 pm|21:9 pm|22:10 pm|23:11 pm) +* **ButlerStartHour** (int): Time at which tasks start to run. The time at which the server starts running background maintenance tasks. (default: 2; available: 0:Midnight|1:1 am|2:2 am|3:3 am|4:4 am|5:5 am|6:6 am|7:7 am|8:8 am|9:9 am|10:10 am|11:11 am|12:Noon|13:1 pm|14:2 pm|15:3 pm|16:4 pm|17:5 pm|18:6 pm|19:7 pm|20:8 pm|21:9 pm|22:10 pm|23:11 pm) +* **ButlerTaskBackupDatabase** (bool): Backup database every three days. (default: True) +* **ButlerTaskCleanOldBundles** (bool): Remove old bundles every week. (default: True) +* **ButlerTaskCleanOldCacheFiles** (bool): Remove old cache files every week. (default: True) +* **ButlerTaskDeepMediaAnalysis** (bool): Perform extensive media analysis during maintenance. (default: True) +* **ButlerTaskGenerateAutoTags** (bool): Analyze and tag photos. (default: True) +* **ButlerTaskOptimizeDatabase** (bool): Optimize database every week. (default: True) +* **ButlerTaskRefreshLibraries** (bool): Update all libraries during maintenance. +* **ButlerTaskRefreshLocalMedia** (bool): Refresh local metadata every three days. (default: True) +* **ButlerTaskRefreshPeriodicMetadata** (bool): Refresh metadata periodically. (default: True) +* **ButlerTaskUpgradeMediaAnalysis** (bool): Upgrade media analysis during maintenance. (default: True) + +Channels Settings +--------------------------- +* **disableCapabilityChecking** (bool): Disable capability checking. Capability checking ensures that plug-ins that are incompatible with this version of the server or the current client application you are using are hidden. Disabling capability checking is useful during development, but will enable access to plug-ins that may perform unreliably with certain client applications. +* **iTunesLibraryXmlPath** (text): iTunes library XML path. +* **iTunesSharingEnabled** (bool): Enable iTunes channel. A server restart is required for a change to take effect. +* **PluginsLaunchTimeout** (int): Number of seconds to wait before a plugin times out. (default: 180) + +Dlna Settings +--------------------------- +* **DlnaAnnouncementLeaseTime** (int): DLNA server announcement lease time. Duration in seconds of DLNA Server SSDP announcement lease time. (default: 1800) +* **DlnaClientPreferences** (text): DLNA client preferences. Client-specific configuration settings for the DLNA server. +* **DlnaDefaultProtocolInfo** (text): DLNA default protocol info. Protocol info string used in GetProtocolInfo responses by the DLNA server. (default: http-get:*:video/mpeg:*,http-get:*:video/mp4:*,http-get:*:video/vnd.dlna.mpeg-tts:*,http-get:*:video/avi:*,http-get:*:video/x-matroska:*,http-get:*:video/x-ms-wmv:*,http-get:*:video/wtv:*,http-get:*:audio/mpeg:*,http-get:*:audio/mp3:*,http-get:*:audio/mp4:*,http-get:*:audio/x-ms-wma*,http-get:*:audio/wav:*,http-get:*:audio/L16:*,http-get:*image/jpeg:*,http-get:*image/png:*,http-get:*image/gif:*,http-get:*image/tiff:*) +* **DlnaDescriptionIcons** (text): DLNA server description icons. Icons offered by DLNA server when devices request server description. (default: png,jpeg;260x260,120x120,48x48) +* **DlnaDeviceDiscoveryInterval** (int): DLNA media renderer discovery interval. Number of seconds between DLNA media renderer discovery requests. (default: 60) +* **DlnaEnabled** (bool): Enable the DLNA server. This allows the server to stream media to DLNA (Digital Living Network Alliance) devices. (default: True) +* **DlnaPlatinumLoggingLevel** (text): DLNA server logging level. (default: OFF; available: OFF|FATAL|SEVERE|WARNING|INFO|FINE|FINER|FINEST|ALL) +* **DlnaReportTimeline** (bool): DLNA server timeline reporting. Enable the DLNA server to report timelines for video play activity. (default: True) + +Extras Settings +--------------------------- +* **CinemaTrailersFromBluRay** (bool): Include Cinema Trailers from new and upcoming movies on Blu-ray. This feature is Plex Pass only. +* **CinemaTrailersFromLibrary** (bool): Include Cinema Trailers from movies in my library. (default: True) +* **CinemaTrailersFromTheater** (bool): Include Cinema Trailers from new and upcoming movies in theaters. This feature is Plex Pass only. +* **CinemaTrailersPrerollID** (text): Cinema Trailers pre-roll video. Copy and paste the video's detail page URL into this field. +* **CinemaTrailersType** (int): Choose Cinema Trailers from. (default: 1; available: 0:All movies|1:Only unwatched movies) + +General Settings +--------------------------- +* **ButlerTaskCheckForUpdates** (bool): Automatically check for updates. (default: True) +* **ButlerUpdateChannel** (text): Update Channel. (default: 16; available: 16:Public|8:Plex Pass) +* **collectUsageData** (bool): Send anonymous usage data to Plex. This helps us improve your experience (for example, to help us match movies and TV shows). (default: True) +* **FriendlyName** (text): Friendly name. This name will be used to identify this media server to other computers on your network. If you leave it blank, your computer's name will be used instead. +* **logDebug** (bool): Enable Plex Media Server debug logging. (default: True) +* **logTokens** (bool): Allow Plex Media Server tokens in logs. Media server tokens can be used to gain access to library content. Don't share logs containing tokens publicly. A server restart is required for a change to take effect. +* **LogVerbose** (bool): Enable Plex Media Server verbose logging. +* **MinimumProgressTime** (int): (default: 60000) + +Library Settings +--------------------------- +* **AlbumSort** (text): (default: year:desc) +* **allowMediaDeletion** (bool): Allow media deletion. The owner of the server will be allowed to delete media files from disk. +* **autoEmptyTrash** (bool): Empty trash automatically after every scan. (default: True) +* **FSEventLibraryPartialScanEnabled** (bool): Run a partial scan when changes are detected. When changes to library folders are detected, only scan the folder that changed. +* **FSEventLibraryUpdatesEnabled** (bool): Update my library automatically. Your library will be updated automatically when changes to library folders are detected. +* **GenerateBIFBehavior** (text): Generate video preview thumbnails. Video preview thumbnails provide live updates in Now Playing and while seeking on supported apps. Thumbnail generation may take a long time, cause high CPU usage, and consume additional disk space. You can turn off thumbnail generation for individual libraries in the library's advanced settings. (default: never; available: never:never|scheduled:as a scheduled task|asap:as a scheduled task and when media is added) +* **GenerateChapterThumbBehavior** (text): Generate chapter thumbnails. Chapter thumbnails provide images in the chapter view on supported apps. They can take a long time to generate and consume additional disk space. (default: scheduled; available: never:never|scheduled:as a scheduled task|asap:as a scheduled task and when media is added) +* **OnDeckWindow** (int): Weeks to consider for On Deck. Shows that have not been watched in this many weeks will not appear in On Deck. (default: 16) +* **ScannerLowPriority** (bool): Run scanner tasks at a lower priority. +* **ScheduledLibraryUpdateInterval** (int): Library update interval. (default: 3600; available: 900:every 15 minutes|1800:every 30 minutes|3600:hourly|7200:every 2 hours|21600:every 6 hours|43200:every 12 hours|86400:daily) +* **ScheduledLibraryUpdatesEnabled** (bool): Update my library periodically. +* **watchMusicSections** (bool): Include music libraries in automatic updates. Linux systems limit the maximum number of watched directories; this may cause problems with large music libraries. + +Network Settings +--------------------------- +* **allowedNetworks** (text): List of IP addresses and networks that are allowed without auth. Comma separated list of IP addresses or IP/netmask entries for networks that are allowed to access Plex Media Server without logging in. When the server is signed out and this value is set, only localhost and addresses on this list will be allowed. +* **ConfigurationUrl** (text): Web Manager URL. (default: http://127.0.0.1:32400/web) +* **customCertificateDomain** (text): Custom certificate domain. Domain name to be published to plex.tv using your mapped port; must match a name from the custom certificate file. +* **customCertificateKey** (text): Custom certificate encryption key. +* **customCertificatePath** (text): Custom certificate location. Path to a PKCS #12 file containing a certificate and private key to enable TLS support on a custom domain. +* **customConnections** (text): Custom server access URLs. A comma-separated list of URLs (http or https) which are published up to plex.tv for server discovery. +* **enableAirplay** (bool): +* **enableHttpPipelining** (bool): Enable HTTP Pipelining. This feature can enable higher performance in the HTTP server component. A server restart is required for a change to take effect. (default: True) +* **EnableIPv6** (bool): Enable server support for IPv6. +* **GdmEnabled** (bool): Enable local network discovery (GDM). This enables the media server to discover other servers and players on the local network. (default: True) +* **LanNetworksBandwidth** (text): LAN Networks. Comma separated list of IP addresses or IP/netmask entries for networks that will be considered to be on the local network when enforcing bandwidth restrictions. If set, all other IP addresses will be considered to be on the external network and and will be subject to external network bandwidth restrictions. If left blank, only the server's subnet is considered to be on the local network. +* **secureConnections** (int): Secure connections. When set to "Required", some unencrypted connections (originating from the Media Server computer) will still be allowed and apps that don't support secure connections will not be able to connect at all. (default: 1; available: 0:Required|1:Preferred|2:Disabled) +* **WebHooksEnabled** (bool): Webhooks. This feature enables your server to send events to external services. (default: True) + +Transcoder Settings +--------------------------- +* **HardwareAcceleratedCodecs** (bool): (default: True) +* **HardwareDevicePath** (text): (default: /dev/dri/renderD128) +* **SegmentedTranscoderTimeout** (int): Segmented transcoder timeout. Timeout in seconds segmented transcodes wait for the transcoder to begin writing data. (default: 20) +* **SystemAudioCodecs** (bool): (default: True) +* **SystemVideoCodecs** (bool): +* **TranscodeCountLimit** (int): Maximum simultaneous video transcode. Limit the number of simultaneous video transcode streams your server can utilize +* **TranscoderDefaultDuration** (int): Transcoder default duration. Duration in minutes to use when transcoding something with an unknown duration. (default: 120) +* **TranscoderH264BackgroundPreset** (text): Background transcoding x264 preset. The x264 preset value used for background transcoding (Sync and Media Optimizer). Slower values will result in better video quality and smaller file sizes, but will take significantly longer to complete processing. (default: veryfast; available: ultrafast:Ultra fast|superfast:Super fast|veryfast:Very fast|faster:Faster|fast:Fast|medium:Medium|slow:Slow|slower:Slower|veryslow:Very slow) +* **TranscoderH264MinimumCRF** (double): (default: 16.0) +* **TranscoderH264Options** (text): +* **TranscoderH264OptionsOverride** (text): +* **TranscoderH264Preset** (text): (default: veryfast) +* **TranscoderLogLevel** (text): (default: error; available: quiet|panic|fatal|error|warning|info|verbose|debug) +* **TranscoderPruneBuffer** (int): Transcoder default prune buffer. Amount in past seconds to retain before pruning segments from a transcode. (default: 300) +* **TranscoderQuality** (int): Transcoder quality. Quality profile used by the transcoder. +* **TranscoderTempDirectory** (text): Transcoder temporary directory. Directory to use when transcoding for temporary files. +* **TranscoderThrottleBuffer** (int): Transcoder default throttle buffer. Amount in seconds to buffer before throttling the transcoder. (default: 60) \ No newline at end of file diff --git a/docs/modules/sync.rst b/docs/modules/sync.rst index 791d161b..b3c624ac 100644 --- a/docs/modules/sync.rst +++ b/docs/modules/sync.rst @@ -1,5 +1,7 @@ -Sync (plexapi.sync) -------------------- +.. include:: ../global.rst + +Sync :modname:`plexapi.sync` +---------------------------- .. automodule:: plexapi.sync :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/utils.rst b/docs/modules/utils.rst index 09f10288..dedb29ff 100644 --- a/docs/modules/utils.rst +++ b/docs/modules/utils.rst @@ -1,5 +1,7 @@ -Utils (plexapi.utils) ---------------------- +.. include:: ../global.rst + +Utils :modname:`plexapi.utils` +------------------------------ .. automodule:: plexapi.utils :members: :show-inheritance: \ No newline at end of file diff --git a/docs/modules/video.rst b/docs/modules/video.rst index a687714b..1347b39e 100644 --- a/docs/modules/video.rst +++ b/docs/modules/video.rst @@ -1,5 +1,8 @@ -Video (plexapi.video) ------------------------ +.. include:: ../global.rst + +Video :modname:`plexapi.video` +------------------------------ .. automodule:: plexapi.video :members: - :show-inheritance: \ No newline at end of file + :show-inheritance: + diff --git a/docs/toc.rst b/docs/toc.rst index 6a5d85a5..121aca4c 100644 --- a/docs/toc.rst +++ b/docs/toc.rst @@ -23,6 +23,7 @@ modules/playlist modules/playqueue modules/server + modules/settings modules/sync modules/utils modules/video diff --git a/plexapi/notify.py b/plexapi/notify.py index f2ce8da5..ab31ad51 100644 --- a/plexapi/notify.py +++ b/plexapi/notify.py @@ -6,16 +6,20 @@ from plexapi.exceptions import Unsupported class PlexNotifier(threading.Thread): - """ Creates a websocket connection to the Plex Server to optionally recieve - notifications. These often include messages from Plex about media scans - as well as updates to currently running Transcode Sessions. + """ Creates a websocket connection to the Plex Server to optionally recieve notifications. These + often include messages from Plex about media scans as well as updates to currently running + Transcode Sessions. This class implements threading.Thread, therfore to start monitoring + notifications you must call .start() on the object once it's created. When calling + `PlexServer.startNotifier()`, the thread will be started for you. + + In order to use this feature, you must have websocket-client installed in your Python path. + This can be installed vis pip `pip install websocket-client`. Parameters: server (:class:`~plexapi.server.PlexServer`): PlexServer this notifier is connected to. - callback (func): Callback function to call on recieved messages. - - NOTE: You need websocket-client installed in order to use this feature. - >> pip install websocket-client + callback (func): Callback function to call on recieved messages. The callback function + will be sent a single argument 'data' which will contain a dictionary of data + recieved from the server. :samp:`def my_callback(data): ...` """ key = '/:/websockets/notifications' @@ -26,9 +30,6 @@ class PlexNotifier(threading.Thread): super(PlexNotifier, self).__init__() def run(self): - """ Starts the PlexNotifier thread. This function should not be called - directly, instead use :func:`~plexapi.server.PlexServer.startNotifier`. - """ # try importing websocket-client package try: import websocket @@ -43,7 +44,10 @@ class PlexNotifier(threading.Thread): self._ws.run_forever() def stop(self): - """ Stop the PlexNotifier thread. """ + """ Stop the PlexNotifier thread. Once the notifier is stopped, it cannot be diractly + started again. You must call :func:`plexapi.server.PlexServer.startNotifier()` + from a PlexServer instance. + """ log.info('Stopping PlexNotifier.') self._ws.close() diff --git a/plexapi/settings.py b/plexapi/settings.py index 921fe0d3..a012cc94 100644 --- a/plexapi/settings.py +++ b/plexapi/settings.py @@ -11,7 +11,6 @@ class Settings(PlexObject): Attributes: key (str): '/:/prefs' - __AUTODOC_SETTINGS__ """ key = '/:/prefs' @@ -30,6 +29,7 @@ class Settings(PlexObject): self.__dict__[attr] = value def _loadData(self, data): + """ Load attribute values from Plex XML response. """ self._data = data for elem in data: id = utils.lowerFirst(elem.attrib['id']) @@ -39,27 +39,37 @@ class Settings(PlexObject): self._settings[id] = Setting(self._server, elem, self._initpath) def all(self): - """ Returns a list of all :any:`~Setting` objects available. """ - return list(self._settings.values()) + """ Returns a list of all :class:`~plexapi.settings.Setting` objects available. """ + return list(v for id, v in sorted(self._settings.items())) def get(self, id): - """ Return the setting with the specified id. """ + """ Return the :class:`~plexapi.settings.Setting` object with the specified id. """ id = utils.lowerFirst(id) if id in self._settings: return self._settings[id] raise NotFound('Invalid setting id: %s' % id) def groups(self): - """ Returns a dict of lists for all :any:`~Setting` objects grouped by setting group. """ + """ Returns a dict of lists for all :class:`~plexapi.settings.Setting` + objects grouped by setting group. + """ groups = defaultdict(list) for setting in self.all(): groups[setting.group].append(setting) return dict(groups) def group(self, group): + """ Return a list of all :class:`~plexapi.settings.Setting` objects in the specified group. + + Parameters: + group (str): Group to return all settings. + """ return self.groups().get(group, []) def save(self): + """ Save any outstanding settnig changes to the :class:`~plexapi.server.PlexServer`. This + performs a full reload() of Settings after complete. + """ params = {} for setting in self.all(): if setting._setValue: @@ -74,6 +84,20 @@ class Settings(PlexObject): class Setting(PlexObject): + """ Represents a single Plex setting. + + Attributes: + id (str): Setting id (or name). + label (str): Short description of what this setting is. + summary (str): Long description of what this setting is. + type (str): Setting type (text, int, double, bool). + default (str): Default value for this setting. + value (str,bool,int,float): Current value for this setting. + hidden (bool): True if this is a hidden setting. + advanced (bool): True if this is an advanced setting. + group (str): Group name this setting is categorized as. + enumValues (list,dict): List or dictionary of valis values for this setting. + """ _bool_cast = lambda x: True if x == 'true' else False _bool_str = lambda x: str(x).lower() TYPES = { @@ -84,28 +108,38 @@ class Setting(PlexObject): } def _loadData(self, data): + """ Load attribute values from Plex XML response. """ self._setValue = None self.id = data.attrib.get('id') self.label = data.attrib.get('label') - self.default = data.attrib.get('default') self.summary = data.attrib.get('summary') self.type = data.attrib.get('type') - self.value = data.attrib.get('value') + self.default = self._cast(data.attrib.get('default')) + self.value = self._cast(data.attrib.get('value')) self.hidden = utils.cast(bool, data.attrib.get('hidden')) self.advanced = utils.cast(bool, data.attrib.get('advanced')) self.group = data.attrib.get('group') self.enumValues = self._getEnumValues(data) + def _cast(self, value): + """ Cast the specifief value to the type of this setting. """ + if self.type != 'text': + value = utils.cast(self.TYPES.get(self.type)['cast'], value) + return value + def _getEnumValues(self, data): + """ Returns a list of dictionary of valis value for this setting. """ enumstr = data.attrib.get('enumValues') if not enumstr: return None if ':' in enumstr: - cast = self.TYPES[self.type]['cast'] - return {cast(k): v for k, v in [kv.split(':') for kv in enumstr.split('|')]} + return {self._cast(k): v for k, v in [kv.split(':') for kv in enumstr.split('|')]} return enumstr.split('|') def set(self, value): + """ Set a new value for this setitng. NOTE: You must call plex.settings.save() for before + any changes to setting values are persisted to the :class:`~plexapi.server.PlexServer`. + """ # check a few things up front if not isinstance(value, self.TYPES[self.type]['type']): badtype = type(value).__name__ diff --git a/tools/listsettings.py b/tools/listsettings.py new file mode 100644 index 00000000..91a9d017 --- /dev/null +++ b/tools/listsettings.py @@ -0,0 +1,23 @@ +# -*- coding: utf-8 -*- +from plexapi.server import PlexServer + + +def list_settings(): + plex = PlexServer() + groups = sorted(plex.settings.groups().items()) + for group, settings in groups: + title = group.title() + print('%s Settings' % (title or 'Misc')) + print('---------------------------') + for s in settings: + label = '%s. ' % s.label if s.label else '' + summary = '%s ' % s.summary if s.summary else '' + enums = '; available: %s' % s._data.attrib['enumValues'] if 'enumValues' in s._data.attrib else '' + default = '(default: %s%s)' % (s.default, enums) if s.default else '' + desc = '%s%s%s' % (label, summary, default) + print('* **%s** (%s): %s' % (s.id, s.type, desc)) + print('') + + +if __name__ == '__main__': + list_settings()