libe3py 0.2.3__tar.gz

libe3py-0.2.3/LICENSE

@@ -0,0 +1,178 @@
+Copyright (c) 2026 Northeastern University
+
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to the Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

libe3py-0.2.3/NOTICE

@@ -0,0 +1,15 @@
+libe3
+
+Copyright (c) 2026 Northeastern University
+
+This product includes software developed at the Institute for Intelligent
+Networked Systems, Northeastern University.
+
+Use, modification and redistribution are permitted under the Apache License,
+Version 2.0 (see LICENSE), including the E3AP protocol definition in
+messages/asn1/V1/e3ap-1.0.0.asn1. If you use libe3, or derive a protocol
+definition or an implementation from it, we ask that you cite the work:
+
+  [citation to be added on publication]
+
+That citation is a request, not an additional condition on the license.

libe3py-0.2.3/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: libe3py
+Version: 0.2.3
+Summary: Python binding of libe3, the O-RAN E3 interface library
+Author: Northeastern University
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Operating System :: POSIX :: Linux
+Project-URL: Homepage, https://github.com/wineslab/libe3
+Project-URL: Documentation, https://github.com/wineslab/libe3/blob/main/swig/README.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# libe3py
+
+Python binding of [libe3](https://github.com/wineslab/libe3), the C++ library that implements the O-RAN
+E3 interface between a RAN node and its dApps. The [dApp library](https://github.com/wineslab/dApp-library)
+(`pip install dapps`) uses it for E3AP; see
+[`swig/README.md`](https://github.com/wineslab/libe3/blob/main/swig/README.md) for the API.
+
+libe3py is built when you install it, against the libe3 installed on the machine, and it must be the same
+version. Install libe3 once:
+
+```bash
+git clone --branch <version> https://github.com/wineslab/libe3 && cd libe3
+./build_libe3 -I                         # build dependencies, swig and python3-dev included
+./build_libe3 --all-encodings --install  # into /usr/local, asks for sudo
+```
+
+then, in any virtual environment and without root:
+
+```bash
+pip install libe3py==<version>
+python -c "import libe3py; print(libe3py.__version__)"
+```

libe3py-0.2.3/VERSION

@@ -0,0 +1 @@
+0.2.3

libe3py-0.2.3/cmake/libe3SwigModule.cmake

@@ -0,0 +1,55 @@
+# The libe3py SWIG module, shared by the in-tree build (libe3SWIG.cmake) and the
+# pip build against an installed libe3 (python/CMakeLists.txt), so the two
+# cannot drift apart.
+#
+#   libe3_add_python_module(<target> SOURCE_DIR <repo root> OUTPUT_DIR <dir> LINK <libe3 target> [INCLUDE <dir>...])
+#
+# Produces <OUTPUT_DIR>/_libe3py.so and <OUTPUT_DIR>/libe3py.py. The module links
+# libe3 statically, so it needs no liblibe3.so at run time.
+#
+# SPDX-FileCopyrightText: Copyright (c) 2026 Northeastern University
+# SPDX-License-Identifier: Apache-2.0
+
+include_guard(GLOBAL)
+
+find_package(SWIG 4.0 REQUIRED COMPONENTS python)
+if(CMAKE_VERSION VERSION_LESS 3.18)
+    find_package(Python3 REQUIRED COMPONENTS Interpreter Development)
+else()
+    find_package(Python3 REQUIRED COMPONENTS Interpreter Development.Module)
+endif()
+include(UseSWIG)
+
+function(libe3_add_python_module target)
+    cmake_parse_arguments(ARG "" "SOURCE_DIR;OUTPUT_DIR;LINK" "INCLUDE" ${ARGN})
+    set(_i "${ARG_SOURCE_DIR}/swig/libe3.i")
+    file(MAKE_DIRECTORY "${ARG_OUTPUT_DIR}")
+    set_property(SOURCE "${_i}" PROPERTY CPLUSPLUS ON)
+    set(_swig_inc "${ARG_SOURCE_DIR}/swig" ${ARG_INCLUDE})
+    set_property(SOURCE "${_i}" PROPERTY INCLUDE_DIRECTORIES ${_swig_inc})
+    set(_swig_flags "")
+    foreach(_d IN LISTS _swig_inc)
+        list(APPEND _swig_flags "-I${_d}")
+    endforeach()
+    # latrec.h refuses to compile without CLOCK_MONOTONIC declared (see its own
+    # #error), which SWIG's preprocessor never sees for real: it does not walk
+    # glibc's actual <time.h>/<bits/time.h> chain the way the real compiler does
+    # afterwards on the generated wrapper. The numeric value is never evaluated
+    # by SWIG, only its definedness, so a placeholder satisfies the check.
+    list(APPEND _swig_flags "-DCLOCK_MONOTONIC=1")
+    set_property(SOURCE "${_i}" PROPERTY SWIG_FLAGS ${_swig_flags})
+
+    swig_add_library(${target}
+        TYPE SHARED
+        LANGUAGE python
+        SOURCES "${_i}" "${ARG_SOURCE_DIR}/swig/e3_dapp_session.cpp"
+        OUTPUT_DIR "${ARG_OUTPUT_DIR}")
+    set_target_properties(${target} PROPERTIES LIBRARY_OUTPUT_DIRECTORY "${ARG_OUTPUT_DIR}")
+    target_include_directories(${target} PRIVATE "${ARG_SOURCE_DIR}/swig" ${ARG_INCLUDE})
+    if(TARGET Python3::Module)
+        target_link_libraries(${target} PRIVATE ${ARG_LINK} Python3::Module)
+    else()
+        target_include_directories(${target} PRIVATE ${Python3_INCLUDE_DIRS})
+        target_link_libraries(${target} PRIVATE ${ARG_LINK} ${Python3_LIBRARIES})
+    endif()
+endfunction()

libe3py-0.2.3/pyproject.toml

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Northeastern University
+# SPDX-License-Identifier: Apache-2.0
+#
+# libe3py: the Python binding of libe3, built against the libe3 installed on the
+# machine (see python/CMakeLists.txt). Install libe3 first, then `pip install libe3py`.
+[build-system]
+requires = ["scikit-build-core>=0.8", "swig>=4.0"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "libe3py"
+dynamic = ["version"]
+description = "Python binding of libe3, the O-RAN E3 interface library"
+readme = "python/README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Northeastern University" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: C++",
+    "Operating System :: POSIX :: Linux",
+]
+
+[project.urls]
+Homepage = "https://github.com/wineslab/libe3"
+Documentation = "https://github.com/wineslab/libe3/blob/main/swig/README.md"
+
+[tool.scikit-build]
+cmake.version = ">=3.18"
+cmake.build-type = "Release"
+cmake.source-dir = "python"
+build-dir = "build/{wheel_tag}"
+wheel.packages = []
+sdist.exclude = ["*"]
+sdist.include = [
+    "VERSION", "LICENSE", "NOTICE", "pyproject.toml",
+    "python/**", "swig/**", "cmake/libe3SwigModule.cmake",
+]
+
+[tool.scikit-build.metadata.version]
+provider = "scikit_build_core.metadata.regex"
+input = "VERSION"
+regex = "^(?P<value>\\d+\\.\\d+\\.\\d+)"

libe3py-0.2.3/python/CMakeLists.txt

@@ -0,0 +1,59 @@
+# libe3py, the Python binding of libe3, built by pip (scikit-build-core, see
+# ../pyproject.toml) against the libe3 already installed on the machine:
+#
+#   sudo ./build_libe3 --all-encodings --install    # once
+#   pip install libe3py                             # or: pip install . from the checkout
+#
+# The module is compiled from the same SWIG sources as the in-tree build and links
+# the installed static libe3, with the feature macros (encodings, latrec) that
+# libe3 was built with. It refuses an installed libe3 of another version, so the
+# binding and the library always match.
+#
+# SPDX-FileCopyrightText: Copyright (c) 2026 Northeastern University
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.18)
+
+set(LIBE3_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/..")
+file(READ "${LIBE3_SOURCE_DIR}/VERSION" LIBE3PY_VERSION)
+string(STRIP "${LIBE3PY_VERSION}" LIBE3PY_VERSION)
+
+project(libe3py VERSION ${LIBE3PY_VERSION} LANGUAGES CXX)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(libe3 CONFIG QUIET)
+if(NOT libe3_FOUND)
+    message(FATAL_ERROR
+        "libe3py ${LIBE3PY_VERSION} is built against an installed libe3, and none was found.\n"
+        "Install libe3 ${LIBE3PY_VERSION} first (https://github.com/wineslab/libe3):\n"
+        "  git clone --branch ${LIBE3PY_VERSION} https://github.com/wineslab/libe3 && cd libe3\n"
+        "  ./build_libe3 -I && ./build_libe3 --all-encodings --install\n"
+        "For a libe3 outside /usr and /usr/local, pass its prefix: "
+        "pip install libe3py --config-settings=cmake.define.CMAKE_PREFIX_PATH=<prefix>")
+endif()
+if(NOT libe3_VERSION VERSION_EQUAL LIBE3PY_VERSION)
+    message(FATAL_ERROR
+        "The installed libe3 is ${libe3_VERSION} (${libe3_DIR}), but this is libe3py ${LIBE3PY_VERSION}.\n"
+        "Install the libe3py that matches it (pip install \"libe3py==${libe3_VERSION}\"), or install libe3 ${LIBE3PY_VERSION}.")
+endif()
+message(STATUS "Building libe3py ${LIBE3PY_VERSION} against libe3 ${libe3_VERSION} from ${libe3_DIR}")
+
+list(APPEND CMAKE_MODULE_PATH "${LIBE3_SOURCE_DIR}/cmake")
+include(libe3SwigModule)
+
+get_target_property(_libe3_inc libe3::libe3 INTERFACE_INCLUDE_DIRECTORIES)
+set(_out "${CMAKE_CURRENT_BINARY_DIR}/swig")
+libe3_add_python_module(libe3py
+    SOURCE_DIR "${LIBE3_SOURCE_DIR}"
+    OUTPUT_DIR "${_out}"
+    LINK libe3::libe3
+    INCLUDE ${_libe3_inc})
+
+if(DEFINED SKBUILD_PLATLIB_DIR)
+    set(_dest "${SKBUILD_PLATLIB_DIR}")
+else()
+    set(_dest ".")
+endif()
+install(TARGETS libe3py LIBRARY DESTINATION "${_dest}")
+install(FILES "${_out}/libe3py.py" DESTINATION "${_dest}")

libe3py-0.2.3/python/README.md

@@ -0,0 +1,22 @@
+# libe3py
+
+Python binding of [libe3](https://github.com/wineslab/libe3), the C++ library that implements the O-RAN
+E3 interface between a RAN node and its dApps. The [dApp library](https://github.com/wineslab/dApp-library)
+(`pip install dapps`) uses it for E3AP; see
+[`swig/README.md`](https://github.com/wineslab/libe3/blob/main/swig/README.md) for the API.
+
+libe3py is built when you install it, against the libe3 installed on the machine, and it must be the same
+version. Install libe3 once:
+
+```bash
+git clone --branch <version> https://github.com/wineslab/libe3 && cd libe3
+./build_libe3 -I                         # build dependencies, swig and python3-dev included
+./build_libe3 --all-encodings --install  # into /usr/local, asks for sudo
+```
+
+then, in any virtual environment and without root:
+
+```bash
+pip install libe3py==<version>
+python -c "import libe3py; print(libe3py.__version__)"
+```

libe3py-0.2.3/swig/README.md

@@ -0,0 +1,129 @@
+# libe3 Python bindings (`libe3py`)
+
+SWIG bindings that let Python drive libe3 in the **dApp role**. A Python dApp can
+delete its pure-Python E3AP stack (ZMQ + `asn1tools`) and let libe3 own E3AP on
+both ends of the link — exactly the split OAI already uses on the RAN side. An
+example consumer is available in
+[dApp-library](https://github.com/wineslab/dApp-library).
+
+## The split: E3AP in libe3, E3SM in Python
+
+libe3 owns **E3AP**: transport, the setup handshake, subscribe/unsubscribe,
+indication/control framing, and all wire encodings (ASN.1 / JSON / Protobuf,
+selected at runtime by `E3Config.encoding`). Python owns **E3SM**: the
+service-model payloads ride opaque, as `bytes`, and are encoded/decoded in
+Python. `libe3py` never touches SM contents.
+
+## Two layers
+
+| Symbol | Purpose |
+|--------|---------|
+| `E3Config`, enums (`E3Role`, `E3LinkLayer`, `E3TransportLayer`, `EncodingFormat`, `ResponseCode`, `AgentState`, `ErrorCode`) | Configure a session. |
+| `E3Agent` (minimal view) | Backwards-compatible seam: construct/config/start, push opaque bytes. Kept for the smoke test. |
+| **`DAppSession` + `E3Event`** | The real dApp seam: full lifecycle + a **batched, lock-free inbound queue**. This is what a Python dApp consumes. |
+
+See [`e3_dapp_session.hpp`](e3_dapp_session.hpp) for the authoritative,
+Doxygen-documented API.
+
+## Why batched drain + GIL release (not callbacks)
+
+E3AP runs at real-time sub-millisecond cadence with very high message
+throughput, so the binding must not become the bottleneck. At those rates the
+limiters are the **count of GIL acquisitions**, the **count of Python↔C++
+boundary crossings**, and libe3's C++ worker threads **stalling on the GIL** —
+not payload copy size (E3AP payloads are small; bulk IQ travels out-of-band in
+shared memory).
+
+`DAppSession` therefore:
+
+- registers libe3's C++ handlers itself and pushes each inbound message into a
+  **bounded lock-free ring** (`libe3::LockFreeQueue`), incrementing a drop
+  counter on overflow instead of blocking libe3;
+- exposes **`poll_events(max_batch, timeout_ms)`**, which blocks for the *first*
+  event (latency ≈ ring wakeup) then sweeps up to `max_batch` already-queued
+  events in a single call — amortising one GIL acquire + one boundary crossing
+  across the whole batch;
+- is wrapped with `%module(threads="1")` (see [`libe3.i`](libe3.i)) so the GIL is
+  **released** around every call; libe3's threads run freely while Python waits.
+
+**Rejected alternatives:** SWIG *directors* run the Python callback on libe3's
+inbound thread under the GIL (serialises dispatch, deadlock-prone if Python
+re-enters libe3); a *per-message* poll pays one GIL round-trip per message and
+caps throughput with no latency benefit over batching.
+
+## Lifecycle
+
+```
+DAppSession(cfg)          # ctor registers all inbound handlers
+  → start()               # connects; begins the handshake
+  → wait_for_setup(ms)    # blocks until setup completes
+  → dapp_id() / setup_ran_function_*()   # read what the RAN advertised
+  → subscribe(rfid, telemetry, control, sub_time, periodicity)
+  → loop:
+      for ev in poll_events(max_batch, timeout_ms):
+          dispatch(ev)                 # E3_EVENT_INDICATION / _XAPP_CONTROL / ...
+      send_control(rfid, cid, payload_bytes)   # or send_report(...)
+  → release()             # tell the RAN we are leaving
+  → stop()                # tear down; unblocks any poll_events
+```
+
+## Minimal Python example
+
+```python
+import libe3py as e3
+
+cfg = e3.E3Config()
+cfg.role = e3.E3Role_DAPP
+cfg.link_layer = e3.E3LinkLayer_ZMQ
+cfg.transport_layer = e3.E3TransportLayer_IPC
+cfg.encoding = e3.EncodingFormat_ASN1        # must match the RAN's E3Configuration
+cfg.dapp_name = "MyDApp"
+
+s = e3.DAppSession(cfg)
+assert s.start() == 0                          # ErrorCode.SUCCESS
+assert s.wait_for_setup(6000) == 0
+print("dApp id:", s.dapp_id())
+
+# Enumerate what the RAN advertised in the SetupResponse.
+for i in range(s.setup_ran_function_count()):
+    rfid = s.setup_ran_function_id(i)
+    ran_function_data = s.setup_ran_function_data(i)   # opaque bytes -> decode in Python
+
+s.subscribe(1, [1], [1], -1, -1)               # RAN function 1, telemetry {1}, control {1}
+
+while True:
+    for ev in s.poll_events(256, 100):         # drain up to 256 per wake, 100ms wait
+        if ev.kind == e3.E3_EVENT_INDICATION:
+            handle(ev.ran_function_id, ev.get_payload())   # get_payload() -> native bytes
+        elif ev.kind == e3.E3_EVENT_SUBSCRIPTION_RESPONSE:
+            ...
+    # send an SM-encoded control back when needed:
+    # s.send_control(1, 1, sm_encode(...))
+```
+
+## Build & install
+
+Install libe3 once (`./build_libe3 --all-encodings --install`, see the main README), then the binding
+with pip, in any virtual environment:
+
+```bash
+pip install libe3py            # or, from the libe3 checkout: pip install .
+python -c "import libe3py; print('libe3py OK', libe3py.__version__)"
+```
+
+pip builds the module from these sources against the installed libe3 (`python/CMakeLists.txt`); it
+needs `swig >= 4.0`, the Python headers and a C++17 compiler (`./build_libe3 -I` installs them), and it
+stops with an error if the installed libe3 is not the same version. For a libe3 outside `/usr` and
+`/usr/local`: `pip install libe3py --config-settings=cmake.define.CMAKE_PREFIX_PATH=<prefix>`.
+
+For development, `./build_libe3 --enable-swig` builds the module in `build/swig` (run the smoke test with
+`PYTHONPATH=build/swig python3 tests/test_swig_smoke.py`); `cmake --install` installs it only if
+`-DLIBE3_PYTHON_INSTALL_DIR=<dir>` is given.
+
+## Service-model definitions
+
+The Simple SM grammar is installed alongside the library under
+`<datadir>/libe3/sm/sm_simple/` — both `e3sm_simple.asn` (ASN.1) and
+`e3sm_simple.proto` (Protobuf) — discoverable via
+`pkg-config --variable=smdir libe3`, so Python dApps can reuse the exact grammar
+their C++ counterpart (`examples/simple_agent.cpp`) uses instead of copying it.