Added dynamic method generation

Author: coffeepenbit

README.md

@@ -15,16 +15,35 @@ To use BookStack's API, you'll need to get a token ID and secret.
 
 You can find how to get these values from your BookStack instance's doc page at `http[s]://<example.com>/api/docs`
 
+**Note**: Your account's user group must have API usage priveleges enabled.
+
 # Usage
 Once you've acquired your token ID and secret, you're ready to rock.
 
 ```python
-import bookstack
+>>> import bookstack
 
 # Input the appropriate values for these three variables
-base_url = 'http[s]://<example.com>'
-token_id = '<token_id>'
-token_secret = '<token_secret>'
+>>> base_url = 'http[s]://<example.com>'
+>>> token_id = '<token_id>'
+>>> token_secret = '<token_secret>'
+
+>>> api = bookstack.BookStack(base_url, token_id=token_id, token_secret=token_secret)
+```
+
+This wrapper *dynamically* generates its API calls at runtime. To have the wrapper generate the methods, use:
+
+```python
+>>> api.generate_api_methods()
+
+>>> api.available_api_methods
+{'get_books_export_pdf', 'get_shelves_list', 'post_books_create', 'get_docs_display', 'delete_shelves_delete', 'get_books_list', 'get_docs_json', 'delete_books_delete', 'get_books_read', 'get_shelves_read', 'put_books_update', 'get_books_export_plain_text', 'get_books_export_html', 'post_shelves_create', ...}
+```
 
