BISOS-PIP is part of ByStar.

The Libre-Halaal ByStar Digital Ecosystem (By* DE) is an interdisciplinary, and ethics-oriented non-proprietary digital ecosystem which challenges the existing proprietary American digital ecosystem while operating concurrently alongside it. On a global scale, By* provide Internet Application Services which preserve autonomy and privacy of the individual. 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. BISOS is a layer on top of Debian. Blee: (BISOS Libre-Halaal Emacs Environment) is a layer on top of Emacs and BISOS, which creates a comprehensive integrated usage and development environment. Blee and BISOS are fully integrated. See the ”Nature of Polyexistentials” book for the bigger picture of how all of ByStar fits together.

For bootstraping BISOS, Blee and ByStar; you can start at: https://github.com/bxgenesis/start

Here we describe the common aspects of all the repos in the bisos-pip organization.

• Common Structure of Repos in the bisos-pip Organization
  • bisos-pip Packages Documentation
  • bisos-pip Build System
• Python File Names Convention
  • Python Files Coding Style and Conventions — COMEEGA

Every package in the bisos-pip organization follows the same repository shape. The repo name (e.g. csSeed) determines the installed package name: setup.py derives it as bisos.<repo-dir-name> from its own path, so a repo named csSeed installs as bisos.csSeed. All bisos-pip packages share the single bisos. namespace (a pkg_resources declare_namespace package), so the per-package code always lives one level down, under py3/bisos/<pkg>/.

Sources are segregated by language at the top of the repo; the Python-3 project is kept under py3/ (leaving room for sibling trees in other languages). A typical repo looks like this — substitute <pkg> for the package name (entries tagged [gen] are machine-produced; never hand-edit them):

<repo>/                          FTO auxNode (repo root)
├── README.org                   human-facing overview (org is the source of truth)
├── LICENSE
├── ftoProc.sh, _tree_,          BISOS File-Tree-Object (FTO) markers + processor
│   _treeProc_, _objectType_
└── py3/                         the Python-3 project (FTO leaf)
    ├── setup.py                 packaging; name auto-derived as bisos.<repo-dir-name>
    ├── pyproject.toml           build-system (setuptools) declaration
    ├── pypiProc.sh              build/publish wrapper (seed over seedPypiProc.sh)
    ├── ftoProc.sh + FTO markers FTO node metadata for this subtree
    ├── _description.org         #+title: line consumed by setup.py as the description
    ├── README.rst               PyPI long_description            [gen: from README.org]
    ├── lh-agpl3-LICENSE.txt
    ├── bisos/
    │   ├── __init__.py          namespace stub (declare_namespace only)
    │   └── <pkg>/               the actual package: CSU modules, libs, seed/seedInfo
    ├── bin/                     CS executables — *.cs and *.pcs (run directly)
    ├── panels/bisos.<pkg>/      Blee-Panels documentation (org-mode)
    ├── dist/                    built sdists / wheels            [gen]
    └── bisos.<pkg>.egg-info/    setuptools metadata              [gen]

The _tree_ / _treeProc_ / _objectType_ marker files and ftoProc.sh are BISOS File-Tree-Object (FTO) metadata: they type each directory as a node or leaf and let /bisos/core/bsip/bin/seedFtoCommon.sh process the repo as a typed tree (_objectType_ carries the dotted type, e.g. sw.py.pypi.icm.fto.leaf). They are repo-management metadata, not Python code.

Documentation for a bisos-pip package is layered from high level to detailed:

1. Top-level =README.org= (repo root) — a very high-level overview: what the package is, where it fits in BISOS, install/usage pointers. README.rst and the #+title: of _description.org are derived from it for PyPI. This is the only documentation a casual reader needs.
2. Blee-Panels under py3/panels/bisos.<pkg>/ — the detailed, working documentation. The package’s entry panel is its base node: py3/panels/bisos.<pkg>/_nodeBase_/fullUsagePanel-en.org (for csSeed, ./py3/panels/bisos.csSeed/_nodeBase_/fullUsagePanel-en.org).

A Blee-Panel is an org-mode document that is itself an FTO node (_objectType_ = blee.org.fto.node, processed by bleePanelProc.sh). Each panel node keeps its content in a _nodeBase_/ subdirectory as fullUsagePanel-<lang>.org — the -en suffix is the language, so panels are multilingual. A panel may have descendant panels (topic sub-nodes); for csSeed these are README, dotPCS-PlantedCS, dotSPCS-SpreadPlantedCS, and seedCsDesign, each with its own _nodeBase_/fullUsagePanel-en.org.

Panels are not isolated files: each package panel is grafted into the global BISOS panels tree (under /bisos/panels/...) and is reachable from within Blee via the “Panels” menu, with in-panel navigation to its Ancestors, Siblings, and Descendants.

The panel and the source code cross-reference each other:

• Python modules name their panel in the csInfo['panel'] field (and link to it from the file’s org header), pointing the reader from code to documentation.
• The panel, in turn, holds runnable examples — invocations of the package’s bin/ executables — and links back to the specific Python files that implement them.

Packaging is convention-driven: nothing is configured by hand. The three build files are generated or maintained from the directory structure and the repo’s files, and a single seeded script drives every build/install/publish action.

setup.py

A collection of org-mode dblocks. Everything — the package name (bisos.<repo-dir-name>), version, scripts, data_files, and install_requires — is determined automatically from the directory structure and files. Treat it as generated: do not hand-edit inside its dblocks, and note the version (pkgVersion()) is managed for you, so a manual edit will not stick.

pyproject.toml

A generic build-system (setuptools) declaration, also maintained by a dblock.

pypiProc.sh

A seeded ICM Bash script derived from /bisos/core/bsip/bin/seedPypiProc.sh. This is the single entry point for all build, install, and publish operations. Run it with no arguments to print its example/usage menu.

Common operations (run from py3/):

# Install locally as editable, into a development venv
pypiProc.sh -v -n showRun -i pkgReInstall edit /bisos/venv/py3/dev-bisos3

# Build, upload to PyPI, then reinstall
pypiProc.sh -v -n showRun -p repo=main -i fullPrepBuildUploadRePrep

Flag conventions, shared by all PyCS/ICM scripts: -v verbose; -n showRun echoes each underlying command as it runs; -i <cmnd> [args] invokes a command; -p name=value sets a parameter.

Executables live in py3/bin/ and deliberately carry no .py suffix; the extension encodes the file’s role instead. (Dashes are allowed in these names.) Importable library/module code lives in py3/bisos/<pkg>/ and does use the .py suffix.

(The .pcs / .spcs / .npcs seed-and-plant mechanics are detailed in The seed / plant model below.)

All Python files — and the bin/ executables — are authored in COMEEGA format (Collaborative Org-Mode Enhanced Emacs Generalized Authorship), which interleaves org-mode structure with the code. Every source file is dense with ####+BEGIN: ... ####+END: blocks and #+begin_org ... #+end_org docstrings: these are machine-generated by Emacs/Blee org-mode dynamic blocks. The content between a ####+BEGIN: and its matching ####+END: is regenerated from the parameters on the BEGIN line — class headers, function signatures, import blocks, the main block, and file boilerplate are all produced this way.

When editing:

• Edit only the body after a ####+END: marker (the actual implementation), not the generated header/signature between the markers — hand edits inside a dblock are liable to be overwritten on regeneration.
• The csInfo dict near the top of each file (version, status, panel) is also managed; treat its version as generated.
• Files end with ### no-byte-compile: t and #+STARTUP: showall — leave intact.

Authoritative references: