Add utils.deprecated decorator function

plexapi/library.py

@@ -1,5 +1,4 @@
 # -*- coding: utf-8 -*-
-import warnings
 from urllib.parse import quote, quote_plus, unquote, urlencode
 
 from plexapi import X_PLEX_CONTAINER_SIZE, log, utils
@@ -7,8 +6,7 @@ from plexapi.base import PlexObject, PlexPartialObject
 from plexapi.exceptions import BadRequest, NotFound
 from plexapi.media import MediaTag
 from plexapi.settings import Setting
-
-warnings.simplefilter('default', category=DeprecationWarning)
+from plexapi.utils import deprecated
 
 
 class Library(PlexObject):
@@ -845,10 +843,8 @@ class LibrarySection(PlexObject):
         """
         return self._server.history(maxresults=maxresults, mindate=mindate, librarySectionID=self.key, accountID=1)
 
+    @deprecated('use "collections" (plural) instead')
     def collection(self, **kwargs):
-        msg = 'LibrarySection.collection() will be deprecated in the future, use collections() (plural) instead.'
-        warnings.warn(msg, DeprecationWarning)
-        log.warning(msg)
         return self.collections()
 
     def collections(self, **kwargs):
@@ -1479,6 +1475,7 @@ class Collections(PlexPartialObject):
         self.updatedAt = utils.toDatetime(data.attrib.get('updatedAt'))
 
     @property
+    @deprecated('use "items" instead')
     def children(self):
         return self.fetchItems(self.key)
         

plexapi/utils.py

@@ -1,9 +1,11 @@
 # -*- coding: utf-8 -*-
 import base64
+import functools
 import logging
 import os
 import re
 import time
+import warnings
 import zipfile
 from datetime import datetime
 from getpass import getpass
@@ -19,6 +21,7 @@ except ImportError:
     tqdm = None
 
 log = logging.getLogger('plexapi')
+warnings.simplefilter('default', category=DeprecationWarning)
 
 # Search Types - Plex uses these to filter specific media types when searching.
 # Library Types - Populated at runtime
@@ -445,3 +448,18 @@ def getAgentIdentifier(section, agent):
 
 def base64str(text):
     return base64.b64encode(text.encode('utf-8')).decode('utf-8')
+
+
+def deprecated(message):
+    def decorator(func):
+        """This is a decorator which can be used to mark functions
+        as deprecated. It will result in a warning being emitted
+        when the function is used."""
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            msg = 'Call to deprecated function or method "%s", %s.' % (func.__name__, message)
+            warnings.warn(msg, category=DeprecationWarning, stacklevel=3)
+            log.warning(msg)
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator