tuberd 0.14__tar.gz

tuberd-0.14/.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$

tuberd-0.14/.gitattributes

@@ -0,0 +1 @@
+.git_archival.txt  export-subst

tuberd-0.14/.github/workflows/black.yml

@@ -0,0 +1,11 @@
+name: Lint
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: psf/black@stable
+

tuberd-0.14/.github/workflows/cmake.yml

@@ -0,0 +1,54 @@
+name: CMake
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+env:
+  CC: gcc-10
+  CXX: g++-10
+  LD_LIBRARY_PATH: /usr/local/lib # this is where libhttpserver installs itself
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Check out libhttpserver dependency
+      uses: actions/checkout@v4
+      with:
+        repository: etr/libhttpserver
+        ref: 0.19.0
+        path: libhttpserver
+
+    - name: Install Python dependencies
+      uses: py-actions/py-dependency-install@v4
+
+    - name: Install C++ dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y libmicrohttpd-dev libfmt-dev pybind11-dev
+
+    - name: Build and install libhttpserver
+      run: |
+        cd libhttpserver
+        ./bootstrap
+        mkdir build
+        cd build
+        ../configure
+        make
+        sudo make install
+
+    - name: Configure CMake
+      run: cmake -B ${{github.workspace}}/build -DCMAKE_MODULE_PATH=/usr/local/share/cmake/Modules
+
+    - name: Build
+      run: cmake --build ${{github.workspace}}/build
+
+    - name: Test
+      working-directory: ${{github.workspace}}/build
+      run: ctest --verbose

tuberd-0.14/.github/workflows/package.yml

@@ -0,0 +1,137 @@
+name: Build
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  release:
+    types: [ published ]
+
+jobs:
+  build_wheels_linux:
+    name: Build wheels for cp3${{ matrix.python_version_minor }}
+    runs-on: ubuntu-20.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python_version_minor: [8, 9, 10, 11, 12]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.${{ matrix.python_version_minor }}
+          architecture: x64
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade patchelf auditwheel
+          ./wheels/install_deps.sh
+
+      - name: Build wheel
+        run: pip wheel . -w wheelhouse -vvv
+
+      - name: Repair wheel
+        run: >
+          auditwheel -v repair ./wheelhouse/tuberd*.whl
+          --exclude libpython3.${{ matrix.python_version_minor }}.so
+          --plat manylinux_2_31_x86_64
+
+      - name: Install wheel for tests
+        run: pip install ./wheelhouse/tuberd*manylinux*.whl
+
+      - name: Run tests
+        run: |
+          cd tests
+          ./test.py --import-mode append
+          ./test.py --import-mode append --orjson-with-numpy
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ runner.os }}-cp3${{ matrix.python_version_minor }}
+          path: ./wheelhouse/tuberd*manylinux*.whl
+
+  build_wheels_osx:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # macos-13 is an intel runner, macos-14 is apple silicon
+          - os: macos-13
+            target: 10.15
+          - os: macos-14
+            target: 11.0
+
+    steps:
+      - name: Set macOS deployment target
+        run: echo "MACOSX_DEPLOYMENT_TARGET=${{ matrix.target }}" >> $GITHUB_ENV
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.20.0
+        env:
+          CIBW_BEFORE_ALL: brew install automake libtool && ./wheels/install_deps.sh
+          CIBW_REPAIR_WHEEL_COMMAND: "delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel} -e Python.framework"
+          CIBW_BUILD_VERBOSITY: 3
+          CIBW_SKIP: cp36-* cp37-* cp313-* cp38-macosx_arm64 pp*
+          CIBW_TEST_COMMAND: >
+            {project}/tests/test.py --import-mode append &&
+            {project}/tests/test.py --import-mode append --orjson-with-numpy
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}
+          path: ./wheelhouse/tuberd*.whl
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  upload_pypi:
+    needs: [build_wheels_linux, build_wheels_osx, build_sdist]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    if: github.event_name == 'release' && github.event.action == 'published'
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          # unpacks all CIBW artifacts into dist/
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tuberd-0.14/.gitignore

@@ -0,0 +1,21 @@
+CMakeFiles/
+CMakeCache.txt
+CTestTestfile.cmake
+DartConfiguration.tcl
+Testing/
+Makefile
+build/
+dist/
+_build/
+_deps/
+_generate/
+cmake_install.cmake
+*.so
+*.py[cod]
+*.egg-info
+*env*
+*.swp
+tuberd
+tuber/_version.py
+Pipfile
+deps/

