Metadata-Version: 2.2
Name: bisos.pyDblock
Version: 0.1
Summary: bisos.py-dblock: Pure-Python org-mode Dynamic Block Expansion
Author: Mohsen Banan
Author-email: libre@mohsen.1.banan.byname.net
Maintainer: Mohsen Banan
Maintainer-email: libre@mohsen.1.banan.byname.net
License: AGPL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: bisos
Requires-Dist: bisos.b
Requires-Dist: bisos.common
Requires-Dist: setuptools==75.8.0
Requires-Dist: wheel==0.38.4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: summary

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

.. contents::
   :depth: 3
..

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 <https://github.com/bisos-pip/pycs>`__. 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:

Table of Contents TOC
=====================

-  `Overview <#overview>`__
-  `Part of BISOS — ByStar Internet Services Operating
   System <#part-of-bisos--bystar-internet-services-operating-system>`__
-  `bisos.py-dblock is a Command-Only PyCS
   Facility <#bisospy-dblock-is-a-command-only-pycs-facility>`__
-  `Installation <#installation>`__

   -  `Installation With pip <#installation-with-pip>`__
   -  `Installation With pipx <#installation-with-pipx>`__
   -  `Post-Installation Basic
      Testing <#post-installation-basic-testing>`__

-  `Usage <#usage>`__

   -  `Update Dblocks in Org Files <#update-dblocks-in-org-files>`__

-  `How It Works <#how-it-works>`__
-  `Key Files <#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 <#pypi-and-github-packaging>`__

-  `Documentation and Blee-Panels <#documentation-and-blee-panels>`__
-  `Support <#support>`__
-  `Planned Improvements <#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 <https://github.com/bxGenesis/start>`__ 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 <https://github.com/bxplpc/120033>`__

*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 <https://github.com/bisos-pip/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:

.. code:: bash

   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:

.. code:: bash

   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:

.. code:: bash

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

Usage
=====

Update Dblocks in Org Files
---------------------------

Expand all registered dblocks in one or more files:

.. code:: bash

   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:

.. code:: bash

   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:

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

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

#. 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 <./setup.py>`__ files driven by
`pypiProc.sh <./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 <./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 <http://mohsen.1.banan.byname.net>`__ 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``
