update examples for api5 release

ampache · Aug 23, 2021 · 12bd2a1 · 12bd2a1
1 parent babf06a
commit 12bd2a1
Show file tree

Hide file tree

Showing 10 changed files with 152 additions and 137 deletions.
diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,4 @@ test*.py
 .idea/
 get_art.jpg
 *ampyche.conf
+docs/examples/ampache.py
diff --git a/README.rst b/README.rst
@@ -8,12 +8,46 @@ Upload to PyPI
 INFO
 ====
 
-A python3 library for interaction with your Ampache server using the XML & JSON API
+A python3 library for interaction with your Ampache 5.x.x server using the XML & JSON API
 
-`<http://ampache.org/API/>`_
+`<https://ampache.org/API/>`_
 
 Code examples and scripts are available from github
 
+There has been a pretty significant change in the library between Ampache 4 and Ampache 5.
+
+Once you connect with your passphrase or api key, the url and auth token are stored allowing you to call methods without them.
+
+.. code-block:: python3
+
+    import ampache
+    import time
+
+    # connect to the server
+    ampacheConnection = ampache.API()
+
+    # if using password auth use encrypt_password
+    mytime = int(time.time())
+    passphrase = ampacheConnection.encrypt_password('mypassword', mytime)
+    auth = ampacheConnection.handshake('https://music.com.au', passphrase, 'my username', mytime)
+
+    # if using an API key auth keep using encrypt_string
+    passphrase = ampacheConnection.encrypt_string('my apikey', 'my username')
+    auth = ampacheConnection.handshake('https://music.com.au', passphrase)
+
+    # now you can call methods without having to keep putting in the url and userkey
+    ampacheConnection.label(1677)
+    
+    # ping has always allowed empty calls so you have to ping with a url and session still
+    ampacheConnection.ping('https://music.com.au', auth)
+
+NEWS
+====
+
+* Password handshake auth is available now.
+* This library only supports Ampache 5+ with a lot of significant change on the Ampache and library side
+
+
 INSTALL
 =======
 

diff --git a/docs/examples/advanced_search.py b/docs/examples/advanced_search.py
@@ -4,55 +4,45 @@
 import sys
 
 # user variables
-ampache_url = 'https://music.server'
-ampache_api = 'mysuperapikey'
-ampache_user = 'myusername'
+ampache_url = 'https://develop.ampache.dev'
+ampache_api = 'demodemo'
+ampache_user = 'demo'
 
 """
 encrypt_string
 """
-encrypted_key = ampache.encrypt_string(ampache_api, ampache_user)
+ampacheConnection = ampache.API()
+encrypted_key = ampacheConnection.encrypt_string(ampache_api, ampache_user)
 
 """
 handshake
 """
 print('Connecting to:\n    ', ampache_url)
 src_api = ampache_api
-ampache_api = ampache.handshake(ampache_url, encrypted_key, False, False, '420000', 'xml')
+ampache_api = ampacheConnection.handshake(ampache_url, encrypted_key, False, False, '420000')
 
 print('\nThe ampache handshake for:\n    ', src_api, '\n\nReturned the following session key:\n    ', ampache_api)
 if not ampache_api:
     print()
     sys.exit('ERROR: Failed to connect to ' + ampache_url)
 
-print('\nPing returned:\n    ', ampache.ping(ampache_url, ampache_api, 'json'))
+print('\nPing returned:\n    ', ampacheConnection.ping(ampache_url, ampache_api))
 print()
 
 """
 advanced_search
 """
-print('\nadvanced_search\nmetadata, BPM, is greater than, 200\n')
-search_rules = [['metadata', 8, 200, 9]]
-search_song = ampache.advanced_search(ampache_url, ampache_api, search_rules, 'and', 'song', 0, 0, 'xml')
-if search_song:
-    for child in search_song:
-        if child.tag == 'total_count':
-            continue
-        print(child.tag, child.attrib)
-        print(child.find('filename').text)
-
-print("\nadvanced_search\nsearch song year = 1999 and CONTAINS artist 'Prodigy'\n")
-search_rules = [['year', 2, 1999], ['artist', 0, 'Prodigy']]
-search_song = ampache.advanced_search(ampache_url, ampache_api, search_rules, 'and', 'song', 0, 0, 'xml')
-if search_song:
-    for child in search_song:
-        if child.tag == 'total_count':
-            continue
-        print(child.tag, child.attrib)
-        print(child.find('filename').text)
+print("\nadvanced_search\nsearch song year = 2009 or CONTAINS artist 'Pro'\n")
+search_rules = [['year', 2, 2009], ['artist', 0, 'Pro']]
+search_song = ampacheConnection.advanced_search(search_rules, 'or', 'song', 0, 0)
+for child in search_song:
+    if child.tag == 'total_count':
+        continue
+    print(child.tag, child.attrib)
+    print(child.find('filename').text)
 
 """
 Close your session when you're done
 """
 print('\nWhen you are finished it\'s a good idea to kill your session')
