exonware-xwnode 0.0.1.13__py3-none-any.whl → 0.0.1.15__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (213) hide show
  1. exonware/__init__.py +1 -1
  2. exonware/xwnode/__init__.py +1 -1
  3. exonware/xwnode/base.py +1 -1
  4. exonware/xwnode/common/__init__.py +20 -0
  5. exonware/xwnode/common/management/__init__.py +26 -0
  6. exonware/xwnode/{strategies → common/management}/manager.py +2 -2
  7. exonware/xwnode/common/monitoring/__init__.py +26 -0
  8. exonware/xwnode/{strategies → common/monitoring}/metrics.py +2 -2
  9. exonware/xwnode/{strategies → common/monitoring}/pattern_detector.py +2 -2
  10. exonware/xwnode/{strategies → common/monitoring}/performance_monitor.py +2 -2
  11. exonware/xwnode/common/patterns/__init__.py +26 -0
  12. exonware/xwnode/{strategies → common/patterns}/advisor.py +1 -1
  13. exonware/xwnode/{strategies → common/patterns}/flyweight.py +4 -4
  14. exonware/xwnode/{strategies → common/patterns}/registry.py +109 -112
  15. exonware/xwnode/common/utils/__init__.py +26 -0
  16. exonware/xwnode/{strategies/edges → edges/strategies}/__init__.py +1 -1
  17. exonware/xwnode/{strategies/edges → edges/strategies}/base.py +3 -3
  18. exonware/xwnode/facade.py +4 -3
  19. exonware/xwnode/{strategies/nodes → nodes/strategies}/__init__.py +1 -1
  20. exonware/xwnode/{strategies/nodes → nodes/strategies}/adjacency_list.py +7 -2
  21. exonware/xwnode/{strategies/nodes → nodes/strategies}/aho_corasick.py +6 -1
  22. exonware/xwnode/{strategies/nodes → nodes/strategies}/array_list.py +6 -1
  23. exonware/xwnode/{strategies/nodes → nodes/strategies}/base.py +24 -4
  24. exonware/xwnode/nodes/strategies/contracts.py +116 -0
  25. exonware/xwnode/{strategies/nodes → nodes/strategies}/deque.py +7 -2
  26. exonware/xwnode/{strategies/nodes → nodes/strategies}/hash_map.py +4 -0
  27. exonware/xwnode/{strategies/nodes → nodes/strategies}/heap.py +6 -1
  28. exonware/xwnode/{strategies/nodes → nodes/strategies}/linked_list.py +6 -1
  29. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_aho_corasick.py +6 -1
  30. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_array_list.py +4 -0
  31. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_avl_tree.py +6 -1
  32. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_b_plus_tree.py +6 -1
  33. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_bitmap.py +6 -1
  34. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_bitset_dynamic.py +6 -1
  35. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_bloom_filter.py +4 -0
  36. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_btree.py +6 -1
  37. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_count_min_sketch.py +4 -0
  38. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_cow_tree.py +6 -1
  39. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_fenwick_tree.py +6 -1
  40. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_hash_map.py +4 -0
  41. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_heap.py +6 -1
  42. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_hyperloglog.py +4 -0
  43. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_linked_list.py +4 -0
  44. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_lsm_tree.py +6 -1
  45. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_ordered_map.py +6 -1
  46. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_ordered_map_balanced.py +6 -1
  47. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_patricia.py +6 -1
  48. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_persistent_tree.py +6 -1
  49. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_radix_trie.py +6 -1
  50. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_red_black_tree.py +6 -1
  51. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_roaring_bitmap.py +6 -1
  52. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_segment_tree.py +6 -1
  53. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_set_hash.py +4 -0
  54. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_set_tree.py +6 -1
  55. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_skip_list.py +6 -1
  56. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_splay_tree.py +6 -1
  57. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_suffix_array.py +6 -1
  58. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_treap.py +6 -1
  59. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_tree_graph_hybrid.py +4 -0
  60. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_trie.py +6 -1
  61. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_union_find.py +6 -1
  62. exonware/xwnode/{strategies/nodes → nodes/strategies}/node_xdata_optimized.py +4 -0
  63. exonware/xwnode/{strategies/nodes → nodes/strategies}/priority_queue.py +7 -2
  64. exonware/xwnode/{strategies/nodes → nodes/strategies}/queue.py +7 -2
  65. exonware/xwnode/{strategies/nodes → nodes/strategies}/sparse_matrix.py +7 -2
  66. exonware/xwnode/{strategies/nodes → nodes/strategies}/stack.py +7 -2
  67. exonware/xwnode/{strategies/nodes → nodes/strategies}/trie.py +6 -1
  68. exonware/xwnode/{strategies/nodes → nodes/strategies}/union_find.py +6 -1
  69. exonware/xwnode/queries/executors/__init__.py +47 -0
  70. exonware/xwnode/queries/executors/advanced/__init__.py +37 -0
  71. exonware/xwnode/queries/executors/advanced/aggregate_executor.py +50 -0
  72. exonware/xwnode/queries/executors/advanced/ask_executor.py +50 -0
  73. exonware/xwnode/queries/executors/advanced/construct_executor.py +50 -0
  74. exonware/xwnode/queries/executors/advanced/describe_executor.py +50 -0
  75. exonware/xwnode/queries/executors/advanced/for_loop_executor.py +50 -0
  76. exonware/xwnode/queries/executors/advanced/foreach_executor.py +50 -0
  77. exonware/xwnode/queries/executors/advanced/join_executor.py +50 -0
  78. exonware/xwnode/queries/executors/advanced/let_executor.py +50 -0
  79. exonware/xwnode/queries/executors/advanced/mutation_executor.py +50 -0
  80. exonware/xwnode/queries/executors/advanced/options_executor.py +50 -0
  81. exonware/xwnode/queries/executors/advanced/pipe_executor.py +50 -0
  82. exonware/xwnode/queries/executors/advanced/subscribe_executor.py +50 -0
  83. exonware/xwnode/queries/executors/advanced/subscription_executor.py +50 -0
  84. exonware/xwnode/queries/executors/advanced/union_executor.py +50 -0
  85. exonware/xwnode/queries/executors/advanced/window_executor.py +51 -0
  86. exonware/xwnode/queries/executors/advanced/with_cte_executor.py +50 -0
  87. exonware/xwnode/queries/executors/aggregation/__init__.py +21 -0
  88. exonware/xwnode/queries/executors/aggregation/avg_executor.py +50 -0
  89. exonware/xwnode/queries/executors/aggregation/count_executor.py +38 -0
  90. exonware/xwnode/queries/executors/aggregation/distinct_executor.py +50 -0
  91. exonware/xwnode/queries/executors/aggregation/group_executor.py +50 -0
  92. exonware/xwnode/queries/executors/aggregation/having_executor.py +50 -0
  93. exonware/xwnode/queries/executors/aggregation/max_executor.py +50 -0
  94. exonware/xwnode/queries/executors/aggregation/min_executor.py +50 -0
  95. exonware/xwnode/queries/executors/aggregation/sum_executor.py +50 -0
  96. exonware/xwnode/queries/executors/aggregation/summarize_executor.py +50 -0
  97. exonware/xwnode/queries/executors/array/__init__.py +9 -0
  98. exonware/xwnode/queries/executors/array/indexing_executor.py +51 -0
  99. exonware/xwnode/queries/executors/array/slicing_executor.py +51 -0
  100. exonware/xwnode/queries/executors/base.py +257 -0
  101. exonware/xwnode/queries/executors/capability_checker.py +204 -0
  102. exonware/xwnode/queries/executors/contracts.py +166 -0
  103. exonware/xwnode/queries/executors/core/__init__.py +17 -0
  104. exonware/xwnode/queries/executors/core/create_executor.py +96 -0
  105. exonware/xwnode/queries/executors/core/delete_executor.py +99 -0
  106. exonware/xwnode/queries/executors/core/drop_executor.py +100 -0
  107. exonware/xwnode/queries/executors/core/insert_executor.py +39 -0
  108. exonware/xwnode/queries/executors/core/select_executor.py +152 -0
  109. exonware/xwnode/queries/executors/core/update_executor.py +102 -0
  110. exonware/xwnode/queries/executors/data/__init__.py +13 -0
  111. exonware/xwnode/queries/executors/data/alter_executor.py +50 -0
  112. exonware/xwnode/queries/executors/data/load_executor.py +50 -0
  113. exonware/xwnode/queries/executors/data/merge_executor.py +50 -0
  114. exonware/xwnode/queries/executors/data/store_executor.py +50 -0
  115. exonware/xwnode/queries/executors/engine.py +221 -0
  116. exonware/xwnode/queries/executors/errors.py +68 -0
  117. exonware/xwnode/queries/executors/filtering/__init__.py +25 -0
  118. exonware/xwnode/queries/executors/filtering/between_executor.py +80 -0
  119. exonware/xwnode/queries/executors/filtering/filter_executor.py +79 -0
  120. exonware/xwnode/queries/executors/filtering/has_executor.py +70 -0
  121. exonware/xwnode/queries/executors/filtering/in_executor.py +70 -0
  122. exonware/xwnode/queries/executors/filtering/like_executor.py +76 -0
  123. exonware/xwnode/queries/executors/filtering/optional_executor.py +76 -0
  124. exonware/xwnode/queries/executors/filtering/range_executor.py +80 -0
  125. exonware/xwnode/queries/executors/filtering/term_executor.py +77 -0
  126. exonware/xwnode/queries/executors/filtering/values_executor.py +71 -0
  127. exonware/xwnode/queries/executors/filtering/where_executor.py +44 -0
  128. exonware/xwnode/queries/executors/graph/__init__.py +15 -0
  129. exonware/xwnode/queries/executors/graph/in_traverse_executor.py +51 -0
  130. exonware/xwnode/queries/executors/graph/match_executor.py +51 -0
  131. exonware/xwnode/queries/executors/graph/out_executor.py +51 -0
  132. exonware/xwnode/queries/executors/graph/path_executor.py +51 -0
  133. exonware/xwnode/queries/executors/graph/return_executor.py +51 -0
  134. exonware/xwnode/queries/executors/ordering/__init__.py +9 -0
  135. exonware/xwnode/queries/executors/ordering/by_executor.py +50 -0
  136. exonware/xwnode/queries/executors/ordering/order_executor.py +51 -0
  137. exonware/xwnode/queries/executors/projection/__init__.py +9 -0
  138. exonware/xwnode/queries/executors/projection/extend_executor.py +50 -0
  139. exonware/xwnode/queries/executors/projection/project_executor.py +50 -0
  140. exonware/xwnode/queries/executors/registry.py +173 -0
  141. exonware/xwnode/queries/executors/types.py +93 -0
  142. exonware/xwnode/queries/parsers/__init__.py +26 -0
  143. exonware/xwnode/queries/parsers/base.py +86 -0
  144. exonware/xwnode/queries/parsers/contracts.py +46 -0
  145. exonware/xwnode/queries/parsers/errors.py +53 -0
  146. exonware/xwnode/queries/parsers/sql_param_extractor.py +318 -0
  147. exonware/xwnode/{strategies/queries → queries/strategies}/__init__.py +1 -1
  148. exonware/xwnode/{strategies/queries → queries/strategies}/base.py +1 -1
  149. exonware/xwnode/{strategies/queries → queries/strategies}/cql.py +1 -1
  150. exonware/xwnode/{strategies/queries → queries/strategies}/cypher.py +1 -1
  151. exonware/xwnode/{strategies/queries → queries/strategies}/datalog.py +1 -1
  152. exonware/xwnode/{strategies/queries → queries/strategies}/elastic_dsl.py +1 -1
  153. exonware/xwnode/{strategies/queries → queries/strategies}/eql.py +1 -1
  154. exonware/xwnode/{strategies/queries → queries/strategies}/flux.py +1 -1
  155. exonware/xwnode/{strategies/queries → queries/strategies}/gql.py +1 -1
  156. exonware/xwnode/{strategies/queries → queries/strategies}/graphql.py +1 -1
  157. exonware/xwnode/{strategies/queries → queries/strategies}/gremlin.py +1 -1
  158. exonware/xwnode/{strategies/queries → queries/strategies}/hiveql.py +1 -1
  159. exonware/xwnode/{strategies/queries → queries/strategies}/hql.py +1 -1
  160. exonware/xwnode/{strategies/queries → queries/strategies}/jmespath.py +1 -1
  161. exonware/xwnode/{strategies/queries → queries/strategies}/jq.py +1 -1
  162. exonware/xwnode/{strategies/queries → queries/strategies}/json_query.py +1 -1
  163. exonware/xwnode/{strategies/queries → queries/strategies}/jsoniq.py +1 -1
  164. exonware/xwnode/{strategies/queries → queries/strategies}/kql.py +1 -1
  165. exonware/xwnode/{strategies/queries → queries/strategies}/linq.py +1 -1
  166. exonware/xwnode/{strategies/queries → queries/strategies}/logql.py +1 -1
  167. exonware/xwnode/{strategies/queries → queries/strategies}/mql.py +1 -1
  168. exonware/xwnode/{strategies/queries → queries/strategies}/n1ql.py +1 -1
  169. exonware/xwnode/{strategies/queries → queries/strategies}/partiql.py +1 -1
  170. exonware/xwnode/{strategies/queries → queries/strategies}/pig.py +1 -1
  171. exonware/xwnode/{strategies/queries → queries/strategies}/promql.py +1 -1
  172. exonware/xwnode/{strategies/queries → queries/strategies}/sparql.py +1 -1
  173. exonware/xwnode/{strategies/queries → queries/strategies}/sql.py +1 -1
  174. exonware/xwnode/{strategies/queries → queries/strategies}/xml_query.py +1 -1
  175. exonware/xwnode/{strategies/queries → queries/strategies}/xpath.py +1 -1
  176. exonware/xwnode/{strategies/queries → queries/strategies}/xquery.py +1 -1
  177. exonware/xwnode/{strategies/queries → queries/strategies}/xwnode_executor.py +1 -1
  178. exonware/xwnode/{strategies/queries → queries/strategies}/xwquery.py +43 -11
  179. exonware/xwnode/strategies/__init__.py +8 -8
  180. exonware/xwnode/version.py +3 -3
  181. {exonware_xwnode-0.0.1.13.dist-info → exonware_xwnode-0.0.1.15.dist-info}/METADATA +2 -3
  182. exonware_xwnode-0.0.1.15.dist-info/RECORD +214 -0
  183. exonware/xwnode/strategies/impls/__init__.py +0 -13
  184. exonware/xwnode/strategies/nodes/_base_node.py +0 -307
  185. exonware_xwnode-0.0.1.13.dist-info/RECORD +0 -132
  186. /exonware/xwnode/{strategies → common/management}/migration.py +0 -0
  187. /exonware/xwnode/{strategies → common/utils}/simple.py +0 -0
  188. /exonware/xwnode/{strategies → common/utils}/utils.py +0 -0
  189. /exonware/xwnode/{strategies/impls → edges/strategies}/_base_edge.py +0 -0
  190. /exonware/xwnode/{strategies/edges → edges/strategies}/adj_list.py +0 -0
  191. /exonware/xwnode/{strategies/edges → edges/strategies}/adj_matrix.py +0 -0
  192. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_adj_list.py +0 -0
  193. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_adj_matrix.py +0 -0
  194. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_bidir_wrapper.py +0 -0
  195. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_block_adj_matrix.py +0 -0
  196. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_coo.py +0 -0
  197. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_csc.py +0 -0
  198. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_csr.py +0 -0
  199. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_dynamic_adj_list.py +0 -0
  200. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_flow_network.py +0 -0
  201. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_hyperedge_set.py +0 -0
  202. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_neural_graph.py +0 -0
  203. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_octree.py +0 -0
  204. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_property_store.py +0 -0
  205. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_quadtree.py +0 -0
  206. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_rtree.py +0 -0
  207. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_temporal_edgeset.py +0 -0
  208. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_tree_graph_basic.py +0 -0
  209. /exonware/xwnode/{strategies/impls → edges/strategies}/edge_weighted_graph.py +0 -0
  210. /exonware/xwnode/{strategies/impls → nodes/strategies}/_base_node.py +0 -0
  211. /exonware/xwnode/{strategies/nodes → nodes/strategies}/node_cuckoo_hash.py +0 -0
  212. {exonware_xwnode-0.0.1.13.dist-info → exonware_xwnode-0.0.1.15.dist-info}/WHEEL +0 -0
  213. {exonware_xwnode-0.0.1.13.dist-info → exonware_xwnode-0.0.1.15.dist-info}/licenses/LICENSE +0 -0
