v2.1.1-beta

Adding the week number parameter

.gitignore

@@ -15,7 +15,9 @@
 release.lock
 version.lock
 logs/*
+backups/*
 cache/*
+newsletters/*
 *.mmdb
 
 # HTTPS Cert/Key #

CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## v2.1.1-beta (2018-04-11)
+
+* Monitoring:
+  * Fix: Live TV transcoding showing incorrectly as direct play.
+* Newsletters:
+  * New: Added week number as parameter. (Thanks @samip5)
+  * Fix: Fallback to cover art on the newsletter cards.
+  * Change: Option to set newsletter time frame by calendar days or hours.
+* Notifications:
+  * New: Added week number as parameter. (Thanks @samip5)
+* Other:
+  * New: Added plexapi library for custom scripts.
+
+
+## v2.1.0-beta (2018-04-07)
+
+* Newsletters:
+  * New: A completely new scheduled newsletter system.
+    * Beautiful HTML formatted newsletter for recently added movies, TV shows, or music.
+    * Send newsletters on a daily, weekly, or monthly schedule to your users.
+    * Customize the number of days of recently added content and the libraries to include on the newsletter.
+    * Add a custom message to be included on the newsletter.
+    * Option to either send an HTML formatted email, or a link to a self-hosted newsletter on your own domain to any notification agent.
+* Notifications:
+  * New: Ability to use self-hosted images on your own domain instead of using Imgur.
+
+
+## v2.0.28 (2018-04-02)
+
+* Monitoring:
+  * Fix: Homepage activity header text.
+
+
+## v2.0.27 (2018-04-02)
+
+* Monitoring:
+  * Change: Move activity refresh interval setting to the settings page.
+
+
+## v2.0.26-beta (2018-03-30)
+
+* Monitoring:
+  * New: Setting to change the refresh interval on the homepage.
+  * Fix: Identify extras correctly on the activity cards.
+* Notifications:
+  * Change: Send Telegram image and text separately if the caption is longer than 200 characters.
+* UI:
+  * Fix: Error when clicking on synced playlist links.
+
+
+## v2.0.25 (2018-03-22)
+
+* Monitoring:
+  * Fix: Websocket not reconnecting causing activity monitoring and notifications to not work.
+  * Fix: Error checking for synced streams without Plex Pass.
+
+
 ## v2.0.24 (2018-03-18)
 
 * Monitoring:

data/interfaces/default/configuration_table.html

@@ -49,6 +49,10 @@ DOCUMENTATION :: END
             <td>Cache Directory:</td>
             <td>${plexpy.CONFIG.CACHE_DIR}</td>
         </tr>
+        <tr>
+            <td>Newsletter Directory:</td>
+            <td>${plexpy.CONFIG.NEWSLETTER_DIR}</td>
+        </tr>
         <tr>
             <td>GeoLite2 Database:</td>
             % if plexpy.CONFIG.GEOIP_DB:

data/interfaces/default/css/tautulli.css

@@ -125,8 +125,10 @@ div.form-control .selectize-input {
     padding-bottom: 2px !important;
     transition: background-color .3s;
 }
-.react-selectize.root-node .simple-value span {
+.react-selectize.root-node .simple-value span,
+.selectize-control.multi .selectize-input > div {
     padding-bottom: 2px !important;
+    padding-left: 5px !important;
 }
 .react-selectize.root-node .react-selectize-control .react-selectize-search-field-and-selected-values .value-wrapper:not(:first-child):before {
     content: "or";
@@ -134,9 +136,6 @@ div.form-control .selectize-input {
     text-transform: uppercase;
     font-size: 10px;
 }
-.react-selectize.root-node .react-selectize-control .react-selectize-search-field-and-selected-values.negative-operator .value-wrapper:not(:first-child):before {
-    content: "and" !important;
-}
 .react-selectize.root-node .react-selectize-control .react-selectize-search-field-and-selected-values .resizable-input {
     padding-top: 3px !important;
     padding-bottom: 3px !important;
@@ -467,6 +466,18 @@ fieldset[disabled] .btn-bright.active {
 .btn-group select {
     margin-top: 0;
 }
+.input-group-addon-form {
+    display: inline-block;
+    line-height: 1.42857143;
+    color: #e5e5e5;
+    background-color: #3B3B3B;
+    border: 1px solid transparent;
+    border-top-right-radius: 3px !important;
+    border-bottom-right-radius: 3px !important;
+    height: 32px;
+    width: 100%;
+    margin-top: 5px;
+}
 #user-selection label {
     margin-bottom: 0;
 }
@@ -745,7 +756,10 @@ a .users-poster-face:hover {
     transition: all .2s ease-in-out;
     overflow: hidden;
 }
-.dashboard-activity-background-overlay {
+.dashboard-activity-background {
+    background-color: #282828;
+    background-position: center;
+    background-size: cover;
     display: -webkit-flex;
     display: flex;
     -webkit-flex-wrap: nowrap;
@@ -754,30 +768,13 @@ a .users-poster-face:hover {
     width: 100%;
     padding: 5px;
     overflow: hidden;
-    -webkit-box-shadow: 0 0 4px rgba(0,0,0,.3), inset 0 0 0 1px rgba(255,255,255,.1);
-    -moz-box-shadow: 0 0 4px rgba(0,0,0,.3),inset 0 0 0 1px rgba(255,255,255,.1);
-    box-shadow: 0 0 4px rgba(0,0,0,.3), inset 0 0 0 1px rgba(255,255,255,.1);
-}
-.dashboard-activity-background {
-    background-color: #282828;
-    background-position: center;
-    background-size: cover;
-    height: 235px;
-    width: 100%;
-    position: absolute;
-    top: 0;
-    right: 0;
-    bottom: 0;
-    left: 0;
-    opacity: 0.40;
-    -webkit-filter: blur(3px);
-    -moz-filter: blur(3px);
-    filter: blur(3px);
     -webkit-transition: background 1s linear;
     transition: background 1s linear;
     -webkit-backface-visibility: hidden;
     backface-visibility: hidden;
-    z-index: -1;
+    -webkit-box-shadow: 0 0 4px rgba(0,0,0,.3), inset 0 0 0 1px rgba(255,255,255,.1);
+    -moz-box-shadow: 0 0 4px rgba(0,0,0,.3),inset 0 0 0 1px rgba(255,255,255,.1);
+    box-shadow: 0 0 4px rgba(0,0,0,.3), inset 0 0 0 1px rgba(255,255,255,.1);
 }
 .dashboard-activity-poster-container {
     background-color: #282828;
@@ -808,14 +805,14 @@ a .users-poster-face:hover {
     background-size: cover;
     height: 225px;
     width: 150px;
-    -webkit-transition: background .2s ease-in-out;
-    transition: background .2s ease-in-out;
-    -webkit-backface-visibility: hidden;
-    backface-visibility: hidden;
     opacity: 0.60;
     -webkit-filter: blur(3px);
     -moz-filter: blur(3px);
     filter: blur(3px);
+    -webkit-transition: background .2s ease-in-out;
+    transition: background .2s ease-in-out;
+    -webkit-backface-visibility: hidden;
+    backface-visibility: hidden;
     z-index: 2;
 }
 .dashboard-activity-cover {
@@ -1162,7 +1159,10 @@ a .dashboard-activity-metadata-user-thumb:hover {
     transition: all .2s ease-in-out;
     overflow: hidden;
 }
-.dashboard-stats-background-overlay {
+.dashboard-stats-background {
+    background-color: #282828;
+    background-position: center;
+    background-size: cover;
     display: -webkit-flex;
     display: flex;
     -webkit-flex-wrap: nowrap;
@@ -1171,30 +1171,13 @@ a .dashboard-activity-metadata-user-thumb:hover {
     width: 100%;
     padding: 5px;
     overflow: hidden;
-    -webkit-box-shadow: 0 0 4px rgba(0,0,0,.3), inset 0 0 0 1px rgba(255,255,255,.1);
-    -moz-box-shadow: 0 0 4px rgba(0,0,0,.3),inset 0 0 0 1px rgba(255,255,255,.1);
-    box-shadow: 0 0 4px rgba(0,0,0,.3), inset 0 0 0 1px rgba(255,255,255,.1);
-}
-.dashboard-stats-background {
-    background-color: #282828;
-    background-position: center;
-    background-size: cover;
-    height: 160px;
-    width: 100%;
-    position: absolute;
-    top: 0;
-    right: 0;
-    bottom: 0;
-    left: 0;
-    opacity: 0.40;
-    -webkit-filter: blur(3px);
-    -moz-filter: blur(3px);
-    filter: blur(3px);
     -webkit-transition: background .2s ease-in-out;
     transition: background .2s ease-in-out;
     -webkit-backface-visibility: hidden;
     backface-visibility: hidden;
-    z-index: -1;
+    -webkit-box-shadow: 0 0 4px rgba(0,0,0,.3), inset 0 0 0 1px rgba(255,255,255,.1);
+    -moz-box-shadow: 0 0 4px rgba(0,0,0,.3),inset 0 0 0 1px rgba(255,255,255,.1);
+    box-shadow: 0 0 4px rgba(0,0,0,.3), inset 0 0 0 1px rgba(255,255,255,.1);
 }
 .dashboard-stats-background.flat {
     opacity: 1;
@@ -1214,17 +1197,6 @@ a .dashboard-activity-metadata-user-thumb:hover {
     z-index: 1;
 }
 .dashboard-stats-poster {
-    background-position: center;
-    background-size: cover;
-    height: 150px;
-    width: 100px;
-    -webkit-transition: background .2s ease-in-out;
-    transition: background .2s ease-in-out;
-    -webkit-backface-visibility: hidden;
-    backface-visibility: hidden;
-    z-index: 2;
-}
-.dashboard-stats-poster-blur {
     background-color: #282828;
     background-position: center;
     background-size: cover;
@@ -1234,10 +1206,6 @@ a .dashboard-activity-metadata-user-thumb:hover {
     transition: background .2s ease-in-out;
     -webkit-backface-visibility: hidden;
     backface-visibility: hidden;
-    opacity: 0.60;
-    -webkit-filter: blur(3px);
-    -moz-filter: blur(3px);
-    filter: blur(3px);
     z-index: 2;
 }
 .dashboard-stats-cover {
@@ -2160,6 +2128,12 @@ a:hover .item-children-poster {
     top: 5px;
     left: 12px;
 }
+.settings-warning {
+    color: #eb8600;
+}
+span.settings-warning {
+    padding-left: 10px;
+}
 #menu_link_show_advanced_settings.active {
   color: #fff;
   background-color: #cc7b19;
@@ -2973,6 +2947,9 @@ a .home-platforms-list-cover-face:hover
 .stacked-configs > li.new-notification-agent,
 .stacked-configs > li.notification-agent,
 .stacked-configs > li.add-notification-agent,
+.stacked-configs > li.new-newsletter-agent,
+.stacked-configs > li.newsletter-agent,
+.stacked-configs > li.add-newsletter-agent,
 .stacked-configs > li.mobile-device,
 .stacked-configs > li.add-mobile-device {
     cursor: pointer;
@@ -3657,38 +3634,71 @@ a:hover .overlay-refresh-image:hover {
 }
 #plexpy-notifiers-table .friendly_name,
 #notifier-config-modal span.notifier_id,
+#plexpy-newsletters-table .friendly_name,
+#newsletter-config-modal span.newsletter_id,
 #plexpy-mobile-devices-table .friendly_name,
 #mobile-device-config-modal span.notifier_id {
     color: #777;
 }
-#notifier-config-modal .nav-tabs {
+#notifier-config-modal .nav-tabs,
+#newsletter-config-modal .nav-tabs {
     margin-bottom: 10px;
     padding-left: 15px;
     border-bottom: 1px solid #444;
 }
-#notifier-config-modal .nav-tabs > li {
+#notifier-config-modal .nav-tabs > li,
+#newsletter-config-modal .nav-tabs > li {
     margin: 0 0 -1px 0;
 }
-#notifier-config-modal .nav-tabs > li > a {
+#notifier-config-modal .nav-tabs > li > a,
+#newsletter-config-modal .nav-tabs > li > a {
     padding: 5px 10px;
     color: #737373;
 }
-#notifier-config-modal .nav-tabs > li > a:hover {
+#notifier-config-modal .nav-tabs > li > a:hover,
+#newsletter-config-modal .nav-tabs > li > a:hover {
     border-color: #444;
     background: #222;
 }
 #notifier-config-modal .nav-tabs > li.active > a,
 #notifier-config-modal .nav-tabs > li.active > a:hover,
-#notifier-config-modal .nav-tabs > li.active > a:focus {
+#notifier-config-modal .nav-tabs > li.active > a:focus,
+#newsletter-config-modal .nav-tabs > li.active > a,
+#newsletter-config-modal .nav-tabs > li.active > a:hover,
+#newsletter-config-modal .nav-tabs > li.active > a:focus {
     color: #fff;
     background: #222;
 }
 #notifier-config-modal .nav-tabs > li.active > a,
 #notifier-config-modal .nav-tabs > li.active > a:hover,
-#notifier-config-modal .nav-tabs > li.active > a:focus {
+#notifier-config-modal .nav-tabs > li.active > a:focus,
+#newsletter-config-modal .nav-tabs > li.active > a,
+#newsletter-config-modal .nav-tabs > li.active > a:hover,
+#newsletter-config-modal .nav-tabs > li.active > a:focus {
     border: 1px solid #444;
     border-bottom-color: transparent;
 }
+#newsletter-config-modal #custom_cron {
+    display: inline-block;
+    width: initial;
+    height: 32px;
+    margin-right: 5px;
+    margin-top: 4px;
+}
+#newsletter-config-modal #cron-widget {
+    display: inline-block;
+    margin-top: 1px;
+}
+#newsletter-config-modal #cron-widget select.cron-select {
+    width: initial;
+    display: inline;
+    height: 32px;
+    margin-top: 4px;
+}
+#newsletter-config-modal #cron-widget select.cron-select[name=cron-period] option[value=minute],
+#newsletter-config-modal #cron-widget select.cron-select[name=cron-period] option[value=hour] {
+    display: none !important;
+}
 .git-group input.form-control {
     width: 50%;
 }
@@ -3841,6 +3851,90 @@ a:hover .overlay-refresh-image:hover {
     background-color: #107c10;
     background-image: url(../images/platforms/xbox.svg);
 }
+.platform-android-rgba {
+    background-color: rgba(164, 202, 57, 0.40);
+}
+.platform-atv-rgba {
+    background-color: rgba(133, 132, 135, 0.40);
+}
+.platform-chrome-rgba {
+    background-color: rgba(237, 94, 80, 0.40);
+}
+.platform-chromecast-rgba {
+    background-color: rgba(16, 164, 232, 0.40);
+}
+.platform-default-rgba {
+    background-color: rgba(229, 160, 13, 0.40);
+}
+.platform-dlna-rgba {
+    background-color: rgba(12, 177, 75, 0.40);
+}
+.platform-firefox-rgba {
+    background-color: rgba(230, 120, 23, 0.40);
+}
+.platform-gtv-rgba {
+    background-color: rgba(0, 139, 207, 0.40);
+}
+.platform-ie-rgba {
+    background-color: rgba(0, 89, 158, 0.40);
+}
+.platform-ios-rgba {
+    background-color: rgba(133, 132, 135, 0.40);
+}
+.platform-kodi-rgba {
+    background-color: rgba(49, 175, 225, 0.40);
+}
+.platform-linux-rgba {
+    background-color: rgba(23, 147, 208, 0.40);
+}
+.platform-macos-rgba {
+    background-color: rgba(133, 132, 135, 0.40);
+}
+.platform-msedge-rgba {
+    background-color: rgba(0, 120, 215, 0.40);
+}
+.platform-opera-rgba {
+    background-color: rgba(255, 27, 45, 0.40);
+}
+.platform-playstation-rgba {
+    background-color: rgba(3, 77, 162, 0.40);
+}
+.platform-plex-rgba {
+    background-color: rgba(229, 160, 13, 0.40);
+}
+.platform-plexamp-rgba {
+    background-color: rgba(229, 160, 13, 0.40);
+}
+.platform-roku-rgba {
+    background-color: rgba(109, 60, 151, 0.40);
+}
+.platform-safari-rgba {
+    background-color: rgba(0, 169, 236, 0.40);
+}
+.platform-samsung-rgba {
+    background-color: rgba(3, 78, 162, 0.40);
+}
+.platform-synclounge-rgba {
+    background-color: rgba(21, 25, 36, 0.40);
+}
+.platform-tivo-rgba {
+    background-color: rgba(0, 167, 225, 0.40);
+}
+.platform-wiiu-rgba {
+    background-color: rgba(3, 169, 244, 0.40);
+}
+.platform-windows-rgba {
+    background-color: rgba(47, 192, 245, 0.40);
+}
+.platform-wp-rgba {
+    background-color: rgba(104, 33, 122, 0.40);
+}
+.platform-xbmc-rgba {
+    background-color: rgba(59, 72, 114, 0.40);
+}
+.platform-xbox-rgba {
+    background-color: rgba(16, 124, 16, 0.40);
+}
 .library-movie {
     background-image: url(../images/libraries/movie.svg);
 }
@@ -3952,3 +4046,50 @@ a:hover .overlay-refresh-image:hover {
     -webkit-appearance: none;
     margin: 0;
 }
+.newsletter-time_frame .input-group-addon {
+    height: 32px;
+    width: 52px;
+    margin-top: 5px;
+    line-height: 1.42857143;
+}
+.newsletter-time_frame input.form-control {
+    width: calc(50% - 37px);
+}
+.newsletter-time_frame select.form-control  {
+    width: calc(50% - 15px);
+    height: 32px;
+}
+.newsletter-loader-container {
+    font-family: 'Open Sans', Arial, sans-serif;
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    left: 0;
+}
+.newsletter-loader-message {
+    color: #282A2D;
+    text-align: center;
+    position: absolute;
+    left: 50%;
+    top: 25%;
+    transform: translate(-50%, -50%);
+}
+.newsletter-loader {
+    border: 5px solid #ccc;
+    -webkit-animation: spin 1s linear infinite;
+    animation: spin 1s linear infinite;
+    border-top: 5px solid #282A2D;
+    border-radius: 50%;
+    width: 50px;
+    height: 50px;
+    position: relative;
+    left: calc(50% - 25px);
+}
+@keyframes spin {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+}
+a[data-tab-destination] {
+    cursor: pointer;
+}

data/interfaces/default/current_activity_instance.html

@@ -64,7 +64,7 @@ DOCUMENTATION :: END
     from collections import defaultdict
     from urllib import quote
     from plexpy import helpers
-    from plexpy.common import VIDEO_RESOLUTION_OVERRIDES, AUDIO_CODEC_OVERRIDES
+    from plexpy.common import VIDEO_RESOLUTION_OVERRIDES, AUDIO_CODEC_OVERRIDES, EXTRA_TYPES
     import plexpy
 %>
 <%
@@ -79,20 +79,19 @@ DOCUMENTATION :: END
 <div class="dashboard-activity-instance" id="activity-instance-${sk}" data-key="${sk}" data-id="${data['session_id']}"
      data-rating_key="${data['rating_key']}" data-parent_rating_key="${data['parent_rating_key']}" data-grandparent_rating_key="${data['grandparent_rating_key']}">
     <div class="dashboard-activity-container">
-        <div class="dashboard-activity-background-overlay">
-            % if data['channel_stream'] == 0:
-            <div id="background-${sk}" class="dashboard-activity-background" style="background-image: url(pms_image_proxy?img=${data['art']}&width=500&height=280&fallback=art&refresh=true);"></div>
-            % else:
-                % if (data['art'] and data['art'].startswith('http')) or (data['thumb'] and data['thumb'].startswith('http')):
-                <div id="background-${sk}" class="dashboard-activity-background" style="background-image: url(${data['art']});"></div>
-                % else:
-                <!--Hacky solution to escape the image url until I come up with something better-->
-                <div id="background-${sk}" class="dashboard-activity-background" style="background-image: url(pms_image_proxy?img=${quote(data['art'] or data['thumb'])}&width=500&height=280&fallback=art&refresh=true&clip=true);"></div>
-                % endif
-            % endif
+        <%
+            if data['channel_stream'] == 0:
+                background_url = 'pms_image_proxy?img=' + data['art'] + '&width=500&height=280&opacity=40&background=282828&blur=3&fallback=art&refresh=true'
+            else:
+                if (data['art'] and data['art'].startswith('http')) or (data['thumb'] and data['thumb'].startswith('http')):
+                    background_url = data['art']
+                else:
+                    background_url = 'pms_image_proxy?img=' + quote(data['art'] or data['thumb']) + '&width=500&height=280&fallback=art&refresh=true&clip=true'
+        %>
+        <div id="background-${sk}" class="dashboard-activity-background" style="background-image: url(${background_url});">
             <div class="dashboard-activity-poster-container hidden-xs">
                 % if data['media_type'] == 'track':
-                <div id="poster-${sk}-bg" class="dashboard-activity-poster-blur" style="background-image: url(pms_image_proxy?img=${data['parent_thumb']}&width=300&height=300&fallback=cover&refresh=true);"></div>
+                <div id="poster-${sk}-bg" class="dashboard-activity-poster" style="background-image: url(pms_image_proxy?img=${data['parent_thumb']}&width=300&height=300&opacity=60&background=282828&blur=3&fallback=cover&refresh=true);"></div>
                 % endif
                 % if data['channel_stream'] == 0:
                     % if data['media_type'] == 'movie':
@@ -108,7 +107,11 @@ DOCUMENTATION :: END
                         <div id="poster-${sk}" class="dashboard-activity-cover" style="background-image: url(pms_image_proxy?img=${data['parent_thumb']}&width=300&height=300&fallback=cover&refresh=true);"></div>
                     </a>
                     % elif data['media_type'] in ('photo', 'clip'):
-                    <div id="poster-${sk}" class="dashboard-activity-poster" style="background-image: url(pms_image_proxy?img=${data['parent_thumb']}&width=300&height=450&fallback=poster&refresh=true);"></div>
+                        % if data['extra_type']:
+                        <div id="poster-${sk}" class="dashboard-activity-poster" style="background-image: url(pms_image_proxy?img=${data['art'].replace('/art', '/thumb') or data['thumb']}&width=300&height=450&fallback=poster&refresh=true);"></div>
+                        % else:
+                        <div id="poster-${sk}" class="dashboard-activity-poster" style="background-image: url(pms_image_proxy?img=${data['parent_thumb'] or data['thumb']}&width=300&height=450&fallback=poster&refresh=true);"></div>
+                        % endif
                     % else:
                     <div id="poster-${sk}" class="dashboard-activity-poster" style="background-image: url(images/art.png);"></div>
                     % endif
@@ -117,7 +120,7 @@ DOCUMENTATION :: END
                     <div id="poster-${sk}" class="dashboard-activity-poster-blur" style="background-image: url(${data['channel_icon']});"></div>
                     <div id="poster-${sk}" class="dashboard-activity-cover" style="background-image: url(${data['channel_icon']});"></div>
                     % else:
-                    <div id="poster-${sk}" class="dashboard-activity-poster-blur" style="background-image: url(pms_image_proxy?img=${data['channel_icon']}&width=300&height=300&fallback=cover&refresh=true);"></div>
+                    <div id="poster-${sk}" class="dashboard-activity-poster" style="background-image: url(pms_image_proxy?img=${data['channel_icon']}&width=300&height=300&opacity=60&background=282828&blur=3&fallback=cover&refresh=true);"></div>
                     <div id="poster-${sk}" class="dashboard-activity-cover" style="background-image: url(pms_image_proxy?img=${data['channel_icon']}&width=300&height=300&fallback=cover&refresh=true);"></div>
                     % endif
                 % endif
@@ -301,14 +304,13 @@ DOCUMENTATION :: END
                             <li class="dashboard-activity-info-item">
                                 <div class="sub-heading">Bandwidth</div>
                                 <div class="sub-value time-right">
-                                    % if data['media_type'] != 'photo' and helpers.cast_to_int(data['bandwidth']):
+                                    % if data['media_type'] != 'photo' and data['bandwidth'] != 'Unknown':
                                     <%
                                         bw = helpers.cast_to_int(data['bandwidth'])
-                                        if bw != "Unknown":
-                                            if bw > 1000:
-                                                bw = str(round(bw / 1000.0, 1)) + ' Mbps'
-                                            else:
-                                                bw = str(bw) + ' kbps'
+                                        if bw > 1000:
+                                            bw = str(round(bw / 1000.0, 1)) + ' Mbps'
+                                        else:
+                                            bw = str(bw) + ' kbps'
                                     %>
                                     <span id="stream-bandwidth-${sk}">${bw}</span>
                                     <span id="streaming-brain-${sk}" data-toggle="tooltip" title="Streaming Brain Estimate (Required Bandwidth)"><i class="fa fa-info-circle"></i></span>
@@ -440,7 +442,12 @@ DOCUMENTATION :: END
                     % elif data['media_type'] == 'photo':
                     <span title="${data['title']}" class="sub-heading">${data['title']}</span>
                     % else:
-                    <span title="${data['year']}" class="sub-heading">${data['year']}</span>
+                        % if data['extra_type']:
+                        <% extra_type = EXTRA_TYPES.get(data['extra_type'], data['sub_type'].capitalize()) %>
+                        <span title="${data['year']} (${extra_type})" class="sub-heading">${data['year']} (${extra_type})</span>
+                        % else:
+                        <span title="${data['year']}" class="sub-heading">${data['year']}</span>
+                        % endif
                     % endif
                 % elif data['channel_title']:
                 <span title="${data['channel_title']}" class="sub-heading">${data['channel_title']}</span>

data/interfaces/default/history.html

@@ -113,7 +113,7 @@
         // Load user ids and names (for the selector)
         $.ajax({
             url: 'get_user_names',
-            type: 'get',
+            type: 'GET',
             dataType: 'json',
             success: function (data) {
                 var select = $('#history-user');
@@ -130,6 +130,7 @@
         function loadHistoryTable(media_type, selected_user_id) {
             history_table_options.ajax = {
                 url: 'get_history',
+                type: 'POST',
                 data: function (d) {
                     return {
                         json_data: JSON.stringify(d),

data/interfaces/default/home_stats.html

@@ -71,22 +71,21 @@ DOCUMENTATION :: END
 %>
 <div class="dashboard-stats-instance" id="stats-instance-${stat_id}" data-stat_id="${stat_id}">
     <div class="dashboard-stats-container">
-        <div class="dashboard-stats-background-overlay">
-            % if stat_id in ('top_movies', 'popular_movies', 'top_tv', 'popular_tv', 'top_music', 'popular_music', 'last_watched'):
-            % if row0['art']:
-            <div id="stats-background-${stat_id}" class="dashboard-stats-background" style="background-image: url(pms_image_proxy?img=${row0['art']}&width=500&height=280&fallback=art);"></div>
-            % else:
-            <div id="stats-background-${stat_id}" class="dashboard-stats-background" style="background-image: url(images/art.png);"></div>
-            % endif
-            % elif stat_id == 'top_platforms':
-            <div id="stats-background-${stat_id}" class="dashboard-stats-background platform-${row0['platform_name']} no-image"></div>
-            % else:
-            <div id="stats-background-${stat_id}" class="dashboard-stats-background flat"></div>
-            % endif
+        % if stat_id in ('top_movies', 'popular_movies', 'top_tv', 'popular_tv', 'top_music', 'popular_music', 'last_watched'):
+        % if row0['art']:
+        <div id="stats-background-${stat_id}" class="dashboard-stats-background" style="background-image: url(pms_image_proxy?img=${row0['art']}&width=500&height=280&opacity=40&background=282828&blur=3&fallback=art);">
+        % else:
+        <div id="stats-background-${stat_id}" class="dashboard-stats-background" style="background-image: url(images/art.png);">
+        % endif
+        % elif stat_id == 'top_platforms':
+        <div id="stats-background-${stat_id}" class="dashboard-stats-background platform-${row0['platform_name']}-rgba no-image">
+        % else:
+        <div id="stats-background-${stat_id}" class="dashboard-stats-background flat">
+        % endif
             % if stat_id in ('top_movies', 'popular_movies', 'top_tv', 'popular_tv', 'top_music', 'popular_music', 'last_watched'):
             <div class="dashboard-stats-poster-container hidden-xs">
                 % if stat_id in ('top_music', 'popular_music'):
-                <div id="stats-thumb-${stat_id}-bg" class="dashboard-stats-poster-blur" style="background-image: url(pms_image_proxy?img=${row0['thumb']}&width=300&height=300&fallback=cover);"></div>
+                <div id="stats-thumb-${stat_id}-bg" class="dashboard-stats-poster" style="background-image: url(pms_image_proxy?img=${row0['thumb']}&width=300&height=300&opacity=60&background=282828&blur=3&fallback=cover);"></div>
                 % endif
                 <% height, type = ('300', 'cover') if stat_id in ('top_music', 'popular_music') else ('450', 'poster') %>
                 <% href = 'info?rating_key={}'.format(row0['rating_key']) if row0['rating_key'] else '#' %>
@@ -200,7 +199,7 @@ DOCUMENTATION :: END
             }).addClass('platform-' + $(elem).data('platform'));
             $('#stats-background-' + stat_id).removeClass(function (index, className) {
                 return (className.match (/(^|\s)platform-\S+/g) || []).join(' ');
-            }).addClass('platform-' + $(elem).data('platform'));
+            }).addClass('platform-' + $(elem).data('platform') + '-rgba');
         } else {
             if (rating_key) {
                 href = 'info?rating_key=' + rating_key;
@@ -209,13 +208,13 @@ DOCUMENTATION :: END
             }
             $('#stats-thumb-url-' + stat_id).attr('href', href).prop('title', $(elem).data('title'));
             if (art) {
-                $('#stats-background-' + stat_id).css('background-image', 'url(pms_image_proxy?img=' + art + '&width=500&height=280&fallback=art)');
+                $('#stats-background-' + stat_id).css('background-image', 'url(pms_image_proxy?img=' + art + '&width=500&height=280&opacity=40&background=282828&blur=3&fallback=art)');
             } else {
                 $('#stats-background-' + stat_id).css('background-image', 'url(images/art.png)');
             }
             if (thumb) {
                 $('#stats-thumb-' + stat_id).css('background-image', 'url(pms_image_proxy?img=' + thumb + '&width=300&height=' + height + '&fallback=' + fallback + ')');
-                $('#stats-thumb-' + stat_id + '-bg').css('background-image', 'url(pms_image_proxy?img=' + thumb + '&width=300&height=' + height + '&fallback=' + fallback + ')');
+                $('#stats-thumb-' + stat_id + '-bg').css('background-image', 'url(pms_image_proxy?img=' + thumb + '&width=300&height=' + height + '&opacity=60&background=282828&blur=3&fallback=' + fallback + ')');
             } else {
                 $('#stats-thumb-' + stat_id).css('background-image', 'url(images/' + fallback + '.png)');
                 $('#stats-thumb-' + stat_id + '-bg').css('background-image', 'url(images/' + fallback + '.png)');

data/interfaces/default/index.html

@@ -123,7 +123,7 @@
                         </label>
                     </div>
                     <div class="input-group pull-left" style="width: 1px;" id="recently-added-count-selection">
-                        <input type="number" class="form-control number-input" name="recently-added-count" id="recently-added-count" value="${config['home_stats_recently_added_count']}" min="1" max="100" data-default="50" data-toggle="tooltip" title="Min: 1 item<br>Max: 100 items" />
+                        <input type="number" class="form-control number-input" name="recently-added-count" id="recently-added-count" value="${config['home_stats_recently_added_count']}" min="1" max="50" data-default="50" data-toggle="tooltip" title="Min: 1 item<br>Max: 50 items" />
                         <span class="input-group-addon btn-dark inactive">items</span>
                     </div>
                 </div>
@@ -375,7 +375,7 @@
                         if (s.media_type === 'track') {
                             // Update if artist changed
                             if (s.grandparent_rating_key !== instance.data('grandparent_rating_key')) {
-                                $('#background-' + key).css('background-image', 'url(pms_image_proxy?img=' + s.art + '&width=500&height=280&fallback=art&refresh=true)');
+                                $('#background-' + key).css('background-image', 'url(pms_image_proxy?img=' + s.art + '&width=500&height=280&opacity=40&background=282828&blur=3&fallback=art&refresh=true)');
                                 $('#metadata-grandparent_title-' + key)
                                     .attr('href', 'info?rating_key=' + s.grandparent_rating_key)
                                     .attr('title', s.grandparent_title)
@@ -384,7 +384,7 @@
                             // Update cover if album changed
                             if (s.parent_rating_key !== instance.data('parent_rating_key')) {
                                 $('#poster-' + key).css('background-image', 'url(pms_image_proxy?img=' + s.parent_thumb + '&width=300&height=300&fallback=poster&refresh=true)');
-                                $('#poster-' + key + '-bg').css('background-image', 'url(pms_image_proxy?img=' + s.parent_thumb + '&width=300&height=300&fallback=poster&refresh=true)');
+                                $('#poster-' + key + '-bg').css('background-image', 'url(pms_image_proxy?img=' + s.parent_thumb + '&width=300&height=300&opacity=60&background=282828&blur=3&fallback=poster&refresh=true)');
                                 $('#poster-url-' + key)
                                     .attr('href', 'info?rating_key=' + s.parent_rating_key)
                                     .attr('title', s.parent_title);
@@ -507,17 +507,15 @@
 
                         $('#location-' + key).html(s.location.toUpperCase());
 
-                        if (s.media_type !== 'photo' && parseInt(s.bandwidth)) {
-                            var bw = parseInt(s.bandwidth);
-                            if (bw !== "Unknown") {
-                                if (bw > 1000) {
-                                    bw = (bw / 1000).toFixed(1) + ' Mbps';
-                                } else {
-                                    bw = bw + ' kbps'
-                                }
+                        if (s.media_type !== 'photo' && s.bandwidth !== 'Unknown') {
+                            var bw = parseInt(s.bandwidth) || 0;
+                            if (bw > 1000) {
+                                bw = (bw / 1000).toFixed(1) + ' Mbps';
+                            } else {
+                                bw = bw + ' kbps'
                             }
                             $('#stream-bandwidth-' + key).html(bw);
-                        }
+                        };
 
                         // Update the stream progress times
                         $('#stream-eta-' + key).html(moment().add(parseInt(s.duration) - parseInt(s.view_offset), 'milliseconds').format(time_format));
@@ -589,7 +587,7 @@
         if (!(create_instances.length) && activity_ready) {
             getCurrentActivity();
         }
-    }, 2000);
+    }, ${config['home_refresh_interval'] * 1000});
 
     setInterval(function(){
         $('.progress_time_offset').each(function () {
@@ -604,7 +602,7 @@
             if ($(this).data('state') === 'playing' && $(this).data('view_offset') >= 0) {
                 var view_offset = parseInt($(this).data('view_offset'));
                 var stream_duration = parseInt($(this).data('stream_duration'));
-                var progress_percent = Math.min(Math.trunc(view_offset / stream_duration * 100), 100)
+                var progress_percent = Math.min(Math.trunc(view_offset / stream_duration * 100), 100);
                 $(this).width(progress_percent - 3 + '%').html(progress_percent + '%')
                     .attr('data-original-title', 'Stream Progress ' + progress_percent + '%')
                     .data('view_offset', Math.min(view_offset + 1000, stream_duration));

data/interfaces/default/info.html

@@ -547,7 +547,7 @@ DOCUMENTATION :: END
     function get_history() {
         history_table_options.ajax = {
             url: 'get_history',
-            type: 'post',
+            type: 'POST',
             data: function ( d ) {
                 return { 
                     json_data: JSON.stringify( d ),
@@ -563,7 +563,7 @@ DOCUMENTATION :: END
     function get_history() {
         history_table_options.ajax = {
             url: 'get_history',
-            type: 'post',
+            type: 'POST',
             data: function ( d ) {
                 return { 
                     json_data: JSON.stringify( d ),
@@ -579,7 +579,7 @@ DOCUMENTATION :: END
     function get_history() {
         history_table_options.ajax = {
             url: 'get_history',
-            type: 'post',
+            type: 'POST',
             data: function ( d ) {
                 return { 
                     json_data: JSON.stringify( d ),

data/interfaces/default/js/tables/newsletter_logs.js

@@ -0,0 +1,146 @@
+newsletter_log_table_options = {
+    "destroy": true,
+    "serverSide": true,
+    "processing": false,
+    "pagingType": "full_numbers",
+    "order": [ 0, 'desc'],
+    "pageLength": 50,
+    "stateSave": true,
+    "language": {
+                "search":"Search: ",
+                "lengthMenu": "Show _MENU_ lines per page",
+                "emptyTable": "No log information available",
+                "info" :"Showing _START_ to _END_ of _TOTAL_ lines",
+                "infoEmpty": "Showing 0 to 0 of 0 lines",
+                "infoFiltered": "(filtered from _MAX_ total lines)",
+                "loadingRecords": '<i class="fa fa-refresh fa-spin"></i> Loading items...</div>'
+    },
+    "autoWidth": false,
+    "scrollX": true,
+    "columnDefs": [
+        {
+            "targets": [0],
+            "data": "timestamp",
+            "createdCell": function (td, cellData, rowData, row, col) {
+                if (cellData !== '') {
+                    $(td).html(moment(cellData, "X").format('YYYY-MM-DD HH:mm:ss'));
+                }
+            },
+            "width": "10%",
+            "className": "no-wrap"
+        },
+        {
+            "targets": [1],
+            "data": "newsletter_id",
+            "createdCell": function (td, cellData, rowData, row, col) {
+                if (cellData !== '') {
+                    $(td).html(cellData);
+                }
+            },
+            "width": "5%",
+            "className": "no-wrap"
+        },
+        {
+            "targets": [2],
+            "data": "agent_name",
+            "createdCell": function (td, cellData, rowData, row, col) {
+                if (cellData !== '') {
+                    $(td).html(cellData);
+                }
+            },
+            "width": "5%",
+            "className": "no-wrap"
+        },
+        {
+            "targets": [3],
+            "data": "notify_action",
+            "createdCell": function (td, cellData, rowData, row, col) {
+                if (cellData !== '') {
+                    $(td).html(cellData);
+                }
+            },
+            "width": "5%",
+            "className": "no-wrap"
+        },
+        {
+            "targets": [4],
+            "data": "subject_text",
+            "createdCell": function (td, cellData, rowData, row, col) {
+                if (cellData !== '') {
+                    $(td).html(cellData);
+                }
+            },
+            "width": "23%"
+        },
+        {
+            "targets": [5],
+            "data": "body_text",
+            "createdCell": function (td, cellData, rowData, row, col) {
+                if (cellData !== '') {
+                    $(td).html(cellData);
+                }
+            },
+            "width": "35%"
+        },
+        {
+            "targets": [6],
+            "data": "start_date",
+            "createdCell": function (td, cellData, rowData, row, col) {
+                if (cellData !== '') {
+                    $(td).html(cellData);
+                }
+            },
+            "width": "5%"
+        },
+        {
+            "targets": [7],
+            "data": "end_date",
+            "createdCell": function (td, cellData, rowData, row, col) {
+                if (cellData !== '') {
+                    $(td).html(cellData);
+                }
+            },
+            "width": "5%"
+        },
+        {
+            "targets": [8],
+            "data": "uuid",
+            "createdCell": function (td, cellData, rowData, row, col) {
+                if (cellData !== '') {
+                    $(td).html('<a href="newsletter/' + rowData['uuid'] + '" target="_blank">' + cellData + '</a>');
+                }
+            },
+            "width": "5%"
+        },
+        {
+            "targets": [9],
+            "data": "success",
+            "createdCell": function (td, cellData, rowData, row, col) {
+                if (cellData === 1) {
+                    $(td).html('<span class="success-tooltip" data-toggle="tooltip" title="Newsletter Sent"><i class="fa fa-lg fa-fw fa-check"></i></span>');
+                } else {
+                    $(td).html('<span class="success-tooltip" data-toggle="tooltip" title="Newsletter Failed"><i class="fa fa-lg fa-fw fa-times"></i></span>');
+                }
+            },
+            "searchable": false,
+            "orderable": false,
+            "className": "no-wrap",
+            "width": "2%"
+        },
+    ],
+    "drawCallback": function (settings) {
+        // Jump to top of page
+        //$('html,body').scrollTop(0);
+        $('#ajaxMsg').fadeOut();
+
+        // Create the tooltips.
+        $('body').tooltip({
+            selector: '[data-toggle="tooltip"]',
+            container: 'body'
+        });
+    },
+    "preDrawCallback": function(settings) {
+        var msg = "<i class='fa fa-refresh fa-spin'></i>&nbspFetching rows...";
+        showMsg(msg, false, false, 0)
+    }
+};

data/interfaces/default/js/tables/notification_logs.js

@@ -86,7 +86,7 @@ notification_log_table_options = {
             "targets": [6],
             "data": "success",
             "createdCell": function (td, cellData, rowData, row, col) {
-                if (cellData == 1) {
+                if (cellData === 1) {
                     $(td).html('<span class="success-tooltip" data-toggle="tooltip" title="Notification Sent"><i class="fa fa-lg fa-fw fa-check"></i></span>');
                 } else {
                     $(td).html('<span class="success-tooltip" data-toggle="tooltip" title="Notification Failed"><i class="fa fa-lg fa-fw fa-times"></i></span>');
@@ -113,4 +113,4 @@ notification_log_table_options = {
         var msg = "<i class='fa fa-refresh fa-spin'></i>&nbspFetching rows...";
         showMsg(msg, false, false, 0)
     }
-}
+};

data/interfaces/default/js/tables/sync_table.js

@@ -37,7 +37,6 @@ sync_table_options = {
             "data": "state",
             "createdCell": function (td, cellData, rowData, row, col) {
                 if (cellData === 'pending') {
-                    $(td).addClass('currentlyWatching');
                     $(td).html('Pending...');
                 } else {
                     $(td).html(cellData.toProperCase());
@@ -66,7 +65,7 @@ sync_table_options = {
             "data": "sync_title",
             "createdCell": function (td, cellData, rowData, row, col) {
                 if (cellData !== '') {
-                    if (rowData['metadata_type'] !== '') {
+                    if (rowData['rating_key']) {
                         $(td).html('<a href="info?rating_key=' + rowData['rating_key'] + '">' + cellData + '</a>');
                     } else {
                         $(td).html(cellData);
@@ -74,7 +73,7 @@ sync_table_options = {
                 }
             },
             "className": "datatable-wrap"
-},
+        },
         {
             "targets": [4],
             "data": "metadata_type",
@@ -150,6 +149,11 @@ sync_table_options = {
     "preDrawCallback": function (settings) {
         var msg = "<i class='fa fa-refresh fa-spin'></i>&nbspFetching rows...";
         showMsg(msg, false, false, 0)
+    },
+    "rowCallback": function (row, rowData, rowIndex) {
+        if (rowData['state'] === 'pending') {
+            $(row).addClass('current-activity-row');
+        }
     }
 };
 

data/interfaces/default/libraries.html

@@ -91,7 +91,7 @@
                     json_data: JSON.stringify(d)
                 };
             }
-        }
+        };
 
         libraries_list_table = $('#libraries_list_table').DataTable(libraries_list_table_options);
         var colvis = new $.fn.dataTable.ColVis(libraries_list_table, { buttonText: '<i class="fa fa-columns"></i> Select columns', buttonClass: 'btn btn-dark', exclude: [0, 1] });

data/interfaces/default/library.html

@@ -374,7 +374,7 @@ DOCUMENTATION :: END
         // Build watch history table
         history_table_options.ajax = {
             url: 'get_history',
-            type: 'post',
+            type: 'POST',
             data: function ( d ) {
                 return {
                     json_data: JSON.stringify( d ),
@@ -406,7 +406,7 @@ DOCUMENTATION :: END
         // Build media info table
         media_info_table_options.ajax = {
             url: 'get_library_media_info',
-            type: 'post',
+            type: 'POST',
             data: function ( d ) {
                 return {
                     json_data: JSON.stringify( d ),

data/interfaces/default/library_stats.html

@@ -35,8 +35,7 @@ DOCUMENTATION :: END
 % if section_type in data:
 <div class="dashboard-stats-instance" id="library-stats-instance-${section_type}" data-section_type="${section_type}">
     <div class="dashboard-stats-container">
-        <div class="dashboard-stats-background-overlay">
-            <div id="library-stats-background-${section_type}" class="dashboard-stats-background" style="background-image: url(pms_image_proxy?img=/:/resources/${section_type}-fanart.jpg&width=500&height=280&fallback=art);"></div>
+        <div id="library-stats-background-${section_type}" class="dashboard-stats-background" style="background-image: url(pms_image_proxy?img=/:/resources/${section_type}-fanart.jpg&width=500&height=280&opacity=40&background=282828&blur=3&fallback=art);">
             <div id="library-stats-thumb-${section_type}" class="dashboard-stats-flat svg-icon library-${section_type} hidden-xs"></div>
             <div class="dashboard-stats-info-container">
                 <div id="library-stats-title-${section_type}" class="dashboard-stats-info-title">

data/interfaces/default/login.html

@@ -85,7 +85,7 @@
             dataType: 'json',
             statusCode: {
                 200: function() {
-                   window.location = "${http_root}";
+                   window.location = "${redirect_uri or http_root}";
                 },
                 401: function() {
                    $('#incorrect-login').show();

data/interfaces/default/logs.html

@@ -50,6 +50,7 @@
             <button class="btn btn-dark" id="download-plexscannerlog" style="display: none;"><i class="fa fa-download"></i> Download logs</button>
             <button class="btn btn-dark" id="clear-logs"><i class="fa fa-trash-o"></i> Clear logs</button>
             <button class="btn btn-dark" id="clear-notify-logs" style="display: none;"><i class="fa fa-trash-o"></i> Clear logs</button>
+            <button class="btn btn-dark" id="clear-newsletter-logs" style="display: none;"><i class="fa fa-trash-o"></i> Clear logs</button>
             <button class="btn btn-dark" id="clear-login-logs" style="display: none;"><i class="fa fa-trash-o"></i> Clear logs</button>
         </div>
     </div>
@@ -62,6 +63,7 @@
                 <li role="presentation"><a id="plex-scanner-logs-btn" href="#tabs-plex_scanner_log" aria-controls="tabs-plex_scanner_log" role="tab" data-toggle="tab">Plex Media Scanner Logs</a></li>
                 <li role="presentation"><a id="plex-websocket-logs-btn" href="#tabs-plex_websocket_log" aria-controls="tabs-plex_websocket_log" role="tab" data-toggle="tab">Plex Websocket Logs</a></li>
                 <li role="presentation"><a id="notification-logs-btn" href="#tabs-notification_log" aria-controls="tabs-notification_log" role="tab" data-toggle="tab">Notification Logs</a></li>
+                <li role="presentation"><a id="newsletter-logs-btn" href="#tabs-newsletter_log" aria-controls="tabs-newsletter_log" role="tab" data-toggle="tab">Newsletter Logs</a></li>
                 <li role="presentation"><a id="login-logs-btn" href="#tabs-login_log" aria-controls="tabs-login_log" role="tab" data-toggle="tab">Login Logs</a></li>
             </ul>
             <div class="tab-content">
@@ -141,6 +143,25 @@
                         <tbody></tbody>
                     </table>
                 </div>
+                <div role="tabpanel" class="tab-pane" id="tabs-newsletter_log">
+                    <table class="display" id="newsletter_log_table" width="100%">
+                        <thead>
+                            <tr>
+                                <th align="left" id="newsletter_timestamp">Timestamp</th>
+                                <th align="left" id="newsletter_newsletter_id">Newsletter ID</th>
+                                <th align="left" id="newsletter_agent_name">Agent</th>
+                                <th align="left" id="newsletter_notify_action">Action</th>
+                                <th align="left" id="newsletter_subject_text">Subject Text</th>
+                                <th align="left" id="newsletter_body_text">Body Text</th>
+                                <th align="left" id="newsletter_start_date">Start Date</th>
+                                <th align="left" id="newsletter_end_date">End Date</th>
+                                <th align="left" id="newsletter_uuid">UUID</th>
+                                <th align="left" id="newsletter_success"></th>
+                            </tr>
+                        </thead>
+                        <tbody></tbody>
+                    </table>
+                </div>
                 <div role="tabpanel" class="tab-pane" id="tabs-login_log">
                     <table class="display login_log_table" id="login_log_table" width="100%">
                         <thead>
@@ -191,6 +212,7 @@
 <script src="${http_root}js/tables/logs.js${cache_param}"></script>
 <script src="${http_root}js/tables/plex_logs.js${cache_param}"></script>
 <script src="${http_root}js/tables/notification_logs.js${cache_param}"></script>
+<script src="${http_root}js/tables/newsletter_logs.js${cache_param}"></script>
 <script src="${http_root}js/tables/login_logs.js${cache_param}"></script>
 <script>
 
@@ -229,8 +251,8 @@
         var selected_log_level = null;
         function loadtautullilogs(logfile, selected_log_level) {
             log_table_options.ajax = {
-                url: "get_log",
-                type: 'post',
+                url: 'get_log',
+                type: 'POST',
                 data: function (d) {
                     return {
                         logfile: logfile,
@@ -249,7 +271,8 @@
 
         function loadPlexLogs() {
             plex_log_table_options.ajax = {
-                url: "get_plex_log?log_type=server"
+                url: 'get_plex_log?log_type=server',
+                type: 'POST'
             };
             plex_log_table_options.initComplete = bindLogLevelFilter;
             plex_log_table = $('#plex_log_table').DataTable(plex_log_table_options);
@@ -257,7 +280,8 @@
 
         function loadPlexScannerLogs() {
             plex_log_table_options.ajax = {
-                url: "get_plex_log?log_type=scanner"
+                url: 'get_plex_log?log_type=scanner',
+                type: 'POST'
             };
             plex_log_table_options.initComplete = bindLogLevelFilter;
             plex_scanner_log_table = $('#plex_scanner_log_table').DataTable(plex_log_table_options);
@@ -265,7 +289,8 @@
 
         function loadNotificationLogs() {
             notification_log_table_options.ajax = {
-                url: "get_notification_log",
+                url: 'get_notification_log',
+                type: 'POST',
                 data: function (d) {
                     return {
                         json_data: JSON.stringify(d)
@@ -275,10 +300,23 @@
             notification_log_table = $('#notification_log_table').DataTable(notification_log_table_options);
         }
 
+        function loadNewsletterLogs() {
+            newsletter_log_table_options.ajax = {
+                url: "get_newsletter_log",
+                data: function (d) {
+                    return {
+                        json_data: JSON.stringify(d)
+                    };
+                }
+            };
+            newsletter_log_table = $('#newsletter_log_table').DataTable(newsletter_log_table_options);
+        }
+
         function loadLoginLogs() {
             login_log_table_options.pageLength = 50;
             login_log_table_options.ajax = {
-                url: "get_user_logins",
+                url: 'get_user_logins',
+                type: 'POST',
                 data: function (d) {
                     return {
                         json_data: JSON.stringify(d)
@@ -296,6 +334,7 @@
             $("#download-plexserverlog").hide();
             $("#download-plexscannerlog").hide();
             $("#clear-notify-logs").hide();
+            $("#clear-newsletter-logs").hide();
             $("#clear-login-logs").hide();
             loadtautullilogs('tautulli', selected_log_level);
             clearSearchButton('tautulli_log_table', log_table);
@@ -309,7 +348,8 @@
             $("#download-plexserverlog").hide();
             $("#download-plexscannerlog").hide();
             $("#clear-notify-logs").hide();
-            $("#clear-login-logs").hide();
+             $("#clear-newsletter-logs").hide();
+           $("#clear-login-logs").hide();
             loadtautullilogs('tautulli_api', selected_log_level);
             clearSearchButton('tautulli_api_log_table', log_table);
         });
@@ -322,6 +362,7 @@
             $("#download-plexserverlog").hide();
             $("#download-plexscannerlog").hide();
             $("#clear-notify-logs").hide();
+            $("#clear-newsletter-logs").hide();
             $("#clear-login-logs").hide();
             loadtautullilogs('plex_websocket', selected_log_level);
             clearSearchButton('plex_websocket_log_table', log_table);
@@ -335,6 +376,7 @@
             $("#download-plexserverlog").show();
             $("#download-plexscannerlog").hide();
             $("#clear-notify-logs").hide();
+            $("#clear-newsletter-logs").hide();
             $("#clear-login-logs").hide();
             loadPlexLogs();
             clearSearchButton('plex_log_table', plex_log_table);
@@ -348,6 +390,7 @@
             $("#download-plexserverlog").hide();
             $("#download-plexscannerlog").show();
             $("#clear-notify-logs").hide();
+            $("#clear-newsletter-logs").hide();
             $("#clear-login-logs").hide();
             loadPlexScannerLogs();
             clearSearchButton('plex_scanner_log_table', plex_scanner_log_table);
@@ -361,11 +404,26 @@
             $("#download-plexserverlog").hide();
             $("#download-plexscannerlog").hide();
             $("#clear-notify-logs").show();
+            $("#clear-newsletter-logs").hide();
             $("#clear-login-logs").hide();
             loadNotificationLogs();
             clearSearchButton('notification_log_table', notification_log_table);
         });
 
+        $("#newsletter-logs-btn").click(function () {
+            $("#tautulli-log-levels").hide();
+            $("#plex-log-levels").hide();
+            $("#clear-logs").hide();
+            $("#download-tautullilog").hide();
+            $("#download-plexserverlog").hide();
+            $("#download-plexscannerlog").hide();
+            $("#clear-notify-logs").hide();
+            $("#clear-newsletter-logs").show();
+            $("#clear-login-logs").hide();
+            loadNewsletterLogs();
+            clearSearchButton('newsletter_log_table', newsletter_log_table);
+        });
+
         $("#login-logs-btn").click(function () {
             $("#tautulli-log-levels").hide();
             $("#plex-log-levels").hide();
@@ -374,6 +432,7 @@
             $("#download-plexserverlog").hide();
             $("#download-plexscannerlog").hide();
             $("#clear-notify-logs").hide();
+            $("#clear-newsletter-logs").hide();
             $("#clear-login-logs").show();
             loadLoginLogs();
             clearSearchButton('login_log_table', notification_log_table);
@@ -442,6 +501,27 @@
             });
         });
 
+        $("#clear-newsletter-logs").click(function () {
+            $("#confirm-message").text("Are you sure you want to clear the Tautulli Newsletter Logs?");
+            $('#confirm-modal').modal();
+            $('#confirm-modal').one('click', '#confirm-button', function () {
+                $.ajax({
+                    url: 'delete_newsletter_log',
+                    type: 'POST',
+                    complete: function (xhr, status) {
+                        result = $.parseJSON(xhr.responseText);
+                        msg = result.message;
+                        if (result.result === 'success') {
+                            showMsg('<i class="fa fa-check"></i> ' + msg, false, true, 5000)
+                        } else {
+                            showMsg('<i class="fa fa-times"></i> ' + msg, false, true, 5000, true)
+                        }
+                        newsletter_log_table.draw();
+                    }
+                });
+            });
+        });
+
         $("#clear-login-logs").click(function () {
             $("#confirm-message").text("Are you sure you want to clear the Tautulli Login Logs?");
             $('#confirm-modal').modal();

data/interfaces/default/newsletter_config.html

@@ -0,0 +1,739 @@
+% if newsletter:
+<%!
+    import json
+    from plexpy import notifiers
+    from plexpy.helpers import anon_url, checked
+
+    all_notifiers = sorted(notifiers.get_notifiers(), key=lambda k: (k['agent_label'].lower(), k['friendly_name'], k['id']))
+    email_notifiers = [n for n in all_notifiers if n['agent_name'] == 'email']
+    email_notifiers = [{'id': 0, 'agent_label': 'New Email Configuration', 'friendly_name': ''}] + email_notifiers
+    other_notifiers = [{'id': 0, 'agent_label': 'Select a Notification Agent', 'friendly_name': ''}] + all_notifiers
+%>
+<div class="modal-dialog" role="document">
+    <div class="modal-content">
+        <div class="modal-header">
+            <button type="button" class="close" data-dismiss="modal" aria-hidden="true"><i class="fa fa-remove"></i></button>
+            <h4 class="modal-title" id="newsletter-config-modal-header">${newsletter['agent_label']} Newsletter Settings &nbsp;<small><span class="newsletter_id">(Newsletter ID: ${newsletter['id']})</span></small></h4>
+        </div>
+        <div class="modal-body">
+            <div class="container-fluid">
+                <div class="row">
+                    <ul class="nav nav-tabs list-unstyled" role="tablist">
+                        <li role="presentation" class="active"><a href="#tabs-newsletter_config" aria-controls="tabs-newsletter_config" role="tab" data-toggle="tab">Configuration</a></li>
+                        <li role="presentation"><a href="#tabs-newsletter_agent" aria-controls="tabs-newsletter_agent" role="tab" data-toggle="tab">Notification Agent</a></li>
+                        <li role="presentation"><a href="#tabs-newsletter_text" aria-controls="tabs-newsletter_text" role="tab" data-toggle="tab">Newsletter Text</a></li>
+                        <li role="presentation"><a href="#tabs-test_newsletter" aria-controls="tabs-test_newsletter" role="tab" data-toggle="tab">Test Newsletter</a></li>
+                    </ul>
+                </div>
+                <form action="set_newsletter_config" method="post" class="form" id="set_newsletter_config" data-parsley-validate>
+                    <div class="tab-content">
+                        <div role="tabpanel" class="tab-pane active" id="tabs-newsletter_config">
+                            <div class="row">
+                                <div class="col-md-12">
+                                    <div class="checkbox" style="margin-bottom: 20px;">
+                                        <label>
+                                            <input type="checkbox" data-id="active_value" class="checkboxes" value="1" ${checked(newsletter['active'])}> Enable the Newsletter
+                                        </label>
+                                        <input type="hidden" id="active_value" name="active" value="${newsletter['active']}">
+                                    </div>
+                                    <div class="form-group">
+                                        <label for="custom_cron">Schedule</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <select class="form-control" id="custom_cron" name="newsletter_config_custom_cron">
+                                                    <option value="0" ${'selected' if newsletter['config']['custom_cron'] == 0 else ''}>Simple</option>
+                                                    <option value="1" ${'selected' if newsletter['config']['custom_cron'] == 1 else ''}>Custom</option>
+                                                </select>
+                                                <input type="text" id="cron_value" name="cron" value="${newsletter['cron']}" />
+                                                <div id="cron-widget"></div>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">
+                                            <span id="simple_cron_message">Set the schedule for the newsletter.</span>
+                                            <span id="custom_cron_message">Set the schedule for the newsletter using a <a href="${anon_url('https://crontab.guru')}" target="_blank">custom crontab</a>. Only standard cron values are valid.</span>
+                                        </p>
+                                    </div>
+                                    <div class="form-group">
+                                        <label for="time_frame">Time Frame</label>
+                                        <div class="row">
+                                            <div class="col-md-4">
+                                                <div class="input-group newsletter-time_frame">
+                                                    <span class="input-group-addon form-control btn-dark inactive">Last</span>
+                                                    <input type="number" class="form-control" id="newsletter_config_time_frame" name="newsletter_config_time_frame" value="${newsletter['config']['time_frame']}">
+                                                    <select class="form-control" id="newsletter_config_time_frame_units" name="newsletter_config_time_frame_units">
+                                                        <option value="days" ${'selected' if newsletter['config']['time_frame_units'] == 'days' else ''}>days</option>
+                                                        <option value="hours" ${'selected' if newsletter['config']['time_frame_units'] == 'hours' else ''}>hours</option>
+                                                    </select>
+                                                </div>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">Set the time frame to include in the newsletter. Note: Days uses calendar days (i.e. since midnight).</p>
+                                    </div>
+                                </div>
+                                <div class="col-md-12" style="padding-top: 10px; border-top: 1px solid #444;">
+                                    <input type="hidden" id="newsletter_id" name="newsletter_id" value="${newsletter['id']}" />
+                                    <input type="hidden" id="agent_id" name="agent_id" value="${newsletter['agent_id']}" />
+                                    % for item in newsletter['config_options']:
+                                    % if item['input_type'] == 'help':
+                                    <div class="form-group">
+                                        <label>${item['label']}</label>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % elif item['input_type'] == 'text' or item['input_type'] == 'password':
+                                    <div class="form-group">
+                                        <label for="${item['name']}">${item['label']}</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <input type="${item['input_type']}" class="form-control" id="${item['name']}" name="${item['name']}" value="${item['value']}" size="30" ${'readonly' if item.get('readonly') else ''}>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % elif item['input_type'] == 'number':
+                                    <div class="form-group">
+                                        <label for="${item['name']}">${item['label']}</label>
+                                        <div class="row">
+                                            <div class="col-md-3">
+                                                <input type="${item['input_type']}" class="form-control" id="${item['name']}" name="${item['name']}" value="${item['value']}" size="30">
+                                            </div>
+                                        </div>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % elif item['input_type'] == 'button':
+                                    <div class="form-group">
+                                        <label for="${item['name']}">${item['label']}</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <input type="button" class="btn btn-bright" id="${item['name']}" name="${item['name']}" value="${item['value']}">
+                                            </div>
+                                        </div>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % elif item['input_type'] == 'checkbox':
+                                    <div class="checkbox">
+                                        <label>
+                                            <input type="checkbox" data-id="${item['name']}" class="checkboxes" value="1" ${checked(item['value'])}> ${item['label']}
+                                        </label>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                        <input type="hidden" id="${item['name']}" name="${item['name']}" value="${item['value']}">
+                                    </div>
+                                    % elif item['input_type'] == 'select':
+                                    <div class="form-group">
+                                        <label for="${item['name']}">${item['label']}</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <select class="form-control" id="${item['name']}" name="${item['name']}">
+                                                    % for key, value in sorted(item['select_options'].iteritems()):
+                                                    % if key == item['value']:
+                                                    <option value="${key}" selected>${value}</option>
+                                                    % else:
+                                                    <option value="${key}">${value}</option>
+                                                    % endif
+                                                    % endfor
+                                                </select>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % elif item['input_type'] == 'selectize':
+                                    <div class="form-group">
+                                        <label for="${item['name']}">${item['label']}</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <select class="form-control" id="${item['name']}" name="${item['name']}">
+                                                    <option value="select-all">Select All</option>
+                                                    <option value="remove-all">Remove All</option>
+                                                    % if isinstance(item['select_options'], dict):
+                                                    % for section, options in item['select_options'].iteritems():
+                                                    <optgroup label="${section}">
+                                                        % for option in sorted(options, key=lambda x: x['text'].lower()):
+                                                            <option value="${option['value']}">${option['text']}</option>
+                                                        % endfor
+                                                    </optgroup>
+                                                    % endfor
+                                                    % else:
+                                                    <option value="border-all"></option>
+                                                    % for option in sorted(item['select_options'], key=lambda x: x['text'].lower()):
+                                                        <option value="${option['value']}">${option['text']}</option>
+                                                    % endfor
+                                                    % endif
+                                                </select>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % endif
+                                    % endfor
+                                </div>
+                                <div class="col-md-12" style="margin-top: 10px; padding-top: 10px; border-top: 1px solid #444;">
+                                    <div class="form-group">
+                                        <label for="friendly_name">Description</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <input type="text" class="form-control" id="friendly_name" name="friendly_name" value="${newsletter['friendly_name']}" size="30">
+                                            </div>
+                                        </div>
+                                        <p class="help-block">Optional: Enter a description to help identify this newsletter in the newsletters list.</p>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                        <div role="tabpanel" class="tab-pane" id="tabs-newsletter_agent">
+                            <div class="row">
+                                <div class="col-md-12">
+                                    <div class="checkbox">
+                                        <label>
+                                            <input type="checkbox" id="newsletter_config_formatted_checkbox" data-id="newsletter_config_formatted" class="checkboxes" value="1" ${checked(newsletter['config']['formatted'])}> Send newsletter as an HTML formatted Email
+                                        </label>
+                                        <p class="help-block">Enable to send the newsletter as an HTML formatted Email. Disable to only send a subject and body message to a different notification agent.</p>
+                                        <input type="hidden" id="newsletter_config_formatted" name="newsletter_config_formatted" value="${newsletter['config']['formatted']}">
+                                    </div>
+                                    <div class="form-group" id="email_notifier_select">
+                                        <label for="newsletter_email_notifier_id">Email Notification Agent</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <select class="form-control" id="newsletter_email_notifier_id" name="newsletter_email_notifier_id">
+                                                    % for notifier in email_notifiers:
+                                                    <% selected = 'selected' if notifier['id'] == newsletter['email_config']['notifier_id'] else '' %>
+                                                    % if notifier['friendly_name']:
+                                                    <option value="${notifier['id']}" ${selected}>${notifier['agent_label']} (${notifier['id']} - ${notifier['friendly_name']})</option>
+                                                    % elif notifier['id']:
+                                                    <option value="${notifier['id']}" ${selected}>${notifier['agent_label']} (${notifier['id']})</option>
+                                                    % else:
+                                                    <option value="${notifier['id']}" ${selected}>${notifier['agent_label']}</option>
+                                                    % endif
+                                                    % endfor
+                                                </select>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">
+                                            Select an existing Email notification agent or enter a new configuration below.<br>
+                                            Note: Make sure HTML support is enabled for the Email notification agent.
+                                        </p>
+                                    </div>
+                                    <div class="form-group" id="other_notifier_select">
+                                        <label for="newsletter_config_notifier_id">Notification Agent</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <select class="form-control" id="newsletter_config_notifier_id" name="newsletter_config_notifier_id">
+                                                    % for notifier in other_notifiers:
+                                                    <% selected = 'selected' if notifier['id'] == newsletter['config']['notifier_id'] else '' %>
+                                                    % if notifier['friendly_name']:
+                                                    <option value="${notifier['id']}" ${selected}>${notifier['agent_label']} (${notifier['id']} - ${notifier['friendly_name']})</option>
+                                                    % elif notifier['id']:
+                                                    <option value="${notifier['id']}" ${selected}>${notifier['agent_label']} (${notifier['id']})</option>
+                                                    % else:
+                                                    <option value="${notifier['id']}" ${selected}>${notifier['agent_label']}</option>
+                                                    % endif
+                                                    % endfor
+                                                </select>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">
+                                            Select an existing notification agent where the subject and body text will be sent.<br>
+                                            Note: Self-hosted newsletters must be enabled under <a data-tab-destination="tabs-notifications" data-dismiss="modal" data-target="#newsletter_self_hosted">Newsletters</a> to include a link to the newsletter.
+                                        </p>
+                                    </div>
+                                </div>
+                                <div id="newsletter-email-config" class="col-md-12" style="padding-top: 10px; border-top: 1px solid #444;">
+                                    % for item in newsletter['email_config_options']:
+                                    % if item['input_type'] == 'help':
+                                    <div class="form-group">
+                                        <label>${item['label']}</label>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % elif item['input_type'] == 'text' or item['input_type'] == 'password':
+                                    <div class="form-group">
+                                        <label for="${item['name']}">${item['label']}</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <input type="${item['input_type']}" class="form-control" id="${item['name']}" name="${item['name']}" value="${item['value']}" size="30" ${'readonly' if item.get('readonly') else ''}>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % elif item['input_type'] == 'number':
+                                    <div class="form-group">
+                                        <label for="${item['name']}">${item['label']}</label>
+                                        <div class="row">
+                                            <div class="col-md-3">
+                                                <input type="${item['input_type']}" class="form-control" id="${item['name']}" name="${item['name']}" value="${item['value']}" size="30">
+                                            </div>
+                                        </div>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % elif item['input_type'] == 'button':
+                                    <div class="form-group">
+                                        <label for="${item['name']}">${item['label']}</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <input type="button" class="btn btn-bright" id="${item['name']}" name="${item['name']}" value="${item['value']}">
+                                            </div>
+                                        </div>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % elif item['input_type'] == 'checkbox' and item['name'] != 'newsletter_email_html_support':
+                                    <div class="checkbox">
+                                        <label>
+                                            <input type="checkbox" data-id="${item['name']}" class="checkboxes" value="1" ${checked(item['value'])}> ${item['label']}
+                                        </label>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                        <input type="hidden" id="${item['name']}" name="${item['name']}" value="${item['value']}">
+                                    </div>
+                                    % elif item['input_type'] == 'select':
+                                    <div class="form-group">
+                                        <label for="${item['name']}">${item['label']}</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <select class="form-control" id="${item['name']}" name="${item['name']}">
+                                                    % for key, value in sorted(item['select_options'].iteritems()):
+                                                    % if key == item['value']:
+                                                    <option value="${key}" selected>${value}</option>
+                                                    % else:
+                                                    <option value="${key}">${value}</option>
+                                                    % endif
+                                                    % endfor
+                                                </select>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % elif item['input_type'] == 'selectize':
+                                    <div class="form-group">
+                                        <label for="${item['name']}">${item['label']}</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <select class="form-control" id="${item['name']}" name="${item['name']}">
+                                                    <option value="select-all">Select All</option>
+                                                    <option value="remove-all">Remove All</option>
+                                                    % if isinstance(item['select_options'], dict):
+                                                    % for section, options in item['select_options'].iteritems():
+                                                    <optgroup label="${section}">
+                                                        % for option in sorted(options, key=lambda x: x['text'].lower()):
+                                                            <option value="${option['value']}">${option['text']}</option>
+                                                        % endfor
+                                                    </optgroup>
+                                                    % endfor
+                                                    % else:
+                                                    <option value="border-all"></option>
+                                                    % for option in sorted(item['select_options'], key=lambda x: x['text'].lower()):
+                                                        <option value="${option['value']}">${option['text']}</option>
+                                                    % endfor
+                                                    % endif
+                                                </select>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">${item['description'] | n}</p>
+                                    </div>
+                                    % endif
+                                    % endfor
+                                    <input type="hidden" id="newsletter_email_html_support" name="newsletter_email_html_support" value="1">
+                                </div>
+                            </div>
+                        </div>
+                        <div role="tabpanel" class="tab-pane" id="tabs-newsletter_text">
+                            <label>Newsletter Text</label>
+                            <p class="help-block">
+                                Set the custom formatted text for each type of notification.
+                                <a href="#newsletter-text-sub-modal" data-toggle="modal">Click here</a> for a list of available parameters which can be used.
+                            </p>
+                            <p class="help-block">
+                                You can also add text modifiers to change the case or slice parameters with a list of items.
+                                <a href="#notify-text-modifiers-modal" data-toggle="modal">Click here</a> to view usage information.
+                            </p>
+                            <div class="row">
+                                <div class="col-md-12">
+                                    <div class="form-group">
+                                        <label for="subject">Subject</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <input type="text" class="form-control" id="subject" name="subject" value="${newsletter['subject']}" size="30">
+                                            </div>
+                                        </div>
+                                        <p class="help-block">
+                                            Enter a custom subject line for the newsletter. Leave blank for default.
+                                        </p>
+                                    </div>
+                                    <div class="form-group" id="newsletter_body">
+                                        <label for="body">Body</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <textarea class="form-control"  id="body" name="body" data-autoresize>${newsletter['body']}</textarea>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">
+                                            Enter a custom body line for the newsletter notification. Leave blank for default.
+                                        </p>
+                                    </div>
+                                    <div class="form-group">
+                                        <label for="message">Message</label>
+                                        <div class="row">
+                                            <div class="col-md-12">
+                                                <textarea class="form-control"  id="message" name="message" data-autoresize>${newsletter['message']}</textarea>
+                                            </div>
+                                        </div>
+                                        <p class="help-block">
+                                            Enter a custom message to include on the newsletter.
+                                        </p>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                        <div role="tabpanel" class="tab-pane" id="tabs-test_newsletter">
+                            <label>Preview Newsletter</label>
+                            <p class="help-block">
+                                Preview the ${newsletter['agent_label']} newsletter.
+                            </p>
+                            <div class="form-group">
+                                <div class="row">
+                                    <div class="col-md-12">
+                                        <input type="button" class="btn btn-bright" id="preview_newsletter" name="preview_newsletter" value="Preview ${newsletter['agent_label']} Newsletter">
+                                    </div>
+                                </div>
+                            </div>
+                            <label>Test Newsletter</label>
+                            <p class="help-block">
+                                Test if the ${newsletter['agent_label']} newsletter is working. Check the <a href="logs">logs</a> for troubleshooting.
+                            </p>
+                            <p class="help-block">
+                                Warning: This will send an actual newsletter to your notification agent!
+                            </p>
+                            <div class="form-group">
+                                <div class="row">
+                                    <div class="col-md-12">
+                                        <input type="button" class="btn btn-bright" id="test_newsletter" name="test_newsletter" value="Test ${newsletter['agent_label']} Newsletter">
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </form>
+            </div>
+        </div>
+        <div class="modal-footer">
+            <input type="button" id="delete-newsletter-item" class="btn btn-danger btn-edit" style="float:left;" value="Delete">
+            <input type="button" id="duplicate-newsletter-item" class="btn btn-dark btn-edit" style="float:left;" value="Duplicate">
+            <input type="button" id="save-newsletter-item" class="btn btn-bright" value="Save">
+        </div>
+    </div>
+</div>
+
+<script src="${http_root}js/jquery-cron-min.js"></script>
+<script>
+
+    $('#newsletter-config-modal').unbind('hidden.bs.modal');
+
+    var cron_widget = $('#cron-widget').cron({
+        initial: '0 0 * * 0',
+        classes: 'form-control cron-select',
+        onChange: function() {
+            $("#cron_value").val($(this).cron('value'));
+        }
+    });
+
+    if (${newsletter['config']['custom_cron']}) {
+        $('#cron_value').val('${newsletter['cron']}');
+    } else {
+        try {
+            cron_widget.cron('value', '${newsletter['cron']}');
+        } catch (e) {}
+    }
+
+    function toggleCustomCron() {
+       if ($('#custom_cron').val() === '1'){
+           $('#cron-widget').hide();
+           $('#cron_value').show();
+           $('#simple_cron_message').hide();
+           $('#custom_cron_message').show();
+       } else {
+           $('#cron-widget').show();
+           $('#cron_value').hide();
+           $('#simple_cron_message').show();
+           $('#custom_cron_message').hide();
+       }
+    }
+    toggleCustomCron();
+
+    $('#custom_cron').change(function () {
+        toggleCustomCron();
+    });
+
+    var $incl_libraries = $('#newsletter_config_incl_libraries').selectize({
+        plugins: ['remove_button'],
+        maxItems: null,
+        render: {
+            option: function(item) {
+                if (item.value.endsWith('-all')) {
+                    return '<div class="' + item.value + '">' + item.text + '</div>'
+                }
+                return '<div>' + item.text + '</div>';
+            }
+        },
+        onItemAdd: function(value) {
+            if (value === 'select-all') {
+                var all_keys = $.map(this.options, function(option){
+                    return option.value.endsWith('-all') ? null : option.value;
+                });
+                this.setValue(all_keys);
+            } else if (value === 'remove-all') {
+                this.clear();
+                this.refreshOptions();
+                this.positionDropdown();
+            }
+        }
+    });
+    var incl_libraries = $incl_libraries[0].selectize;
+    incl_libraries.setValue(${json.dumps(next((c['value'] for c in newsletter['config_options'] if c['name'] == 'newsletter_config_incl_libraries'), [])) | n});
+
+    function toggleEmailSelect () {
+        if ($('#newsletter_config_formatted_checkbox').is(':checked')) {
+            $('#newsletter_body').hide();
+            $('#email_notifier_select').show();
+            $('#other_notifier_select').hide();
+            toggleNewEmailConfig();
+        } else {
+            $('#newsletter_body').show();
+            $('#email_notifier_select').hide();
+            $('#other_notifier_select').show();
+            $('#newsletter-email-config').hide();
+        }
+    }
+    toggleEmailSelect();
+
+    $('#newsletter_config_formatted_checkbox').change(function () {
+        toggleEmailSelect();
+    });
+
+    function toggleNewEmailConfig () {
+        if ($('#newsletter_config_formatted_checkbox').is(':checked') && $('#newsletter_email_notifier_id').val() === '0') {
+            $('#newsletter-email-config').show();
+        } else {
+            $('#newsletter-email-config').hide();
+        }
+    }
+    toggleNewEmailConfig();
+
+    $('#newsletter_email_notifier_id').change(function () {
+        toggleNewEmailConfig();
+    });
+
+    var REGEX_EMAIL = '([a-z0-9!#$%&\'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+/=?^_`{|}~-]+)*@' +
+                      '(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)';
+    var $email_selectors = $('#newsletter_email_to, #newsletter_email_cc, #newsletter_email_bcc').selectize({
+        plugins: ['remove_button'],
+        maxItems: null,
+        render: {
+            item: function(item, escape) {
+                return '<div>' +
+                    (item.text ? '<span class="item-text">' + escape(item.text) + '</span>' : '') +
+                    (item.value ? '<span class="item-value">' + escape(item.value) + '</span>' : '') +
+                '</div>';
+            },
+            option: function(item, escape) {
+                var label = item.text || item.value;
+                var caption = item.text ? item.value : null;
+                if (item.value.endsWith('-all')) {
+                    return '<div class="' + item.value + '">' + escape(label) + '</div>'
+                }
+                return '<div>' +
+                    escape(label) +
+                    (caption ? '<span class="caption">' + escape(caption) + '</span>' : '') +
+                '</div>';
+            }
+        },
+        onItemAdd: function(value) {
+            if (value === 'select-all') {
+                var all_keys = $.map(this.options, function(option){
+                    return option.value.endsWith('-all') ? null : option.value;
+                });
+                this.setValue(all_keys);
+            } else if (value === 'remove-all') {
+                this.clear();
+                this.refreshOptions();
+                this.positionDropdown();
+            }
+        },
+        createFilter: function(input) {
+            var match, regex;
+
+            // email@address.com
+            regex = new RegExp('^' + REGEX_EMAIL + '$', 'i');
+            match = input.match(regex);
+            if (match) return !this.options.hasOwnProperty(match[0]);
+
+            // user <email@address.com>
+            regex = new RegExp('^([^<]*)\<' + REGEX_EMAIL + '\>$', 'i');
+            match = input.match(regex);
+            if (match) return !this.options.hasOwnProperty(match[2]);
+
+            return false;
+        },
+        create: function(input) {
+            if ((new RegExp('^' + REGEX_EMAIL + '$', 'i')).test(input)) {
+                return {value: input};
+            }
+            var match = input.match(new RegExp('^([^<]*)\<' + REGEX_EMAIL + '\>$', 'i'));
+            if (match) {
+                return {
+                    value : match[2],
+                    text  : $.trim(match[1])
+                };
+            }
+            return false;
+        }
+    });
+    var email_to = $email_selectors[0].selectize;
+    var email_cc = $email_selectors[1].selectize;
+    var email_bcc = $email_selectors[2].selectize;
+    email_to.setValue(${json.dumps(next((c['value'] for c in newsletter['email_config_options'] if c['name'] == 'newsletter_email_to'), [])) | n});
+    email_cc.setValue(${json.dumps(next((c['value'] for c in newsletter['email_config_options'] if c['name'] == 'newsletter_email_cc'), [])) | n});
+    email_bcc.setValue(${json.dumps(next((c['value'] for c in newsletter['email_config_options'] if c['name'] == 'newsletter_email_bcc'), [])) | n});
+
+    function reloadModal() {
+        $.ajax({
+            url: 'get_newsletter_config_modal',
+            data: { newsletter_id: '${newsletter["id"]}' },
+            cache: false,
+            async: true,
+            complete: function (xhr, status) {
+                $('#newsletter-config-modal').html(xhr.responseText);
+            }
+        });
+    }
+
+    function saveCallback(jqXHR) {
+        if (jqXHR) {
+            var result = $.parseJSON(jqXHR.responseText);
+            var msg = result.message;
+            if (result.result == 'success') {
+                showMsg('<i class="fa fa-check"></i> ' + msg, false, true, 5000)
+            } else {
+                showMsg('<i class="fa fa-times"></i> ' + msg, false, true, 5000, true)
+            }
+        }
+
+        getNewslettersTable();
+    }
+
+    function deleteCallback() {
+        $('#newsletter-config-modal').modal('hide');
+        getNewslettersTable();
+    }
+
+    function duplicateCallback(result) {
+        // Set new newsletter id
+        $('#newsletter_id').val(result.newsletter_id);
+        // Clear friendly name
+        $('#friendly_name').val("");
+
+        saveNewsletter();
+
+        $('#newsletter-config-modal').on('hidden.bs.modal', function () {
+            loadNewsletterConfig(result.newsletter_id);
+        });
+        $('#newsletter-config-modal').modal('hide');
+    }
+
+    function saveNewsletter() {
+        // Trim all text inputs before saving
+        $('input[type=text]').val(function(_, value) {
+            return $.trim(value);
+        });
+        // Make sure simple cron value is set
+        if ($('#custom_cron').val() === '0'){
+            $("#cron_value").val(cron_widget.cron('value'));
+        }
+        doAjaxCall('set_newsletter_config', $(this), 'tabs', true, true, saveCallback);
+    }
+
+    $('#delete-newsletter-item').click(function () {
+        var msg = 'Are you sure you want to delete this <strong>${newsletter["agent_label"]}</strong> newsletter?';
+        var url = 'delete_newsletter';
+        confirmAjaxCall(url, msg, { newsletter_id: '${newsletter["id"]}' }, null, deleteCallback);
+    });
+
+    $('#duplicate-newsletter-item').click(function() {
+        var msg = 'Are you sure you want to duplicate this <strong>${newsletter["agent_label"]}</strong> newsletter?';
+        var url = 'add_newsletter_config';
+        confirmAjaxCall(url, msg, { agent_id: '${newsletter["agent_id"]}' }, null, duplicateCallback);
+    });
+
+    $('#save-newsletter-item').click(function () {
+        saveNewsletter();
+    });
+
+    $('#preview_newsletter').click(function () {
+        doAjaxCall('set_newsletter_config', $(this), 'tabs', true, false, previewNewsletter);
+    });
+
+    $('#test_newsletter').click(function () {
+        doAjaxCall('set_newsletter_config', $(this), 'tabs', true, false, sendTestNewsletter);
+    });
+
+    function previewNewsletter() {
+        showMsg('<i class="fa fa-check"></i>&nbsp; Check pop-up blocker if no response.', false, true, 2000);
+        window.open('newsletter_preview?newsletter_id=' + $('#newsletter_id').val());
+    }
+
+    function sendTestNewsletter() {
+        showMsg('<i class="fa fa-refresh fa-spin"></i>&nbsp; Sending Newsletter', false);
+        $.ajax({
+            url: 'send_newsletter',
+            data: {
+                newsletter_id: $('#newsletter_id').val(),
+                notify_action: 'test'
+            },
+            cache: false,
+            async: true,
+            success: function (data) {
+                if (data.result === 'success') {
+                    showMsg('<i class="fa fa-check"></i> ' + data.message, false, true, 5000);
+                } else {
+                    showMsg('<i class="fa fa-exclamation-circle"></i> ' + data.message, false, true, 5000, true);
+                }
+            }
+        });
+    }
+
+    $("${', '.join(['#' + c['name'] for c in newsletter['config_options'] if c.get('refresh')])}").on('change', function () {
+        // Reload modal to update certain fields
+        doAjaxCall('set_newsletter_config', $(this), 'tabs', true, false, reloadModal);
+        return false;
+    });
+
+    // Never send checkbox values directly, always substitute value in hidden input.
+    $('.checkboxes').click(function () {
+        var configToggle = $(this).data('id');
+        if ($(this).is(':checked')) {
+            $('#'+configToggle).val(1);
+        } else {
+            $('#'+configToggle).val(0);
+        }
+    });
+
+    // auto resizing textarea for custom notification message body
+    $('textarea[data-autoresize]').each(function () {
+        var offset = this.offsetHeight - this.clientHeight;
+        var resizeTextarea = function (el) {
+            $(el).css('height', 'auto').css('height', el.scrollHeight + offset);
+        };
+        $(this).on('focus keyup input', function () { resizeTextarea(this); }).removeAttr('data-autoresize');
+    });
+</script>
+% else:
+<div class="modal-dialog" role="document">
+    <div class="modal-content">
+        <div class="modal-header">
+            <button type="button" class="close" data-dismiss="modal" aria-hidden="true"><i class="fa fa-remove"></i></button>
+            <h4 class="modal-title" id="newsletter-config-modal-header">Error</h4>
+        </div>
+        <div class="modal-body" style="text-align: center">
+            <strong>
+                <i class="fa fa-exclamation-circle"></i> Failed to retrieve newsletter configuration. Check the <a href="logs">logs</a> for more info.
+            </strong>
+        </div>
+        <div class="modal-footer">
+        </div>
+    </div>
+</div>
+% endif

data/interfaces/default/newsletter_preview.html

@@ -0,0 +1,48 @@
+<%
+    import urllib
+%>
+<!doctype html>
+
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>Tautulli - ${title} | ${server_name}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link href="${http_root}css/tautulli.css${cache_param}" rel="stylesheet">
+    <style>
+        * {
+            padding: 0 !important;
+            margin: 0 !important;
+        }
+    </style>
+</head>
+
+<body>
+<div id="loader" class="newsletter-loader-container">
+    <div class="newsletter-loader-message">
+        <div class="newsletter-loader"></div>
+        <br>
+        Generating Newsletter
+        <br>
+        Please wait, this may take a few minutes...
+    </div>
+</div>
+
+<script src="${http_root}js/jquery-2.1.4.min.js"></script>
+<script>
+$(document).ready(function () {
+    var frame = $('<iframe></iframe>', {
+        src: '${http_root}real_newsletter?${urllib.urlencode(kwargs) | n}',
+        frameborder: '0',
+        style: 'display: none; height: 100vh; width: 100vw;'
+    });
+    frame.on('load', function (e) {
+        $(e.target).fadeIn();
+        $('#loader').fadeOut();
+    });
+    $('body').append(frame);
+});
+</script>
+
+</body>
+</html>

data/interfaces/default/newsletters_table.html

@@ -0,0 +1,51 @@
+<%doc>
+USAGE DOCUMENTATION :: PLEASE LEAVE THIS AT THE TOP OF THIS FILE
+
+For Mako templating syntax documentation please visit: http://docs.makotemplates.org/en/latest/
+
+Filename:           newsletters_table.html
+Version:            0.1
+
+DOCUMENTATION :: END
+</%doc>
+
+<% from plexpy.newsletter_handler import NEWSLETTER_SCHED %>
+<ul class="stacked-configs list-unstyled">
+    % for newsletter in sorted(newsletters_list, key=lambda k: (k['agent_label'], k['friendly_name'], k['id'])):
+    <li class="newsletter-agent" data-id="${newsletter['id']}">
+        <span>
+            <span class="toggle-left trigger-tooltip ${'active' if newsletter['active'] else ''}" data-toggle="tooltip" data-placement="top" title="Newsletter ${'active' if newsletter['active'] else 'inactive'}"><i class="fa fa-lg fa-newspaper-o"></i></span>
+            % if newsletter['friendly_name']:
+            ${newsletter['agent_label']} &nbsp;<span class="friendly_name">(${newsletter['id']} - ${newsletter['friendly_name']})</span>
+            % else:
+            ${newsletter['agent_label']} &nbsp;<span class="friendly_name">(${newsletter['id']})</span>
+            % endif
+            <span class="toggle-right"><i class="fa fa-lg fa-cog"></i></span>
+            <span class="toggle-right friendly_name" id="newsletter-next_run-${newsletter['id']}">
+                % if NEWSLETTER_SCHED.get_job('newsletter-{}'.format(newsletter['id'])):
+                <% job = NEWSLETTER_SCHED.get_job('newsletter-{}'.format(newsletter['id'])) %>
+                <script>
+                    $("#newsletter-next_run-${newsletter['id']}").text(moment("${job.next_run_time}", "YYYY-MM-DD HH:mm:ssZ").fromNow())
+                </script>
+                % endif
+            </span>
+        </span>
+    </li>
+    % endfor
+    <li class="add-newsletter-agent" id="add-newsletter-agent" data-target="#add-newsletter-modal" data-toggle="modal">
+        <span>
+            <span class="toggle-left"><i class="fa fa-lg fa-newspaper-o"></i></span> Add a new newsletter agent
+            <span class="toggle-right"><i class="fa fa-lg fa-plus"></i></span>
+        </span>
+    </li>
+</ul>
+
+<script>
+    // Load newsletter config modal
+    $(".newsletter-agent").click(function () {
+        var newsletter_id = $(this).data('id');
+        loadNewsletterConfig(newsletter_id);
+    });
+
+    $('.trigger-tooltip').tooltip();
+</script>

data/interfaces/default/notifier_config.html

@@ -1,3 +1,4 @@
+% if notifier:
 <%!
     import json
     from plexpy import helpers, notifiers, users
@@ -6,9 +7,6 @@
     user_emails = [{'user': u['friendly_name'] or u['username'], 'email': u['email']} for u in users.Users().get_users() if u['email']]
     sorted(user_emails, key=lambda u: u['user'])
 %>
-% if notifier:
-<link href="${http_root}css/selectize.bootstrap3.css" rel="stylesheet" />
-<link href="${http_root}css/selectize.min.css" rel="stylesheet" />
 <div class="modal-dialog" role="document">
     <div class="modal-content">
         <div class="modal-header">
@@ -19,7 +17,7 @@
             <div class="container-fluid">
                 <div class="row">
                     <ul class="nav nav-tabs list-unstyled" role="tablist">
-                        <li role="presentation" class="active"><a href="#tabs-config" aria-controls="tabs-config" role="tab" data-toggle="tab">Configuration</a></li>
+                        <li role="presentation" class="active"><a href="#tabs-notifier_config" aria-controls="tabs-notifier_config" role="tab" data-toggle="tab">Configuration</a></li>
                         <li role="presentation"><a href="#tabs-notify_triggers" aria-controls="tabs-notify_triggers" role="tab" data-toggle="tab">Triggers</a></li>
                         <li role="presentation"><a href="#tabs-notify_conditions" aria-controls="tabs-notify_conditions" role="tab" data-toggle="tab">Conditions</a></li>
                         <li role="presentation"><a href="#tabs-notify_text" aria-controls="tabs-notify_text" role="tab" data-toggle="tab">${'Arguments' if notifier['agent_name'] == 'scripts' else 'Text'}</a></li>
@@ -28,7 +26,7 @@
                 </div>
                 <form action="set_notifier_config" method="post" class="form" id="set_notifier_config" data-parsley-validate>
                     <div class="tab-content">
-                        <div role="tabpanel" class="tab-pane active" id="tabs-config">
+                        <div role="tabpanel" class="tab-pane active" id="tabs-notifier_config">
                             <div class="row">
                                 <div class="col-md-12">
                                     <input type="hidden" id="notifier_id" name="notifier_id" value="${notifier['id']}" />
@@ -148,7 +146,7 @@
                                     % for action in available_notification_actions:
                                     <div class="checkbox">
                                         <label>
-                                            <input type="checkbox" data-id="${action['name']}" class="checkboxes" value="1" ${helpers.checked(notifier['actions'][action['name']])}> Notify on ${action['label']}
+                                            <input type="checkbox" data-id="${action['name']}" class="checkboxes" value="1" ${helpers.checked(notifier['actions'][action['name']])}> ${action['label']}
                                         </label>
                                         <p class="help-block">${action['description'] | n}</p>
                                         <input type="hidden" id="${action['name']}" name="${action['name']}" value="${notifier['actions'][action['name']]}">
@@ -164,7 +162,7 @@
                                 <a href="#notify-text-sub-modal" data-toggle="modal">Click here</a> for a description of all the parameters.
                             </p>
                             <div id="condition-widget"></div>
-                            <input type="hidden" name="custom_conditions" id="custom_conditions" />
+                            <input type="hidden" id="custom_conditions" name="custom_conditions" />
 
                             <div class="form-group">
                                 <label for="custom_conditions_logic">Condition Logic</label>
@@ -340,21 +338,6 @@
         }
     });
 
-    function setNegativeOperator(select) {
-       if (select.val() === 'does not contain' || select.val() === 'is not') {
-           select.closest('.form-group').find('.react-selectize-search-field-and-selected-values').addClass('negative-operator');
-       } else {
-           select.closest('.form-group').find('.react-selectize-search-field-and-selected-values').removeClass('negative-operator');
-       }
-    }
-
-    $('#condition-widget select[name=operator]').each(function () {
-        setNegativeOperator($(this));
-    });
-    $('#condition-widget').on('change', 'select[name=operator]', function () {
-        setNegativeOperator($(this));
-    });
-
     function reloadModal() {
         $.ajax({
             url: 'get_notifier_config_modal',
@@ -422,7 +405,7 @@
     $('#duplicate-notifier-item').click(function() {
         var msg = 'Are you sure you want to duplicate this <strong>${notifier["agent_label"]}</strong> notification agent?';
         var url = 'add_notifier_config';
-        confirmAjaxCall(url, msg, { agent_id: "${notifier['agent_id']}" }, null, duplicateCallback);
+        confirmAjaxCall(url, msg, { agent_id: '${notifier["agent_id"]}' }, null, duplicateCallback);
     });
 
     $('#save-notifier-item').click(function () {
@@ -435,7 +418,7 @@
             '<div class="form-group">' +
             '<label>Warning</label>' +
             '<p class="help-block" style="color: #eb8600;">Facebook requires HTTPS for authorization. ' +
-            'Please enable HTTPS for Tautulli under <a data-tab-destination="tabs-web_interface" data-dismiss="modal" style="cursor: pointer;">Web Interface</a>.</p>' +
+            'Please enable HTTPS for Tautulli under <a data-tab-destination="tabs-web_interface" data-dismiss="modal" data-target="#enable_https">Web Interface</a>.</p>' +
             '</div>'
         );
         $('#facebook_redirect_uri').val('HTTPS not enabled');
@@ -763,11 +746,12 @@
     });
 
     function sendTestNotification() {
+        showMsg('<i class="fa fa-refresh fa-spin"></i>&nbsp; Sending Notification', false);
         if ('${notifier["agent_name"]}' !== 'browser') {
             $.ajax({
                 url: 'send_notification',
                 data: {
-                    notifier_id: '${notifier["id"]}',
+                    notifier_id: $('#notifier_id').val(),
                     subject: $('#test_subject').val(),
                     body: $('#test_body').val(),
                     script: $('#test_script').val(),
@@ -776,13 +760,11 @@
                 },
                 cache: false,
                 async: true,
-                complete: function (xhr, status) {
-                    if (xhr.responseText.indexOf('sent') > -1) {
-                        msg = '<i class="fa fa-check"></i>&nbsp; ' + xhr.responseText;
-                        showMsg(msg, false, true, 2000);
+                success: function (data) {
+                    if (data.result === 'success') {
+                        showMsg('<i class="fa fa-check"></i> ' + data.message, false, true, 5000);
                     } else {
-                        msg = '<i class="fa fa-times"></i>&nbsp; ' + xhr.responseText;
-                        showMsg(msg, false, true, 2000, true);
+                        showMsg('<i class="fa fa-exclamation-circle"></i> ' + data.message, false, true, 5000, true);
                     }
                 }
             });

data/interfaces/default/settings.html

@@ -4,10 +4,11 @@
     import sys
 
     import plexpy
-    from plexpy import common, notifiers
+    from plexpy import common, notifiers, newsletters
     from plexpy.helpers import anon_url, checked
 
-    available_notification_agents = sorted(notifiers.available_notification_agents(), key=lambda k: k['label'])
+    available_notification_agents = sorted(notifiers.available_notification_agents(), key=lambda k: k['label'].lower())
+    available_newsletter_agents = sorted(newsletters.available_newsletter_agents(), key=lambda k: k['label'].lower())
 %>
 <%def name="headIncludes()">
 </%def>
@@ -49,8 +50,9 @@
                 <li role="presentation"><a href="#tabs-homepage" aria-controls="tabs-homepage" role="tab" data-toggle="tab">Homepage</a></li>
                 <li role="presentation"><a href="#tabs-web_interface" aria-controls="tabs-web_interface" role="tab" data-toggle="tab">Web Interface</a></li>
                 <li role="presentation"><a href="#tabs-plex_media_server" aria-controls="tabs-plex_media_server" role="tab" data-toggle="tab">Plex Media Server</a></li>
-                <li role="presentation"><a href="#tabs-notifications" aria-controls="tabs-notifications" role="tab" data-toggle="tab">Notifications</a></li>
+                <li role="presentation"><a href="#tabs-notifications" aria-controls="tabs-notifications" role="tab" data-toggle="tab">Notifications & Newsletters</a></li>
                 <li role="presentation"><a href="#tabs-notification_agents" aria-controls="tabs-notification_agents" role="tab" data-toggle="tab">Notification Agents</a></li>
+                <li role="presentation"><a href="#tabs-newsletter_agents" aria-controls="tabs-newsletter_agents" role="tab" data-toggle="tab">Newsletter Agents</a></li>
                 <li role="presentation"><a href="#tabs-import_backups" aria-controls="tabs-import_backups" role="tab" data-toggle="tab">Import & Backups</a></li>
                 <li role="presentation"><a href="#tabs-android_app" aria-controls="tabs-android_app" role="tab" data-toggle="tab">Tautulli Remote Android App <sup><small>beta</small></sup></a></li>
             </ul>
@@ -267,6 +269,21 @@
 
                     <div role="tabpanel" class="tab-pane" id="tabs-homepage">
 
+                        <div class="padded-header">
+                            <h3>Activity</h3>
+                        </div>
+
+                        <div class="form-group">
+                            <label for="home_refresh_interval">Activty Refresh Interval</label>
+                            <div class="row">
+                                <div class="col-md-2">
+                                    <input type="text" class="form-control" data-parsley-type="integer" id="home_refresh_interval" name="home_refresh_interval" value="${config['home_refresh_interval']}" size="5" data-parsley-min="2" data-parsley-trigger="change" data-parsley-errors-container="#home_refresh_interval_error" required>
+                                </div>
+                                <div id="home_refresh_interval_error" class="alert alert-danger settings-alert" role="alert"></div>
+                            </div>
+                            <p class="help-block">Set the interval (in seconds) to refresh the current activity on the homepage. Minimum 2.</p>
+                        </div>
+
                         <div class="padded-header">
                             <h3>Sections</h3>
                         </div>
@@ -438,6 +455,18 @@
                             </div>
                             <p class="help-block">Port to bind web server to. Note that ports below 1024 may require root.</p>
                         </div>
+                        <div class="form-group advanced-setting">
+                            <label for="http_base_url">Public Tautulli Domain</label>
+                            <div class="row">
+                                <div class="col-md-8">
+                                    <input type="text" class="form-control" id="http_base_url" name="http_base_url" value="${config['http_base_url']}" placeholder="http://mydomain.com" data-parsley-trigger="change" data-parsley-pattern="^https?:\/\/\S+$" data-parsley-errors-container="#http_base_url_error"  data-parsley-error-message="Invalid URL">
+                                </div>
+                                <div id=http_base_url_error" class="alert alert-danger settings-alert" role="alert"></div>
+                            </div>
+                            <p class="help-block">
+                                Set your public Tautulli domain for self-hosted notification images and newsletters. (e.g. http://mydomain.com)
+                            </p>
+                        </div>
                         <div class="form-group advanced-setting">
                             <label for="http_root">HTTP Root</label>
                             <div class="row">
@@ -554,7 +583,7 @@
                             <label>
                                 <input type="checkbox" name="http_hash_password" id="http_hash_password" value="1" ${config['http_hash_password']} data-parsley-trigger="change"> Hash Password in the Config File
                             </label>
-                            <span id="hashPasswordCheck" style="color: #eb8600; padding-left: 10px;"></span>
+                            <span id="hashPasswordCheck" class="settings-warning"></span>
                             <p class="help-block">Store a hashed password in the config file.<br />Warning: Your password cannot be recovered if forgotten!</p>
                         </div>
                         <input type="text" id="http_hashed_password" name="http_hashed_password" value="${config['http_hashed_password']}" style="display: none;" data-parsley-trigger="change" data-parsley-type="integer" data-parsley-range="[0, 1]"
@@ -572,14 +601,14 @@
                             <label>
                                 <input type="checkbox" class="auth-settings" name="http_plex_admin" id="http_plex_admin" value="1" ${config['http_plex_admin']} data-parsley-trigger="change"> Allow Plex Admin
                             </label>
-                            <span id="allowPlexCheck" style="color: #eb8600; padding-left: 10px;"></span>
+                            <span id="allowPlexCheck" class="settings-warning"></span>
                             <p class="help-block">Allow the Plex server admin to login as a Tautulli admin using their Plex.tv account.</p>
                         </div>
                         <div class="checkbox">
                             <label>
                                 <input type="checkbox" id="allow_guest_access" name="allow_guest_access" value="1" ${config['allow_guest_access']}> Allow Guest Access to Tautulli
                             </label>
-                            <span id="allowGuestCheck" style="color: #eb8600; padding-left: 10px;"></span>
+                            <span id="allowGuestCheck" class="settings-warning"></span>
                             <p class="help-block">Allow shared users to login to Tautulli using their Plex.tv account. Individual user access needs to be enabled from Users > Edit Mode.</p>
                         </div>
 
@@ -666,12 +695,7 @@
                             <label for="pms_url">Plex Server URL</label>
                             <div class="row">
                                 <div class="col-md-9">
-                                    <div class="input-group">
-                                        <input type="text" class="form-control" id="pms_url" name="pms_url" value="${config['pms_url']}" size="30" readonly>
-                                        <span class="input-group-btn">
-                                            <button class="btn btn-form" type="button" id="test_pms_url_button">Test URL</button>
-                                        </span>
-                                    </div>
+                                    <input type="text" class="form-control" id="pms_url" name="pms_url" value="${config['pms_url']}" size="30" readonly>
                                 </div>
                             </div>
                             <p class="help-block">
@@ -690,7 +714,7 @@
                             <div class="row">
                                 <div class="col-md-9">
                                     <div class="input-group">
-                                        <input type="text" class="form-control" id="pms_web_url" name="pms_web_url" value="${config['pms_web_url']}" size="30" data-parsley-trigger="change" data-parsley-pattern="^https?:\/\/\S+$|^https:\/\/app.plex.tv\/desktop$" data-parsley-errors-container="#pms_web_url_error"  data-parsley-error-message="Invalid Plex Web URL.">
+                                        <input type="text" class="form-control" id="pms_web_url" name="pms_web_url" value="${config['pms_web_url']}" size="30" data-parsley-trigger="change" data-parsley-pattern="^https?:\/\/\S+$|^https:\/\/app.plex.tv\/desktop$" data-parsley-errors-container="#pms_web_url_error"  data-parsley-error-message="Invalid Plex Web URL">
                                         <span class="input-group-btn">
                                             <button class="btn btn-form" type="button" id="test_pms_web_button">Test URL</button>
                                         </span>
@@ -766,7 +790,7 @@
                                 <input type="checkbox" id="monitor_remote_access" name="monitor_remote_access" value="1" ${config['monitor_remote_access']}> Monitor Plex Remote Access
                             </label>
                             <span id="cloudMonitorRemoteAccess" style="display: none; color: #eb8600; padding-left: 10px;"> Not available for Plex Cloud servers.</span>
-                            <span id="remoteAccessCheck" style="color: #eb8600; padding-left: 10px;"></span>
+                            <span id="remoteAccessCheck" class="settings-warning"></span>
                             <p class="help-block">Enable to have Tautulli check if remote access to the Plex Media Server goes down.</p>
                         </div>
 
@@ -912,7 +936,7 @@
                         </div>
                         <!--<div class="checkbox">
                             <label>
-                                <input type="checkbox" name="notify_recently_added_upgrade" id="notify_recently_added_upgrade" value="1" ${config['notify_recently_added_upgrade']}> Send a Notification for New Versions <span style="color: #eb8600; padding-left: 10px;">[Not working]</span>
+                                <input type="checkbox" name="notify_recently_added_upgrade" id="notify_recently_added_upgrade" value="1" ${config['notify_recently_added_upgrade']}> Send a Notification for New Versions <span class="settings-warning">[Not working]</span>
                             </label>
                             <p class="help-block">
                                 Enable to send another recently added notification when adding a new version of existing media.<br />
@@ -921,16 +945,38 @@
                         </div>-->
 
                         <div class="padded-header">
-                            <h3>3rd Party APIs</h3>
+                            <h3>Newsletters</h3>
                         </div>
 
                         <div class="checkbox">
                             <label>
-                                <input type="checkbox" name="notify_upload_posters" id="notify_upload_posters" value="1" ${config['notify_upload_posters']}> Upload Posters to Imgur for Notifications
+                                <input type="checkbox" id="newsletter_self_hosted" name="newsletter_self_hosted" value="1" ${config['newsletter_self_hosted']}> Self-Hosted Newsletters
                             </label>
-                            <p class="help-block">Enable to upload Plex posters to Imgur for notifications. Disable if posters are not being used to save bandwidth.</p>
+                            <p class="help-block">Enable to host newsletters on your own domain. This will generate a link to an HTML page where you can view the newsletter.</p>
                         </div>
-                        <div id="imgur_upload_options">
+                        <div id="self_host_newsletter_options" style="overlfow: hidden; display: ${'block' if config['newsletter_self_hosted'] == 'checked' else 'none'}">
+                            <p class="help-block" id="self_host_newsletter_message">Note: The <span class="inline-pre">${http_root}newsletter</span> endpoint on your domain must be publicly accessible from the internet.</p>
+                            <p class="help-block settings-warning base-url-warning">Warning: Public Tautulli domain not set under <a data-tab-destination="tabs-web_interface" data-target="#http_base_url">Web Interface</a>.</p>
+                        </div>
+
+                        <div class="padded-header">
+                            <h3>3rd Party APIs</h3>
+                        </div>
+
+                        <div class="form-group">
+                            <label for="notify_upload_posters">Image Hosting</label>
+                            <div class="row">
+                                <div class="col-md-6">
+                                    <select class="form-control" id="notify_upload_posters" name="notify_upload_posters">
+                                        <option value="0" ${'selected' if config['notify_upload_posters'] == 0 else ''}>Disabled</option>
+                                        <option value="1" ${'selected' if config['notify_upload_posters'] == 1 else ''}>Imgur</option>
+                                        <option value="2" ${'selected' if config['notify_upload_posters'] == 2 else ''}>Self-hosted on public Tautulli domain</option>
+                                    </select>
+                                </div>
+                            </div>
+                            <p class="help-block">Select where to host Plex images for notifications and newsletters.</p>
+                        </div>
+                        <div id="imgur_upload_options" style="overlfow: hidden; display: ${'none' if config['notify_upload_posters'] != 1 else 'block'}">
                             <div class="form-group">
                                 <label for="imgur_client_id">Imgur Client ID</label>
                                 <div class="row">
@@ -940,9 +986,14 @@
                                 </div>
                                 <p class="help-block">
                                     Enter your Imgur API client ID in order to upload posters.
-                                    You can register a new application <a href="${anon_url('https://api.imgur.com/oauth2/addclient')}" target="_blank">here</a>.<br />
+                                    You can register a new application <a href="${anon_url('https://api.imgur.com/oauth2/addclient')}" target="_blank">here</a>.
+                                </p>
                             </div>
                         </div>
+                        <div id="self_host_image_options" style="overlfow: hidden; display: ${'none' if config['notify_upload_posters'] != 2 else 'block'}">
+                            <p class="help-block" id="self_host_image_message">Note: The <span class="inline-pre">${http_root}image</span> endpoint on your domain must be publicly accessible from the internet.</p>
+                            <p class="help-block settings-warning base-url-warning">Warning: Public Tautulli domain not set under <a data-tab-destination="tabs-web_interface" data-target="#http_base_url">Web Interface</a>.</p>
+                        </div>
                         <div class="checkbox">
                             <label>
                                 <input type="checkbox" name="themoviedb_lookup" id="themoviedb_lookup" value="1" ${config['themoviedb_lookup']}> Lookup TheMovieDB Links
@@ -980,6 +1031,26 @@
 
                     </div>
 
+                    <div role="tabpanel" class="tab-pane" id="tabs-newsletter_agents">
+
+                        <div class="padded-header">
+                            <h3>Newsletter Agents</h3>
+                        </div>
+
+                        <p class="help-block">
+                            Add a new newsletter agent, or configure an existing newsletter agent by clicking the settings icon on the right.
+                        </p>
+                        <p class="help-block settings-warning" id="newsletter_upload_warning">
+                            Note: Either <a data-tab-destination="tabs-notifications" data-target="#notify_upload_posters">Image Hosting</a> on Imgur or <a data-tab-destination="tabs-notifications" data-target="#newsletter_self_hosted">Self-Hosted Newsletters</a> must be enabled.</span>
+                        </p>
+                        <br/>
+                        <div id="plexpy-newsletters-table">
+                            <div class='text-muted'><i class="fa fa-refresh fa-spin"></i> Loading newsletter agents...</div>
+                            <br>
+                        </div>
+
+                    </div>
+
                     <div role="tabpanel" class="tab-pane" id="tabs-import_backups">
 
                         <div class="padded-header">
@@ -1024,6 +1095,17 @@
                             <h3>Directories</h3>
                         </div>
 
+                        <div class="form-group">
+                            <label for="log_dir">Log Directory</label>
+                            <div class="row">
+                                <div class="col-md-6">
+                                    <input type="text" class="form-control directory-settings" id="log_dir" name="log_dir" value="${config['log_dir']}">
+                                    <div class="btn-group">
+                                        <button class="btn btn-form" type="button" id="clear_logs">Clear Logs</button>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
                         <div class="form-group">
                             <label for="backup_dir">Backup Directory</label>
                             <div class="row">
@@ -1049,13 +1131,10 @@
                             </div>
                         </div>
                         <div class="form-group">
-                            <label for="log_dir">Log Directory</label>
+                            <label for="newsletter_dir">Newsletter Directory</label>
                             <div class="row">
                                 <div class="col-md-6">
-                                    <input type="text" class="form-control directory-settings" id="log_dir" name="log_dir" value="${config['log_dir']}">
-                                    <div class="btn-group">
-                                        <button class="btn btn-form" type="button" id="clear_logs">Clear Logs</button>
-                                    </div>
+                                    <input type="text" class="form-control directory-settings" id="newsletter_dir" name="newsletter_dir" value="${config['newsletter_dir']}">
                                 </div>
                             </div>
                         </div>
@@ -1082,7 +1161,7 @@
                         <p class="form-group">
                             <label>Registered Devices</label>
                             <p class="help-block">Register a new device using a QR code, or configure an existing device by clicking the settings icon on the right.</p>
-                            <p id="app_api_msg" style="color: #eb8600;">The API must be enabled under <a data-tab-destination="tabs-web_interface" style="cursor: pointer;">Web Interface</a> to use the app.</p>
+                            <p id="app_api_msg" style="color: #eb8600;">The API must be enabled under <a data-tab-destination="tabs-web_interface" data-target="#api_enabled">Web Interface</a> to use the app.</p>
                             <div class="row">
                                 <div id="plexpy-mobile-devices-table" class="col-md-12">
                                     <div class='text-muted'><i class="fa fa-refresh fa-spin"></i> Loading registered devices...</div>
@@ -1249,7 +1328,36 @@
         </div>
     </div>
 </div>
+<div id="add-newsletter-modal" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="add-newsletter-modal">
+    <div class="modal-dialog" role="document">
+        <div class="modal-content">
+            <div class="modal-header">
+                <button type="button" class="close" data-dismiss="modal" aria-hidden="true"><i class="fa fa-remove"></i></button>
+                <h4 class="modal-title">Add a Newsletter Agent</h4>
+            </div>
+            <div class="modal-body">
+                <div class="container-fluid">
+                    <div class="row">
+                        <div class="col-md-12">
+                            <ul class="stacked-configs list-unstyled">
+                                % for agent in available_newsletter_agents:
+                                <li class="new-newsletter-agent" data-id="${agent['id']}">
+                                    <span>${agent['label']}</span>
+                                </li>
+                                % endfor
+                            </ul>
+                        </div>
+                    </div>
+                </div>
+            </div>
+            <div class="modal-footer">
+                <input type="button" class="btn btn-bright" data-dismiss="modal" value="Cancel">
+            </div>
+        </div>
+    </div>
+</div>
 <div id="notifier-config-modal" class="modal fade wide" tabindex="-1" role="dialog" aria-labelledby="notifier-config-modal"></div>
+<div id="newsletter-config-modal" class="modal fade wide" tabindex="-1" role="dialog" aria-labelledby="newsletter-config-modal"></div>
 <div id="notify-text-sub-modal" class="modal fade wide" tabindex="-1" role="dialog" aria-labelledby="notify-text-sub-modal">
     <div class="modal-dialog" role="document">
         <div class="modal-content">
@@ -1405,6 +1513,53 @@
 </div>
 <div id="notifier-text-preview-modal" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="notifier-text-preview-modal">
 </div>
+<div id="newsletter-text-sub-modal" class="modal fade wide" tabindex="-1" role="dialog" aria-labelledby="newsletter-text-sub-modal">
+    <div class="modal-dialog" role="document">
+        <div class="modal-content">
+            <div class="modal-header">
+                <button type="button" class="close" data-dismiss="modal" aria-hidden="true">
+                    <i class="fa fa-remove"></i>
+                </button>
+                <h4 class="modal-title">Newsletter Parameters</h4>
+            </div>
+            <div class="modal-body">
+                <div>
+                    <p class="help-block">
+                        If the value for a selected parameter cannot be provided, it will display as blank.
+                    </p>
+                    % for category in common.NEWSLETTER_PARAMETERS:
+                    <table class="notification-params">
+                        <thead>
+                            <tr>
+                                <th colspan="2">
+                                    ${category['category']}
+                                </th>
+                            </tr>
+                        </thead>
+                        <tbody>
+                            % for parameter in category['parameters']:
+                            <tr>
+                                <td><strong>{${parameter['value']}}</strong></td>
+                                <td>
+                                    ${parameter['description']}
+                                    % if parameter.get('example'):
+                                    <span class="small-muted">(${parameter['example']})</span>
+                                    % endif
+                                    % if parameter.get('help_text'):
+                                    <p class="small-muted">(${parameter['help_text']})</p>
+                                    % endif
+                                </td>
+                            </tr>
+                            % endfor
+                        </tbody>
+                    </table>
+                    % endfor
+                </div>
+            </div>
+            <div class="modal-footer"></div>
+        </div>
+    </div>
+</div>
 <div id="changelog-modal" class="modal fade wide" tabindex="-1" role="dialog" aria-labelledby="changelog-modal">
     <div class="modal-dialog" role="document">
         <div class="modal-content">
@@ -1539,6 +1694,29 @@
         });
     }
 
+    function getNewslettersTable() {
+        $.ajax({
+            url: 'get_newsletters_table',
+            cache: false,
+            async: true,
+            complete: function(xhr, status) {
+                $("#plexpy-newsletters-table").html(xhr.responseText);
+            }
+        });
+    }
+
+    function loadNewsletterConfig(newsletter_id) {
+        $.ajax({
+            url: 'get_newsletter_config_modal',
+            data: { newsletter_id: newsletter_id },
+            cache: false,
+            async: true,
+            complete: function (xhr, status) {
+                $("#newsletter-config-modal").html(xhr.responseText).modal('show');
+            }
+        });
+    }
+
     function getMobileDevicesTable() {
         $.ajax({
             url: 'get_mobile_devices_table',
@@ -1611,6 +1789,7 @@ $(document).ready(function() {
         getConfigurationTable();
         getSchedulerTable();
         getNotifiersTable();
+        getNewslettersTable();
         getMobileDevicesTable();
         loadUpdateDistros();
         settingsChanged = false;
@@ -1647,9 +1826,9 @@ $(document).ready(function() {
     initConfigCheckbox('#enable_https');
     initConfigCheckbox('#https_create_cert');
     initConfigCheckbox('#check_github');
-    initConfigCheckbox('#notify_upload_posters');
     initConfigCheckbox('#monitor_pms_updates');
-    
+    initConfigCheckbox('#newsletter_self_hosted');
+
     $('#menu_link_shutdown').click(function() {
         $('#confirm-message').text("Are you sure you want to shutdown Tautulli?");
         $('#confirm-modal').modal();
@@ -1694,6 +1873,7 @@ $(document).ready(function() {
     getConfigurationTable();
     getSchedulerTable();
     getNotifiersTable();
+    getNewslettersTable();
     getMobileDevicesTable();
 
     $('#changelog-modal-link').on('click', function (e) {
@@ -1861,6 +2041,9 @@ $(document).ready(function() {
             $('#pms_url_manual').prop('checked', false);
             $('#pms_url').val('Please verify your server above to retrieve the URL');
             PMSCloudCheck();
+        },
+        onDropdownOpen: function() {
+            this.clear();
         }
     });
     var select_pms = $select_pms[0].selectize;
@@ -1934,11 +2117,11 @@ $(document).ready(function() {
                 data: {
                     hostname: pms_ip,
                     port: pms_port,
-                    identifier: pms_identifier,
                     ssl: pms_ssl,
                     remote: pms_is_remote,
                     manual: pms_url_manual,
-                    get_url: serverChanged
+                    get_url: true,
+                    test_websocket: true
                 },
                 cache: true,
                 async: true,
@@ -1951,15 +2134,23 @@ $(document).ready(function() {
                     var result = xhr;
                     var identifier = result.identifier;
                     var url = result.url;
+                    var ws = result.ws;
                     if (identifier) {
                         $("#pms_identifier").val(identifier);
+
                         if (url) {
                             $("#pms_url").val(url);
                         }
-                        $("#pms_verify").html('<i class="fa fa-check"></i>').fadeIn('fast');
-                        $("#pms_ip_group").removeClass("has-error");
 
-                        serverChanged = false;
+                        if (ws === false) {
+                            $("#pms_verify").html('<i class="fa fa-close"></i>').fadeIn('fast');
+                            $("#pms_ip_group").addClass("has-error");
+                            showMsg('<i class="fa fa-exclamation-circle"></i> Server found but unable to connect websocket.<br>Check the <a href="logs">logs</a> for errors.', false, true, 5000, true)
+                        } else {
+                            $("#pms_verify").html('<i class="fa fa-check"></i>').fadeIn('fast');
+                            $("#pms_ip_group").removeClass("has-error");
+                            serverChanged = false;
+                        }
 
                         if (_callback) {
                             _callback();
@@ -1987,13 +2178,6 @@ $(document).ready(function() {
         $("#pms_web_url").val(pms_web_url || 'https://app.plex.tv/desktop');
     }
 
-    $('#test_pms_url_button').on('click', function(){
-        var pms_url = $.trim($("#pms_url").val());
-        if (pms_url.startsWith('http')) {
-            window.open(pms_url + '/web', '_blank');
-        }
-    });
-
     $('#test_pms_web_button').on('click', function(){
         var pms_web_url = $.trim($("#pms_web_url").val());
         window.open(pms_web_url, '_blank');
@@ -2307,6 +2491,32 @@ $(document).ready(function() {
         });
     });
 
+    // Add a new newsletter agent
+    $('.new-newsletter-agent').click(function () {
+        $.ajax({
+            url: 'add_newsletter_config',
+            data: { agent_id: $(this).data('id') },
+            cache: false,
+            async: true,
+            complete: function (xhr, status) {
+                var result = $.parseJSON(xhr.responseText);
+                var msg = result.message;
+                $('#add-newsletter-modal').modal('hide');
+                if (result.result == 'success') {
+                    showMsg('<i class="fa fa-check"></i> ' + msg, false, true, 5000);
+                    loadNewsletterConfig(result.newsletter_id);
+                } else {
+                    showMsg('<i class="fa fa-times"></i> ' + msg, false, true, 5000, true);
+                }
+                getNewslettersTable();
+            }
+        });
+    });
+
+    $('#http_base_url').change(function () {
+       $(this).val($(this).val().replace(/\/*$/, ''));
+    });
+
     function apiEnabled() {
         var api_enabled = $('#api_enabled').prop('checked');
         $('#app_api_msg').toggle(!(api_enabled));
@@ -2316,9 +2526,62 @@ $(document).ready(function() {
         apiEnabled();
     });
 
+    function imageUpload() {
+        var upload_val = $('#notify_upload_posters').val();
+        if (upload_val === '1') {
+            $('#imgur_upload_options').slideDown();
+        } else {
+            $('#imgur_upload_options').slideUp();
+        }
+        if (upload_val === '2') {
+            $('#self_host_image_options').slideDown();
+        } else {
+            $('#self_host_image_options').slideUp();
+        }
+    }
+    $('#notify_upload_posters').change(function () {
+        imageUpload();
+    });
+
+    function baseURLSet() {
+        if ($('#http_base_url').val()) {
+            $('.base-url-warning').hide();
+        } else {
+            $('.base-url-warning').show();
+        }
+    }
+    baseURLSet();
+
+    $('#http_base_url').change(function () {
+       baseURLSet();
+    });
+
+    function newsletterUploadEnabled() {
+        if ($('#notify_upload_posters').val() === '1' || $('#newsletter_self_hosted').is(':checked')) {
+            $('#newsletter_upload_warning').hide();
+        } else {
+            $('#newsletter_upload_warning').show();
+        }
+    }
+    newsletterUploadEnabled();
+
+    $('#notify_upload_posters, #newsletter_self_hosted').change(function () {
+        baseURLSet();
+        newsletterUploadEnabled();
+    });
+
     $('body').on('click', 'a[data-tab-destination]', function () {
         var tab = $(this).data('tab-destination');
         $("a[href=#" + tab + "]").click();
+        var scroll_destination = $(this).data('target');
+        if (scroll_destination) {
+            if ($(scroll_destination).closest('.advanced-setting').length && !$('#menu_link_show_advanced_settings').hasClass('active')) {
+                $('#menu_link_show_advanced_settings').click()
+            }
+            var body_container = $('.body-container')
+            var scroll_pos = scroll_destination ? body_container.scrollTop() + $(scroll_destination).offset().top - 100 : 0;
+            body_container.animate({scrollTop: scroll_pos});
+        }
     });
 });
 </script>

data/interfaces/default/sync.html

@@ -100,7 +100,7 @@
         // Load user ids and names (for the selector)
         $.ajax({
             url: 'get_user_names',
-            type: 'get',
+            type: 'GET',
             dataType: 'json',
             success: function (data) {
                 var select = $('#sync-user');
@@ -116,7 +116,8 @@
 
         function loadSyncTable(selected_user_id) {
             sync_table_options.ajax = {
-                url: 'get_sync?user_id=' + selected_user_id
+                url: 'get_sync?user_id=' + selected_user_id,
+                type: 'POST'
             };
             sync_table = $('#sync_table').DataTable(sync_table_options);
             var colvis = new $.fn.dataTable.ColVis(sync_table, {

data/interfaces/default/user.html

@@ -413,7 +413,7 @@ DOCUMENTATION :: END
         // Build watch history table
         history_table_options.ajax = {
             url: 'get_history',
-            type: 'post',
+            type: 'POST',
             data: function ( d ) {
                 return {
                     json_data: JSON.stringify( d ),
@@ -442,7 +442,8 @@ DOCUMENTATION :: END
     function loadSyncTable() {
         // Build user sync table
         sync_table_options.ajax = {
-             url: 'get_sync?user_id=' + user_id
+             url: 'get_sync?user_id=' + user_id,
+            type: 'POST'
         };
         sync_table = $('#sync_table-UID-${data["user_id"]}').DataTable(sync_table_options);
         sync_table.column(2).visible(false);
@@ -457,7 +458,7 @@ DOCUMENTATION :: END
         // Build user IP table
         user_ip_table_options.ajax = {
             url: 'get_user_ips',
-            type: 'post',
+            type: 'POST',
             data: function ( d ) {
                 return {
                     json_data: JSON.stringify( d ),
@@ -474,6 +475,7 @@ DOCUMENTATION :: END
         // Build user login table
         login_log_table_options.ajax = {
             url: 'get_user_logins',
+            type: 'POST',
             data: function(d) {
                 return {
                     json_data: JSON.stringify(d),

data/interfaces/default/users.html

@@ -94,7 +94,7 @@
                     json_data: JSON.stringify(d)
                 };
             }
-        }
+        };
 
         users_list_table = $('#users_list_table').DataTable(users_list_table_options);
         var colvis = new $.fn.dataTable.ColVis(users_list_table, { buttonText: '<i class="fa fa-columns"></i> Select columns', buttonClass: 'btn btn-dark', exclude: [0, 1] });

data/interfaces/default/welcome.html

@@ -374,6 +374,9 @@ $(document).ready(function() {
                 $('#pms_is_remote_checkbox').prop('disabled', false);
                 $('#pms_ssl_checkbox').prop('disabled', false);
             }
+        },
+        onDropdownOpen: function() {
+            this.clear();
         }
     });
     var select_pms = $select_pms[0].selectize;

lib/apscheduler/__init__.py

@@ -1,5 +1,10 @@
-version_info = (3, 0, 1)
-version = '3.0.1'
-release = '3.0.1'
+from pkg_resources import get_distribution, DistributionNotFound
 
-__version__ = release  # PEP 396
+try:
+    release = get_distribution('APScheduler').version.split('-')[0]
+except DistributionNotFound:
+    release = '3.5.0'
+
+version_info = tuple(int(x) if x.isdigit() else x for x in release.split('.'))
+version = __version__ = '.'.join(str(x) for x in version_info[:3])
+del get_distribution, DistributionNotFound

lib/apscheduler/events.py

@@ -1,25 +1,33 @@
-__all__ = ('EVENT_SCHEDULER_START', 'EVENT_SCHEDULER_SHUTDOWN', 'EVENT_EXECUTOR_ADDED', 'EVENT_EXECUTOR_REMOVED',
-           'EVENT_JOBSTORE_ADDED', 'EVENT_JOBSTORE_REMOVED', 'EVENT_ALL_JOBS_REMOVED', 'EVENT_JOB_ADDED',
-           'EVENT_JOB_REMOVED', 'EVENT_JOB_MODIFIED', 'EVENT_JOB_EXECUTED', 'EVENT_JOB_ERROR', 'EVENT_JOB_MISSED',
+__all__ = ('EVENT_SCHEDULER_STARTED', 'EVENT_SCHEDULER_SHUTDOWN', 'EVENT_SCHEDULER_PAUSED',
+           'EVENT_SCHEDULER_RESUMED', 'EVENT_EXECUTOR_ADDED', 'EVENT_EXECUTOR_REMOVED',
+           'EVENT_JOBSTORE_ADDED', 'EVENT_JOBSTORE_REMOVED', 'EVENT_ALL_JOBS_REMOVED',
+           'EVENT_JOB_ADDED', 'EVENT_JOB_REMOVED', 'EVENT_JOB_MODIFIED', 'EVENT_JOB_EXECUTED',
+           'EVENT_JOB_ERROR', 'EVENT_JOB_MISSED', 'EVENT_JOB_SUBMITTED', 'EVENT_JOB_MAX_INSTANCES',
            'SchedulerEvent', 'JobEvent', 'JobExecutionEvent')
 
 
-EVENT_SCHEDULER_START = 1
-EVENT_SCHEDULER_SHUTDOWN = 2
-EVENT_EXECUTOR_ADDED = 4
-EVENT_EXECUTOR_REMOVED = 8
-EVENT_JOBSTORE_ADDED = 16
-EVENT_JOBSTORE_REMOVED = 32
-EVENT_ALL_JOBS_REMOVED = 64
-EVENT_JOB_ADDED = 128
-EVENT_JOB_REMOVED = 256
-EVENT_JOB_MODIFIED = 512
-EVENT_JOB_EXECUTED = 1024
-EVENT_JOB_ERROR = 2048
-EVENT_JOB_MISSED = 4096
-EVENT_ALL = (EVENT_SCHEDULER_START | EVENT_SCHEDULER_SHUTDOWN | EVENT_JOBSTORE_ADDED | EVENT_JOBSTORE_REMOVED |
+EVENT_SCHEDULER_STARTED = EVENT_SCHEDULER_START = 2 ** 0
+EVENT_SCHEDULER_SHUTDOWN = 2 ** 1
+EVENT_SCHEDULER_PAUSED = 2 ** 2
+EVENT_SCHEDULER_RESUMED = 2 ** 3
+EVENT_EXECUTOR_ADDED = 2 ** 4
+EVENT_EXECUTOR_REMOVED = 2 ** 5
+EVENT_JOBSTORE_ADDED = 2 ** 6
+EVENT_JOBSTORE_REMOVED = 2 ** 7
+EVENT_ALL_JOBS_REMOVED = 2 ** 8
+EVENT_JOB_ADDED = 2 ** 9
+EVENT_JOB_REMOVED = 2 ** 10
+EVENT_JOB_MODIFIED = 2 ** 11
+EVENT_JOB_EXECUTED = 2 ** 12
+EVENT_JOB_ERROR = 2 ** 13
+EVENT_JOB_MISSED = 2 ** 14
+EVENT_JOB_SUBMITTED = 2 ** 15
+EVENT_JOB_MAX_INSTANCES = 2 ** 16
+EVENT_ALL = (EVENT_SCHEDULER_STARTED | EVENT_SCHEDULER_SHUTDOWN | EVENT_SCHEDULER_PAUSED |
+             EVENT_SCHEDULER_RESUMED | EVENT_EXECUTOR_ADDED | EVENT_EXECUTOR_REMOVED |
+             EVENT_JOBSTORE_ADDED | EVENT_JOBSTORE_REMOVED | EVENT_ALL_JOBS_REMOVED |
              EVENT_JOB_ADDED | EVENT_JOB_REMOVED | EVENT_JOB_MODIFIED | EVENT_JOB_EXECUTED |
-             EVENT_JOB_ERROR | EVENT_JOB_MISSED)
+             EVENT_JOB_ERROR | EVENT_JOB_MISSED | EVENT_JOB_SUBMITTED | EVENT_JOB_MAX_INSTANCES)
 
 
 class SchedulerEvent(object):
@@ -55,9 +63,21 @@ class JobEvent(SchedulerEvent):
         self.jobstore = jobstore
 
 
+class JobSubmissionEvent(JobEvent):
+    """
+    An event that concerns the submission of a job to its executor.
+
+    :ivar scheduled_run_times: a list of datetimes when the job was intended to run
+    """
+
+    def __init__(self, code, job_id, jobstore, scheduled_run_times):
+        super(JobSubmissionEvent, self).__init__(code, job_id, jobstore)
+        self.scheduled_run_times = scheduled_run_times
+
+
 class JobExecutionEvent(JobEvent):
     """
-    An event that concerns the execution of individual jobs.
+    An event that concerns the running of a job within its executor.
 
     :ivar scheduled_run_time: the time when the job was scheduled to be run
     :ivar retval: the return value of the successfully executed job
@@ -65,7 +85,8 @@ class JobExecutionEvent(JobEvent):
     :ivar traceback: a formatted traceback for the exception
     """
 
-    def __init__(self, code, job_id, jobstore, scheduled_run_time, retval=None, exception=None, traceback=None):
+    def __init__(self, code, job_id, jobstore, scheduled_run_time, retval=None, exception=None,
+                 traceback=None):
         super(JobExecutionEvent, self).__init__(code, job_id, jobstore)
         self.scheduled_run_time = scheduled_run_time
         self.retval = retval

lib/apscheduler/executors/asyncio.py

@@ -1,28 +1,60 @@
 from __future__ import absolute_import
+
 import sys
 
 from apscheduler.executors.base import BaseExecutor, run_job
 
+try:
+    from asyncio import iscoroutinefunction
+    from apscheduler.executors.base_py3 import run_coroutine_job
+except ImportError:
+    from trollius import iscoroutinefunction
+    run_coroutine_job = None
+
 
 class AsyncIOExecutor(BaseExecutor):
     """
     Runs jobs in the default executor of the event loop.
 
+    If the job function is a native coroutine function, it is scheduled to be run directly in the
+    event loop as soon as possible. All other functions are run in the event loop's default
+    executor which is usually a thread pool.
+
     Plugin alias: ``asyncio``
     """
 
     def start(self, scheduler, alias):
         super(AsyncIOExecutor, self).start(scheduler, alias)
         self._eventloop = scheduler._eventloop
+        self._pending_futures = set()
+
+    def shutdown(self, wait=True):
+        # There is no way to honor wait=True without converting this method into a coroutine method
+        for f in self._pending_futures:
+            if not f.done():
+                f.cancel()
+
+        self._pending_futures.clear()
 
     def _do_submit_job(self, job, run_times):
         def callback(f):
+            self._pending_futures.discard(f)
             try:
                 events = f.result()
-            except:
+            except BaseException:
                 self._run_job_error(job.id, *sys.exc_info()[1:])
             else:
                 self._run_job_success(job.id, events)
 
-        f = self._eventloop.run_in_executor(None, run_job, job, job._jobstore_alias, run_times, self._logger.name)
+        if iscoroutinefunction(job.func):
+            if run_coroutine_job is not None:
+                coro = run_coroutine_job(job, job._jobstore_alias, run_times, self._logger.name)
+                f = self._eventloop.create_task(coro)
+            else:
+                raise Exception('Executing coroutine based jobs is not supported with Trollius')
+        else:
+            f = self._eventloop.run_in_executor(None, run_job, job, job._jobstore_alias, run_times,
+                                                self._logger.name)
+
         f.add_done_callback(callback)
+        self._pending_futures.add(f)

lib/apscheduler/executors/base.py

@@ -8,13 +8,15 @@ import sys
 from pytz import utc
 import six
 
-from apscheduler.events import JobExecutionEvent, EVENT_JOB_MISSED, EVENT_JOB_ERROR, EVENT_JOB_EXECUTED
+from apscheduler.events import (
+    JobExecutionEvent, EVENT_JOB_MISSED, EVENT_JOB_ERROR, EVENT_JOB_EXECUTED)
 
 
 class MaxInstancesReachedError(Exception):
     def __init__(self, job):
         super(MaxInstancesReachedError, self).__init__(
-            'Job "%s" has already reached its maximum number of instances (%d)' % (job.id, job.max_instances))
+            'Job "%s" has already reached its maximum number of instances (%d)' %
+            (job.id, job.max_instances))
 
 
 class BaseExecutor(six.with_metaclass(ABCMeta, object)):
@@ -30,13 +32,14 @@ class BaseExecutor(six.with_metaclass(ABCMeta, object)):
 
     def start(self, scheduler, alias):
         """
-        Called by the scheduler when the scheduler is being started or when the executor is being added to an already
-        running scheduler.
+        Called by the scheduler when the scheduler is being started or when the executor is being
+        added to an already running scheduler.
 
-        :param apscheduler.schedulers.base.BaseScheduler scheduler: the scheduler that is starting this executor
+        :param apscheduler.schedulers.base.BaseScheduler scheduler: the scheduler that is starting
+            this executor
         :param str|unicode alias: alias of this executor as it was assigned to the scheduler
-        """
 
+        """
         self._scheduler = scheduler
         self._lock = scheduler._create_lock()
         self._logger = logging.getLogger('apscheduler.executors.%s' % alias)
@@ -45,7 +48,8 @@ class BaseExecutor(six.with_metaclass(ABCMeta, object)):
         """
         Shuts down this executor.
 
-        :param bool wait: ``True`` to wait until all submitted jobs have been executed
+        :param bool wait: ``True`` to wait until all submitted jobs
+            have been executed
         """
 
     def submit_job(self, job, run_times):
@@ -53,10 +57,12 @@ class BaseExecutor(six.with_metaclass(ABCMeta, object)):
         Submits job for execution.
 
         :param Job job: job to execute
-        :param list[datetime] run_times: list of datetimes specifying when the job should have been run
-        :raises MaxInstancesReachedError: if the maximum number of allowed instances for this job has been reached
-        """
+        :param list[datetime] run_times: list of datetimes specifying
+            when the job should have been run
+        :raises MaxInstancesReachedError: if the maximum number of
+            allowed instances for this job has been reached
 
+        """
         assert self._lock is not None, 'This executor has not been started yet'
         with self._lock:
             if self._instances[job.id] >= job.max_instances:
@@ -70,50 +76,71 @@ class BaseExecutor(six.with_metaclass(ABCMeta, object)):
         """Performs the actual task of scheduling `run_job` to be called."""
 
     def _run_job_success(self, job_id, events):
-        """Called by the executor with the list of generated events when `run_job` has been successfully called."""
+        """
+        Called by the executor with the list of generated events when :func:`run_job` has been
+        successfully called.
 
+        """
         with self._lock:
             self._instances[job_id] -= 1
+            if self._instances[job_id] == 0:
+                del self._instances[job_id]
 
         for event in events:
             self._scheduler._dispatch_event(event)
 
     def _run_job_error(self, job_id, exc, traceback=None):
-        """Called by the executor with the exception if there is an error calling `run_job`."""
-
+        """Called by the executor with the exception if there is an error  calling `run_job`."""
         with self._lock:
             self._instances[job_id] -= 1
+            if self._instances[job_id] == 0:
+                del self._instances[job_id]
 
         exc_info = (exc.__class__, exc, traceback)
         self._logger.error('Error running job %s', job_id, exc_info=exc_info)
 
 
 def run_job(job, jobstore_alias, run_times, logger_name):
-    """Called by executors to run the job. Returns a list of scheduler events to be dispatched by the scheduler."""
+    """
+    Called by executors to run the job. Returns a list of scheduler events to be dispatched by the
+    scheduler.
 
+    """
     events = []
     logger = logging.getLogger(logger_name)
     for run_time in run_times:
-        # See if the job missed its run time window, and handle possible misfires accordingly
+        # See if the job missed its run time window, and handle
+        # possible misfires accordingly
         if job.misfire_grace_time is not None:
             difference = datetime.now(utc) - run_time
             grace_time = timedelta(seconds=job.misfire_grace_time)
             if difference > grace_time:
-                events.append(JobExecutionEvent(EVENT_JOB_MISSED, job.id, jobstore_alias, run_time))
+                events.append(JobExecutionEvent(EVENT_JOB_MISSED, job.id, jobstore_alias,
+                                                run_time))
                 logger.warning('Run time of job "%s" was missed by %s', job, difference)
                 continue
 
         logger.info('Running job "%s" (scheduled at %s)', job, run_time)
         try:
             retval = job.func(*job.args, **job.kwargs)
-        except:
+        except BaseException:
             exc, tb = sys.exc_info()[1:]
             formatted_tb = ''.join(format_tb(tb))
-            events.append(JobExecutionEvent(EVENT_JOB_ERROR, job.id, jobstore_alias, run_time, exception=exc,
-                                            traceback=formatted_tb))
+            events.append(JobExecutionEvent(EVENT_JOB_ERROR, job.id, jobstore_alias, run_time,
+                                            exception=exc, traceback=formatted_tb))
             logger.exception('Job "%s" raised an exception', job)
+
+            # This is to prevent cyclic references that would lead to memory leaks
+            if six.PY2:
+                sys.exc_clear()
+                del tb
+            else:
+                import traceback
+                traceback.clear_frames(tb)
+                del tb
         else:
-            events.append(JobExecutionEvent(EVENT_JOB_EXECUTED, job.id, jobstore_alias, run_time, retval=retval))
+            events.append(JobExecutionEvent(EVENT_JOB_EXECUTED, job.id, jobstore_alias, run_time,
+                                            retval=retval))
             logger.info('Job "%s" executed successfully', job)
 
     return events

lib/apscheduler/executors/base_py3.py

@@ -0,0 +1,41 @@
+import logging
+import sys
+from datetime import datetime, timedelta
+from traceback import format_tb
+
+from pytz import utc
+
+from apscheduler.events import (
+    JobExecutionEvent, EVENT_JOB_MISSED, EVENT_JOB_ERROR, EVENT_JOB_EXECUTED)
+
+
+async def run_coroutine_job(job, jobstore_alias, run_times, logger_name):
+    """Coroutine version of run_job()."""
+    events = []
+    logger = logging.getLogger(logger_name)
+    for run_time in run_times:
+        # See if the job missed its run time window, and handle possible misfires accordingly
+        if job.misfire_grace_time is not None:
+            difference = datetime.now(utc) - run_time
+            grace_time = timedelta(seconds=job.misfire_grace_time)
+            if difference > grace_time:
+                events.append(JobExecutionEvent(EVENT_JOB_MISSED, job.id, jobstore_alias,
+                                                run_time))
+                logger.warning('Run time of job "%s" was missed by %s', job, difference)
+                continue
+
+        logger.info('Running job "%s" (scheduled at %s)', job, run_time)
+        try:
+            retval = await job.func(*job.args, **job.kwargs)
+        except BaseException:
+            exc, tb = sys.exc_info()[1:]
+            formatted_tb = ''.join(format_tb(tb))
+            events.append(JobExecutionEvent(EVENT_JOB_ERROR, job.id, jobstore_alias, run_time,
+                                            exception=exc, traceback=formatted_tb))
+            logger.exception('Job "%s" raised an exception', job)
+        else:
+            events.append(JobExecutionEvent(EVENT_JOB_EXECUTED, job.id, jobstore_alias, run_time,
+                                            retval=retval))
+            logger.info('Job "%s" executed successfully', job)
+
+    return events

lib/apscheduler/executors/debug.py

@@ -5,7 +5,8 @@ from apscheduler.executors.base import BaseExecutor, run_job
 
 class DebugExecutor(BaseExecutor):
     """
-    A special executor that executes the target callable directly instead of deferring it to a thread or process.
+    A special executor that executes the target callable directly instead of deferring it to a
+    thread or process.
 
     Plugin alias: ``debug``
     """
@@ -13,7 +14,7 @@ class DebugExecutor(BaseExecutor):
     def _do_submit_job(self, job, run_times):
         try:
             events = run_job(job, job._jobstore_alias, run_times, self._logger.name)
-        except:
+        except BaseException:
             self._run_job_error(job.id, *sys.exc_info()[1:])
         else:
             self._run_job_success(job.id, events)

lib/apscheduler/executors/gevent.py

@@ -21,9 +21,10 @@ class GeventExecutor(BaseExecutor):
         def callback(greenlet):
             try:
                 events = greenlet.get()
-            except:
+            except BaseException:
                 self._run_job_error(job.id, *sys.exc_info()[1:])
             else:
                 self._run_job_success(job.id, events)
 
-        gevent.spawn(run_job, job, job._jobstore_alias, run_times, self._logger.name).link(callback)
+        gevent.spawn(run_job, job, job._jobstore_alias, run_times, self._logger.name).\
+            link(callback)

lib/apscheduler/executors/tornado.py

@@ -0,0 +1,54 @@
+from __future__ import absolute_import
+
+import sys
+from concurrent.futures import ThreadPoolExecutor
+
+from tornado.gen import convert_yielded
+
+from apscheduler.executors.base import BaseExecutor, run_job
+
+try:
+    from inspect import iscoroutinefunction
+    from apscheduler.executors.base_py3 import run_coroutine_job
+except ImportError:
+    def iscoroutinefunction(func):
+        return False
+
+
+class TornadoExecutor(BaseExecutor):
+    """
+    Runs jobs either in a thread pool or directly on the I/O loop.
+
+    If the job function is a native coroutine function, it is scheduled to be run directly in the
+    I/O loop as soon as possible. All other functions are run in a thread pool.
+
+    Plugin alias: ``tornado``
+
+    :param int max_workers: maximum number of worker threads in the thread pool
+    """
+
+    def __init__(self, max_workers=10):
+        super(TornadoExecutor, self).__init__()
+        self.executor = ThreadPoolExecutor(max_workers)
+
+    def start(self, scheduler, alias):
+        super(TornadoExecutor, self).start(scheduler, alias)
+        self._ioloop = scheduler._ioloop
+
+    def _do_submit_job(self, job, run_times):
+        def callback(f):
+            try:
+                events = f.result()
+            except BaseException:
+                self._run_job_error(job.id, *sys.exc_info()[1:])
+            else:
+                self._run_job_success(job.id, events)
+
+        if iscoroutinefunction(job.func):
+            f = run_coroutine_job(job, job._jobstore_alias, run_times, self._logger.name)
+        else:
+            f = self.executor.submit(run_job, job, job._jobstore_alias, run_times,
+                                     self._logger.name)
+
+        f = convert_yielded(f)
+        f.add_done_callback(callback)

lib/apscheduler/executors/twisted.py

@@ -21,5 +21,5 @@ class TwistedExecutor(BaseExecutor):
             else:
                 self._run_job_error(job.id, result.value, result.tb)
 
-        self._reactor.getThreadPool().callInThreadWithCallback(callback, run_job, job, job._jobstore_alias, run_times,
-                                                               self._logger.name)
+        self._reactor.getThreadPool().callInThreadWithCallback(
+            callback, run_job, job, job._jobstore_alias, run_times, self._logger.name)

lib/apscheduler/job.py

@@ -4,8 +4,9 @@ from uuid import uuid4
 import six
 
 from apscheduler.triggers.base import BaseTrigger
-from apscheduler.util import ref_to_obj, obj_to_ref, datetime_repr, repr_escape, get_callable_name, check_callable_args, \
-    convert_to_datetime
+from apscheduler.util import (
+    ref_to_obj, obj_to_ref, datetime_repr, repr_escape, get_callable_name, check_callable_args,
+    convert_to_datetime)
 
 
 class Job(object):
@@ -21,13 +22,20 @@ class Job(object):
     :var bool coalesce: whether to only run the job once when several run times are due
     :var trigger: the trigger object that controls the schedule of this job
     :var str executor: the name of the executor that will run this job
-    :var int misfire_grace_time: the time (in seconds) how much this job's execution is allowed to be late
-    :var int max_instances: the maximum number of concurrently executing instances allowed for this job
+    :var int misfire_grace_time: the time (in seconds) how much this job's execution is allowed to
+        be late
+    :var int max_instances: the maximum number of concurrently executing instances allowed for this
+        job
     :var datetime.datetime next_run_time: the next scheduled run time of this job
+
+    .. note::
+        The ``misfire_grace_time`` has some non-obvious effects on job execution. See the
+        :ref:`missed-job-executions` section in the documentation for an in-depth explanation.
     """
 
-    __slots__ = ('_scheduler', '_jobstore_alias', 'id', 'trigger', 'executor', 'func', 'func_ref', 'args', 'kwargs',
-                 'name', 'misfire_grace_time', 'coalesce', 'max_instances', 'next_run_time')
+    __slots__ = ('_scheduler', '_jobstore_alias', 'id', 'trigger', 'executor', 'func', 'func_ref',
+                 'args', 'kwargs', 'name', 'misfire_grace_time', 'coalesce', 'max_instances',
+                 'next_run_time')
 
     def __init__(self, scheduler, id=None, **kwargs):
         super(Job, self).__init__()
@@ -38,53 +46,69 @@ class Job(object):
     def modify(self, **changes):
         """
         Makes the given changes to this job and saves it in the associated job store.
+
         Accepted keyword arguments are the same as the variables on this class.
 
         .. seealso:: :meth:`~apscheduler.schedulers.base.BaseScheduler.modify_job`
-        """
 
+        :return Job: this job instance
+
+        """
         self._scheduler.modify_job(self.id, self._jobstore_alias, **changes)
+        return self
 
     def reschedule(self, trigger, **trigger_args):
         """
         Shortcut for switching the trigger on this job.
 
         .. seealso:: :meth:`~apscheduler.schedulers.base.BaseScheduler.reschedule_job`
-        """
 
+        :return Job: this job instance
+
+        """
         self._scheduler.reschedule_job(self.id, self._jobstore_alias, trigger, **trigger_args)
+        return self
 
     def pause(self):
         """
         Temporarily suspend the execution of this job.
 
         .. seealso:: :meth:`~apscheduler.schedulers.base.BaseScheduler.pause_job`
-        """
 
+        :return Job: this job instance
+
+        """
         self._scheduler.pause_job(self.id, self._jobstore_alias)
+        return self
 
     def resume(self):
         """
         Resume the schedule of this job if previously paused.
 
         .. seealso:: :meth:`~apscheduler.schedulers.base.BaseScheduler.resume_job`
-        """
 
+        :return Job: this job instance
+
+        """
         self._scheduler.resume_job(self.id, self._jobstore_alias)
+        return self
 
     def remove(self):
         """
         Unschedules this job and removes it from its associated job store.
 
         .. seealso:: :meth:`~apscheduler.schedulers.base.BaseScheduler.remove_job`
-        """
 
+        """
         self._scheduler.remove_job(self.id, self._jobstore_alias)
 
     @property
     def pending(self):
-        """Returns ``True`` if the referenced job is still waiting to be added to its designated job store."""
+        """
+        Returns ``True`` if the referenced job is still waiting to be added to its designated job
+        store.
 
+        """
         return self._jobstore_alias is None
 
     #
@@ -97,8 +121,8 @@ class Job(object):
 
         :type now: datetime.datetime
         :rtype: list[datetime.datetime]
-        """
 
+        """
         run_times = []
         next_run_time = self.next_run_time
         while next_run_time and next_run_time <= now:
@@ -108,8 +132,11 @@ class Job(object):
         return run_times
 
     def _modify(self, **changes):
-        """Validates the changes to the Job and makes the modifications if and only if all of them validate."""
+        """
+        Validates the changes to the Job and makes the modifications if and only if all of them
+        validate.
 
+        """
         approved = {}
 
         if 'id' in changes:
@@ -125,7 +152,7 @@ class Job(object):
             args = changes.pop('args') if 'args' in changes else self.args
             kwargs = changes.pop('kwargs') if 'kwargs' in changes else self.kwargs
 
-            if isinstance(func, str):
+            if isinstance(func, six.string_types):
                 func_ref = func
                 func = ref_to_obj(func)
             elif callable(func):
@@ -177,7 +204,8 @@ class Job(object):
         if 'trigger' in changes:
             trigger = changes.pop('trigger')
             if not isinstance(trigger, BaseTrigger):
-                raise TypeError('Expected a trigger instance, got %s instead' % trigger.__class__.__name__)
+                raise TypeError('Expected a trigger instance, got %s instead' %
+                                trigger.__class__.__name__)
 
             approved['trigger'] = trigger
 
@@ -189,10 +217,12 @@ class Job(object):
 
         if 'next_run_time' in changes:
             value = changes.pop('next_run_time')
-            approved['next_run_time'] = convert_to_datetime(value, self._scheduler.timezone, 'next_run_time')
+            approved['next_run_time'] = convert_to_datetime(value, self._scheduler.timezone,
+                                                            'next_run_time')
 
         if changes:
-            raise AttributeError('The following are not modifiable attributes of Job: %s' % ', '.join(changes))
+            raise AttributeError('The following are not modifiable attributes of Job: %s' %
+                                 ', '.join(changes))
 
         for key, value in six.iteritems(approved):
             setattr(self, key, value)
@@ -200,9 +230,10 @@ class Job(object):
     def __getstate__(self):
         # Don't allow this Job to be serialized if the function reference could not be determined
         if not self.func_ref:
-            raise ValueError('This Job cannot be serialized since the reference to its callable (%r) could not be '
-                             'determined. Consider giving a textual reference (module:function name) instead.' %
-                             (self.func,))
+            raise ValueError(
+                'This Job cannot be serialized since the reference to its callable (%r) could not '
+                'be determined. Consider giving a textual reference (module:function name) '
+                'instead.' % (self.func,))
 
         return {
             'version': 1,
@@ -221,7 +252,8 @@ class Job(object):
 
     def __setstate__(self, state):
         if state.get('version', 1) > 1:
-            raise ValueError('Job has version %s, but only version 1 can be handled' % state['version'])
+            raise ValueError('Job has version %s, but only version 1 can be handled' %
+                             state['version'])
 
         self.id = state['id']
         self.func_ref = state['func']
@@ -245,8 +277,13 @@ class Job(object):
         return '<Job (id=%s name=%s)>' % (repr_escape(self.id), repr_escape(self.name))
 
     def __str__(self):
-        return '%s (trigger: %s, next run at: %s)' % (repr_escape(self.name), repr_escape(str(self.trigger)),
-                                                      datetime_repr(self.next_run_time))
+        return repr_escape(self.__unicode__())
 
     def __unicode__(self):
-        return six.u('%s (trigger: %s, next run at: %s)') % (self.name, self.trigger, datetime_repr(self.next_run_time))
+        if hasattr(self, 'next_run_time'):
+            status = ('next run at: ' + datetime_repr(self.next_run_time) if
+                      self.next_run_time else 'paused')
+        else:
+            status = 'pending'
+
+        return u'%s (trigger: %s, %s)' % (self.name, self.trigger, status)

lib/apscheduler/jobstores/base.py

@@ -8,23 +8,27 @@ class JobLookupError(KeyError):
     """Raised when the job store cannot find a job for update or removal."""
 
     def __init__(self, job_id):
-        super(JobLookupError, self).__init__(six.u('No job by the id of %s was found') % job_id)
+        super(JobLookupError, self).__init__(u'No job by the id of %s was found' % job_id)
 
 
 class ConflictingIdError(KeyError):
     """Raised when the uniqueness of job IDs is being violated."""
 
     def __init__(self, job_id):
-        super(ConflictingIdError, self).__init__(six.u('Job identifier (%s) conflicts with an existing job') % job_id)
+        super(ConflictingIdError, self).__init__(
+            u'Job identifier (%s) conflicts with an existing job' % job_id)
 
 
 class TransientJobError(ValueError):
-    """Raised when an attempt to add transient (with no func_ref) job to a persistent job store is detected."""
+    """
+    Raised when an attempt to add transient (with no func_ref) job to a persistent job store is
+    detected.
+    """
 
     def __init__(self, job_id):
         super(TransientJobError, self).__init__(
-            six.u('Job (%s) cannot be added to this job store because a reference to the callable could not be '
-                  'determined.') % job_id)
+            u'Job (%s) cannot be added to this job store because a reference to the callable '
+            u'could not be determined.' % job_id)
 
 
 class BaseJobStore(six.with_metaclass(ABCMeta)):
@@ -36,10 +40,11 @@ class BaseJobStore(six.with_metaclass(ABCMeta)):
 
     def start(self, scheduler, alias):
         """
-        Called by the scheduler when the scheduler is being started or when the job store is being added to an already
-        running scheduler.
+        Called by the scheduler when the scheduler is being started or when the job store is being
+        added to an already running scheduler.
 
-        :param apscheduler.schedulers.base.BaseScheduler scheduler: the scheduler that is starting this job store
+        :param apscheduler.schedulers.base.BaseScheduler scheduler: the scheduler that is starting
+            this job store
         :param str|unicode alias: alias of this job store as it was assigned to the scheduler
         """
 
@@ -50,13 +55,22 @@ class BaseJobStore(six.with_metaclass(ABCMeta)):
     def shutdown(self):
         """Frees any resources still bound to this job store."""
 
+    def _fix_paused_jobs_sorting(self, jobs):
+        for i, job in enumerate(jobs):
+            if job.next_run_time is not None:
+                if i > 0:
+                    paused_jobs = jobs[:i]
+                    del jobs[:i]
+                    jobs.extend(paused_jobs)
+                break
+
     @abstractmethod
     def lookup_job(self, job_id):
         """
         Returns a specific job, or ``None`` if it isn't found..
 
-        The job store is responsible for setting the ``scheduler`` and ``jobstore`` attributes of the returned job to
-        point to the scheduler and itself, respectively.
+        The job store is responsible for setting the ``scheduler`` and ``jobstore`` attributes of
+        the returned job to point to the scheduler and itself, respectively.
 
         :param str|unicode job_id: identifier of the job
         :rtype: Job
@@ -75,7 +89,8 @@ class BaseJobStore(six.with_metaclass(ABCMeta)):
     @abstractmethod
     def get_next_run_time(self):
         """
-        Returns the earliest run time of all the jobs stored in this job store, or ``None`` if there are no active jobs.
+        Returns the earliest run time of all the jobs stored in this job store, or ``None`` if
+        there are no active jobs.
 
         :rtype: datetime.datetime
         """
@@ -83,11 +98,12 @@ class BaseJobStore(six.with_metaclass(ABCMeta)):
     @abstractmethod
     def get_all_jobs(self):
         """
-        Returns a list of all jobs in this job store. The returned jobs should be sorted by next run time (ascending).
-        Paused jobs (next_run_time is None) should be sorted last.
+        Returns a list of all jobs in this job store.
+        The returned jobs should be sorted by next run time (ascending).
+        Paused jobs (next_run_time == None) should be sorted last.
 
-        The job store is responsible for setting the ``scheduler`` and ``jobstore`` attributes of the returned jobs to
-        point to the scheduler and itself, respectively.
+        The job store is responsible for setting the ``scheduler`` and ``jobstore`` attributes of
+        the returned jobs to point to the scheduler and itself, respectively.
 
         :rtype: list[Job]
         """

lib/apscheduler/jobstores/memory.py

@@ -13,7 +13,8 @@ class MemoryJobStore(BaseJobStore):
 
     def __init__(self):
         super(MemoryJobStore, self).__init__()
-        self._jobs = []  # list of (job, timestamp), sorted by next_run_time and job id (ascending)
+        # list of (job, timestamp), sorted by next_run_time and job id (ascending)
+        self._jobs = []
         self._jobs_index = {}  # id -> (job, timestamp) lookup table
 
     def lookup_job(self, job_id):
@@ -80,13 +81,13 @@ class MemoryJobStore(BaseJobStore):
 
     def _get_job_index(self, timestamp, job_id):
         """
-        Returns the index of the given job, or if it's not found, the index where the job should be inserted based on
-        the given timestamp.
+        Returns the index of the given job, or if it's not found, the index where the job should be
+        inserted based on the given timestamp.
 
         :type timestamp: int
         :type job_id: str
-        """
 
+        """
         lo, hi = 0, len(self._jobs)
         timestamp = float('inf') if timestamp is None else timestamp
         while lo < hi:

lib/apscheduler/jobstores/mongodb.py

@@ -1,4 +1,5 @@
 from __future__ import absolute_import
+import warnings
 
 from apscheduler.jobstores.base import BaseJobStore, JobLookupError, ConflictingIdError
 from apscheduler.util import maybe_ref, datetime_to_utc_timestamp, utc_timestamp_to_datetime
@@ -19,16 +20,18 @@ except ImportError:  # pragma: nocover
 
 class MongoDBJobStore(BaseJobStore):
     """
-    Stores jobs in a MongoDB database. Any leftover keyword arguments are directly passed to pymongo's `MongoClient
+    Stores jobs in a MongoDB database. Any leftover keyword arguments are directly passed to
+    pymongo's `MongoClient
     <http://api.mongodb.org/python/current/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`_.
 
     Plugin alias: ``mongodb``
 
     :param str database: database to store jobs in
     :param str collection: collection to store jobs in
-    :param client: a :class:`~pymongo.mongo_client.MongoClient` instance to use instead of providing connection
-                   arguments
-    :param int pickle_protocol: pickle protocol level to use (for serialization), defaults to the highest available
+    :param client: a :class:`~pymongo.mongo_client.MongoClient` instance to use instead of
+        providing connection arguments
+    :param int pickle_protocol: pickle protocol level to use (for serialization), defaults to the
+        highest available
     """
 
     def __init__(self, database='apscheduler', collection='jobs', client=None,
@@ -42,14 +45,23 @@ class MongoDBJobStore(BaseJobStore):
             raise ValueError('The "collection" parameter must not be empty')
 
         if client:
-            self.connection = maybe_ref(client)
+            self.client = maybe_ref(client)
         else:
             connect_args.setdefault('w', 1)
-            self.connection = MongoClient(**connect_args)
+            self.client = MongoClient(**connect_args)
 
-        self.collection = self.connection[database][collection]
+        self.collection = self.client[database][collection]
+
+    def start(self, scheduler, alias):
+        super(MongoDBJobStore, self).start(scheduler, alias)
         self.collection.ensure_index('next_run_time', sparse=True)
 
+    @property
+    def connection(self):
+        warnings.warn('The "connection" member is deprecated -- use "client" instead',
+                      DeprecationWarning)
+        return self.client
+
     def lookup_job(self, job_id):
         document = self.collection.find_one(job_id, ['job_state'])
         return self._reconstitute_job(document['job_state']) if document else None
@@ -59,12 +71,15 @@ class MongoDBJobStore(BaseJobStore):
         return self._get_jobs({'next_run_time': {'$lte': timestamp}})
 
     def get_next_run_time(self):
-        document = self.collection.find_one({'next_run_time': {'$ne': None}}, fields=['next_run_time'],
+        document = self.collection.find_one({'next_run_time': {'$ne': None}},
+                                            projection=['next_run_time'],
                                             sort=[('next_run_time', ASCENDING)])
         return utc_timestamp_to_datetime(document['next_run_time']) if document else None
 
     def get_all_jobs(self):
-        return self._get_jobs({})
+        jobs = self._get_jobs({})
+        self._fix_paused_jobs_sorting(jobs)
+        return jobs
 
     def add_job(self, job):
         try:
@@ -83,7 +98,7 @@ class MongoDBJobStore(BaseJobStore):
         }
         result = self.collection.update({'_id': job.id}, {'$set': changes})
         if result and result['n'] == 0:
-            raise JobLookupError(id)
+            raise JobLookupError(job.id)
 
     def remove_job(self, job_id):
         result = self.collection.remove(job_id)
@@ -94,7 +109,7 @@ class MongoDBJobStore(BaseJobStore):
         self.collection.remove()
 
     def shutdown(self):
-        self.connection.disconnect()
+        self.client.close()
 
     def _reconstitute_job(self, job_state):
         job_state = pickle.loads(job_state)
@@ -107,11 +122,13 @@ class MongoDBJobStore(BaseJobStore):
     def _get_jobs(self, conditions):
         jobs = []
         failed_job_ids = []
-        for document in self.collection.find(conditions, ['_id', 'job_state'], sort=[('next_run_time', ASCENDING)]):
+        for document in self.collection.find(conditions, ['_id', 'job_state'],
+                                             sort=[('next_run_time', ASCENDING)]):
             try:
                 jobs.append(self._reconstitute_job(document['job_state']))
-            except:
-                self._logger.exception('Unable to restore job "%s" -- removing it', document['_id'])
+            except BaseException:
+                self._logger.exception('Unable to restore job "%s" -- removing it',
+                                       document['_id'])
                 failed_job_ids.append(document['_id'])
 
         # Remove all the jobs we failed to restore
@@ -121,4 +138,4 @@ class MongoDBJobStore(BaseJobStore):
         return jobs
 
     def __repr__(self):
-        return '<%s (client=%s)>' % (self.__class__.__name__, self.connection)
+        return '<%s (client=%s)>' % (self.__class__.__name__, self.client)

lib/apscheduler/jobstores/redis.py

@@ -1,5 +1,7 @@
 from __future__ import absolute_import
+from datetime import datetime
 
+from pytz import utc
 import six
 
 from apscheduler.jobstores.base import BaseJobStore, JobLookupError, ConflictingIdError
@@ -19,14 +21,16 @@ except ImportError:  # pragma: nocover
 
 class RedisJobStore(BaseJobStore):
     """
-    Stores jobs in a Redis database. Any leftover keyword arguments are directly passed to redis's StrictRedis.
+    Stores jobs in a Redis database. Any leftover keyword arguments are directly passed to redis's
+    :class:`~redis.StrictRedis`.
 
     Plugin alias: ``redis``
 
     :param int db: the database number to store jobs in
     :param str jobs_key: key to store jobs in
     :param str run_times_key: key to store the jobs' run times in
-    :param int pickle_protocol: pickle protocol level to use (for serialization), defaults to the highest available
+    :param int pickle_protocol: pickle protocol level to use (for serialization), defaults to the
+        highest available
     """
 
     def __init__(self, db=0, jobs_key='apscheduler.jobs', run_times_key='apscheduler.run_times',
@@ -65,7 +69,8 @@ class RedisJobStore(BaseJobStore):
     def get_all_jobs(self):
         job_states = self.redis.hgetall(self.jobs_key)
         jobs = self._reconstitute_jobs(six.iteritems(job_states))
-        return sorted(jobs, key=lambda job: job.next_run_time)
+        paused_sort_key = datetime(9999, 12, 31, tzinfo=utc)
+        return sorted(jobs, key=lambda job: job.next_run_time or paused_sort_key)
 
     def add_job(self, job):
         if self.redis.hexists(self.jobs_key, job.id):
@@ -73,8 +78,10 @@ class RedisJobStore(BaseJobStore):
 
         with self.redis.pipeline() as pipe:
             pipe.multi()
-            pipe.hset(self.jobs_key, job.id, pickle.dumps(job.__getstate__(), self.pickle_protocol))
-            pipe.zadd(self.run_times_key, datetime_to_utc_timestamp(job.next_run_time), job.id)
+            pipe.hset(self.jobs_key, job.id, pickle.dumps(job.__getstate__(),
+                                                          self.pickle_protocol))
+            if job.next_run_time:
+                pipe.zadd(self.run_times_key, datetime_to_utc_timestamp(job.next_run_time), job.id)
             pipe.execute()
 
     def update_job(self, job):
@@ -82,7 +89,8 @@ class RedisJobStore(BaseJobStore):
             raise JobLookupError(job.id)
 
         with self.redis.pipeline() as pipe:
-            pipe.hset(self.jobs_key, job.id, pickle.dumps(job.__getstate__(), self.pickle_protocol))
+            pipe.hset(self.jobs_key, job.id, pickle.dumps(job.__getstate__(),
+                                                          self.pickle_protocol))
             if job.next_run_time:
                 pipe.zadd(self.run_times_key, datetime_to_utc_timestamp(job.next_run_time), job.id)
             else:
@@ -121,7 +129,7 @@ class RedisJobStore(BaseJobStore):
         for job_id, job_state in job_states:
             try:
                 jobs.append(self._reconstitute_job(job_state))
-            except:
+            except BaseException:
                 self._logger.exception('Unable to restore job "%s" -- removing it', job_id)
                 failed_job_ids.append(job_id)
 

lib/apscheduler/jobstores/rethinkdb.py

@@ -0,0 +1,153 @@
+from __future__ import absolute_import
+
+from apscheduler.jobstores.base import BaseJobStore, JobLookupError, ConflictingIdError
+from apscheduler.util import maybe_ref, datetime_to_utc_timestamp, utc_timestamp_to_datetime
+from apscheduler.job import Job
+
+try:
+    import cPickle as pickle
+except ImportError:  # pragma: nocover
+    import pickle
+
+try:
+    import rethinkdb as r
+except ImportError:  # pragma: nocover
+    raise ImportError('RethinkDBJobStore requires rethinkdb installed')
+
+
+class RethinkDBJobStore(BaseJobStore):
+    """
+    Stores jobs in a RethinkDB database. Any leftover keyword arguments are directly passed to
+    rethinkdb's `RethinkdbClient <http://www.rethinkdb.com/api/#connect>`_.
+
+    Plugin alias: ``rethinkdb``
+
+    :param str database: database to store jobs in
+    :param str collection: collection to store jobs in
+    :param client: a :class:`rethinkdb.net.Connection` instance to use instead of providing
+        connection arguments
+    :param int pickle_protocol: pickle protocol level to use (for serialization), defaults to the
+        highest available
+    """
+
+    def __init__(self, database='apscheduler', table='jobs', client=None,
+                 pickle_protocol=pickle.HIGHEST_PROTOCOL, **connect_args):
+        super(RethinkDBJobStore, self).__init__()
+
+        if not database:
+            raise ValueError('The "database" parameter must not be empty')
+        if not table:
+            raise ValueError('The "table" parameter must not be empty')
+
+        self.database = database
+        self.table = table
+        self.client = client
+        self.pickle_protocol = pickle_protocol
+        self.connect_args = connect_args
+        self.conn = None
+
+    def start(self, scheduler, alias):
+        super(RethinkDBJobStore, self).start(scheduler, alias)
+
+        if self.client:
+            self.conn = maybe_ref(self.client)
+        else:
+            self.conn = r.connect(db=self.database, **self.connect_args)
+
+        if self.database not in r.db_list().run(self.conn):
+            r.db_create(self.database).run(self.conn)
+
+        if self.table not in r.table_list().run(self.conn):
+            r.table_create(self.table).run(self.conn)
+
+        if 'next_run_time' not in r.table(self.table).index_list().run(self.conn):
+            r.table(self.table).index_create('next_run_time').run(self.conn)
+
+        self.table = r.db(self.database).table(self.table)
+
+    def lookup_job(self, job_id):
+        results = list(self.table.get_all(job_id).pluck('job_state').run(self.conn))
+        return self._reconstitute_job(results[0]['job_state']) if results else None
+
+    def get_due_jobs(self, now):
+        return self._get_jobs(r.row['next_run_time'] <= datetime_to_utc_timestamp(now))
+
+    def get_next_run_time(self):
+        results = list(
+            self.table
+            .filter(r.row['next_run_time'] != None)  # flake8: noqa
+            .order_by(r.asc('next_run_time'))
+            .map(lambda x: x['next_run_time'])
+            .limit(1)
+            .run(self.conn)
+        )
+        return utc_timestamp_to_datetime(results[0]) if results else None
+
+    def get_all_jobs(self):
+        jobs = self._get_jobs()
+        self._fix_paused_jobs_sorting(jobs)
+        return jobs
+
+    def add_job(self, job):
+        job_dict = {
+            'id': job.id,
+            'next_run_time': datetime_to_utc_timestamp(job.next_run_time),
+            'job_state': r.binary(pickle.dumps(job.__getstate__(), self.pickle_protocol))
+        }
+        results = self.table.insert(job_dict).run(self.conn)
+        if results['errors'] > 0:
+            raise ConflictingIdError(job.id)
+
+    def update_job(self, job):
+        changes = {
+            'next_run_time': datetime_to_utc_timestamp(job.next_run_time),
+            'job_state': r.binary(pickle.dumps(job.__getstate__(), self.pickle_protocol))
+        }
+        results = self.table.get_all(job.id).update(changes).run(self.conn)
+        skipped = False in map(lambda x: results[x] == 0, results.keys())
+        if results['skipped'] > 0 or results['errors'] > 0 or not skipped:
+            raise JobLookupError(job.id)
+
+    def remove_job(self, job_id):
+        results = self.table.get_all(job_id).delete().run(self.conn)
+        if results['deleted'] + results['skipped'] != 1:
+            raise JobLookupError(job_id)
+
+    def remove_all_jobs(self):
+        self.table.delete().run(self.conn)
+
+    def shutdown(self):
+        self.conn.close()
+
+    def _reconstitute_job(self, job_state):
+        job_state = pickle.loads(job_state)
+        job = Job.__new__(Job)
+        job.__setstate__(job_state)
+        job._scheduler = self._scheduler
+        job._jobstore_alias = self._alias
+        return job
+
+    def _get_jobs(self, predicate=None):
+        jobs = []
+        failed_job_ids = []
+        query = (self.table.filter(r.row['next_run_time'] != None).filter(predicate) if
+                 predicate else self.table)
+        query = query.order_by('next_run_time', 'id').pluck('id', 'job_state')
+
+        for document in query.run(self.conn):
+            try:
+                jobs.append(self._reconstitute_job(document['job_state']))
+            except:
+                self._logger.exception('Unable to restore job "%s" -- removing it', document['id'])
+                failed_job_ids.append(document['id'])
+
+        # Remove all the jobs we failed to restore
+        if failed_job_ids:
+            r.expr(failed_job_ids).for_each(
+                lambda job_id: self.table.get_all(job_id).delete()).run(self.conn)
+
+        return jobs
+
+    def __repr__(self):
+        connection = self.conn
+        return '<%s (connection=%s)>' % (self.__class__.__name__, connection)

lib/apscheduler/jobstores/sqlalchemy.py

@@ -10,29 +10,38 @@ except ImportError:  # pragma: nocover
     import pickle
 
 try:
-    from sqlalchemy import create_engine, Table, Column, MetaData, Unicode, Float, LargeBinary, select
+    from sqlalchemy import (
+        create_engine, Table, Column, MetaData, Unicode, Float, LargeBinary, select)
     from sqlalchemy.exc import IntegrityError
+    from sqlalchemy.sql.expression import null
 except ImportError:  # pragma: nocover
     raise ImportError('SQLAlchemyJobStore requires SQLAlchemy installed')
 
 
 class SQLAlchemyJobStore(BaseJobStore):
     """
-    Stores jobs in a database table using SQLAlchemy. The table will be created if it doesn't exist in the database.
+    Stores jobs in a database table using SQLAlchemy.
+    The table will be created if it doesn't exist in the database.
 
     Plugin alias: ``sqlalchemy``
 
-    :param str url: connection string (see `SQLAlchemy documentation
-                    <http://docs.sqlalchemy.org/en/latest/core/engines.html?highlight=create_engine#database-urls>`_
-                    on this)
-    :param engine: an SQLAlchemy Engine to use instead of creating a new one based on ``url``
+    :param str url: connection string (see
+        :ref:`SQLAlchemy documentation <sqlalchemy:database_urls>` on this)
+    :param engine: an SQLAlchemy :class:`~sqlalchemy.engine.Engine` to use instead of creating a
+        new one based on ``url``
     :param str tablename: name of the table to store jobs in
-    :param metadata: a :class:`~sqlalchemy.MetaData` instance to use instead of creating a new one
-    :param int pickle_protocol: pickle protocol level to use (for serialization), defaults to the highest available
+    :param metadata: a :class:`~sqlalchemy.schema.MetaData` instance to use instead of creating a
+        new one
+    :param int pickle_protocol: pickle protocol level to use (for serialization), defaults to the
+        highest available
+    :param str tableschema: name of the (existing) schema in the target database where the table
+        should be
+    :param dict engine_options: keyword arguments to :func:`~sqlalchemy.create_engine`
+        (ignored if ``engine`` is given)
     """
 
     def __init__(self, url=None, engine=None, tablename='apscheduler_jobs', metadata=None,
-                 pickle_protocol=pickle.HIGHEST_PROTOCOL):
+                 pickle_protocol=pickle.HIGHEST_PROTOCOL, tableschema=None, engine_options=None):
         super(SQLAlchemyJobStore, self).__init__()
         self.pickle_protocol = pickle_protocol
         metadata = maybe_ref(metadata) or MetaData()
@@ -40,18 +49,22 @@ class SQLAlchemyJobStore(BaseJobStore):
         if engine:
             self.engine = maybe_ref(engine)
         elif url:
-            self.engine = create_engine(url)
+            self.engine = create_engine(url, **(engine_options or {}))
         else:
             raise ValueError('Need either "engine" or "url" defined')
 
-        # 191 = max key length in MySQL for InnoDB/utf8mb4 tables, 25 = precision that translates to an 8-byte float
+        # 191 = max key length in MySQL for InnoDB/utf8mb4 tables,
+        # 25 = precision that translates to an 8-byte float
         self.jobs_t = Table(
             tablename, metadata,
             Column('id', Unicode(191, _warn_on_bytestring=False), primary_key=True),
             Column('next_run_time', Float(25), index=True),
-            Column('job_state', LargeBinary, nullable=False)
+            Column('job_state', LargeBinary, nullable=False),
+            schema=tableschema
         )
 
+    def start(self, scheduler, alias):
+        super(SQLAlchemyJobStore, self).start(scheduler, alias)
         self.jobs_t.create(self.engine, True)
 
     def lookup_job(self, job_id):
@@ -64,13 +77,16 @@ class SQLAlchemyJobStore(BaseJobStore):
         return self._get_jobs(self.jobs_t.c.next_run_time <= timestamp)
 
     def get_next_run_time(self):
-        selectable = select([self.jobs_t.c.next_run_time]).where(self.jobs_t.c.next_run_time != None).\
+        selectable = select([self.jobs_t.c.next_run_time]).\
+            where(self.jobs_t.c.next_run_time != null()).\
             order_by(self.jobs_t.c.next_run_time).limit(1)
         next_run_time = self.engine.execute(selectable).scalar()
         return utc_timestamp_to_datetime(next_run_time)
 
     def get_all_jobs(self):
-        return self._get_jobs()
+        jobs = self._get_jobs()
+        self._fix_paused_jobs_sorting(jobs)
+        return jobs
 
     def add_job(self, job):
         insert = self.jobs_t.insert().values(**{
@@ -116,13 +132,14 @@ class SQLAlchemyJobStore(BaseJobStore):
 
     def _get_jobs(self, *conditions):
         jobs = []
-        selectable = select([self.jobs_t.c.id, self.jobs_t.c.job_state]).order_by(self.jobs_t.c.next_run_time)
+        selectable = select([self.jobs_t.c.id, self.jobs_t.c.job_state]).\
+            order_by(self.jobs_t.c.next_run_time)
         selectable = selectable.where(*conditions) if conditions else selectable
         failed_job_ids = set()
         for row in self.engine.execute(selectable):
             try:
                 jobs.append(self._reconstitute_job(row.job_state))
-            except:
+            except BaseException:
                 self._logger.exception('Unable to restore job "%s" -- removing it', row.id)
                 failed_job_ids.add(row.id)
 

lib/apscheduler/jobstores/zookeeper.py

@@ -0,0 +1,179 @@
+from __future__ import absolute_import
+
+import os
+from datetime import datetime
+
+from pytz import utc
+from kazoo.exceptions import NoNodeError, NodeExistsError
+
+from apscheduler.jobstores.base import BaseJobStore, JobLookupError, ConflictingIdError
+from apscheduler.util import maybe_ref, datetime_to_utc_timestamp, utc_timestamp_to_datetime
+from apscheduler.job import Job
+
+try:
+    import cPickle as pickle
+except ImportError:  # pragma: nocover
+    import pickle
+
+try:
+    from kazoo.client import KazooClient
+except ImportError:  # pragma: nocover
+    raise ImportError('ZooKeeperJobStore requires Kazoo installed')
+
+
+class ZooKeeperJobStore(BaseJobStore):
+    """
+    Stores jobs in a ZooKeeper tree. Any leftover keyword arguments are directly passed to
+    kazoo's `KazooClient
+    <http://kazoo.readthedocs.io/en/latest/api/client.html>`_.
+
+    Plugin alias: ``zookeeper``
+
+    :param str path: path to store jobs in
+    :param client: a :class:`~kazoo.client.KazooClient` instance to use instead of
+        providing connection arguments
+    :param int pickle_protocol: pickle protocol level to use (for serialization), defaults to the
+        highest available
+    """
+
+    def __init__(self, path='/apscheduler', client=None, close_connection_on_exit=False,
+                 pickle_protocol=pickle.HIGHEST_PROTOCOL, **connect_args):
+        super(ZooKeeperJobStore, self).__init__()
+        self.pickle_protocol = pickle_protocol
+        self.close_connection_on_exit = close_connection_on_exit
+
+        if not path:
+            raise ValueError('The "path" parameter must not be empty')
+
+        self.path = path
+
+        if client:
+            self.client = maybe_ref(client)
+        else:
+            self.client = KazooClient(**connect_args)
+        self._ensured_path = False
+
+    def _ensure_paths(self):
+        if not self._ensured_path:
+            self.client.ensure_path(self.path)
+        self._ensured_path = True
+
+    def start(self, scheduler, alias):
+        super(ZooKeeperJobStore, self).start(scheduler, alias)
+        if not self.client.connected:
+            self.client.start()
+
+    def lookup_job(self, job_id):
+        self._ensure_paths()
+        node_path = os.path.join(self.path, job_id)
+        try:
+            content, _ = self.client.get(node_path)
+            doc = pickle.loads(content)
+            job = self._reconstitute_job(doc['job_state'])
+            return job
+        except BaseException:
+            return None
+
+    def get_due_jobs(self, now):
+        timestamp = datetime_to_utc_timestamp(now)
+        jobs = [job_def['job'] for job_def in self._get_jobs()
+                if job_def['next_run_time'] is not None and job_def['next_run_time'] <= timestamp]
+        return jobs
+
+    def get_next_run_time(self):
+        next_runs = [job_def['next_run_time'] for job_def in self._get_jobs()
+                     if job_def['next_run_time'] is not None]
+        return utc_timestamp_to_datetime(min(next_runs)) if len(next_runs) > 0 else None
+
+    def get_all_jobs(self):
+        jobs = [job_def['job'] for job_def in self._get_jobs()]
+        self._fix_paused_jobs_sorting(jobs)
+        return jobs
+
+    def add_job(self, job):
+        self._ensure_paths()
+        node_path = os.path.join(self.path,  str(job.id))
+        value = {
+            'next_run_time': datetime_to_utc_timestamp(job.next_run_time),
+            'job_state': job.__getstate__()
+        }
+        data = pickle.dumps(value, self.pickle_protocol)
+        try:
+            self.client.create(node_path, value=data)
+        except NodeExistsError:
+            raise ConflictingIdError(job.id)
+
+    def update_job(self, job):
+        self._ensure_paths()
+        node_path = os.path.join(self.path,  str(job.id))
+        changes = {
+            'next_run_time': datetime_to_utc_timestamp(job.next_run_time),
+            'job_state': job.__getstate__()
+        }
+        data = pickle.dumps(changes, self.pickle_protocol)
+        try:
+            self.client.set(node_path, value=data)
+        except NoNodeError:
+            raise JobLookupError(job.id)
+
+    def remove_job(self, job_id):
+        self._ensure_paths()
+        node_path = os.path.join(self.path,  str(job_id))
+        try:
+            self.client.delete(node_path)
+        except NoNodeError:
+            raise JobLookupError(job_id)
+
+    def remove_all_jobs(self):
+        try:
+            self.client.delete(self.path, recursive=True)
+        except NoNodeError:
+            pass
+        self._ensured_path = False
+
+    def shutdown(self):
+        if self.close_connection_on_exit:
+            self.client.stop()
+            self.client.close()
+
+    def _reconstitute_job(self, job_state):
+        job_state = job_state
+        job = Job.__new__(Job)
+        job.__setstate__(job_state)
+        job._scheduler = self._scheduler
+        job._jobstore_alias = self._alias
+        return job
+
+    def _get_jobs(self):
+        self._ensure_paths()
+        jobs = []
+        failed_job_ids = []
+        all_ids = self.client.get_children(self.path)
+        for node_name in all_ids:
+            try:
+                node_path = os.path.join(self.path, node_name)
+                content, _ = self.client.get(node_path)
+                doc = pickle.loads(content)
+                job_def = {
+                    'job_id': node_name,
+                    'next_run_time': doc['next_run_time'] if doc['next_run_time'] else None,
+                    'job_state': doc['job_state'],
+                    'job': self._reconstitute_job(doc['job_state']),
+                    'creation_time': _.ctime
+                }
+                jobs.append(job_def)
+            except BaseException:
+                self._logger.exception('Unable to restore job "%s" -- removing it' % node_name)
+                failed_job_ids.append(node_name)
+
+        # Remove all the jobs we failed to restore
+        if failed_job_ids:
+            for failed_id in failed_job_ids:
+                self.remove_job(failed_id)
+        paused_sort_key = datetime(9999, 12, 31, tzinfo=utc)
+        return sorted(jobs, key=lambda job_def: (job_def['job'].next_run_time or paused_sort_key,
+                                                 job_def['creation_time']))
+
+    def __repr__(self):
+        self._logger.exception('<%s (client=%s)>' % (self.__class__.__name__, self.client))
+        return '<%s (client=%s)>' % (self.__class__.__name__, self.client)

lib/apscheduler/schedulers/asyncio.py

@@ -1,5 +1,5 @@
 from __future__ import absolute_import
-from functools import wraps
+from functools import wraps, partial
 
 from apscheduler.schedulers.base import BaseScheduler
 from apscheduler.util import maybe_ref
@@ -10,13 +10,15 @@ except ImportError:  # pragma: nocover
     try:
         import trollius as asyncio
     except ImportError:
-        raise ImportError('AsyncIOScheduler requires either Python 3.4 or the asyncio package installed')
+        raise ImportError(
+            'AsyncIOScheduler requires either Python 3.4 or the asyncio package installed')
 
 
 def run_in_event_loop(func):
     @wraps(func)
     def wrapper(self, *args, **kwargs):
-        self._eventloop.call_soon_threadsafe(func, self, *args, **kwargs)
+        wrapped = partial(func, self, *args, **kwargs)
+        self._eventloop.call_soon_threadsafe(wrapped)
     return wrapper
 
 
@@ -24,6 +26,8 @@ class AsyncIOScheduler(BaseScheduler):
     """
     A scheduler that runs on an asyncio (:pep:`3156`) event loop.
 
+    The default executor can run jobs based on native coroutines (``async def``).
+
     Extra options:
 
     ============== =============================================================
@@ -34,10 +38,6 @@ class AsyncIOScheduler(BaseScheduler):
     _eventloop = None
     _timeout = None
 
-    def start(self):
-        super(AsyncIOScheduler, self).start()
-        self.wakeup()
-
     @run_in_event_loop
     def shutdown(self, wait=True):
         super(AsyncIOScheduler, self).shutdown(wait)

lib/apscheduler/schedulers/background.py

@@ -1,4 +1,5 @@
 from __future__ import absolute_import
+
 from threading import Thread, Event
 
 from apscheduler.schedulers.base import BaseScheduler
@@ -13,11 +14,12 @@ class BackgroundScheduler(BlockingScheduler):
 
     Extra options:
 
-    ========== ============================================================================================
-    ``daemon`` Set the ``daemon`` option in the background thread (defaults to ``True``,
-               see `the documentation <https://docs.python.org/3.4/library/threading.html#thread-objects>`_
+    ========== =============================================================================
+    ``daemon`` Set the ``daemon`` option in the background thread (defaults to ``True``, see
+               `the documentation
+               <https://docs.python.org/3.4/library/threading.html#thread-objects>`_
                for further details)
-    ========== ============================================================================================
+    ========== =============================================================================
     """
 
     _thread = None
@@ -26,14 +28,14 @@ class BackgroundScheduler(BlockingScheduler):
         self._daemon = asbool(config.pop('daemon', True))
         super(BackgroundScheduler, self)._configure(config)
 
-    def start(self):
-        BaseScheduler.start(self)
+    def start(self, *args, **kwargs):
         self._event = Event()
+        BaseScheduler.start(self, *args, **kwargs)
         self._thread = Thread(target=self._main_loop, name='APScheduler')
         self._thread.daemon = self._daemon
         self._thread.start()
 
-    def shutdown(self, wait=True):
-        super(BackgroundScheduler, self).shutdown(wait)
+    def shutdown(self, *args, **kwargs):
+        super(BackgroundScheduler, self).shutdown(*args, **kwargs)
         self._thread.join()
         del self._thread

lib/apscheduler/schedulers/blocking.py

@@ -1,21 +1,21 @@
 from __future__ import absolute_import
+
 from threading import Event
 
-from apscheduler.schedulers.base import BaseScheduler
+from apscheduler.schedulers.base import BaseScheduler, STATE_STOPPED
+from apscheduler.util import TIMEOUT_MAX
 
 
 class BlockingScheduler(BaseScheduler):
     """
-    A scheduler that runs in the foreground (:meth:`~apscheduler.schedulers.base.BaseScheduler.start` will block).
+    A scheduler that runs in the foreground
+    (:meth:`~apscheduler.schedulers.base.BaseScheduler.start` will block).
     """
-
-    MAX_WAIT_TIME = 4294967  # Maximum value accepted by Event.wait() on Windows
-
     _event = None
 
-    def start(self):
-        super(BlockingScheduler, self).start()
+    def start(self, *args, **kwargs):
         self._event = Event()
+        super(BlockingScheduler, self).start(*args, **kwargs)
         self._main_loop()
 
     def shutdown(self, wait=True):
@@ -23,10 +23,11 @@ class BlockingScheduler(BaseScheduler):
         self._event.set()
 
     def _main_loop(self):
-        while self.running:
-            wait_seconds = self._process_jobs()
-            self._event.wait(wait_seconds if wait_seconds is not None else self.MAX_WAIT_TIME)
+        wait_seconds = TIMEOUT_MAX
+        while self.state != STATE_STOPPED:
+            self._event.wait(wait_seconds)
             self._event.clear()
+            wait_seconds = self._process_jobs()
 
     def wakeup(self):
         self._event.set()

lib/apscheduler/schedulers/gevent.py

@@ -16,14 +16,14 @@ class GeventScheduler(BlockingScheduler):
 
     _greenlet = None
 
-    def start(self):
-        BaseScheduler.start(self)
+    def start(self, *args, **kwargs):
         self._event = Event()
+        BaseScheduler.start(self, *args, **kwargs)
         self._greenlet = gevent.spawn(self._main_loop)
         return self._greenlet
 
-    def shutdown(self, wait=True):
-        super(GeventScheduler, self).shutdown(wait)
+    def shutdown(self, *args, **kwargs):
+        super(GeventScheduler, self).shutdown(*args, **kwargs)
         self._greenlet.join()
         del self._greenlet
 

lib/apscheduler/schedulers/qt.py

@@ -4,7 +4,7 @@ from apscheduler.schedulers.base import BaseScheduler
 
 try:
     from PyQt5.QtCore import QObject, QTimer
-except ImportError:  # pragma: nocover
+except (ImportError, RuntimeError):  # pragma: nocover
     try:
         from PyQt4.QtCore import QObject, QTimer
     except ImportError:
@@ -19,12 +19,8 @@ class QtScheduler(BaseScheduler):
 
     _timer = None
 
-    def start(self):
-        super(QtScheduler, self).start()
-        self.wakeup()
-
-    def shutdown(self, wait=True):
-        super(QtScheduler, self).shutdown(wait)
+    def shutdown(self, *args, **kwargs):
+        super(QtScheduler, self).shutdown(*args, **kwargs)
         self._stop_timer()
 
     def _start_timer(self, wait_seconds):

lib/apscheduler/schedulers/tornado.py

@@ -1,4 +1,5 @@
 from __future__ import absolute_import
+
 from datetime import timedelta
 from functools import wraps
 
@@ -22,6 +23,8 @@ class TornadoScheduler(BaseScheduler):
     """
     A scheduler that runs on a Tornado IOLoop.
 
+    The default executor can run jobs based on native coroutines (``async def``).
+
     =========== ===============================================================
     ``io_loop`` Tornado IOLoop instance to use (defaults to the global IO loop)
     =========== ===============================================================
@@ -30,10 +33,6 @@ class TornadoScheduler(BaseScheduler):
     _ioloop = None
     _timeout = None
 
-    def start(self):
-        super(TornadoScheduler, self).start()
-        self.wakeup()
-
     @run_in_ioloop
     def shutdown(self, wait=True):
         super(TornadoScheduler, self).shutdown(wait)
@@ -53,6 +52,10 @@ class TornadoScheduler(BaseScheduler):
             self._ioloop.remove_timeout(self._timeout)
             del self._timeout
 
+    def _create_default_executor(self):
+        from apscheduler.executors.tornado import TornadoExecutor
+        return TornadoExecutor()
+
     @run_in_ioloop
     def wakeup(self):
         self._stop_timer()

lib/apscheduler/schedulers/twisted.py

@@ -1,4 +1,5 @@
 from __future__ import absolute_import
+
 from functools import wraps
 
 from apscheduler.schedulers.base import BaseScheduler
@@ -35,10 +36,6 @@ class TwistedScheduler(BaseScheduler):
         self._reactor = maybe_ref(config.pop('reactor', default_reactor))
         super(TwistedScheduler, self)._configure(config)
 
-    def start(self):
-        super(TwistedScheduler, self).start()
-        self.wakeup()
-
     @run_in_reactor
     def shutdown(self, wait=True):
         super(TwistedScheduler, self).shutdown(wait)

lib/apscheduler/triggers/base.py

@@ -1,4 +1,6 @@
 from abc import ABCMeta, abstractmethod
+from datetime import timedelta
+import random
 
 import six
 
@@ -6,11 +8,41 @@ import six
 class BaseTrigger(six.with_metaclass(ABCMeta)):
     """Abstract base class that defines the interface that every trigger must implement."""
 
+    __slots__ = ()
+
     @abstractmethod
     def get_next_fire_time(self, previous_fire_time, now):
         """
-        Returns the next datetime to fire on, If no such datetime can be calculated, returns ``None``.
+        Returns the next datetime to fire on, If no such datetime can be calculated, returns
+        ``None``.
 
         :param datetime.datetime previous_fire_time: the previous time the trigger was fired
         :param datetime.datetime now: current datetime
         """
+
+    def _apply_jitter(self, next_fire_time, jitter, now):
+        """
+        Randomize ``next_fire_time`` by adding or subtracting a random value (the jitter). If the
+        resulting datetime is in the past, returns the initial ``next_fire_time`` without jitter.
+
+        ``next_fire_time - jitter <= result <= next_fire_time + jitter``
+
+        :param datetime.datetime|None next_fire_time: next fire time without jitter applied. If
+            ``None``, returns ``None``.
+        :param int|None jitter: maximum number of seconds to add or subtract to
+            ``next_fire_time``. If ``None`` or ``0``, returns ``next_fire_time``
+        :param datetime.datetime now: current datetime
+        :return datetime.datetime|None: next fire time with a jitter.
+        """
+        if next_fire_time is None or not jitter:
+            return next_fire_time
+
+        next_fire_time_with_jitter = next_fire_time + timedelta(
+                seconds=random.uniform(-jitter, jitter))
+
+        if next_fire_time_with_jitter < now:
+            # Next fire time with jitter is in the past.
+            # Ignore jitter to avoid false misfire.
+            return next_fire_time
+
+        return next_fire_time_with_jitter

lib/apscheduler/triggers/combining.py

@@ -0,0 +1,95 @@
+from apscheduler.triggers.base import BaseTrigger
+from apscheduler.util import obj_to_ref, ref_to_obj
+
+
+class BaseCombiningTrigger(BaseTrigger):
+    __slots__ = ('triggers', 'jitter')
+
+    def __init__(self, triggers, jitter=None):
+        self.triggers = triggers
+        self.jitter = jitter
+
+    def __getstate__(self):
+        return {
+            'version': 1,
+            'triggers': [(obj_to_ref(trigger.__class__), trigger.__getstate__())
+                         for trigger in self.triggers],
+            'jitter': self.jitter
+        }
+
+    def __setstate__(self, state):
+        if state.get('version', 1) > 1:
+            raise ValueError(
+                'Got serialized data for version %s of %s, but only versions up to 1 can be '
+                'handled' % (state['version'], self.__class__.__name__))
+
+        self.jitter = state['jitter']
+        self.triggers = []
+        for clsref, state in state['triggers']:
+            cls = ref_to_obj(clsref)
+            trigger = cls.__new__(cls)
+            trigger.__setstate__(state)
+            self.triggers.append(trigger)
+
+    def __repr__(self):
+        return '<{}({}{})>'.format(self.__class__.__name__, self.triggers,
+                                   ', jitter={}'.format(self.jitter) if self.jitter else '')
+
+
+class AndTrigger(BaseCombiningTrigger):
+    """
+    Always returns the earliest next fire time that all the given triggers can agree on.
+    The trigger is considered to be finished when any of the given triggers has finished its
+    schedule.
+
+    Trigger alias: ``and``
+
+    :param list triggers: triggers to combine
+    :param int|None jitter: advance or delay the job execution by ``jitter`` seconds at most.
+    """
+
+    __slots__ = ()
+
+    def get_next_fire_time(self, previous_fire_time, now):
+        while True:
+            fire_times = [trigger.get_next_fire_time(previous_fire_time, now)
+                          for trigger in self.triggers]
+            if None in fire_times:
+                return None
+            elif min(fire_times) == max(fire_times):
+                return self._apply_jitter(fire_times[0], self.jitter, now)
+            else:
+                now = max(fire_times)
+
+    def __str__(self):
+        return 'and[{}]'.format(', '.join(str(trigger) for trigger in self.triggers))
+
+
+class OrTrigger(BaseCombiningTrigger):
+    """
+    Always returns the earliest next fire time produced by any of the given triggers.
+    The trigger is considered finished when all the given triggers have finished their schedules.
+
+    Trigger alias: ``or``
+
+    :param list triggers: triggers to combine
+    :param int|None jitter: advance or delay the job execution by ``jitter`` seconds at most.
+
+    .. note:: Triggers that depends on the previous fire time, such as the interval trigger, may
+        seem to behave strangely since they are always passed the previous fire time produced by
+        any of the given triggers.
+    """
+
+    __slots__ = ()
+
+    def get_next_fire_time(self, previous_fire_time, now):
+        fire_times = [trigger.get_next_fire_time(previous_fire_time, now)
+                      for trigger in self.triggers]
+        fire_times = [fire_time for fire_time in fire_times if fire_time is not None]
+        if fire_times:
+            return self._apply_jitter(min(fire_times), self.jitter, now)
+        else:
+            return None
+
+    def __str__(self):
+        return 'or[{}]'.format(', '.join(str(trigger) for trigger in self.triggers))

lib/apscheduler/triggers/cron/__init__.py

@@ -4,13 +4,15 @@ from tzlocal import get_localzone
 import six
 
 from apscheduler.triggers.base import BaseTrigger
-from apscheduler.triggers.cron.fields import BaseField, WeekField, DayOfMonthField, DayOfWeekField, DEFAULT_VALUES
+from apscheduler.triggers.cron.fields import (
+    BaseField, MonthField, WeekField, DayOfMonthField, DayOfWeekField, DEFAULT_VALUES)
 from apscheduler.util import datetime_ceil, convert_to_datetime, datetime_repr, astimezone
 
 
 class CronTrigger(BaseTrigger):
     """
-    Triggers when current time matches all specified time constraints, similarly to how the UNIX cron scheduler works.
+    Triggers when current time matches all specified time constraints,
+    similarly to how the UNIX cron scheduler works.
 
     :param int|str year: 4-digit year
     :param int|str month: month (1-12)
@@ -22,8 +24,9 @@ class CronTrigger(BaseTrigger):
     :param int|str second: second (0-59)
     :param datetime|str start_date: earliest possible date/time to trigger on (inclusive)
     :param datetime|str end_date: latest possible date/time to trigger on (inclusive)
-    :param datetime.tzinfo|str timezone: time zone to use for the date/time calculations
-                                         (defaults to scheduler timezone)
+    :param datetime.tzinfo|str timezone: time zone to use for the date/time calculations (defaults
+        to scheduler timezone)
+    :param int|None jitter: advance or delay the job execution by ``jitter`` seconds at most.
 
     .. note:: The first weekday is always **monday**.
     """
@@ -31,7 +34,7 @@ class CronTrigger(BaseTrigger):
     FIELD_NAMES = ('year', 'month', 'day', 'week', 'day_of_week', 'hour', 'minute', 'second')
     FIELDS_MAP = {
         'year': BaseField,
-        'month': BaseField,
+        'month': MonthField,
         'week': WeekField,
         'day': DayOfMonthField,
         'day_of_week': DayOfWeekField,
@@ -40,15 +43,16 @@ class CronTrigger(BaseTrigger):
         'second': BaseField
     }
 
-    __slots__ = 'timezone', 'start_date', 'end_date', 'fields'
+    __slots__ = 'timezone', 'start_date', 'end_date', 'fields', 'jitter'
 
-    def __init__(self, year=None, month=None, day=None, week=None, day_of_week=None, hour=None, minute=None,
-                 second=None, start_date=None, end_date=None, timezone=None):
+    def __init__(self, year=None, month=None, day=None, week=None, day_of_week=None, hour=None,
+                 minute=None, second=None, start_date=None, end_date=None, timezone=None,
+                 jitter=None):
         if timezone:
             self.timezone = astimezone(timezone)
-        elif start_date and start_date.tzinfo:
+        elif isinstance(start_date, datetime) and start_date.tzinfo:
             self.timezone = start_date.tzinfo
-        elif end_date and end_date.tzinfo:
+        elif isinstance(end_date, datetime) and end_date.tzinfo:
             self.timezone = end_date.tzinfo
         else:
             self.timezone = get_localzone()
@@ -56,6 +60,8 @@ class CronTrigger(BaseTrigger):
         self.start_date = convert_to_datetime(start_date, self.timezone, 'start_date')
         self.end_date = convert_to_datetime(end_date, self.timezone, 'end_date')
 
+        self.jitter = jitter
+
         values = dict((key, value) for (key, value) in six.iteritems(locals())
                       if key in self.FIELD_NAMES and value is not None)
         self.fields = []
@@ -76,13 +82,35 @@ class CronTrigger(BaseTrigger):
             field = field_class(field_name, exprs, is_default)
             self.fields.append(field)
 
+    @classmethod
+    def from_crontab(cls, expr, timezone=None):
+        """
+        Create a :class:`~CronTrigger` from a standard crontab expression.
+
+        See https://en.wikipedia.org/wiki/Cron for more information on the format accepted here.
+
+        :param expr: minute, hour, day of month, month, day of week
+        :param datetime.tzinfo|str timezone: time zone to use for the date/time calculations (
+            defaults to scheduler timezone)
+        :return: a :class:`~CronTrigger` instance
+
+        """
+        values = expr.split()
+        if len(values) != 5:
+            raise ValueError('Wrong number of fields; got {}, expected 5'.format(len(values)))
+
+        return cls(minute=values[0], hour=values[1], day=values[2], month=values[3],
+                   day_of_week=values[4], timezone=timezone)
+
     def _increment_field_value(self, dateval, fieldnum):
         """
-        Increments the designated field and resets all less significant fields to their minimum values.
+        Increments the designated field and resets all less significant fields to their minimum
+        values.
 
         :type dateval: datetime
         :type fieldnum: int
-        :return: a tuple containing the new date, and the number of the field that was actually incremented
+        :return: a tuple containing the new date, and the number of the field that was actually
+            incremented
         :rtype: tuple
         """
 
@@ -128,12 +156,13 @@ class CronTrigger(BaseTrigger):
                 else:
                     values[field.name] = new_value
 
-        difference = datetime(**values) - dateval.replace(tzinfo=None)
-        return self.timezone.normalize(dateval + difference)
+        return self.timezone.localize(datetime(**values))
 
     def get_next_fire_time(self, previous_fire_time, now):
         if previous_fire_time:
-            start_date = max(now, previous_fire_time + timedelta(microseconds=1))
+            start_date = min(now, previous_fire_time + timedelta(microseconds=1))
+            if start_date == previous_fire_time:
+                start_date += timedelta(microseconds=1)
         else:
             start_date = max(now, self.start_date) if self.start_date else now
 
@@ -163,8 +192,36 @@ class CronTrigger(BaseTrigger):
                 return None
 
         if fieldnum >= 0:
+            if self.jitter is not None:
+                next_date = self._apply_jitter(next_date, self.jitter, now)
             return next_date
 
+    def __getstate__(self):
+        return {
+            'version': 2,
+            'timezone': self.timezone,
+            'start_date': self.start_date,
+            'end_date': self.end_date,
+            'fields': self.fields,
+            'jitter': self.jitter,
+        }
+
+    def __setstate__(self, state):
+        # This is for compatibility with APScheduler 3.0.x
+        if isinstance(state, tuple):
+            state = state[1]
+
+        if state.get('version', 1) > 2:
+            raise ValueError(
+                'Got serialized data for version %s of %s, but only versions up to 2 can be '
+                'handled' % (state['version'], self.__class__.__name__))
+
+        self.timezone = state['timezone']
+        self.start_date = state['start_date']
+        self.end_date = state['end_date']
+        self.fields = state['fields']
+        self.jitter = state.get('jitter')
+
     def __str__(self):
         options = ["%s='%s'" % (f.name, f) for f in self.fields if not f.is_default]
         return 'cron[%s]' % (', '.join(options))
@@ -172,5 +229,11 @@ class CronTrigger(BaseTrigger):
     def __repr__(self):
         options = ["%s='%s'" % (f.name, f) for f in self.fields if not f.is_default]
         if self.start_date:
-            options.append("start_date='%s'" % datetime_repr(self.start_date))
-        return '<%s (%s)>' % (self.__class__.__name__, ', '.join(options))
+            options.append("start_date=%r" % datetime_repr(self.start_date))
+        if self.end_date:
+            options.append("end_date=%r" % datetime_repr(self.end_date))
+        if self.jitter:
+            options.append('jitter=%s' % self.jitter)
+
+        return "<%s (%s, timezone='%s')>" % (
+            self.__class__.__name__, ', '.join(options), self.timezone)

lib/apscheduler/triggers/cron/expressions.py

@@ -1,17 +1,16 @@
-"""
-This module contains the expressions applicable for CronTrigger's fields.
-"""
+"""This module contains the expressions applicable for CronTrigger's fields."""
 
 from calendar import monthrange
 import re
 
 from apscheduler.util import asint
 
-__all__ = ('AllExpression', 'RangeExpression', 'WeekdayRangeExpression', 'WeekdayPositionExpression',
-           'LastDayOfMonthExpression')
+__all__ = ('AllExpression', 'RangeExpression', 'WeekdayRangeExpression',
+           'WeekdayPositionExpression', 'LastDayOfMonthExpression')
 
 
 WEEKDAYS = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']
+MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec']
 
 
 class AllExpression(object):
@@ -22,6 +21,14 @@ class AllExpression(object):
         if self.step == 0:
             raise ValueError('Increment must be higher than 0')
 
+    def validate_range(self, field_name):
+        from apscheduler.triggers.cron.fields import MIN_VALUES, MAX_VALUES
+
+        value_range = MAX_VALUES[field_name] - MIN_VALUES[field_name]
+        if self.step and self.step > value_range:
+            raise ValueError('the step value ({}) is higher than the total range of the '
+                             'expression ({})'.format(self.step, value_range))
+
     def get_next_value(self, date, field):
         start = field.get_value(date)
         minval = field.get_min(date)
@@ -37,6 +44,9 @@ class AllExpression(object):
         if next <= maxval:
             return next
 
+    def __eq__(self, other):
+        return isinstance(other, self.__class__) and self.step == other.step
+
     def __str__(self):
         if self.step:
             return '*/%d' % self.step
@@ -51,7 +61,7 @@ class RangeExpression(AllExpression):
         r'(?P<first>\d+)(?:-(?P<last>\d+))?(?:/(?P<step>\d+))?$')
 
     def __init__(self, first, last=None, step=None):
-        AllExpression.__init__(self, step)
+        super(RangeExpression, self).__init__(step)
         first = asint(first)
         last = asint(last)
         if last is None and step is None:
@@ -61,25 +71,41 @@ class RangeExpression(AllExpression):
         self.first = first
         self.last = last
 
+    def validate_range(self, field_name):
+        from apscheduler.triggers.cron.fields import MIN_VALUES, MAX_VALUES
+
+        super(RangeExpression, self).validate_range(field_name)
+        if self.first < MIN_VALUES[field_name]:
+            raise ValueError('the first value ({}) is lower than the minimum value ({})'
+                             .format(self.first, MIN_VALUES[field_name]))
+        if self.last is not None and self.last > MAX_VALUES[field_name]:
+            raise ValueError('the last value ({}) is higher than the maximum value ({})'
+                             .format(self.last, MAX_VALUES[field_name]))
+        value_range = (self.last or MAX_VALUES[field_name]) - self.first
+        if self.step and self.step > value_range:
+            raise ValueError('the step value ({}) is higher than the total range of the '
+                             'expression ({})'.format(self.step, value_range))
+
     def get_next_value(self, date, field):
-        start = field.get_value(date)
+        startval = field.get_value(date)
         minval = field.get_min(date)
         maxval = field.get_max(date)
 
         # Apply range limits
         minval = max(minval, self.first)
-        if self.last is not None:
-            maxval = min(maxval, self.last)
-        start = max(start, minval)
+        maxval = min(maxval, self.last) if self.last is not None else maxval
+        nextval = max(minval, startval)
 
-        if not self.step:
-            next = start
-        else:
-            distance_to_next = (self.step - (start - minval)) % self.step
-            next = start + distance_to_next
+        # Apply the step if defined
+        if self.step:
+            distance_to_next = (self.step - (nextval - minval)) % self.step
+            nextval += distance_to_next
 
-        if next <= maxval:
-            return next
+        return nextval if nextval <= maxval else None
+
+    def __eq__(self, other):
+        return (isinstance(other, self.__class__) and self.first == other.first and
+                self.last == other.last)
 
     def __str__(self):
         if self.last != self.first and self.last is not None:
@@ -100,6 +126,37 @@ class RangeExpression(AllExpression):
         return "%s(%s)" % (self.__class__.__name__, ', '.join(args))
 
 
+class MonthRangeExpression(RangeExpression):
+    value_re = re.compile(r'(?P<first>[a-z]+)(?:-(?P<last>[a-z]+))?', re.IGNORECASE)
+
+    def __init__(self, first, last=None):
+        try:
+            first_num = MONTHS.index(first.lower()) + 1
+        except ValueError:
+            raise ValueError('Invalid month name "%s"' % first)
+
+        if last:
+            try:
+                last_num = MONTHS.index(last.lower()) + 1
+            except ValueError:
+                raise ValueError('Invalid month name "%s"' % last)
+        else:
+            last_num = None
+
+        super(MonthRangeExpression, self).__init__(first_num, last_num)
+
+    def __str__(self):
+        if self.last != self.first and self.last is not None:
+            return '%s-%s' % (MONTHS[self.first - 1], MONTHS[self.last - 1])
+        return MONTHS[self.first - 1]
+
+    def __repr__(self):
+        args = ["'%s'" % MONTHS[self.first]]
+        if self.last != self.first and self.last is not None:
+            args.append("'%s'" % MONTHS[self.last - 1])
+        return "%s(%s)" % (self.__class__.__name__, ', '.join(args))
+
+
 class WeekdayRangeExpression(RangeExpression):
     value_re = re.compile(r'(?P<first>[a-z]+)(?:-(?P<last>[a-z]+))?', re.IGNORECASE)
 
@@ -117,7 +174,7 @@ class WeekdayRangeExpression(RangeExpression):
         else:
             last_num = None
 
-        RangeExpression.__init__(self, first_num, last_num)
+        super(WeekdayRangeExpression, self).__init__(first_num, last_num)
 
     def __str__(self):
         if self.last != self.first and self.last is not None:
@@ -133,9 +190,11 @@ class WeekdayRangeExpression(RangeExpression):
 
 class WeekdayPositionExpression(AllExpression):
     options = ['1st', '2nd', '3rd', '4th', '5th', 'last']
-    value_re = re.compile(r'(?P<option_name>%s) +(?P<weekday_name>(?:\d+|\w+))' % '|'.join(options), re.IGNORECASE)
+    value_re = re.compile(r'(?P<option_name>%s) +(?P<weekday_name>(?:\d+|\w+))' %
+                          '|'.join(options), re.IGNORECASE)
 
     def __init__(self, option_name, weekday_name):
+        super(WeekdayPositionExpression, self).__init__(None)
         try:
             self.option_num = self.options.index(option_name.lower())
         except ValueError:
@@ -147,8 +206,7 @@ class WeekdayPositionExpression(AllExpression):
             raise ValueError('Invalid weekday name "%s"' % weekday_name)
 
     def get_next_value(self, date, field):
-        # Figure out the weekday of the month's first day and the number
-        # of days in that month
+        # Figure out the weekday of the month's first day and the number of days in that month
         first_day_wday, last_day = monthrange(date.year, date.month)
 
         # Calculate which day of the month is the first of the target weekdays
@@ -160,23 +218,28 @@ class WeekdayPositionExpression(AllExpression):
         if self.option_num < 5:
             target_day = first_hit_day + self.option_num * 7
         else:
-            target_day = first_hit_day + ((last_day - first_hit_day) / 7) * 7
+            target_day = first_hit_day + ((last_day - first_hit_day) // 7) * 7
 
         if target_day <= last_day and target_day >= date.day:
             return target_day
 
+    def __eq__(self, other):
+        return (super(WeekdayPositionExpression, self).__eq__(other) and
+                self.option_num == other.option_num and self.weekday == other.weekday)
+
     def __str__(self):
         return '%s %s' % (self.options[self.option_num], WEEKDAYS[self.weekday])
 
     def __repr__(self):
-        return "%s('%s', '%s')" % (self.__class__.__name__, self.options[self.option_num], WEEKDAYS[self.weekday])
+        return "%s('%s', '%s')" % (self.__class__.__name__, self.options[self.option_num],
+                                   WEEKDAYS[self.weekday])
 
 
 class LastDayOfMonthExpression(AllExpression):
     value_re = re.compile(r'last', re.IGNORECASE)
 
     def __init__(self):
-        pass
+        super(LastDayOfMonthExpression, self).__init__(None)
 
     def get_next_value(self, date, field):
         return monthrange(date.year, date.month)[1]

lib/apscheduler/triggers/cron/fields.py

@@ -1,22 +1,26 @@
-"""
-Fields represent CronTrigger options which map to :class:`~datetime.datetime`
-fields.
-"""
+"""Fields represent CronTrigger options which map to :class:`~datetime.datetime` fields."""
 
 from calendar import monthrange
+import re
+
+import six
 
 from apscheduler.triggers.cron.expressions import (
-    AllExpression, RangeExpression, WeekdayPositionExpression, LastDayOfMonthExpression, WeekdayRangeExpression)
+    AllExpression, RangeExpression, WeekdayPositionExpression, LastDayOfMonthExpression,
+    WeekdayRangeExpression, MonthRangeExpression)
 
 
-__all__ = ('MIN_VALUES', 'MAX_VALUES', 'DEFAULT_VALUES', 'BaseField', 'WeekField', 'DayOfMonthField', 'DayOfWeekField')
+__all__ = ('MIN_VALUES', 'MAX_VALUES', 'DEFAULT_VALUES', 'BaseField', 'WeekField',
+           'DayOfMonthField', 'DayOfWeekField')
 
 
-MIN_VALUES = {'year': 1970, 'month': 1, 'day': 1, 'week': 1, 'day_of_week': 0, 'hour': 0, 'minute': 0, 'second': 0}
-MAX_VALUES = {'year': 2 ** 63, 'month': 12, 'day:': 31, 'week': 53, 'day_of_week': 6, 'hour': 23, 'minute': 59,
-              'second': 59}
-DEFAULT_VALUES = {'year': '*', 'month': 1, 'day': 1, 'week': '*', 'day_of_week': '*', 'hour': 0, 'minute': 0,
-                  'second': 0}
+MIN_VALUES = {'year': 1970, 'month': 1, 'day': 1, 'week': 1, 'day_of_week': 0, 'hour': 0,
+              'minute': 0, 'second': 0}
+MAX_VALUES = {'year': 9999, 'month': 12, 'day': 31, 'week': 53, 'day_of_week': 6, 'hour': 23,
+              'minute': 59, 'second': 59}
+DEFAULT_VALUES = {'year': '*', 'month': 1, 'day': 1, 'week': '*', 'day_of_week': '*', 'hour': 0,
+                  'minute': 0, 'second': 0}
+SEPARATOR = re.compile(' *, *')
 
 
 class BaseField(object):
@@ -50,23 +54,29 @@ class BaseField(object):
         self.expressions = []
 
         # Split a comma-separated expression list, if any
-        exprs = str(exprs).strip()
-        if ',' in exprs:
-            for expr in exprs.split(','):
-                self.compile_expression(expr)
-        else:
-            self.compile_expression(exprs)
+        for expr in SEPARATOR.split(str(exprs).strip()):
+            self.compile_expression(expr)
 
     def compile_expression(self, expr):
         for compiler in self.COMPILERS:
             match = compiler.value_re.match(expr)
             if match:
                 compiled_expr = compiler(**match.groupdict())
+
+                try:
+                    compiled_expr.validate_range(self.name)
+                except ValueError as e:
+                    exc = ValueError('Error validating expression {!r}: {}'.format(expr, e))
+                    six.raise_from(exc, None)
+
                 self.expressions.append(compiled_expr)
                 return
 
         raise ValueError('Unrecognized expression "%s" for field "%s"' % (expr, self.name))
 
+    def __eq__(self, other):
+        return isinstance(self, self.__class__) and self.expressions == other.expressions
+
     def __str__(self):
         expr_strings = (str(e) for e in self.expressions)
         return ','.join(expr_strings)
@@ -94,4 +104,8 @@ class DayOfWeekField(BaseField):
     COMPILERS = BaseField.COMPILERS + [WeekdayRangeExpression]
 
     def get_value(self, dateval):
-        return dateval.weekday()
+        return dateval.isoweekday() % 7
+
+
+class MonthField(BaseField):
+    COMPILERS = BaseField.COMPILERS + [MonthRangeExpression]

lib/apscheduler/triggers/date.py

@@ -14,15 +14,36 @@ class DateTrigger(BaseTrigger):
     :param datetime.tzinfo|str timezone: time zone for ``run_date`` if it doesn't have one already
     """
 
-    __slots__ = 'timezone', 'run_date'
+    __slots__ = 'run_date'
 
     def __init__(self, run_date=None, timezone=None):
         timezone = astimezone(timezone) or get_localzone()
-        self.run_date = convert_to_datetime(run_date or datetime.now(), timezone, 'run_date')
+        if run_date is not None:
+            self.run_date = convert_to_datetime(run_date, timezone, 'run_date')
+        else:
+            self.run_date = datetime.now(timezone)
 
     def get_next_fire_time(self, previous_fire_time, now):
         return self.run_date if previous_fire_time is None else None
 
+    def __getstate__(self):
+        return {
+            'version': 1,
+            'run_date': self.run_date
+        }
+
+    def __setstate__(self, state):
+        # This is for compatibility with APScheduler 3.0.x
+        if isinstance(state, tuple):
+            state = state[1]
+
+        if state.get('version', 1) > 1:
+            raise ValueError(
+                'Got serialized data for version %s of %s, but only version 1 can be handled' %
+                (state['version'], self.__class__.__name__))
+
+        self.run_date = state['run_date']
+
     def __str__(self):
         return 'date[%s]' % datetime_repr(self.run_date)
 

lib/apscheduler/triggers/interval.py

@@ -9,8 +9,8 @@ from apscheduler.util import convert_to_datetime, timedelta_seconds, datetime_re
 
 class IntervalTrigger(BaseTrigger):
     """
-    Triggers on specified intervals, starting on ``start_date`` if specified, ``datetime.now()`` + interval
-    otherwise.
+    Triggers on specified intervals, starting on ``start_date`` if specified, ``datetime.now()`` +
+    interval otherwise.
 
     :param int weeks: number of weeks to wait
     :param int days: number of days to wait
@@ -20,12 +20,15 @@ class IntervalTrigger(BaseTrigger):
     :param datetime|str start_date: starting point for the interval calculation
     :param datetime|str end_date: latest possible date/time to trigger on
     :param datetime.tzinfo|str timezone: time zone to use for the date/time calculations
+    :param int|None jitter: advance or delay the job execution by ``jitter`` seconds at most.
     """
 
-    __slots__ = 'timezone', 'start_date', 'end_date', 'interval'
+    __slots__ = 'timezone', 'start_date', 'end_date', 'interval', 'interval_length', 'jitter'
 
-    def __init__(self, weeks=0, days=0, hours=0, minutes=0, seconds=0, start_date=None, end_date=None, timezone=None):
-        self.interval = timedelta(weeks=weeks, days=days, hours=hours, minutes=minutes, seconds=seconds)
+    def __init__(self, weeks=0, days=0, hours=0, minutes=0, seconds=0, start_date=None,
+                 end_date=None, timezone=None, jitter=None):
+        self.interval = timedelta(weeks=weeks, days=days, hours=hours, minutes=minutes,
+                                  seconds=seconds)
         self.interval_length = timedelta_seconds(self.interval)
         if self.interval_length == 0:
             self.interval = timedelta(seconds=1)
@@ -33,9 +36,9 @@ class IntervalTrigger(BaseTrigger):
 
         if timezone:
             self.timezone = astimezone(timezone)
-        elif start_date and start_date.tzinfo:
+        elif isinstance(start_date, datetime) and start_date.tzinfo:
             self.timezone = start_date.tzinfo
-        elif end_date and end_date.tzinfo:
+        elif isinstance(end_date, datetime) and end_date.tzinfo:
             self.timezone = end_date.tzinfo
         else:
             self.timezone = get_localzone()
@@ -44,6 +47,8 @@ class IntervalTrigger(BaseTrigger):
         self.start_date = convert_to_datetime(start_date, self.timezone, 'start_date')
         self.end_date = convert_to_datetime(end_date, self.timezone, 'end_date')
 
+        self.jitter = jitter
+
     def get_next_fire_time(self, previous_fire_time, now):
         if previous_fire_time:
             next_fire_time = previous_fire_time + self.interval
@@ -54,12 +59,48 @@ class IntervalTrigger(BaseTrigger):
             next_interval_num = int(ceil(timediff_seconds / self.interval_length))
             next_fire_time = self.start_date + self.interval * next_interval_num
 
+        if self.jitter is not None:
+            next_fire_time = self._apply_jitter(next_fire_time, self.jitter, now)
+
         if not self.end_date or next_fire_time <= self.end_date:
             return self.timezone.normalize(next_fire_time)
 
+    def __getstate__(self):
+        return {
+            'version': 2,
+            'timezone': self.timezone,
+            'start_date': self.start_date,
+            'end_date': self.end_date,
+            'interval': self.interval,
+            'jitter': self.jitter,
+        }
+
+    def __setstate__(self, state):
+        # This is for compatibility with APScheduler 3.0.x
+        if isinstance(state, tuple):
+            state = state[1]
+
+        if state.get('version', 1) > 2:
+            raise ValueError(
+                'Got serialized data for version %s of %s, but only versions up to 2 can be '
+                'handled' % (state['version'], self.__class__.__name__))
+
+        self.timezone = state['timezone']
+        self.start_date = state['start_date']
+        self.end_date = state['end_date']
+        self.interval = state['interval']
+        self.interval_length = timedelta_seconds(self.interval)
+        self.jitter = state.get('jitter')
+
     def __str__(self):
         return 'interval[%s]' % str(self.interval)
 
     def __repr__(self):
-        return "<%s (interval=%r, start_date='%s')>" % (self.__class__.__name__, self.interval,
-                                                        datetime_repr(self.start_date))
+        options = ['interval=%r' % self.interval, 'start_date=%r' % datetime_repr(self.start_date)]
+        if self.end_date:
+            options.append("end_date=%r" % datetime_repr(self.end_date))
+        if self.jitter:
+            options.append('jitter=%s' % self.jitter)
+
+        return "<%s (%s, timezone='%s')>" % (
+            self.__class__.__name__, ', '.join(options), self.timezone)

lib/apscheduler/util.py

@@ -2,9 +2,9 @@
 
 from __future__ import division
 from datetime import date, datetime, time, timedelta, tzinfo
-from inspect import isfunction, ismethod, getargspec
 from calendar import timegm
 import re
+from functools import partial
 
 from pytz import timezone, utc
 import six
@@ -12,14 +12,16 @@ import six
 try:
     from inspect import signature
 except ImportError:  # pragma: nocover
-    try:
-        from funcsigs import signature
-    except ImportError:
-        signature = None
+    from funcsigs import signature
+
+try:
+    from threading import TIMEOUT_MAX
+except ImportError:
+    TIMEOUT_MAX = 4294967  # Maximum value accepted by Event.wait() on Windows
 
 __all__ = ('asint', 'asbool', 'astimezone', 'convert_to_datetime', 'datetime_to_utc_timestamp',
-           'utc_timestamp_to_datetime', 'timedelta_seconds', 'datetime_ceil', 'get_callable_name', 'obj_to_ref',
-           'ref_to_obj', 'maybe_ref', 'repr_escape', 'check_callable_args')
+           'utc_timestamp_to_datetime', 'timedelta_seconds', 'datetime_ceil', 'get_callable_name',
+           'obj_to_ref', 'ref_to_obj', 'maybe_ref', 'repr_escape', 'check_callable_args')
 
 
 class _Undefined(object):
@@ -32,17 +34,18 @@ class _Undefined(object):
     def __repr__(self):
         return '<undefined>'
 
+
 undefined = _Undefined()  #: a unique object that only signifies that no value is defined
 
 
 def asint(text):
     """
-    Safely converts a string to an integer, returning None if the string is None.
+    Safely converts a string to an integer, returning ``None`` if the string is ``None``.
 
     :type text: str
     :rtype: int
-    """
 
+    """
     if text is not None:
         return int(text)
 
@@ -52,8 +55,8 @@ def asbool(obj):
     Interprets an object as a boolean value.
 
     :rtype: bool
-    """
 
+    """
     if isinstance(obj, str):
         obj = obj.strip().lower()
         if obj in ('true', 'yes', 'on', 'y', 't', '1'):
@@ -69,15 +72,19 @@ def astimezone(obj):
     Interprets an object as a timezone.
 
     :rtype: tzinfo
-    """
 
+    """
     if isinstance(obj, six.string_types):
         return timezone(obj)
     if isinstance(obj, tzinfo):
         if not hasattr(obj, 'localize') or not hasattr(obj, 'normalize'):
             raise TypeError('Only timezones from the pytz library are supported')
         if obj.zone == 'local':
-            raise ValueError('Unable to determine the name of the local timezone -- use an explicit timezone instead')
+            raise ValueError(
+                'Unable to determine the name of the local timezone -- you must explicitly '
+                'specify the name of the local timezone. Please refrain from using timezones like '
+                'EST to prevent problems with daylight saving time. Instead, use a locale based '
+                'timezone name (such as Europe/Helsinki).')
         return obj
     if obj is not None:
         raise TypeError('Expected tzinfo, got %s instead' % obj.__class__.__name__)
@@ -92,20 +99,20 @@ _DATE_REGEX = re.compile(
 def convert_to_datetime(input, tz, arg_name):
     """
     Converts the given object to a timezone aware datetime object.
+
     If a timezone aware datetime object is passed, it is returned unmodified.
     If a native datetime object is passed, it is given the specified timezone.
     If the input is a string, it is parsed as a datetime with the given timezone.
 
-    Date strings are accepted in three different forms: date only (Y-m-d),
-    date with time (Y-m-d H:M:S) or with date+time with microseconds
-    (Y-m-d H:M:S.micro).
+    Date strings are accepted in three different forms: date only (Y-m-d), date with time
+    (Y-m-d H:M:S) or with date+time with microseconds (Y-m-d H:M:S.micro).
 
     :param str|datetime input: the datetime or string to convert to a timezone aware datetime
     :param datetime.tzinfo tz: timezone to interpret ``input`` in
     :param str arg_name: the name of the argument (used in an error message)
     :rtype: datetime
-    """
 
+    """
     if input is None:
         return
     elif isinstance(input, datetime):
@@ -125,14 +132,16 @@ def convert_to_datetime(input, tz, arg_name):
     if datetime_.tzinfo is not None:
         return datetime_
     if tz is None:
-        raise ValueError('The "tz" argument must be specified if %s has no timezone information' % arg_name)
+        raise ValueError(
+            'The "tz" argument must be specified if %s has no timezone information' % arg_name)
     if isinstance(tz, six.string_types):
         tz = timezone(tz)
 
     try:
         return tz.localize(datetime_, is_dst=None)
     except AttributeError:
-        raise TypeError('Only pytz timezones are supported (need the localize() and normalize() methods)')
+        raise TypeError(
+            'Only pytz timezones are supported (need the localize() and normalize() methods)')
 
 
 def datetime_to_utc_timestamp(timeval):
@@ -141,8 +150,8 @@ def datetime_to_utc_timestamp(timeval):
 
     :type timeval: datetime
     :rtype: float
-    """
 
+    """
     if timeval is not None:
         return timegm(timeval.utctimetuple()) + timeval.microsecond / 1000000
 
@@ -153,8 +162,8 @@ def utc_timestamp_to_datetime(timestamp):
 
     :type timestamp: float
     :rtype: datetime
-    """
 
+    """
     if timestamp is not None:
         return datetime.fromtimestamp(timestamp, utc)
 
@@ -165,8 +174,8 @@ def timedelta_seconds(delta):
 
     :type delta: timedelta
     :rtype: float
-    """
 
+    """
     return delta.days * 24 * 60 * 60 + delta.seconds + \
         delta.microseconds / 1000000.0
 
@@ -176,8 +185,8 @@ def datetime_ceil(dateval):
     Rounds the given datetime object upwards.
 
     :type dateval: datetime
-    """
 
+    """
     if dateval.microsecond > 0:
         return dateval + timedelta(seconds=1, microseconds=-dateval.microsecond)
     return dateval
@@ -192,8 +201,8 @@ def get_callable_name(func):
     Returns the best available display name for the given function/callable.
 
     :rtype: str
-    """
 
+    """
     # the easy case (on Python 3.3+)
     if hasattr(func, '__qualname__'):
         return func.__qualname__
@@ -222,20 +231,24 @@ def get_callable_name(func):
 
 def obj_to_ref(obj):
     """
-    Returns the path to the given object.
+    Returns the path to the given callable.
 
     :rtype: str
+    :raises TypeError: if the given object is not callable
+    :raises ValueError: if the given object is a :class:`~functools.partial`, lambda or a nested
+        function
+
     """
+    if isinstance(obj, partial):
+        raise ValueError('Cannot create a reference to a partial()')
 
-    try:
-        ref = '%s:%s' % (obj.__module__, get_callable_name(obj))
-        obj2 = ref_to_obj(ref)
-        if obj != obj2:
-            raise ValueError
-    except Exception:
-        raise ValueError('Cannot determine the reference to %r' % obj)
+    name = get_callable_name(obj)
+    if '<lambda>' in name:
+        raise ValueError('Cannot create a reference to a lambda')
+    if '<locals>' in name:
+        raise ValueError('Cannot create a reference to a nested function')
 
-    return ref
+    return '%s:%s' % (obj.__module__, name)
 
 
 def ref_to_obj(ref):
@@ -243,8 +256,8 @@ def ref_to_obj(ref):
     Returns the object pointed to by ``ref``.
 
     :type ref: str
-    """
 
+    """
     if not isinstance(ref, six.string_types):
         raise TypeError('References must be strings')
     if ':' not in ref:
@@ -252,12 +265,12 @@ def ref_to_obj(ref):
 
     modulename, rest = ref.split(':', 1)
     try:
-        obj = __import__(modulename)
+        obj = __import__(modulename, fromlist=[rest])
     except ImportError:
         raise LookupError('Error resolving reference %s: could not import module' % ref)
 
     try:
-        for name in modulename.split('.')[1:] + rest.split('.'):
+        for name in rest.split('.'):
             obj = getattr(obj, name)
         return obj
     except Exception:
@@ -268,8 +281,8 @@ def maybe_ref(ref):
     """
     Returns the object that the given reference points to, if it is indeed a reference.
     If it is not a reference, the object is returned as-is.
-    """
 
+    """
     if not isinstance(ref, str):
         return ref
     return ref_to_obj(ref)
@@ -281,7 +294,8 @@ if six.PY2:
             return string.encode('ascii', 'backslashreplace')
         return string
 else:
-    repr_escape = lambda string: string
+    def repr_escape(string):
+        return string
 
 
 def check_callable_args(func, args, kwargs):
@@ -290,70 +304,51 @@ def check_callable_args(func, args, kwargs):
 
     :type args: tuple
     :type kwargs: dict
-    """
 
+    """
     pos_kwargs_conflicts = []  # parameters that have a match in both args and kwargs
     positional_only_kwargs = []  # positional-only parameters that have a match in kwargs
     unsatisfied_args = []  # parameters in signature that don't have a match in args or kwargs
     unsatisfied_kwargs = []  # keyword-only arguments that don't have a match in kwargs
     unmatched_args = list(args)  # args that didn't match any of the parameters in the signature
-    unmatched_kwargs = list(kwargs)  # kwargs that didn't match any of the parameters in the signature
-    has_varargs = has_var_kwargs = False  # indicates if the signature defines *args and **kwargs respectively
+    # kwargs that didn't match any of the parameters in the signature
+    unmatched_kwargs = list(kwargs)
+    # indicates if the signature defines *args and **kwargs respectively
+    has_varargs = has_var_kwargs = False
 
-    if signature:
-        try:
-            sig = signature(func)
-        except ValueError:
-            return  # signature() doesn't work against every kind of callable
+    try:
+        sig = signature(func)
+    except ValueError:
+        # signature() doesn't work against every kind of callable
+        return
 
-        for param in six.itervalues(sig.parameters):
-            if param.kind == param.POSITIONAL_OR_KEYWORD:
-                if param.name in unmatched_kwargs and unmatched_args:
-                    pos_kwargs_conflicts.append(param.name)
-                elif unmatched_args:
-                    del unmatched_args[0]
-                elif param.name in unmatched_kwargs:
-                    unmatched_kwargs.remove(param.name)
-                elif param.default is param.empty:
-                    unsatisfied_args.append(param.name)
-            elif param.kind == param.POSITIONAL_ONLY:
-                if unmatched_args:
-                    del unmatched_args[0]
-                elif param.name in unmatched_kwargs:
-                    unmatched_kwargs.remove(param.name)
-                    positional_only_kwargs.append(param.name)
-                elif param.default is param.empty:
-                    unsatisfied_args.append(param.name)
-            elif param.kind == param.KEYWORD_ONLY:
-                if param.name in unmatched_kwargs:
-                    unmatched_kwargs.remove(param.name)
-                elif param.default is param.empty:
-                    unsatisfied_kwargs.append(param.name)
-            elif param.kind == param.VAR_POSITIONAL:
-                has_varargs = True
-            elif param.kind == param.VAR_KEYWORD:
-                has_var_kwargs = True
-    else:
-        if not isfunction(func) and not ismethod(func) and hasattr(func, '__call__'):
-            func = func.__call__
-
-        try:
-            argspec = getargspec(func)
-        except TypeError:
-            return  # getargspec() doesn't work certain callables
-
-        argspec_args = argspec.args if not ismethod(func) else argspec.args[1:]
-        has_varargs = bool(argspec.varargs)
-        has_var_kwargs = bool(argspec.keywords)
-        for arg, default in six.moves.zip_longest(argspec_args, argspec.defaults or (), fillvalue=undefined):
-            if arg in unmatched_kwargs and unmatched_args:
-                pos_kwargs_conflicts.append(arg)
+    for param in six.itervalues(sig.parameters):
+        if param.kind == param.POSITIONAL_OR_KEYWORD:
+            if param.name in unmatched_kwargs and unmatched_args:
+                pos_kwargs_conflicts.append(param.name)
             elif unmatched_args:
                 del unmatched_args[0]
-            elif arg in unmatched_kwargs:
-                unmatched_kwargs.remove(arg)
-            elif default is undefined:
-                unsatisfied_args.append(arg)
+            elif param.name in unmatched_kwargs:
+                unmatched_kwargs.remove(param.name)
+            elif param.default is param.empty:
+                unsatisfied_args.append(param.name)
+        elif param.kind == param.POSITIONAL_ONLY:
+            if unmatched_args:
+                del unmatched_args[0]
+            elif param.name in unmatched_kwargs:
+                unmatched_kwargs.remove(param.name)
+                positional_only_kwargs.append(param.name)
+            elif param.default is param.empty:
+                unsatisfied_args.append(param.name)
+        elif param.kind == param.KEYWORD_ONLY:
+            if param.name in unmatched_kwargs:
+                unmatched_kwargs.remove(param.name)
+            elif param.default is param.empty:
+                unsatisfied_kwargs.append(param.name)
+        elif param.kind == param.VAR_POSITIONAL:
+            has_varargs = True
+        elif param.kind == param.VAR_KEYWORD:
+            has_var_kwargs = True
 
     # Make sure there are no conflicts between args and kwargs
     if pos_kwargs_conflicts:
@@ -365,21 +360,26 @@ def check_callable_args(func, args, kwargs):
         raise ValueError('The following arguments cannot be given as keyword arguments: %s' %
                          ', '.join(positional_only_kwargs))
 
-    # Check that the number of positional arguments minus the number of matched kwargs matches the argspec
+    # Check that the number of positional arguments minus the number of matched kwargs matches the
+    # argspec
     if unsatisfied_args:
-        raise ValueError('The following arguments have not been supplied: %s' % ', '.join(unsatisfied_args))
+        raise ValueError('The following arguments have not been supplied: %s' %
+                         ', '.join(unsatisfied_args))
 
     # Check that all keyword-only arguments have been supplied
     if unsatisfied_kwargs:
-        raise ValueError('The following keyword-only arguments have not been supplied in kwargs: %s' %
-                         ', '.join(unsatisfied_kwargs))
+        raise ValueError(
+            'The following keyword-only arguments have not been supplied in kwargs: %s' %
+            ', '.join(unsatisfied_kwargs))
 
     # Check that the callable can accept the given number of positional arguments
     if not has_varargs and unmatched_args:
-        raise ValueError('The list of positional arguments is longer than the target callable can handle '
-                         '(allowed: %d, given in args: %d)' % (len(args) - len(unmatched_args), len(args)))
+        raise ValueError(
+            'The list of positional arguments is longer than the target callable can handle '
+            '(allowed: %d, given in args: %d)' % (len(args) - len(unmatched_args), len(args)))
 
     # Check that the callable can accept the given keyword arguments
     if not has_var_kwargs and unmatched_kwargs:
-        raise ValueError('The target callable does not accept the following keyword arguments: %s' %
-                         ', '.join(unmatched_kwargs))
+        raise ValueError(
+            'The target callable does not accept the following keyword arguments: %s' %
+            ', '.join(unmatched_kwargs))

lib/arrow/__init__.py

@@ -4,5 +4,5 @@ from .arrow import Arrow
 from .factory import ArrowFactory
 from .api import get, now, utcnow
 
-__version__ = '0.7.0'
+__version__ = '0.10.0'
 VERSION = __version__

lib/arrow/api.py

@@ -51,5 +51,5 @@ def factory(type):
     return ArrowFactory(type)
 
 
-__all__ = ['get', 'utcnow', 'now', 'factory', 'iso']
+__all__ = ['get', 'utcnow', 'now', 'factory']
 

lib/arrow/arrow.py

@@ -12,6 +12,8 @@ from dateutil import tz as dateutil_tz
 from dateutil.relativedelta import relativedelta
 import calendar
 import sys
+import warnings
+
 
 from arrow import util, locales, parser, formatter
 
@@ -45,6 +47,7 @@ class Arrow(object):
 
     _ATTRS = ['year', 'month', 'day', 'hour', 'minute', 'second', 'microsecond']
     _ATTRS_PLURAL = ['{0}s'.format(a) for a in _ATTRS]
+    _MONTHS_PER_QUARTER = 3
 
     def __init__(self, year, month, day, hour=0, minute=0, second=0, microsecond=0,
                  tzinfo=None):
@@ -306,6 +309,9 @@ class Arrow(object):
         if name == 'week':
             return self.isocalendar()[1]
 
+        if name == 'quarter':
+            return int((self.month-1)/self._MONTHS_PER_QUARTER) + 1
+
         if not name.startswith('_'):
             value = getattr(self._datetime, name, None)
 
@@ -378,16 +384,16 @@ class Arrow(object):
         >>> arw.replace(year=2014, month=6)
         <Arrow [2014-06-11T22:27:34.787885+00:00]>
 
-        Use plural property names to shift their current value relatively:
-
-        >>> arw.replace(years=1, months=-1)
-        <Arrow [2014-04-11T22:27:34.787885+00:00]>
-
         You can also provide a timezone expression can also be replaced:
 
         >>> arw.replace(tzinfo=tz.tzlocal())
         <Arrow [2013-05-11T22:27:34.787885-07:00]>
 
+       Use plural property names to shift their current value relatively (**deprecated**):
+
+       >>> arw.replace(years=1, months=-1)
+       <Arrow [2014-04-11T22:27:34.787885+00:00]>
+
         Recognized timezone expressions:
 
             - A ``tzinfo`` object.
@@ -398,21 +404,29 @@ class Arrow(object):
         '''
 
         absolute_kwargs = {}
-        relative_kwargs = {}
+        relative_kwargs = {}  # TODO: DEPRECATED; remove in next release
 
         for key, value in kwargs.items():
 
             if key in self._ATTRS:
                 absolute_kwargs[key] = value
-            elif key in self._ATTRS_PLURAL or key == 'weeks':
+            elif key in self._ATTRS_PLURAL or key in ['weeks', 'quarters']:
+                # TODO: DEPRECATED
+                warnings.warn("replace() with plural property to shift value"
+                              "is deprecated, use shift() instead",
+                              DeprecationWarning)
                 relative_kwargs[key] = value
-            elif key == 'week':
-                raise AttributeError('setting absolute week is not supported')
+            elif key in ['week', 'quarter']:
+                raise AttributeError('setting absolute {0} is not supported'.format(key))
             elif key !='tzinfo':
-                raise AttributeError()
+                raise AttributeError('unknown attribute: "{0}"'.format(key))
+
+        # core datetime does not support quarters, translate to months.
+        relative_kwargs.setdefault('months', 0)
+        relative_kwargs['months'] += relative_kwargs.pop('quarters', 0) * self._MONTHS_PER_QUARTER
 
         current = self._datetime.replace(**absolute_kwargs)
-        current += relativedelta(**relative_kwargs)
+        current += relativedelta(**relative_kwargs) # TODO: DEPRECATED
 
         tzinfo = kwargs.get('tzinfo')
 
@@ -422,9 +436,41 @@ class Arrow(object):
 
         return self.fromdatetime(current)
 
+    def shift(self, **kwargs):
+        ''' Returns a new :class:`Arrow <arrow.arrow.Arrow>` object with attributes updated
+        according to inputs.
+
+        Use plural property names to shift their current value relatively:
+
+        >>> import arrow
+        >>> arw = arrow.utcnow()
+        >>> arw
+        <Arrow [2013-05-11T22:27:34.787885+00:00]>
+        >>> arw.shift(years=1, months=-1)
+        <Arrow [2014-04-11T22:27:34.787885+00:00]>
+
+        '''
+
+        relative_kwargs = {}
+
+        for key, value in kwargs.items():
+
+            if key in self._ATTRS_PLURAL or key in ['weeks', 'quarters']:
+                relative_kwargs[key] = value
+            else:
+                raise AttributeError()
+
+        # core datetime does not support quarters, translate to months.
+        relative_kwargs.setdefault('months', 0)
+        relative_kwargs['months'] += relative_kwargs.pop('quarters', 0) * self._MONTHS_PER_QUARTER
+
+        current = self._datetime + relativedelta(**relative_kwargs)
+
+        return self.fromdatetime(current)
+
     def to(self, tz):
-        ''' Returns a new :class:`Arrow <arrow.arrow.Arrow>` object, converted to the target
-        timezone.
+        ''' Returns a new :class:`Arrow <arrow.arrow.Arrow>` object, converted
+        to the target timezone.
 
         :param tz: an expression representing a timezone.
 
@@ -587,6 +633,7 @@ class Arrow(object):
             Defaults to now in the current :class:`Arrow <arrow.arrow.Arrow>` object's timezone.
         :param locale: (optional) a ``str`` specifying a locale.  Defaults to 'en_us'.
         :param only_distance: (optional) returns only time difference eg: "11 seconds" without "in" or "ago" part.
+
         Usage::
 
             >>> earlier = arrow.utcnow().replace(hours=-2)
@@ -651,7 +698,8 @@ class Arrow(object):
         elif diff < 29808000:
             self_months = self._datetime.year * 12 + self._datetime.month
             other_months = dt.year * 12 + dt.month
-            months = sign * abs(other_months - self_months)
+
+            months = sign * int(max(abs(other_months - self_months), 2))
 
             return locale.describe('months', months, only_distance=only_distance)
 
@@ -676,7 +724,7 @@ class Arrow(object):
 
     def __sub__(self, other):
 
-        if isinstance(other, timedelta):
+        if isinstance(other, (timedelta, relativedelta)):
             return self.fromdatetime(self._datetime - other, self._datetime.tzinfo)
 
         elif isinstance(other, datetime):
@@ -688,7 +736,11 @@ class Arrow(object):
         raise TypeError()
 
     def __rsub__(self, other):
-        return self.__sub__(other)
+
+        if isinstance(other, datetime):
+            return other - self._datetime
+
+        raise TypeError()
 
 
     # comparisons
@@ -702,8 +754,6 @@ class Arrow(object):
         if not isinstance(other, (Arrow, datetime)):
             return False
 
-        other = self._get_datetime(other)
-
         return self._datetime == self._get_datetime(other)
 
     def __ne__(self, other):
@@ -882,7 +932,9 @@ class Arrow(object):
             return cls.max, limit
 
         else:
-            return end, sys.maxsize
+            if limit is None:
+                return end, sys.maxsize
+            return end, limit
 
     @staticmethod
     def _get_timestamp_from_input(timestamp):

lib/arrow/formatter.py

@@ -94,7 +94,7 @@ class DateTimeFormatter(object):
             tz = dateutil_tz.tzutc() if dt.tzinfo is None else dt.tzinfo
             total_minutes = int(util.total_seconds(tz.utcoffset(dt)) / 60)
 
-            sign = '+' if total_minutes > 0 else '-'
+            sign = '+' if total_minutes >= 0 else '-'
             total_minutes = abs(total_minutes)
             hour, minute = divmod(total_minutes, 60)
 

lib/arrow/locales.py

@@ -7,8 +7,8 @@ import sys
 
 
 def get_locale(name):
-    '''Returns an appropriate :class:`Locale <locale.Locale>` corresponding
-    to an inpute locale name.
+    '''Returns an appropriate :class:`Locale <arrow.locales.Locale>`
+    corresponding to an inpute locale name.
 
     :param name: the name of the locale.
 
@@ -186,7 +186,7 @@ class Locale(object):
 
 class EnglishLocale(Locale):
 
-    names = ['en', 'en_us', 'en_gb', 'en_au', 'en_be', 'en_jp', 'en_za']
+    names = ['en', 'en_us', 'en_gb', 'en_au', 'en_be', 'en_jp', 'en_za', 'en_ca']
 
     past = '{0} ago'
     future = 'in {0}'
@@ -263,10 +263,10 @@ class ItalianLocale(Locale):
     day_names = ['', 'lunedì', 'martedì', 'mercoledì', 'giovedì', 'venerdì', 'sabato', 'domenica']
     day_abbreviations = ['', 'lun', 'mar', 'mer', 'gio', 'ven', 'sab', 'dom']
 
-    ordinal_day_re = r'((?P<value>[1-3]?[0-9](?=°))°)'
+    ordinal_day_re = r'((?P<value>[1-3]?[0-9](?=[ºª]))[ºª])'
 
     def _ordinal_number(self, n):
-        return '{0}°'.format(n)
+        return '{0}º'.format(n)
 
 
 class SpanishLocale(Locale):
@@ -297,10 +297,10 @@ class SpanishLocale(Locale):
     day_names = ['', 'lunes', 'martes', 'miércoles', 'jueves', 'viernes', 'sábado', 'domingo']
     day_abbreviations = ['', 'lun', 'mar', 'mie', 'jue', 'vie', 'sab', 'dom']
 
-    ordinal_day_re = r'((?P<value>[1-3]?[0-9](?=°))°)'
+    ordinal_day_re = r'((?P<value>[1-3]?[0-9](?=[ºª]))[ºª])'
 
     def _ordinal_number(self, n):
-        return '{0}°'.format(n)
+        return '{0}º'.format(n)
 
 
 class FrenchLocale(Locale):
@@ -379,7 +379,7 @@ class JapaneseLocale(Locale):
 
     timeframes = {
         'now': '現在',
-        'seconds': '秒',
+        'seconds': '数秒',
         'minute': '1分',
         'minutes': '{0}分',
         'hour': '1時間',
@@ -559,8 +559,8 @@ class KoreanLocale(Locale):
 
     timeframes = {
         'now': '지금',
-        'seconds': '몇초',
-        'minute': '일 분',
+        'seconds': '몇 초',
+        'minute': '1분',
         'minutes': '{0}분',
         'hour': '1시간',
         'hours': '{0}시간',
@@ -919,7 +919,7 @@ class NewNorwegianLocale(Locale):
 
 class PortugueseLocale(Locale):
     names = ['pt', 'pt_pt']
-    
+
     past = 'há {0}'
     future = 'em {0}'
 
@@ -946,11 +946,11 @@ class PortugueseLocale(Locale):
     day_names = ['', 'segunda-feira', 'terça-feira', 'quarta-feira', 'quinta-feira', 'sexta-feira',
         'sábado', 'domingo']
     day_abbreviations = ['', 'seg', 'ter', 'qua', 'qui', 'sex', 'sab', 'dom']
-    
-    
+
+
 class BrazilianPortugueseLocale(PortugueseLocale):
     names = ['pt_br']
-    
+
     past = 'fazem {0}'
 
 
@@ -1034,7 +1034,7 @@ class TurkishLocale(Locale):
         'days': '{0} gün',
         'month': 'bir ay',
         'months': '{0} ay',
-        'year': 'a yıl',
+        'year': 'yıl',
         'years': '{0} yıl',
     }
 
@@ -1047,6 +1047,37 @@ class TurkishLocale(Locale):
     day_abbreviations = ['', 'Pzt', 'Sal', 'Çar', 'Per', 'Cum', 'Cmt', 'Paz']
 
 
+class AzerbaijaniLocale(Locale):
+
+    names = ['az', 'az_az']
+
+    past = '{0} əvvəl'
+    future = '{0} sonra'
+
+    timeframes = {
+        'now': 'indi',
+        'seconds': 'saniyə',
+        'minute': 'bir dəqiqə',
+        'minutes': '{0} dəqiqə',
+        'hour': 'bir saat',
+        'hours': '{0} saat',
+        'day': 'bir gün',
+        'days': '{0} gün',
+        'month': 'bir ay',
+        'months': '{0} ay',
+        'year': 'il',
+        'years': '{0} il',
+    }
+
+    month_names = ['', 'Yanvar', 'Fevral', 'Mart', 'Aprel', 'May', 'İyun', 'İyul',
+        'Avqust', 'Sentyabr', 'Oktyabr', 'Noyabr', 'Dekabr']
+    month_abbreviations = ['', 'Yan', 'Fev', 'Mar', 'Apr', 'May', 'İyn', 'İyl', 'Avq',
+        'Sen', 'Okt', 'Noy', 'Dek']
+
+    day_names = ['', 'Bazar ertəsi', 'Çərşənbə axşamı', 'Çərşənbə', 'Cümə axşamı', 'Cümə', 'Şənbə', 'Bazar']
+    day_abbreviations = ['', 'Ber', 'Çax', 'Çər', 'Cax', 'Cüm', 'Şnb', 'Bzr']
+
+
 class ArabicLocale(Locale):
 
     names = ['ar', 'ar_eg']
@@ -1205,11 +1236,11 @@ class HindiLocale(Locale):
     future = '{0} बाद'
 
     timeframes = {
-        'now': 'अभि',
+        'now': 'अभी',
         'seconds': 'सेकंड्',
         'minute': 'एक मिनट ',
         'minutes': '{0} मिनट ',
-        'hour': 'एक घंट',
+        'hour': 'एक घंटा',
         'hours': '{0} घंटे',
         'day': 'एक दिन',
         'days': '{0} दिन',
@@ -1226,8 +1257,8 @@ class HindiLocale(Locale):
         'PM': 'शाम',
     }
 
-    month_names = ['', 'जनवरी', 'फ़रवरी', 'मार्च', 'अप्रैल ', 'मई', 'जून', 'जुलाई',
-                   'आगस्त', 'सितम्बर', 'अकतूबर', 'नवेम्बर', 'दिसम्बर']
+    month_names = ['', 'जनवरी', 'फरवरी', 'मार्च', 'अप्रैल ', 'मई', 'जून', 'जुलाई',
+                   'अगस्त', 'सितंबर', 'अक्टूबर', 'नवंबर', 'दिसंबर']
     month_abbreviations = ['', 'जन', 'फ़र', 'मार्च', 'अप्रै', 'मई', 'जून', 'जुलाई', 'आग',
                            'सित', 'अकत', 'नवे', 'दिस']
 
@@ -1284,7 +1315,8 @@ class CzechLocale(Locale):
 
 
     def _format_timeframe(self, timeframe, delta):
-        '''Czech aware time frame format function, takes into account the differences between past and future forms.'''
+        '''Czech aware time frame format function, takes into account
+        the differences between past and future forms.'''
         form = self.timeframes[timeframe]
         if isinstance(form, dict):
             if delta == 0:
@@ -1293,7 +1325,7 @@ class CzechLocale(Locale):
                 form = form['future']
             else:
                 form = form['past']
-        delta = abs(delta)  
+        delta = abs(delta)
 
         if isinstance(form, list):
             if 2 <= delta % 10 <= 4 and (delta % 100 < 10 or delta % 100 >= 20):
@@ -1303,6 +1335,78 @@ class CzechLocale(Locale):
 
         return form.format(delta)
 
+
+class SlovakLocale(Locale):
+    names = ['sk', 'sk_sk']
+
+    timeframes = {
+        'now': 'Teraz',
+        'seconds': {
+            'past': 'pár sekundami',
+            'future': ['{0} sekundy', '{0} sekúnd']
+        },
+        'minute': {'past': 'minútou', 'future': 'minútu', 'zero': '{0} minút'},
+        'minutes': {
+            'past': '{0} minútami',
+            'future': ['{0} minúty', '{0} minút']
+        },
+        'hour': {'past': 'hodinou', 'future': 'hodinu', 'zero': '{0} hodín'},
+        'hours': {
+            'past': '{0} hodinami',
+            'future': ['{0} hodiny', '{0} hodín']
+        },
+        'day': {'past': 'dňom', 'future': 'deň', 'zero': '{0} dní'},
+        'days': {
+            'past': '{0} dňami',
+            'future': ['{0} dni', '{0} dní']
+        },
+        'month': {'past': 'mesiacom', 'future': 'mesiac', 'zero': '{0} mesiacov'},
+        'months': {
+            'past': '{0} mesiacmi',
+            'future': ['{0} mesiace', '{0} mesiacov']
+        },
+        'year': {'past': 'rokom', 'future': 'rok', 'zero': '{0} rokov'},
+        'years': {
+            'past': '{0} rokmi',
+            'future': ['{0} roky', '{0} rokov']
+        }
+    }
+
+    past = 'Pred {0}'
+    future = 'O {0}'
+
+    month_names = ['', 'január', 'február', 'marec', 'apríl', 'máj', 'jún',
+        'júl', 'august', 'september', 'október', 'november', 'december']
+    month_abbreviations = ['', 'jan', 'feb', 'mar', 'apr', 'máj', 'jún', 'júl',
+        'aug', 'sep', 'okt', 'nov', 'dec']
+
+    day_names = ['', 'pondelok', 'utorok', 'streda', 'štvrtok', 'piatok',
+        'sobota', 'nedeľa']
+    day_abbreviations = ['', 'po', 'ut', 'st', 'št', 'pi', 'so', 'ne']
+
+
+    def _format_timeframe(self, timeframe, delta):
+        '''Slovak aware time frame format function, takes into account
+        the differences between past and future forms.'''
+        form = self.timeframes[timeframe]
+        if isinstance(form, dict):
+            if delta == 0:
+                form = form['zero']  # And *never* use 0 in the singular!
+            elif delta > 0:
+                form = form['future']
+            else:
+                form = form['past']
+        delta = abs(delta)
+
+        if isinstance(form, list):
+            if 2 <= delta % 10 <= 4 and (delta % 100 < 10 or delta % 100 >= 20):
+                form = form[0]
+            else:
+                form = form[1]
+
+        return form.format(delta)
+
+
 class FarsiLocale(Locale):
 
     names = ['fa', 'fa_ir']
@@ -1463,7 +1567,7 @@ class MarathiLocale(Locale):
 
     day_names = ['', 'सोमवार', 'मंगळवार', 'बुधवार', 'गुरुवार', 'शुक्रवार', 'शनिवार', 'रविवार']
     day_abbreviations = ['', 'सोम', 'मंगळ', 'बुध', 'गुरु', 'शुक्र', 'शनि', 'रवि']
-    
+
 def _map_locales():
 
     locales = {}
@@ -1471,14 +1575,14 @@ def _map_locales():
     for cls_name, cls in inspect.getmembers(sys.modules[__name__], inspect.isclass):
         if issubclass(cls, Locale):
             for name in cls.names:
-                locales[name.lower()] = cls  
+                locales[name.lower()] = cls
 
     return locales
 
-class CatalaLocale(Locale):
-    names = ['ca', 'ca_ca']
+class CatalanLocale(Locale):
+    names = ['ca', 'ca_es', 'ca_ad', 'ca_fr', 'ca_it']
     past = 'Fa {0}'
-    future = '{0}' # I don't know what's the right phrase in catala for the future.
+    future = 'En {0}'
 
     timeframes = {
         'now': 'Ara mateix',
@@ -1490,15 +1594,15 @@ class CatalaLocale(Locale):
         'day': 'un dia',
         'days': '{0} dies',
         'month': 'un mes',
-        'months': '{0} messos',
+        'months': '{0} mesos',
         'year': 'un any',
         'years': '{0} anys',
     }
 
-    month_names = ['', 'Jener', 'Febrer', 'Març', 'Abril', 'Maig', 'Juny', 'Juliol', 'Agost', 'Setembre', 'Octubre', 'Novembre', 'Decembre']
-    month_abbreviations = ['', 'Jener', 'Febrer', 'Març', 'Abril', 'Maig', 'Juny', 'Juliol', 'Agost', 'Setembre', 'Octubre', 'Novembre', 'Decembre']
-    day_names = ['', 'Dilluns', 'Dimars', 'Dimecres', 'Dijous', 'Divendres', 'Disabte', 'Diumenge']
-    day_abbreviations = ['', 'Dilluns', 'Dimars', 'Dimecres', 'Dijous', 'Divendres', 'Disabte', 'Diumenge']
+    month_names = ['', 'Gener', 'Febrer', 'Març', 'Abril', 'Maig', 'Juny', 'Juliol', 'Agost', 'Setembre', 'Octubre', 'Novembre', 'Desembre']
+    month_abbreviations = ['', 'Gener', 'Febrer', 'Març', 'Abril', 'Maig', 'Juny', 'Juliol', 'Agost', 'Setembre', 'Octubre', 'Novembre', 'Desembre']
+    day_names = ['', 'Dilluns', 'Dimarts', 'Dimecres', 'Dijous', 'Divendres', 'Dissabte', 'Diumenge']
+    day_abbreviations = ['', 'Dilluns', 'Dimarts', 'Dimecres', 'Dijous', 'Divendres', 'Dissabte', 'Diumenge']
 
 class BasqueLocale(Locale):
     names = ['eu', 'eu_eu']
@@ -1587,6 +1691,50 @@ class HungarianLocale(Locale):
         return form.format(abs(delta))
 
 
+class EsperantoLocale(Locale):
+    names = ['eo', 'eo_xx']
+    past = 'antaŭ {0}'
+    future = 'post {0}'
+
+    timeframes = {
+        'now': 'nun',
+        'seconds': 'kelkaj sekundoj',
+        'minute': 'unu minuto',
+        'minutes': '{0} minutoj',
+        'hour': 'un horo',
+        'hours': '{0} horoj',
+        'day': 'unu tago',
+        'days': '{0} tagoj',
+        'month': 'unu monato',
+        'months': '{0} monatoj',
+        'year': 'unu jaro',
+        'years': '{0} jaroj',
+    }
+
+    month_names = ['', 'januaro', 'februaro', 'marto', 'aprilo', 'majo',
+                   'junio', 'julio', 'aŭgusto', 'septembro', 'oktobro',
+                   'novembro', 'decembro']
+    month_abbreviations = ['', 'jan', 'feb', 'mar', 'apr', 'maj', 'jun',
+                           'jul', 'aŭg', 'sep', 'okt', 'nov', 'dec']
+
+    day_names = ['', 'lundo', 'mardo', 'merkredo', 'ĵaŭdo', 'vendredo',
+                 'sabato', 'dimanĉo']
+    day_abbreviations = ['', 'lun', 'mar', 'mer', 'ĵaŭ', 'ven',
+                         'sab', 'dim']
+
+    meridians = {
+        'am': 'atm',
+        'pm': 'ptm',
+        'AM': 'ATM',
+        'PM': 'PTM',
+    }
+
+    ordinal_day_re = r'((?P<value>[1-3]?[0-9](?=a))a)'
+
+    def _ordinal_number(self, n):
+        return '{0}a'.format(n)
+
+
 class ThaiLocale(Locale):
 
     names = ['th', 'th_th']
@@ -1700,4 +1848,164 @@ class BengaliLocale(Locale):
             return '{0}ষ্ঠ'.format(n)
 
 
+class RomanshLocale(Locale):
+
+    names = ['rm', 'rm_ch']
+
+    past = 'avant {0}'
+    future = 'en {0}'
+
+    timeframes = {
+        'now': 'en quest mument',
+        'seconds': 'secundas',
+        'minute': 'ina minuta',
+        'minutes': '{0} minutas',
+        'hour': 'in\'ura',
+        'hours': '{0} ura',
+        'day': 'in di',
+        'days': '{0} dis',
+        'month': 'in mais',
+        'months': '{0} mais',
+        'year': 'in onn',
+        'years': '{0} onns',
+    }
+
+    month_names = [
+        '', 'schaner', 'favrer', 'mars', 'avrigl', 'matg', 'zercladur',
+        'fanadur', 'avust', 'settember', 'october', 'november', 'december'
+    ]
+
+    month_abbreviations = [
+        '', 'schan', 'fav', 'mars', 'avr', 'matg', 'zer', 'fan', 'avu',
+        'set', 'oct', 'nov', 'dec'
+    ]
+
+    day_names = [
+        '', 'glindesdi', 'mardi', 'mesemna', 'gievgia', 'venderdi',
+        'sonda', 'dumengia'
+    ]
+
+    day_abbreviations = [
+        '', 'gli', 'ma', 'me', 'gie', 've', 'so', 'du'
+    ]
+
+
+class SwissLocale(Locale):
+
+    names = ['de', 'de_ch']
+
+    past = 'vor {0}'
+    future = 'in {0}'
+
+    timeframes = {
+            'now': 'gerade eben',
+            'seconds':  'Sekunden',
+            'minute': 'einer Minute',
+            'minutes': '{0} Minuten',
+            'hour': 'einer Stunde',
+            'hours': '{0} Stunden',
+            'day': 'einem Tag',
+            'days': '{0} Tage',
+            'month': 'einem Monat',
+            'months': '{0} Monaten',
+            'year': 'einem Jahr',
+            'years': '{0} Jahren',
+        }
+
+    month_names = [
+            '', 'Januar', 'Februar', 'März', 'April', 'Mai', 'Juni', 'Juli',
+            'August', 'September', 'Oktober', 'November', 'Dezember'
+        ]
+
+    month_abbreviations = [
+            '', 'Jan', 'Feb', 'Mär', 'Apr', 'Mai', 'Jun', 'Jul', 'Aug', 'Sep',
+            'Okt', 'Nov', 'Dez'
+        ]
+
+    day_names = [
+            '', 'Montag', 'Dienstag', 'Mittwoch', 'Donnerstag', 'Freitag',
+            'Samstag', 'Sonntag'
+        ]
+
+    day_abbreviations = [
+            '', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa', 'So'
+        ]
+
+
+class RomanianLocale(Locale):
+    names = ['ro', 'ro_ro']
+
+    past = '{0} în urmă'
+    future = 'peste {0}'
+
+    timeframes = {
+        'now': 'acum',
+        'seconds': 'câteva secunde',
+        'minute': 'un minut',
+        'minutes': '{0} minute',
+        'hour': 'o oră',
+        'hours': '{0} ore',
+        'day': 'o zi',
+        'days': '{0} zile',
+        'month': 'o lună',
+        'months': '{0} luni',
+        'year': 'un an',
+        'years': '{0} ani',
+    }
+
+    month_names = ['', 'ianuarie', 'februarie', 'martie', 'aprilie', 'mai', 'iunie', 'iulie',
+                   'august', 'septembrie', 'octombrie', 'noiembrie', 'decembrie']
+    month_abbreviations = ['', 'ian', 'febr', 'mart', 'apr', 'mai', 'iun', 'iul', 'aug', 'sept', 'oct', 'nov', 'dec']
+
+    day_names = ['', 'luni', 'marți', 'miercuri', 'joi', 'vineri', 'sâmbătă', 'duminică']
+    day_abbreviations = ['', 'Lun', 'Mar', 'Mie', 'Joi', 'Vin', 'Sâm', 'Dum']
+
+
+class SlovenianLocale(Locale):
+    names = ['sl', 'sl_si']
+
+    past = 'pred {0}'
+    future = 'čez {0}'
+
+    timeframes = {
+        'now': 'zdaj',
+        'seconds': 'sekund',
+        'minute': 'minuta',
+        'minutes': '{0} minutami',
+        'hour': 'uro',
+        'hours': '{0} ur',
+        'day': 'dan',
+        'days': '{0} dni',
+        'month': 'mesec',
+        'months': '{0} mesecev',
+        'year': 'leto',
+        'years': '{0} let',
+    }
+
+    meridians = {
+        'am': '',
+        'pm': '',
+        'AM': '',
+        'PM': '',
+    }
+
+    month_names = [
+        '', 'Januar', 'Februar', 'Marec', 'April', 'Maj', 'Junij', 'Julij',
+        'Avgust', 'September', 'Oktober', 'November', 'December'
+    ]
+
+    month_abbreviations = [
+        '', 'Jan', 'Feb', 'Mar', 'Apr', 'Maj', 'Jun', 'Jul', 'Avg',
+        'Sep', 'Okt', 'Nov', 'Dec'
+    ]
+
+    day_names = [
+        '', 'Ponedeljek', 'Torek', 'Sreda', 'Četrtek', 'Petek', 'Sobota', 'Nedelja'
+    ]
+
+    day_abbreviations = [
+        '', 'Pon', 'Tor', 'Sre', 'Čet', 'Pet', 'Sob', 'Ned'
+    ]
+
+
 _locales = _map_locales()

lib/arrow/parser.py

@@ -5,7 +5,6 @@ from __future__ import unicode_literals
 from datetime import datetime
 from dateutil import tz
 import re
-
 from arrow import locales
 
 
@@ -15,16 +14,14 @@ class ParserError(RuntimeError):
 
 class DateTimeParser(object):
 
-    _FORMAT_RE = re.compile('(YYY?Y?|MM?M?M?|Do|DD?D?D?|HH?|hh?|mm?|ss?|SS?S?S?S?S?|ZZ?Z?|a|A|X)')
+    _FORMAT_RE = re.compile('(YYY?Y?|MM?M?M?|Do|DD?D?D?|d?d?d?d|HH?|hh?|mm?|ss?|S+|ZZ?Z?|a|A|X)')
+    _ESCAPE_RE = re.compile('\[[^\[\]]*\]')
 
-    _ONE_THROUGH_SIX_DIGIT_RE = re.compile('\d{1,6}')
-    _ONE_THROUGH_FIVE_DIGIT_RE = re.compile('\d{1,5}')
-    _ONE_THROUGH_FOUR_DIGIT_RE = re.compile('\d{1,4}')
-    _ONE_TWO_OR_THREE_DIGIT_RE = re.compile('\d{1,3}')
+    _ONE_OR_MORE_DIGIT_RE = re.compile('\d+')
     _ONE_OR_TWO_DIGIT_RE = re.compile('\d{1,2}')
     _FOUR_DIGIT_RE = re.compile('\d{4}')
     _TWO_DIGIT_RE = re.compile('\d{2}')
-    _TZ_RE = re.compile('[+\-]?\d{2}:?\d{2}')
+    _TZ_RE = re.compile('[+\-]?\d{2}:?(\d{2})?')
     _TZ_NAME_RE = re.compile('\w[\w+\-/]+')
 
 
@@ -47,12 +44,7 @@ class DateTimeParser(object):
         'ZZZ': _TZ_NAME_RE,
         'ZZ': _TZ_RE,
         'Z': _TZ_RE,
-        'SSSSSS': _ONE_THROUGH_SIX_DIGIT_RE,
-        'SSSSS': _ONE_THROUGH_FIVE_DIGIT_RE,
-        'SSSS': _ONE_THROUGH_FOUR_DIGIT_RE,
-        'SSS': _ONE_TWO_OR_THREE_DIGIT_RE,
-        'SS': _ONE_OR_TWO_DIGIT_RE,
-        'S': re.compile('\d'),
+        'S': _ONE_OR_MORE_DIGIT_RE,
     }
 
     MARKERS = ['YYYY', 'MM', 'DD']
@@ -67,6 +59,10 @@ class DateTimeParser(object):
             'MMM': self._choice_re(self.locale.month_abbreviations[1:],
                                    re.IGNORECASE),
             'Do': re.compile(self.locale.ordinal_day_re),
+            'dddd': self._choice_re(self.locale.day_names[1:], re.IGNORECASE),
+            'ddd': self._choice_re(self.locale.day_abbreviations[1:],
+                                   re.IGNORECASE),
+            'd' : re.compile("[1-7]"),
             'a': self._choice_re(
                 (self.locale.meridians['am'], self.locale.meridians['pm'])
             ),
@@ -88,11 +84,10 @@ class DateTimeParser(object):
             time_parts = re.split('[+-]', time_string, 1)
             has_tz = len(time_parts) > 1
             has_seconds = time_parts[0].count(':') > 1
-            has_subseconds = '.' in time_parts[0]
+            has_subseconds = re.search('[.,]', time_parts[0])
 
             if has_subseconds:
-                subseconds_token = 'S' * min(len(re.split('\D+', time_parts[0].split('.')[1], 1)[0]), 6)
-                formats = ['YYYY-MM-DDTHH:mm:ss.%s' % subseconds_token]
+                formats = ['YYYY-MM-DDTHH:mm:ss%sS' % has_subseconds.group()]
             elif has_seconds:
                 formats = ['YYYY-MM-DDTHH:mm:ss']
             else:
@@ -123,10 +118,18 @@ class DateTimeParser(object):
         # we construct a new string by replacing each
         # token by its pattern:
         # 'YYYY-MM-DD' -> '(?P<YYYY>\d{4})-(?P<MM>\d{2})-(?P<DD>\d{2})'
-        fmt_pattern = fmt
         tokens = []
         offset = 0
-        for m in self._FORMAT_RE.finditer(fmt):
+
+        # Extract the bracketed expressions to be reinserted later.
+        escaped_fmt = re.sub(self._ESCAPE_RE, "#" , fmt)
+        # Any number of S is the same as one.
+        escaped_fmt = re.sub('S+', 'S', escaped_fmt)
+        escaped_data = re.findall(self._ESCAPE_RE, fmt)
+
+        fmt_pattern = escaped_fmt
+
+        for m in self._FORMAT_RE.finditer(escaped_fmt):
             token = m.group(0)
             try:
                 input_re = self._input_re_map[token]
@@ -140,9 +143,20 @@ class DateTimeParser(object):
             # are returned in the order found by finditer.
             fmt_pattern = fmt_pattern[:m.start() + offset] + input_pattern + fmt_pattern[m.end() + offset:]
             offset += len(input_pattern) - (m.end() - m.start())
-        match = re.search(fmt_pattern, string, flags=re.IGNORECASE)
+
+        final_fmt_pattern = ""
+        a = fmt_pattern.split("#")
+        b = escaped_data
+
+        # Due to the way Python splits, 'a' will always be longer
+        for i in range(len(a)):
+            final_fmt_pattern += a[i]
+            if i < len(b):
+                final_fmt_pattern += b[i][1:-1]
+
+        match = re.search(final_fmt_pattern, string, flags=re.IGNORECASE)
         if match is None:
-            raise ParserError('Failed to match \'{0}\' when parsing \'{1}\''.format(fmt_pattern, string))
+            raise ParserError('Failed to match \'{0}\' when parsing \'{1}\''.format(final_fmt_pattern, string))
         parts = {}
         for token in tokens:
             if token == 'Do':
@@ -181,18 +195,22 @@ class DateTimeParser(object):
         elif token in ['ss', 's']:
             parts['second'] = int(value)
 
-        elif token == 'SSSSSS':
-            parts['microsecond'] = int(value)
-        elif token == 'SSSSS':
-            parts['microsecond'] = int(value) * 10
-        elif token == 'SSSS':
-            parts['microsecond'] = int(value) * 100
-        elif token == 'SSS':
-            parts['microsecond'] = int(value) * 1000
-        elif token == 'SS':
-            parts['microsecond'] = int(value) * 10000
         elif token == 'S':
-            parts['microsecond'] = int(value) * 100000
+            # We have the *most significant* digits of an arbitrary-precision integer.
+            # We want the six most significant digits as an integer, rounded.
+            # FIXME: add nanosecond support somehow?
+            value = value.ljust(7, str('0'))
+
+            # floating-point (IEEE-754) defaults to half-to-even rounding
+            seventh_digit = int(value[6])
+            if seventh_digit == 5:
+                rounding = int(value[5]) % 2
+            elif seventh_digit > 5:
+                rounding = 1
+            else:
+                rounding = 0
+
+            parts['microsecond'] = int(value[:6]) + rounding
 
         elif token == 'X':
             parts['timestamp'] = int(value)
@@ -242,7 +260,7 @@ class DateTimeParser(object):
             try:
                 _datetime = self.parse(string, fmt)
                 break
-            except:
+            except ParserError:
                 pass
 
         if _datetime is None:
@@ -273,7 +291,7 @@ class DateTimeParser(object):
 
 class TzinfoParser(object):
 
-    _TZINFO_RE = re.compile('([+\-])?(\d\d):?(\d\d)')
+    _TZINFO_RE = re.compile('([+\-])?(\d\d):?(\d\d)?')
 
     @classmethod
     def parse(cls, string):
@@ -292,6 +310,8 @@ class TzinfoParser(object):
 
             if iso_match:
                 sign, hours, minutes = iso_match.groups()
+                if minutes is None:
+                    minutes = 0
                 seconds = int(hours) * 3600 + int(minutes) * 60
 
                 if sign == '-':
@@ -303,6 +323,6 @@ class TzinfoParser(object):
                 tzinfo = tz.gettz(string)
 
         if tzinfo is None:
-            raise ParserError('Could not parse timezone expression "{0}"', string)
+            raise ParserError('Could not parse timezone expression "{0}"'.format(string))
 
         return tzinfo

lib/arrow/util.py

@@ -22,6 +22,8 @@ else: # pragma: no cover
     total_seconds = _total_seconds_27
 
 def is_timestamp(value):
+    if type(value) == bool:
+        return False
     try:
         float(value)
         return True

lib/funcsigs/__init__.py

@@ -0,0 +1,829 @@
+# Copyright 2001-2013 Python Software Foundation; All Rights Reserved
+"""Function signature objects for callables
+
+Back port of Python 3.3's function signature tools from the inspect module,
+modified to be compatible with Python 2.6, 2.7 and 3.3+.
+"""
+from __future__ import absolute_import, division, print_function
+import itertools
+import functools
+import re
+import types
+
+try:
+    from collections import OrderedDict
+except ImportError:
+    from ordereddict import OrderedDict
+
+from funcsigs.version import __version__
+
+__all__ = ['BoundArguments', 'Parameter', 'Signature', 'signature']
+
+
+_WrapperDescriptor = type(type.__call__)
+_MethodWrapper = type(all.__call__)
+
+_NonUserDefinedCallables = (_WrapperDescriptor,
+                            _MethodWrapper,
+                            types.BuiltinFunctionType)
+
+
+def formatannotation(annotation, base_module=None):
+    if isinstance(annotation, type):
+        if annotation.__module__ in ('builtins', '__builtin__', base_module):
+            return annotation.__name__
+        return annotation.__module__+'.'+annotation.__name__
+    return repr(annotation)
+
+
+def _get_user_defined_method(cls, method_name, *nested):
+    try:
+        if cls is type:
+            return
+        meth = getattr(cls, method_name)
+        for name in nested:
+            meth = getattr(meth, name, meth)
+    except AttributeError:
+        return
+    else:
+        if not isinstance(meth, _NonUserDefinedCallables):
+            # Once '__signature__' will be added to 'C'-level
+            # callables, this check won't be necessary
+            return meth
+
+
+def signature(obj):
+    '''Get a signature object for the passed callable.'''
+
+    if not callable(obj):
+        raise TypeError('{0!r} is not a callable object'.format(obj))
+
+    if isinstance(obj, types.MethodType):
+        sig = signature(obj.__func__)
+        if obj.__self__ is None:
+            # Unbound method - preserve as-is.
+            return sig
+        else:
+            # Bound method. Eat self - if we can.
+            params = tuple(sig.parameters.values())
+
+            if not params or params[0].kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
+                raise ValueError('invalid method signature')
+
+            kind = params[0].kind
+            if kind in (_POSITIONAL_OR_KEYWORD, _POSITIONAL_ONLY):
+                # Drop first parameter:
+                # '(p1, p2[, ...])' -> '(p2[, ...])'
+                params = params[1:]
+            else:
+                if kind is not _VAR_POSITIONAL:
+                    # Unless we add a new parameter type we never
+                    # get here
+                    raise ValueError('invalid argument type')
+                # It's a var-positional parameter.
+                # Do nothing. '(*args[, ...])' -> '(*args[, ...])'
+
+            return sig.replace(parameters=params)
+
+    try:
+        sig = obj.__signature__
+    except AttributeError:
+        pass
+    else:
+        if sig is not None:
+            return sig
+
+    try:
+        # Was this function wrapped by a decorator?
+        wrapped = obj.__wrapped__
+    except AttributeError:
+        pass
+    else:
+        return signature(wrapped)
+
+    if isinstance(obj, types.FunctionType):
+        return Signature.from_function(obj)
+
+    if isinstance(obj, functools.partial):
+        sig = signature(obj.func)
+
+        new_params = OrderedDict(sig.parameters.items())
+
+        partial_args = obj.args or ()
+        partial_keywords = obj.keywords or {}
+        try:
+            ba = sig.bind_partial(*partial_args, **partial_keywords)
+        except TypeError as ex:
+            msg = 'partial object {0!r} has incorrect arguments'.format(obj)
+            raise ValueError(msg)
+
+        for arg_name, arg_value in ba.arguments.items():
+            param = new_params[arg_name]
+            if arg_name in partial_keywords:
+                # We set a new default value, because the following code
+                # is correct:
+                #
+                #   >>> def foo(a): print(a)
+                #   >>> print(partial(partial(foo, a=10), a=20)())
+                #   20
+                #   >>> print(partial(partial(foo, a=10), a=20)(a=30))
+                #   30
+                #
+                # So, with 'partial' objects, passing a keyword argument is
+                # like setting a new default value for the corresponding
+                # parameter
+                #
+                # We also mark this parameter with '_partial_kwarg'
+                # flag.  Later, in '_bind', the 'default' value of this
+                # parameter will be added to 'kwargs', to simulate
+                # the 'functools.partial' real call.
+                new_params[arg_name] = param.replace(default=arg_value,
+                                                     _partial_kwarg=True)
+
+            elif (param.kind not in (_VAR_KEYWORD, _VAR_POSITIONAL) and
+                            not param._partial_kwarg):
+                new_params.pop(arg_name)
+
+        return sig.replace(parameters=new_params.values())
+
+    sig = None
+    if isinstance(obj, type):
+        # obj is a class or a metaclass
+
+        # First, let's see if it has an overloaded __call__ defined
+        # in its metaclass
+        call = _get_user_defined_method(type(obj), '__call__')
+        if call is not None:
+            sig = signature(call)
+        else:
+            # Now we check if the 'obj' class has a '__new__' method
+            new = _get_user_defined_method(obj, '__new__')
+            if new is not None:
+                sig = signature(new)
+            else:
+                # Finally, we should have at least __init__ implemented
+                init = _get_user_defined_method(obj, '__init__')
+                if init is not None:
+                    sig = signature(init)
+    elif not isinstance(obj, _NonUserDefinedCallables):
+        # An object with __call__
+        # We also check that the 'obj' is not an instance of
+        # _WrapperDescriptor or _MethodWrapper to avoid
+        # infinite recursion (and even potential segfault)
+        call = _get_user_defined_method(type(obj), '__call__', 'im_func')
+        if call is not None:
+            sig = signature(call)
+
+    if sig is not None:
+        # For classes and objects we skip the first parameter of their
+        # __call__, __new__, or __init__ methods
+        return sig.replace(parameters=tuple(sig.parameters.values())[1:])
+
+    if isinstance(obj, types.BuiltinFunctionType):
+        # Raise a nicer error message for builtins
+        msg = 'no signature found for builtin function {0!r}'.format(obj)
+        raise ValueError(msg)
+
+    raise ValueError('callable {0!r} is not supported by signature'.format(obj))
+
+
+class _void(object):
+    '''A private marker - used in Parameter & Signature'''
+
+
+class _empty(object):
+    pass
+
+
+class _ParameterKind(int):
+    def __new__(self, *args, **kwargs):
+        obj = int.__new__(self, *args)
+        obj._name = kwargs['name']
+        return obj
+
+    def __str__(self):
+        return self._name
+
+    def __repr__(self):
+        return '<_ParameterKind: {0!r}>'.format(self._name)
+
+
+_POSITIONAL_ONLY        = _ParameterKind(0, name='POSITIONAL_ONLY')
+_POSITIONAL_OR_KEYWORD  = _ParameterKind(1, name='POSITIONAL_OR_KEYWORD')
+_VAR_POSITIONAL         = _ParameterKind(2, name='VAR_POSITIONAL')
+_KEYWORD_ONLY           = _ParameterKind(3, name='KEYWORD_ONLY')
+_VAR_KEYWORD            = _ParameterKind(4, name='VAR_KEYWORD')
+
+
+class Parameter(object):
+    '''Represents a parameter in a function signature.
+
+    Has the following public attributes:
+
+    * name : str
+        The name of the parameter as a string.
+    * default : object
+        The default value for the parameter if specified.  If the
+        parameter has no default value, this attribute is not set.
+    * annotation
+        The annotation for the parameter if specified.  If the
+        parameter has no annotation, this attribute is not set.
+    * kind : str
+        Describes how argument values are bound to the parameter.
+        Possible values: `Parameter.POSITIONAL_ONLY`,
+        `Parameter.POSITIONAL_OR_KEYWORD`, `Parameter.VAR_POSITIONAL`,
+        `Parameter.KEYWORD_ONLY`, `Parameter.VAR_KEYWORD`.
+    '''
+
+    __slots__ = ('_name', '_kind', '_default', '_annotation', '_partial_kwarg')
+
+    POSITIONAL_ONLY         = _POSITIONAL_ONLY
+    POSITIONAL_OR_KEYWORD   = _POSITIONAL_OR_KEYWORD
+    VAR_POSITIONAL          = _VAR_POSITIONAL
+    KEYWORD_ONLY            = _KEYWORD_ONLY
+    VAR_KEYWORD             = _VAR_KEYWORD
+
+    empty = _empty
+
+    def __init__(self, name, kind, default=_empty, annotation=_empty,
+                 _partial_kwarg=False):
+
+        if kind not in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD,
+                        _VAR_POSITIONAL, _KEYWORD_ONLY, _VAR_KEYWORD):
+            raise ValueError("invalid value for 'Parameter.kind' attribute")
+        self._kind = kind
+
+        if default is not _empty:
+            if kind in (_VAR_POSITIONAL, _VAR_KEYWORD):
+                msg = '{0} parameters cannot have default values'.format(kind)
+                raise ValueError(msg)
+        self._default = default
+        self._annotation = annotation
+
+        if name is None:
+            if kind != _POSITIONAL_ONLY:
+                raise ValueError("None is not a valid name for a "
+                                 "non-positional-only parameter")
+            self._name = name
+        else:
+            name = str(name)
+            if kind != _POSITIONAL_ONLY and not re.match(r'[a-z_]\w*$', name, re.I):
+                msg = '{0!r} is not a valid parameter name'.format(name)
+                raise ValueError(msg)
+            self._name = name
+
+        self._partial_kwarg = _partial_kwarg
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def default(self):
+        return self._default
+
+    @property
+    def annotation(self):
+        return self._annotation
+
+    @property
+    def kind(self):
+        return self._kind
+
+    def replace(self, name=_void, kind=_void, annotation=_void,
+                default=_void, _partial_kwarg=_void):
+        '''Creates a customized copy of the Parameter.'''
+
+        if name is _void:
+            name = self._name
+
+        if kind is _void:
+            kind = self._kind
+
+        if annotation is _void:
+            annotation = self._annotation
+
+        if default is _void:
+            default = self._default
+
+        if _partial_kwarg is _void:
+            _partial_kwarg = self._partial_kwarg
+
+        return type(self)(name, kind, default=default, annotation=annotation,
+                          _partial_kwarg=_partial_kwarg)
+
+    def __str__(self):
+        kind = self.kind
+
+        formatted = self._name
+        if kind == _POSITIONAL_ONLY:
+            if formatted is None:
+                formatted = ''
+            formatted = '<{0}>'.format(formatted)
+
+        # Add annotation and default value
+        if self._annotation is not _empty:
+            formatted = '{0}:{1}'.format(formatted,
+                                       formatannotation(self._annotation))
+
+        if self._default is not _empty:
+            formatted = '{0}={1}'.format(formatted, repr(self._default))
+
+        if kind == _VAR_POSITIONAL:
+            formatted = '*' + formatted
+        elif kind == _VAR_KEYWORD:
+            formatted = '**' + formatted
+
+        return formatted
+
+    def __repr__(self):
+        return '<{0} at {1:#x} {2!r}>'.format(self.__class__.__name__,
+                                           id(self), self.name)
+
+    def __hash__(self):
+        msg = "unhashable type: '{0}'".format(self.__class__.__name__)
+        raise TypeError(msg)
+
+    def __eq__(self, other):
+        return (issubclass(other.__class__, Parameter) and
+                self._name == other._name and
+                self._kind == other._kind and
+                self._default == other._default and
+                self._annotation == other._annotation)
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+
+class BoundArguments(object):
+    '''Result of `Signature.bind` call.  Holds the mapping of arguments
+    to the function's parameters.
+
+    Has the following public attributes:
+
+    * arguments : OrderedDict
+        An ordered mutable mapping of parameters' names to arguments' values.
+        Does not contain arguments' default values.
+    * signature : Signature
+        The Signature object that created this instance.
+    * args : tuple
+        Tuple of positional arguments values.
+    * kwargs : dict
+        Dict of keyword arguments values.
+    '''
+
+    def __init__(self, signature, arguments):
+        self.arguments = arguments
+        self._signature = signature
+
+    @property
+    def signature(self):
+        return self._signature
+
+    @property
+    def args(self):
+        args = []
+        for param_name, param in self._signature.parameters.items():
+            if (param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY) or
+                                                    param._partial_kwarg):
+                # Keyword arguments mapped by 'functools.partial'
+                # (Parameter._partial_kwarg is True) are mapped
+                # in 'BoundArguments.kwargs', along with VAR_KEYWORD &
+                # KEYWORD_ONLY
+                break
+
+            try:
+                arg = self.arguments[param_name]
+            except KeyError:
+                # We're done here. Other arguments
+                # will be mapped in 'BoundArguments.kwargs'
+                break
+            else:
+                if param.kind == _VAR_POSITIONAL:
+                    # *args
+                    args.extend(arg)
+                else:
+                    # plain argument
+                    args.append(arg)
+
+        return tuple(args)
+
+    @property
+    def kwargs(self):
+        kwargs = {}
+        kwargs_started = False
+        for param_name, param in self._signature.parameters.items():
+            if not kwargs_started:
+                if (param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY) or
+                                                param._partial_kwarg):
+                    kwargs_started = True
+                else:
+                    if param_name not in self.arguments:
+                        kwargs_started = True
+                        continue
+
+            if not kwargs_started:
+                continue
+
+            try:
+                arg = self.arguments[param_name]
+            except KeyError:
+                pass
+            else:
+                if param.kind == _VAR_KEYWORD:
+                    # **kwargs
+                    kwargs.update(arg)
+                else:
+                    # plain keyword argument
+                    kwargs[param_name] = arg
+
+        return kwargs
+
+    def __hash__(self):
+        msg = "unhashable type: '{0}'".format(self.__class__.__name__)
+        raise TypeError(msg)
+
+    def __eq__(self, other):
+        return (issubclass(other.__class__, BoundArguments) and
+                self.signature == other.signature and
+                self.arguments == other.arguments)
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+
+class Signature(object):
+    '''A Signature object represents the overall signature of a function.
+    It stores a Parameter object for each parameter accepted by the
+    function, as well as information specific to the function itself.
+
+    A Signature object has the following public attributes and methods:
+
+    * parameters : OrderedDict
+        An ordered mapping of parameters' names to the corresponding
+        Parameter objects (keyword-only arguments are in the same order
+        as listed in `code.co_varnames`).
+    * return_annotation : object
+        The annotation for the return type of the function if specified.
+        If the function has no annotation for its return type, this
+        attribute is not set.
+    * bind(*args, **kwargs) -> BoundArguments
+        Creates a mapping from positional and keyword arguments to
+        parameters.
+    * bind_partial(*args, **kwargs) -> BoundArguments
+        Creates a partial mapping from positional and keyword arguments
+        to parameters (simulating 'functools.partial' behavior.)
+    '''
+
+    __slots__ = ('_return_annotation', '_parameters')
+
+    _parameter_cls = Parameter
+    _bound_arguments_cls = BoundArguments
+
+    empty = _empty
+
+    def __init__(self, parameters=None, return_annotation=_empty,
+                 __validate_parameters__=True):
+        '''Constructs Signature from the given list of Parameter
+        objects and 'return_annotation'.  All arguments are optional.
+        '''
+
+        if parameters is None:
+            params = OrderedDict()
+        else:
+            if __validate_parameters__:
+                params = OrderedDict()
+                top_kind = _POSITIONAL_ONLY
+
+                for idx, param in enumerate(parameters):
+                    kind = param.kind
+                    if kind < top_kind:
+                        msg = 'wrong parameter order: {0} before {1}'
+                        msg = msg.format(top_kind, param.kind)
+                        raise ValueError(msg)
+                    else:
+                        top_kind = kind
+
+                    name = param.name
+                    if name is None:
+                        name = str(idx)
+                        param = param.replace(name=name)
+
+                    if name in params:
+                        msg = 'duplicate parameter name: {0!r}'.format(name)
+                        raise ValueError(msg)
+                    params[name] = param
+            else:
+                params = OrderedDict(((param.name, param)
+                                                for param in parameters))
+
+        self._parameters = params
+        self._return_annotation = return_annotation
+
+    @classmethod
+    def from_function(cls, func):
+        '''Constructs Signature for the given python function'''
+
+        if not isinstance(func, types.FunctionType):
+            raise TypeError('{0!r} is not a Python function'.format(func))
+
+        Parameter = cls._parameter_cls
+
+        # Parameter information.
+        func_code = func.__code__
+        pos_count = func_code.co_argcount
+        arg_names = func_code.co_varnames
+        positional = tuple(arg_names[:pos_count])
+        keyword_only_count = getattr(func_code, 'co_kwonlyargcount', 0)
+        keyword_only = arg_names[pos_count:(pos_count + keyword_only_count)]
+        annotations = getattr(func, '__annotations__', {})
+        defaults = func.__defaults__
+        kwdefaults = getattr(func, '__kwdefaults__', None)
+
+        if defaults:
+            pos_default_count = len(defaults)
+        else:
+            pos_default_count = 0
+
+        parameters = []
+
+        # Non-keyword-only parameters w/o defaults.
+        non_default_count = pos_count - pos_default_count
+        for name in positional[:non_default_count]:
+            annotation = annotations.get(name, _empty)
+            parameters.append(Parameter(name, annotation=annotation,
+                                        kind=_POSITIONAL_OR_KEYWORD))
+
+        # ... w/ defaults.
+        for offset, name in enumerate(positional[non_default_count:]):
+            annotation = annotations.get(name, _empty)
+            parameters.append(Parameter(name, annotation=annotation,
+                                        kind=_POSITIONAL_OR_KEYWORD,
+                                        default=defaults[offset]))
+
+        # *args
+        if func_code.co_flags & 0x04:
+            name = arg_names[pos_count + keyword_only_count]
+            annotation = annotations.get(name, _empty)
+            parameters.append(Parameter(name, annotation=annotation,
+                                        kind=_VAR_POSITIONAL))
+
+        # Keyword-only parameters.
+        for name in keyword_only:
+            default = _empty
+            if kwdefaults is not None:
+                default = kwdefaults.get(name, _empty)
+
+            annotation = annotations.get(name, _empty)
+            parameters.append(Parameter(name, annotation=annotation,
+                                        kind=_KEYWORD_ONLY,
+                                        default=default))
+        # **kwargs
+        if func_code.co_flags & 0x08:
+            index = pos_count + keyword_only_count
+            if func_code.co_flags & 0x04:
+                index += 1
+
+            name = arg_names[index]
+            annotation = annotations.get(name, _empty)
+            parameters.append(Parameter(name, annotation=annotation,
+                                        kind=_VAR_KEYWORD))
+
+        return cls(parameters,
+                   return_annotation=annotations.get('return', _empty),
+                   __validate_parameters__=False)
+
+    @property
+    def parameters(self):
+        try:
+            return types.MappingProxyType(self._parameters)
+        except AttributeError:
+            return OrderedDict(self._parameters.items())
+
+    @property
+    def return_annotation(self):
+        return self._return_annotation
+
+    def replace(self, parameters=_void, return_annotation=_void):
+        '''Creates a customized copy of the Signature.
+        Pass 'parameters' and/or 'return_annotation' arguments
+        to override them in the new copy.
+        '''
+
+        if parameters is _void:
+            parameters = self.parameters.values()
+
+        if return_annotation is _void:
+            return_annotation = self._return_annotation
+
+        return type(self)(parameters,
+                          return_annotation=return_annotation)
+
+    def __hash__(self):
+        msg = "unhashable type: '{0}'".format(self.__class__.__name__)
+        raise TypeError(msg)
+
+    def __eq__(self, other):
+        if (not issubclass(type(other), Signature) or
+                    self.return_annotation != other.return_annotation or
+                    len(self.parameters) != len(other.parameters)):
+            return False
+
+        other_positions = dict((param, idx)
+                           for idx, param in enumerate(other.parameters.keys()))
+
+        for idx, (param_name, param) in enumerate(self.parameters.items()):
+            if param.kind == _KEYWORD_ONLY:
+                try:
+                    other_param = other.parameters[param_name]
+                except KeyError:
+                    return False
+                else:
+                    if param != other_param:
+                        return False
+            else:
+                try:
+                    other_idx = other_positions[param_name]
+                except KeyError:
+                    return False
+                else:
+                    if (idx != other_idx or
+                                    param != other.parameters[param_name]):
+                        return False
+
+        return True
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def _bind(self, args, kwargs, partial=False):
+        '''Private method.  Don't use directly.'''
+
+        arguments = OrderedDict()
+
+        parameters = iter(self.parameters.values())
+        parameters_ex = ()
+        arg_vals = iter(args)
+
+        if partial:
+            # Support for binding arguments to 'functools.partial' objects.
+            # See 'functools.partial' case in 'signature()' implementation
+            # for details.
+            for param_name, param in self.parameters.items():
+                if (param._partial_kwarg and param_name not in kwargs):
+                    # Simulating 'functools.partial' behavior
+                    kwargs[param_name] = param.default
+
+        while True:
+            # Let's iterate through the positional arguments and corresponding
+            # parameters
+            try:
+                arg_val = next(arg_vals)
+            except StopIteration:
+                # No more positional arguments
+                try:
+                    param = next(parameters)
+                except StopIteration:
+                    # No more parameters. That's it. Just need to check that
+                    # we have no `kwargs` after this while loop
+                    break
+                else:
+                    if param.kind == _VAR_POSITIONAL:
+                        # That's OK, just empty *args.  Let's start parsing
+                        # kwargs
+                        break
+                    elif param.name in kwargs:
+                        if param.kind == _POSITIONAL_ONLY:
+                            msg = '{arg!r} parameter is positional only, ' \
+                                  'but was passed as a keyword'
+                            msg = msg.format(arg=param.name)
+                            raise TypeError(msg)
+                        parameters_ex = (param,)
+                        break
+                    elif (param.kind == _VAR_KEYWORD or
+                                                param.default is not _empty):
+                        # That's fine too - we have a default value for this
+                        # parameter.  So, lets start parsing `kwargs`, starting
+                        # with the current parameter
+                        parameters_ex = (param,)
+                        break
+                    else:
+                        if partial:
+                            parameters_ex = (param,)
+                            break
+                        else:
+                            msg = '{arg!r} parameter lacking default value'
+                            msg = msg.format(arg=param.name)
+                            raise TypeError(msg)
+            else:
+                # We have a positional argument to process
+                try:
+                    param = next(parameters)
+                except StopIteration:
+                    raise TypeError('too many positional arguments')
+                else:
+                    if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
+                        # Looks like we have no parameter for this positional
+                        # argument
+                        raise TypeError('too many positional arguments')
+
+                    if param.kind == _VAR_POSITIONAL:
+                        # We have an '*args'-like argument, let's fill it with
+                        # all positional arguments we have left and move on to
+                        # the next phase
+                        values = [arg_val]
+                        values.extend(arg_vals)
+                        arguments[param.name] = tuple(values)
+                        break
+
+                    if param.name in kwargs:
+                        raise TypeError('multiple values for argument '
+                                        '{arg!r}'.format(arg=param.name))
+
+                    arguments[param.name] = arg_val
+
+        # Now, we iterate through the remaining parameters to process
+        # keyword arguments
+        kwargs_param = None
+        for param in itertools.chain(parameters_ex, parameters):
+            if param.kind == _POSITIONAL_ONLY:
+                # This should never happen in case of a properly built
+                # Signature object (but let's have this check here
+                # to ensure correct behaviour just in case)
+                raise TypeError('{arg!r} parameter is positional only, '
+                                'but was passed as a keyword'. \
+                                format(arg=param.name))
+
+            if param.kind == _VAR_KEYWORD:
+                # Memorize that we have a '**kwargs'-like parameter
+                kwargs_param = param
+                continue
+
+            param_name = param.name
+            try:
+                arg_val = kwargs.pop(param_name)
+            except KeyError:
+                # We have no value for this parameter.  It's fine though,
+                # if it has a default value, or it is an '*args'-like
+                # parameter, left alone by the processing of positional
+                # arguments.
+                if (not partial and param.kind != _VAR_POSITIONAL and
+                                                    param.default is _empty):
+                    raise TypeError('{arg!r} parameter lacking default value'. \
+                                    format(arg=param_name))
+
+            else:
+                arguments[param_name] = arg_val
+
+        if kwargs:
+            if kwargs_param is not None:
+                # Process our '**kwargs'-like parameter
+                arguments[kwargs_param.name] = kwargs
+            else:
+                raise TypeError('too many keyword arguments %r' % kwargs)
+
+        return self._bound_arguments_cls(self, arguments)
+
+    def bind(*args, **kwargs):
+        '''Get a BoundArguments object, that maps the passed `args`
+        and `kwargs` to the function's signature.  Raises `TypeError`
+        if the passed arguments can not be bound.
+        '''
+        return args[0]._bind(args[1:], kwargs)
+
+    def bind_partial(self, *args, **kwargs):
+        '''Get a BoundArguments object, that partially maps the
+        passed `args` and `kwargs` to the function's signature.
+        Raises `TypeError` if the passed arguments can not be bound.
+        '''
+        return self._bind(args, kwargs, partial=True)
+
+    def __str__(self):
+        result = []
+        render_kw_only_separator = True
+        for idx, param in enumerate(self.parameters.values()):
+            formatted = str(param)
+
+            kind = param.kind
+            if kind == _VAR_POSITIONAL:
+                # OK, we have an '*args'-like parameter, so we won't need
+                # a '*' to separate keyword-only arguments
+                render_kw_only_separator = False
+            elif kind == _KEYWORD_ONLY and render_kw_only_separator:
+                # We have a keyword-only parameter to render and we haven't
+                # rendered an '*args'-like parameter before, so add a '*'
+                # separator to the parameters list ("foo(arg1, *, arg2)" case)
+                result.append('*')
+                # This condition should be only triggered once, so
+                # reset the flag
+                render_kw_only_separator = False
+
+            result.append(formatted)
+
+        rendered = '({0})'.format(', '.join(result))
+
+        if self.return_annotation is not _empty:
+            anno = formatannotation(self.return_annotation)
+            rendered += ' -> {0}'.format(anno)
+
+        return rendered

lib/funcsigs/version.py

@@ -0,0 +1 @@
+__version__ = "1.0.2"

lib/plexapi/__init__.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+import logging
+import os
+from logging.handlers import RotatingFileHandler
+from platform import uname
+from plexapi.config import PlexConfig, reset_base_headers
+from plexapi.utils import SecretsFilter
+from uuid import getnode
+
+# Load User Defined Config
+DEFAULT_CONFIG_PATH = os.path.expanduser('~/.config/plexapi/config.ini')
+CONFIG_PATH = os.environ.get('PLEXAPI_CONFIG_PATH', DEFAULT_CONFIG_PATH)
+CONFIG = PlexConfig(CONFIG_PATH)
+
+# PlexAPI Settings
+PROJECT = 'PlexAPI'
+VERSION = '3.0.6'
+TIMEOUT = CONFIG.get('plexapi.timeout', 30, int)
+X_PLEX_CONTAINER_SIZE = CONFIG.get('plexapi.container_size', 100, int)
+
+# Plex Header Configuation
+X_PLEX_PROVIDES = CONFIG.get('header.provides', 'controller')
+X_PLEX_PLATFORM = CONFIG.get('header.platorm', uname()[0])
+X_PLEX_PLATFORM_VERSION = CONFIG.get('header.platform_version', uname()[2])
+X_PLEX_PRODUCT = CONFIG.get('header.product', PROJECT)
+X_PLEX_VERSION = CONFIG.get('header.version', VERSION)
+X_PLEX_DEVICE = CONFIG.get('header.device', X_PLEX_PLATFORM)
+X_PLEX_DEVICE_NAME = CONFIG.get('header.device_name', uname()[1])
+X_PLEX_IDENTIFIER = CONFIG.get('header.identifier', str(hex(getnode())))
+BASE_HEADERS = reset_base_headers()
+
+# Logging Configuration
+log = logging.getLogger('plexapi')
+logfile = CONFIG.get('log.path')
+logformat = CONFIG.get('log.format', '%(asctime)s %(module)12s:%(lineno)-4s %(levelname)-9s %(message)s')
+loglevel = CONFIG.get('log.level', 'INFO').upper()
+loghandler = logging.NullHandler()
+
+if logfile:  # pragma: no cover
+    logbackups = CONFIG.get('log.backup_count', 3, int)
+    logbytes = CONFIG.get('log.rotate_bytes', 512000, int)
+    loghandler = RotatingFileHandler(os.path.expanduser(logfile), 'a', logbytes, logbackups)
+
+loghandler.setFormatter(logging.Formatter(logformat))
+log.addHandler(loghandler)
+log.setLevel(loglevel)
+logfilter = SecretsFilter()
+if CONFIG.get('log.show_secrets', '').lower() != 'true':
+    log.addFilter(logfilter)

lib/plexapi/alert.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+import json
+import threading
+import websocket
+from plexapi import log
+
+
+class AlertListener(threading.Thread):
+    """ Creates a websocket connection to the PlexServer to optionally recieve alert 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
+        alerts you must call .start() on the object once it's created. When calling
+        `PlexServer.startAlertListener()`, the thread will be started for you.
+
+        Parameters:
+            server (:class:`~plexapi.server.PlexServer`): PlexServer this listener is connected to.
+            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'
+
+    def __init__(self, server, callback=None):
+        super(AlertListener, self).__init__()
+        self.daemon = True
+        self._server = server
+        self._callback = callback
+        self._ws = None
+
+    def run(self):
+        # create the websocket connection
+        url = self._server.url(self.key, includeToken=True).replace('http', 'ws')
+        log.info('Starting AlertListener: %s', url)
+        self._ws = websocket.WebSocketApp(url, on_message=self._onMessage,
+                                          on_error=self._onError)
+        self._ws.run_forever()
+
+    def stop(self):
+        """ Stop the AlertListener thread. Once the notifier is stopped, it cannot be diractly
+            started again. You must call :func:`plexapi.server.PlexServer.startAlertListener()`
+            from a PlexServer instance.
+        """
+        log.info('Stopping AlertListener.')
+        self._ws.close()
+
+    def _onMessage(self, ws, message):
+        """ Called when websocket message is recieved. """
+        try:
+            data = json.loads(message)['NotificationContainer']
+            log.debug('Alert: %s %s %s', *data)
+            if self._callback:
+                self._callback(data)
+        except Exception as err:  # pragma: no cover
+            log.error('AlertListener Msg Error: %s', err)
+
+    def _onError(self, ws, err):  # pragma: no cover
+        """ Called when websocket error is recieved. """
+        log.error('AlertListener Error: %s' % err)

lib/plexapi/audio.py

@@ -0,0 +1,304 @@
+# -*- coding: utf-8 -*-
+from plexapi import media, utils
+from plexapi.base import Playable, PlexPartialObject
+
+
+class Audio(PlexPartialObject):
+    """ Base class for audio :class:`~plexapi.audio.Artist`, :class:`~plexapi.audio.Album`
+        and :class:`~plexapi.audio.Track` objects.
+
+        Attributes:
+            addedAt (datetime): Datetime this item was added to the library.
+            index (sting): Index Number (often the track number).
+            key (str): API URL (/library/metadata/<ratingkey>).
+            lastViewedAt (datetime): Datetime item was last accessed.
+            librarySectionID (int): :class:`~plexapi.library.LibrarySection` ID.
+            listType (str): Hardcoded as 'audio' (useful for search filters).
+            ratingKey (int): Unique key identifying this item.
+            summary (str): Summary of the artist, track, or album.
+            thumb (str): URL to thumbnail image.
+            title (str): Artist, Album or Track title. (Jason Mraz, We Sing, Lucky, etc.)
+            titleSort (str): Title to use when sorting (defaults to title).
+            type (str): 'artist', 'album', or 'track'.
+            updatedAt (datatime): Datetime this item was updated.
+            viewCount (int): Count of times this item was accessed.
+    """
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.listType = 'audio'
+        self.addedAt = utils.toDatetime(data.attrib.get('addedAt'))
+        self.index = data.attrib.get('index')
+        self.key = data.attrib.get('key')
+        self.lastViewedAt = utils.toDatetime(data.attrib.get('lastViewedAt'))
+        self.librarySectionID = data.attrib.get('librarySectionID')
+        self.ratingKey = utils.cast(int, data.attrib.get('ratingKey'))
+        self.summary = data.attrib.get('summary')
+        self.thumb = data.attrib.get('thumb')
+        self.title = data.attrib.get('title')
+        self.titleSort = data.attrib.get('titleSort', self.title)
+        self.type = data.attrib.get('type')
+        self.updatedAt = utils.toDatetime(data.attrib.get('updatedAt'))
+        self.viewCount = utils.cast(int, data.attrib.get('viewCount', 0))
+
+    @property
+    def thumbUrl(self):
+        """ Return url to for the thumbnail image. """
+        key = self.firstAttr('thumb', 'parentThumb', 'granparentThumb')
+        return self._server.url(key, includeToken=True) if key else None
+
+    @property
+    def artUrl(self):
+        """ Return the first art url starting on the most specific for that item."""
+        art = self.firstAttr('art', 'grandparentArt')
+        return self._server.url(art, includeToken=True) if art else None
+
+    def url(self, part):
+        """ Returns the full URL for this audio item. Typically used for getting a specific track. """
+        return self._server.url(part, includeToken=True) if part else None
+
+
+@utils.registerPlexObject
+class Artist(Audio):
+    """ Represents a single audio artist.
+
+        Attributes:
+            TAG (str): 'Directory'
+            TYPE (str): 'artist'
+            art (str): Artist artwork (/library/metadata/<ratingkey>/art/<artid>)
+            countries (list): List of :class:`~plexapi.media.Country` objects this artist respresents.
+            genres (list): List of :class:`~plexapi.media.Genre` objects this artist respresents.
+            guid (str): Unknown (unique ID; com.plexapp.agents.plexmusic://gracenote/artist/05517B8701668D28?lang=en)
+            key (str): API URL (/library/metadata/<ratingkey>).
+            location (str): Filepath this artist is found on disk.
+            similar (list): List of :class:`~plexapi.media.Similar` artists.
+    """
+    TAG = 'Directory'
+    TYPE = 'artist'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        Audio._loadData(self, data)
+        self.art = data.attrib.get('art')
+        self.guid = data.attrib.get('guid')
+        self.key = self.key.replace('/children', '')  # FIX_BUG_50
+        self.locations = self.listAttrs(data, 'path', etag='Location')
+        self.countries = self.findItems(data, media.Country)
+        self.genres = self.findItems(data, media.Genre)
+        self.similar = self.findItems(data, media.Similar)
+        self.collections = self.findItems(data, media.Collection)
+
+    def __iter__(self):
+        for album in self.albums():
+            yield album
+
+    def album(self, title):
+        """ Returns the :class:`~plexapi.audio.Album` that matches the specified title.
+
+            Parameters:
+                title (str): Title of the album to return.
+        """
+        key = '%s/children' % self.key
+        return self.fetchItem(key, title__iexact=title)
+
+    def albums(self, **kwargs):
+        """ Returns a list of :class:`~plexapi.audio.Album` objects by this artist. """
+        key = '%s/children' % self.key
+        return self.fetchItems(key, **kwargs)
+
+    def track(self, title):
+        """ Returns the :class:`~plexapi.audio.Track` that matches the specified title.
+
+            Parameters:
+                title (str): Title of the track to return.
+        """
+        key = '%s/allLeaves' % self.key
+        return self.fetchItem(key, title__iexact=title)
+
+    def tracks(self, **kwargs):
+        """ Returns a list of :class:`~plexapi.audio.Track` objects by this artist. """
+        key = '%s/allLeaves' % self.key
+        return self.fetchItems(key, **kwargs)
+
+    def get(self, title):
+        """ Alias of :func:`~plexapi.audio.Artist.track`. """
+        return self.track(title)
+
+    def download(self, savepath=None, keep_orginal_name=False, **kwargs):
+        """ Downloads all tracks for this artist to the specified location.
+
+            Parameters:
+                savepath (str): Title of the track to return.
+                keep_orginal_name (bool): Set True to keep the original filename as stored in
+                    the Plex server. False will create a new filename with the format
+                    "<Atrist> - <Album> <Track>".
+                kwargs (dict): If specified, a :func:`~plexapi.audio.Track.getStreamURL()` will
+                    be returned and the additional arguments passed in will be sent to that
+                    function. If kwargs is not specified, the media items will be downloaded
+                    and saved to disk.
+        """
+        filepaths = []
+        for album in self.albums():
+            for track in album.tracks():
+                filepaths += track.download(savepath, keep_orginal_name, **kwargs)
+        return filepaths
+
+
+@utils.registerPlexObject
+class Album(Audio):
+    """ Represents a single audio album.
+
+        Attributes:
+            TAG (str): 'Directory'
+            TYPE (str): 'album'
+            art (str): Album artwork (/library/metadata/<ratingkey>/art/<artid>)
+            genres (list): List of :class:`~plexapi.media.Genre` objects this album respresents.
+            key (str): API URL (/library/metadata/<ratingkey>).
+            originallyAvailableAt (datetime): Datetime this album was released.
+            parentKey (str): API URL of this artist.
+            parentRatingKey (int): Unique key identifying artist.
+            parentThumb (str): URL to artist thumbnail image.
+            parentTitle (str): Name of the artist for this album.
+            studio (str): Studio that released this album.
+            year (int): Year this album was released.
+    """
+    TAG = 'Directory'
+    TYPE = 'album'
+
+    def __iter__(self):
+        for track in self.tracks:
+            yield track
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        Audio._loadData(self, data)
+        self.art = data.attrib.get('art')
+        self.key = self.key.replace('/children', '')  # fixes bug #50
+        self.originallyAvailableAt = utils.toDatetime(data.attrib.get('originallyAvailableAt'), '%Y-%m-%d')
+        self.parentKey = data.attrib.get('parentKey')
+        self.parentRatingKey = data.attrib.get('parentRatingKey')
+        self.parentThumb = data.attrib.get('parentThumb')
+        self.parentTitle = data.attrib.get('parentTitle')
+        self.studio = data.attrib.get('studio')
+        self.year = utils.cast(int, data.attrib.get('year'))
+        self.genres = self.findItems(data, media.Genre)
+        self.collections = self.findItems(data, media.Collection)
+        self.labels = self.findItems(data, media.Label)
+
+    def track(self, title):
+        """ Returns the :class:`~plexapi.audio.Track` that matches the specified title.
+
+            Parameters:
+                title (str): Title of the track to return.
+        """
+        key = '%s/children' % self.key
+        return self.fetchItem(key, title__iexact=title)
+
+    def tracks(self, **kwargs):
+        """ Returns a list of :class:`~plexapi.audio.Track` objects in this album. """
+        key = '%s/children' % self.key
+        return self.fetchItems(key, **kwargs)
+
+    def get(self, title):
+        """ Alias of :func:`~plexapi.audio.Album.track`. """
+        return self.track(title)
+
+    def artist(self):
+        """ Return :func:`~plexapi.audio.Artist` of this album. """
+        return self.fetchItem(self.parentKey)
+
+    def download(self, savepath=None, keep_orginal_name=False, **kwargs):
+        """ Downloads all tracks for this artist to the specified location.
+
+            Parameters:
+                savepath (str): Title of the track to return.
+                keep_orginal_name (bool): Set True to keep the original filename as stored in
+                    the Plex server. False will create a new filename with the format
+                    "<Atrist> - <Album> <Track>".
+                kwargs (dict): If specified, a :func:`~plexapi.audio.Track.getStreamURL()` will
+                    be returned and the additional arguments passed in will be sent to that
+                    function. If kwargs is not specified, the media items will be downloaded
+                    and saved to disk.
+        """
+        filepaths = []
+        for track in self.tracks():
+            filepaths += track.download(savepath, keep_orginal_name, **kwargs)
+        return filepaths
+
+
+@utils.registerPlexObject
+class Track(Audio, Playable):
+    """ Represents a single audio track.
+
+        Attributes:
+            TAG (str): 'Directory'
+            TYPE (str): 'track'
+            art (str): Track artwork (/library/metadata/<ratingkey>/art/<artid>)
+            chapterSource (TYPE): Unknown
+            duration (int): Length of this album in seconds.
+            grandparentArt (str): Artist artowrk.
+            grandparentKey (str): Artist API URL.
+            grandparentRatingKey (str): Unique key identifying artist.
+            grandparentThumb (str): URL to artist thumbnail image.
+            grandparentTitle (str): Name of the artist for this track.
+            guid (str): Unknown (unique ID).
+            media (list): List of :class:`~plexapi.media.Media` objects for this track.
+            moods (list): List of :class:`~plexapi.media.Mood` objects for this track.
+            originalTitle (str): Original track title (if translated).
+            parentIndex (int): Album index.
+            parentKey (str): Album API URL.
+            parentRatingKey (int): Unique key identifying album.
+            parentThumb (str): URL to album thumbnail image.
+            parentTitle (str): Name of the album for this track.
+            primaryExtraKey (str): Unknown
+            ratingCount (int): Unknown
+            userRating (float): Rating of this track (0.0 - 10.0) equaling (0 stars - 5 stars)
+            viewOffset (int): Unknown
+            year (int): Year this track was released.
+            sessionKey (int): Session Key (active sessions only).
+            usernames (str): Username of person playing this track (active sessions only).
+            player (str): :class:`~plexapi.client.PlexClient` for playing track (active sessions only).
+            transcodeSessions (None): :class:`~plexapi.media.TranscodeSession` for playing
+                track (active sessions only).
+    """
+    TAG = 'Track'
+    TYPE = 'track'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        Audio._loadData(self, data)
+        Playable._loadData(self, data)
+        self.art = data.attrib.get('art')
+        self.chapterSource = data.attrib.get('chapterSource')
+        self.duration = utils.cast(int, data.attrib.get('duration'))
+        self.grandparentArt = data.attrib.get('grandparentArt')
+        self.grandparentKey = data.attrib.get('grandparentKey')
+        self.grandparentRatingKey = data.attrib.get('grandparentRatingKey')
+        self.grandparentThumb = data.attrib.get('grandparentThumb')
+        self.grandparentTitle = data.attrib.get('grandparentTitle')
+        self.guid = data.attrib.get('guid')
+        self.originalTitle = data.attrib.get('originalTitle')
+        self.parentIndex = data.attrib.get('parentIndex')
+        self.parentKey = data.attrib.get('parentKey')
+        self.parentRatingKey = data.attrib.get('parentRatingKey')
+        self.parentThumb = data.attrib.get('parentThumb')
+        self.parentTitle = data.attrib.get('parentTitle')
+        self.primaryExtraKey = data.attrib.get('primaryExtraKey')
+        self.ratingCount = utils.cast(int, data.attrib.get('ratingCount'))
+        self.userRating = utils.cast(float, data.attrib.get('userRating', 0))
+        self.viewOffset = utils.cast(int, data.attrib.get('viewOffset', 0))
+        self.year = utils.cast(int, data.attrib.get('year'))
+        self.media = self.findItems(data, media.Media)
+        self.moods = self.findItems(data, media.Mood)
+
+    def _prettyfilename(self):
+        """ Returns a filename for use in download. """
+        return '%s - %s %s' % (self.grandparentTitle, self.parentTitle, self.title)
+
+    def album(self):
+        """ Return this track's :class:`~plexapi.audio.Album`. """
+        return self.fetchItem(self.parentKey)
+
+    def artist(self):
+        """ Return this track's :class:`~plexapi.audio.Artist`. """
+        return self.fetchItem(self.grandparentKey)

lib/plexapi/base.py

@@ -0,0 +1,581 @@
+# -*- coding: utf-8 -*-
+import re
+
+from plexapi import log, utils
+from plexapi.compat import quote_plus, urlencode
+from plexapi.exceptions import BadRequest, NotFound, UnknownType, Unsupported
+from plexapi.utils import tag_helper
+
+OPERATORS = {
+    'exact': lambda v, q: v == q,
+    'iexact': lambda v, q: v.lower() == q.lower(),
+    'contains': lambda v, q: q in v,
+    'icontains': lambda v, q: q.lower() in v.lower(),
+    'ne': lambda v, q: v != q,
+    'in': lambda v, q: v in q,
+    'gt': lambda v, q: v > q,
+    'gte': lambda v, q: v >= q,
+    'lt': lambda v, q: v < q,
+    'lte': lambda v, q: v <= q,
+    'startswith': lambda v, q: v.startswith(q),
+    'istartswith': lambda v, q: v.lower().startswith(q),
+    'endswith': lambda v, q: v.endswith(q),
+    'iendswith': lambda v, q: v.lower().endswith(q),
+    'exists': lambda v, q: v is not None if q else v is None,
+    'regex': lambda v, q: re.match(q, v),
+    'iregex': lambda v, q: re.match(q, v, flags=re.IGNORECASE),
+}
+
+
+class PlexObject(object):
+    """ Base class for all Plex objects.
+
+        Parameters:
+            server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional)
+            data (ElementTree): Response from PlexServer used to build this object (optional).
+            initpath (str): Relative path requested when retrieving specified `data` (optional).
+    """
+    TAG = None      # xml element tag
+    TYPE = None     # xml element type
+    key = None      # plex relative url
+
+    def __init__(self, server, data, initpath=None):
+        self._server = server
+        self._data = data
+        self._initpath = initpath or self.key
+        self._details_key = ''
+        if data is not None:
+            self._loadData(data)
+
+    def __repr__(self):
+        uid = self._clean(self.firstAttr('_baseurl', 'key', 'id', 'playQueueID', 'uri'))
+        name = self._clean(self.firstAttr('title', 'name', 'username', 'product', 'tag', 'value'))
+        return '<%s>' % ':'.join([p for p in [self.__class__.__name__, uid, name] if p])
+
+    def __setattr__(self, attr, value):
+        # dont overwrite an attr with None unless its a private variable
+        if value is not None or attr.startswith('_') or attr not in self.__dict__:
+            self.__dict__[attr] = value
+
+    def _clean(self, value):
+        """ Clean attr value for display in __repr__. """
+        if value:
+            value = str(value).replace('/library/metadata/', '')
+            value = value.replace('/children', '')
+            return value.replace(' ', '-')[:20]
+
+    def _buildItem(self, elem, cls=None, initpath=None):
+        """ Factory function to build objects based on registered PLEXOBJECTS. """
+        # cls is specified, build the object and return
+        initpath = initpath or self._initpath
+        if cls is not None:
+            return cls(self._server, elem, initpath)
+        # cls is not specified, try looking it up in PLEXOBJECTS
+        etype = elem.attrib.get('type', elem.attrib.get('streamType'))
+        ehash = '%s.%s' % (elem.tag, etype) if etype else elem.tag
+        ecls = utils.PLEXOBJECTS.get(ehash, utils.PLEXOBJECTS.get(elem.tag))
+        # log.debug('Building %s as %s', elem.tag, ecls.__name__)
+        if ecls is not None:
+            return ecls(self._server, elem, initpath)
+        raise UnknownType("Unknown library type <%s type='%s'../>" % (elem.tag, etype))
+
+    def _buildItemOrNone(self, elem, cls=None, initpath=None):
+        """ Calls :func:`~plexapi.base.PlexObject._buildItem()` but returns
+            None if elem is an unknown type.
+        """
+        try:
+            return self._buildItem(elem, cls, initpath)
+        except UnknownType:
+            return None
+
+    def fetchItem(self, ekey, cls=None, **kwargs):
+        """ Load the specified key to find and build the first item with the
+            specified tag and attrs. If no tag or attrs are specified then
+            the first item in the result set is returned.
+
+            Parameters:
+                ekey (str or int): Path in Plex to fetch items from. If an int is passed
+                    in, the key will be translated to /library/metadata/<key>. This allows
+                    fetching an item only knowing its key-id.
+                cls (:class:`~plexapi.base.PlexObject`): If you know the class of the
+                    items to be fetched, passing this in will help the parser ensure
+                    it only returns those items. By default we convert the xml elements
+                    with the best guess PlexObjects based on tag and type attrs.
+                etag (str): Only fetch items with the specified tag.
+                **kwargs (dict): Optionally add attribute filters on the items to fetch. For
+                    example, passing in viewCount=0 will only return matching items. Filtering
+                    is done before the Python objects are built to help keep things speedy.
+                    Note: Because some attribute names are already used as arguments to this
+                    function, such as 'tag', you may still reference the attr tag byappending
+                    an underscore. For example, passing in _tag='foobar' will return all items
+                    where tag='foobar'. Also Note: Case very much matters when specifying kwargs
+                    -- Optionally, operators can be specified by append it
+                    to the end of the attribute name for more complex lookups. For example,
+                    passing in viewCount__gte=0 will return all items where viewCount >= 0.
+                    Available operations include:
+
+                    * __contains: Value contains specified arg.
+                    * __endswith: Value ends with specified arg.
+                    * __exact: Value matches specified arg.
+                    * __exists (bool): Value is or is not present in the attrs.
+                    * __gt: Value is greater than specified arg.
+                    * __gte: Value is greater than or equal to specified arg.
+                    * __icontains: Case insensative value contains specified arg.
+                    * __iendswith: Case insensative value ends with specified arg.
+                    * __iexact: Case insensative value matches specified arg.
+                    * __in: Value is in a specified list or tuple.
+                    * __iregex: Case insensative value matches the specified regular expression.
+                    * __istartswith: Case insensative value starts with specified arg.
+                    * __lt: Value is less than specified arg.
+                    * __lte: Value is less than or equal to specified arg.
+                    * __regex: Value matches the specified regular expression.
+                    * __startswith: Value starts with specified arg.
+        """
+        if isinstance(ekey, int):
+            ekey = '/library/metadata/%s' % ekey
+        for elem in self._server.query(ekey):
+            if self._checkAttrs(elem, **kwargs):
+                return self._buildItem(elem, cls, ekey)
+        clsname = cls.__name__ if cls else 'None'
+        raise NotFound('Unable to find elem: cls=%s, attrs=%s' % (clsname, kwargs))
+
+    def fetchItems(self, ekey, cls=None, **kwargs):
+        """ Load the specified key to find and build all items with the specified tag
+            and attrs. See :func:`~plexapi.base.PlexObject.fetchItem` for more details
+            on how this is used.
+        """
+        data = self._server.query(ekey)
+        return self.findItems(data, cls, ekey, **kwargs)
+
+    def findItems(self, data, cls=None, initpath=None, **kwargs):
+        """ Load the specified data to find and build all items with the specified tag
+            and attrs. See :func:`~plexapi.base.PlexObject.fetchItem` for more details
+            on how this is used.
+        """
+        # filter on cls attrs if specified
+        if cls and cls.TAG and 'tag' not in kwargs:
+            kwargs['etag'] = cls.TAG
+        if cls and cls.TYPE and 'type' not in kwargs:
+            kwargs['type'] = cls.TYPE
+        # loop through all data elements to find matches
+        items = []
+        for elem in data:
+            if self._checkAttrs(elem, **kwargs):
+                item = self._buildItemOrNone(elem, cls, initpath)
+                if item is not None:
+                    items.append(item)
+        return items
+
+    def firstAttr(self, *attrs):
+        """ Return the first attribute in attrs that is not None. """
+        for attr in attrs:
+            value = self.__dict__.get(attr)
+            if value is not None:
+                return value
+
+    def listAttrs(self, data, attr, **kwargs):
+        results = []
+        for elem in data:
+            kwargs['%s__exists' % attr] = True
+            if self._checkAttrs(elem, **kwargs):
+                results.append(elem.attrib.get(attr))
+        return results
+
+    def reload(self, key=None):
+        """ Reload the data for this object from self.key. """
+        key = key or self._details_key or self.key
+        if not key:
+            raise Unsupported('Cannot reload an object not built from a URL.')
+        self._initpath = key
+        data = self._server.query(key)
+        self._loadData(data[0])
+        return self
+
+    def _checkAttrs(self, elem, **kwargs):
+        attrsFound = {}
+        for attr, query in kwargs.items():
+            attr, op, operator = self._getAttrOperator(attr)
+            values = self._getAttrValue(elem, attr)
+            # special case query in (None, 0, '') to include missing attr
+            if op == 'exact' and not values and query in (None, 0, ''):
+                return True
+            # return if attr were looking for is missing
+            attrsFound[attr] = False
+            for value in values:
+                value = self._castAttrValue(op, query, value)
+                if operator(value, query):
+                    attrsFound[attr] = True
+                    break
+        # log.debug('Checking %s for %s found: %s', elem.tag, kwargs, attrsFound)
+        return all(attrsFound.values())
+
+    def _getAttrOperator(self, attr):
+        for op, operator in OPERATORS.items():
+            if attr.endswith('__%s' % op):
+                attr = attr.rsplit('__', 1)[0]
+                return attr, op, operator
+        # default to exact match
+        return attr, 'exact', OPERATORS['exact']
+
+    def _getAttrValue(self, elem, attrstr, results=None):
+        # log.debug('Fetching %s in %s', attrstr, elem.tag)
+        parts = attrstr.split('__', 1)
+        attr = parts[0]
+        attrstr = parts[1] if len(parts) == 2 else None
+        if attrstr:
+            results = [] if results is None else results
+            for child in [c for c in elem if c.tag.lower() == attr.lower()]:
+                results += self._getAttrValue(child, attrstr, results)
+            return [r for r in results if r is not None]
+        # check were looking for the tag
+        if attr.lower() == 'etag':
+            return [elem.tag]
+        # loop through attrs so we can perform case-insensative match
+        for _attr, value in elem.attrib.items():
+            if attr.lower() == _attr.lower():
+                return [value]
+        return []
+
+    def _castAttrValue(self, op, query, value):
+        if op == 'exists':
+            return value
+        if isinstance(query, bool):
+            return bool(int(value))
+        if isinstance(query, int) and '.' in value:
+            return float(value)
+        if isinstance(query, int):
+            return int(value)
+        if isinstance(query, float):
+            return float(value)
+        return value
+
+    def _loadData(self, data):
+        raise NotImplementedError('Abstract method not implemented.')
+
+
+class PlexPartialObject(PlexObject):
+    """ Not all objects in the Plex listings return the complete list of elements
+        for the object. This object will allow you to assume each object is complete,
+        and if the specified value you request is None it will fetch the full object
+        automatically and update itself.
+    """
+
+    def __eq__(self, other):
+        return other is not None and self.key == other.key
+
+    def __hash__(self):
+        return hash(repr(self))
+
+    def __iter__(self):
+        yield self
+
+    def __getattribute__(self, attr):
+        # Dragons inside.. :-/
+        value = super(PlexPartialObject, self).__getattribute__(attr)
+        # Check a few cases where we dont want to reload
+        if attr == 'key' or attr.startswith('_'): return value
+        if value not in (None, []): return value
+        if self.isFullObject(): return value
+        # Log the reload.
+        clsname = self.__class__.__name__
+        title = self.__dict__.get('title', self.__dict__.get('name'))
+        objname = "%s '%s'" % (clsname, title) if title else clsname
+        log.debug("Reloading %s for attr '%s'" % (objname, attr))
+        # Reload and return the value
+        self.reload()
+        return super(PlexPartialObject, self).__getattribute__(attr)
+
+    def analyze(self):
+        """ Tell Plex Media Server to performs analysis on it this item to gather
+            information. Analysis includes:
+
+            * Gather Media Properties: All of the media you add to a Library has
+                properties that are useful to know–whether it's a video file, a
+                music track, or one of your photos (container, codec, resolution, etc).
+            * Generate Default Artwork: Artwork will automatically be grabbed from a
+                video file. A background image will be pulled out as well as a
+                smaller image to be used for poster/thumbnail type purposes.
+            * Generate Video Preview Thumbnails: Video preview thumbnails are created,
+                if you have that feature enabled. Video preview thumbnails allow
+                graphical seeking in some Apps. It's also used in the Plex Web App Now
+                Playing screen to show a graphical representation of where playback
+                is. Video preview thumbnails creation is a CPU-intensive process akin
+                to transcoding the file.
+        """
+        key = '/%s/analyze' % self.key.lstrip('/')
+        self._server.query(key, method=self._server._session.put)
+
+    def isFullObject(self):
+        """ Retruns True if this is already a full object. A full object means all attributes
+            were populated from the api path representing only this item. For example, the
+            search result for a movie often only contain a portion of the attributes a full
+            object (main url) for that movie contain.
+        """
+        return not self.key or self.key == self._initpath
+
+    def isPartialObject(self):
+        """ Returns True if this is not a full object. """
+        return not self.isFullObject()
+
+    def edit(self, **kwargs):
+        """ Edit an object.
+
+            Parameters:
+                kwargs (dict): Dict of settings to edit.
+
+            Example:
+                {'type': 1,
+                 'id': movie.ratingKey,
+                 'collection[0].tag.tag': 'Super',
+                 'collection.locked': 0}
+        """
+        if 'id' not in kwargs:
+            kwargs['id'] = self.ratingKey
+        if 'type' not in kwargs:
+            kwargs['type'] = utils.searchType(self.type)
+
+        part = '/library/sections/%s/all?%s' % (self.librarySectionID,
+                                                urlencode(kwargs))
+        self._server.query(part, method=self._server._session.put)
+
+    def _edit_tags(self, tag, items, locked=True, remove=False):
+        """ Helper to edit and refresh a tags.
+
+            Parameters:
+                tag (str): tag name
+                items (list): list of tags to add
+                locked (bool): lock this field.
+                remove (bool): If this is active remove the tags in items.
+        """
+        if not isinstance(items, list):
+            items = [items]
+        value = getattr(self, tag + 's')
+        existing_cols = [t.tag for t in value if t and remove is False]
+        d = tag_helper(tag, existing_cols + items, locked, remove)
+        self.edit(**d)
+        self.refresh()
+
+    def addCollection(self, collections):
+        """ Add a collection(s).
+
+           Parameters:
+                collections (list): list of strings
+        """
+        self._edit_tags('collection', collections)
+
+    def removeCollection(self, collections):
+        """ Remove a collection(s). """
+        self._edit_tags('collection', collections, remove=True)
+
+    def addLabel(self, labels):
+        """ Add a label(s). """
+        self._edit_tags('label', labels)
+
+    def removeLabel(self, labels):
+        """ Remove a label(s). """
+        self._edit_tags('label', labels, remove=True)
+
+    def addGenre(self, genres):
+        """ Add a genre(s). """
+        self._edit_tags('genre', genres)
+
+    def removeGenre(self, genres):
+        """ Remove a genre(s). """
+        self._edit_tags('genre', genres, remove=True)
+
+    def refresh(self):
+        """ Refreshing a Library or individual item causes the metadata for the item to be
+            refreshed, even if it already has metadata. You can think of refreshing as
+            "update metadata for the requested item even if it already has some". You should
+            refresh a Library or individual item if:
+
+            * You've changed the Library Metadata Agent.
+            * You've added "Local Media Assets" (such as artwork, theme music, external
+                subtitle files, etc.)
+            * You want to freshen the item posters, summary, etc.
+            * There's a problem with the poster image that's been downloaded.
+            * Items are missing posters or other downloaded information. This is possible if
+                the refresh process is interrupted (the Server is turned off, internet
+                connection dies, etc).
+        """
+        key = '%s/refresh' % self.key
+        self._server.query(key, method=self._server._session.put)
+
+    def section(self):
+        """ Returns the :class:`~plexapi.library.LibrarySection` this item belongs to. """
+        return self._server.library.sectionByID(self.librarySectionID)
+
+    def delete(self):
+        """ Delete a media element. This has to be enabled under settings > server > library in plex webui. """
+        try:
+            return self._server.query(self.key, method=self._server._session.delete)
+        except BadRequest:  # pragma: no cover
+            log.error('Failed to delete %s. This could be because you '
+                'havnt allowed items to be deleted' % self.key)
+            raise
+
+    # The photo tag cant be built atm. TODO
+    # def arts(self):
+    #     part = '%s/arts' % self.key
+    #     return self.fetchItem(part)
+
+    # def poster(self):
+    #     part = '%s/posters' % self.key
+    #     return self.fetchItem(part, etag='Photo')
+
+
+class Playable(object):
+    """ This is a general place to store functions specific to media that is Playable.
+        Things were getting mixed up a bit when dealing with Shows, Season, Artists,
+        Albums which are all not playable.
+
+        Attributes:
+            sessionKey (int): Active session key.
+            usernames (str): Username of the person playing this item (for active sessions).
+            players (:class:`~plexapi.client.PlexClient`): Client objects playing this item (for active sessions).
+            session (:class:`~plexapi.media.Session`): Session object, for a playing media file.
+            transcodeSessions (:class:`~plexapi.media.TranscodeSession`): Transcode Session object
+                if item is being transcoded (None otherwise).
+            viewedAt (datetime): Datetime item was last viewed (history).
+            playlistItemID (int): Playlist item ID (only populated for :class:`~plexapi.playlist.Playlist` items).
+    """
+
+    def _loadData(self, data):
+        self.sessionKey = utils.cast(int, data.attrib.get('sessionKey'))            # session
+        self.usernames = self.listAttrs(data, 'title', etag='User')                 # session
+        self.players = self.findItems(data, etag='Player')                          # session
+        self.transcodeSessions = self.findItems(data, etag='TranscodeSession')      # session
+        self.session = self.findItems(data, etag='Session')                         # session
+        self.viewedAt = utils.toDatetime(data.attrib.get('viewedAt'))               # history
+        self.playlistItemID = utils.cast(int, data.attrib.get('playlistItemID'))    # playlist
+
+    def isFullObject(self):
+        """ Retruns True if this is already a full object. A full object means all attributes
+            were populated from the api path representing only this item. For example, the
+            search result for a movie often only contain a portion of the attributes a full
+            object (main url) for that movie contain.
+        """
+        return self._details_key == self._initpath or not self.key
+
+    def getStreamURL(self, **params):
+        """ Returns a stream url that may be used by external applications such as VLC.
+
+            Parameters:
+                **params (dict): optional parameters to manipulate the playback when accessing
+                    the stream. A few known parameters include: maxVideoBitrate, videoResolution
+                    offset, copyts, protocol, mediaIndex, platform.
+
+            Raises:
+                Unsupported: When the item doesn't support fetching a stream URL.
+        """
+        if self.TYPE not in ('movie', 'episode', 'track'):
+            raise Unsupported('Fetching stream URL for %s is unsupported.' % self.TYPE)
+        mvb = params.get('maxVideoBitrate')
+        vr = params.get('videoResolution', '')
+        params = {
+            'path': self.key,
+            'offset': params.get('offset', 0),
+            'copyts': params.get('copyts', 1),
+            'protocol': params.get('protocol'),
+            'mediaIndex': params.get('mediaIndex', 0),
+            'X-Plex-Platform': params.get('platform', 'Chrome'),
+            'maxVideoBitrate': max(mvb, 64) if mvb else None,
+            'videoResolution': vr if re.match('^\d+x\d+$', vr) else None
+        }
+        # remove None values
+        params = {k: v for k, v in params.items() if v is not None}
+        streamtype = 'audio' if self.TYPE in ('track', 'album') else 'video'
+        # sort the keys since the randomness fucks with my tests..
+        sorted_params = sorted(params.items(), key=lambda val: val[0])
+        return self._server.url('/%s/:/transcode/universal/start.m3u8?%s' %
+            (streamtype, urlencode(sorted_params)), includeToken=True)
+
+    def iterParts(self):
+        """ Iterates over the parts of this media item. """
+        for item in self.media:
+            for part in item.parts:
+                yield part
+
+    def split(self):
+        """Split a duplicate."""
+        key = '%s/split' % self.key
+        return self._server.query(key, method=self._server._session.put)
+
+    def unmatch(self):
+        """Unmatch a media file."""
+        key = '%s/unmatch' % self.key
+        return self._server.query(key, method=self._server._session.put)
+
+    def play(self, client):
+        """ Start playback on the specified client.
+
+            Parameters:
+                client (:class:`~plexapi.client.PlexClient`): Client to start playing on.
+        """
+        client.playMedia(self)
+
+    def download(self, savepath=None, keep_orginal_name=False, **kwargs):
+        """ Downloads this items media to the specified location. Returns a list of
+            filepaths that have been saved to disk.
+
+            Parameters:
+                savepath (str): Title of the track to return.
+                keep_orginal_name (bool): Set True to keep the original filename as stored in
+                    the Plex server. False will create a new filename with the format
+                    "<Artist> - <Album> <Track>".
+                kwargs (dict): If specified, a :func:`~plexapi.audio.Track.getStreamURL()` will
+                    be returned and the additional arguments passed in will be sent to that
+                    function. If kwargs is not specified, the media items will be downloaded
+                    and saved to disk.
+        """
+        filepaths = []
+        locations = [i for i in self.iterParts() if i]
+        for location in locations:
+            filename = location.file
+            if keep_orginal_name is False:
+                filename = '%s.%s' % (self._prettyfilename(), location.container)
+            # So this seems to be a alot slower but allows transcode.
+            if kwargs:
+                download_url = self.getStreamURL(**kwargs)
+            else:
+                download_url = self._server.url('%s?download=1' % location.key)
+            filepath = utils.download(download_url, self._server._token, filename=filename,
+                savepath=savepath, session=self._server._session)
+            if filepath:
+                filepaths.append(filepath)
+        return filepaths
+
+    def stop(self, reason=''):
+        """ Stop playback for a media item. """
+        key = '/status/sessions/terminate?sessionId=%s&reason=%s' % (self.session[0].id, quote_plus(reason))
+        return self._server.query(key)
+
+    def updateProgress(self, time, state='stopped'):
+        """ Set the watched progress for this video.
+
+        Note that setting the time to 0 will not work.
+        Use `markWatched` or `markUnwatched` to achieve
+        that goal.
+
+            Parameters:
+                time (int): milliseconds watched
+                state (string): state of the video, default 'stopped'
+        """
+        key = '/:/progress?key=%s&identifier=com.plexapp.plugins.library&time=%d&state=%s' % (self.ratingKey,
+                                                                                              time, state)
+        self._server.query(key)
+        self.reload()
+
+
+@utils.registerPlexObject
+class Release(PlexObject):
+    TAG = 'Release'
+    key = '/updater/status'
+
+    def _loadData(self, data):
+        self.download_key = data.attrib.get('key')
+        self.version = data.attrib.get('version')
+        self.added = data.attrib.get('added')
+        self.fixed = data.attrib.get('fixed')
+        self.downloadURL = data.attrib.get('downloadURL')
+        self.state = data.attrib.get('state')

lib/plexapi/client.py

@@ -0,0 +1,527 @@
+# -*- coding: utf-8 -*-
+
+import requests
+
+from requests.status_codes import _codes as codes
+from plexapi import BASE_HEADERS, CONFIG, TIMEOUT
+from plexapi import log, logfilter, utils
+from plexapi.base import PlexObject
+from plexapi.compat import ElementTree
+from plexapi.exceptions import BadRequest, Unsupported
+from plexapi.playqueue import PlayQueue
+
+
+DEFAULT_MTYPE = 'video'
+
+
+@utils.registerPlexObject
+class PlexClient(PlexObject):
+    """ Main class for interacting with a Plex client. This class can connect
+        directly to the client and control it or proxy commands through your
+        Plex Server. To better understand the Plex client API's read this page:
+        https://github.com/plexinc/plex-media-player/wiki/Remote-control-API
+
+        Parameters:
+            server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional).
+            data (ElementTree): Response from PlexServer used to build this object (optional).
+            initpath (str): Path used to generate data.
+            baseurl (str): HTTP URL to connect dirrectly to this client.
+            token (str): X-Plex-Token used for authenication (optional).
+            session (:class:`~requests.Session`): requests.Session object if you want more control (optional).
+            timeout (int): timeout in seconds on initial connect to client (default config.TIMEOUT).
+
+        Attributes:
+            TAG (str): 'Player'
+            key (str): '/resources'
+            device (str): Best guess on the type of device this is (PS, iPhone, Linux, etc).
+            deviceClass (str): Device class (pc, phone, etc).
+            machineIdentifier (str): Unique ID for this device.
+            model (str): Unknown
+            platform (str): Unknown
+            platformVersion (str): Description
+            product (str): Client Product (Plex for iOS, etc).
+            protocol (str): Always seems ot be 'plex'.
+            protocolCapabilities (list<str>): List of client capabilities (navigation, playback,
+                timeline, mirror, playqueues).
+            protocolVersion (str): Protocol version (1, future proofing?)
+            server (:class:`~plexapi.server.PlexServer`): Server this client is connected to.
+            session (:class:`~requests.Session`): Session object used for connection.
+            state (str): Unknown
+            title (str): Name of this client (Johns iPhone, etc).
+            token (str): X-Plex-Token used for authenication
+            vendor (str): Unknown
+            version (str): Device version (4.6.1, etc).
+            _baseurl (str): HTTP address of the client.
+            _token (str): Token used to access this client.
+            _session (obj): Requests session object used to access this client.
+            _proxyThroughServer (bool): Set to True after calling
+                :func:`~plexapi.client.PlexClient.proxyThroughServer()` (default False).
+    """
+    TAG = 'Player'
+    key = '/resources'
+
+    def __init__(self, server=None, data=None, initpath=None, baseurl=None,
+          token=None, connect=True, session=None, timeout=None):
+        super(PlexClient, self).__init__(server, data, initpath)
+        self._baseurl = baseurl.strip('/') if baseurl else None
+        self._token = logfilter.add_secret(token)
+        self._showSecrets = CONFIG.get('log.show_secrets', '').lower() == 'true'
+        server_session = server._session if server else None
+        self._session = session or server_session or requests.Session()
+        self._proxyThroughServer = False
+        self._commandId = 0
+        if not any([data, initpath, baseurl, token]):
+            self._baseurl = CONFIG.get('auth.client_baseurl', 'http://localhost:32433')
+            self._token = logfilter.add_secret(CONFIG.get('auth.client_token'))
+        if connect and self._baseurl:
+            self.connect(timeout=timeout)
+
+    def _nextCommandId(self):
+        self._commandId += 1
+        return self._commandId
+
+    def connect(self, timeout=None):
+        """ Alias of reload as any subsequent requests to this client will be
+            made directly to the device even if the object attributes were initially
+            populated from a PlexServer.
+        """
+        if not self.key:
+            raise Unsupported('Cannot reload an object not built from a URL.')
+        self._initpath = self.key
+        data = self.query(self.key, timeout=timeout)
+        self._loadData(data[0])
+        return self
+
+    def reload(self):
+        """ Alias to self.connect(). """
+        return self.connect()
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.deviceClass = data.attrib.get('deviceClass')
+        self.machineIdentifier = data.attrib.get('machineIdentifier')
+        self.product = data.attrib.get('product')
+        self.protocol = data.attrib.get('protocol')
+        self.protocolCapabilities = data.attrib.get('protocolCapabilities', '').split(',')
+        self.protocolVersion = data.attrib.get('protocolVersion')
+        self.platform = data.attrib.get('platform')
+        self.platformVersion = data.attrib.get('platformVersion')
+        self.title = data.attrib.get('title') or data.attrib.get('name')
+        # Active session details
+        # Since protocolCapabilities is missing from /sessions we cant really control this player without
+        # creating a client manually.
+        # Add this in next breaking release.
+        # if self._initpath == 'status/sessions':
+        self.device = data.attrib.get('device')         # session
+        self.model = data.attrib.get('model')           # session
+        self.state = data.attrib.get('state')           # session
+        self.vendor = data.attrib.get('vendor')         # session
+        self.version = data.attrib.get('version')       # session
+        self.local = utils.cast(bool, data.attrib.get('local', 0))
+        self.address = data.attrib.get('address')        # session
+        self.remotePublicAddress = data.attrib.get('remotePublicAddress')
+        self.userID = data.attrib.get('userID')
+
+    def _headers(self, **kwargs):
+        """ Returns a dict of all default headers for Client requests. """
+        headers = BASE_HEADERS
+        if self._token:
+            headers['X-Plex-Token'] = self._token
+        headers.update(kwargs)
+        return headers
+
+    def proxyThroughServer(self, value=True, server=None):
+        """ Tells this PlexClient instance to proxy all future commands through the PlexServer.
+            Useful if you do not wish to connect directly to the Client device itself.
+
+            Parameters:
+                value (bool): Enable or disable proxying (optional, default True).
+
+            Raises:
+                :class:`~plexapi.exceptions.Unsupported`: Cannot use client proxy with unknown server.
+        """
+        if server:
+            self._server = server
+        if value is True and not self._server:
+            raise Unsupported('Cannot use client proxy with unknown server.')
+        self._proxyThroughServer = value
+
+    def query(self, path, method=None, headers=None, timeout=None, **kwargs):
+        """ Main method used to handle HTTPS requests to the Plex client. This method helps
+            by encoding the response to utf-8 and parsing the returned XML into and
+            ElementTree object. Returns None if no data exists in the response.
+        """
+        url = self.url(path)
+        method = method or self._session.get
+        timeout = timeout or TIMEOUT
+        log.debug('%s %s', method.__name__.upper(), url)
+        headers = self._headers(**headers or {})
+        response = method(url, headers=headers, timeout=timeout, **kwargs)
+        if response.status_code not in (200, 201):
+            codename = codes.get(response.status_code)[0]
+            errtext = response.text.replace('\n', ' ')
+            log.warning('BadRequest (%s) %s %s; %s' % (response.status_code, codename, response.url, errtext))
+            raise BadRequest('(%s) %s; %s %s' % (response.status_code, codename, response.url, errtext))
+        data = response.text.encode('utf8')
+        return ElementTree.fromstring(data) if data.strip() else None
+
+    def sendCommand(self, command, proxy=None, **params):
+        """ Convenience wrapper around :func:`~plexapi.client.PlexClient.query()` to more easily
+            send simple commands to the client. Returns an ElementTree object containing
+            the response.
+
+            Parameters:
+                command (str): Command to be sent in for format '<controller>/<command>'.
+                proxy (bool): Set True to proxy this command through the PlexServer.
+                **params (dict): Additional GET parameters to include with the command.
+
+            Raises:
+                :class:`~plexapi.exceptions.Unsupported`: When we detect the client
+                    doesn't support this capability.
+        """
+        command = command.strip('/')
+        controller = command.split('/')[0]
+        if controller not in self.protocolCapabilities:
+            log.debug('Client %s doesnt support %s controller.'
+                      'What your trying might not work' % (self.title, controller))
+
+        params['commandID'] = self._nextCommandId()
+        key = '/player/%s%s' % (command, utils.joinArgs(params))
+        headers = {'X-Plex-Target-Client-Identifier': self.machineIdentifier}
+        proxy = self._proxyThroughServer if proxy is None else proxy
+        if proxy:
+            return self._server.query(key, headers=headers)
+        return self.query(key, headers=headers)
+
+    def url(self, key, includeToken=False):
+        """ Build a URL string with proper token argument. Token will be appended to the URL
+            if either includeToken is True or CONFIG.log.show_secrets is 'true'.
+        """
+        if not self._baseurl:
+            raise BadRequest('PlexClient object missing baseurl.')
+        if self._token and (includeToken or self._showSecrets):
+            delim = '&' if '?' in key else '?'
+            return '%s%s%sX-Plex-Token=%s' % (self._baseurl, key, delim, self._token)
+        return '%s%s' % (self._baseurl, key)
+
+    # ---------------------
+    # Navigation Commands
+    # These commands navigate around the user-interface.
+    def contextMenu(self):
+        """ Open the context menu on the client. """
+        self.sendCommand('navigation/contextMenu')
+
+    def goBack(self):
+        """ Navigate back one position. """
+        self.sendCommand('navigation/back')
+
+    def goToHome(self):
+        """ Go directly to the home screen. """
+        self.sendCommand('navigation/home')
+
+    def goToMusic(self):
+        """ Go directly to the playing music panel. """
+        self.sendCommand('navigation/music')
+
+    def moveDown(self):
+        """ Move selection down a position. """
+        self.sendCommand('navigation/moveDown')
+
+    def moveLeft(self):
+        """ Move selection left a position. """
+        self.sendCommand('navigation/moveLeft')
+
+    def moveRight(self):
+        """ Move selection right a position. """
+        self.sendCommand('navigation/moveRight')
+
+    def moveUp(self):
+        """ Move selection up a position. """
+        self.sendCommand('navigation/moveUp')
+
+    def nextLetter(self):
+        """ Jump to next letter in the alphabet. """
+        self.sendCommand('navigation/nextLetter')
+
+    def pageDown(self):
+        """ Move selection down a full page. """
+        self.sendCommand('navigation/pageDown')
+
+    def pageUp(self):
+        """ Move selection up a full page. """
+        self.sendCommand('navigation/pageUp')
+
+    def previousLetter(self):
+        """ Jump to previous letter in the alphabet. """
+        self.sendCommand('navigation/previousLetter')
+
+    def select(self):
+        """ Select element at the current position. """
+        self.sendCommand('navigation/select')
+
+    def toggleOSD(self):
+        """ Toggle the on screen display during playback. """
+        self.sendCommand('navigation/toggleOSD')
+
+    def goToMedia(self, media, **params):
+        """ Navigate directly to the specified media page.
+
+            Parameters:
+                media (:class:`~plexapi.media.Media`): Media object to navigate to.
+                **params (dict): Additional GET parameters to include with the command.
+
+            Raises:
+                :class:`~plexapi.exceptions.Unsupported`: When no PlexServer specified in this object.
+        """
+        if not self._server:
+            raise Unsupported('A server must be specified before using this command.')
+        server_url = media._server._baseurl.split(':')
+        self.sendCommand('mirror/details', **dict({
+            'machineIdentifier': self._server.machineIdentifier,
+            'address': server_url[1].strip('/'),
+            'port': server_url[-1],
+            'key': media.key,
+        }, **params))
+
+    # -------------------
+    # Playback Commands
+    # Most of the playback commands take a mandatory mtype {'music','photo','video'} argument,
+    # to specify which media type to apply the command to, (except for playMedia). This
+    # is in case there are multiple things happening (e.g. music in the background, photo
+    # slideshow in the foreground).
+    def pause(self, mtype=DEFAULT_MTYPE):
+        """ Pause the currently playing media type.
+
+            Parameters:
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.sendCommand('playback/pause', type=mtype)
+
+    def play(self, mtype=DEFAULT_MTYPE):
+        """ Start playback for the specified media type.
+
+            Parameters:
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.sendCommand('playback/play', type=mtype)
+
+    def refreshPlayQueue(self, playQueueID, mtype=DEFAULT_MTYPE):
+        """ Refresh the specified Playqueue.
+
+            Parameters:
+                playQueueID (str): Playqueue ID.
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.sendCommand(
+            'playback/refreshPlayQueue', playQueueID=playQueueID, type=mtype)
+
+    def seekTo(self, offset, mtype=DEFAULT_MTYPE):
+        """ Seek to the specified offset (ms) during playback.
+
+            Parameters:
+                offset (int): Position to seek to (milliseconds).
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.sendCommand('playback/seekTo', offset=offset, type=mtype)
+
+    def skipNext(self, mtype=DEFAULT_MTYPE):
+        """ Skip to the next playback item.
+
+            Parameters:
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.sendCommand('playback/skipNext', type=mtype)
+
+    def skipPrevious(self, mtype=DEFAULT_MTYPE):
+        """ Skip to previous playback item.
+
+            Parameters:
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.sendCommand('playback/skipPrevious', type=mtype)
+
+    def skipTo(self, key, mtype=DEFAULT_MTYPE):
+        """ Skip to the playback item with the specified key.
+
+            Parameters:
+                key (str): Key of the media item to skip to.
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.sendCommand('playback/skipTo', key=key, type=mtype)
+
+    def stepBack(self, mtype=DEFAULT_MTYPE):
+        """ Step backward a chunk of time in the current playback item.
+
+            Parameters:
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.sendCommand('playback/stepBack', type=mtype)
+
+    def stepForward(self, mtype=DEFAULT_MTYPE):
+        """ Step forward a chunk of time in the current playback item.
+
+            Parameters:
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.sendCommand('playback/stepForward', type=mtype)
+
+    def stop(self, mtype=DEFAULT_MTYPE):
+        """ Stop the currently playing item.
+
+            Parameters:
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.sendCommand('playback/stop', type=mtype)
+
+    def setRepeat(self, repeat, mtype=DEFAULT_MTYPE):
+        """ Enable repeat for the specified playback items.
+
+            Parameters:
+                repeat (int): Repeat mode (0=off, 1=repeatone, 2=repeatall).
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.setParameters(repeat=repeat, mtype=mtype)
+
+    def setShuffle(self, shuffle, mtype=DEFAULT_MTYPE):
+        """ Enable shuffle for the specified playback items.
+
+            Parameters:
+                shuffle (int): Shuffle mode (0=off, 1=on)
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.setParameters(shuffle=shuffle, mtype=mtype)
+
+    def setVolume(self, volume, mtype=DEFAULT_MTYPE):
+        """ Enable volume for the current playback item.
+
+            Parameters:
+                volume (int): Volume level (0-100).
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.setParameters(volume=volume, mtype=mtype)
+
+    def setAudioStream(self, audioStreamID, mtype=DEFAULT_MTYPE):
+        """ Select the audio stream for the current playback item (only video).
+
+            Parameters:
+                audioStreamID (str): ID of the audio stream from the media object.
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.setStreams(audioStreamID=audioStreamID, mtype=mtype)
+
+    def setSubtitleStream(self, subtitleStreamID, mtype=DEFAULT_MTYPE):
+        """ Select the subtitle stream for the current playback item (only video).
+
+            Parameters:
+                subtitleStreamID (str): ID of the subtitle stream from the media object.
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.setStreams(subtitleStreamID=subtitleStreamID, mtype=mtype)
+
+    def setVideoStream(self, videoStreamID, mtype=DEFAULT_MTYPE):
+        """ Select the video stream for the current playback item (only video).
+
+            Parameters:
+                videoStreamID (str): ID of the video stream from the media object.
+                mtype (str): Media type to take action against (music, photo, video).
+        """
+        self.setStreams(videoStreamID=videoStreamID, mtype=mtype)
+
+    def playMedia(self, media, offset=0, **params):
+        """ Start playback of the specified media item. See also:
+
+            Parameters:
+                media (:class:`~plexapi.media.Media`): Media item to be played back
+                    (movie, music, photo, playlist, playqueue).
+                offset (int): Number of milliseconds at which to start playing with zero
+                    representing the beginning (default 0).
+                **params (dict): Optional additional parameters to include in the playback request. See
+                    also: https://github.com/plexinc/plex-media-player/wiki/Remote-control-API#modified-commands
+
+            Raises:
+                :class:`~plexapi.exceptions.Unsupported`: When no PlexServer specified in this object.
+        """
+        if not self._server:
+            raise Unsupported('A server must be specified before using this command.')
+        server_url = media._server._baseurl.split(':')
+
+        if self.product != 'OpenPHT':
+            try:
+                self.sendCommand('timeline/subscribe', port=server_url[1].strip('/'), protocol='http')
+            except:  # noqa: E722
+                # some clients dont need or like this and raises http 400.
+                # We want to include the exception in the log,
+                # but it might still work so we swallow it.
+                log.exception('%s failed to subscribe ' % self.title)
+
+        playqueue = media if isinstance(media, PlayQueue) else self._server.createPlayQueue(media)
+        self.sendCommand('playback/playMedia', **dict({
+            'machineIdentifier': self._server.machineIdentifier,
+            'address': server_url[1].strip('/'),
+            'port': server_url[-1],
+            'offset': offset,
+            'key': media.key,
+            'token': media._server._token,
+            'containerKey': '/playQueues/%s?window=100&own=1' % playqueue.playQueueID,
+        }, **params))
+
+    def setParameters(self, volume=None, shuffle=None, repeat=None, mtype=DEFAULT_MTYPE):
+        """ Set multiple playback parameters at once.
+
+            Parameters:
+                volume (int): Volume level (0-100; optional).
+                shuffle (int): Shuffle mode (0=off, 1=on; optional).
+                repeat (int): Repeat mode (0=off, 1=repeatone, 2=repeatall; optional).
+                mtype (str): Media type to take action against (optional music, photo, video).
+        """
+        params = {}
+        if repeat is not None:
+            params['repeat'] = repeat
+        if shuffle is not None:
+            params['shuffle'] = shuffle
+        if volume is not None:
+            params['volume'] = volume
+        if mtype is not None:
+            params['type'] = mtype
+        self.sendCommand('playback/setParameters', **params)
+
+    def setStreams(self, audioStreamID=None, subtitleStreamID=None, videoStreamID=None, mtype=DEFAULT_MTYPE):
+        """ Select multiple playback streams at once.
+
+            Parameters:
+                audioStreamID (str): ID of the audio stream from the media object.
+                subtitleStreamID (str): ID of the subtitle stream from the media object.
+                videoStreamID (str): ID of the video stream from the media object.
+                mtype (str): Media type to take action against (optional music, photo, video).
+        """
+        params = {}
+        if audioStreamID is not None:
+            params['audioStreamID'] = audioStreamID
+        if subtitleStreamID is not None:
+            params['subtitleStreamID'] = subtitleStreamID
+        if videoStreamID is not None:
+            params['videoStreamID'] = videoStreamID
+        if mtype is not None:
+            params['type'] = mtype
+        self.sendCommand('playback/setStreams', **params)
+
+    # -------------------
+    # Timeline Commands
+    def timeline(self):
+        """ Poll the current timeline and return the XML response. """
+        return self.sendCommand('timeline/poll', wait=1)
+
+    def isPlayingMedia(self, includePaused=False):
+        """ Returns True if any media is currently playing.
+
+            Parameters:
+                includePaused (bool): Set True to treat currently paused items
+                    as playing (optional; default True).
+        """
+        for mediatype in self.timeline():
+            if mediatype.get('state') == 'playing':
+                return True
+            if includePaused and mediatype.get('state') == 'paused':
+                return True
+        return False

lib/plexapi/compat.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+# Python 2/3 compatability
+# Always try Py3 first
+import os
+from sys import version_info
+
+ustr = str
+if version_info < (3,):
+    ustr = unicode
+
+try:
+    string_type = basestring
+except NameError:
+    string_type = str
+
+try:
+    from urllib.parse import urlencode
+except ImportError:
+    from urllib import urlencode
+
+try:
+    from urllib.parse import quote
+except ImportError:
+    from urllib import quote
+
+try:
+    from urllib.parse import quote_plus
+except ImportError:
+    from urllib import quote_plus
+
+try:
+    from urllib.parse import unquote
+except ImportError:
+    from urllib import unquote
+
+try:
+    from configparser import ConfigParser
+except ImportError:
+    from ConfigParser import ConfigParser
+
+try:
+    from xml.etree import cElementTree as ElementTree
+except ImportError:
+    from xml.etree import ElementTree
+
+
+def makedirs(name, mode=0o777, exist_ok=False):
+    """ Mimicks os.makedirs() from Python 3. """
+    try:
+        os.makedirs(name, mode)
+    except OSError:
+        if not os.path.isdir(name) or not exist_ok:
+            raise

lib/plexapi/config.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+import os
+from collections import defaultdict
+from plexapi.compat import ConfigParser
+
+
+class PlexConfig(ConfigParser):
+    """ PlexAPI configuration object. Settings are stored in an INI file within the
+        user's home directory and can be overridden after importing plexapi by simply
+        setting the value. See the documentation section 'Configuration' for more
+        details on available options.
+
+        Parameters:
+            path (str): Path of the configuration file to load.
+    """
+    def __init__(self, path):
+        ConfigParser.__init__(self)
+        self.read(path)
+        self.data = self._asDict()
+
+    def get(self, key, default=None, cast=None):
+        """ Returns the specified configuration value or <default> if not found.
+
+            Parameters:
+                key (str): Configuration variable to load in the format '<section>.<variable>'.
+                default: Default value to use if key not found.
+                cast (func): Cast the value to the specified type before returning.
+        """
+        try:
+            # First: check environment variable is set
+            envkey = 'PLEXAPI_%s' % key.upper().replace('.', '_')
+            value = os.environ.get(envkey)
+            if value is None:
+                # Second: check the config file has attr
+                section, name = key.lower().split('.')
+                value = self.data.get(section, {}).get(name, default)
+            return cast(value) if cast else value
+        except:  # noqa: E722
+            return default
+
+    def _asDict(self):
+        """ Returns all configuration values as a dictionary. """
+        config = defaultdict(dict)
+        for section in self._sections:
+            for name, value in self._sections[section].items():
+                if name != '__name__':
+                    config[section.lower()][name.lower()] = value
+        return dict(config)
+
+
+def reset_base_headers():
+    """ Convenience function returns a dict of all base X-Plex-* headers for session requests. """
+    import plexapi
+    return {
+        'X-Plex-Platform': plexapi.X_PLEX_PLATFORM,
+        'X-Plex-Platform-Version': plexapi.X_PLEX_PLATFORM_VERSION,
+        'X-Plex-Provides': plexapi.X_PLEX_PROVIDES,
+        'X-Plex-Product': plexapi.X_PLEX_PRODUCT,
+        'X-Plex-Version': plexapi.X_PLEX_VERSION,
+        'X-Plex-Device': plexapi.X_PLEX_DEVICE,
+        'X-Plex-Device-Name': plexapi.X_PLEX_DEVICE_NAME,
+        'X-Plex-Client-Identifier': plexapi.X_PLEX_IDENTIFIER,
+    }

lib/plexapi/exceptions.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+
+class PlexApiException(Exception):
+    """ Base class for all PlexAPI exceptions. """
+    pass
+
+
+class BadRequest(PlexApiException):
+    """ An invalid request, generally a user error. """
+    pass
+
+
+class NotFound(PlexApiException):
+    """ Request media item or device is not found. """
+    pass
+
+
+class UnknownType(PlexApiException):
+    """ Unknown library type. """
+    pass
+
+
+class Unsupported(PlexApiException):
+    """ Unsupported client request. """
+    pass
+
+
+class Unauthorized(PlexApiException):
+    """ Invalid username or password. """
+    pass

lib/plexapi/library.py

@@ -0,0 +1,716 @@
+# -*- coding: utf-8 -*-
+from plexapi import X_PLEX_CONTAINER_SIZE, log, utils
+from plexapi.base import PlexObject
+from plexapi.compat import unquote, urlencode, quote_plus
+from plexapi.media import MediaTag
+from plexapi.exceptions import BadRequest, NotFound
+
+
+class Library(PlexObject):
+    """ Represents a PlexServer library. This contains all sections of media defined
+        in your Plex server including video, shows and audio.
+
+        Attributes:
+            key (str): '/library'
+            identifier (str): Unknown ('com.plexapp.plugins.library').
+            mediaTagVersion (str): Unknown (/system/bundle/media/flags/)
+            server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to.
+            title1 (str): 'Plex Library' (not sure how useful this is).
+            title2 (str): Second title (this is blank on my setup).
+    """
+    key = '/library'
+
+    def _loadData(self, data):
+        self._data = data
+        self._sectionsByID = {}  # cached Section UUIDs
+        self.identifier = data.attrib.get('identifier')
+        self.mediaTagVersion = data.attrib.get('mediaTagVersion')
+        self.title1 = data.attrib.get('title1')
+        self.title2 = data.attrib.get('title2')
+
+    def sections(self):
+        """ Returns a list of all media sections in this library. Library sections may be any of
+            :class:`~plexapi.library.MovieSection`, :class:`~plexapi.library.ShowSection`,
+            :class:`~plexapi.library.MusicSection`, :class:`~plexapi.library.PhotoSection`.
+        """
+        key = '/library/sections'
+        sections = []
+        for elem in self._server.query(key):
+            for cls in (MovieSection, ShowSection, MusicSection, PhotoSection):
+                if elem.attrib.get('type') == cls.TYPE:
+                    section = cls(self._server, elem, key)
+                    self._sectionsByID[section.key] = section
+                    sections.append(section)
+        return sections
+
+    def section(self, title=None):
+        """ Returns the :class:`~plexapi.library.LibrarySection` that matches the specified title.
+
+            Parameters:
+                title (str): Title of the section to return.
+        """
+        for section in self.sections():
+            if section.title.lower() == title.lower():
+                return section
+        raise NotFound('Invalid library section: %s' % title)
+
+    def sectionByID(self, sectionID):
+        """ Returns the :class:`~plexapi.library.LibrarySection` that matches the specified sectionID.
+
+            Parameters:
+                sectionID (str): ID of the section to return.
+        """
+        if not self._sectionsByID or sectionID not in self._sectionsByID:
+            self.sections()
+        return self._sectionsByID[sectionID]
+
+    def all(self, **kwargs):
+        """ Returns a list of all media from all library sections.
+            This may be a very large dataset to retrieve.
+        """
+        items = []
+        for section in self.sections():
+            for item in section.all(**kwargs):
+                items.append(item)
+        return items
+
+    def onDeck(self):
+        """ Returns a list of all media items on deck. """
+        return self.fetchItems('/library/onDeck')
+
+    def recentlyAdded(self):
+        """ Returns a list of all media items recently added. """
+        return self.fetchItems('/library/recentlyAdded')
+
+    def search(self, title=None, libtype=None, **kwargs):
+        """ Searching within a library section is much more powerful. It seems certain
+            attributes on the media objects can be targeted to filter this search down
+            a bit, but I havent found the documentation for it.
+
+            Example: "studio=Comedy%20Central" or "year=1999" "title=Kung Fu" all work. Other items
+            such as actor=<id> seem to work, but require you already know the id of the actor.
+            TLDR: This is untested but seems to work. Use library section search when you can.
+        """
+        args = {}
+        if title:
+            args['title'] = title
+        if libtype:
+            args['type'] = utils.searchType(libtype)
+        for attr, value in kwargs.items():
+            args[attr] = value
+        key = '/library/all%s' % utils.joinArgs(args)
+        return self.fetchItems(key)
+
+    def cleanBundles(self):
+        """ Poster images and other metadata for items in your library are kept in "bundle"
+            packages. When you remove items from your library, these bundles aren't immediately
+            removed. Removing these old bundles can reduce the size of your install. By default, your
+            server will automatically clean up old bundles once a week as part of Scheduled Tasks.
+        """
+        # TODO: Should this check the response for success or the correct mediaprefix?
+        self._server.query('/library/clean/bundles')
+
+    def emptyTrash(self):
+        """ If a library has items in the Library Trash, use this option to empty the Trash. """
+        for section in self.sections():
+            section.emptyTrash()
+
+    def optimize(self):
+        """ The Optimize option cleans up the server database from unused or fragmented data.
+            For example, if you have deleted or added an entire library or many items in a
+            library, you may like to optimize the database.
+        """
+        self._server.query('/library/optimize')
+
+    def update(self):
+        """ Scan this library for new items."""
+        self._server.query('/library/sections/all/refresh')
+
+    def cancelUpdate(self):
+        """ Cancel a library update. """
+        key = '/library/sections/all/refresh'
+        self._server.query(key, method=self._server._session.delete)
+
+    def refresh(self):
+        """ Forces a download of fresh media information from the internet.
+            This can take a long time. Any locked fields are not modified.
+        """
+        self._server.query('/library/sections/all/refresh?force=1')
+
+    def deleteMediaPreviews(self):
+        """ Delete the preview thumbnails for the all sections. This cannot be
+            undone. Recreating media preview files can take hours or even days.
+        """
+        for section in self.sections():
+            section.deleteMediaPreviews()
+
+    def add(self, name='', type='', agent='', scanner='', location='', language='en', *args, **kwargs):
+        """ Simplified add for the most common options.
+
+            Parameters:
+                name (str): Name of the library
+                agent (str): Example com.plexapp.agents.imdb
+                type (str): movie, show, # check me
+                location (str): /path/to/files
+                language (str): Two letter language fx en
+                kwargs (dict): Advanced options should be passed as a dict. where the id is the key.
+
+            **Photo Preferences**
+
+                * **agent** (str): com.plexapp.agents.none
+                * **enableAutoPhotoTags** (bool): Tag photos. Default value false.
+                * **enableBIFGeneration** (bool): Enable video preview thumbnails. Default value true.
+                * **includeInGlobal** (bool): Include in dashboard. Default value true.
+                * **scanner** (str): Plex Photo Scanner
+
+            **Movie Preferences**
+
+                * **agent** (str): com.plexapp.agents.none, com.plexapp.agents.imdb, com.plexapp.agents.themoviedb
+                * **enableBIFGeneration** (bool): Enable video preview thumbnails. Default value true.
+                * **enableCinemaTrailers** (bool): Enable Cinema Trailers. Default value true.
+                * **includeInGlobal** (bool): Include in dashboard. Default value true.
+                * **scanner** (str): Plex Movie Scanner, Plex Video Files Scanner
+
+            **IMDB Movie Options** (com.plexapp.agents.imdb)
+
+                * **title** (bool): Localized titles. Default value false.
+                * **extras** (bool): Find trailers and extras automatically (Plex Pass required). Default value true.
+                * **only_trailers** (bool): Skip extras which aren't trailers. Default value false.
+                * **redband** (bool): Use red band (restricted audiences) trailers when available. Default value false.
+                * **native_subs** (bool): Include extras with subtitles in Library language. Default value false.
+                * **cast_list** (int): Cast List Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.
+                * **ratings** (int): Ratings Source, Default value 0 Possible options:
+                  0:Rotten Tomatoes, 1:IMDb, 2:The Movie Database.
+                * **summary** (int): Plot Summary Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.
+                * **country** (int): Default value 46 Possible options 0:Argentina, 1:Australia, 2:Austria,
+                  3:Belgium, 4:Belize, 5:Bolivia, 6:Brazil, 7:Canada, 8:Chile, 9:Colombia, 10:Costa Rica,
+                  11:Czech Republic, 12:Denmark, 13:Dominican Republic, 14:Ecuador, 15:El Salvador,
+                  16:France, 17:Germany, 18:Guatemala, 19:Honduras, 20:Hong Kong SAR, 21:Ireland,
+                  22:Italy, 23:Jamaica, 24:Korea, 25:Liechtenstein, 26:Luxembourg, 27:Mexico, 28:Netherlands,
+                  29:New Zealand, 30:Nicaragua, 31:Panama, 32:Paraguay, 33:Peru, 34:Portugal,
+                  35:Peoples Republic of China, 36:Puerto Rico, 37:Russia, 38:Singapore, 39:South Africa,
+                  40:Spain, 41:Sweden, 42:Switzerland, 43:Taiwan, 44:Trinidad, 45:United Kingdom,
+                  46:United States, 47:Uruguay, 48:Venezuela.
+                * **collections** (bool): Use collection info from The Movie Database. Default value false.
+                * **localart** (bool): Prefer artwork based on library language. Default value true.
+                * **adult** (bool): Include adult content. Default value false.
+                * **usage** (bool): Send anonymous usage data to Plex. Default value true.
+
+            **TheMovieDB Movie Options** (com.plexapp.agents.themoviedb)
+
+                * **collections** (bool): Use collection info from The Movie Database. Default value false.
+                * **localart** (bool): Prefer artwork based on library language. Default value true.
+                * **adult** (bool): Include adult content. Default value false.
+                * **country** (int): Country (used for release date and content rating). Default value 47 Possible
+                  options 0:, 1:Argentina, 2:Australia, 3:Austria, 4:Belgium, 5:Belize, 6:Bolivia, 7:Brazil, 8:Canada,
+                  9:Chile, 10:Colombia, 11:Costa Rica, 12:Czech Republic, 13:Denmark, 14:Dominican Republic, 15:Ecuador,
+                  16:El Salvador, 17:France, 18:Germany, 19:Guatemala, 20:Honduras, 21:Hong Kong SAR, 22:Ireland,
+                  23:Italy, 24:Jamaica, 25:Korea, 26:Liechtenstein, 27:Luxembourg, 28:Mexico, 29:Netherlands,
+                  30:New Zealand, 31:Nicaragua, 32:Panama, 33:Paraguay, 34:Peru, 35:Portugal,
+                  36:Peoples Republic of China, 37:Puerto Rico, 38:Russia, 39:Singapore, 40:South Africa, 41:Spain,
+                  42:Sweden, 43:Switzerland, 44:Taiwan, 45:Trinidad, 46:United Kingdom, 47:United States, 48:Uruguay,
+                  49:Venezuela.
+
+            **Show Preferences**
+
+                * **agent** (str): com.plexapp.agents.none, com.plexapp.agents.thetvdb, com.plexapp.agents.themoviedb
+                * **enableBIFGeneration** (bool): Enable video preview thumbnails. Default value true.
+                * **episodeSort** (int): Episode order. Default -1 Possible options: 0:Oldest first, 1:Newest first.
+                * **flattenSeasons** (int): Seasons. Default value 0 Possible options: 0:Show,1:Hide.
+                * **includeInGlobal** (bool): Include in dashboard. Default value true.
+                * **scanner** (str): Plex Series Scanner
+
+            **TheTVDB Show Options** (com.plexapp.agents.thetvdb)
+
+                * **extras** (bool): Find trailers and extras automatically (Plex Pass required). Default value true.
+                * **native_subs** (bool): Include extras with subtitles in Library language. Default value false.
+
+            **TheMovieDB Show Options** (com.plexapp.agents.themoviedb)
+
+                * **collections** (bool): Use collection info from The Movie Database. Default value false.
+                * **localart** (bool): Prefer artwork based on library language. Default value true.
+                * **adult** (bool): Include adult content. Default value false.
+                * **country** (int): Country (used for release date and content rating). Default value 47 options
+                  0:, 1:Argentina, 2:Australia, 3:Austria, 4:Belgium, 5:Belize, 6:Bolivia, 7:Brazil, 8:Canada, 9:Chile,
+                  10:Colombia, 11:Costa Rica, 12:Czech Republic, 13:Denmark, 14:Dominican Republic, 15:Ecuador,
+                  16:El Salvador, 17:France, 18:Germany, 19:Guatemala, 20:Honduras, 21:Hong Kong SAR, 22:Ireland,
+                  23:Italy, 24:Jamaica, 25:Korea, 26:Liechtenstein, 27:Luxembourg, 28:Mexico, 29:Netherlands,
+                  30:New Zealand, 31:Nicaragua, 32:Panama, 33:Paraguay, 34:Peru, 35:Portugal,
+                  36:Peoples Republic of China, 37:Puerto Rico, 38:Russia, 39:Singapore, 40:South Africa,
+                  41:Spain, 42:Sweden, 43:Switzerland, 44:Taiwan, 45:Trinidad, 46:United Kingdom, 47:United States,
+                  48:Uruguay, 49:Venezuela.
+
+            **Other Video Preferences**
+
+                * **agent** (str): com.plexapp.agents.none, com.plexapp.agents.imdb, com.plexapp.agents.themoviedb
+                * **enableBIFGeneration** (bool): Enable video preview thumbnails. Default value true.
+                * **enableCinemaTrailers** (bool): Enable Cinema Trailers. Default value true.
+                * **includeInGlobal** (bool): Include in dashboard. Default value true.
+                * **scanner** (str): Plex Movie Scanner, Plex Video Files Scanner
+
+            **IMDB Other Video Options** (com.plexapp.agents.imdb)
+
+                * **title** (bool): Localized titles. Default value false.
+                * **extras** (bool): Find trailers and extras automatically (Plex Pass required). Default value true.
+                * **only_trailers** (bool): Skip extras which aren't trailers. Default value false.
+                * **redband** (bool): Use red band (restricted audiences) trailers when available. Default value false.
+                * **native_subs** (bool): Include extras with subtitles in Library language. Default value false.
+                * **cast_list** (int): Cast List Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.
+                * **ratings** (int): Ratings Source Default value 0 Possible options:
+                  0:Rotten Tomatoes,1:IMDb,2:The Movie Database.
+                * **summary** (int): Plot Summary Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.
+                * **country** (int): Country: Default value 46 Possible options: 0:Argentina, 1:Australia, 2:Austria,
+                  3:Belgium, 4:Belize, 5:Bolivia, 6:Brazil, 7:Canada, 8:Chile, 9:Colombia, 10:Costa Rica,
+                  11:Czech Republic, 12:Denmark, 13:Dominican Republic, 14:Ecuador, 15:El Salvador, 16:France,
+                  17:Germany, 18:Guatemala, 19:Honduras, 20:Hong Kong SAR, 21:Ireland, 22:Italy, 23:Jamaica,
+                  24:Korea, 25:Liechtenstein, 26:Luxembourg, 27:Mexico, 28:Netherlands, 29:New Zealand, 30:Nicaragua,
+                  31:Panama, 32:Paraguay, 33:Peru, 34:Portugal, 35:Peoples Republic of China, 36:Puerto Rico,
+                  37:Russia, 38:Singapore, 39:South Africa, 40:Spain, 41:Sweden, 42:Switzerland, 43:Taiwan, 44:Trinidad,
+                  45:United Kingdom, 46:United States, 47:Uruguay, 48:Venezuela.
+                * **collections** (bool): Use collection info from The Movie Database. Default value false.
+                * **localart** (bool): Prefer artwork based on library language. Default value true.
+                * **adult** (bool): Include adult content. Default value false.
+                * **usage** (bool): Send anonymous usage data to Plex. Default value true.
+
+            **TheMovieDB Other Video Options** (com.plexapp.agents.themoviedb)
+
+                * **collections** (bool): Use collection info from The Movie Database. Default value false.
+                * **localart** (bool): Prefer artwork based on library language. Default value true.
+                * **adult** (bool): Include adult content. Default value false.
+                * **country** (int): Country (used for release date and content rating). Default
+                  value 47 Possible options 0:, 1:Argentina, 2:Australia, 3:Austria, 4:Belgium, 5:Belize,
+                  6:Bolivia, 7:Brazil, 8:Canada, 9:Chile, 10:Colombia, 11:Costa Rica, 12:Czech Republic,
+                  13:Denmark, 14:Dominican Republic, 15:Ecuador, 16:El Salvador, 17:France, 18:Germany,
+                  19:Guatemala, 20:Honduras, 21:Hong Kong SAR, 22:Ireland, 23:Italy, 24:Jamaica,
+                  25:Korea, 26:Liechtenstein, 27:Luxembourg, 28:Mexico, 29:Netherlands, 30:New Zealand,
+                  31:Nicaragua, 32:Panama, 33:Paraguay, 34:Peru, 35:Portugal,
+                  36:Peoples Republic of China, 37:Puerto Rico, 38:Russia, 39:Singapore,
+                  40:South Africa, 41:Spain, 42:Sweden, 43:Switzerland, 44:Taiwan, 45:Trinidad,
+                  46:United Kingdom, 47:United States, 48:Uruguay, 49:Venezuela.
+        """
+        part = '/library/sections?name=%s&type=%s&agent=%s&scanner=%s&language=%s&location=%s' % (
+            quote_plus(name), type, agent, quote_plus(scanner), language, quote_plus(location))  # noqa E126
+        if kwargs:
+            part += urlencode(kwargs)
+        return self._server.query(part, method=self._server._session.post)
+
+
+class LibrarySection(PlexObject):
+    """ Base class for a single library section.
+
+        Attributes:
+            ALLOWED_FILTERS (tuple): ()
+            ALLOWED_SORT (tuple): ()
+            BOOLEAN_FILTERS (tuple<str>): ('unwatched', 'duplicate')
+            server (:class:`~plexapi.server.PlexServer`): Server this client is connected to.
+            initpath (str): Path requested when building this object.
+            agent (str): Unknown (com.plexapp.agents.imdb, etc)
+            allowSync (bool): True if you allow syncing content from this section.
+            art (str): Wallpaper artwork used to respresent this section.
+            composite (str): Composit image used to represent this section.
+            createdAt (datetime): Datetime this library section was created.
+            filters (str): Unknown
+            key (str): Key (or ID) of this library section.
+            language (str): Language represented in this section (en, xn, etc).
+            locations (str): Paths on disk where section content is stored.
+            refreshing (str): True if this section is currently being refreshed.
+            scanner (str): Internal scanner used to find media (Plex Movie Scanner, Plex Premium Music Scanner, etc.)
+            thumb (str): Thumbnail image used to represent this section.
+            title (str): Title of this section.
+            type (str): Type of content section represents (movie, artist, photo, show).
+            updatedAt (datetime): Datetime this library section was last updated.
+            uuid (str): Unique id for this section (32258d7c-3e6c-4ac5-98ad-bad7a3b78c63)
+    """
+    ALLOWED_FILTERS = ()
+    ALLOWED_SORT = ()
+    BOOLEAN_FILTERS = ('unwatched', 'duplicate')
+
+    def _loadData(self, data):
+        self._data = data
+        self.agent = data.attrib.get('agent')
+        self.allowSync = utils.cast(bool, data.attrib.get('allowSync'))
+        self.art = data.attrib.get('art')
+        self.composite = data.attrib.get('composite')
+        self.createdAt = utils.toDatetime(data.attrib.get('createdAt'))
+        self.filters = data.attrib.get('filters')
+        self.key = data.attrib.get('key')  # invalid key from plex
+        self.language = data.attrib.get('language')
+        self.locations = self.listAttrs(data, 'path', etag='Location')
+        self.refreshing = utils.cast(bool, data.attrib.get('refreshing'))
+        self.scanner = data.attrib.get('scanner')
+        self.thumb = data.attrib.get('thumb')
+        self.title = data.attrib.get('title')
+        self.type = data.attrib.get('type')
+        self.updatedAt = utils.toDatetime(data.attrib.get('updatedAt'))
+        self.uuid = data.attrib.get('uuid')
+
+    def delete(self):
+        """ Delete a library section. """
+        try:
+            return self._server.query('/library/sections/%s' % self.key, method=self._server._session.delete)
+        except BadRequest:  # pragma: no cover
+            msg = 'Failed to delete library %s' % self.key
+            msg += 'You may need to allow this permission in your Plex settings.'
+            log.error(msg)
+            raise
+
+    def edit(self, **kwargs):
+        """ Edit a library (Note: agent is required). See :class:`~plexapi.library.Library` for example usage.
+
+            Parameters:
+                kwargs (dict): Dict of settings to edit.
+        """
+        part = '/library/sections/%s?%s' % (self.key, urlencode(kwargs))
+        self._server.query(part, method=self._server._session.put)
+
+        # Reload this way since the self.key dont have a full path, but is simply a id.
+        for s in self._server.library.sections():
+            if s.key == self.key:
+                return s
+
+    def get(self, title):
+        """ Returns the media item with the specified title.
+
+            Parameters:
+                title (str): Title of the item to return.
+        """
+        key = '/library/sections/%s/all' % self.key
+        return self.fetchItem(key, title__iexact=title)
+
+    def all(self, **kwargs):
+        """ Returns a list of media from this library section. """
+        key = '/library/sections/%s/all' % self.key
+        return self.fetchItems(key, **kwargs)
+
+    def onDeck(self):
+        """ Returns a list of media items on deck from this library section. """
+        key = '/library/sections/%s/onDeck' % self.key
+        return self.fetchItems(key)
+
+    def recentlyAdded(self, maxresults=50):
+        """ Returns a list of media items recently added from this library section.
+
+            Parameters:
+                maxresults (int): Max number of items to return (default 50).
+        """
+        return self.search(sort='addedAt:desc', maxresults=maxresults)
+
+    def analyze(self):
+        """ Run an analysis on all of the items in this library section. See
+            See :func:`~plexapi.base.PlexPartialObject.analyze` for more details.
+        """
+        key = '/library/sections/%s/analyze' % self.key
+        self._server.query(key, method=self._server._session.put)
+
+    def emptyTrash(self):
+        """ If a section has items in the Trash, use this option to empty the Trash. """
+        key = '/library/sections/%s/emptyTrash' % self.key
+        self._server.query(key, method=self._server._session.put)
+
+    def update(self):
+        """ Scan this section for new media. """
+        key = '/library/sections/%s/refresh' % self.key
+        self._server.query(key)
+
+    def cancelUpdate(self):
+        """ Cancel update of this Library Section. """
+        key = '/library/sections/%s/refresh' % self.key
+        self._server.query(key, method=self._server._session.delete)
+
+    def refresh(self):
+        """ Forces a download of fresh media information from the internet.
+            This can take a long time. Any locked fields are not modified.
+        """
+        key = '/library/sections/%s/refresh?force=1' % self.key
+        self._server.query(key)
+
+    def deleteMediaPreviews(self):
+        """ Delete the preview thumbnails for items in this library. This cannot
+            be undone. Recreating media preview files can take hours or even days.
+        """
+        key = '/library/sections/%s/indexes' % self.key
+        self._server.query(key, method=self._server._session.delete)
+
+    def listChoices(self, category, libtype=None, **kwargs):
+        """ Returns a list of :class:`~plexapi.library.FilterChoice` objects for the
+            specified category and libtype. kwargs can be any of the same kwargs in
+            :func:`plexapi.library.LibraySection.search()` to help narrow down the choices
+            to only those that matter in your current context.
+
+            Parameters:
+                category (str): Category to list choices for (genre, contentRating, etc).
+                libtype (int): Library type of item filter.
+                **kwargs (dict): Additional kwargs to narrow down the choices.
+
+            Raises:
+                :class:`~plexapi.exceptions.BadRequest`: Cannot include kwarg equal to specified category.
+        """
+        # TODO: Should this be moved to base?
+        if category in kwargs:
+            raise BadRequest('Cannot include kwarg equal to specified category: %s' % category)
+        args = {}
+        for subcategory, value in kwargs.items():
+            args[category] = self._cleanSearchFilter(subcategory, value)
+        if libtype is not None:
+            args['type'] = utils.searchType(libtype)
+        key = '/library/sections/%s/%s%s' % (self.key, category, utils.joinArgs(args))
+        return self.fetchItems(key, cls=FilterChoice)
+
+    def search(self, title=None, sort=None, maxresults=999999, libtype=None, **kwargs):
+        """ Search the library. If there are many results, they will be fetched from the server
+            in batches of X_PLEX_CONTAINER_SIZE amounts. If you're only looking for the first <num>
+            results, it would be wise to set the maxresults option to that amount so this functions
+            doesn't iterate over all results on the server.
+
+            Parameters:
+                title (str): General string query to search for (optional).
+                sort (str): column:dir; column can be any of {addedAt, originallyAvailableAt, lastViewedAt,
+                      titleSort, rating, mediaHeight, duration}. dir can be asc or desc (optional).
+                maxresults (int): Only return the specified number of results (optional).
+                libtype (str): Filter results to a spcifiec libtype (movie, show, episode, artist,
+                    album, track; optional).
+                **kwargs (dict): Any of the available filters for the current library section. Partial string
+                        matches allowed. Multiple matches OR together. All inputs will be compared with the
+                        available options and a warning logged if the option does not appear valid.
+
+                        * unwatched: Display or hide unwatched content (True, False). [all]
+                        * duplicate: Display or hide duplicate items (True, False). [movie]
+                        * actor: List of actors to search ([actor_or_id, ...]). [movie]
+                        * collection: List of collections to search within ([collection_or_id, ...]). [all]
+                        * contentRating: List of content ratings to search within ([rating_or_key, ...]). [movie,tv]
+                        * country: List of countries to search within ([country_or_key, ...]). [movie,music]
+                        * decade: List of decades to search within ([yyy0, ...]). [movie]
+                        * director: List of directors to search ([director_or_id, ...]). [movie]
+                        * genre: List Genres to search within ([genere_or_id, ...]). [all]
+                        * network: List of TV networks to search within ([resolution_or_key, ...]). [tv]
+                        * resolution: List of video resolutions to search within ([resolution_or_key, ...]). [movie]
+                        * studio: List of studios to search within ([studio_or_key, ...]). [music]
+                        * year: List of years to search within ([yyyy, ...]). [all]
+        """
+        # cleanup the core arguments
+        args = {}
+        for category, value in kwargs.items():
+            args[category] = self._cleanSearchFilter(category, value, libtype)
+        if title is not None:
+            args['title'] = title
+        if sort is not None:
+            args['sort'] = self._cleanSearchSort(sort)
+        if libtype is not None:
+            args['type'] = utils.searchType(libtype)
+        # iterate over the results
+        results, subresults = [], '_init'
+        args['X-Plex-Container-Start'] = 0
+        args['X-Plex-Container-Size'] = min(X_PLEX_CONTAINER_SIZE, maxresults)
+        while subresults and maxresults > len(results):
+            key = '/library/sections/%s/all%s' % (self.key, utils.joinArgs(args))
+            subresults = self.fetchItems(key)
+            results += subresults[:maxresults - len(results)]
+            args['X-Plex-Container-Start'] += args['X-Plex-Container-Size']
+        return results
+
+    def _cleanSearchFilter(self, category, value, libtype=None):
+        # check a few things before we begin
+        if category not in self.ALLOWED_FILTERS:
+            raise BadRequest('Unknown filter category: %s' % category)
+        if category in self.BOOLEAN_FILTERS:
+            return '1' if value else '0'
+        if not isinstance(value, (list, tuple)):
+            value = [value]
+        # convert list of values to list of keys or ids
+        result = set()
+        choices = self.listChoices(category, libtype)
+        lookup = {c.title.lower(): unquote(unquote(c.key)) for c in choices}
+        allowed = set(c.key for c in choices)
+        for item in value:
+            item = str((item.id or item.tag) if isinstance(item, MediaTag) else item).lower()
+            # find most logical choice(s) to use in url
+            if item in allowed: result.add(item); continue
+            if item in lookup: result.add(lookup[item]); continue
+            matches = [k for t, k in lookup.items() if item in t]
+            if matches: map(result.add, matches); continue
+            # nothing matched; use raw item value
+            log.warning('Filter value not listed, using raw item value: %s' % item)
+            result.add(item)
+        return ','.join(result)
+
+    def _cleanSearchSort(self, sort):
+        sort = '%s:asc' % sort if ':' not in sort else sort
+        scol, sdir = sort.lower().split(':')
+        lookup = {s.lower(): s for s in self.ALLOWED_SORT}
+        if scol not in lookup:
+            raise BadRequest('Unknown sort column: %s' % scol)
+        if sdir not in ('asc', 'desc'):
+            raise BadRequest('Unknown sort dir: %s' % sdir)
+        return '%s:%s' % (lookup[scol], sdir)
+
+
+class MovieSection(LibrarySection):
+    """ Represents a :class:`~plexapi.library.LibrarySection` section containing movies.
+
+        Attributes:
+            ALLOWED_FILTERS (list<str>): List of allowed search filters. ('unwatched',
+                'duplicate', 'year', 'decade', 'genre', 'contentRating', 'collection',
+                'director', 'actor', 'country', 'studio', 'resolution', 'guid', 'label')
+            ALLOWED_SORT (list<str>): List of allowed sorting keys. ('addedAt',
+                'originallyAvailableAt', 'lastViewedAt', 'titleSort', 'rating',
+                'mediaHeight', 'duration')
+            TAG (str): 'Directory'
+            TYPE (str): 'movie'
+    """
+    ALLOWED_FILTERS = ('unwatched', 'duplicate', 'year', 'decade', 'genre', 'contentRating',
+                       'collection', 'director', 'actor', 'country', 'studio', 'resolution',
+                       'guid', 'label')
+    ALLOWED_SORT = ('addedAt', 'originallyAvailableAt', 'lastViewedAt', 'titleSort', 'rating',
+                    'mediaHeight', 'duration')
+    TAG = 'Directory'
+    TYPE = 'movie'
+
+
+class ShowSection(LibrarySection):
+    """ Represents a :class:`~plexapi.library.LibrarySection` section containing tv shows.
+
+        Attributes:
+            ALLOWED_FILTERS (list<str>): List of allowed search filters. ('unwatched',
+                'year', 'genre', 'contentRating', 'network', 'collection', 'guid', 'label')
+            ALLOWED_SORT (list<str>): List of allowed sorting keys. ('addedAt', 'lastViewedAt',
+                'originallyAvailableAt', 'titleSort', 'rating', 'unwatched')
+            TAG (str): 'Directory'
+            TYPE (str): 'show'
+    """
+    ALLOWED_FILTERS = ('unwatched', 'year', 'genre', 'contentRating', 'network', 'collection',
+                       'guid', 'duplicate', 'label')
+    ALLOWED_SORT = ('addedAt', 'lastViewedAt', 'originallyAvailableAt', 'titleSort',
+                    'rating', 'unwatched')
+    TAG = 'Directory'
+    TYPE = 'show'
+
+    def searchShows(self, **kwargs):
+        """ Search for a show. See :func:`~plexapi.library.LibrarySection.search()` for usage. """
+        return self.search(libtype='show', **kwargs)
+
+    def searchEpisodes(self, **kwargs):
+        """ Search for an episode. See :func:`~plexapi.library.LibrarySection.search()` for usage. """
+        return self.search(libtype='episode', **kwargs)
+
+    def recentlyAdded(self, libtype='episode', maxresults=50):
+        """ Returns a list of recently added episodes from this library section.
+
+            Parameters:
+                maxresults (int): Max number of items to return (default 50).
+        """
+        return self.search(sort='addedAt:desc', libtype=libtype, maxresults=maxresults)
+
+
+class MusicSection(LibrarySection):
+    """ Represents a :class:`~plexapi.library.LibrarySection` section containing music artists.
+
+        Attributes:
+            ALLOWED_FILTERS (list<str>): List of allowed search filters. ('genre',
+                'country', 'collection')
+            ALLOWED_SORT (list<str>): List of allowed sorting keys. ('addedAt',
+                'lastViewedAt', 'viewCount', 'titleSort')
+            TAG (str): 'Directory'
+            TYPE (str): 'artist'
+    """
+    ALLOWED_FILTERS = ('genre', 'country', 'collection', 'mood')
+    ALLOWED_SORT = ('addedAt', 'lastViewedAt', 'viewCount', 'titleSort')
+    TAG = 'Directory'
+    TYPE = 'artist'
+
+    def albums(self):
+        """ Returns a list of :class:`~plexapi.audio.Album` objects in this section. """
+        key = '/library/sections/%s/albums' % self.key
+        return self.fetchItems(key)
+
+    def searchArtists(self, **kwargs):
+        """ Search for an artist. See :func:`~plexapi.library.LibrarySection.search()` for usage. """
+        return self.search(libtype='artist', **kwargs)
+
+    def searchAlbums(self, **kwargs):
+        """ Search for an album. See :func:`~plexapi.library.LibrarySection.search()` for usage. """
+        return self.search(libtype='album', **kwargs)
+
+    def searchTracks(self, **kwargs):
+        """ Search for a track. See :func:`~plexapi.library.LibrarySection.search()` for usage. """
+        return self.search(libtype='track', **kwargs)
+
+
+class PhotoSection(LibrarySection):
+    """ Represents a :class:`~plexapi.library.LibrarySection` section containing photos.
+
+        Attributes:
+            ALLOWED_FILTERS (list<str>): List of allowed search filters. ('all', 'iso',
+                'make', 'lens', 'aperture', 'exposure')
+            ALLOWED_SORT (list<str>): List of allowed sorting keys. ('addedAt')
+            TAG (str): 'Directory'
+            TYPE (str): 'photo'
+    """
+    ALLOWED_FILTERS = ('all', 'iso', 'make', 'lens', 'aperture', 'exposure')
+    ALLOWED_SORT = ('addedAt',)
+    TAG = 'Directory'
+    TYPE = 'photo'
+
+    def searchAlbums(self, title, **kwargs):
+        """ Search for an album. See :func:`~plexapi.library.LibrarySection.search()` for usage. """
+        key = '/library/sections/%s/all?type=14' % self.key
+        return self.fetchItems(key, title=title)
+
+    def searchPhotos(self, title, **kwargs):
+        """ Search for a photo. See :func:`~plexapi.library.LibrarySection.search()` for usage. """
+        key = '/library/sections/%s/all?type=13' % self.key
+        return self.fetchItems(key, title=title)
+
+
+class FilterChoice(PlexObject):
+    """ Represents a single filter choice. These objects are gathered when using filters
+        while searching for library items and is the object returned in the result set of
+        :func:`~plexapi.library.LibrarySection.listChoices()`.
+
+        Attributes:
+            TAG (str): 'Directory'
+            server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to.
+            initpath (str): Relative path requested when retrieving specified `data` (optional).
+            fastKey (str): API path to quickly list all items in this filter
+                (/library/sections/<section>/all?genre=<key>)
+            key (str): Short key (id) of this filter option (used ad <key> in fastKey above).
+            thumb (str): Thumbnail used to represent this filter option.
+            title (str): Human readable name for this filter option.
+            type (str): Filter type (genre, contentRating, etc).
+    """
+    TAG = 'Directory'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.fastKey = data.attrib.get('fastKey')
+        self.key = data.attrib.get('key')
+        self.thumb = data.attrib.get('thumb')
+        self.title = data.attrib.get('title')
+        self.type = data.attrib.get('type')
+
+
+@utils.registerPlexObject
+class Hub(PlexObject):
+    """ Represents a single Hub (or category) in the PlexServer search.
+
+        Attributes:
+            TAG (str): 'Hub'
+            hubIdentifier (str): Unknown.
+            size (int): Number of items found.
+            title (str): Title of this Hub.
+            type (str): Type of items in the Hub.
+            items (str): List of items in the Hub.
+    """
+    TAG = 'Hub'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.hubIdentifier = data.attrib.get('hubIdentifier')
+        self.size = utils.cast(int, data.attrib.get('size'))
+        self.title = data.attrib.get('title')
+        self.type = data.attrib.get('type')
+        self.items = self.findItems(data)
+
+    def __len__(self):
+        return self.size

lib/plexapi/media.py

@@ -0,0 +1,504 @@
+# -*- coding: utf-8 -*-
+from plexapi import log, utils
+from plexapi.base import PlexObject
+from plexapi.exceptions import BadRequest
+from plexapi.utils import cast
+
+
+@utils.registerPlexObject
+class Media(PlexObject):
+    """ Container object for all MediaPart objects. Provides useful data about the
+        video this media belong to such as video framerate, resolution, etc.
+
+        Attributes:
+            TAG (str): 'Media'
+            server (:class:`~plexapi.server.PlexServer`): PlexServer object this is from.
+            initpath (str): Relative path requested when retrieving specified data.
+            video (str): Video this media belongs to.
+            aspectRatio (float): Aspect ratio of the video (ex: 2.35).
+            audioChannels (int): Number of audio channels for this video (ex: 6).
+            audioCodec (str): Audio codec used within the video (ex: ac3).
+            bitrate (int): Bitrate of the video (ex: 1624)
+            container (str): Container this video is in (ex: avi).
+            duration (int): Length of the video in milliseconds (ex: 6990483).
+            height (int): Height of the video in pixels (ex: 256).
+            id (int): Plex ID of this media item (ex: 46184).
+            has64bitOffsets (bool): True if video has 64 bit offsets (?).
+            optimizedForStreaming (bool): True if video is optimized for streaming.
+            videoCodec (str): Video codec used within the video (ex: ac3).
+            videoFrameRate (str): Video frame rate (ex: 24p).
+            videoResolution (str): Video resolution (ex: sd).
+            width (int): Width of the video in pixels (ex: 608).
+            parts (list<:class:`~plexapi.media.MediaPart`>): List of MediaParts in this video.
+    """
+    TAG = 'Media'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.aspectRatio = cast(float, data.attrib.get('aspectRatio'))
+        self.audioChannels = cast(int, data.attrib.get('audioChannels'))
+        self.audioCodec = data.attrib.get('audioCodec')
+        self.bitrate = cast(int, data.attrib.get('bitrate'))
+        self.container = data.attrib.get('container')
+        self.duration = cast(int, data.attrib.get('duration'))
+        self.height = cast(int, data.attrib.get('height'))
+        self.id = cast(int, data.attrib.get('id'))
+        self.has64bitOffsets = cast(bool, data.attrib.get('has64bitOffsets'))
+        self.optimizedForStreaming = cast(bool, data.attrib.get('optimizedForStreaming'))
+        self.videoCodec = data.attrib.get('videoCodec')
+        self.videoFrameRate = data.attrib.get('videoFrameRate')
+        self.videoResolution = data.attrib.get('videoResolution')
+        self.width = cast(int, data.attrib.get('width'))
+        self.parts = self.findItems(data, MediaPart)
+
+    def delete(self):
+        part = self._initpath + '/media/%s' % self.id
+        try:
+            return self._server.query(part, method=self._server._session.delete)
+        except BadRequest:
+            log.error("Failed to delete %s. This could be because you havn't allowed "
+                      "items to be deleted" % part)
+            raise
+
+
+@utils.registerPlexObject
+class MediaPart(PlexObject):
+    """ Represents a single media part (often a single file) for the media this belongs to.
+
+        Attributes:
+            TAG (str): 'Part'
+            server (:class:`~plexapi.server.PlexServer`): PlexServer object this is from.
+            initpath (str): Relative path requested when retrieving specified data.
+            media (:class:`~plexapi.media.Media`): Media object this part belongs to.
+            container (str): Container type of this media part (ex: avi).
+            duration (int): Length of this media part in milliseconds.
+            file (str): Path to this file on disk (ex: /media/Movies/Cars.(2006)/Cars.cd2.avi)
+            id (int): Unique ID of this media part.
+            indexes (str, None): None or SD.
+            key (str): Key used to access this media part (ex: /library/parts/46618/1389985872/file.avi).
+            size (int): Size of this file in bytes (ex: 733884416).
+            streams (list<:class:`~plexapi.media.MediaPartStream`>): List of streams in this media part.
+    """
+    TAG = 'Part'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.container = data.attrib.get('container')
+        self.duration = cast(int, data.attrib.get('duration'))
+        self.file = data.attrib.get('file')
+        self.id = cast(int, data.attrib.get('id'))
+        self.indexes = data.attrib.get('indexes')
+        self.key = data.attrib.get('key')
+        self.size = cast(int, data.attrib.get('size'))
+        self.streams = self._buildStreams(data)
+
+    def _buildStreams(self, data):
+        streams = []
+        for elem in data:
+            for cls in (VideoStream, AudioStream, SubtitleStream):
+                if elem.attrib.get('streamType') == str(cls.STREAMTYPE):
+                    streams.append(cls(self._server, elem, self._initpath))
+        return streams
+
+    def videoStreams(self):
+        """ Returns a list of :class:`~plexapi.media.VideoStream` objects in this MediaPart. """
+        return [stream for stream in self.streams if stream.streamType == VideoStream.STREAMTYPE]
+
+    def audioStreams(self):
+        """ Returns a list of :class:`~plexapi.media.AudioStream` objects in this MediaPart. """
+        return [stream for stream in self.streams if stream.streamType == AudioStream.STREAMTYPE]
+
+    def subtitleStreams(self):
+        """ Returns a list of :class:`~plexapi.media.SubtitleStream` objects in this MediaPart. """
+        return [stream for stream in self.streams if stream.streamType == SubtitleStream.STREAMTYPE]
+
+
+class MediaPartStream(PlexObject):
+    """ Base class for media streams. These consist of video, audio and subtitles.
+
+        Attributes:
+            server (:class:`~plexapi.server.PlexServer`): PlexServer object this is from.
+            initpath (str): Relative path requested when retrieving specified data.
+            part (:class:`~plexapi.media.MediaPart`): Media part this stream belongs to.
+            codec (str): Codec of this stream (ex: srt, ac3, mpeg4).
+            codecID (str): Codec ID (ex: XVID).
+            id (int): Unique stream ID on this server.
+            index (int): Unknown
+            language (str): Stream language (ex: English, ไทย).
+            languageCode (str): Ascii code for language (ex: eng, tha).
+            selected (bool): True if this stream is selected.
+            streamType (int): Stream type (1=:class:`~plexapi.media.VideoStream`,
+                2=:class:`~plexapi.media.AudioStream`, 3=:class:`~plexapi.media.SubtitleStream`).
+            type (int): Alias for streamType.
+    """
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.codec = data.attrib.get('codec')
+        self.codecID = data.attrib.get('codecID')
+        self.id = cast(int, data.attrib.get('id'))
+        self.index = cast(int, data.attrib.get('index', '-1'))
+        self.language = data.attrib.get('language')
+        self.languageCode = data.attrib.get('languageCode')
+        self.selected = cast(bool, data.attrib.get('selected', '0'))
+        self.streamType = cast(int, data.attrib.get('streamType'))
+        self.type = cast(int, data.attrib.get('streamType'))
+
+    @staticmethod
+    def parse(server, data, initpath):  # pragma: no cover seems to be dead code.
+        """ Factory method returns a new MediaPartStream from xml data. """
+        STREAMCLS = {1: VideoStream, 2: AudioStream, 3: SubtitleStream}
+        stype = cast(int, data.attrib.get('streamType'))
+        cls = STREAMCLS.get(stype, MediaPartStream)
+        return cls(server, data, initpath)
+
+
+@utils.registerPlexObject
+class VideoStream(MediaPartStream):
+    """ Respresents a video stream within a :class:`~plexapi.media.MediaPart`.
+
+        Attributes:
+            TAG (str): 'Stream'
+            STREAMTYPE (int): 1
+            bitDepth (int): Bit depth (ex: 8).
+            bitrate (int): Bitrate (ex: 1169)
+            cabac (int): Unknown
+            chromaSubsampling (str): Chroma Subsampling (ex: 4:2:0).
+            colorSpace (str): Unknown
+            duration (int): Duration of video stream in milliseconds.
+            frameRate (float): Frame rate (ex: 23.976)
+            frameRateMode (str): Unknown
+            hasScallingMatrix (bool): True if video stream has a scaling matrix.
+            height (int): Height of video stream.
+            level (int): Videl stream level (?).
+            profile (str): Video stream profile (ex: asp).
+            refFrames (int): Unknown
+            scanType (str): Video stream scan type (ex: progressive).
+            title (str): Title of this video stream.
+            width (int): Width of video stream.
+    """
+    TAG = 'Stream'
+    STREAMTYPE = 1
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        super(VideoStream, self)._loadData(data)
+        self.bitDepth = cast(int, data.attrib.get('bitDepth'))
+        self.bitrate = cast(int, data.attrib.get('bitrate'))
+        self.cabac = cast(int, data.attrib.get('cabac'))
+        self.chromaSubsampling = data.attrib.get('chromaSubsampling')
+        self.colorSpace = data.attrib.get('colorSpace')
+        self.duration = cast(int, data.attrib.get('duration'))
+        self.frameRate = cast(float, data.attrib.get('frameRate'))
+        self.frameRateMode = data.attrib.get('frameRateMode')
+        self.hasScallingMatrix = cast(bool, data.attrib.get('hasScallingMatrix'))
+        self.height = cast(int, data.attrib.get('height'))
+        self.level = cast(int, data.attrib.get('level'))
+        self.profile = data.attrib.get('profile')
+        self.refFrames = cast(int, data.attrib.get('refFrames'))
+        self.scanType = data.attrib.get('scanType')
+        self.title = data.attrib.get('title')
+        self.width = cast(int, data.attrib.get('width'))
+
+
+@utils.registerPlexObject
+class AudioStream(MediaPartStream):
+    """ Respresents a audio stream within a :class:`~plexapi.media.MediaPart`.
+
+        Attributes:
+            TAG (str): 'Stream'
+            STREAMTYPE (int): 2
+            audioChannelLayout (str): Audio channel layout (ex: 5.1(side)).
+            bitDepth (int): Bit depth (ex: 16).
+            bitrate (int): Audio bitrate (ex: 448).
+            bitrateMode (str): Bitrate mode (ex: cbr).
+            channels (int): number of channels in this stream (ex: 6).
+            dialogNorm (int): Unknown (ex: -27).
+            duration (int): Duration of audio stream in milliseconds.
+            samplingRate (int): Sampling rate (ex: xxx)
+            title (str): Title of this audio stream.
+    """
+    TAG = 'Stream'
+    STREAMTYPE = 2
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        super(AudioStream, self)._loadData(data)
+        self.audioChannelLayout = data.attrib.get('audioChannelLayout')
+        self.bitDepth = cast(int, data.attrib.get('bitDepth'))
+        self.bitrate = cast(int, data.attrib.get('bitrate'))
+        self.bitrateMode = data.attrib.get('bitrateMode')
+        self.channels = cast(int, data.attrib.get('channels'))
+        self.dialogNorm = cast(int, data.attrib.get('dialogNorm'))
+        self.duration = cast(int, data.attrib.get('duration'))
+        self.samplingRate = cast(int, data.attrib.get('samplingRate'))
+        self.title = data.attrib.get('title')
+
+
+@utils.registerPlexObject
+class SubtitleStream(MediaPartStream):
+    """ Respresents a audio stream within a :class:`~plexapi.media.MediaPart`.
+
+        Attributes:
+            TAG (str): 'Stream'
+            STREAMTYPE (int): 3
+            format (str): Subtitle format (ex: srt).
+            key (str): Key of this subtitle stream (ex: /library/streams/212284).
+            title (str): Title of this subtitle stream.
+    """
+    TAG = 'Stream'
+    STREAMTYPE = 3
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        super(SubtitleStream, self)._loadData(data)
+        self.format = data.attrib.get('format')
+        self.key = data.attrib.get('key')
+        self.title = data.attrib.get('title')
+
+
+@utils.registerPlexObject
+class Session(PlexObject):
+    """ Represents a current session. """
+    TAG = 'Session'
+
+    def _loadData(self, data):
+        self.id = data.attrib.get('id')
+        self.bandwidth = utils.cast(int, data.attrib.get('bandwidth'))
+        self.location = data.attrib.get('location')
+
+
+@utils.registerPlexObject
+class TranscodeSession(PlexObject):
+    """ Represents a current transcode session.
+
+        Attributes:
+            TAG (str): 'TranscodeSession'
+            TODO: Document this.
+    """
+    TAG = 'TranscodeSession'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.audioChannels = cast(int, data.attrib.get('audioChannels'))
+        self.audioCodec = data.attrib.get('audioCodec')
+        self.audioDecision = data.attrib.get('audioDecision')
+        self.container = data.attrib.get('container')
+        self.context = data.attrib.get('context')
+        self.duration = cast(int, data.attrib.get('duration'))
+        self.height = cast(int, data.attrib.get('height'))
+        self.key = data.attrib.get('key')
+        self.progress = cast(float, data.attrib.get('progress'))
+        self.protocol = data.attrib.get('protocol')
+        self.remaining = cast(int, data.attrib.get('remaining'))
+        self.speed = cast(int, data.attrib.get('speed'))
+        self.throttled = cast(int, data.attrib.get('throttled'))
+        self.sourceVideoCodec = data.attrib.get('sourceVideoCodec')
+        self.videoCodec = data.attrib.get('videoCodec')
+        self.videoDecision = data.attrib.get('videoDecision')
+        self.width = cast(int, data.attrib.get('width'))
+
+
+class MediaTag(PlexObject):
+    """ Base class for media tags used for filtering and searching your library
+        items or navigating the metadata of media items in your library. Tags are
+        the construct used for things such as Country, Director, Genre, etc.
+
+        Attributes:
+            server (:class:`~plexapi.server.PlexServer`): Server this client is connected to.
+            id (id): Tag ID (This seems meaningless except to use it as a unique id).
+            role (str): Unknown
+            tag (str): Name of the tag. This will be Animation, SciFi etc for Genres. The name of
+                person for Directors and Roles (ex: Animation, Stephen Graham, etc).
+            <Hub_Search_Attributes>: Attributes only applicable in search results from
+                PlexServer :func:`~plexapi.server.PlexServer.search()`. They provide details of which
+                library section the tag was found as well as the url to dig deeper into the results.
+
+                * key (str): API URL to dig deeper into this tag (ex: /library/sections/1/all?actor=9081).
+                * librarySectionID (int): Section ID this tag was generated from.
+                * librarySectionTitle (str): Library section title this tag was found.
+                * librarySectionType (str): Media type of the library section this tag was found.
+                * tagType (int): Tag type ID.
+                * thumb (str): URL to thumbnail image.
+    """
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.id = cast(int, data.attrib.get('id'))
+        self.role = data.attrib.get('role')
+        self.tag = data.attrib.get('tag')
+        # additional attributes only from hub search
+        self.key = data.attrib.get('key')
+        self.librarySectionID = cast(int, data.attrib.get('librarySectionID'))
+        self.librarySectionTitle = data.attrib.get('librarySectionTitle')
+        self.librarySectionType = data.attrib.get('librarySectionType')
+        self.tagType = cast(int, data.attrib.get('tagType'))
+        self.thumb = data.attrib.get('thumb')
+
+    def items(self, *args, **kwargs):
+        """ Return the list of items within this tag. This function is only applicable
+            in search results from PlexServer :func:`~plexapi.server.PlexServer.search()`.
+        """
+        if not self.key:
+            raise BadRequest('Key is not defined for this tag: %s' % self.tag)
+        return self.fetchItems(self.key)
+
+
+@utils.registerPlexObject
+class Collection(MediaTag):
+    """ Represents a single Collection media tag.
+
+        Attributes:
+            TAG (str): 'Collection'
+            FILTER (str): 'collection'
+    """
+    TAG = 'Collection'
+    FILTER = 'collection'
+
+
+@utils.registerPlexObject
+class Label(MediaTag):
+    """ Represents a single label media tag.
+
+        Attributes:
+            TAG (str): 'label'
+            FILTER (str): 'label'
+    """
+    TAG = 'Label'
+    FILTER = 'label'
+
+
+@utils.registerPlexObject
+class Country(MediaTag):
+    """ Represents a single Country media tag.
+
+        Attributes:
+            TAG (str): 'Country'
+            FILTER (str): 'country'
+    """
+    TAG = 'Country'
+    FILTER = 'country'
+
+
+@utils.registerPlexObject
+class Director(MediaTag):
+    """ Represents a single Director media tag.
+
+        Attributes:
+            TAG (str): 'Director'
+            FILTER (str): 'director'
+    """
+    TAG = 'Director'
+    FILTER = 'director'
+
+
+@utils.registerPlexObject
+class Genre(MediaTag):
+    """ Represents a single Genre media tag.
+
+        Attributes:
+            TAG (str): 'Genre'
+            FILTER (str): 'genre'
+    """
+    TAG = 'Genre'
+    FILTER = 'genre'
+
+
+@utils.registerPlexObject
+class Mood(MediaTag):
+    """ Represents a single Mood media tag.
+
+        Attributes:
+            TAG (str): 'Mood'
+            FILTER (str): 'mood'
+    """
+    TAG = 'Mood'
+    FILTER = 'mood'
+
+
+@utils.registerPlexObject
+class Producer(MediaTag):
+    """ Represents a single Producer media tag.
+
+        Attributes:
+            TAG (str): 'Producer'
+            FILTER (str): 'producer'
+    """
+    TAG = 'Producer'
+    FILTER = 'producer'
+
+
+@utils.registerPlexObject
+class Role(MediaTag):
+    """ Represents a single Role (actor/actress) media tag.
+
+        Attributes:
+            TAG (str): 'Role'
+            FILTER (str): 'role'
+    """
+    TAG = 'Role'
+    FILTER = 'role'
+
+
+@utils.registerPlexObject
+class Similar(MediaTag):
+    """ Represents a single Similar media tag.
+
+        Attributes:
+            TAG (str): 'Similar'
+            FILTER (str): 'similar'
+    """
+    TAG = 'Similar'
+    FILTER = 'similar'
+
+
+@utils.registerPlexObject
+class Writer(MediaTag):
+    """ Represents a single Writer media tag.
+
+        Attributes:
+            TAG (str): 'Writer'
+            FILTER (str): 'writer'
+    """
+    TAG = 'Writer'
+    FILTER = 'writer'
+
+
+@utils.registerPlexObject
+class Chapter(PlexObject):
+    """ Represents a single Writer media tag.
+
+        Attributes:
+            TAG (str): 'Chapter'
+    """
+    TAG = 'Chapter'
+
+    def _loadData(self, data):
+        self._data = data
+        self.id = cast(int, data.attrib.get('id', 0))
+        self.filter = data.attrib.get('filter')  # I couldn't filter on it anyways
+        self.tag = data.attrib.get('tag')
+        self.title = self.tag
+        self.index = cast(int, data.attrib.get('index'))
+        self.start = cast(int, data.attrib.get('startTimeOffset'))
+        self.end = cast(int, data.attrib.get('endTimeOffset'))
+
+
+@utils.registerPlexObject
+class Field(PlexObject):
+    """ Represents a single Field.
+
+        Attributes:
+            TAG (str): 'Field'
+    """
+    TAG = 'Field'
+
+    def _loadData(self, data):
+        self._data = data
+        self.name = data.attrib.get('name')
+        self.locked = cast(bool, data.attrib.get('locked'))

lib/plexapi/myplex.py

@@ -0,0 +1,727 @@
+# -*- coding: utf-8 -*-
+import copy
+import requests
+import time
+from requests.status_codes import _codes as codes
+from plexapi import BASE_HEADERS, CONFIG, TIMEOUT
+from plexapi import log, logfilter, utils
+from plexapi.base import PlexObject
+from plexapi.exceptions import BadRequest, NotFound
+from plexapi.client import PlexClient
+from plexapi.compat import ElementTree
+from plexapi.library import LibrarySection
+from plexapi.server import PlexServer
+from plexapi.utils import joinArgs
+
+
+class MyPlexAccount(PlexObject):
+    """ MyPlex account and profile information. This object represents the data found Account on
+        the myplex.tv servers at the url https://plex.tv/users/account. You may create this object
+        directly by passing in your username & password (or token). There is also a convenience
+        method provided at :class:`~plexapi.server.PlexServer.myPlexAccount()` which will create
+        and return this object.
+
+        Parameters:
+            username (str): Your MyPlex username.
+            password (str): Your MyPlex password.
+            session (requests.Session, optional): Use your own session object if you want to
+                cache the http responses from PMS
+            timeout (int): timeout in seconds on initial connect to myplex (default config.TIMEOUT).
+
+        Attributes:
+            SIGNIN (str): 'https://plex.tv/users/sign_in.xml'
+            key (str): 'https://plex.tv/users/account'
+            authenticationToken (str): Unknown.
+            certificateVersion (str): Unknown.
+            cloudSyncDevice (str): Unknown.
+            email (str): Your current Plex email address.
+            entitlements (List<str>): List of devices your allowed to use with this account.
+            guest (bool): Unknown.
+            home (bool): Unknown.
+            homeSize (int): Unknown.
+            id (str): Your Plex account ID.
+            locale (str): Your Plex locale
+            mailing_list_status (str): Your current mailing list status.
+            maxHomeSize (int): Unknown.
+            queueEmail (str): Email address to add items to your `Watch Later` queue.
+            queueUid (str): Unknown.
+            restricted (bool): Unknown.
+            roles: (List<str>) Lit of account roles. Plexpass membership listed here.
+            scrobbleTypes (str): Description
+            secure (bool): Description
+            subscriptionActive (bool): True if your subsctiption is active.
+            subscriptionFeatures: (List<str>) List of features allowed on your subscription.
+            subscriptionPlan (str): Name of subscription plan.
+            subscriptionStatus (str): String representation of `subscriptionActive`.
+            thumb (str): URL of your account thumbnail.
+            title (str): Unknown. - Looks like an alias for `username`.
+            username (str): Your account username.
+            uuid (str): Unknown.
+            _token (str): Token used to access this client.
+            _session (obj): Requests session object used to access this client.
+    """
+    FRIENDINVITE = 'https://plex.tv/api/servers/{machineId}/shared_servers'                     # post with data
+    FRIENDSERVERS = 'https://plex.tv/api/servers/{machineId}/shared_servers/{serverId}'         # put with data
+    PLEXSERVERS = 'https://plex.tv/api/servers/{machineId}'                                     # get
+    FRIENDUPDATE = 'https://plex.tv/api/friends/{userId}'                                       # put with args, delete
+    REMOVEINVITE = 'https://plex.tv/api/invites/requested/{userId}?friend=0&server=1&home=0'    # delete
+    REQUESTED = 'https://plex.tv/api/invites/requested'                                         # get
+    REQUESTS = 'https://plex.tv/api/invites/requests'                                           # get
+    SIGNIN = 'https://plex.tv/users/sign_in.xml'                                                # get with auth
+    WEBHOOKS = 'https://plex.tv/api/v2/user/webhooks'                                           # get, post with data
+    # Key may someday switch to the following url. For now the current value works.
+    # https://plex.tv/api/v2/user?X-Plex-Token={token}&X-Plex-Client-Identifier={clientId}
+    key = 'https://plex.tv/users/account'
+
+    def __init__(self, username=None, password=None, token=None, session=None, timeout=None):
+        self._token = token
+        self._session = session or requests.Session()
+        data, initpath = self._signin(username, password, timeout)
+        super(MyPlexAccount, self).__init__(self, data, initpath)
+
+    def _signin(self, username, password, timeout):
+        if self._token:
+            return self.query(self.key), self.key
+        username = username or CONFIG.get('auth.myplex_username')
+        password = password or CONFIG.get('auth.myplex_password')
+        data = self.query(self.SIGNIN, method=self._session.post, auth=(username, password), timeout=timeout)
+        return data, self.SIGNIN
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self._token = logfilter.add_secret(data.attrib.get('authenticationToken'))
+        self._webhooks = []
+        self.authenticationToken = self._token
+        self.certificateVersion = data.attrib.get('certificateVersion')
+        self.cloudSyncDevice = data.attrib.get('cloudSyncDevice')
+        self.email = data.attrib.get('email')
+        self.guest = utils.cast(bool, data.attrib.get('guest'))
+        self.home = utils.cast(bool, data.attrib.get('home'))
+        self.homeSize = utils.cast(int, data.attrib.get('homeSize'))
+        self.id = data.attrib.get('id')
+        self.locale = data.attrib.get('locale')
+        self.mailing_list_status = data.attrib.get('mailing_list_status')
+        self.maxHomeSize = utils.cast(int, data.attrib.get('maxHomeSize'))
+        self.queueEmail = data.attrib.get('queueEmail')
+        self.queueUid = data.attrib.get('queueUid')
+        self.restricted = utils.cast(bool, data.attrib.get('restricted'))
+        self.scrobbleTypes = data.attrib.get('scrobbleTypes')
+        self.secure = utils.cast(bool, data.attrib.get('secure'))
+        self.thumb = data.attrib.get('thumb')
+        self.title = data.attrib.get('title')
+        self.username = data.attrib.get('username')
+        self.uuid = data.attrib.get('uuid')
+        # TODO: Fetch missing MyPlexAccount attributes
+        self.subscriptionActive = None      # renamed on server
+        self.subscriptionStatus = None      # renamed on server
+        self.subscriptionPlan = None        # renmaed on server
+        self.subscriptionFeatures = None    # renamed on server
+        self.roles = None
+        self.entitlements = None
+
+    def device(self, name):
+        """ Returns the :class:`~plexapi.myplex.MyPlexDevice` that matches the name specified.
+
+            Parameters:
+                name (str): Name to match against.
+        """
+        for device in self.devices():
+            if device.name.lower() == name.lower():
+                return device
+        raise NotFound('Unable to find device %s' % name)
+
+    def devices(self):
+        """ Returns a list of all :class:`~plexapi.myplex.MyPlexDevice` objects connected to the server. """
+        data = self.query(MyPlexDevice.key)
+        return [MyPlexDevice(self, elem) for elem in data]
+
+    def _headers(self, **kwargs):
+        """ Returns dict containing base headers for all requests to the server. """
+        headers = BASE_HEADERS.copy()
+        if self._token:
+            headers['X-Plex-Token'] = self._token
+        headers.update(kwargs)
+        return headers
+
+    def query(self, url, method=None, headers=None, timeout=None, **kwargs):
+        method = method or self._session.get
+        timeout = timeout or TIMEOUT
+        log.debug('%s %s %s', method.__name__.upper(), url, kwargs.get('json', ''))
+        headers = self._headers(**headers or {})
+        response = method(url, headers=headers, timeout=timeout, **kwargs)
+        if response.status_code not in (200, 201, 204):  # pragma: no cover
+            codename = codes.get(response.status_code)[0]
+            errtext = response.text.replace('\n', ' ')
+            log.warning('BadRequest (%s) %s %s; %s' % (response.status_code, codename, response.url, errtext))
+            raise BadRequest('(%s) %s %s; %s' % (response.status_code, codename, response.url, errtext))
+        data = response.text.encode('utf8')
+        return ElementTree.fromstring(data) if data.strip() else None
+
+    def resource(self, name):
+        """ Returns the :class:`~plexapi.myplex.MyPlexResource` that matches the name specified.
+
+            Parameters:
+                name (str): Name to match against.
+        """
+        for resource in self.resources():
+            if resource.name.lower() == name.lower():
+                return resource
+        raise NotFound('Unable to find resource %s' % name)
+
+    def resources(self):
+        """ Returns a list of all :class:`~plexapi.myplex.MyPlexResource` objects connected to the server. """
+        data = self.query(MyPlexResource.key)
+        return [MyPlexResource(self, elem) for elem in data]
+
+    def inviteFriend(self, user, server, sections=None, allowSync=False, allowCameraUpload=False,
+          allowChannels=False, filterMovies=None, filterTelevision=None, filterMusic=None):
+        """ Share library content with the specified user.
+
+            Parameters:
+                user (str): MyPlexUser, username, email of the user to be added.
+                server (PlexServer): PlexServer object or machineIdentifier containing the library sections to share.
+                sections ([Section]): Library sections, names or ids to be shared (default None shares all sections).
+                allowSync (Bool): Set True to allow user to sync content.
+                allowCameraUpload (Bool): Set True to allow user to upload photos.
+                allowChannels (Bool): Set True to allow user to utilize installed channels.
+                filterMovies (Dict): Dict containing key 'contentRating' and/or 'label' each set to a list of
+                    values to be filtered. ex: {'contentRating':['G'], 'label':['foo']}
+                filterTelevision (Dict): Dict containing key 'contentRating' and/or 'label' each set to a list of
+                    values to be filtered. ex: {'contentRating':['G'], 'label':['foo']}
+                filterMusic (Dict): Dict containing key 'label' set to a list of values to be filtered.
+                    ex: {'label':['foo']}
+        """
+        username = user.username if isinstance(user, MyPlexUser) else user
+        machineId = server.machineIdentifier if isinstance(server, PlexServer) else server
+        sectionIds = self._getSectionIds(machineId, sections)
+        params = {
+            'server_id': machineId,
+            'shared_server': {'library_section_ids': sectionIds, 'invited_email': username},
+            'sharing_settings': {
+                'allowSync': ('1' if allowSync else '0'),
+                'allowCameraUpload': ('1' if allowCameraUpload else '0'),
+                'allowChannels': ('1' if allowChannels else '0'),
+                'filterMovies': self._filterDictToStr(filterMovies or {}),
+                'filterTelevision': self._filterDictToStr(filterTelevision or {}),
+                'filterMusic': self._filterDictToStr(filterMusic or {}),
+            },
+        }
+        headers = {'Content-Type': 'application/json'}
+        url = self.FRIENDINVITE.format(machineId=machineId)
+        return self.query(url, self._session.post, json=params, headers=headers)
+
+    def removeFriend(self, user):
+        """ Remove the specified user from all sharing.
+
+            Parameters:
+                user (str): MyPlexUser, username, email of the user to be added.
+        """
+        user = self.user(user)
+        url = self.FRIENDUPDATE if user.friend else self.REMOVEINVITE
+        url = url.format(userId=user.id)
+        return self.query(url, self._session.delete)
+
+    def updateFriend(self, user, server, sections=None, removeSections=False, allowSync=None, allowCameraUpload=None,
+                     allowChannels=None, filterMovies=None, filterTelevision=None, filterMusic=None):
+        """ Update the specified user's share settings.
+
+            Parameters:
+                user (str): MyPlexUser, username, email of the user to be added.
+                server (PlexServer): PlexServer object or machineIdentifier containing the library sections to share.
+                sections: ([Section]): Library sections, names or ids to be shared (default None shares all sections).
+                removeSections (Bool): Set True to remove all shares. Supersedes sections.
+                allowSync (Bool): Set True to allow user to sync content.
+                allowCameraUpload (Bool): Set True to allow user to upload photos.
+                allowChannels (Bool): Set True to allow user to utilize installed channels.
+                filterMovies (Dict): Dict containing key 'contentRating' and/or 'label' each set to a list of
+                    values to be filtered. ex: {'contentRating':['G'], 'label':['foo']}
+                filterTelevision (Dict): Dict containing key 'contentRating' and/or 'label' each set to a list of
+                    values to be filtered. ex: {'contentRating':['G'], 'label':['foo']}
+                filterMusic (Dict): Dict containing key 'label' set to a list of values to be filtered.
+                    ex: {'label':['foo']}
+        """
+        # Update friend servers
+        response_filters = ''
+        response_servers = ''
+        user = self.user(user.username if isinstance(user, MyPlexUser) else user)
+        machineId = server.machineIdentifier if isinstance(server, PlexServer) else server
+        sectionIds = self._getSectionIds(machineId, sections)
+        headers = {'Content-Type': 'application/json'}
+        # Determine whether user has access to the shared server.
+        user_servers = [s for s in user.servers if s.machineIdentifier == machineId]
+        if user_servers and sectionIds:
+            serverId = user_servers[0].id
+            params = {'server_id': machineId, 'shared_server': {'library_section_ids': sectionIds}}
+            url = self.FRIENDSERVERS.format(machineId=machineId, serverId=serverId)
+        else:
+            params = {'server_id': machineId, 'shared_server': {'library_section_ids': sectionIds,
+                "invited_id": user.id}}
+            url = self.FRIENDINVITE.format(machineId=machineId)
+        # Remove share sections, add shares to user without shares, or update shares
+        if sectionIds:
+            if removeSections is True:
+                response_servers = self.query(url, self._session.delete, json=params, headers=headers)
+            elif 'invited_id' in params.get('shared_server', ''):
+                response_servers = self.query(url, self._session.post, json=params, headers=headers)
+            else:
+                response_servers = self.query(url, self._session.put, json=params, headers=headers)
+        else:
+            log.warning('Section name, number of section object is required changing library sections')
+        # Update friend filters
+        url = self.FRIENDUPDATE.format(userId=user.id)
+        params = {}
+        if isinstance(allowSync, bool):
+            params['allowSync'] = '1' if allowSync else '0'
+        if isinstance(allowCameraUpload, bool):
+            params['allowCameraUpload'] = '1' if allowCameraUpload else '0'
+        if isinstance(allowChannels, bool):
+            params['allowChannels'] = '1' if allowChannels else '0'
+        if isinstance(filterMovies, dict):
+            params['filterMovies'] = self._filterDictToStr(filterMovies or {})  # '1' if allowChannels else '0'
+        if isinstance(filterTelevision, dict):
+            params['filterTelevision'] = self._filterDictToStr(filterTelevision or {})
+        if isinstance(allowChannels, dict):
+            params['filterMusic'] = self._filterDictToStr(filterMusic or {})
+        if params:
+            url += joinArgs(params)
+            response_filters = self.query(url, self._session.put)
+        return response_servers, response_filters
+
+    def user(self, username):
+        """ Returns the :class:`~myplex.MyPlexUser` that matches the email or username specified.
+
+            Parameters:
+                username (str): Username, email or id of the user to return.
+        """
+        for user in self.users():
+            # Home users don't have email, username etc.
+            if username.lower() == user.title.lower():
+                return user
+
+            elif (user.username and user.email and user.id and username.lower() in
+                 (user.username.lower(), user.email.lower(), str(user.id))):
+                return user
+
+        raise NotFound('Unable to find user %s' % username)
+
+    def users(self):
+        """ Returns a list of all :class:`~plexapi.myplex.MyPlexUser` objects connected to your account.
+            This includes both friends and pending invites. You can reference the user.friend to
+            distinguish between the two.
+        """
+        friends = [MyPlexUser(self, elem) for elem in self.query(MyPlexUser.key)]
+        requested = [MyPlexUser(self, elem, self.REQUESTED) for elem in self.query(self.REQUESTED)]
+        return friends + requested
+
+    def _getSectionIds(self, server, sections):
+        """ Converts a list of section objects or names to sectionIds needed for library sharing. """
+        if not sections: return []
+        # Get a list of all section ids for looking up each section.
+        allSectionIds = {}
+        machineIdentifier = server.machineIdentifier if isinstance(server, PlexServer) else server
+        url = self.PLEXSERVERS.replace('{machineId}', machineIdentifier)
+        data = self.query(url, self._session.get)
+        for elem in data[0]:
+            allSectionIds[elem.attrib.get('id', '').lower()] = elem.attrib.get('id')
+            allSectionIds[elem.attrib.get('title', '').lower()] = elem.attrib.get('id')
+            allSectionIds[elem.attrib.get('key', '').lower()] = elem.attrib.get('id')
+        log.debug(allSectionIds)
+        # Convert passed in section items to section ids from above lookup
+        sectionIds = []
+        for section in sections:
+            sectionKey = section.key if isinstance(section, LibrarySection) else section
+            sectionIds.append(allSectionIds[sectionKey.lower()])
+        return sectionIds
+
+    def _filterDictToStr(self, filterDict):
+        """ Converts friend filters to a string representation for transport. """
+        values = []
+        for key, vals in filterDict.items():
+            if key not in ('contentRating', 'label'):
+                raise BadRequest('Unknown filter key: %s', key)
+            values.append('%s=%s' % (key, '%2C'.join(vals)))
+        return '|'.join(values)
+
+    def addWebhook(self, url):
+        # copy _webhooks and append url
+        urls = self._webhooks[:] + [url]
+        return self.setWebhooks(urls)
+
+    def deleteWebhook(self, url):
+        urls = copy.copy(self._webhooks)
+        if url not in urls:
+            raise BadRequest('Webhook does not exist: %s' % url)
+        urls.remove(url)
+        return self.setWebhooks(urls)
+
+    def setWebhooks(self, urls):
+        log.info('Setting webhooks: %s' % urls)
+        data = self.query(self.WEBHOOKS, self._session.post, data={'urls[]': urls})
+        self._webhooks = self.listAttrs(data, 'url', etag='webhook')
+        return self._webhooks
+
+    def webhooks(self):
+        data = self.query(self.WEBHOOKS)
+        self._webhooks = self.listAttrs(data, 'url', etag='webhook')
+        return self._webhooks
+
+    def optOut(self, playback=None, library=None):
+        """ Opt in or out of sharing stuff with plex.
+            See: https://www.plex.tv/about/privacy-legal/
+        """
+        params = {}
+        if playback is not None:
+            params['optOutPlayback'] = int(playback)
+        if library is not None:
+            params['optOutLibraryStats'] = int(library)
+        url = 'https://plex.tv/api/v2/user/privacy'
+        return self.query(url, method=self._session.put, params=params)
+
+
+class MyPlexUser(PlexObject):
+    """ This object represents non-signed in users such as friends and linked
+        accounts. NOTE: This should not be confused with the :class:`~myplex.MyPlexAccount`
+        which is your specific account. The raw xml for the data presented here
+        can be found at: https://plex.tv/api/users/
+
+        Attributes:
+            TAG (str): 'User'
+            key (str): 'https://plex.tv/api/users/'
+            allowCameraUpload (bool): True if this user can upload images.
+            allowChannels (bool): True if this user has access to channels.
+            allowSync (bool): True if this user can sync.
+            email (str): User's email address (user@gmail.com).
+            filterAll (str): Unknown.
+            filterMovies (str): Unknown.
+            filterMusic (str): Unknown.
+            filterPhotos (str): Unknown.
+            filterTelevision (str): Unknown.
+            home (bool): Unknown.
+            id (int): User's Plex account ID.
+            protected (False): Unknown (possibly SSL enabled?).
+            recommendationsPlaylistId (str): Unknown.
+            restricted (str): Unknown.
+            thumb (str): Link to the users avatar.
+            title (str): Seems to be an aliad for username.
+            username (str): User's username.
+    """
+    TAG = 'User'
+    key = 'https://plex.tv/api/users/'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.friend = self._initpath == self.key
+        self.allowCameraUpload = utils.cast(bool, data.attrib.get('allowCameraUpload'))
+        self.allowChannels = utils.cast(bool, data.attrib.get('allowChannels'))
+        self.allowSync = utils.cast(bool, data.attrib.get('allowSync'))
+        self.email = data.attrib.get('email')
+        self.filterAll = data.attrib.get('filterAll')
+        self.filterMovies = data.attrib.get('filterMovies')
+        self.filterMusic = data.attrib.get('filterMusic')
+        self.filterPhotos = data.attrib.get('filterPhotos')
+        self.filterTelevision = data.attrib.get('filterTelevision')
+        self.home = utils.cast(bool, data.attrib.get('home'))
+        self.id = utils.cast(int, data.attrib.get('id'))
+        self.protected = utils.cast(bool, data.attrib.get('protected'))
+        self.recommendationsPlaylistId = data.attrib.get('recommendationsPlaylistId')
+        self.restricted = data.attrib.get('restricted')
+        self.thumb = data.attrib.get('thumb')
+        self.title = data.attrib.get('title', '')
+        self.username = data.attrib.get('username', '')
+        self.servers = self.findItems(data, MyPlexServerShare)
+
+    def get_token(self, machineIdentifier):
+        try:
+            for item in self._server.query(self._server.FRIENDINVITE.format(machineId=machineIdentifier)):
+                if utils.cast(int, item.attrib.get('userID')) == self.id:
+                    return item.attrib.get('accessToken')
+        except Exception:
+            log.exception('Failed to get access token for %s' % self.title)
+
+
+class Section(PlexObject):
+    """ This refers to a shared section. The raw xml for the data presented here
+        can be found at: https://plex.tv/api/servers/{machineId}/shared_servers/{serverId}
+
+        Attributes:
+            TAG (str): section
+            id (int): shared section id
+            sectionKey (str): what key we use for this section
+            title (str): Title of the section
+            sectionId (str): shared section id
+            type (str): movie, tvshow, artist
+            shared (bool): If this section is shared with the user
+
+    """
+    TAG = 'Section'
+
+    def _loadData(self, data):
+        self._data = data
+        # self.id = utils.cast(int, data.attrib.get('id'))  # Havnt decided if this should be changed.
+        self.sectionKey = data.attrib.get('key')
+        self.title = data.attrib.get('title')
+        self.sectionId = data.attrib.get('id')
+        self.type = data.attrib.get('type')
+        self.shared = utils.cast(bool, data.attrib.get('shared'))
+
+
+class MyPlexServerShare(PlexObject):
+    """ Represents a single user's server reference. Used for library sharing.
+
+        Attributes:
+            id (int): id for this share
+            serverId (str): what id plex uses for this.
+            machineIdentifier (str): The servers machineIdentifier
+            name (str): The servers name
+            lastSeenAt (datetime): Last connected to the server?
+            numLibraries (int): Total number of libraries
+            allLibraries (bool): True if all libraries is shared with this user.
+            owned (bool): 1 if the server is owned by the user
+            pending (bool): True if the invite is pending.
+
+    """
+    TAG = 'Server'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.id = utils.cast(int, data.attrib.get('id'))
+        self.serverId = utils.cast(int, data.attrib.get('serverId'))
+        self.machineIdentifier = data.attrib.get('machineIdentifier')
+        self.name = data.attrib.get('name')
+        self.lastSeenAt = utils.toDatetime(data.attrib.get('lastSeenAt'))
+        self.numLibraries = utils.cast(int, data.attrib.get('numLibraries'))
+        self.allLibraries = utils.cast(bool, data.attrib.get('allLibraries'))
+        self.owned = utils.cast(bool, data.attrib.get('owned'))
+        self.pending = utils.cast(bool, data.attrib.get('pending'))
+
+    def sections(self):
+        url = MyPlexAccount.FRIENDSERVERS.format(machineId=self.machineIdentifier, serverId=self.id)
+        data = self._server.query(url)
+        sections = []
+
+        for section in data.iter('Section'):
+            if ElementTree.iselement(section):
+                sections.append(Section(self, section, url))
+
+        return sections
+
+
+class MyPlexResource(PlexObject):
+    """ This object represents resources connected to your Plex server that can provide
+        content such as Plex Media Servers, iPhone or Android clients, etc. The raw xml
+        for the data presented here can be found at:
+        https://plex.tv/api/resources?includeHttps=1&includeRelay=1
+
+        Attributes:
+            TAG (str): 'Device'
+            key (str): 'https://plex.tv/api/resources?includeHttps=1&includeRelay=1'
+            accessToken (str): This resources accesstoken.
+            clientIdentifier (str): Unique ID for this resource.
+            connections (list): List of :class:`~myplex.ResourceConnection` objects
+                for this resource.
+            createdAt (datetime): Timestamp this resource first connected to your server.
+            device (str): Best guess on the type of device this is (PS, iPhone, Linux, etc).
+            home (bool): Unknown
+            lastSeenAt (datetime): Timestamp this resource last connected.
+            name (str): Descriptive name of this resource.
+            owned (bool): True if this resource is one of your own (you logged into it).
+            platform (str): OS the resource is running (Linux, Windows, Chrome, etc.)
+            platformVersion (str): Version of the platform.
+            presence (bool): True if the resource is online
+            product (str): Plex product (Plex Media Server, Plex for iOS, Plex Web, etc.)
+            productVersion (str): Version of the product.
+            provides (str): List of services this resource provides (client, server,
+                player, pubsub-player, etc.)
+            synced (bool): Unknown (possibly True if the resource has synced content?)
+    """
+    TAG = 'Device'
+    key = 'https://plex.tv/api/resources?includeHttps=1&includeRelay=1'
+
+    def _loadData(self, data):
+        self._data = data
+        self.name = data.attrib.get('name')
+        self.accessToken = logfilter.add_secret(data.attrib.get('accessToken'))
+        self.product = data.attrib.get('product')
+        self.productVersion = data.attrib.get('productVersion')
+        self.platform = data.attrib.get('platform')
+        self.platformVersion = data.attrib.get('platformVersion')
+        self.device = data.attrib.get('device')
+        self.clientIdentifier = data.attrib.get('clientIdentifier')
+        self.createdAt = utils.toDatetime(data.attrib.get('createdAt'))
+        self.lastSeenAt = utils.toDatetime(data.attrib.get('lastSeenAt'))
+        self.provides = data.attrib.get('provides')
+        self.owned = utils.cast(bool, data.attrib.get('owned'))
+        self.home = utils.cast(bool, data.attrib.get('home'))
+        self.synced = utils.cast(bool, data.attrib.get('synced'))
+        self.presence = utils.cast(bool, data.attrib.get('presence'))
+        self.connections = self.findItems(data, ResourceConnection)
+        self.publicAddressMatches = utils.cast(bool, data.attrib.get('publicAddressMatches'))
+        # This seems to only be available if its not your device (say are shared server)
+        self.httpsRequired = utils.cast(bool, data.attrib.get('httpsRequired'))
+        self.ownerid = utils.cast(int, data.attrib.get('ownerId', 0))
+        self.sourceTitle = data.attrib.get('sourceTitle')  # owners plex username.
+
+    def connect(self, ssl=None, timeout=None):
+        """ Returns a new :class:`~server.PlexServer` or :class:`~client.PlexClient` object.
+            Often times there is more than one address specified for a server or client.
+            This function will prioritize local connections before remote and HTTPS before HTTP.
+            After trying to connect to all available addresses for this resource and
+            assuming at least one connection was successful, the PlexServer object is built and returned.
+
+            Parameters:
+                ssl (optional): Set True to only connect to HTTPS connections. Set False to
+                    only connect to HTTP connections. Set None (default) to connect to any
+                    HTTP or HTTPS connection.
+
+            Raises:
+                :class:`~plexapi.exceptions.NotFound`: When unable to connect to any addresses for this resource.
+        """
+        # Sort connections from (https, local) to (http, remote)
+        # Only check non-local connections unless we own the resource
+        connections = sorted(self.connections, key=lambda c: c.local, reverse=True)
+        owned_or_unowned_non_local = lambda x: self.owned or (not self.owned and not x.local)
+        https = [c.uri for c in connections if owned_or_unowned_non_local(c)]
+        http = [c.httpuri for c in connections if owned_or_unowned_non_local(c)]
+        cls = PlexServer if 'server' in self.provides else PlexClient
+        # Force ssl, no ssl, or any (default)
+        if ssl is True: connections = https
+        elif ssl is False: connections = http
+        else: connections = https + http
+        # Try connecting to all known resource connections in parellel, but
+        # only return the first server (in order) that provides a response.
+        listargs = [[cls, url, self.accessToken, timeout] for url in connections]
+        log.info('Testing %s resource connections..', len(listargs))
+        results = utils.threaded(_connect, listargs)
+        return _chooseConnection('Resource', self.name, results)
+
+
+class ResourceConnection(PlexObject):
+    """ Represents a Resource Connection object found within the
+        :class:`~myplex.MyPlexResource` objects.
+
+        Attributes:
+            TAG (str): 'Connection'
+            address (str): Local IP address
+            httpuri (str): Full local address
+            local (bool): True if local
+            port (int): 32400
+            protocol (str): HTTP or HTTPS
+            uri (str): External address
+    """
+    TAG = 'Connection'
+
+    def _loadData(self, data):
+        self._data = data
+        self.protocol = data.attrib.get('protocol')
+        self.address = data.attrib.get('address')
+        self.port = utils.cast(int, data.attrib.get('port'))
+        self.uri = data.attrib.get('uri')
+        self.local = utils.cast(bool, data.attrib.get('local'))
+        self.httpuri = 'http://%s:%s' % (self.address, self.port)
+        self.relay = utils.cast(bool, data.attrib.get('relay'))
+
+
+class MyPlexDevice(PlexObject):
+    """ This object represents resources connected to your Plex server that provide
+        playback ability from your Plex Server, iPhone or Android clients, Plex Web,
+        this API, etc. The raw xml for the data presented here can be found at:
+        https://plex.tv/devices.xml
+
+        Attributes:
+            TAG (str): 'Device'
+            key (str): 'https://plex.tv/devices.xml'
+            clientIdentifier (str): Unique ID for this resource.
+            connections (list): List of connection URIs for the device.
+            device (str): Best guess on the type of device this is (Linux, iPad, AFTB, etc).
+            id (str): MyPlex ID of the device.
+            model (str): Model of the device (bueller, Linux, x86_64, etc.)
+            name (str): Hostname of the device.
+            platform (str): OS the resource is running (Linux, Windows, Chrome, etc.)
+            platformVersion (str): Version of the platform.
+            product (str): Plex product (Plex Media Server, Plex for iOS, Plex Web, etc.)
+            productVersion (string): Version of the product.
+            provides (str): List of services this resource provides (client, controller,
+                sync-target, player, pubsub-player).
+            publicAddress (str): Public IP address.
+            screenDensity (str): Unknown
+            screenResolution (str): Screen resolution (750x1334, 1242x2208, etc.)
+            token (str): Plex authentication token for the device.
+            vendor (str): Device vendor (ubuntu, etc).
+            version (str): Unknown (1, 2, 1.3.3.3148-b38628e, 1.3.15, etc.)
+    """
+    TAG = 'Device'
+    key = 'https://plex.tv/devices.xml'
+
+    def _loadData(self, data):
+        self._data = data
+        self.name = data.attrib.get('name')
+        self.publicAddress = data.attrib.get('publicAddress')
+        self.product = data.attrib.get('product')
+        self.productVersion = data.attrib.get('productVersion')
+        self.platform = data.attrib.get('platform')
+        self.platformVersion = data.attrib.get('platformVersion')
+        self.device = data.attrib.get('device')
+        self.model = data.attrib.get('model')
+        self.vendor = data.attrib.get('vendor')
+        self.provides = data.attrib.get('provides')
+        self.clientIdentifier = data.attrib.get('clientIdentifier')
+        self.version = data.attrib.get('version')
+        self.id = data.attrib.get('id')
+        self.token = logfilter.add_secret(data.attrib.get('token'))
+        self.screenResolution = data.attrib.get('screenResolution')
+        self.screenDensity = data.attrib.get('screenDensity')
+        self.createdAt = utils.toDatetime(data.attrib.get('createdAt'))
+        self.lastSeenAt = utils.toDatetime(data.attrib.get('lastSeenAt'))
+        self.connections = [connection.attrib.get('uri') for connection in data.iter('Connection')]
+
+    def connect(self, timeout=None):
+        """ Returns a new :class:`~plexapi.client.PlexClient` or :class:`~plexapi.server.PlexServer`
+            Sometimes there is more than one address specified for a server or client.
+            After trying to connect to all available addresses for this client and assuming
+            at least one connection was successful, the PlexClient object is built and returned.
+
+            Raises:
+                :class:`~plexapi.exceptions.NotFound`: When unable to connect to any addresses for this device.
+        """
+        cls = PlexServer if 'server' in self.provides else PlexClient
+        listargs = [[cls, url, self.token, timeout] for url in self.connections]
+        log.info('Testing %s device connections..', len(listargs))
+        results = utils.threaded(_connect, listargs)
+        return _chooseConnection('Device', self.name, results)
+
+    def delete(self):
+        """ Remove this device from your account. """
+        key = 'https://plex.tv/devices/%s.xml' % self.id
+        self._server.query(key, self._server._session.delete)
+
+
+def _connect(cls, url, token, timeout, results, i):
+    """ Connects to the specified cls with url and token. Stores the connection
+        information to results[i] in a threadsafe way.
+    """
+    starttime = time.time()
+    try:
+        device = cls(baseurl=url, token=token, timeout=timeout)
+        runtime = int(time.time() - starttime)
+        results[i] = (url, token, device, runtime)
+    except Exception as err:
+        runtime = int(time.time() - starttime)
+        log.error('%s: %s', url, err)
+        results[i] = (url, token, None, runtime)
+
+
+def _chooseConnection(ctype, name, results):
+    """ Chooses the first (best) connection from the given _connect results. """
+    # At this point we have a list of result tuples containing (url, token, PlexServer, runtime)
+    # or (url, token, None, runtime) in the case a connection could not be established.
+    for url, token, result, runtime in results:
+        okerr = 'OK' if result else 'ERR'
+        log.info('%s connection %s (%ss): %s?X-Plex-Token=%s', ctype, okerr, runtime, url, token)
+    results = [r[2] for r in results if r and r[2] is not None]
+    if results:
+        log.info('Connecting to %s: %s?X-Plex-Token=%s', ctype, results[0]._baseurl, results[0]._token)
+        return results[0]
+    raise NotFound('Unable to connect to %s: %s' % (ctype.lower(), name))

lib/plexapi/photo.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+from plexapi import media, utils
+from plexapi.base import PlexPartialObject
+from plexapi.exceptions import NotFound
+
+
+@utils.registerPlexObject
+class Photoalbum(PlexPartialObject):
+    """ Represents a photoalbum (collection of photos).
+
+        Attributes:
+            TAG (str): 'Directory'
+            TYPE (str): 'photo'
+            addedAt (datetime): Datetime this item was added to the library.
+            art (str): Photo art (/library/metadata/<ratingkey>/art/<artid>)
+            composite (str): Unknown
+            guid (str): Unknown (unique ID)
+            index (sting): Index number of this album.
+            key (str): API URL (/library/metadata/<ratingkey>).
+            librarySectionID (int): :class:`~plexapi.library.LibrarySection` ID.
+            listType (str): Hardcoded as 'photo' (useful for search filters).
+            ratingKey (int): Unique key identifying this item.
+            summary (str): Summary of the photoalbum.
+            thumb (str): URL to thumbnail image.
+            title (str): Photoalbum title. (Trip to Disney World)
+            type (str): Unknown
+            updatedAt (datatime): Datetime this item was updated.
+    """
+    TAG = 'Directory'
+    TYPE = 'photo'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self.listType = 'photo'
+        self.addedAt = utils.toDatetime(data.attrib.get('addedAt'))
+        self.art = data.attrib.get('art')
+        self.composite = data.attrib.get('composite')
+        self.guid = data.attrib.get('guid')
+        self.index = utils.cast(int, data.attrib.get('index'))
+        self.key = data.attrib.get('key')
+        self.librarySectionID = data.attrib.get('librarySectionID')
+        self.ratingKey = data.attrib.get('ratingKey')
+        self.summary = data.attrib.get('summary')
+        self.thumb = data.attrib.get('thumb')
+        self.title = data.attrib.get('title')
+        self.type = data.attrib.get('type')
+        self.updatedAt = utils.toDatetime(data.attrib.get('updatedAt'))
+
+    def albums(self, **kwargs):
+        """ Returns a list of :class:`~plexapi.photo.Photoalbum` objects in this album. """
+        key = '/library/metadata/%s/children' % self.ratingKey
+        return self.fetchItems(key, etag='Directory', **kwargs)
+
+    def album(self, title):
+        """ Returns the :class:`~plexapi.photo.Photoalbum` that matches the specified title. """
+        for album in self.albums():
+            if album.title.lower() == title.lower():
+                return album
+        raise NotFound('Unable to find album: %s' % title)
+
+    def photos(self, **kwargs):
+        """ Returns a list of :class:`~plexapi.photo.Photo` objects in this album. """
+        key = '/library/metadata/%s/children' % self.ratingKey
+        return self.fetchItems(key, etag='Photo', **kwargs)
+
+    def photo(self, title):
+        """ Returns the :class:`~plexapi.photo.Photo` that matches the specified title. """
+        for photo in self.photos():
+            if photo.title.lower() == title.lower():
+                return photo
+        raise NotFound('Unable to find photo: %s' % title)
+
+
+@utils.registerPlexObject
+class Photo(PlexPartialObject):
+    """ Represents a single photo.
+
+        Attributes:
+            TAG (str): 'Photo'
+            TYPE (str): 'photo'
+            addedAt (datetime): Datetime this item was added to the library.
+            index (sting): Index number of this photo.
+            key (str): API URL (/library/metadata/<ratingkey>).
+            listType (str): Hardcoded as 'photo' (useful for search filters).
+            media (TYPE): Unknown
+            originallyAvailableAt (datetime): Datetime this photo was added to Plex.
+            parentKey (str): Photoalbum API URL.
+            parentRatingKey (int): Unique key identifying the photoalbum.
+            ratingKey (int): Unique key identifying this item.
+            summary (str): Summary of the photo.
+            thumb (str): URL to thumbnail image.
+            title (str): Photo title.
+            type (str): Unknown
+            updatedAt (datatime): Datetime this item was updated.
+            year (int): Year this photo was taken.
+    """
+    TAG = 'Photo'
+    TYPE = 'photo'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self.listType = 'photo'
+        self.addedAt = utils.toDatetime(data.attrib.get('addedAt'))
+        self.index = utils.cast(int, data.attrib.get('index'))
+        self.key = data.attrib.get('key')
+        self.originallyAvailableAt = utils.toDatetime(
+            data.attrib.get('originallyAvailableAt'), '%Y-%m-%d')
+        self.parentKey = data.attrib.get('parentKey')
+        self.parentRatingKey = data.attrib.get('parentRatingKey')
+        self.ratingKey = data.attrib.get('ratingKey')
+        self.summary = data.attrib.get('summary')
+        self.thumb = data.attrib.get('thumb')
+        self.title = data.attrib.get('title')
+        self.type = data.attrib.get('type')
+        self.updatedAt = utils.toDatetime(data.attrib.get('updatedAt'))
+        self.year = utils.cast(int, data.attrib.get('year'))
+        self.media = self.findItems(data, media.Media)
+
+    def photoalbum(self):
+        """ Return this photo's :class:`~plexapi.photo.Photoalbum`. """
+        return self.fetchItem(self.parentKey)
+
+    def section(self):
+        """ Returns the :class:`~plexapi.library.LibrarySection` this item belongs to. """
+        return self._server.library.sectionByID(self.photoalbum().librarySectionID)

lib/plexapi/playlist.py

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+from plexapi import utils
+from plexapi.base import PlexPartialObject, Playable
+from plexapi.exceptions import BadRequest
+from plexapi.playqueue import PlayQueue
+from plexapi.utils import cast, toDatetime
+
+
+@utils.registerPlexObject
+class Playlist(PlexPartialObject, Playable):
+    """ Represents a single Playlist object.
+        # TODO: Document attributes
+    """
+    TAG = 'Playlist'
+    TYPE = 'playlist'
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        Playable._loadData(self, data)
+        self.addedAt = toDatetime(data.attrib.get('addedAt'))
+        self.composite = data.attrib.get('composite')  # url to thumbnail
+        self.duration = cast(int, data.attrib.get('duration'))
+        self.durationInSeconds = cast(int, data.attrib.get('durationInSeconds'))
+        self.guid = data.attrib.get('guid')
+        self.key = data.attrib.get('key')
+        self.key = self.key.replace('/items', '') if self.key else self.key  # FIX_BUG_50
+        self.leafCount = cast(int, data.attrib.get('leafCount'))
+        self.playlistType = data.attrib.get('playlistType')
+        self.ratingKey = cast(int, data.attrib.get('ratingKey'))
+        self.smart = cast(bool, data.attrib.get('smart'))
+        self.summary = data.attrib.get('summary')
+        self.title = data.attrib.get('title')
+        self.type = data.attrib.get('type')
+        self.updatedAt = toDatetime(data.attrib.get('updatedAt'))
+        self._items = None  # cache for self.items
+
+    def __len__(self):  # pragma: no cover
+        return len(self.items())
+
+    def __contains__(self, other):  # pragma: no cover
+        return any(i.key == other.key for i in self.items())
+
+    def __getitem__(self, key):  # pragma: no cover
+        return self.items()[key]
+
+    def items(self):
+        """ Returns a list of all items in the playlist. """
+        if self._items is None:
+            key = '%s/items' % self.key
+            items = self.fetchItems(key)
+            self._items = items
+        return self._items
+
+    def addItems(self, items):
+        """ Add items to a playlist. """
+        if not isinstance(items, (list, tuple)):
+            items = [items]
+        ratingKeys = []
+        for item in items:
+            if item.listType != self.playlistType:  # pragma: no cover
+                raise BadRequest('Can not mix media types when building a playlist: %s and %s' %
+                    (self.playlistType, item.listType))
+            ratingKeys.append(str(item.ratingKey))
+        uuid = items[0].section().uuid
+        ratingKeys = ','.join(ratingKeys)
+        key = '%s/items%s' % (self.key, utils.joinArgs({
+            'uri': 'library://%s/directory//library/metadata/%s' % (uuid, ratingKeys)
+        }))
+        result = self._server.query(key, method=self._server._session.put)
+        self.reload()
+        return result
+
+    def removeItem(self, item):
+        """ Remove a file from a playlist. """
+        key = '%s/items/%s' % (self.key, item.playlistItemID)
+        result = self._server.query(key, method=self._server._session.delete)
+        self.reload()
+        return result
+
+    def moveItem(self, item, after=None):
+        """ Move a to a new position in playlist. """
+        key = '%s/items/%s/move' % (self.key, item.playlistItemID)
+        if after:
+            key += '?after=%s' % after.playlistItemID
+        result = self._server.query(key, method=self._server._session.put)
+        self.reload()
+        return result
+
+    def edit(self, title=None, summary=None):
+        """ Edit playlist. """
+        key = '/library/metadata/%s%s' % (self.ratingKey, utils.joinArgs({'title': title, 'summary': summary}))
+        result = self._server.query(key, method=self._server._session.put)
+        self.reload()
+        return result
+
+    def delete(self):
+        """ Delete playlist. """
+        return self._server.query(self.key, method=self._server._session.delete)
+
+    def playQueue(self, *args, **kwargs):
+        """ Create a playqueue from this playlist. """
+        return PlayQueue.create(self._server, self, *args, **kwargs)
+
+    @classmethod
+    def create(cls, server, title, items):
+        """ Create a playlist. """
+        if not isinstance(items, (list, tuple)):
+            items = [items]
+        ratingKeys = []
+        for item in items:
+            if item.listType != items[0].listType:  # pragma: no cover
+                raise BadRequest('Can not mix media types when building a playlist')
+            ratingKeys.append(str(item.ratingKey))
+        ratingKeys = ','.join(ratingKeys)
+        uuid = items[0].section().uuid
+        key = '/playlists%s' % utils.joinArgs({
+            'uri': 'library://%s/directory//library/metadata/%s' % (uuid, ratingKeys),
+            'type': items[0].listType,
+            'title': title,
+            'smart': 0
+        })
+        data = server.query(key, method=server._session.post)[0]
+        return cls(server, data, initpath=key)
+
+    def copyToUser(self, user):
+        """ Copy playlist to another user account. """
+        from plexapi.server import PlexServer
+        myplex = self._server.myPlexAccount()
+        user = myplex.user(user)
+        # Get the token for your machine.
+        token = user.get_token(self._server.machineIdentifier)
+        # Login to your server using your friends credentials.
+        user_server = PlexServer(self._server._baseurl, token)
+        return self.create(user_server, self.title, self.items())

lib/plexapi/playqueue.py

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+from plexapi import utils
+from plexapi.base import PlexObject
+
+
+class PlayQueue(PlexObject):
+    """ Control a PlayQueue.
+
+        Attributes:
+            key (str): This is only added to support playMedia
+            identifier (str): com.plexapp.plugins.library
+            initpath (str): Relative url where data was grabbed from.
+            items (list): List of :class:`~plexapi.media.Media` or class:`~plexapi.playlist.Playlist`
+            mediaTagPrefix (str): Fx /system/bundle/media/flags/
+            mediaTagVersion (str): Fx 1485957738
+            playQueueID (str): a id for the playqueue
+            playQueueSelectedItemID (str): playQueueSelectedItemID
+            playQueueSelectedItemOffset (str): playQueueSelectedItemOffset
+            playQueueSelectedMetadataItemID (<type 'str'>): 7
+            playQueueShuffled (bool): True if shuffled
+            playQueueSourceURI (str): Fx library://150425c9-0d99-4242-821e-e5ab81cd2221/item//library/metadata/7
+            playQueueTotalCount (str): How many items in the play queue.
+            playQueueVersion (str): What version the playqueue is.
+            server (:class:`~plexapi.server.PlexServer`): Server you are connected to.
+            size (str): Seems to be a alias for playQueueTotalCount.
+    """
+
+    def _loadData(self, data):
+        self._data = data
+        self.identifier = data.attrib.get('identifier')
+        self.mediaTagPrefix = data.attrib.get('mediaTagPrefix')
+        self.mediaTagVersion = data.attrib.get('mediaTagVersion')
+        self.playQueueID = data.attrib.get('playQueueID')
+        self.playQueueSelectedItemID = data.attrib.get('playQueueSelectedItemID')
+        self.playQueueSelectedItemOffset = data.attrib.get('playQueueSelectedItemOffset')
+        self.playQueueSelectedMetadataItemID = data.attrib.get('playQueueSelectedMetadataItemID')
+        self.playQueueShuffled = utils.cast(bool, data.attrib.get('playQueueShuffled', 0))
+        self.playQueueSourceURI = data.attrib.get('playQueueSourceURI')
+        self.playQueueTotalCount = data.attrib.get('playQueueTotalCount')
+        self.playQueueVersion = data.attrib.get('playQueueVersion')
+        self.size = utils.cast(int, data.attrib.get('size', 0))
+        self.items = self.findItems(data)
+
+    @classmethod
+    def create(cls, server, item, shuffle=0, repeat=0, includeChapters=1, includeRelated=1):
+        """ Create and returns a new :class:`~plexapi.playqueue.PlayQueue`.
+
+            Paramaters:
+                server (:class:`~plexapi.server.PlexServer`): Server you are connected to.
+                item (:class:`~plexapi.media.Media` or class:`~plexapi.playlist.Playlist`): A media or Playlist.
+                shuffle (int, optional): Start the playqueue shuffled.
+                repeat (int, optional): Start the playqueue shuffled.
+                includeChapters (int, optional): include Chapters.
+                includeRelated (int, optional): include Related.
+        """
+        args = {}
+        args['includeChapters'] = includeChapters
+        args['includeRelated'] = includeRelated
+        args['repeat'] = repeat
+        args['shuffle'] = shuffle
+        if item.type == 'playlist':
+            args['playlistID'] = item.ratingKey
+            args['type'] = item.playlistType
+        else:
+            uuid = item.section().uuid
+            args['key'] = item.key
+            args['type'] = item.listType
+            args['uri'] = 'library://%s/item/%s' % (uuid, item.key)
+        path = '/playQueues%s' % utils.joinArgs(args)
+        data = server.query(path, method=server._session.post)
+        c = cls(server, data, initpath=path)
+        # we manually add a key so we can pass this to playMedia
+        # since the data, does not contain a key.
+        c.key = item.key
+        return c

lib/plexapi/server.py

@@ -0,0 +1,471 @@
+# -*- coding: utf-8 -*-
+import requests
+from requests.status_codes import _codes as codes
+from plexapi import BASE_HEADERS, CONFIG, TIMEOUT
+from plexapi import log, logfilter, utils
+from plexapi.alert import AlertListener
+from plexapi.base import PlexObject
+from plexapi.client import PlexClient
+from plexapi.compat import ElementTree, urlencode
+from plexapi.exceptions import BadRequest, NotFound
+from plexapi.library import Library, Hub
+from plexapi.settings import Settings
+from plexapi.playlist import Playlist
+from plexapi.playqueue import PlayQueue
+from plexapi.utils import cast
+
+# Need these imports to populate utils.PLEXOBJECTS
+from plexapi import (audio as _audio, video as _video,        # noqa: F401
+    photo as _photo, media as _media, playlist as _playlist)  # noqa: F401
+
+
+class PlexServer(PlexObject):
+    """ This is the main entry point to interacting with a Plex server. It allows you to
+        list connected clients, browse your library sections and perform actions such as
+        emptying trash. If you do not know the auth token required to access your Plex
+        server, or simply want to access your server with your username and password, you
+        can also create an PlexServer instance from :class:`~plexapi.myplex.MyPlexAccount`.
+
+        Parameters:
+            baseurl (str): Base url for to access the Plex Media Server (default: 'http://localhost:32400').
+            token (str): Required Plex authentication token to access the server.
+            session (requests.Session, optional): Use your own session object if you want to
+                cache the http responses from PMS
+            timeout (int): timeout in seconds on initial connect to server (default config.TIMEOUT).
+
+        Attributes:
+            allowCameraUpload (bool): True if server allows camera upload.
+            allowChannelAccess (bool): True if server allows channel access (iTunes?).
+            allowMediaDeletion (bool): True is server allows media to be deleted.
+            allowSharing (bool): True is server allows sharing.
+            allowSync (bool): True is server allows sync.
+            backgroundProcessing (bool): Unknown
+            certificate (bool): True if server has an HTTPS certificate.
+            companionProxy (bool): Unknown
+            diagnostics (bool): Unknown
+            eventStream (bool): Unknown
+            friendlyName (str): Human friendly name for this server.
+            hubSearch (bool): True if `Hub Search <https://www.plex.tv/blog
+                /seek-plex-shall-find-leveling-web-app/>`_ is enabled. I believe this
+                is enabled for everyone
+            machineIdentifier (str): Unique ID for this server (looks like an md5).
+            multiuser (bool): True if `multiusers <https://support.plex.tv/hc/en-us/articles
+                /200250367-Multi-User-Support>`_ are enabled.
+            myPlex (bool): Unknown (True if logged into myPlex?).
+            myPlexMappingState (str): Unknown (ex: mapped).
+            myPlexSigninState (str): Unknown (ex: ok).
+            myPlexSubscription (bool): True if you have a myPlex subscription.
+            myPlexUsername (str): Email address if signed into myPlex (user@example.com)
+            ownerFeatures (list): List of features allowed by the server owner. This may be based
+                on your PlexPass subscription. Features include: camera_upload, cloudsync,
+                content_filter, dvr, hardware_transcoding, home, lyrics, music_videos, pass,
+                photo_autotags, premium_music_metadata, session_bandwidth_restrictions, sync,
+                trailers, webhooks (and maybe more).
+            photoAutoTag (bool): True if photo `auto-tagging <https://support.plex.tv/hc/en-us
+                /articles/234976627-Auto-Tagging-of-Photos>`_ is enabled.
+            platform (str): Platform the server is hosted on (ex: Linux)
+            platformVersion (str): Platform version (ex: '6.1 (Build 7601)', '4.4.0-59-generic').
+            pluginHost (bool): Unknown
+            readOnlyLibraries (bool): Unknown
+            requestParametersInCookie (bool): Unknown
+            streamingBrainVersion (bool): Current `Streaming Brain <https://www.plex.tv/blog
+                /mcstreamy-brain-take-world-two-easy-steps/>`_ version.
+            sync (bool): True if `syncing to a device <https://support.plex.tv/hc/en-us/articles
+                /201053678-Sync-Media-to-a-Device>`_ is enabled.
+            transcoderActiveVideoSessions (int): Number of active video transcoding sessions.
+            transcoderAudio (bool): True if audio transcoding audio is available.
+            transcoderLyrics (bool): True if audio transcoding lyrics is available.
+            transcoderPhoto (bool): True if audio transcoding photos is available.
+            transcoderSubtitles (bool): True if audio transcoding subtitles is available.
+            transcoderVideo (bool): True if audio transcoding video is available.
+            transcoderVideoBitrates (bool): List of video bitrates.
+            transcoderVideoQualities (bool): List of video qualities.
+            transcoderVideoResolutions (bool): List of video resolutions.
+            updatedAt (int): Datetime the server was updated.
+            updater (bool): Unknown
+            version (str): Current Plex version (ex: 1.3.2.3112-1751929)
+            voiceSearch (bool): True if voice search is enabled. (is this Google Voice search?)
+            _baseurl (str): HTTP address of the client.
+            _token (str): Token used to access this client.
+            _session (obj): Requests session object used to access this client.
+    """
+    key = '/'
+
+    def __init__(self, baseurl=None, token=None, session=None, timeout=None):
+        self._baseurl = baseurl or CONFIG.get('auth.server_baseurl', 'http://localhost:32400')
+        self._token = logfilter.add_secret(token or CONFIG.get('auth.server_token'))
+        self._showSecrets = CONFIG.get('log.show_secrets', '').lower() == 'true'
+        self._session = session or requests.Session()
+        self._library = None   # cached library
+        self._settings = None   # cached settings
+        self._myPlexAccount = None   # cached myPlexAccount
+        data = self.query(self.key, timeout=timeout)
+        super(PlexServer, self).__init__(self, data, self.key)
+
+    def _loadData(self, data):
+        """ Load attribute values from Plex XML response. """
+        self._data = data
+        self.allowCameraUpload = cast(bool, data.attrib.get('allowCameraUpload'))
+        self.allowChannelAccess = cast(bool, data.attrib.get('allowChannelAccess'))
+        self.allowMediaDeletion = cast(bool, data.attrib.get('allowMediaDeletion'))
+        self.allowSharing = cast(bool, data.attrib.get('allowSharing'))
+        self.allowSync = cast(bool, data.attrib.get('allowSync'))
+        self.backgroundProcessing = cast(bool, data.attrib.get('backgroundProcessing'))
+        self.certificate = cast(bool, data.attrib.get('certificate'))
+        self.companionProxy = cast(bool, data.attrib.get('companionProxy'))
+        self.diagnostics = utils.toList(data.attrib.get('diagnostics'))
+        self.eventStream = cast(bool, data.attrib.get('eventStream'))
+        self.friendlyName = data.attrib.get('friendlyName')
+        self.hubSearch = cast(bool, data.attrib.get('hubSearch'))
+        self.machineIdentifier = data.attrib.get('machineIdentifier')
+        self.multiuser = cast(bool, data.attrib.get('multiuser'))
+        self.myPlex = cast(bool, data.attrib.get('myPlex'))
+        self.myPlexMappingState = data.attrib.get('myPlexMappingState')
+        self.myPlexSigninState = data.attrib.get('myPlexSigninState')
+        self.myPlexSubscription = cast(bool, data.attrib.get('myPlexSubscription'))
+        self.myPlexUsername = data.attrib.get('myPlexUsername')
+        self.ownerFeatures = utils.toList(data.attrib.get('ownerFeatures'))
+        self.photoAutoTag = cast(bool, data.attrib.get('photoAutoTag'))
+        self.platform = data.attrib.get('platform')
+        self.platformVersion = data.attrib.get('platformVersion')
+        self.pluginHost = cast(bool, data.attrib.get('pluginHost'))
+        self.readOnlyLibraries = cast(int, data.attrib.get('readOnlyLibraries'))
+        self.requestParametersInCookie = cast(bool, data.attrib.get('requestParametersInCookie'))
+        self.streamingBrainVersion = data.attrib.get('streamingBrainVersion')
+        self.sync = cast(bool, data.attrib.get('sync'))
+        self.transcoderActiveVideoSessions = int(data.attrib.get('transcoderActiveVideoSessions', 0))
+        self.transcoderAudio = cast(bool, data.attrib.get('transcoderAudio'))
+        self.transcoderLyrics = cast(bool, data.attrib.get('transcoderLyrics'))
+        self.transcoderPhoto = cast(bool, data.attrib.get('transcoderPhoto'))
+        self.transcoderSubtitles = cast(bool, data.attrib.get('transcoderSubtitles'))
+        self.transcoderVideo = cast(bool, data.attrib.get('transcoderVideo'))
+        self.transcoderVideoBitrates = utils.toList(data.attrib.get('transcoderVideoBitrates'))
+        self.transcoderVideoQualities = utils.toList(data.attrib.get('transcoderVideoQualities'))
+        self.transcoderVideoResolutions = utils.toList(data.attrib.get('transcoderVideoResolutions'))
+        self.updatedAt = utils.toDatetime(data.attrib.get('updatedAt'))
+        self.updater = cast(bool, data.attrib.get('updater'))
+        self.version = data.attrib.get('version')
+        self.voiceSearch = cast(bool, data.attrib.get('voiceSearch'))
+
+    def _headers(self, **kwargs):
+        """ Returns dict containing base headers for all requests to the server. """
+        headers = BASE_HEADERS.copy()
+        if self._token:
+            headers['X-Plex-Token'] = self._token
+        headers.update(kwargs)
+        return headers
+
+    @property
+    def library(self):
+        """ Library to browse or search your media. """
+        if not self._library:
+            try:
+                data = self.query(Library.key)
+                self._library = Library(self, data)
+            except BadRequest:
+                data = self.query('/library/sections/')
+                # Only the owner has access to /library
+                # so just return the library without the data.
+                return Library(self, data)
+        return self._library
+
+    @property
+    def settings(self):
+        """ Returns a list of all server settings. """
+        if not self._settings:
+            data = self.query(Settings.key)
+            self._settings = Settings(self, data)
+        return self._settings
+
+    def account(self):
+        """ Returns the :class:`~plexapi.server.Account` object this server belongs to. """
+        data = self.query(Account.key)
+        return Account(self, data)
+
+    def myPlexAccount(self):
+        """ Returns a :class:`~plexapi.myplex.MyPlexAccount` object using the same
+            token to access this server. If you are not the owner of this PlexServer
+            you're likley to recieve an authentication error calling this.
+        """
+        if self._myPlexAccount is None:
+            from plexapi.myplex import MyPlexAccount
+            self._myPlexAccount = MyPlexAccount(token=self._token)
+        return self._myPlexAccount
+
+    def _myPlexClientPorts(self):
+        """ Sometimes the PlexServer does not properly advertise port numbers required
+            to connect. This attemps to look up device port number from plex.tv.
+            See issue #126: Make PlexServer.clients() more user friendly.
+              https://github.com/pkkid/python-plexapi/issues/126
+        """
+        try:
+            ports = {}
+            account = self.myPlexAccount()
+            for device in account.devices():
+                if device.connections and ':' in device.connections[0][6:]:
+                    ports[device.clientIdentifier] = device.connections[0].split(':')[-1]
+            return ports
+        except Exception as err:
+            log.warning('Unable to fetch client ports from myPlex: %s', err)
+            return ports
+
+    def clients(self):
+        """ Returns list of all :class:`~plexapi.client.PlexClient` objects connected to server. """
+        items = []
+        ports = None
+        for elem in self.query('/clients'):
+            port = elem.attrib.get('port')
+            if not port:
+                log.warning('%s did not advertise a port, checking plex.tv.', elem.attrib.get('name'))
+                ports = self._myPlexClientPorts() if ports is None else ports
+                port = ports.get(elem.attrib.get('machineIdentifier'))
+            baseurl = 'http://%s:%s' % (elem.attrib['host'], port)
+            items.append(PlexClient(baseurl=baseurl, server=self,
+                                    token=self._token, data=elem, connect=False))
+
+        return items
+
+    def client(self, name):
+        """ Returns the :class:`~plexapi.client.PlexClient` that matches the specified name.
+
+            Parameters:
+                name (str): Name of the client to return.
+
+            Raises:
+                :class:`~plexapi.exceptions.NotFound`: Unknown client name
+        """
+        for client in self.clients():
+            if client and client.title == name:
+                return client
+
+        raise NotFound('Unknown client name: %s' % name)
+
+    def createPlaylist(self, title, items):
+        """ Creates and returns a new :class:`~plexapi.playlist.Playlist`.
+
+            Parameters:
+                title (str): Title of the playlist to be created.
+                items (list<Media>): List of media items to include in the playlist.
+        """
+        return Playlist.create(self, title, items)
+
+    def createPlayQueue(self, item, **kwargs):
+        """ Creates and returns a new :class:`~plexapi.playqueue.PlayQueue`.
+
+            Parameters:
+                item (Media or Playlist): Media or playlist to add to PlayQueue.
+                kwargs (dict): See `~plexapi.playerque.PlayQueue.create`.
+        """
+        return PlayQueue.create(self, item, **kwargs)
+
+    def downloadDatabases(self, savepath=None, unpack=False):
+        """ Download databases.
+
+            Parameters:
+                savepath (str): Defaults to current working dir.
+                unpack (bool): Unpack the zip file.
+        """
+        url = self.url('/diagnostics/databases')
+        filepath = utils.download(url, self._token, None, savepath, self._session, unpack=unpack)
+        return filepath
+
+    def downloadLogs(self, savepath=None, unpack=False):
+        """ Download server logs.
+
+            Parameters:
+                savepath (str): Defaults to current working dir.
+                unpack (bool): Unpack the zip file.
+        """
+        url = self.url('/diagnostics/logs')
+        filepath = utils.download(url, self._token, None, savepath, self._session, unpack=unpack)
+        return filepath
+
+    def check_for_update(self, force=True, download=False):
+        """ Returns a :class:`~plexapi.base.Release` object containing release info.
+
+           Parameters:
+                force (bool): Force server to check for new releases
+                download (bool): Download if a update is available.
+        """
+        part = '/updater/check?download=%s' % (1 if download else 0)
+        if force:
+            self.query(part, method=self._session.put)
+        return self.fetchItem('/updater/status')
+
+    def isLatest(self):
+        """ Check if the installed version of PMS is the latest. """
+        release = self.check_for_update(force=True)
+        return bool(release.version == self.version)
+
+    def installUpdate(self):
+        """ Install the newest version of Plex Media Server. """
+        # We can add this but dunno how useful this is since it sometimes
+        # requires user action using a gui.
+        part = '/updater/apply'
+        release = self.check_for_update(force=True, download=True)
+        if release and release.version != self.version:
+            # figure out what method this is..
+            return self.query(part, method=self._session.put)
+
+    def history(self):
+        """ Returns a list of media items from watched history. """
+        return self.fetchItems('/status/sessions/history/all')
+
+    def playlists(self):
+        """ Returns a list of all :class:`~plexapi.playlist.Playlist` objects saved on the server. """
+        # TODO: Add sort and type options?
+        # /playlists/all?type=15&sort=titleSort%3Aasc&playlistType=video&smart=0
+        return self.fetchItems('/playlists')
+
+    def playlist(self, title):
+        """ Returns the :class:`~plexapi.client.Playlist` that matches the specified title.
+
+            Parameters:
+                title (str): Title of the playlist to return.
+
+            Raises:
+                :class:`~plexapi.exceptions.NotFound`: Invalid playlist title
+        """
+        return self.fetchItem('/playlists', title=title)
+
+    def query(self, key, method=None, headers=None, timeout=None, **kwargs):
+        """ Main method used to handle HTTPS requests to the Plex server. This method helps
+            by encoding the response to utf-8 and parsing the returned XML into and
+            ElementTree object. Returns None if no data exists in the response.
+        """
+        url = self.url(key)
+        method = method or self._session.get
+        timeout = timeout or TIMEOUT
+        log.debug('%s %s', method.__name__.upper(), url)
+        headers = self._headers(**headers or {})
+        response = method(url, headers=headers, timeout=timeout, **kwargs)
+        if response.status_code not in (200, 201):
+            codename = codes.get(response.status_code)[0]
+            errtext = response.text.replace('\n', ' ')
+            log.warning('BadRequest (%s) %s %s; %s' % (response.status_code, codename, response.url, errtext))
+            raise BadRequest('(%s) %s; %s %s' % (response.status_code, codename, response.url, errtext))
+        data = response.text.encode('utf8')
+        return ElementTree.fromstring(data) if data.strip() else None
+
+    def search(self, query, mediatype=None, limit=None):
+        """ Returns a list of media items or filter categories from the resulting
+            `Hub Search <https://www.plex.tv/blog/seek-plex-shall-find-leveling-web-app/>`_
+            against all items in your Plex library. This searches genres, actors, directors,
+            playlists, as well as all the obvious media titles. It performs spell-checking
+            against your search terms (because KUROSAWA is hard to spell). It also provides
+            contextual search results. So for example, if you search for 'Pernice', it’ll
+            return 'Pernice Brothers' as the artist result, but we’ll also go ahead and
+            return your most-listened to albums and tracks from the artist. If you type
+            'Arnold' you’ll get a result for the actor, but also the most recently added
+            movies he’s in.
+
+            Parameters:
+                query (str): Query to use when searching your library.
+                mediatype (str): Optionally limit your search to the specified media type.
+                limit (int): Optionally limit to the specified number of results per Hub.
+        """
+        results = []
+        params = {'query': query}
+        if mediatype:
+            params['section'] = utils.SEARCHTYPES[mediatype]
+        if limit:
+            params['limit'] = limit
+        key = '/hubs/search?%s' % urlencode(params)
+        for hub in self.fetchItems(key, Hub):
+            results += hub.items
+        return results
+
+    def sessions(self):
+        """ Returns a list of all active session (currently playing) media objects. """
+        return self.fetchItems('/status/sessions')
+
+    def startAlertListener(self, callback=None):
+        """ 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.
+
+            NOTE: You need websocket-client installed in order to use this feature.
+            >> pip install websocket-client
+
+            Parameters:
+                callback (func): Callback function to call on recieved messages.
+
+            raises:
+                :class:`~plexapi.exception.Unsupported`: Websocket-client not installed.
+        """
+        notifier = AlertListener(self, callback)
+        notifier.start()
+        return notifier
+
+    def transcodeImage(self, media, height, width, opacity=100, saturation=100):
+        """ Returns the URL for a transcoded image from the specified media object.
+            Returns None if no media specified (needed if user tries to pass thumb
+            or art directly).
+
+            Parameters:
+                height (int): Height to transcode the image to.
+                width (int): Width to transcode the image to.
+                opacity (int): Opacity of the resulting image (possibly deprecated).
+                saturation (int): Saturating of the resulting image.
+        """
+        if media:
+            transcode_url = '/photo/:/transcode?height=%s&width=%s&opacity=%s&saturation=%s&url=%s' % (
+                height, width, opacity, saturation, media)
+            return self.url(transcode_url, includeToken=True)
+
+    def url(self, key, includeToken=None):
+        """ Build a URL string with proper token argument.  Token will be appended to the URL
+            if either includeToken is True or CONFIG.log.show_secrets is 'true'.
+        """
+        if self._token and (includeToken or self._showSecrets):
+            delim = '&' if '?' in key else '?'
+            return '%s%s%sX-Plex-Token=%s' % (self._baseurl, key, delim, self._token)
+        return '%s%s' % (self._baseurl, key)
+
+
+class Account(PlexObject):
+    """ Contains the locally cached MyPlex account information. The properties provided don't
+        match the :class:`~plexapi.myplex.MyPlexAccount` object very well. I believe this exists
+        because access to myplex is not required to get basic plex information. I can't imagine
+        object is terribly useful except unless you were needed this information while offline.
+
+        Parameters:
+            server (:class:`~plexapi.server.PlexServer`): PlexServer this account is connected to (optional)
+            data (ElementTree): Response from PlexServer used to build this object (optional).
+
+        Attributes:
+            authToken (str): Plex authentication token to access the server.
+            mappingError (str): Unknown
+            mappingErrorMessage (str): Unknown
+            mappingState (str): Unknown
+            privateAddress (str): Local IP address of the Plex server.
+            privatePort (str): Local port of the Plex server.
+            publicAddress (str): Public IP address of the Plex server.
+            publicPort (str): Public port of the Plex server.
+            signInState (str): Signin state for this account (ex: ok).
+            subscriptionActive (str): True if the account subscription is active.
+            subscriptionFeatures (str): List of features allowed by the server for this account.
+                This may be based on your PlexPass subscription. Features include: camera_upload,
+                cloudsync, content_filter, dvr, hardware_transcoding, home, lyrics, music_videos,
+                pass, photo_autotags, premium_music_metadata, session_bandwidth_restrictions,
+                sync, trailers, webhooks' (and maybe more).
+            subscriptionState (str): 'Active' if this subscription is active.
+            username (str): Plex account username (user@example.com).
+    """
+    key = '/myplex/account'
+
+    def _loadData(self, data):
+        self._data = data
+        self.authToken = data.attrib.get('authToken')
+        self.username = data.attrib.get('username')
+        self.mappingState = data.attrib.get('mappingState')
+        self.mappingError = data.attrib.get('mappingError')
+        self.mappingErrorMessage = data.attrib.get('mappingErrorMessage')
+        self.signInState = data.attrib.get('signInState')
+        self.publicAddress = data.attrib.get('publicAddress')
+        self.publicPort = data.attrib.get('publicPort')
+        self.privateAddress = data.attrib.get('privateAddress')
+        self.privatePort = data.attrib.get('privatePort')
+        self.subscriptionFeatures = utils.toList(data.attrib.get('subscriptionFeatures'))
+        self.subscriptionActive = cast(bool, data.attrib.get('subscriptionActive'))
+        self.subscriptionState = data.attrib.get('subscriptionState')

lib/plexapi/settings.py

@@ -0,0 +1,156 @@
+# -*- coding: utf-8 -*-
+from collections import defaultdict
+
+from plexapi import log, utils
+from plexapi.base import PlexObject
+from plexapi.compat import quote, string_type
+from plexapi.exceptions import BadRequest, NotFound
+
+
+class Settings(PlexObject):
+    """ Container class for all settings. Allows getting and setting PlexServer settings.
+
+        Attributes:
+            key (str): '/:/prefs'
+    """
+    key = '/:/prefs'
+
+    def __init__(self, server, data, initpath=None):
+        self._settings = {}
+        super(Settings, self).__init__(server, data, initpath)
+
+    def __getattr__(self, attr):
+        if attr.startswith('_'):
+            return self.__dict__[attr]
+        return self.get(attr).value
+
+    def __setattr__(self, attr, value):
+        if not attr.startswith('_'):
+            return self.get(attr).set(value)
+        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'])
+            if id in self._settings:
+                self._settings[id]._loadData(elem)
+                continue
+            self._settings[id] = Setting(self._server, elem, self._initpath)
+
+    def all(self):
+        """ 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 :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 :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:
+                log.info('Saving PlexServer setting %s = %s' % (setting.id, setting._setValue))
+                params[setting.id] = quote(setting._setValue)
+        if not params:
+            raise BadRequest('No setting have been modified.')
+        querystr = '&'.join(['%s=%s' % (k, v) for k, v in params.items()])
+        url = '%s?%s' % (self.key, querystr)
+        self._server.query(url, self._server._session.put)
+        self.reload()
+
+
+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 = {
+        'bool': {'type': bool, 'cast': _bool_cast, 'tostr': _bool_str},
+        'double': {'type': float, 'cast': float, 'tostr': string_type},
+        'int': {'type': int, 'cast': int, 'tostr': string_type},
+        'text': {'type': string_type, 'cast': string_type, 'tostr': string_type},
+    }
+
+    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.summary = data.attrib.get('summary')
+        self.type = data.attrib.get('type')
+        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:
+            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__
+            raise BadRequest('Invalid value for %s: a %s is required, not %s' % (self.id, self.type, badtype))
+        if self.enumValues and value not in self.enumValues:
+            raise BadRequest('Invalid value for %s: %s not in %s' % (self.id, value, list(self.enumValues)))
+        # store value off to the side until we call settings.save()
+        tostr = self.TYPES[self.type]['tostr']
+        self._setValue = tostr(value)
+
+    def toUrl(self):
+        """Helper for urls"""
+        return '%s=%s' % (self.id, self._value or self.value)

lib/plexapi/sync.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+import requests
+from plexapi import utils
+from plexapi.exceptions import NotFound
+
+
+class SyncItem(object):
+    """ Sync Item. This doesn't current work. """
+    def __init__(self, device, data, servers=None):
+        self._device = device
+        self._servers = servers
+        self._loadData(data)
+
+    def _loadData(self, data):
+        self._data = data
+        self.id = utils.cast(int, data.attrib.get('id'))
+        self.version = utils.cast(int, data.attrib.get('version'))
+        self.rootTitle = data.attrib.get('rootTitle')
+        self.title = data.attrib.get('title')
+        self.metadataType = data.attrib.get('metadataType')
+        self.machineIdentifier = data.find('Server').get('machineIdentifier')
+        self.status = data.find('Status').attrib.copy()
+        self.MediaSettings = data.find('MediaSettings').attrib.copy()
+        self.policy = data.find('Policy').attrib.copy()
+        self.location = data.find('Location').attrib.copy()
+
+    def server(self):
+        server = list(filter(lambda x: x.machineIdentifier == self.machineIdentifier, self._servers))
+        if 0 == len(server):
+            raise NotFound('Unable to find server with uuid %s' % self.machineIdentifier)
+        return server[0]
+
+    def getMedia(self):
+        server = self.server().connect()
+        key = '/sync/items/%s' % self.id
+        return server.fetchItems(key)
+
+    def markAsDone(self, sync_id):
+        server = self.server().connect()
+        url = '/sync/%s/%s/files/%s/downloaded' % (
+            self._device.clientIdentifier, server.machineIdentifier, sync_id)
+        server.query(url, method=requests.put)

lib/plexapi/utils.py

@@ -0,0 +1,363 @@
+# -*- coding: utf-8 -*-
+import logging
+import os
+import re
+import requests
+import time
+import zipfile
+from datetime import datetime
+from getpass import getpass
+from threading import Thread
+from tqdm import tqdm
+from plexapi import compat
+from plexapi.exceptions import NotFound
+
+# Search Types - Plex uses these to filter specific media types when searching.
+# Library Types - Populated at runtime
+SEARCHTYPES = {'movie': 1, 'show': 2, 'season': 3, 'episode': 4,
+               'artist': 8, 'album': 9, 'track': 10, 'photo': 14}
+PLEXOBJECTS = {}
+
+
+class SecretsFilter(logging.Filter):
+    """ Logging filter to hide secrets. """
+
+    def __init__(self, secrets=None):
+        self.secrets = secrets or set()
+
+    def add_secret(self, secret):
+        if secret is not None:
+            self.secrets.add(secret)
+        return secret
+
+    def filter(self, record):
+        cleanargs = list(record.args)
+        for i in range(len(cleanargs)):
+            if isinstance(cleanargs[i], compat.string_type):
+                for secret in self.secrets:
+                    cleanargs[i] = cleanargs[i].replace(secret, '<hidden>')
+        record.args = tuple(cleanargs)
+        return True
+
+
+def registerPlexObject(cls):
+    """ Registry of library types we may come across when parsing XML. This allows us to
+        define a few helper functions to dynamically convery the XML into objects. See
+        buildItem() below for an example.
+    """
+    etype = getattr(cls, 'STREAMTYPE', cls.TYPE)
+    ehash = '%s.%s' % (cls.TAG, etype) if etype else cls.TAG
+    if ehash in PLEXOBJECTS:
+        raise Exception('Ambiguous PlexObject definition %s(tag=%s, type=%s) with %s' %
+            (cls.__name__, cls.TAG, etype, PLEXOBJECTS[ehash].__name__))
+    PLEXOBJECTS[ehash] = cls
+    return cls
+
+
+def cast(func, value):
+    """ Cast the specified value to the specified type (returned by func). Currently this
+        only support int, float, bool. Should be extended if needed.
+
+        Parameters:
+            func (func): Calback function to used cast to type (int, bool, float).
+            value (any): value to be cast and returned.
+    """
+    if value is not None:
+        if func == bool:
+            return bool(int(value))
+        elif func in (int, float):
+            try:
+                return func(value)
+            except ValueError:
+                return float('nan')
+        return func(value)
+    return value
+
+
+def joinArgs(args):
+    """ Returns a query string (uses for HTTP URLs) where only the value is URL encoded.
+        Example return value: '?genre=action&type=1337'.
+
+        Parameters:
+            args (dict): Arguments to include in query string.
+    """
+    if not args:
+        return ''
+    arglist = []
+    for key in sorted(args, key=lambda x: x.lower()):
+        value = compat.ustr(args[key])
+        arglist.append('%s=%s' % (key, compat.quote(value)))
+    return '?%s' % '&'.join(arglist)
+
+
+def lowerFirst(s):
+    return s[0].lower() + s[1:]
+
+
+def rget(obj, attrstr, default=None, delim='.'):  # pragma: no cover
+    """ Returns the value at the specified attrstr location within a nexted tree of
+        dicts, lists, tuples, functions, classes, etc. The lookup is done recursivley
+        for each key in attrstr (split by by the delimiter) This function is heavily
+        influenced by the lookups used in Django templates.
+
+        Parameters:
+            obj (any): Object to start the lookup in (dict, obj, list, tuple, etc).
+            attrstr (str): String to lookup (ex: 'foo.bar.baz.value')
+            default (any): Default value to return if not found.
+            delim (str): Delimiter separating keys in attrstr.
+    """
+    try:
+        parts = attrstr.split(delim, 1)
+        attr = parts[0]
+        attrstr = parts[1] if len(parts) == 2 else None
+        if isinstance(obj, dict):
+            value = obj[attr]
+        elif isinstance(obj, list):
+            value = obj[int(attr)]
+        elif isinstance(obj, tuple):
+            value = obj[int(attr)]
+        elif isinstance(obj, object):
+            value = getattr(obj, attr)
+        if attrstr:
+            return rget(value, attrstr, default, delim)
+        return value
+    except:  # noqa: E722
+        return default
+
+
+def searchType(libtype):
+    """ Returns the integer value of the library string type.
+
+        Parameters:
+            libtype (str): LibType to lookup (movie, show, season, episode, artist, album, track)
+
+        Raises:
+            NotFound: Unknown libtype
+    """
+    libtype = compat.ustr(libtype)
+    if libtype in [compat.ustr(v) for v in SEARCHTYPES.values()]:
+        return libtype
+    if SEARCHTYPES.get(libtype) is not None:
+        return SEARCHTYPES[libtype]
+    raise NotFound('Unknown libtype: %s' % libtype)
+
+
+def threaded(callback, listargs):
+    """ Returns the result of <callback> for each set of \*args in listargs. Each call
+        to <callback. is called concurrently in their own separate threads.
+
+        Parameters:
+            callback (func): Callback function to apply to each set of \*args.
+            listargs (list): List of lists; \*args to pass each thread.
+    """
+    threads, results = [], []
+    for args in listargs:
+        args += [results, len(results)]
+        results.append(None)
+        threads.append(Thread(target=callback, args=args))
+        threads[-1].setDaemon(True)
+        threads[-1].start()
+    for thread in threads:
+        thread.join()
+    return results
+
+
+def toDatetime(value, format=None):
+    """ Returns a datetime object from the specified value.
+
+        Parameters:
+            value (str): value to return as a datetime
+            format (str): Format to pass strftime (optional; if value is a str).
+    """
+    if value and value is not None:
+        if format:
+            value = datetime.strptime(value, format)
+        else:
+            value = datetime.fromtimestamp(int(value))
+    return value
+
+
+def toList(value, itemcast=None, delim=','):
+    """ Returns a list of strings from the specified value.
+
+        Parameters:
+            value (str): comma delimited string to convert to list.
+            itemcast (func): Function to cast each list item to (default str).
+            delim (str): string delimiter (optional; default ',').
+    """
+    value = value or ''
+    itemcast = itemcast or str
+    return [itemcast(item) for item in value.split(delim) if item != '']
+
+
+def downloadSessionImages(server, filename=None, height=150, width=150,
+                          opacity=100, saturation=100):  # pragma: no cover
+    """ Helper to download a bif image or thumb.url from plex.server.sessions.
+
+       Parameters:
+           filename (str): default to None,
+           height (int): Height of the image.
+           width (int): width of the image.
+           opacity (int): Opacity of the resulting image (possibly deprecated).
+           saturation (int): Saturating of the resulting image.
+
+       Returns:
+            {'hellowlol': {'filepath': '<filepath>', 'url': 'http://<url>'},
+            {'<username>': {filepath, url}}, ...
+    """
+    info = {}
+    for media in server.sessions():
+        url = None
+        for part in media.iterParts():
+            if media.thumb:
+                url = media.thumb
+            if part.indexes:  # always use bif images if available.
+                url = '/library/parts/%s/indexes/%s/%s' % (part.id, part.indexes.lower(), media.viewOffset)
+        if url:
+            if filename is None:
+                prettyname = media._prettyfilename()
+                filename = 'session_transcode_%s_%s_%s' % (media.usernames[0], prettyname, int(time.time()))
+            url = server.transcodeImage(url, height, width, opacity, saturation)
+            filepath = download(url, filename=filename)
+            info['username'] = {'filepath': filepath, 'url': url}
+    return info
+
+
+def download(url, token, filename=None, savepath=None, session=None, chunksize=4024,
+             unpack=False, mocked=False, showstatus=False):
+    """ Helper to download a thumb, videofile or other media item. Returns the local
+        path to the downloaded file.
+
+       Parameters:
+            url (str): URL where the content be reached.
+            token (str): Plex auth token to include in headers.
+            filename (str): Filename of the downloaded file, default None.
+            savepath (str): Defaults to current working dir.
+            chunksize (int): What chunksize read/write at the time.
+            mocked (bool): Helper to do evertything except write the file.
+            unpack (bool): Unpack the zip file.
+            showstatus(bool): Display a progressbar.
+
+        Example:
+            >>> download(a_episode.getStreamURL(), a_episode.location)
+            /path/to/file
+    """
+
+    from plexapi import log
+    # fetch the data to be saved
+    session = session or requests.Session()
+    headers = {'X-Plex-Token': token}
+    response = session.get(url, headers=headers, stream=True)
+    # make sure the savepath directory exists
+    savepath = savepath or os.getcwd()
+    compat.makedirs(savepath, exist_ok=True)
+
+    # try getting filename from header if not specified in arguments (used for logs, db)
+    if not filename and response.headers.get('Content-Disposition'):
+        filename = re.findall(r'filename=\"(.+)\"', response.headers.get('Content-Disposition'))
+        filename = filename[0] if filename[0] else None
+
+    filename = os.path.basename(filename)
+    fullpath = os.path.join(savepath, filename)
+    # append file.ext from content-type if not already there
+    extension = os.path.splitext(fullpath)[-1]
+    if not extension:
+        contenttype = response.headers.get('content-type')
+        if contenttype and 'image' in contenttype:
+            fullpath += contenttype.split('/')[1]
+
+    # check this is a mocked download (testing)
+    if mocked:
+        log.debug('Mocked download %s', fullpath)
+        return fullpath
+
+    # save the file to disk
+    log.info('Downloading: %s', fullpath)
+    if showstatus:  # pragma: no cover
+        total = int(response.headers.get('content-length', 0))
+        bar = tqdm(unit='B', unit_scale=True, total=total, desc=filename)
+
+    with open(fullpath, 'wb') as handle:
+        for chunk in response.iter_content(chunk_size=chunksize):
+            handle.write(chunk)
+            if showstatus:
+                bar.update(len(chunk))
+
+    if showstatus:  # pragma: no cover
+        bar.close()
+    # check we want to unzip the contents
+    if fullpath.endswith('zip') and unpack:
+        with zipfile.ZipFile(fullpath, 'r') as handle:
+            handle.extractall(savepath)
+
+    return fullpath
+
+
+def tag_helper(tag, items, locked=True, remove=False):
+    """ Simple tag helper for editing a object. """
+    if not isinstance(items, list):
+        items = [items]
+    data = {}
+    if not remove:
+        for i, item in enumerate(items):
+            tagname = '%s[%s].tag.tag' % (tag, i)
+            data[tagname] = item
+    if remove:
+        tagname = '%s[].tag.tag-' % tag
+        data[tagname] = ','.join(items)
+    data['%s.locked' % tag] = 1 if locked else 0
+    return data
+
+
+def getMyPlexAccount(opts=None):  # pragma: no cover
+    """ Helper function tries to get a MyPlex Account instance by checking
+        the the following locations for a username and password. This is
+        useful to create user-friendly command line tools.
+        1. command-line options (opts).
+        2. environment variables and config.ini
+        3. Prompt on the command line.
+    """
+    from plexapi import CONFIG
+    from plexapi.myplex import MyPlexAccount
+    # 1. Check command-line options
+    if opts and opts.username and opts.password:
+        print('Authenticating with Plex.tv as %s..' % opts.username)
+        return MyPlexAccount(opts.username, opts.password)
+    # 2. Check Plexconfig (environment variables and config.ini)
+    config_username = CONFIG.get('auth.myplex_username')
+    config_password = CONFIG.get('auth.myplex_password')
+    if config_username and config_password:
+        print('Authenticating with Plex.tv as %s..' % config_username)
+        return MyPlexAccount(config_username, config_password)
+    # 3. Prompt for username and password on the command line
+    username = input('What is your plex.tv username: ')
+    password = getpass('What is your plex.tv password: ')
+    print('Authenticating with Plex.tv as %s..' % username)
+    return MyPlexAccount(username, password)
+
+
+def choose(msg, items, attr):  # pragma: no cover
+    """ Command line helper to display a list of choices, asking the
+        user to choose one of the options.
+    """
+    # Return the first item if there is only one choice
+    if len(items) == 1:
+        return items[0]
+    # Print all choices to the command line
+    print()
+    for index, i in enumerate(items):
+        name = attr(i) if callable(attr) else getattr(i, attr)
+        print('  %s: %s' % (index, name))
+    print()
+    # Request choice from the user
+    while True:
+        try:
+            inp = input('%s: ' % msg)
+            if any(s in inp for s in (':', '::', '-')):
+                idx = slice(*map(lambda x: int(x.strip()) if x.strip() else None, inp.split(':')))
+                return items[idx]
+            else:
+                return items[int(inp)]
+
+        except (ValueError, IndexError):
+            pass