-print('    ', ampache.goodbye(ampache_url, ampache_api, 'xml'))
+ampacheConnection.goodbye()
diff --git a/docs/examples/cache_playlist.py b/docs/examples/cache_playlist.py
@@ -5,78 +5,80 @@
 import ampache
 
 # user variables
-url = 'https://music.server'
-api = 'mysuperapikey'
-user = 'myusername'
-smart_list = 142
+url = 'https://develop.ampache.dev'
+api = 'demodemo'
+user = 'demo'
+smart_list = 21
 my_limit = 4
-my_transcode = 'ogg'
+my_transcode = 'raw'
 my_destin = '/tmp'
 
 
 def cache_playlist(ampache_url, ampache_api, ampache_user, api_format, smartlist, destination, transcode, limit):
+    ampacheConnection = ampache.API()
+    ampacheConnection.set_format(api_format)
     """ encrypt_string
     def encrypt_string(ampache_api, user):
     """
-    encrypted_key = ampache.encrypt_string(ampache_api, ampache_user)
+    encrypted_key = ampacheConnection.encrypt_string(ampache_api, ampache_user)
 
     """ handshake
-    def handshake(ampache_url, ampache_api, user = False, timestamp = False, version = '420000', api_format = 'xml'):
+    def handshake(ampache_url, ampache_api, user = False, timestamp = False, version = '420000'):
     # processed details
     """
-    ampache_session = ampache.handshake(ampache_url, encrypted_key, False, False, '420000', api_format)
+    ampache_session = ampacheConnection.handshake(ampache_url, encrypted_key, False, False, '420000')
     if not ampache_session:
         print()
         sys.exit('ERROR: Failed to connect to ' + ampache_url)
 
     """ ping
-    def ping(ampache_url, ampache_api, api_format = 'xml'):
+    def ping(ampache_url, ampache_api):
     # did all this work?
     """
-    my_ping = ampache.ping(ampache_url, ampache_session, api_format)
+    my_ping = ampacheConnection.ping(ampache_url, ampache_session)
     if not my_ping:
         print()
         sys.exit('ERROR: Failed to ping ' + ampache_url)
 
     """ set_debug
     def set_debug(mybool):
     """
-    ampache.set_debug(False)
+    ampacheConnection.set_debug(False)
 
     """ advanced_search
     def advanced_search(ampache_url, ampache_api, rules, operator = 'and',
-                        type = 'song', offset = 0, limit = 0, random = 0, api_format = 'xml'):
+                        type = 'song', offset = 0, limit = 0, random = 0):
     """
     list_songs = list()
     search_rules = [['smartplaylist', 0, smartlist]]
-    search_song = ampache.advanced_search(ampache_url, ampache_session,
-                                          search_rules, 'or', 'song', 0, limit, 1, api_format)
+    search_song = ampacheConnection.advanced_search(search_rules, 'or', 'song', 0, limit, 1)
 
-    for child in search_song:
-        if api_format == 'xml':
+    if api_format == 'xml':
+        for child in search_song:
             if child.tag == 'song':
-                list_songs.append([child.attrib['id'],
-                                   os.path.basename(os.path.splitext(child.find('filename').text)[0] + '.' + transcode)])
-        else:
-            list_songs.append([child['id'], os.path.basename(os.path.splitext(child['filename'])[0] + '.' + transcode)])
+                list_songs.append([child.attrib['id'], os.path.basename(child.find('filename').text)])
+    else:
+         for child in search_song['song']:
+            print('list')
+            print(child)
+            list_songs.append([child['id'], os.path.basename(child['filename'])])
 
     print(list_songs)
 
     """ download
-    def download(ampache_url, ampache_api, object_id, object_type, destination, file_format='raw', api_format='xml'):
+    def download(ampache_url, ampache_api, object_id, object_type, destination, file_format='raw'):
     """
     for object_id in list_songs:
         if not os.path.isfile(os.path.join(destination, object_id[1])):
-            ampache.download(ampache_url, ampache_session, object_id[0],
-                             'song', os.path.join(destination, object_id[1]), transcode, api_format)
+            ampacheConnection.download(object_id[0], 'song', os.path.join(destination, object_id[1]), transcode)
         else:
             print('File exists')
 
     """ goodbye
-    def goodbye(ampache_url, ampache_api, api_format = 'xml'):
+    def goodbye(ampache_url, ampache_api):
     Close your session when you're done
     """
-    ampache.goodbye(ampache_url, ampache_session, api_format)
+    ampacheConnection.goodbye()
 
 
 cache_playlist(url, api, user, 'xml', smart_list, my_destin, my_transcode, my_limit)

diff --git a/docs/examples/login.py b/docs/examples/login.py
@@ -5,24 +5,27 @@
 import ampache
 
 # user variables
-ampache_url = 'https://music.server'
-ampache_api = 'mysuperapikey'
-ampache_user = 'myusername'
+ampache_url = 'https://develop.ampache.dev'
+ampache_api = 'demodemo'
+ampache_user = 'demo'
 
 # xml or json supported formats
 api_format = 'json'
 
+ampacheConnection = ampache.API()
+ampacheConnection.set_format(api_format)
+
 """
 encrypt_string
 """
