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