| Name | ipyrf JSON |
| Version |
1.1.1
JSON |
| download |
| home_page | None |
| Summary | A tiny iperf3-like tool with JSON output (TCP/UDP) |
| upload_time | 2025-10-22 12:25:46 |
| maintainer | None |
| docs_url | None |
| author | Steinwurf ApS |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Steinwurf
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
network
iperf
throughput
udp
tcp
benchmark
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
ipyrf
=====
Minimal iperf3-like network throughput tool with JSON output. Supports TCP and UDP, server and client modes.
Features
--------
- TCP and UDP tests
- JSON or human-readable output
- Optional bandwidth capping (TCP/UDP)
- UDP packet loss estimation
- Linux TCP congestion control selection (if available)
Installation
------------
From PyPI (recommended):
.. code-block:: bash
python3 -m pip install ipyrf
From source (editable):
.. code-block:: bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -U pip build
python3 -m pip install -e .
Test Utilities (ipyrf.test)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``ipyrf.test`` module provides test utilities for writing your own tests:
.. code-block:: python
from ipyrf.test import IPyrfBuilder, CheckCriteria
def test_my_network(testdirectory):
builder = IPyrfBuilder(testdirectory)
port = 12345
server = builder.build()
client = builder.build()
server.run_tcp_server("127.0.0.1", port)
client.run_tcp_client("127.0.0.1", port, duration=2)
# Check with custom criteria
builder.check(
(server, client),
timeout=5,
criteria={"min_bps": 1000000}
)
Available classes and functions:
- ``IPyrfClient``: Run and monitor ipyrf instances
- ``IPyrfBuilder``: Builder pattern for creating test instances
- ``CheckCriteria``: Configurable criteria for evaluating test results
See ``examples/using_test_utilities.py`` for more examples.
Running Tests
~~~~~~~~~~~~~
The project includes a comprehensive test suite using pytest:
.. code-block:: bash
# Run all tests
python3 waf --run_tests
Usage
-----
The package installs a console script named ``ipyrf``.
Quick examples
~~~~~~~~~~~~~~
TCP server:
.. code-block:: bash
ipyrf tcp server 0.0.0.0 --port 12345
TCP client:
.. code-block:: bash
ipyrf tcp client 127.0.0.1 --port 12345 --time 5
ipyrf tcp client 127.0.0.1 --port 12345 --time 5 --set-mss 1400
UDP server:
.. code-block:: bash
ipyrf udp server 0.0.0.0 --port 12345
UDP client (with bandwidth cap and optional payload size):
.. code-block:: bash
ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5
ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5 -l 1200
Interactive mode
----------------
You can run clients in an interactive mode that lets you adjust the pacing live using your keyboard. Use ``--interactive`` and optionally ``--interval`` (seconds between stats updates). When interactive is enabled, the same client logic is used underneath with a dynamic pacing controller.
Controls shown in the terminal:
- ``←``: -1 Mbps
- ``→``: +1 Mbps
- ``↓``: -10%
- ``↑``: +10%
- ``0``: reset to initial bandwidth (or unlimited for TCP if none was provided)
- ``u``: unlimited (disable pacing)
- ``q``: quit
Examples:
.. code-block:: bash
# TCP interactive (unlimited unless you pass --bandwidth)
ipyrf tcp client 127.0.0.1 --port 5201 --interactive
# TCP interactive with initial pacing and custom interval
ipyrf tcp client 127.0.0.1 --port 5201 --bandwidth 200M --set-mss 1400 --interactive --interval 0.5
# UDP interactive (requires initial --bandwidth)
ipyrf udp client 127.0.0.1 --port 5201 --bandwidth 50M -l 1200 --interactive
CLI overview
------------
Top-level structure:
.. code-block:: text
ipyrf [tcp|udp] [server|client] [OPTIONS]
Common options (both protocols, both roles):
- ``--port``: Port (default 5201)
- ``--logfile``: Redirect output to a file
- ``--json_log``: Emit logs in JSON (newline-delimited)
TCP-specific options:
- ``tcp server ADDRESS``: Start a TCP server on ``ADDRESS``
- ``tcp client ADDRESS``: Start a TCP client to connect to ``ADDRESS``
- ``--congestion-control``: Select Linux TCP CC algorithm if available
- ``--time``: Test duration (seconds), default 10
- ``--bandwidth``: Target rate (e.g., ``50M``); used for pacing, optional
- ``--set-mss``: Set approximate MSS via ``TCP_MAXSEG``
- ``--interactive``: Enable interactive pacing controls
- ``--interval``: Stats interval in seconds for interactive mode (default 1.0)
UDP-specific options:
- ``udp server ADDRESS``: Start a UDP server on ``ADDRESS``
- ``udp client ADDRESS``: Start a UDP client to ``ADDRESS``
- ``--time``: Test duration (seconds), default 10
- ``--bandwidth``: Target rate (required for UDP client; e.g., ``50M``)
- ``-l/--length``: UDP payload length (default 1200)
- ``--interactive``: Enable interactive pacing controls
- ``--interval``: Stats interval in seconds for interactive mode (default 1.0)
JSON logging
------------
Add ``--json_log`` to switch all output to newline-delimited JSON objects. This is useful for machine parsing or dashboards. Example:
.. code-block:: bash
ipyrf tcp client 127.0.0.1 --time 5 --json_log | jq
Notes
-----
- Output is JSON (newline-delimited for update events) when ``--json_log`` is given; otherwise, a human-readable summary is printed.
- UDP mode sends a FIN marker at the end and the server exits after FIN (or inactivity timeout).
- On Linux, congestion control selection is exposed if ``/proc`` entries are available.
License
-------
MIT. See ``LICENSE``.
Raw data
{
"_id": null,
"home_page": null,
"name": "ipyrf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "network, iperf, throughput, udp, tcp, benchmark",
"author": "Steinwurf ApS",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a4/4f/9523f1d77cfe4f229823f6c653fe80a11517c0a4d6f25f4c9f7850ef50ee/ipyrf-1.1.1.tar.gz",
"platform": null,
"description": "ipyrf\n=====\n\nMinimal iperf3-like network throughput tool with JSON output. Supports TCP and UDP, server and client modes.\n\nFeatures\n--------\n- TCP and UDP tests\n- JSON or human-readable output\n- Optional bandwidth capping (TCP/UDP)\n- UDP packet loss estimation\n- Linux TCP congestion control selection (if available)\n\nInstallation\n------------\n\nFrom PyPI (recommended):\n\n.. code-block:: bash\n\n python3 -m pip install ipyrf\n\nFrom source (editable):\n\n.. code-block:: bash\n\n python3 -m venv .venv\n source .venv/bin/activate\n python3 -m pip install -U pip build\n python3 -m pip install -e .\n\nTest Utilities (ipyrf.test)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ``ipyrf.test`` module provides test utilities for writing your own tests:\n\n.. code-block:: python\n\n from ipyrf.test import IPyrfBuilder, CheckCriteria\n\n def test_my_network(testdirectory):\n builder = IPyrfBuilder(testdirectory)\n port = 12345\n\n server = builder.build()\n client = builder.build()\n\n server.run_tcp_server(\"127.0.0.1\", port)\n client.run_tcp_client(\"127.0.0.1\", port, duration=2)\n\n # Check with custom criteria\n builder.check(\n (server, client),\n timeout=5,\n criteria={\"min_bps\": 1000000}\n )\n\nAvailable classes and functions:\n\n- ``IPyrfClient``: Run and monitor ipyrf instances\n- ``IPyrfBuilder``: Builder pattern for creating test instances\n- ``CheckCriteria``: Configurable criteria for evaluating test results\n\nSee ``examples/using_test_utilities.py`` for more examples.\n\nRunning Tests\n~~~~~~~~~~~~~\n\nThe project includes a comprehensive test suite using pytest:\n\n.. code-block:: bash\n\n # Run all tests\n python3 waf --run_tests\n\nUsage\n-----\n\nThe package installs a console script named ``ipyrf``.\n\nQuick examples\n~~~~~~~~~~~~~~\n\nTCP server:\n\n.. code-block:: bash\n\n ipyrf tcp server 0.0.0.0 --port 12345\n\nTCP client:\n\n.. code-block:: bash\n\n ipyrf tcp client 127.0.0.1 --port 12345 --time 5\n ipyrf tcp client 127.0.0.1 --port 12345 --time 5 --set-mss 1400\n\nUDP server:\n\n.. code-block:: bash\n\n ipyrf udp server 0.0.0.0 --port 12345\n\nUDP client (with bandwidth cap and optional payload size):\n\n.. code-block:: bash\n\n ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5\n ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5 -l 1200\n\nInteractive mode\n----------------\n\nYou can run clients in an interactive mode that lets you adjust the pacing live using your keyboard. Use ``--interactive`` and optionally ``--interval`` (seconds between stats updates). When interactive is enabled, the same client logic is used underneath with a dynamic pacing controller.\n\nControls shown in the terminal:\n\n- ``\u2190``: -1 Mbps\n- ``\u2192``: +1 Mbps\n- ``\u2193``: -10%\n- ``\u2191``: +10%\n- ``0``: reset to initial bandwidth (or unlimited for TCP if none was provided)\n- ``u``: unlimited (disable pacing)\n- ``q``: quit\n\nExamples:\n\n.. code-block:: bash\n\n # TCP interactive (unlimited unless you pass --bandwidth)\n ipyrf tcp client 127.0.0.1 --port 5201 --interactive\n\n # TCP interactive with initial pacing and custom interval\n ipyrf tcp client 127.0.0.1 --port 5201 --bandwidth 200M --set-mss 1400 --interactive --interval 0.5\n\n # UDP interactive (requires initial --bandwidth)\n ipyrf udp client 127.0.0.1 --port 5201 --bandwidth 50M -l 1200 --interactive\n\nCLI overview\n------------\n\nTop-level structure:\n\n.. code-block:: text\n\n ipyrf [tcp|udp] [server|client] [OPTIONS]\n\nCommon options (both protocols, both roles):\n\n- ``--port``: Port (default 5201)\n- ``--logfile``: Redirect output to a file\n- ``--json_log``: Emit logs in JSON (newline-delimited)\n\nTCP-specific options:\n\n- ``tcp server ADDRESS``: Start a TCP server on ``ADDRESS``\n- ``tcp client ADDRESS``: Start a TCP client to connect to ``ADDRESS``\n- ``--congestion-control``: Select Linux TCP CC algorithm if available\n- ``--time``: Test duration (seconds), default 10\n- ``--bandwidth``: Target rate (e.g., ``50M``); used for pacing, optional\n- ``--set-mss``: Set approximate MSS via ``TCP_MAXSEG``\n- ``--interactive``: Enable interactive pacing controls\n- ``--interval``: Stats interval in seconds for interactive mode (default 1.0)\n\nUDP-specific options:\n\n- ``udp server ADDRESS``: Start a UDP server on ``ADDRESS``\n- ``udp client ADDRESS``: Start a UDP client to ``ADDRESS``\n- ``--time``: Test duration (seconds), default 10\n- ``--bandwidth``: Target rate (required for UDP client; e.g., ``50M``)\n- ``-l/--length``: UDP payload length (default 1200)\n- ``--interactive``: Enable interactive pacing controls\n- ``--interval``: Stats interval in seconds for interactive mode (default 1.0)\n\nJSON logging\n------------\n\nAdd ``--json_log`` to switch all output to newline-delimited JSON objects. This is useful for machine parsing or dashboards. Example:\n\n.. code-block:: bash\n\n ipyrf tcp client 127.0.0.1 --time 5 --json_log | jq\n\nNotes\n-----\n\n- Output is JSON (newline-delimited for update events) when ``--json_log`` is given; otherwise, a human-readable summary is printed.\n- UDP mode sends a FIN marker at the end and the server exits after FIN (or inactivity timeout).\n- On Linux, congestion control selection is exposed if ``/proc`` entries are available.\n\nLicense\n-------\n\nMIT. See ``LICENSE``.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Steinwurf\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n \n \n ",
"summary": "A tiny iperf3-like tool with JSON output (TCP/UDP)",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/steinwurf/ipyrf",
"Issues": "https://github.com/steinwurf/ipyrf/issues",
"Repository": "https://github.com/steinwurf/ipyrf"
},
"split_keywords": [
"network",
" iperf",
" throughput",
" udp",
" tcp",
" benchmark"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9a9936e7be2f63e85ae1ae5601b0666a21e85eab5e6dd1ce09f45515fc0b6cc7",
"md5": "522240dd9593f72420dc776d0875c919",
"sha256": "203175535ecfbea8f42edb8f4290f352a24edad3fb787fd7703b73bc2a3a9be2"
},
"downloads": -1,
"filename": "ipyrf-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "522240dd9593f72420dc776d0875c919",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20656,
"upload_time": "2025-10-22T12:25:45",
"upload_time_iso_8601": "2025-10-22T12:25:45.572831Z",
"url": "https://files.pythonhosted.org/packages/9a/99/36e7be2f63e85ae1ae5601b0666a21e85eab5e6dd1ce09f45515fc0b6cc7/ipyrf-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a44f9523f1d77cfe4f229823f6c653fe80a11517c0a4d6f25f4c9f7850ef50ee",
"md5": "8e86aa23b7cfec102942a66e49cb6e6b",
"sha256": "0feac50faa37c163e5a93100c28e372c250a0a4b215e7ddb6bab1526f94631bc"
},
"downloads": -1,
"filename": "ipyrf-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "8e86aa23b7cfec102942a66e49cb6e6b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20739,
"upload_time": "2025-10-22T12:25:46",
"upload_time_iso_8601": "2025-10-22T12:25:46.985527Z",
"url": "https://files.pythonhosted.org/packages/a4/4f/9523f1d77cfe4f229823f6c653fe80a11517c0a4d6f25f4c9f7850ef50ee/ipyrf-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 12:25:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "steinwurf",
"github_project": "ipyrf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ipyrf"
}