@@ -7,6 +7,7 @@ with fast indexed access.
7
7
 
8
8
  from typing import Any, Iterator, List, Union, Dict
9
9
  from .base import ANodeLinearStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
 
12
13
 
@@ -14,7 +15,11 @@ class ArrayListStrategy(ANodeLinearStrategy):
14
15
  """
15
16
  Array List node strategy for sequential data with O(1) indexed access.
16
17
 
17
- Uses Python's built-in list for optimal performance with indexed operations.
18
+ Uses Python's built-in list for optimal performance
19
+
20
+ # Strategy type classification
21
+ STRATEGY_TYPE = NodeType.LINEAR
22
+ with indexed operations.
18
23
  """
19
24
 
20
25
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -7,12 +7,13 @@ This module defines the abstract base classes for all node strategy implementati
7
7
  - ANodeLinearStrategy: Phase 1 - Linear data structure capabilities
8
8
  - ANodeTreeStrategy: Phase 2 - Tree data structure capabilities
9
9
  - ANodeGraphStrategy: Phase 3&4 - Graph data structure capabilities
10
+ - ANodeMatrixStrategy: Matrix-based data structure capabilities
10
11
 
11
12
  Company: eXonware.com
12
13
  Author: Eng. Muhammad AlShehri
13
14
  Email: connect@exonware.com
