Skip to content

Table of Contents

booklab

booklab main python package for Booklab system

Consists of the following sub-packages:

  • booklab-cli which is a CLI application to manage system
  • booklabd designed to serve /api/.../ system routes that need database write access
  • booklib booklab system specific general library functions usable by all sub-modules
  • data containing the system data in JSON files
  • conf containing configuration files for different system components including infrastructure ones like gunicorn or nginx
  • doc_src contains the source of static site directory as Markdown files
  • docs/ contains rhe static site compiled and "ready to use as-is" with any standard HTTP server
  • doc-techical containing system usage documentation (aka api interface)

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

booklab.gunicorn.conf

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.booklab_cli

CLI module to assure system operatins as command line.

Architecture; Linux standard (POSIX) CLI

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

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.gunicorn.conf

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.booklib.getBook

getBook

def getBook(db: pysondb, book_code: str) -> dict | None

Check for a given book code:

  • test if book code is not None
  • test if book code exists in database and is exactly 1 record
  • if both conditions return that record as List[Dict]
  • if not any condition return None

Returns:

  • dict(pysondb) with found record
  • None if any condition is not met

booklab.booklib

Module aimed for booklab general purpose functions usable across all its (sub)modules.

Notes:

  • Functions / code defined in this module is agnostic to web application context or CLI application context. In cases where a context is needed this will be trasparent applied locally, meaning that once exit from that function, previous context is fully restored (no side-effects).

  • Some functions could run in background and return control immediatelly after call. These will accept a callback endpoint to be called when finish run.

  • Some functions could have a "lazy / delayed" run behavior and these will be accordingly documented to avoid false expectations.

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

booklab.booklib.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

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.doc_src.book_tmpl.bkcmd_gen_final_book

booklab.doc_src.book_tmpl.bkcmd_start_book_preview

booklab.doc_src.book_tmpl

booklab.doc_src.book_tmpl.bkcmd_render_cfg_file

my_name

use __file__ attribute which guarantees the full pth-and-name of current python file (ATTN if is in a library !)

my_crt_dir

normally this should be the site root directory (in production docs/ & in dev doc_src/)

splitted_my_real_dir

split directory path in its parts

book_directory_name

get last list entry as being the book name where intend to obtain the book code (book dir name format: book_)

book_database_code

keep only characters after book_, sufix name of directory ((book dir name format: book_))

bcat_records

will return a list with all recorsd but allways keep only the first one as code key is UNIQUE

bcat_records

keep only the first one as code key is UNIQUE

templates_root

directory where the file is that need to be renderend (book_mkdocs.yml)

source_config_file

source file (JINJA)

destination_config_file

destination file (YAML)

bcat_jinja_tmpl

load read file content as template

booklab.doc_src

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.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.

Query paraneters: none

api_bstatus

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

serve Book status (bstatus) functionality.

Query paraneters: book code

api_edtb

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

serve Book edit (edtb) functionality.

Query paraneters: book code

api_orgm

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

serve Book structure organization (orgm: functionality.

Query paraneters: book code

api_prvb

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

serve Book preview (prvb) functionality.

Query paraneters: book code

api_bbld

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

serve Book build (bbld) functionality.

Query paraneters: book code

api_dplb

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

serve Book delivery (dplb) functionality.

Query paraneters: book code

api_bcat

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

serve accessing books catalog (bcat) functionality.

index

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

serve a cessing Home route. This is an alternate (but those expected from an end user) way to access static site main / home 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.book_tmpl.bkcmd_gen_final_book

booklab.docs.book_tmpl.bkcmd_start_book_preview

booklab.docs.book_tmpl

booklab.docs.book_tmpl.bkcmd_render_cfg_file

my_name

use __file__ attribute which guarantees the full pth-and-name of current python file (ATTN if is in a library !)

my_crt_dir

normally this should be the site root directory (in production docs/ & in dev doc_src/)

splitted_my_real_dir

split directory path in its parts

book_directory_name

get last list entry as being the book name where intend to obtain the book code (book dir name format: book_)

book_database_code

keep only characters after book_, sufix name of directory ((book dir name format: book_))

bcat_records

will return a list with all recorsd but allways keep only the first one as code key is UNIQUE

bcat_records

keep only the first one as code key is UNIQUE

templates_root

directory where the file is that need to be renderend (book_mkdocs.yml)

source_config_file

source file (JINJA)

destination_config_file

destination file (YAML)

bcat_jinja_tmpl

load read file content as template

booklab.docs

booklab.__main__

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

booklab.data

data component contains the application database as JSON files:

  • a books database (books_catalog.json) containing all created books and detailed information about each one
  • a system database (app_info.json) containing information about installed application
Last update: September 27, 2025