Implement Pure Python AVL Tree Backend, Update Benchmarks & Myths FAQ by AnshMNSoni · Pull Request #21 · AnshMNSoni/PythonSTL

AnshMNSoni · 2026-07-01T09:29:03Z

Description

This PR resolves the behavioral inconsistency and benchmarking discrepancy between the C++ (Rust-compiled) backend and the pure Python fallback backend for sorted containers (stl_set and stl_map).

Problem

Previously, the Python implementations wrapped built-in set and dict objects. Because Python's built-ins are hash tables, they offered O(1) complexity and unordered iteration, whereas the Rust/C++ implementations used B-Trees with O(log n) complexity and sorted iteration. This resulted in behavioral inconsistencies (elements were sorted when Rust was compiled, but unsorted when it fell back to Python) and an unequal "apples-to-oranges" benchmark comparison.

Solution

AVL Tree Implementation: Created a core self-balancing AVL Tree in pure Python to serve as the fallback backend for both set and map containers.
Backend Unification: Modified the private set and map implementation wrappers to use this AVL tree, ensuring O(log n) time complexity and sorted iteration on both Rust and Python backends.
3-Way Benchmark: Expanded the benchmark script to support a three-way comparison (Rust Backend vs. Pure Python Backend vs. Native Python Built-ins) to clearly document FFI boundary crossing costs and algorithmic tradeoffs.
README FAQ: Updated the README to address common myths regarding project utility (competitive programming compatibility) and the systems design benefits of the hybrid Rust-Python architecture.
Version Bump: Bumped versioning to 1.1.7 across configuration files.

Changes

[NEW] pythonstl/core/avl_tree.py: Self-balancing BST containing node insertion, balancing, deletions, and sorted in-order iterators.
[MODIFY] pythonstl/implementations/associative/_set_impl.py: Replaced native set fallback with AVLTree.
[MODIFY] pythonstl/implementations/associative/_map_impl.py: Replaced native dict fallback with AVLTree.
[MODIFY] benchmarks/benchmark_all_structures.py: Added native built-in baseline and expanded the summary reporting table.
[MODIFY] README.md: Added the 3-way container benchmark table and the Myths & Common Misconceptions FAQ.
[MODIFY] pythonstl/init.py & pyproject.toml: Bumped version to 1.1.7.

Verification

Added test cases in tests/test_set.py and tests/test_map.py to verify that both backends maintain elements in sorted order.
Ran pytest suite: All 83 tests passed successfully.

deepsource-io · 2026-07-01T09:29:15Z

DeepSource Code Review

We reviewed changes in dfd1cb2...623d428 on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade	Security Reliability Complexity Hygiene

Code Review Summary

Analyzer	Updated (UTC)	Details
C & C++	Jul 1, 2026 9:29a.m.	Review ↗
Rust	Jul 1, 2026 9:29a.m.	Review ↗
Python	Jul 1, 2026 9:29a.m.	Review ↗

Important

AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.

deepsource-io · 2026-07-01T09:30:07Z

+        self.height: int = 1
+
+
+class AVLTree(Generic[K, V]):


Implementing __eq__ without also implementing __hash__

In order to conform to the object model, classes that define their own equality method should also define their own hash method, or be unhashable. If the hash method is not defined then the hash of the super class is used. This is unlikely to result in the expected behavior. A class can be made unhashable by setting its __hash__ attribute to None.

deepsource-io · 2026-07-01T09:30:07Z

+        """Check if a key exists in the tree."""
+        return self._find(self.root, key) is not None
+
+    def _find(self, node: Optional[AVLNode[K, V]], key: K) -> Optional[AVLNode[K, V]]:


Method doesn't use the class instance and could be converted into a static method

The method doesn't use its bound instance. Decorate this method with @staticmethod decorator, so that Python does not have to instantiate a bound method for every instance of this class thereby saving memory and computation. Read more about staticmethods here.

deepsource-io · 2026-07-01T09:30:07Z

+            raise KeyError(key)
+        return node.value
+
+    def _get_height(self, node: Optional[AVLNode[K, V]]) -> int:


Method doesn't use the class instance and could be converted into a static method

The method doesn't use its bound instance. Decorate this method with @staticmethod decorator, so that Python does not have to instantiate a bound method for every instance of this class thereby saving memory and computation. Read more about staticmethods here.

deepsource-io · 2026-07-01T09:30:07Z