14
- Version: 0.0.1.13
15
- Generation Date: January 2, 2025
15
+ Version: 0.0.1.15
16
+ Generation Date: 08-Oct-2025
16
17
  """
17
18
 
18
19
  from abc import ABC, abstractmethod
@@ -20,10 +21,17 @@ from typing import Any, Optional, List, Dict, Iterator
20
21
 
21
22
  from ...contracts import iNodeStrategy
22
23
  from ...errors import XWNodeTypeError, XWNodeValueError
24
+ from .contracts import NodeType
23
25
 
24
26
 
25
- class ANodeStrategy(ABC):
26
- """Base strategy for all node implementations."""
27
+ class ANodeStrategy(iNodeStrategy):
28
+ """Base strategy for all node implementations - extends iNodeStrategy interface."""
29
+
30
+ # Strategy type classification (must be overridden by subclasses)
31
+ STRATEGY_TYPE: NodeType = NodeType.TREE # Default for backward compatibility
32
+
33
+ # Supported operations (empty = all universal operations)
34
+ SUPPORTED_OPERATIONS: List[str] = []
27
35
 
28
36
  def __init__(self, data: Any = None, **options):
29
37
  """Initialize node strategy."""
@@ -74,6 +82,9 @@ class ANodeStrategy(ABC):
74
82
  class ANodeLinearStrategy(ANodeStrategy):
75
83
  """Phase 1: Linear data structure capabilities."""
76
84
 
85
+ # Linear node type
86
+ STRATEGY_TYPE: NodeType = NodeType.LINEAR
87
+
77
88
  def push_front(self, value: Any) -> None:
78
89
  """Add element to front."""
79
90
  raise NotImplementedError("Subclasses must implement push_front")
@@ -119,6 +130,9 @@ class ANodeLinearStrategy(ANodeStrategy):
119
130
  class ANodeGraphStrategy(ANodeStrategy):
120
131
  """Phase 3&4: Graph data structure capabilities."""
121
132
 
133
+ # Graph node type
134
+ STRATEGY_TYPE: NodeType = NodeType.GRAPH
135
+
122
136
  def add_edge(self, from_node: Any, to_node: Any, weight: float = 1.0) -> None:
123
137
  """Add edge between nodes."""
124
138
  raise NotImplementedError("Subclasses must implement add_edge")
@@ -160,6 +174,9 @@ class ANodeGraphStrategy(ANodeStrategy):
160
174
  class ANodeMatrixStrategy(ANodeStrategy):
161
175
  """Matrix-based data structure capabilities."""
162
176
 
177
+ # Matrix node type
178
+ STRATEGY_TYPE: NodeType = NodeType.MATRIX
179
+
163
180
  def get_dimensions(self) -> tuple:
164
181
  """Get matrix dimensions (rows, cols)."""
165
182
  raise NotImplementedError("Subclasses must implement get_dimensions")
@@ -209,6 +226,9 @@ class ANodeMatrixStrategy(ANodeStrategy):
209
226
  class ANodeTreeStrategy(ANodeGraphStrategy):
210
227
  """Phase 2: Tree data structure capabilities."""
211
228
 
229
+ # Tree node type
230
+ STRATEGY_TYPE: NodeType = NodeType.TREE
231
+
212
232
  def insert(self, key: Any, value: Any) -> None:
213
233
  """Insert with tree ordering."""
214
234
  raise NotImplementedError("Subclasses must implement insert")
@@ -0,0 +1,116 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ #exonware/xwnode/src/exonware/xwnode/nodes/strategies/contracts.py
4
+
5
+ Node Strategy Contracts
6
+
7
+ This module defines contracts and enums for node strategies,
8
+ including the NodeType classification system for operation routing.
9
+
10
+ Company: eXonware.com
11
+ Author: Eng. Muhammad AlShehri
12
+ Email: connect@exonware.com
13
+ Version: 0.0.1.15
14
+ Generation Date: 08-Oct-2025
15
+ """
16
+
17
+ from enum import Enum, auto
18
+ from abc import ABC, abstractmethod
19
+ from typing import Any, List, Optional, Iterator
20
+
21
+
22
+ class NodeType(Enum):
23
+ """
24
+ Node strategy type classification.
25
+
26
+ Used to determine which operations can be executed on a node.
27
+ """
28
+ LINEAR = auto() # Array-like, sequential access (lists, stacks, queues)
29
+ TREE = auto() # Hierarchical, key-based ordering (maps, trees, tries)
30
+ GRAPH = auto() # Nodes with relationships (union-find, graphs)
31
+ MATRIX = auto() # 2D grid access (bitmaps, matrices)
32
+ HYBRID = auto() # Combination of multiple types
33
+
34
+
35
+ class INodeStrategy(ABC):
36
+ """
37
+ Base interface for all node strategies.
38
+
39
+ All node strategies must implement this interface and declare their type
40
+ and supported operations.
41
+ """
42
+
43
+ # Strategy type classification (must be set by each strategy)
44
+ STRATEGY_TYPE: NodeType = NodeType.TREE # Default
45
+
46
+ # Supported operations (can be overridden by each strategy)
47
+ SUPPORTED_OPERATIONS: List[str] = [] # Empty = supports all universal operations
48
+
49
+ @abstractmethod
50
+ def insert(self, key: Any, value: Any) -> None:
51
+ """Insert key-value pair."""
52
+ pass
53
+
54
+ @abstractmethod
55
+ def find(self, key: Any) -> Optional[Any]:
56
+ """Find value by key."""
57
+ pass
58
+
59
+ @abstractmethod
60
+ def delete(self, key: Any) -> bool:
61
+ """Delete by key."""
62
+ pass
63
+
64
+ @abstractmethod
65
+ def size(self) -> int:
66
+ """Get size of structure."""
67
+ pass
68
+
69
+ @abstractmethod
70
+ def is_empty(self) -> bool:
71
+ """Check if structure is empty."""
72
+ pass
73
+
74
+ @abstractmethod
75
+ def to_native(self) -> Any:
76
+ """Convert to native Python object."""
77
+ pass
78
+
79
+ @abstractmethod
80
+ def keys(self) -> Iterator[Any]:
81
+ """Get iterator over keys."""
82
+ pass
83
+
84
+ @abstractmethod
85
+ def values(self) -> Iterator[Any]:
86
+ """Get iterator over values."""
87
+ pass
88
+
89
+ @abstractmethod
90
+ def items(self) -> Iterator[tuple[Any, Any]]:
91
+ """Get iterator over key-value pairs."""
92
+ pass
93
+
94
+ @classmethod
95
+ def get_strategy_type(cls) -> NodeType:
96
+ """Get the strategy type for this class."""
97
+ return cls.STRATEGY_TYPE
98
+
99
+ @classmethod
100
+ def get_supported_operations(cls) -> List[str]:
101
+ """Get list of explicitly supported operations."""
102
+ return cls.SUPPORTED_OPERATIONS
103
+
104
+ @classmethod
105
+ def supports_operation(cls, operation: str) -> bool:
106
+ """Check if this strategy supports a specific operation."""
107
+ # Empty list means supports all universal operations
108
+ if not cls.SUPPORTED_OPERATIONS:
109
+ return True
110
+ return operation in cls.SUPPORTED_OPERATIONS
111
+
112
+
113
+ __all__ = [
114
+ 'NodeType',
115
+ 'INodeStrategy',
116
+ ]
@@ -6,13 +6,14 @@ Implements a double-ended queue using Python's deque for efficient operations at
6
6
  Company: eXonware.com