-api = bookstack.BookStack(base_url, token_id=token_id, token_secret=token_secret)
-```
+The above are then the methods available to you, for example:
+
+```python
+>>> books_list = api.get_books_list()
+>>> books_list['data'][0]['name']
+'Mathematics'
+```

setup.py

@@ -1,21 +1,12 @@
 from setuptools import setup, find_packages
 import os
 
-
-here = os.path.abspath(os.path.dirname(__file__))
-
-about = {}
-with open(os.path.join(here, 'src', 'bookstack', '__init__.py'), 'r', encoding='utf-8') as f:
-    exec(f.read(), about)
-
-with open(os.path.join(here, 'README.md'), encoding='utf-8') as f:
-    long_description = f.read()
-
-install_requires = [
-    'requests'
+CLASSIFIERS = [
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
 ]
-
-extras_require = {
+EXTRAS_REQUIRE = {
     'dev': [
         'bump2version',
         'pylint',
@@ -25,24 +16,43 @@
         'tox'
     ]
 }
+INSTALL_REQUIRES = [
+    'requests>= 2.18, < 3',
+    'cached_property >= 1.5, < 2',
+    'inflection == 0.4'
+]
+
 
+def get_about(here):
+    about = {}
+    about_info_path = os.path.join(here, 'src', 'bookstack', '__version__.py')
+    with open(about_info_path,'r', encoding='utf-8' ) as f:
+        exec(f.read(), about)
+
+    return about
+
+def get_long_description(here):
+    with open(os.path.join(here, 'README.md'), encoding='utf-8') as f:
+        long_description = f.read()
+
+    return long_description
+
+
+here = os.path.abspath(os.path.dirname(__file__))
+about = get_about(here)
 
 setup(
     name=about['__title__'],
     version=about['__version__'],
     url=about['__url__'],
     description=about['__description__'],
-    long_description=long_description,
+    long_description=get_long_description(here),
     author=about['__author__'],
     author_email=about['__author_email__'],
     long_description_content_type='text/markdown',
     packages=find_packages('src'),    
     package_dir={'': 'src'},
-    install_requires=install_requires,
-    extras_require=extras_require,
-    classifiers=[
-        "Programming Language :: Python :: 3",
-        "License :: OSI Approved :: MIT License",
-        "Operating System :: OS Independent",
-    ]
+    install_requires=INSTALL_REQUIRES,
+    extras_require=EXTRAS_REQUIRE,
+    classifiers=CLASSIFIERS
 )

src/bookstack/models.py

@@ -1,74 +1,92 @@
+from json.decoder import JSONDecodeError
+import string
 import urllib
 
+from cached_property import cached_property
+import inflection
 import requests
 
 
+API_PATH = 'api/docs.json/'
+
+
 class BookStack:
-    def __init__(self, base_url, token_id=None, token_secret=None):
-        self.api_base_url = self._create_api_base_url(base_url)
+    def __init__(
+                self,
+                base_url,
+                token_id=None,
+                token_secret=None,
+                api_path=API_PATH
+            ):
+        self.api_base_url = base_url
         self.token_id = None
         self.token_secret = None
+        self._api_path = api_path
 
+        self.available_api_methods = set()
         self._session = BaseURLSession(self.api_base_url)
         self._session.auth = Auth(token_id, token_secret)
 
-        self.endpoint_paths = {
-            'docs': 'docs.json/',
-            'books': 'books/',
-            'shelves': 'shelves/',
-            'export_text': 'export/plaintext',
-            'export_html': 'export/html'
-        }
-    
-    @staticmethod
-    def _create_api_base_url(base_url):
-        parsed_url = urllib.parse.urlparse(base_url)
-        if 'api' in str(parsed_url.path):
-            parsed_url = parsed_url
-        else:
-            parsed_url = parsed_url._replace(**{'path': 'api/'})
-
-        return parsed_url.geturl()
-
-    def get_docs(self):
-        return self._session.get(self.endpoint_paths['docs']).json()
-
-    def get_books(self):
-        return self._session.get(self.endpoint_paths['books']).json()
-
-    def read_book(self, book_id):
-        return self._session.get(
-            urllib.parse.urljoin(
-                self.endpoint_paths['books'],
-                str(book_id)
-            )
-        ).json()
+    def generate_api_methods(self):
+        for base_model_info in self._get_api().values():
+            for method_info in base_model_info:
+                method_name = self._create_method_name(method_info)
 
-    def export_text(self, book_id):
-        return self._session.get(
-            urllib.parse.urljoin(
-                self.endpoint_paths['books'],
-                f"{book_id}/{self.endpoint_paths['export_text']}"
-            )
-        ).text
+                setattr(
+                    self, 
+                    method_name,
+                    self._create_api_method(method_info)
+                )
+
+                self.available_api_methods.add(method_name)
+
+    def _get_api(self):
+        return self._session.request('GET', self._api_path).json()
 
-    def export_html(self, book_id):
-        return self._session.get(
-            urllib.parse.urljoin(
-                self.endpoint_paths['books'],
-                f"{book_id}/{self.endpoint_paths['export_html']}"
+    def _create_api_method(self, method_info):
+        def request_method(**kwargs):
+            response = self._session.request(
+                method_info['method'],
+                method_info['uri'].format(**kwargs)
             )
-        ).text              
-        
+            
+            return self._get_response_content(response)
+
+        return request_method
+
+    @staticmethod
+    def _get_api_args(uri):
+        return [api_arg
+                for _, api_arg, _, _ in string.Formatter().parse(uri)]
+
+    def _create_method_name(self, method_info):
+        return self._format_camelcase(
+            '_'.join([method_info['method'], method_info['name']])
+        )
+
+    @staticmethod
+    def _format_camelcase(string_):
+        return inflection.underscore(string_)
+
+    @staticmethod
+    def _get_response_content(response):
+        try:
+            content = response.json()
+        except JSONDecodeError:
+            content = response.text
+
+        return content
+
 
 class BaseURLSession(requests.Session):
     def __init__(self, base_url, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.base_url = base_url
 
-    def get(self, url_path, *args, **kwargs):
+    def request(self, method, url_path, *args, **kwargs):
         url = urllib.parse.urljoin(self.base_url, url_path)
-        return super().get(url, *args, **kwargs)
+        
+        return super().request(method, url, *args, **kwargs)
 
 
 class Auth(requests.auth.AuthBase):
@@ -82,6 +100,7 @@ def __init__(self,
         self.token_secret = token_secret
 
     def __call__(self, r):
-        r.headers[self.header_key] = f'Token {self.token_id}:{self.token_secret}'
+        r.headers[self.header_key] = \
+            f'Token {self.token_id}:{self.token_secret}'
 
         return r

tests/test_models.py

@@ -40,46 +40,42 @@ def test_intiialize(base_url, token_id, token_secret):
         assert token_id == token_id
         assert token_secret == token_secret
 
-    # @staticmethod
-    # @pytest.mark.vcr()
-    # def test_get_docs(fixture_bookstack):
-    #     test_result = fixture_bookstack._get_docs()
+    @staticmethod
+    def test_generate_api_methods(fixture_bookstack, fixture_api_info):
+        fixture_bookstack.generate_api_methods()
 
-    #     assert test_result
-    #     assert isinstance(test_result, dict)
-    #     assert all(key in test_result.keys() for key in ['docs'])        
+        assert 'get_books_list' in fixture_bookstack.available_api_methods
+        assert 'get_books_list' in dir(fixture_bookstack)
 
     @staticmethod
-    # @pytest.mark.vcr()
-    def test_api(fixture_bookstack):
-        test_result = fixture_bookstack._api
+    @pytest.mark.vcr()
+    def test_get_docs_json(fixture_bookstack):
+        test_result = fixture_bookstack.get_docs_json()
 
-        assert isinstance(test_result, bookstack.models.API)
+        assert test_result
+        assert isinstance(test_result, dict)
+        assert all(key in test_result.keys() for key in ['docs'])        
 
     @staticmethod
-    def test_methods(fixture_bookstack):
-        test_result = fixture_bookstack.methods()
+    def test_available_api_methods(fixture_bookstack):
+        test_result = fixture_bookstack.available_api_methods
 
-        assert 'books_export_plain_text' in test_result
+        assert 'get_books_export_plain_text' in test_result
         assert '_create_methods' not in test_result
 
-    @staticmethod
-    def test_reset_api(fixture_bookstack):
-        raise NotImplementedError
-
     @staticmethod
     @pytest.mark.vcr()
-    def test_get_books(fixture_bookstack):
-        test_result = fixture_bookstack.get_books()
+    def test_get_books_list(fixture_bookstack):
+        test_result = fixture_bookstack.get_books_list()
 
         assert test_result
         assert isinstance(test_result, dict)
         assert all(key in test_result.keys() for key in ['data', 'total'])
 
     @staticmethod
     @pytest.mark.vcr()
-    def test_read_book(fixture_bookstack):
-        test_result = fixture_bookstack.read_book(1)
+    def test_get_books_read(fixture_bookstack):
+        test_result = fixture_bookstack.get_books_read(id=2)
 
         assert test_result
         assert isinstance(test_result, dict)
@@ -88,30 +84,16 @@ def test_read_book(fixture_bookstack):
 
     @staticmethod
     @pytest.mark.vcr()
-    def test_export_text(fixture_bookstack):
-        test_result = fixture_bookstack.export_text(1)
+    def test_get_books_export_plain_text(fixture_bookstack):
+        test_result = fixture_bookstack.get_books_export_plain_text(id=2)
 
         assert test_result
         assert isinstance(test_result, str)
 
     @staticmethod
     @pytest.mark.vcr()
-    def test_export_html(fixture_bookstack):
-        test_result = fixture_bookstack.export_html(1)
+    def test_get_books_export_html(fixture_bookstack):
+        test_result = fixture_bookstack.get_books_export_html(id=2)
 
         assert test_result
         assert isinstance(test_result, str)
-
-
-class TestAPI:
-    @staticmethod
-    def test_intiialize_empty():
-        with pytest.raises(TypeError):
-            bookstack.models.API() # pylint: disable=no-value-for-parameter
-    
-    @staticmethod
-    def test_initialize(api_info):
-        test_result = bookstack.models.API(api_info)
-
-        assert test_result
-