From 7b7c92c8a3bba11117b30b658a111d6595b146b6 Mon Sep 17 00:00:00 2001 From: Tommy Carpenter Date: Tue, 13 Aug 2019 10:53:29 -0400 Subject: [PATCH] Make the PYPI page for rmr look nicer. Change-Id: I6d2c42e7e348e25016cb706267b7065446ae3886 Signed-off-by: Tommy Carpenter --- src/bindings/rmr-python/Changelog.md | 3 ++ src/bindings/rmr-python/README.md | 60 ----------------------- src/bindings/rmr-python/README.rst | 92 ++++++++++++++++++++++++++++++++++++ src/bindings/rmr-python/setup.py | 15 +++++- 4 files changed, 108 insertions(+), 62 deletions(-) delete mode 100644 src/bindings/rmr-python/README.md create mode 100644 src/bindings/rmr-python/README.rst diff --git a/src/bindings/rmr-python/Changelog.md b/src/bindings/rmr-python/Changelog.md index 101f9e8..d729712 100644 --- a/src/bindings/rmr-python/Changelog.md +++ b/src/bindings/rmr-python/Changelog.md @@ -4,6 +4,9 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/). +## [0.10.5] - 8/13/2019 + * Make the PYPI page for rmr look nicer. + ## [0.10.4] - 8/08/2019 * Fix underlying problem getting errno from some environments; now references new RMR message field to get errno value. * Add /usr/local/lib64 to tox environment variable to support systems where libraries natually install in lib64 rather than lib. diff --git a/src/bindings/rmr-python/README.md b/src/bindings/rmr-python/README.md deleted file mode 100644 index 814c27e..0000000 --- a/src/bindings/rmr-python/README.md +++ /dev/null @@ -1,60 +0,0 @@ -# rmr-python - -# Summary, Limitations -This is a CTYPES wrapper around the C rmr library. It requires you have rmr installed. - -That is, it is not a native re-implementation of the rmr library. This seems to come with pros and cons. On the positive side, wrapping the library was much less work; we only need to wrap the function signatures. -Keeping up with the rmr spec is thus also less work, as when new functions are added into the C lib, we only need to again wrap the function signatures. - -The downside is this seems to be Linux only currently. This wrapper immediately SIGABRT's on Mac, and no one yet seems to know why. -The other downside is that there are currently some functionality that needs to be "exported" from the C library for this to be fully operational. For example, CTYPES does not have access to C header files, and important -constants are defined in the C header files. Also, the C lib uses "errno" to propogate some error conditions, and those are not available "in-band" yet. - -It could be questioned whether this was a good decision, or whether we should have natively reimplemented the API with the nano nng python bindings: https://pypi.org/project/pynng/ - -## Not Yet Implemented -At the time of this writing (March 28 2019) The following C functions are not yet implemented in this library (do we need them?): - - 1. `extern void rmr_free_msg` - 2. `extern rmr_mbuf_t* rmr_mtosend_msg` - 3. `extern rmr_mbuf_t* rmr_call` (this has some problems AFAIU from Scott) - 4. `extern rmr_mbuf_t* rmr_rcv_specific` - 5. `extern int rmr_get_rcvfd` - -# Higher order library - -There is/was somewhat of a debate about what belongs here, and the current answer is that this is mostly a pure wrapper around the C rmr library (though it does come with one convenience function called `message_summary` which is quite useful) - -There are some higher order send functions, for example functions that send and expect an ACK back of a specific message type, that might be useful to you, here: https://gitlab.research.att.com/tommy/ric-ons-a1-gevent/blob/master/a1/a1rmr.py - -# Unit Testing - - tox - open htmlcov/index.html - -# Installation - -## Prequisites - -If rmr is *not* compiled on your system, see the below instructions for downloading and compiling rmr. This library expects that the rmr .so files are compiled and available. - -## From PyPi - - pip install rmr==X.Y.Z - -## From Source - - git clone "https://gerrit.o-ran-sc.org/r/ric-plt/lib/rmr" - cd rmr/src/bindings/rmr-python/ - pip install . - -# Examples - -See the `examples` directory. - -# Compiling rmr (if not already done on your system) -(Note, you may or may not need sudo in your final command, depending on permissions to `/usr/local`. The pack externals option to CMake is needed only if the NNG libary is not already installed on the system, and you do not wish to manually install it.) - - git clone https://gerrit.oran-osc.org/r/ric-plt/lib/rmr - cd rmr - mkdir .build; cd .build; cmake .. -DPACK_EXTERNALS=1; sudo make install diff --git a/src/bindings/rmr-python/README.rst b/src/bindings/rmr-python/README.rst new file mode 100644 index 0000000..cbda718 --- /dev/null +++ b/src/bindings/rmr-python/README.rst @@ -0,0 +1,92 @@ +rmr-python +========== + +Summary, Limitations +==================== + +This is a CTYPES wrapper around the C rmr library. It requires you have +rmr installed. + +That is, it is not a native re-implementation of the rmr library. This +seems to come with pros and cons. On the positive side, wrapping the +library was much less work; we only need to wrap the function +signatures. Keeping up with the rmr spec is thus also less work, as when +new functions are added into the C lib, we only need to again wrap the +function signatures. + +The downside is this seems to be Linux only currently. This wrapper +immediately SIGABRT’s on Mac, and no one yet seems to know why. The +other downside is that there are currently some functionality that needs +to be “exported” from the C library for this to be fully operational. +For example, CTYPES does not have access to C header files, and +important constants are defined in the C header files. + +Possibly evaluate whether we could natively reimplement the API with the nano nng python +bindings: https://pypi.org/project/pynng/ + +Not Yet Implemented +------------------- + +At the time of this writing (Aug 13 2019) The following C functions +are not yet implemented in this library (do we need them?): + +:: + + 1. `extern void rmr_free_msg` + 2. `extern rmr_mbuf_t* rmr_mtosend_msg` + 3. `extern rmr_mbuf_t* rmr_call` (this has some problems AFAIU from Scott) + 4. `extern rmr_mbuf_t* rmr_rcv_specific` + 5. `extern int rmr_get_rcvfd` + +Unit Testing +============ + +:: + + tox + open htmlcov/index.html + +Installation +============ + +Prequisites +----------- + +If rmr is *not* compiled on your system, see the below instructions for +downloading and compiling rmr. This library expects that the rmr .so +files are compiled and available. + +From PyPi +--------- + +:: + + pip install rmr==X.Y.Z + +From Source +----------- + +:: + + git clone "https://gerrit.o-ran-sc.org/r/ric-plt/lib/rmr" + cd rmr/src/bindings/rmr-python/ + pip install . + +Examples +======== + +See the ``examples`` directory. + +Compiling rmr (if not already done on your system) +================================================== + +(Note, you may or may not need sudo in your final command, depending on +permissions to ``/usr/local``. The pack externals option to CMake is +needed only if the NNG libary is not already installed on the system, +and you do not wish to manually install it.) + +:: + + git clone https://gerrit.oran-osc.org/r/ric-plt/lib/rmr + cd rmr + mkdir .build; cd .build; cmake .. -DPACK_EXTERNALS=1; sudo make install diff --git a/src/bindings/rmr-python/setup.py b/src/bindings/rmr-python/setup.py index 1df9311..2ea41f6 100644 --- a/src/bindings/rmr-python/setup.py +++ b/src/bindings/rmr-python/setup.py @@ -22,18 +22,29 @@ SETUP_DIR = abspath(dirname(__file__)) def _long_descr(): """Yields the content of documentation files for the long description""" - doc_path = path_join(SETUP_DIR, "README.md") + doc_path = path_join(SETUP_DIR, "README.rst") with open(doc_path) as f: return f.read() setup( name="rmr", - version="0.10.4", + version="0.10.5", packages=find_packages(), author="Tommy Carpenter, E. Scott Daniels", description="Python wrapper for RIC RMR", url="https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/lib/rmr", + classifiers=[ + "Development Status :: 4 - Beta", + "Intended Audience :: Telecommunications Industry", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.7", + "License :: OSI Approved :: Apache Software License", + "Operating System :: POSIX :: Linux", + "Topic :: Communications", + ], + python_requires=">=3.7", + keywords="RIC rmr", license="Apache 2.0", data_files=[("", ["LICENSE.txt"])], install_requires=[], -- 2.16.6