Add docs to fetch PlexServer() without needing to log into MyPlex; Add this as an option in the tests and examples as well

README.md

@@ -16,9 +16,9 @@ Python bindings for the Plex API.
 
 #### Getting a PlexServer Instance ####
 
-There are two types of authentication.  If running the PlexAPI on the same
+There are three types of authentication. If running the PlexAPI on the same
 network as the Plex Server (and you are not using Plex Users), you can
-authenticate without a username and password.  Getting a PlexServer
+authenticate without a username and password. Getting a PlexServer
 instance is as easy as the following:
 
 ```python
@@ -26,8 +26,19 @@ from plexapi.server import PlexServer
 plex = PlexServer()   # Defaults to localhost:32400
 ```
 
-If you are running on a separate network or using Plex Users you need to log
-into MyPlex to get a PlexServer instance.  An example of this is below. NOTE:
+If you want to avoid logging into MyPlex and you already know your auth token
+string, you can use the PlexServer object directly as above, but passing in
+the baseuri and auth token directly.
+
+```python
+from plexapi.server import MyPlexUser
+baseuri = 'http://plexserver:32400'
+token = '2ffLuB84dqLswk9skLos'
+plex = PlexServer(baseuri, token)
+```
+
+If you are running on a separate network or using Plex Users you can log
+into MyPlex to get a PlexServer instance. An example of this is below. NOTE:
 Servername below is the name of the server (not the hostname and port).  If
 logged into Plex Web you can see the server name in the top left above your
 available libraries.
@@ -35,9 +46,10 @@ available libraries.
 ```python
 from plexapi.myplex import MyPlexUser
 user = MyPlexUser.signin('<USERNAME>', '<PASSWORD>')
-plex = user.getResource('<SERVERNAME>').connect()
+plex = user.getResource('<SERVERNAME>').connect()  # returns a PlexServer instance
 ```
 
+
 #### Usage Examples ####
 
 ```python

examples/examples.py

@@ -73,11 +73,17 @@ def example_008_get_stream_url(plex):
 
 
 if __name__ == '__main__':
+    # There are three ways to authenticate:
+    #  1. If the server is running on localhost, just run without any auth.
+    #  2. Pass in --username, --password, and --resource.
+    #  3. Pass in --baseuri, --token
     parser = argparse.ArgumentParser(description='Run PlexAPI examples.')
     parser.add_argument('-r', '--resource', help='Name of the Plex resource (requires user/pass).')
+    parser.add_argument('-n', '--name', help='Only run tests containing this string. Leave blank to run all tests.')
     parser.add_argument('-u', '--username', help='Username for the Plex server.')
     parser.add_argument('-p', '--password', help='Password for the Plex server.')
-    parser.add_argument('-n', '--name', help='Only run tests containing this string. Leave blank to run all examples.')
+    parser.add_argument('-b', '--baseuri', help='Baseuri needed for auth token authentication')
+    parser.add_argument('-t', '--token', help='Auth token (instead of user/pass)')
     args = parser.parse_args()
     plex, user = fetch_server(args)
     for example in iter_tests(__name__, args):

examples/tests.py

@@ -271,10 +271,16 @@ def test_018_fetch_details_not_in_search_result(plex, user=None):
 
 
 if __name__ == '__main__':
+    # There are three ways to authenticate:
+    #  1. If the server is running on localhost, just run without any auth.
+    #  2. Pass in --username, --password, and --resource.
+    #  3. Pass in --baseuri, --token
     parser = argparse.ArgumentParser(description='Run PlexAPI tests.')
     parser.add_argument('-r', '--resource', help='Name of the Plex resource (requires user/pass).')
+    parser.add_argument('-n', '--name', help='Only run tests containing this string. Leave blank to run all tests.')
     parser.add_argument('-u', '--username', help='Username for the Plex server.')
     parser.add_argument('-p', '--password', help='Password for the Plex server.')
-    parser.add_argument('-n', '--name', help='Only run tests containing this string. Leave blank to run all tests.')
+    parser.add_argument('-b', '--baseuri', help='Baseuri needed for auth token authentication')
+    parser.add_argument('-t', '--token', help='Auth token (instead of user/pass)')
     args = parser.parse_args()
     run_tests(__name__, args)

examples/utils.py

@@ -24,9 +24,11 @@ def log(indent, message, color=None):
 
 
 def fetch_server(args):
-    if args.resource:
+    if args.resource and args.username and args.password:
         user = MyPlexUser.signin(args.username, args.password)
         return user.getResource(args.resource).connect(), user
+    elif args.baseuri and args.token:
+        return server.PlexServer(args.baseuri, args.token), None
     return server.PlexServer(), None