osmith has submitted this change. ( https://gerrit.osmocom.org/c/python/osmo-python-tests/+/43101?usp=email )
Change subject: README: update ......................................................................
README: update
* Convert to markdown * Add a short summary on top * Modernize installation instructions * Change the example from deprecated openbsc and deprecated osmodumpdoc.py to libosmocore's osmo-ns-dummy and osmotestconfig.py * Remove mention of twisted_ipa.py, as it was removed in 5d0fac9d
Change-Id: I13c6327ca210e29cde3f9bb75c93c892682a5a28 --- D README A README.md 2 files changed, 89 insertions(+), 47 deletions(-)
Approvals: pespin: Looks good to me, but someone else must approve Jenkins Builder: Verified fixeria: Looks good to me, approved
diff --git a/README b/README deleted file mode 100644 index 3b59257..0000000 --- a/README +++ /dev/null @@ -1,47 +0,0 @@ -Building/installation: - - sudo python3 setup.py install - -If you prefer to have it cleanly removable, install checkinstall and run - - sudo checkinstall python setup.py install - -Alternatively, just run - - pip3 install --user -e ./ - -depending on your python version. - -Use: -There are currently following scripts in this package: -osmotestconfig.py - test that apps start/write with example configs -osmo_trap2cgi.py - implementation of CGI <-> Ctrl proxy implemented on top of asyncio and aiohttp -osmo_rate_ctr2csv.py - rate counter dumper on top of osmo_ipa -osmo_interact_vty.py - pipe stdin/stdout to a VTY session -osmo_interact_ctrl.py - pipe stdin/stdout to a CTRL port -osmo_verify_transcript_vty.py - VTY testing by VTY session screen dumps -osmo_verify_transcript_ctrl.py - CTRL testing by CTRL session script files -twisted_ipa.py - implementation of IPA and Ctrl protocols on top of Twisted framework -osmodumpdoc.py - dump documentation, superseded by osmo_interact_vty.py -X -osmotestvty.py - test vty operations, superseded by osmo_verify_transcript_vty.py - -Some of these scripts import a project-specific osmoappdesc.py, -which provides information about the available apps, configs, vty ports, etc. -and is provided by other source trees (like osmo-bsc.git, osmo-msc.git, ...) - -Run the scripts with osmoappdesc.py in the current directory (preferred) -or with -p <the directory containing osmoappdesc.py>. -Remember that osmoappdesc.py may contain relative paths. - -Example: -After install osmodumpdoc for openbsc's apps can be run by: -cd <your_source_dir>/openbsc/openbsc && osmodumpdoc.py - -Libraries: -osmopy/osmoutil.py - code that's shared between the scripts -osmopy/osmo_ipa.py - generic implementation of IPA and Ctrl protocols in python -osmopy/trap_helper.py - generic Trap class and related helpers used by soap.py and ctrl2cgi.py -osmopy/osmo_interact/{vty,ctrl}.py - general interactions with VTY and CTRL ports -osmopy/obscvty.py - connect to a vty, superseded by osmo_interact/vty - -obscvty.py may be of general use. osmoutil.py probably isn't. diff --git a/README.md b/README.md new file mode 100644 index 0000000..b5d9959 --- /dev/null +++ b/README.md @@ -0,0 +1,89 @@ +# osmo-python-tests + +Various scripts that are mostly used for interacting with VTY/CTRL interfaces +of Osmocom programs. + +## Installation + +### Python user install directory + +While discouraged by the python developers, the easiest way to make +osmo-python-tests always available for your user is installing to +`~/.local/lib/python3.*/site-packages/osmopy`: + +``` +$ pip3 install --user --break-system-packages . +``` + +### Virtual environment + +If you prefer to have osmo-python-tests clearly separated, install to a venv: + +``` +$ python3 -m venv ~/.osmocom-venv +$ source ~/.osmocom-venv/bin/activate +$ pip3 install . +``` + +Keep in mind that you must run the source line again whenever you need to use +osmo-python-tests. + +### Osmocom binary packages + +If you run a Debian-based Linux distribution, you can alternatively enable the +[Osmocom binary repository](https://osmocom.org/projects/cellular-infrastructure/wiki/Binary_Packages) +and do a system-wide installation: + +``` +# apt install osmo-python-tests +``` + +## Usage + +There are currently following scripts in this package: + +* `osmotestconfig.py` - test that apps start/write with example configs +* `osmo_trap2cgi.py` - implementation of CGI <-> Ctrl proxy implemented on top of asyncio and aiohttp +* `osmo_rate_ctr2csv.py` - rate counter dumper on top of osmo_ipa +* `osmo_interact_vty.py` - pipe stdin/stdout to a VTY session +* `osmo_interact_ctrl.py` - pipe stdin/stdout to a CTRL port +* `osmo_verify_transcript_vty.py` - VTY testing by VTY session screen dumps +* `osmo_verify_transcript_ctrl.py` - CTRL testing by CTRL session script files +* `osmodumpdoc.py` - dump documentation, superseded by `osmo_interact_vty.py -X` +* `osmotestvty.py` - test vty operations, superseded by `osmo_verify_transcript_vty.py` + +Some of these scripts import a project-specific `osmoappdesc.py`, which +provides information about the available apps, configs, vty ports, etc. and is +provided by other source trees (like osmo-bsc.git, osmo-msc.git, ...). + +Run the scripts with `osmoappdesc.py` in the current directory (preferred) or +with `-p <the directory containing osmoappdesc.py>`. Remember that +`osmoappdesc.py` may contain relative paths. + +### Example + +Build osmo-ns-dummy from libosmocore: + +``` +$ cd libosmocore +$ autoreconf -fi +$ ./configure +$ make +``` + +Enter the directory with `osmoappdesc.py` and run a test script: + +``` +$ cd tests/gb +$ osmotestconfig.py -w . +``` + +## Libraries + +* `osmopy/osmoutil.py` - code that's shared between the scripts +* `osmopy/osmo_ipa.py` - generic implementation of IPA and Ctrl protocols in python +* `osmopy/trap_helper.py` - generic Trap class and related helpers used by `soap.py` and `ctrl2cgi.py` +* `osmopy/osmo_interact/{vty,ctrl}.py` - general interactions with VTY and CTRL ports +* `osmopy/obscvty.py` - connect to a vty, superseded by `osmo_interact/vty.py` + +`obscvty.py` may be of general use. `osmoutil.py` probably isn't.