7
7
  Author: Eng. Muhammad AlShehri
8
8
  Email: connect@exonware.com
9
- Version: 0.0.1.13
9
+ Version: 0.0.1.15
10
10
  Generation Date: 07-Sep-2025
11
11
  """
12
12
 
13
13
  from typing import Any, Iterator, Optional, Dict, Union
14
14
  from collections import deque
15
15
  from .base import ANodeLinearStrategy
16
+ from .contracts import NodeType
16
17
  from ...types import NodeMode, NodeTrait
17
18
 
18
19
 
@@ -21,7 +22,11 @@ class DequeStrategy(ANodeLinearStrategy):
21
22
  Deque (Double-ended queue) node strategy for efficient operations at both ends.
22
23
 
23
24
  Provides O(1) operations for adding/removing elements at both front and back,
24
- ideal for sliding window algorithms and breadth-first search.
25
+ ideal for sliding window algorithms a
26
+
27
+ # Strategy type classification
28
+ STRATEGY_TYPE = NodeType.LINEAR
29
+ nd breadth-first search.
25
30
  """
26
31
 
27
32
  def __init__(self):
@@ -7,6 +7,7 @@ using Python's built-in dictionary.
7
7
 
8
8
  from typing import Any, Iterator, Dict, List, Optional, Union
