Renames api.py to session.py

README.md

@@ -13,22 +13,22 @@ So far, the API wrapper is still considered unstable, a proper setup file is in
 ## usage
 
 ```
->>> from funkwhale import api
+>>> from funkwhale import session
 # Create the session instance (no login is performed at this step).
 # Use the demo server and credentials.
->>> session = api.Session()
+>>> mySession = session.Session()
 # Or provide your own data.
->>> session = api.Session(instance_endpoint="https://demo.funkwhale.audio", username="demo", password="demo")
+>>> mySession = session.Session(instance_endpoint="https://demo.funkwhale.audio", username="demo", password="demo")
 # Alternatively, if you already have a JWT token you can pass it to the session class
->>> session = api.Session(instance_endpoint="https://demo.funkwhale.audio", token="xxxxxxxxx")
+>>> mySession = session.Session(instance_endpoint="https://demo.funkwhale.audio", token="xxxxxxxxx")
 # Do login.
->>> session.login()
+>>> mySession.login()
 # If username and password were provided, the login method generated already the JWT token.
 # You can save this somewhere for passing it later.
->>> print(session.token)
+>>> print(mySession.token)
 xxxxxxxxx
 # Create the API object, that will be responsible for calling the funkwhale's server.
->>> api = session.get_api()
+>>> api = mySession.get_api()
 # all API calls follow the format "path.to.api.method(key=value, other_key=other_value)"
 # where method can be get and post.
 # Retrieve only 5 artists in the current instance.
@@ -51,6 +51,37 @@ Professor Kliq
 ...
 Demo library
 >>>
+# In some situations, Funkwhale returns partial or full URLS in some API calls.
+# We can use the direct_post and direct_get in the api object for calling the requests methods
+# This will call requests.get and requests.post without any magic in the API.
+# for example, to retrieve a next page after calling to api.artists.get, there is a key called next.
+>>> print(artists["next"])
+http://demo.funkwhale.audio:80/api/v1/artists/?page=2&page_size=5
+# In this case we will not use api.artists.get because it builds the URL based in class attributes.
+# Instead we just use the direct_get method.
+>>> next_artists = api.direct_get(artists["next"])
+>>> for i in  next_artists["results"]:
+...     print(i["name"])
+...
+Nine Inch Nails
+Neon NiteClub
+Igor Pumphonia
+MicheyQ
+JekK
+# also, we can pass partial URLS such as /api/v1/listen/track_id to the API.
+# the API has a function called full_url which will convert the URL properly into a full URL so it can be used in other apps
+# Or used to be called with direct_post/direct_get
+# This kind of URL is returned by funkwhale in tracks, for example.
+# retrieve a single Track.
+>>> track = api.tracks.get(1)
+# the listen_url is a partial URL so we cannot pass it directly to request methods.
+>>> print (tracks["listen_url"])
+/api/v1/listen/778e01b2-85d9-4f73-b30d-3007a011c5f3/
+# Convert it to a full URL which will be accepted by all request methods and in other apps
+# As long as the provided credentials are valid.
+>>> api.full_url(track["listen_url"])
+https://demo.funkwhale.audio/api/v1/listen/778e01b2-85d9-4f73-b30d-3007a011c5f3/
+>>>
 ```
 
 More usage examples are located in the tests directory. Also You can see all available methods directly in the [Funkwhale interactive API.](https://docs.funkwhale.audio/swagger/)

tests/test_api.py

@@ -1,13 +1,13 @@
 # -*- coding: utf-8 -*-
 import unittest
-from funkwhale import api
+from funkwhale import session
 
 class testApi(unittest.TestCase):
 
 	def setUp(self):
 		# For the moment we use the demo Funkwhale server.
 		# Later the API wrapper should have the possibility of using environment variables to fill the class constructor.
-		self.session = api.Session()
+		self.session = session.Session()
 
 	def test_auth(self):
 		""" Testing user authentication against the Funkwhale server. """
@@ -18,7 +18,7 @@ class testApi(unittest.TestCase):
 		""" Testing the exception mechanism present in all API methods. """
 		self.setUp()
 		self.session.username = "demo1"
-		self.assertRaises(api.APIError, self.session.login)
+		self.assertRaises(session.APIError, self.session.login)
 		self.setUp()
 		self.session.login()