API packet booklab - BookLab
Author: Petre Iordanescu (petre.iordanescu@gmail.com)

Skip to content

booklab">

# booklab

Main python package for Booklab system.

Consists of the following sub-packages:

- `booklab_cli` main CLI application to operate the system
- `booklabd` designed to serve `/api/.../` routes used by all functionalities that need write / update and POST operations
- `conf` contain configuration files for different system components including infrastructure ones like gunicorn or nginx
- `doc_src` contain the source of static site directory as Markdown files
- `docs` contain rhe static site compiled and "ready to use as-is" with any standard HTTP server
- `my_books` contain the end user created & generated books and `books_catalog.json` with info about all user books
- `scripts` contain diffrent scrpts usefull in system administrarion (install, maintain, configure, in-house development and customizations)

Package is compliant with Python PEP packaging specificatios and published on PyPi under `booklab` name. Package is open source licenced and available as source package on GitHub under `booklab` name and author repositories.

author: Petre Iordanescu (mail: petre.iordanescu@gmail.com, GitHub: petre-renware)

# booklab.booklab_cli

Booklab CLI module to assure system operatins as command line.

Usage:

    booklab -v
    booklab setup <options>
    booklab init <options>
    booklab server (run|stop|restart)
    booklab catalog
    booklab status <my-book>
    booklab new
    booklab build <my-book>
    booklab preview <my-book>
    booklab deploy <my-book>
    booklab page-edit <my-book>
    booklab page-upload <my-book>
    booklab page-upload <my-book>
    vooklab edit-nav[igation] <my-book>
    booklab pack <my-book>

Options:

    -l, --list    List books catalog
    -s, --status  Display detailes about a book
    -v, --version Display booklab application version

Architecture; Linux standard (POSIX) CLI

Author; Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.booklab_cli.cmd_xxx

Command xxx definition.

# booklab.booklab_cli.param_types

Define parameters used by CLI app.

Parameters definition as used by `Typer` framework in parameters definition and described through `Annotated` class.

# booklab.conf

Cnfigurations component contains various system components configuration files:

- `gunicorn` WSGI web server
- `nginx` local proxy HTTP

Notes / remarks:

- files wirh `.py` extension are considered Python files and can be imported accordingly as longas they are valid Python-code.
- all files from here are assumed to be text files. Any deviation from this rule is assumed to be treated accordingly in code.

Author; Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.conf.gunicorn_config

Configuration file for gunicorn in serving `booklabd` server application

This is a Python file that will be executed by gunicorn at run-time. As consequence declare all assignements as valid Python code.

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.conf.booklab_ext_url

This Python file contains external access URL information. By external access is understood all URL parts necessary to expose Booklab application:

- EXT_SERVER - the external exposed server name and port if diffrent than standard default (80 or 443) (example: "booklab.mydomain.ro")
- EXT_PATH - the external exposed URL of configured start locations through a LAN main proxy (example: "/booklab/" for a complete external URL like http://booklab.mydomain.ro:5002/booklab/)

NOTE: all information are of string type

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.my_books.book_template

Contains the book template used when create a new book (`newb` funxtion, `/api/newb/` booklabd route).

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.my_books

This component contains all defined books as individual directories, each one with all definions initiated from `book_template/` directory

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.my_books.books_manager

## Results Objects

    @dataclass(frozen = True)
    class Results()

Define a result model (type) frequently used as return set by MyBook methods.

Class as data type (model) is defined frozen to protect change its instance attribites once created. This is usefull when used as member in other objects to protect them to be altered outside the object.

#### exit_code

Exit code of run method. Usual is the same as method returns.

#### exit_text

Output text of last run method (equivalent of stdout when run a console process).

#### console_out

    @property
    def console_out() -> None | str

Return `exit_text` converted to console format on a dumb terminal.

## MyBooks Objects

    class MyBooks()

Class that manage end user books.

Mandatory requirements:

- any Jinja renderings will be made "from string" (ie, using Flask `render_from_string()` which is included) or by creating a local Jinja environment.

author: Petre Iordanescu (petre.iordanescu@gmail.com)

#### MY_BOOKS_URL_prefix

URL prefix to add when accesing a book local (generated) site.

#### MY_BOOK_URL

Instantiated book URL to local (generated) site.

#### MY_BOOKS_ROOT

Confusing name ? just duplicate the global one in class namespace.

#### book_code

Instanciated book code.

#### db_books_catalog

Books catalog data controller.

#### db_book_nav

Books navigation data controller.

#### jinja_env

Jinja environment usable for my_books rendering needs.

#### results

Keep result of last run method (for methods that should return composite result).

#### __init__

    def __init__(db: pysondb, book_code: str) -> None

Init an instance of class MyBooks.

#### getBook

    def getBook() -> dict | None

Check for a given book code that is not None, exists in database and is exactly 1 record.

Returns:

- `dict` with found record or
- `None` if any of conditiona is not met

#### getBookNav

    def getBookNav(format: str = None) -> None | dict | str

Get book navigation.

Navigation info is retrieved from `book_navigation.json` data-file and is identified by `self.db_book_nav` pysondb handler.

Returns:

- `python dict` using `format = "dict"` (default option)
- `JSON str` using `format = "json"`
- `YAML str` using `format = "yaml"`
- `None` if not known format

#### wrBookNav

    def wrBookNav() -> bool

Write out file "book_navigation.yml".

Returns:

- `True` if file was written
- `False` if file was not written or cannot be read regardless why (usual problem is source file)

Lateral effects:

- on disk: create / update current book navigation definition file in YAML format (`book_navigation.yml`).

#### getBookPath

    def getBookPath() -> str

Get absolute path of current book root directory.

#### getBookURL

    def getBookURL() -> str

Get preview URL (redirectable as is) for current book_code.

#### renderBookConfig

    def renderBookConfig() -> Results

Render current book configuration file. Produce file `mkdocs.yml` as being the configuration file to build the book. File is writen in book root directory.

Returns:

- `Results object` reference to `self.results`

Lateral effects:

- on disk: update current book configuration file (`mkdocs.yml`).

#### buildBook

    def buildBook() -> None | str

Build (mkdocs build) current boook.

Build current book (ie, `mkdocs build`) in its own directory. Method suppose that mkdocs.yml file is good and book content directory (doc_src/) content is ok and "as-expected", that meaning the method just run nkdocs build process, collect output and return it.

Returns:

- `str` stdout + stderr of run process
- `None` if process exit with fatal err (standard baah return 1)

Lateral effects:

- on disk: create / update current book static site directory (usual `docs/`).

#### createPhysicalBook

    def createPhysicalBook() -> bool

Create physical book directory as copy of "book_template".

Lateral effects:

- on disk: creates new directory & filrs on disk represing current book physical location.

# booklab.doc_src

Booklab master static site:

- `doc_src/` markdown source files
- `docs/` generated static site ready to be used as is with any standard HTTP server

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.scripts

Booklab utility scripts that solve various aspects in installing, configuring and running Booklab system / application.

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.__version__

version.py module that contains Booklab aplication version number.

NOTE: this module is imported and made "public" in `booklab._init__.py`

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.booklabd.publisher

#### publish

    def publish()

Decorator the publishes the Flask function, wiring up arguments to the incoming request.

The function arguments are inspected and used to extract the values from the request GET/POST data (via request.values). If type annotations are specified, the incoming values will be instantiated as that type. If "**kwargs" is included, remaining GET/POST values are placed there, otherwise they are ignored.

Example:

@app.route("/somewhere") @publish() def somewhere(gender:str, age:int=None): return jsonify(gender=gender, age=age)

# booklab.booklabd.routes

Module that serve `booklabd` interface api-functions as HTTP routes

Important variables:

- `booklab.boolabd.api_app`: web application object (aka Flask.app)

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

#### api_newb

    @api_app.route("/api/newb/")
    def api_newb()

Serve New book (newb) functionality.

#### api_bstatus

    @api_app.route("/api/bstatus/")
    def api_bstatus(book_code: str = ...)

Serve Book status (bstatus) functionality.

Query parameters: `code` for database `boook_code`

#### api_edtb

    @api_app.route("/api/edtb/")
    def api_edtb(book_code: str = ...)

Serve Book edit (edtb) functionality.

Query parameters: `code` for database `boook_code`

#### api_orgm

    @api_app.route("/api/orgm/")
    def api_orgm(book_code: str = ...)

Serve Book structure & navigation organization (orgm) functionality.

Query parameters: `code` for database `boook_code`

#### api_prvb

    @api_app.route("/api/prvb/")
    def api_prvb(book_code: str = ...)

Serve Book preview (prvb) functionality.

Query parameters: `code` for database `boook_code`

#### api_bbld

    @api_app.route("/api/bbld/")
    def api_bbld(book_code: str = ...)

Serve Book build (bbld) functionality.

Query parameters: `code` for database `boook_code`

#### api_dplb

    @api_app.route("/api/dplb/")
    def api_dplb(book_code: str = ...)

Serve Book delivery (dplb) functionality.

Query parameters: `code` for database `boook_code`

#### api_bcat

    @api_app.route("/api/bcat/")
    def api_bcat()

Serve Books catalog (bcat) functionality.

#### version

    @api_app.route("/api/version/")
    def version()

Return Booklab application version as pure plain raw text (no html).

#### index

    @api_app.route("/")
    def index()

Serve accessing Home route. This route is an alternate option way (but usually the expected one from an end user) to access static site main / home page.

#### about

    @api_app.route("/api/about/")
    def about()

Construct and request for "About Booklab" page.

# booklab.booklabd.app_init

app_init module that initialize `booklabd` application

This module is designed to initialize the main web application object `api_app`.

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

#### init_app

    def init_app(app_name: str, static_site_dir: str, templates_dir: str,
                 pjroot_location: str) -> Flask

Create Flask application object and return it

Arguments:

- `app_name` - name of web application objwcr
- `static_site_dir` - directory used by Flask app to render Jinja templates
- `templates_dir` - directory name where templates are to becfound (relative to pjroot_location)
- `pjroot_location` - project root directory (relative to pjroot_location)

Returns:

web application object

# booklab.booklabd

booklabd - Booklab API server module

Main functionalities: * operate & manage JSON database file * provide necessary http API routes fir book functionalities that need write & dynamic (run-time) behavior

Architecture; HTTP WSGI

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.docs

Booklab master static site:

- `doc_src/` markdown source files
- `docs/` generated static site ready to be used as is with any standard HTTP server

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

# booklab.__main__

... wip ... modules to be launched at package call with `-m` option

# booklab.db_init

Module that initialize `booklabd` database (more JSON files)

This module is designed to initialize database objects `db_books` and `db_system`.

Author: Petre Iordanescu (petre.iordanescu@gmail.com)

#### init_db

    def init_db() -> tuple[pysondb]

Create db_books, db_system objects and return them as tuple

Returns:

`(db_books, db_system)` tuple of pysondb object

Last update: November 19, 2025