coffeepenbit/bookstack

A Python wrapper for BookStack's API

bookstack

A Python wrapper for BookStack's API

Current version: 0.2.0-post1

Installation

To install bookstack, run:

pip install bookstack

Setup

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.

>>> import bookstack

# Input the appropriate values for these three variables
>>> 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:

>>> 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', ...}

The above are then the methods available to you, for example:

>>> books_list = api.get_books_list()
>>> books_list['data'][0]['name']
'Mathematics'

And to POST you can follow this example:

>>> api.post_books_create({'name': 'Sample Book', 'description': 'Sample Description', 'tags': [{ 'name': 'Sample-Name', 'value': 'Sample-Value' }] })

bookstack's Issues

POST didn't work

I think, this is wrong:

bookstack/src/bookstack/models.py

Line 50 in ac63b0e

method_info['uri'].format(**kwargs)

POST didn't work because **kwargs was not passed to the requests function. Therefore, it was not possible to use the data parameter.

            response = self._session.request(
                method_info['method'],
                #method_info['uri'].format(**kwargs)       <- this didn't work for POST
                method_info['uri'],
                **kwargs
            )

POST methods and POST data

Seems like POST methods don't send the POST data, such as name when creating a book. I tried to use name and data kwargs but always got 422 error.

add minimal sample for post request

hi, first of all i am a total python newbee and i am trying to use your bookstack api.
the connection works and the api element shows me all the allowed api methods.
however i am not able to perform a post request.

is it somehow possible to add a minimal sample how to perform a post request using a simple json payload ?
That would be awesome. Thanks

POST method argument error

I cannot call any post methods.

Installed with PIP
Version: 0.1.0b0

Error: TypeError: BookStack._create_api_method..request_method() takes 0 positional arguments but 1 was given

I don't know if I am doing something wrong, but it happens, even if i call the method from the readme?!

TypeError thrown during generate_api_methods()

The code is as follows so far

api = bookstack.BookStack(base_url, 
                          token_id=token_id, 
                          token_secret=token_secret)

api.generate_api_methods()

the output

Traceback (most recent call last):
  File "/home/keith/repo/release-automation-bookstack/release-checklist.py", line 13, in <module>
    api.generate_api_methods()
  File "/home/keith/repo/release-automation-bookstack/.venv/lib/python3.11/site-packages/bookstack/models.py", line 33, in generate_api_methods
    method_name = self._create_method_name(method_info)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/keith/repo/release-automation-bookstack/.venv/lib/python3.11/site-packages/bookstack/models.py", line 70, in _create_method_name
    '_'.join([method_info['method'], method_info['name']])
              ~~~~~~~~~~~^^^^^^^^^^
TypeError: string indices must be integers, not 'str'

BookStack v23.05.1
Python 3.11.2 (main, Mar 13 2023, 12:18:29) [GCC 12.2.0] on linux

Unable to generate API methods

Doing the following:

import os
import bookstack

base_url = "https://libros.catedu.es"
token_id = os.environ["BOOKSTACK_TOKEN_ID"]
token_secret = os.environ["BOOKSTACK_TOKEN_SECRET"]

api = bookstack.BookStack(base_url, token_id=token_id, token_secret=token_secret)
api.generate_api_methods()

... gives me the following traceback:

---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
[/home/deleyva/Documentos/2022/jesus-scripts/probando.ipynb](https://file+.vscode-resource.vscode-cdn.net/home/deleyva/Documentos/2022/jesus-scripts/probando.ipynb) Cell 34 in ()
----> [1](vscode-notebook-cell:/home/deleyva/Documentos/2022/jesus-scripts/probando.ipynb#X45sZmlsZQ%3D%3D?line=0) api.generate_api_methods()

File [~/.cache/pypoetry/virtualenvs/jesus-scripts-RbQ3YFZJ-py3.8/lib/python3.8/site-packages/bookstack/models.py:33](https://file+.vscode-resource.vscode-cdn.net/home/deleyva/Documentos/2022/jesus-scripts/~/.cache/pypoetry/virtualenvs/jesus-scripts-RbQ3YFZJ-py3.8/lib/python3.8/site-packages/bookstack/models.py:33), in BookStack.generate_api_methods(self)
     31 for base_model_info in self._get_api().values():
     32     for method_info in base_model_info:
---> 33         method_name = self._create_method_name(method_info)
     35         setattr(
     36             self, 
     37             method_name,
     38             self._create_api_method(method_info)
     39         )
     41         self.available_api_methods.add(method_name)

File [~/.cache/pypoetry/virtualenvs/jesus-scripts-RbQ3YFZJ-py3.8/lib/python3.8/site-packages/bookstack/models.py:64](https://file+.vscode-resource.vscode-cdn.net/home/deleyva/Documentos/2022/jesus-scripts/~/.cache/pypoetry/virtualenvs/jesus-scripts-RbQ3YFZJ-py3.8/lib/python3.8/site-packages/bookstack/models.py:64), in BookStack._create_method_name(self, method_info)
     62 def _create_method_name(self, method_info):
     63     return self._format_camelcase(
---> 64         '_'.join([method_info['method'], method_info['name']])
     65     )

TypeError: string indices must be integers

Unable to retrieve more than 100 records with LIST methods

Our wiki has 100+ pages. The list methods of this framework only return up to 100 records at a time. We have tried including offset, count, and filter as keyword arguments in several different ways but no luck. Is it possible to include these parameters when calling the list methods? If yes, could you let us know how?