Metadata-Version: 2.2
Name: bisos.fileObj
Version: 0.1
Summary: bisos.fileObj: Filesystem-directory-backed data structures (fto, fp, fv)
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: bisos.csPlayer
Requires-Dist: bisos.csSeed
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.fileObj: Filesystem-directory-backed data structures (fto, fp, fv)
========================================================================

.. contents::
   :depth: 3
..

Overview
========

*bisos.fileObj* is an **umbrella package for filesystem-directory-backed
data structures** in BISOS. Each module inside is a self-contained
abstraction whose identity and state live in a filesystem directory, not
in a database or in memory.

Currently:

-  ``bisos.fileObj.fto`` — **File Tree Object** + tree walker. A
   generalization of the bash-based FTO facility
   (``/bisos/core/bsip/bin/lcnObjectTree.libSh``, ``seedFtoCommon.sh``,
   ``ftoProc.sh``). Marker-file conventions (``_tree_``, ``_treeProc_``,
   ``_objectType_``), branch/leaf classification, and a walker that
   recurses down a tree applying a command at each node. This is the
   first module and the reason the umbrella package exists.
-  ``bisos.fileObj.fp`` — **File Parameter**. Currently in
   ``bisos.b.fp``; reserved slot for a future migration into this
   package.
-  ``bisos.fileObj.fv`` — **File Variable**. Currently in
   ``bisos.b.fv``; reserved slot for a future migration.

*bisos.fileObj* is a python package that uses the
`PyCS-Framework <https://github.com/bisos-pip/pycs>`__.

Charter — Scope of This Package
===============================

**This package is for filesystem-directory-backed data structures where
the directory IS the object identity.** If your thing needs a database,
an in-memory structure, or a network resource, it doesn't belong here.

The charter is deliberately narrow so the umbrella does not become a
"small utility drawer." Additions require that the thing being added:

#. Represents its identity and state as a filesystem directory.
#. Uses marker files (like ``_tree_``) to make its type / role
   discoverable.
#. Sits at a similar level of abstraction as ``fto``, ``fp``, ``fv`` —
   primitive data structures, not higher-level constructs. Higher-level
   things (``bisos.regfps`` over ``fp``, ``bisos.siteRegistrars`` over
   ``regfps``) belong in their own packages.

If a proposed module doesn't meet all three, it goes in its own package
or in a different umbrella.

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.fileObj* is part of BISOS. It is a standalone package that can be
used independently of the full BISOS environment.

Installation
============

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

The bisos.fileObj pip package is available at PyPI as
https://pypi.org/project/bisos.fileObj

Installation With pip
---------------------

.. code:: bash

   pip install bisos.fileObj

Installation With pipx
----------------------

.. code:: bash

   pipx install bisos.fileObj

Usage
=====

As a Python library
-------------------

.. code:: python

   from bisos.fileObj import fto

   branch = fto.FILE_TreeObject('/tmp/exampleTree')
   branch.branchCreate()

   leaf = fto.FILE_TreeObject('/tmp/exampleTree/leaf1')
   leaf.leafCreate()

   fto.treeRecurse(base='/tmp/exampleTree', command=['echo', 'hello'])

As a walker
-----------

Plant a branch ``.spcs`` at any branch directory in your tree, then
invoke it with a command. The walker descends into every leaf beneath
that branch and applies the command via each leaf's ``_treeProc_``.

See the ``bisos.dockerProc`` + ``bro_dockerfiles`` combination for a
worked-through example.

Key Files
=========

-  ``py3/bisos/fileObj/__init__.py`` — package init.
-  ``py3/bisos/fileObj/fto.py`` — ``FILE_TreeObject`` class,
   ``FileTreeItem`` enum, walker functions. Modeled on
   ``/bisos/core/bsip/bin/lcnObjectTree.libSh``.
-  ``py3/bisos/fileObj/fto_csu.py`` — PyCS command surface exposing the
   walker (``treeRecurse``, ``effectiveBranches``, etc.) as ``cs.Cmnd``
   classes.

Documentation and Blee-Panels
=============================

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

See
`file:./panels/bisos.fileObj/_nodeBase_/fullUsagePanel-en.org <./panels/bisos.fileObj/_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
====================

-  Migrate ``b.fp`` and ``b.fv`` into ``bisos.fileObj.fp`` /
   ``bisos.fileObj.fv`` with compatibility shims in ``bisos.b``.
-  Add a branch ``.spcs`` reference implementation that any tree can
   plant.
-  Extend ``_objectType_`` dispatch so heterogeneous trees (mixed leaf
   types) are handled cleanly.