-encrypted_key = ampache.encrypt_string(ampache_api, ampache_user)
+encrypted_key = ampacheConnection.encrypt_string(ampache_api, ampache_user)
 
 """
 handshake
 """
 print('Connecting to:\n    ', ampache_url)
 src_api = ampache_api
-ampache_api = ampache.handshake(ampache_url, encrypted_key, False, False, '420000', api_format)
+ampache_api = ampacheConnection.handshake(ampache_url, encrypted_key, False, False, '420000')
 
 print('\nThe ampache handshake for:\n    ', src_api, '\n\nReturned the following session key:\n    ', ampache_api)
 if not ampache_api:

diff --git a/docs/examples/playlist_test.py b/docs/examples/playlist_test.py
@@ -5,22 +5,24 @@
 import ampache
 
 # user variables
-ampache_url = 'https://music.server'
-ampache_api = 'mysuperapikey'
-ampache_user = 'myusername'
+ampache_url = 'https://develop.ampache.dev'
+ampache_api = 'demodemo'
+ampache_user = 'demo'
+
+ampacheConnection = ampache.API()
 
 """
 encrypt_string
 """
-encrypted_key = ampache.encrypt_string(ampache_api, ampache_user)
+encrypted_key = ampacheConnection.encrypt_string(ampache_api, ampache_user)
 
 """
 handshake
 """
 # processed details
 print('Connecting to:\n    ', ampache_url)
 src_api = ampache_api
-ampache_api = ampache.handshake(ampache_url, encrypted_key)
+ampache_api = ampacheConnection.handshake(ampache_url, encrypted_key)
 print('\nThe ampache handshake for:\n    ', src_api, '\n\nReturned the following session key:\n    ', ampache_api)
 if not ampache_api:
     print()
@@ -30,7 +32,7 @@
 ping
 """
 # did all this work?
-my_ping = ampache.ping(ampache_url, ampache_api)
+my_ping = ampacheConnection.ping(ampache_url, ampache_api)
 print('\nif your handshake was correct, ping will return your session key and extend the session.')
 print('\nPing returned:\n    ', my_ping)
 if not my_ping:
@@ -40,12 +42,12 @@
 """
 playlists
 """
-playlists = ampache.playlists(ampache_url, ampache_api)
+playlists = ampacheConnection.playlists()
 
 """
 playlist_create
 """
-playlist_create = (ampache.playlist_create(ampache_url, ampache_api, 'python-test', 'private'))
+playlist_create = (ampacheConnection.playlist_create('python-test', 'private'))
 if playlist_create:
     for child in playlist_create:
         if child.tag == 'playlist':
@@ -55,7 +57,7 @@
 """
 playlist
 """
-playlist = ampache.playlists(ampache_url, ampache_api, 'python-test', 'private')
+playlist = ampacheConnection.playlists('python-test', 'private')
 if playlist:
     for child in playlist:
         print(child.tag, child.attrib)
@@ -67,38 +69,35 @@
 """
 playlist_add_song
 """
-songs = ampache.get_indexes(ampache_url, ampache_api, 'song', False, False, False, False, 0, 10)
-for child in songs:
-    if child.tag == 'song':
-        print(ampache.playlist_add_song(ampache_url, ampache_api, single_playlist, child.attrib['id'], 1))
-        print(ampache.playlist_add_song(ampache_url, ampache_api, single_playlist, child.attrib['id'], 1))
+songs = ampacheConnection.get_indexes('song', False, False, False, False, False, 0, 10)
+
+for child in ampacheConnection.get_id_list(songs, 'song'):
+    ampacheConnection.playlist_add_song(single_playlist, child, 1)
 
 """
 playlist_songs
 """
-playlist_songs = ampache.playlist_songs(ampache_url, ampache_api, single_playlist)
+playlist_songs = ampacheConnection.playlist_songs(single_playlist)
 
 """
 playlist_remove_song
 """
-for child in playlist_songs:
-    if child.tag == 'song':
-        print(ampache.playlist_remove_song(ampache_url, ampache_api, single_playlist, child.attrib['id']))
+for child in ampacheConnection.get_id_list(playlist_songs, 'song'):
+    ampacheConnection.playlist_remove_song(single_playlist, child)
 
 """
 playlist_edit
 """
-print(ampache.playlist_edit(ampache_url, ampache_api, single_playlist, 'generic', 'public'))
 
 
 """
 playlist_delete
 """
-print(ampache.playlist_delete(ampache_url, ampache_api, single_playlist))
+ampacheConnection.playlist_delete(single_playlist)
 
 """
 goodbye
 """
 # Close your session when you're done
 print('\nWhen you are finished it\'s a good idea to kill your session')
-print('    ', ampache.goodbye(ampache_url, ampache_api))
+ampacheConnection.goodbye()
diff --git a/docs/examples/requirements.txt b/docs/examples/requirements.txt
@@ -1,4 +1,4 @@
-ampache~=4.2.2
+ampache~=5
 requests~=2.22.0
 setuptools~=44.0.0
 playsound~=1.2