tuberd-0.14/CHANGES

@@ -0,0 +1,126 @@
+Version 0.14
+============
+
+- CI/CD improvements: builds wheels for manylinux and OS X
+
+Version 0.13
+============
+
+- A "simple" (non-asyncio) client now lives alongside the asyncio client. The
+  points of entry for these are "resolve" and "resolve_simple". They are
+  approximately API-compatible, but the non-asyncio version entirely avoids
+  async code style (async def / await / ...).
+
+- Multiple calls (using a Context or SimpleContext) can now optionally continue
+  after errors, using the continue_on_error flag. When this is True, all calls
+  in a Context/SimpleContext run to completion even if some of them fail.
+  The default behaviour remains the same - when continue_on_error is False,
+  server-side execution proceeds in sequence and halts at the first call that
+  encounters an error.
+
+Version 0.12
+============
+
+- Headers are now properly included in binary builds (.whl files)
+- Corrected PYTHONPATH for "make test"; broken in 0.11.
+
+Version 0.11
+============
+
+- resolve now required (20)
+- tuber package rearranged to tuber.server / tuber.client; registry moved to server (#19)
+- linter (black) added to CI/CD flow (#17)
+- client-side Python packages (aiohttpd) no longer required in server environment (#18)
+- setuptools now builds client and server (#14)
+
+Version 0.10
+============
+
+- Adds support for CBOR as a transport mechanism.
+
+Version 0.9
+===========
+
+- Removes dependency on boost::program_options in favour of getoptA
+- Compatibility fixes for libfmt, libhttpserver, OS X, Clang
+
+Version 0.8
+===========
+
+- Compatibility fix for libfmt
+
+Version 0.7
+===========
+
+Released 2023-12-11
+
+* New features:
+
+  - Added support for warnings.warn calls in server-side code - these are
+    propagated through a "warnings" field in the result object and bubbled up
+    as client-side warnings.
+
+Version 0.6
+===========
+
+Released 2023-02-24
+
+* Fixes:
+
+  - Acquire GIL earlier in response scope, outside "try" block.  Otherwise, the
+    exception path occurs outside the GIL block, and it's not valid to use
+    json_dumps to emit error messages. Fixes a segfault when invalid JSON is
+    supplied.
+
+Version 0.5
+===========
+
+Released 2022-05-24
+
+* Fixes:
+
+  - Correct preamble install path.
+
+Version 0.4
+===========
+
+Released 2022-04-14
+
+* Features:
+
+  - Adds --orjson-with-numpy extension to enable orjson fast-path. This
+    serializer offers significant performance gains, especially when using
+    numpy objects.
+
+Version 0.3
+===========
+
+Released 2022-04-07
+
+* Features:
+
+  - Adds option for use of user-specified JSON module.
+
+Version 0.2
+===========
+
+Released 2022-04-06
+
+* Features:
+
+  - Removes dependency on nlohmann::json. The JSON dependency is intended to
+    speed up serialization. The Python-native JSON serializer is implemented in
+    C under the hood, and should be better able to avoid casual
+    copy-conversions of arguments and results.
+
+  - Adds Python test framework. The test framework is a starting point (it does not exercise unhappy
+    paths or argument variations right now.)
+
+Version 0.1
+===========
+
+Released 2022-04-03
+
+* Features:
+
+   - Initial release.

tuberd-0.14/CMakeLists.txt

@@ -0,0 +1,45 @@
+# Build instructions for tuberd server only.  The client portion is installed
+# via setuptools.
+
+cmake_minimum_required(VERSION 3.16...3.22)
+project(tuberd VERSION 1.0.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17")
+
+# link against deps dir
+if(EXISTS ${CMAKE_SOURCE_DIR}/deps)
+	message(STATUS "Found deps: ${CMAKE_SOURCE_DIR}/deps")
+	list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/deps/share/cmake/Modules")
+	list(APPEND CMAKE_PREFIX_PATH "${CMAKE_SOURCE_DIR}/deps")
+endif()
+
+find_package(Python COMPONENTS Interpreter Development REQUIRED)
+find_package(fmt REQUIRED)
+find_package(LibHttpServer REQUIRED)
+find_package(pybind11 REQUIRED)
+find_package(Threads REQUIRED)
+
+include(CTest)
+
+add_executable(tuberd src/server.cpp)
+target_link_libraries(tuberd PRIVATE fmt::fmt ${LIBHTTPSERVER_LIBRARIES} pybind11::embed Threads::Threads)
+
+pybind11_add_module(test_module MODULE tests/test_module.cpp)
+target_include_directories(test_module PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
+target_link_libraries(test_module PRIVATE fmt::fmt)
+
+add_test(NAME test-native-json
+	WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+	COMMAND tests/test.py)
+
+add_test(NAME test-orjson-fastpath
+	WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+	COMMAND tests/test.py --orjson-with-numpy)
+
+set_tests_properties(test-native-json test-orjson-fastpath
+	PROPERTIES ENVIRONMENT "PATH=${CMAKE_BINARY_DIR}:$ENV{PATH};PYTHONPATH=${CMAKE_BINARY_DIR}:${CMAKE_SOURCE_DIR}")
+
+set_target_properties(tuberd PROPERTIES PUBLIC_HEADER "include/tuber_support.hpp")
+install(TARGETS tuberd PUBLIC_HEADER DESTINATION include)

tuberd-0.14/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2023-2024 Graeme Smecher <gsmecher@threespeedlogic.com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tuberd-0.14/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.1
+Name: tuberd
+Version: 0.14
+Summary: Serve Python (or C++) objects across a LAN using something like JSON-RPC
+Author-email: Graeme Smecher <gsmecher@threespeedlogic.com>
+License: Copyright (c) 2023-2024 Graeme Smecher <gsmecher@threespeedlogic.com>
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its contributors
+           may be used to endorse or promote products derived from this software
+           without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: source, https://github.com/gsmecher/tuberd
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: orjson
+Requires-Dist: pytest
+Requires-Dist: requests
+Requires-Dist: aiohttp
+Requires-Dist: pytest-asyncio
+Requires-Dist: cbor2
+
+.. image:: https://badge.fury.io/py/tuberd.svg
+   :target: https://badge.fury.io/py/tuberd
+
+.. image:: https://github.com/gsmecher/tuberd/actions/workflows/package.yml/badge.svg
+   :target: https://github.com/gsmecher/tuberd/actions/workflows/package.yml
+
+Tuber Server and Client
+=======================
+
+Tuber_ is a C++ server and Python client for exposing an instrumentation
+control plane across a network.
+
+On a client, you can write Python code like this:
+
+.. code:: python
+
+   >>> some_resource.increment([1, 2, 3, 4, 5])
+   [2, 3, 4, 5, 6]
+
+...and end up with a remote method call on a networked resource written in
+Python or (more usually) C++. The C++ implementation might look like this:
+
+.. code:: c++
+
+   class SomeResource {
+   public:
+       std::vector<int> increment(std::vector<int> x) {
+           std::ranges::for_each(x, [](int &n) { n++; });
+           return x;
+       };
+   };
+
+On the client side, Python needs to know where to find the server. On the
+server side, the C++ code must be registered with pybind11 (just as any other
+pybind11 code) and the tuber server.  Other than that, however, there is no
+ceremony and no boilerplate.
+
+Its main features and design principles are:
+
+- Pythonic call styles, including \*args, \*\*kwargs, and DocStrings.
+
+- JSON and CBOR support for efficient and friendly serialization of return
+  values.
+
+- "Less-is-more" approach to code. For example, Tuber uses pybind11_ and C++ as
+  a shim between C and Python, because the combination gives us the shortest
+  and most expressive way to produce the results we want. It pairs excellently
+  with orjson_ (as a JSON interface) or cbor2_ (as a CBOR interface), which
+  efficiently serialize (for example) NumPy_ arrays created in C++ across the
+  network.
+
+- Schema-less RPC using standard-ish protocols (HTTP 1.1, JSON, CBOR, and
+  something like JSON-RPC_). Avoiding a schema allows server and client code to
+  be independently and seamlessly up- and downgraded, with differences between
+  exposed APIs only visible at the sites where RPC calls are made.
+
+- A mature, quick-ish, third-party, low-overhead, low-prerequisite embedded
+  webserver. Tuber uses libhttpserver_, which in turn, is a C++ wrapper around
+  the well-established libmicrohttpd_. We use the thread-per-connection
+  configuration because a single keep-alive connection with a single client is
+  the expected "hot path"; C10K_-style server architectures wouldn't be better.
+
+- High performance when communicating with RPC endpoints, using:
+
+  - HTTP/1.1 Keep-Alive to avoid single-connection-per-request overhead.  See
+    `this Wikipedia page
+    <https://en.wikipedia.org/wiki/HTTP_persistent_connection#HTTP_1.1>`_ for
+    details.
+
+  - A call API that (optionally) allows multiple RPC calls to be combined and
+    dispatched together.
+
+  - Client-side caches for remote properties (server-side constants)
+
+  - Python 3.x's aiohttp_/asyncio_ libraries to asynchronously dispatch across
+    multiple endpoints (e.g. multiple boards in a crate, each of which is an
+    independent Tuber endpoint.)
+
+- A friendly interactive experience using Jupyter_/IPython_-style REPL
+  environments. Tuber servers export metadata that can be used to provide
+  DocStrings and tab-completion for RPC resources.
+
+- The ability to serve a web-based UI using static JavaScript, CSS, and HTML.
+
+Anti-goals of this Tuber server include the following:
+
+- No authentication/encryption is used. For now, network security is strictly
+  out-of-scope. (Yes, it feels naïve to write this in 2022.)
+
+- The additional complexity of HTTP/2 and HTTP/3 protocols are not justified.
+  HTTP/1.1 keep-alive obviates much of the performance gains promised by
+  connection multiplexing.
+
+- The performance gains possible using a binary RPC protocol do not justify the
+  loss of a human-readable, browser-accessible JSON protocol.
+
+- The use of newer, better languages than C++ (server side) or Python (client
+  side).  The instruments Tuber targets are likely to be a polyglot stew, and I
+  am mindful that every additional language or runtime reduces the project's
+  accessibility to newcomers.  Perhaps pybind11_ will be eclipsed by something
+  in Rust one day - for now, the ability to make casual cross-language calls is
+  essential to keeping Tuber small. (Exception: the orjson JSON library is a
+  wonderful complement to tuber and I recommend using them together!)
+
+Although the Tuber server hosts an embedded Python interpreter and can expose
+embedded resources coded in ordinary Python, it is intended to expose C/C++
+code. The Python interpeter provides a convenient, Pythonic approach to
+attribute and method lookup and dispatch without the overhead of a fully
+interpreted embedded runtime.
+
+Tuber is licensed using the 3-clause BSD license (BSD-3-Clause). This software
+is intended to be useful, and its licensing is intended to be pragmatic. If
+licensing is a stumbling block for you, please contact me at
+`gsmecher@threespeedlogic.com <mailto:gsmecher@threespeedlogic.com>`_.
+
+.. _Tuber: https://github.com/gsmecher/tuber
+.. _GPLv3: https://www.gnu.org/licenses/gpl-3.0.en.html
+.. _Jupyter: https://jupyter.org/
+.. _IPython: https://ipython.org/
+.. _libhttpserver: https://github.com/etr/libhttpserver
+.. _NumPy: https://www.numpy.org
+.. _orjson: https://github.com/ijl/orjson
+.. _cbor2: https://github.com/agronholm/cbor2
+.. _libmicrohttpd: https://www.gnu.org/software/libmicrohttpd/
+.. _JSON-RPC: https://www.jsonrpc.org/
+.. _pybind11: https://pybind11.readthedocs.io/en/stable/index.html
+.. _C10K: http://www.kegel.com/c10k.html
+.. _asyncio: https://docs.python.org/3/library/asyncio.html
+.. _aiohttp: https://docs.aiohttp.org/en/stable/
+.. _autoawait: https://ipython.readthedocs.io/en/stable/interactive/autoawait.html
+
+Installation
+------------
+
+Pre-built wheels for Linux and macOS operating systems are available on PyPI for
+CPython 3.8+:
+
+.. code:: bash
+
+   pip install tuberd
+
+Building from source requires the ``libfmt`` and ``libmicrohttpd`` dependencies,
+along with ``libhttpserver``.  To ensure that ``cmake`` can find the
+``libhttpserver`` library, you may need to add the path where the
+``FindLibHttpServer.cmake`` file is installed to the ``CMAKE_MODULE_PATH``
+option, for example:
+
+.. code:: bash
+
+   CMAKE_ARGS="-DCMAKE_MODULE_PATH=/usr/local/share/cmake/Modules" pip install .
+
+To simplify the build process, the ``wheels/install_deps.sh`` script can be used to
+build all the dependencies locally and compile against them.  In this instance,
+``cmake`` should be able to discover the appropriate paths for all dependencies:
+
+.. code:: bash
+
+   ./wheels/install_deps.sh
+   pip install .