9
9
  from .base import ANodeStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
 
12
13
 
@@ -18,6 +19,9 @@ class HashMapStrategy(ANodeStrategy):
18
19
  with associative operations.
19
20
  """
20
21
 
22
+ # HashMap is a tree/map structure (key-based access)
23
+ STRATEGY_TYPE = NodeType.TREE
24
+
21
25
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
22
26
  """Initialize the hash map strategy."""
23
27
  super().__init__(data=None, **options)
@@ -7,6 +7,7 @@ This module implements the HEAP strategy for priority queue operations.
7
7
  import heapq
8
8
  from typing import Any, Iterator, List, Optional, Dict
9
9
  from .base import ANodeTreeStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
 
12
13
 
@@ -51,7 +52,11 @@ class xHeapStrategy(ANodeTreeStrategy):
51
52
  """
52
53
  Heap node strategy for priority queue operations.
53
54
 
54
- Optimized for push, pop, and peek operations with configurable min/max behavior.
55
+ Optimized for push, pop, and peek operations with config
56
+
57
+ # Strategy type classification
58
+ STRATEGY_TYPE = NodeType.TREE
59
+ urable min/max behavior.
55
60
  """
56
61
 
57
62
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -7,6 +7,7 @@ insertions and deletions with sequential access patterns.
7
7
 
8
8
  from typing import Any, Iterator, List, Dict, Optional
9
9
  from .base import ANodeLinearStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
 
12
13
 
@@ -25,7 +26,11 @@ class LinkedListStrategy(ANodeLinearStrategy):
25
26
  Linked List node strategy for efficient insertions and deletions.
26
27
 
27
28
  Provides O(1) insertions/deletions at known positions with
28
- sequential access patterns optimized for iteration.
29
+ sequential access patterns
30
+
31
+ # Strategy type classification
32
+ STRATEGY_TYPE = NodeType.LINEAR
33
+ optimized for iteration.
29
34
  """