+        """Insert or update a key-value pair in the tree."""
+        self.root = self._insert(self.root, key, value)
+
+    def _insert(self, node: Optional[AVLNode[K, V]], key: K, value: V) -> AVLNode[K, V]:


`AVLTree._insert` has a cyclomatic complexity of 16 with "high" risk

A function with high cyclomatic complexity can be hard to understand and
maintain. Cyclomatic complexity is a software metric that measures the number of
independent paths through a function. A higher cyclomatic complexity indicates
that the function has more decision points and is more complex.

deepsource-io · 2026-07-01T09:30:07Z

+        if key in self:
+            self.root = self._delete(self.root, key)
+
+    def _min_value_node(self, node: AVLNode[K, V]) -> AVLNode[K, V]:


Method doesn't use the class instance and could be converted into a static method

The method doesn't use its bound instance. Decorate this method with @staticmethod decorator, so that Python does not have to instantiate a bound method for every instance of this class thereby saving memory and computation. Read more about staticmethods here.

deepsource-io · 2026-07-01T09:30:07Z

        assert m.at(2) == "two"
        assert m.find(3) is True
+
+    def test_sorted_order(self):


Method doesn't use the class instance and could be converted into a static method

The method doesn't use its bound instance. Decorate this method with @staticmethod decorator, so that Python does not have to instantiate a bound method for every instance of this class thereby saving memory and computation. Read more about staticmethods here.

deepsource-io · 2026-07-01T09:30:07Z

        s.erase("banana")
        assert s.find("banana") is False
+
+    def test_sorted_order(self):


Method doesn't use the class instance and could be converted into a static method

The method doesn't use its bound instance. Decorate this method with @staticmethod decorator, so that Python does not have to instantiate a bound method for every instance of this class thereby saving memory and computation. Read more about staticmethods here.

AnshMNSoni added 2 commits July 1, 2026 14:52

add(myths)

4c22367

bump: version to 1.1.7

623d428

AnshMNSoni self-assigned this Jul 1, 2026

AnshMNSoni added bug Something isn't working enhancement New feature or request labels Jul 1, 2026

deepsource-io Bot reviewed Jul 1, 2026

View reviewed changes

AnshMNSoni merged commit 257943b into main Jul 1, 2026
5 of 6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Implement Pure Python AVL Tree Backend, Update Benchmarks & Myths FAQ#21

Implement Pure Python AVL Tree Backend, Update Benchmarks & Myths FAQ#21
AnshMNSoni merged 2 commits into
mainfrom
v1.1.7

AnshMNSoni commented Jul 1, 2026

Uh oh!

deepsource-io Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

deepsource-io Bot Jul 1, 2026

Uh oh!

deepsource-io Bot Jul 1, 2026

Uh oh!

deepsource-io Bot Jul 1, 2026

Uh oh!

deepsource-io Bot Jul 1, 2026

Uh oh!

deepsource-io Bot Jul 1, 2026

Uh oh!

deepsource-io Bot Jul 1, 2026

Uh oh!

deepsource-io Bot Jul 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

AnshMNSoni commented Jul 1, 2026

Description

Problem

Solution

Changes

Verification

Uh oh!

deepsource-io Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DeepSource Code Review

PR Report Card

Code Review Summary

Uh oh!

deepsource-io Bot Jul 1, 2026

Choose a reason for hiding this comment

Implementing __eq__ without also implementing __hash__

Uh oh!

deepsource-io Bot Jul 1, 2026

Choose a reason for hiding this comment

Method doesn't use the class instance and could be converted into a static method

Uh oh!

deepsource-io Bot Jul 1, 2026

Choose a reason for hiding this comment

Method doesn't use the class instance and could be converted into a static method

Uh oh!

deepsource-io Bot Jul 1, 2026

Choose a reason for hiding this comment

`AVLTree._insert` has a cyclomatic complexity of 16 with "high" risk

Uh oh!

deepsource-io Bot Jul 1, 2026

Choose a reason for hiding this comment

Method doesn't use the class instance and could be converted into a static method

Uh oh!

deepsource-io Bot Jul 1, 2026

Choose a reason for hiding this comment

Method doesn't use the class instance and could be converted into a static method

Uh oh!

deepsource-io Bot Jul 1, 2026

Choose a reason for hiding this comment

Method doesn't use the class instance and could be converted into a static method

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

deepsource-io Bot commented Jul 1, 2026 •

edited

Loading

Implementing eq without also implementing hash