bisos.pyDblock 0.1

bisos.py-dblock: Pure-Python org-mode Dynamic Block Expansion

Contents

• Overview

• Table of Contents TOC

• Part of BISOS — ByStar Internet Services Operating System

• bisos.py-dblock is a Command-Only PyCS Facility

• Installation

  • Installation With pip

  • Installation With pipx

  • Post-Installation Basic Testing

• Usage

• How It Works

• Key Files

  • py3/bin/py-dblock.cs

  • py3/bisos/pyDblock/updateDblock.py

  • py3/bisos/pyDblock/dblock_particulars.py

  • PyPi and Github Packaging

• Documentation and Blee-Panels

• Support

• Planned Improvements

Overview

bisos.py-dblock is a pure-Python engine for expanding org-mode dynamic blocks (dblocks) in files, without requiring Emacs or the Blee bx-dblock tool. It mimics org-mode’s dblock model: handlers register under a signature string, and a single pass over a file dispatches each ####+BEGIN: <signature> [args] / ####+END: block to its registered handler, replacing the block body with freshly computed content.

bisos.py-dblock is a python package that uses the PyCS-Framework. It provides the py-dblock.cs command for updating org-mode dynamic blocks from the command-line.

The package ships one built-in handler, for the b:ai:file/particulars dblock used by the ByStar AI collaborative development template set.

Table of Contents TOC

• Overview

• Part of BISOS — ByStar Internet Services Operating System

• bisos.py-dblock is a Command-Only PyCS Facility

• Installation

  • Installation With pip

  • Installation With pipx

  • Post-Installation Basic Testing

• Usage

  • Update Dblocks in Org Files

• How It Works

• Key Files

  • `py3/bin/py-dblock.cs <#py3binpy-dblockcs>`__

  • `py3/bisos/pyDblock/updateDblock.py <#py3bisospydblockupdatedblockpy>`__

  • `py3/bisos/pyDblock/dblock_particulars.py <#py3bisospydblockdblock_particularspy>`__

  • PyPi and Github Packaging

• Documentation and Blee-Panels

• Support

• Planned Improvements

Part of BISOS — ByStar Internet Services Operating System

Layered on top of Debian, BISOS (By* Internet Services Operating System) is a unified and universal framework for developing both internet services and software-service continuums that use internet services. See Bootstrapping ByStar, BISOS and Blee for information about getting started with BISOS.

BISOS is a foundation for The Libre-Halaal ByStar Digital Ecosystem which is described as a cure for losses of autonomy and privacy in a book titled: Nature of Polyexistentials

bisos.py-dblock is part of BISOS. It is a standalone package that can be used independently of the full BISOS environment.

bisos.py-dblock is a Command-Only PyCS Facility

bisos.py-dblock is a command-line tool. It is a PyCS single-unit command service. PyCS is a framework that converges development of CLI tools and services. PyCS is an alternative to FastAPI, Typer and Click.

bisos.py-dblock uses the PyCS-Framework to expand org-mode ####+BEGIN: ...

/ ####+END: dynamic blocks in one or more files, in pure Python, without requiring Emacs or bx-dblock.

The core of PyCS-Framework is the bisos.b package (the PyCS-Foundation). See bisos.b for an overview.

Installation

The sources for the bisos.py-dblock pip package are maintained at: https://github.com/bisos-pip/py-dblock.

The bisos.py-dblock pip package is available at PYPI as https://pypi.org/project/bisos.py-dblock

You can install bisos.py-dblock with pip or pipx.

Installation With pip

If you need access to bisos.py-dblock as a python module, you can install it with pip:

pip install bisos.py-dblock

Installation With pipx

If you only need access to bisos.py-dblock on command-line, you can install it with pipx:

pipx install bisos.py-dblock

The following command is made available:

• py-dblock.cs — updates org-mode dynamic blocks in files (pure Python)

Post-Installation Basic Testing

After installation, run:

py-dblock.cs
py-dblock.cs -i examples

Usage

Update Dblocks in Org Files

Expand all registered dblocks in one or more files:

py-dblock.cs -i updateDblocks AI-WorkPlan.org AI-DevStatus.org

Each file argument is scanned for ####+BEGIN: <signature> / ####+END: blocks. Blocks whose signature has a registered handler are re-expanded; unrecognised blocks are left untouched. Non-file arguments are skipped with a note.

A ready-to-use example/test file is bundled at py3/tests/AI-WorkPlan.org (a copy of the ByStar mother/AI-WorkPlan.org template). It contains a b:ai:file/particulars dblock, so:

py-dblock.cs -i updateDblocks ./tests/AI-WorkPlan.org

expands that block in place. py-dblock.cs -i examples lists this and other example invocations.

How It Works

py-dblock mimics org-mode’s dblock model in pure Python:

1. Handlers register under a signature string via registerHandler(signature, fn).

2. expandAll(filePath) does a single-pass regex substitution over the file. and its :key value arguments are parsed from the BEGIN line, the registered

   handler is looked up, and its returned text replaces the block body.

3. Unregistered signatures are left untouched.

The bundled b:ai:file/particulars handler derives its content from the file path, the containing directory, and the AI-Activity.org symlink present there (activity name + companion-docs list).

Key Files

An overview of the relevant files of the bisos.py-dblock package:

py3/bin/py-dblock.cs

The CS-MU (Command-Services Multi-Unit). Provides the updateDblocks command. Imports dblock_particulars to register the b:ai:file/particulars handler.

py3/bisos/pyDblock/updateDblock.py

General dblock dispatch engine. Handlers register under a signature string via registerHandler(sig, fn). expandAll(filePath) does a single-pass regex substitution over the file, dispatching each ####+BEGIN: <signature> block to its registered handler.

py3/bisos/pyDblock/dblock_particulars.py

Self-registering handler for the b:ai:file/particulars dblock signature. Derives the activity from the AI-Activity.org symlink and builds the companion-docs list by scanning the directory.

PyPi and Github Packaging

All bisos-pip repos in the https://github.com/bisos-pip github organization follow the same structure. They all have setup.py files driven by pypiProc.sh.

Documentation and Blee-Panels

bisos.py-dblock is part of ByStar Digital Ecosystem http://www.by-star.net.

This module’s primary documentation is in the form of Blee-Panels.

bisos.py-dblock Blee-Panels are in the ./panels directory. From within Blee and BISOS these panels are accessible under the Blee “Panels” menu.

See file:./panels/bisos.py-dblock/_nodeBase_/fullUsagePanel-en.org for a starting point.

Support

For support, criticism, comments and questions; please contact the author/maintainer

Mohsen Banan at: http://mohsen.1.banan.byname.net/contact

Planned Improvements

• Upload to PyPI and test as pipx install

• Write fullUsagePanel-en.org Blee-Panel

• Add further dblock handlers beyond b:ai:file/particulars