30
35
 
31
36
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -8,6 +8,7 @@ string matching using the Aho-Corasick automaton algorithm.
8
8
  from typing import Any, Iterator, List, Dict, Set, Optional, Tuple
9
9
  from collections import deque, defaultdict
10
10
  from .base import ANodeTreeStrategy
11
+ from .contracts import NodeType
11
12
  from ...types import NodeMode, NodeTrait
12
13
 
13
14
 
@@ -31,7 +32,11 @@ class AhoCorasickStrategy(ANodeTreeStrategy):
31
32
  Aho-Corasick node strategy for multi-pattern string matching.
32
33
 
33
34
  Efficiently searches for multiple patterns simultaneously in a text
34
- using a finite automaton with failure links for linear-time matching.
35
+ using a finite automaton with failure links f
36
+
37
+ # Strategy type classification
38
+ STRATEGY_TYPE = NodeType.TREE
39
+ or linear-time matching.
35
40
  """
36
41
 
37
42
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -17,6 +17,10 @@ class xArrayListStrategy(aNodeStrategy):
17
17
  Uses Python's built-in list for optimal performance with indexed operations.
18
18
  """
19
19
 
20
+ # Strategy type classification
21
+ STRATEGY_TYPE = NodeType.LINEAR
22
+
23
+
20
24
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
21
25
  """Initialize the array list strategy."""
22
26
  super().__init__(NodeMode.ARRAY_LIST, traits, **options)
@@ -8,6 +8,7 @@ search trees with guaranteed O(log n) height and operations.
8
8
 
9
9
  from typing import Any, Iterator, List, Dict, Optional, Tuple
10
10
  from .base import ANodeTreeStrategy
11
+ from .contracts import NodeType
11
12
  from ...types import NodeMode, NodeTrait
12
13
 
13
14
 
@@ -42,7 +43,11 @@ class AVLTreeStrategy(ANodeTreeStrategy):
42
43
  AVL tree node strategy for strictly balanced binary search trees.
43
44
 
44
45
  Provides guaranteed O(log n) height and operations through height-based
45
- balancing rules and rotations.
46
+ balanc
47
+
48
+ # Strategy type classification
49
+ STRATEGY_TYPE = NodeType.TREE
50
+ ing rules and rotations.
46
51
  """
47
52
 
48
53
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -7,6 +7,7 @@ operations with efficient range queries and sequential access.
7
7
 
8
8
  from typing import Any, Iterator, List, Dict, Optional, Tuple
9
9
  from .base import ANodeTreeStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
 
12
13
 
@@ -44,7 +45,11 @@ class BPlusTreeStrategy(ANodeTreeStrategy):
44
45
  B+ Tree node strategy for database-friendly operations.
45
46
 
46
47
  Provides efficient range queries, sequential access, and balanced
47
- tree operations optimized for disk-based storage systems.
48
+ tree operations optimized for dis
49
+
50
+ # Strategy type classification
51
+ STRATEGY_TYPE = NodeType.TREE
52
+ k-based storage systems.
48
53
  """
49
54
 
