py-radix

Common errors

• ModuleNotFoundError: No module named 'radix'

  cause The `py-radix` package was not successfully installed, or the Python environment where it was installed is not active. The Python import statement uses `import radix` while the PyPI package name is `py-radix`.
  fix Ensure `py-radix` is installed in your active Python environment by running `pip install py-radix`. If using virtual environments, ensure your environment is activated.

• ERROR: Command errored out with exit status 1: ... Building wheel for py-radix (pyproject.toml) did not run successfully.

  cause This error typically indicates that the C extension part of `py-radix` failed to compile. This can be due to missing C development tools (e.g., GCC on Linux, Visual C++ build tools on Windows) or incompatibilities with newer Python versions or compilers.
  fix Install the necessary C build tools for your operating system. For Linux, this often involves `sudo apt-get install build-essential` (Debian/Ubuntu) or equivalent. For Windows, install 'Desktop development with C++' from Visual Studio Installer. As a workaround, you can install the pure Python version by setting `RADIX_NO_EXT=1` before installation: `RADIX_NO_EXT=1 pip install py-radix`.

Warnings

• breaking Installation issues observed with Python 3.13+ and GCC 14+ due to stricter type checking during the C extension compilation. While recent versions (1.1.0) include support for Python 3.14's free-threaded build, specific compiler/Python combinations may still face compilation errors.
  Fix: Ensure C build tools are properly installed for your system. If encountering persistent build errors, particularly on newer Python versions, try setting the environment variable `RADIX_NO_EXT=1` before `pip install py-radix` to force installation of the pure Python version (though this may have performance implications). Check the GitHub issues for specific patches or workarounds for your environment.
• gotcha Modifying the Radix tree (adding or deleting nodes) while iterating over it can lead to a `RuntimeWarning` and abort the iteration. The internal state of the tree can become inconsistent if structural changes are made during traversal.
  Fix: Avoid adding or deleting nodes within a `for rnode in rtree:` loop. If you need to modify the tree based on its contents, collect the necessary modifications and apply them after the iteration completes. Modifying a node's `data` dictionary during iteration is safe.
• gotcha By default, `py-radix` attempts to build a C extension for performance. If C compilation fails (e.g., missing build tools, incompatible compiler), the installation might error out.
  Fix: To bypass C extension compilation and install the pure Python version, set the environment variable `RADIX_NO_EXT=1` before running `pip install py-radix`. Example: `RADIX_NO_EXT=1 pip install py-radix`.

Install

• pip install py-radix Latest stable version

Imports

• Radix

  import radix

  The top-level package name for import is 'radix', not 'py_radix' or 'py-radix'.

Quickstart

This quickstart demonstrates how to create a Radix tree, add IPv4 and IPv6 network prefixes with associated data, and perform exact and best-match lookups. It also shows how to iterate through all stored nodes.

import radix

# Create a new tree
rtree = radix.Radix()

# Add nodes. Adding a node returns a RadixNode object.
# You can store arbitrary data in its 'data' dict.
rnode = rtree.add("10.0.0.0/8")
rnode.data["description"] = "Internal Network A"

# You can also specify networks using separate network and masklen, or packed binary addresses.
rnode = rtree.add(network="172.16.0.0", masklen=24)
rnode.data["location"] = "Branch Office"

# IPv6 prefixes are fully supported
rtree.add("2001:DB8::/32")

# Exact search returns a RadixNode if the prefix exists
found_node = rtree.search_exact("10.0.0.0/8")
if found_node:
    print(f"Found exact match: {found_node.prefix}, Data: {found_node.data}")

# Best-match search returns the longest matching prefix
best_match = rtree.search_best("10.0.0.123")
if best_match:
    print(f"Best match for 10.0.0.123: {best_match.prefix}, Data: {best_match.data}")

# Iterate over all nodes in the tree
print("\nAll prefixes in the tree:")
for node in rtree:
    print(node.prefix)