#+title: bisos.b:  PyCS-Foundation Package --  Python Commands and Services Package
#+DATE: <2024-02-19 Mon 16:27>
#+AUTHOR: Mohsen BANAN

* Overview
*bisos.b* (*PyCS-Foundation*) is a python package which functions as a foundation
for development of Command-Services based on the general model of
*Expectation Complete Operations* (*ECO*)s.

PyCS-Foundation is further enhanced with other packages and tools forming *PyCS-Framework*.
PyCS-Framework are a set of Standalone-BISOS-Packages.
PyCS-Framework can be used in python environments without BISOS.

PyCS-Framework is further enhanced with BISOS packages and tools forming
*PyCS-BISOS-Framework*. Python BISOS-Applications and BISOS-Capabilities are all
based on the PyCS-BISOS-Framework.

* Table of Contents     :TOC:
- [[#overview][Overview]]
- [[#about-bisos----bystar-internet-services-operating-system----and-bystar-de][About BISOS -- ByStar Internet Services Operating System -- and ByStar DE]]
- [[#pycs-complete-framework][PyCS Complete Framework]]
- [[#concept-of-command-services-and-expection-complete-operations-ecp][Concept of Command-Services and Expection Complete Operations (ECP)]]
  - [[#current-and-prior-art][Current and Prior Art]]
  - [[#our-model-and-terminology-for-remote-operation][Our model and terminology for Remote-Operation]]
  - [[#pycs-python-command-servicesbisoss-integration-framework][PyCS (Python Command Services):BISOS's Integration Framework]]
  - [[#commands-services-as-python-ecp][Commands-Services as Python ECP]]
- [[#bisosfacter-as-a-standalone-piece-of-bisos][bisos.facter as a Standalone Piece of BISOS]]
- [[#installation][Installation]]
  - [[#with-pip][With pip]]
  - [[#with-pipx][With pipx]]
- [[#usage][Usage]]
  - [[#locally-system-command-line][Locally (system command-line)]]
  - [[#remotely-as-a-service][Remotely (as a service)]]
- [[#bisosfacter-code-walkthrough][bisos.facter Code Walkthrough]]
  - [[#bisosfacter-source-code-is-in-comeega][bisos.facter Source Code is in COMEEGA]]
  - [[#take-from-120033commonengadopt][Take from 120033/common/engAdopt]]
  - [[#binfactercs--binroperf-factercs--binroinv-factercs][./bin/facter.cs  (./bin/roPerf-facter.cs  ./bin/roInv-facter.cs)]]
  - [[#bisosfacterfacterpy][./bisos/facter/facter.py]]
  - [[#bisosfacterfacter_csupy][./bisos/facter/facter_csu.py]]
- [[#support][Support]]
- [[#documentation][Documentation]]

* About BISOS -- ByStar Internet Services Operating System -- and ByStar DE

Layered on top of Debian, *BISOS*: (*ByStar Internet Services Operating System*) is a
unified and universal platform for developing both internet services and
software-service continuums that use internet services. See [[https://github.com/bxGenesis/start][Bootstrapping
ByStar, BISOS and Blee]] for information about getting started with BISOS.

/bisos.b/ is a small piece of a much bigger picture. *BISOS* is a
foundation for *The Libre-Halaal ByStar Digital Ecosystem* which is described as
a cure for losses of autonomy and privacy that we are experiencing in a book
titled: [[https://github.com/bxplpc/120033][Nature of Polyexistentials]]

* PyCS Complete Framework

* Concept of Command-Services and Expection Complete Operations (ECP)

** Current and Prior Art

Conventionally, a good number of packages and frameworks have been produced to
facilitate development of CLI based python applications. These include:
Click, Typer (based on Pydantic), [[https://docs.python.org/3/library/argparse.html][argparse]], Docopt, fire, etc.

Conventionally, a good number of packages and frameworks have been produced to
facilitate development of Web-APIs/Web-Services/REST-APIs/OpenAPI/Swagger based
python clients and servers. These include: FastAPI (based on Pydantic), gRPC,
pyswagger, Bravado, Flask-API, djangorestframework, RPyC, etc.

These common conventional approaches have several shorcomings. These include:


- The model and terminology of Web-APIs/Web-Services/REST-APIs/OpenAPI/SOAP/gRPC is
  ill directed. The proper model and terminology is that of *Remote Operations*.

- All of the web services models mix web with remote ops at protocol layer.
  Particularly true of OpenAPI.

- Confusing Client Server with invoke/perform

- CLI development and API development have a great deal in common and can be merged.

- Lack of framework

** Our model and terminology for Remote-Operation

Our model and terminology for Remote-Operations is based
on:

#+BEGIN_QUOTE
  *X.880: Remote Operations: Model, Notation and Service Definition*
#+END_QUOTE


ITU X.880 and X.881 which are harmonized with ISO/IEC 13712-1, provide
a model, terminology and service definitions for Remote Operations.
These date back to mid 1990s

Such a valuable formal model and terminology is absent in the Web
Services world and the OpenAIP/Swagger world.

The RO-Verifier software exposes web services capabilities in the
Remote Operations model which conform to the ROSE terminology.


** PyCS (Python Command Services):BISOS's Integration Framework
   :PROPERTIES:
   :CUSTOM_ID: pycs-python-command-servicesbisoss-integration-framework
   :END:

 [sec:PyCS:BISOS'sIntegrationFramework]

BISOS is largely focused on configuration and integration of related
software packages towards creation of consistent services. This is
typically done with "scripts" that augment the software packages in a
consistent way. By scripts, we mean programs that are executed at
command line. At times we also need to build Remote Operations (RO) to
accommodate remote invocation of central services.

There are three fundamental important choices to be made:

1. What programming language should we use for integration?

2. What command-line framework should we use?

3. What Remote Operations (Web Services, REST, Micro Services) framework
   should we use?

BISOS primarily uses Python and some Bash for scripting.

There are various Python frameworks for command-line and web services.
These include click, FastAPI, Flask, Django, RPyC and various others.
None of these provide a comprehensive enough framework for BISOS. BPyF
(BISOS Python Framework) is a comprehensive integration framework of
BISOS that combines existing capabilities from various Python
frameworks.

[[/lcnt/lgpc/bystar/permanent/common/figures/pycsAnatomy.pdf]]

As depicted in Figure [[#fig:pycsAnatomy][[fig:pycsAnatomy]]], BPyF
consists of five major parts.

- Common facilities --- logging, io, error handling, etc.

- File Parameters (FP) and Schema of File Parameters --- BISOS's data
  representation and configuration model

- PyCS: Python Command Services

- BISOS Abstractions

- CS-Units and CS-MultiUnits

In Figure [[#fig:pycsAnatomy][[fig:pycsAnatomy]]], boxes under the
dashed line represent various libraries. General purpose libraries (on
the right side is light green) provide common facilities such as IO,
logging, error handling and configuration management which are used
throughout BISOS. Various libraries that represent BISOS abstractions in
Python such as BPOs, PALS and PAAI. These are shown on the left side in
darker green.

For data representation, BISOS uses its own model called File
Parameters. The equivalent functionality of File Parameters is often
provided by Yaml and Json in typical open-source software packages.

*** PyCS Expectation Complete Operations (ECO)
    :PROPERTIES:
    :CUSTOM_ID: pycs-expectation-complete-operations-eco
    :END:

 [sec:PyCSExpectationCompleteOperations(ECO)]

PyCS is rooted in the model of Expectation Complete Operations (ECO),
which allows for local invocation of an ECO to map to command-line
invocation and remote invocation of an ECO to map to the microservices
model and Remote Operations. This universality of ECOs allows for
command-line facilities to become microservices.

Facilities for command line invocation are depicted above the dashed
line, on the left side of "internet". Facilities in support of service
(Remote Operation) performers are depicted above the dashed line, on the
right side of "internet".

Expectation complete operations are specified and implemented in
CS-Units. A CS-Multi-Unit represents a collection of CS-Units. Notice
that CS-Unit and CS-Multi-Unit boxes are replicated on both sides of
"internet". This indicates that both commands and remote operations map
to expectation complete operations.

Each ECO is capable of describing everything expected from the operation
in full detail which includes all typing information. The information in
Expectation Complete Operation includes:

- Name of the operation

- All input parameters

  - List of optional and mandatory parameters

  - List of positional arguments

  - Stdin expectations

- All outcome parameters

  - All result parameters

  - All error parameters

The information of expectation complete operation then maps to
command-line verbs, parameters and arguments, and similarly for remote
operations. The list of available verbs is specified by the
CS-Multi-Unit. Since CS-Multi-Units are capable of describing all of the
expectations of all of their operations, very powerful automated user
interfaces for invocation of operations can be built. The "CS Player"
box in Figure [[#fig:pycsAnatomy][[fig:pycsAnatomy]]] illustrates that.

*** BISOS PyCS Remote Operations (Web Services)
    :PROPERTIES:
    :CUSTOM_ID: bisos-pycs-remote-operations-web-services
    :END:

 [sec:BISOSPyCSRemoteOperations(WebServices)]

Many BISOS facilities need to be implemented and are implemented as
remote operations. We use the concept and abstraction of remote
operations instead of web services or microservices, to define network
exposed operations.

In BISOS, instead of choosing specific web services or rpc paradigms
such as OpenAPI/Swagger, FastAPI, SOAP, gRPC, RPyC, etc, we bind our
model of Expectation Complete Operations (ECO) to these at a later
stage.

At this time, PyCS remote operations are implemented using RPyC. RPyC or
Remote Python Call, is a transparent library for symmetrical remote
procedure calls, clustering, and distributed-computing. Use of RPyC is
depicted with the line going through the vertical box labeled
"internet". Names used by invokers and performers are shown in the boxes
labeled "RO-Sap" (Remote Operation Service Access Point).

PyCS framework provides a solid foundation for transformation of
software into services and integration of software and services in
BISOS.


** Commands-Services as Python ECP

bisos.facter can be used locally on command-line or remotely as a service.
bisos.facter is a PyCS multi-unit command-service.
PyCS is a framework that converges developement of CLI and Services.
PyCS is an alternative to FastAPI, Typer and Click.

bisos.facter uses the PyCS Framework to:

1) Provide access to facter information  through python namedtuple
2) Provide local access to facter information on CLI
3) Provide remote access to facter information through remote invocation of
   python Expection Complete Operations using [[https://github.com/tomerfiliba-org/rpyc][rpyc]].
4) Provide remote access to facter information on CLI

What is unique in the PyCS Framework is that these four models are all
a single abstraction.




* bisos.facter as a Standalone Piece of BISOS


* Installation

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

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

You can install bisos.facter with pip or pipx.

** With pip

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

#+begin_src bash
pip install bisos.facter
#+end_src

** With pipx

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

#+begin_src bash
pipx install bisos.facter
#+end_src

The following commands are made available:
- facter.cs
- roInv-facter.cs
- roPerf-facter.cs

These are all one file with 3 names. _roInv-facter.cs_ and _roPerf-facter.cs_ are sym-links to _facter.cs_

* Usage

** Locally (system command-line)

=facter.cs= does the equivalent of facter.

#+begin_src bash
bin/facter.cs
#+end_src

** Remotely (as a service)

You can also  run


*** Performer

Invoke performer as:

#+begin_src bash
bin/roPerf-facter.cs
#+end_src

*** Invoker

#+begin_src bash
bin/roInv-facter.cs
#+end_src

* bisos.facter Code Walkthrough

** bisos.facter Source Code is in COMEEGA

bisos.facter can be used locally on command-line or remotely as a service.
** TODO Take from 120033/common/engAdopt


** ./bin/facter.cs  (./bin/roPerf-facter.cs  ./bin/roInv-facter.cs)
A multi-unit

** ./bisos/facter/facter.py

** ./bisos/facter/facter_csu.py

* Support

For support, criticism, comments and questions; please contact the
author/maintainer\\
[[http://mohsen.1.banan.byname.net][Mohsen Banan]] at:
[[http://mohsen.1.banan.byname.net/contact]]

* Documentation

Part of ByStar Digital Ecosystem [[http://www.by-star.net]].

This module's primary documentation is in
[[http://www.by-star.net/PLPC/180047]]