50
55
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -8,6 +8,7 @@ and boolean operations with compressed storage.
8
8
  from typing import Any, Iterator, List, Dict, Optional, Union
9
9
  import array
10
10
  from .base import ANodeMatrixStrategy
11
+ from .contracts import NodeType
11
12
  from ...types import NodeMode, NodeTrait
12
13
 
13
14
 
@@ -16,7 +17,11 @@ class BitmapStrategy(ANodeMatrixStrategy):
16
17
  Bitmap node strategy for efficient bit manipulation and boolean operations.
17
18
 
18
19
  Provides space-efficient storage for boolean flags and supports
19
- fast bitwise operations with compressed representation.
20
+ fast bitwise operations with co
21
+
22
+ # Strategy type classification
23
+ STRATEGY_TYPE = NodeType.MATRIX
24
+ mpressed representation.
20
25
  """
21
26
 
22
27
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -7,6 +7,7 @@ operations with automatic resizing and bit manipulation capabilities.
7
7
 
8
8
  from typing import Any, Iterator, List, Dict, Optional, Tuple, Union
9
9
  from .base import ANodeMatrixStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
 
12
13
 
@@ -15,7 +16,11 @@ class BitsetDynamicStrategy(ANodeMatrixStrategy):
15
16
  Dynamic Bitset node strategy for bit manipulation operations.
16
17
 
17
18
  Provides efficient set operations, bit manipulation, and automatic
18
- resizing for large-scale boolean data processing.
19
+ resizing for large-scale
20
+
21
+ # Strategy type classification
22
+ STRATEGY_TYPE = NodeType.MATRIX
23
+ boolean data processing.
19
24
  """
20
25
 
21
26
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -9,6 +9,7 @@ from typing import Any, Iterator, List, Dict, Optional
9
9
  import hashlib
10
10
  import math
11
11
  from ._base_node import aNodeStrategy
12
+ from .contracts import NodeType
12
13
  from ...types import NodeMode, NodeTrait
13
14
 
14
15
 
@@ -22,6 +23,9 @@ class xBloomFilterStrategy(aNodeStrategy):
22
23
  - Configurable false positive rate
23
24
  """
24
25
 
26
+ # Strategy type classification
27
+ STRATEGY_TYPE = NodeType.MATRIX
28
+
25
29
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
26
30
  """Initialize the Bloom Filter strategy."""
27
31
  super().__init__(NodeMode.BLOOM_FILTER, traits, **options)
@@ -7,6 +7,7 @@ and sorted key operations with guaranteed O(log n) performance.
7
7
 
8
8
  from typing import Any, Iterator, List, Optional, Union, Dict
9
9
  from .base import ANodeTreeStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
 
12
13
 
@@ -93,7 +94,11 @@ class BTreeStrategy(ANodeTreeStrategy):
93
94
  B-Tree node strategy for efficient sorted operations and range queries.
94
95
 
95
96
  Provides O(log n) search, insert, and delete operations with excellent
96
- cache performance for range queries.
97
+ cache perfor
98
+
99
+ # Strategy type classification
100
+ STRATEGY_TYPE = NodeType.TREE
101
+ mance for range queries.
97
102
  """
98
103
 
99
104
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -20,6 +20,10 @@ class xCountMinSketchStrategy(aNodeStrategy):
20
20
  probabilistic error bounds and no false negatives.
21
21
  """
22
22
 
23
+ # Strategy type classification
24
+ STRATEGY_TYPE = NodeType.MATRIX
25
+
26
+
23
27
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
24
28
  """Initialize the Count-Min Sketch strategy."""
25
29
  super().__init__(NodeMode.COUNT_MIN_SKETCH, traits, **options)
@@ -8,6 +8,7 @@ atomic snapshots and versioning capabilities.
8
8
 
9
9
  from typing import Any, Iterator, List, Dict, Optional, Tuple, Set
10
10
  from .base import ANodeTreeStrategy
11
+ from .contracts import NodeType
11
12
  from ...types import NodeMode, NodeTrait
12
13
 
13
14
 
@@ -65,7 +66,11 @@ class COWTreeStrategy(ANodeTreeStrategy):
65
66
  Copy-on-write tree node strategy with atomic snapshots.
66
67
 
67
68
  Provides instant snapshots, atomic updates, and versioning through
68
- copy-on-write semantics with reference counting.
69
+ copy-on-write semantics
70
+
71
+ # Strategy type classification
72
+ STRATEGY_TYPE = NodeType.TREE
73
+ with reference counting.
69
74
  """
70
75
 
71
76
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -7,6 +7,7 @@ queries and point updates with O(log n) complexity.
7
7
 
8
8
  from typing import Any, Iterator, List, Dict, Union
9
9
  from .base import ANodeTreeStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
 
12
13
 
@@ -15,7 +16,11 @@ class FenwickTreeStrategy(ANodeTreeStrategy):
15
16
  Fenwick Tree node strategy for efficient prefix sum operations.
16
17
 
17
18
  Also known as Binary Indexed Tree (BIT), provides O(log n) prefix sum
18
- queries and point updates with minimal memory overhead.
19
+ queries and point updates with
20
+
21
+ # Strategy type classification
22
+ STRATEGY_TYPE = NodeType.TREE
23
+ minimal memory overhead.
19
24
  """
20
25
 
21
26
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -29,6 +29,10 @@ class xHashMapStrategy(aNodeStrategy):
29
29
  with associative operations.
30
30
  """
31
31
 
32
+ # Strategy type classification
33
+ STRATEGY_TYPE = NodeType.TREE
34
+
35
+
32
36
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
33
37
  """Initialize the hash map strategy."""
34
38
  super().__init__(NodeMode.HASH_MAP, traits, **options)
@@ -7,6 +7,7 @@ This module implements the HEAP strategy for priority queue operations.
7
7
  import heapq
8
8
  from typing import Any, Iterator, List, Optional, Dict
9
9
  from .base import ANodeTreeStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
  from ..utils import (
12
13
  MinHeap,
@@ -25,7 +26,11 @@ class HeapStrategy(ANodeTreeStrategy):
25
26
  """
26
27
  Heap node strategy for priority queue operations.
27
28
 
28
- Optimized for push, pop, and peek operations with configurable min/max behavior.
29
+ Optimized for push, pop, and peek operations with config
30
+
31
+ # Strategy type classification
32
+ STRATEGY_TYPE = NodeType.TREE
33
+ urable min/max behavior.
29
34
  """
30
35
 
31
36
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -20,6 +20,10 @@ class xHyperLogLogStrategy(aNodeStrategy):
20
20
  with configurable precision and excellent scalability.
21
21
  """
22
22
 
23
+ # Strategy type classification
24
+ STRATEGY_TYPE = NodeType.MATRIX
25
+
26
+
23
27
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
24
28
  """Initialize the HyperLogLog strategy."""
25
29
  super().__init__(NodeMode.HYPERLOGLOG, traits, **options)
@@ -28,6 +28,10 @@ class xLinkedListStrategy(aNodeStrategy):
28
28
  sequential access patterns optimized for iteration.
29
29
  """
30
30
 
31
+ # Strategy type classification
32
+ STRATEGY_TYPE = NodeType.LINEAR
33
+
34
+
31
35
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
32
36
  """Initialize the Linked List strategy."""
33
37
  super().__init__(NodeMode.LINKED_LIST, traits, **options)
@@ -10,6 +10,7 @@ import time
10
10
  import threading
11
11
  from collections import defaultdict
12
12
  from .base import ANodeTreeStrategy
13
+ from .contracts import NodeType
13
14
  from ...types import NodeMode, NodeTrait
14
15
 
15
16
 
@@ -92,7 +93,11 @@ class LSMTreeStrategy(ANodeTreeStrategy):
92
93
  LSM Tree node strategy for write-heavy workloads.
93
94
 
94
95
  Provides excellent write performance with eventual read consistency
95
- through in-memory memtables and sorted disk-based SSTables.
96
+ through in-memory memtables and sor
97
+
98
+ # Strategy type classification
99
+ STRATEGY_TYPE = NodeType.TREE
100
+ ted disk-based SSTables.
96
101
  """
97
102
 
98
103
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -8,6 +8,7 @@ operations with efficient range queries and ordered iteration.
8
8
  from typing import Any, Iterator, List, Dict, Optional, Tuple
9
9
  import bisect
10
10
  from .base import ANodeTreeStrategy
11
+ from .contracts import NodeType
11
12
  from ...types import NodeMode, NodeTrait
12
13
 
13
14
 
@@ -16,7 +17,11 @@ class OrderedMapStrategy(ANodeTreeStrategy):
16
17
  Ordered Map node strategy for sorted key-value operations.
17
18
 
18
19
  Maintains keys in sorted order for efficient range queries,
19
- ordered iteration, and logarithmic search operations.
20
+ ordered iteration, and logari
21
+
22
+ # Strategy type classification
23
+ STRATEGY_TYPE = NodeType.TREE
24
+ thmic search operations.
20
25
  """
21
26
 
22
27
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -7,6 +7,7 @@ ordered operations with guaranteed O(log n) performance.
7
7
 
8
8
  from typing import Any, Iterator, List, Dict, Optional, Tuple
9
9
  from .base import ANodeTreeStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
 
12
13
 
@@ -43,7 +44,11 @@ class OrderedMapBalancedStrategy(ANodeTreeStrategy):
43
44
  Balanced Ordered Map node strategy using AVL tree.
44
45
 
45
46
  Provides guaranteed O(log n) operations with automatic balancing
46
- for optimal performance in all scenarios.
47
+ for optimal perfo
48
+
49
+ # Strategy type classification
50
+ STRATEGY_TYPE = NodeType.TREE
51
+ rmance in all scenarios.
47
52
  """
48
53
 
49
54
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
@@ -7,6 +7,7 @@ Retrieve Information Coded in Alphanumeric) for binary trie compression.
7
7
 
8
8
  from typing import Any, Iterator, List, Dict, Optional, Tuple
9
9
  from .base import ANodeTreeStrategy
10
+ from .contracts import NodeType
10
11
  from ...types import NodeMode, NodeTrait
11
12
 
12
13
 
@@ -31,7 +32,11 @@ class PatriciaStrategy(ANodeTreeStrategy):
31
32
  PATRICIA node strategy for compressed binary trie operations.
32
33
 
33
34
  Implements PATRICIA algorithm for efficient string storage and
34
- retrieval using compressed binary trie structure.
35
+ retrieval using compresse
36
+
37
+ # Strategy type classification
38
+ STRATEGY_TYPE = NodeType.TREE
39
+ d binary trie structure.
35
40
  """
36
41
 
37
42
  def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):