dsa-builder 1.0.0
A complete Python library for Data Structures, Algorithms, Graphs, Searching, Sorting & Utilities — beginner-friendly, production-ready.
License: MIT
Requires Python: >=3.11

# 📦 **dsa_builder**

### *A complete Python library for Data Structures, Algorithms, Graphs, Searching, Sorting & Utilities — beginner-friendly, production-ready.*

---

## 🧠 **What is dsa_builder?**

**dsa_builder** is a lightweight yet complete Python package designed for:

* Students learning Data Structures & Algorithms
* Developers who want reusable DSA utilities
* Interview preparation
* Teaching / classroom demos
* Research prototypes
* Quick scripting requiring fast DSA helpers

It includes **search algorithms, sorting algorithms, graph algorithms, stacks, queues, linked lists, pathfinding, cycle detection, MST, SCC, and more.**

It also includes **Rich-powered automatic pretty-printing**, so *all* `print()` outputs from the package or user code are formatted in rich, readable style without importing anything manually.

---

## ⭐ **Key Features**

### ✔ Complete DSA Suite

* Stacks (array & linked)
* Queues (deque & linked)
* Singly, doubly, circular linked lists
* Searching: linear, binary, bounds, rotated array search
* Sorting: basic, intermediate, advanced (merge, quick, heap, counting, radix, timsort)
* Graph class + advanced algorithms
* Dijkstra, Bellman-Ford, DFS, BFS
* MST: Kruskal, Prim
* SCC (Kosaraju)
* Cycle detection with cycle path
* Shortest path reconstruction

---

### ✔ Automatic Rich Output (No Import Needed)

`print()` automatically becomes Rich's colorful pretty printer.

Example:

```python
print({"a": 1, "b": [1,2,3]})
```

Prints beautifully formatted output without importing Rich manually.

---

### ✔ Modern Python API

Every module is accessible through:

```python
from dsa_builder import *
```

or specifically:

```python
from dsa_builder import Graph, merge_sort, binary_search_iterative
```

---

### ✔ Easy to Extend

All modules are independent, readable, and documented.
New data structures or algorithms can be added easily.

---

## 📁 **Directory Structure**

```
dsa_builder/
│
├── __init__.py
├── rich_print.py
├── stack.py
├── queue.py
├── linked_list.py
├── search.py
├── sorting.py
├── graph.py
├── graph_algorithms.py
├── complexity.py
└── main.py  (example usage)
```

---

## 🔧 Installation

```
pip install dsa_builder
```

(If publishing later, you will replace with the real PyPI command.)

---

## 🚀 Getting Started

### **1. Import the library**

```python
import dsa_builder
```

Everything prints in Rich style automatically.

### **2. Graph Example**

```python
from dsa_builder import Graph

g = Graph(directed=False)
g.add_edge("A", "B")
g.add_edge("B", "C")

print(g.to_adj_list())
```

Output (auto-rich):

```
{
    "A": [("B", 1.0)],
    "B": [("A", 1.0), ("C", 1.0)],
    "C": [("B", 1.0)],
}
```

---

## 🔎 Searching Algorithms

### Supported:

* `linear_search`
* `binary_search_iterative`
* `binary_search_recursive`
* `lower_bound`
* `upper_bound`
* `find_first_last`
* `search_in_rotated_array`

### Example

```python
from dsa_builder import binary_search_iterative

nums = [1,3,5,7,9]
print(binary_search_iterative(nums, 7))  # 3
```

---

## 🔢 Sorting Algorithms

Supported sorts include:

### **Basic Sorting**

* `selection_sort`
* `bubble_sort`
* `insertion_sort`

### **Advanced Sorting**

* `merge_sort`
* `quick_sort`
* `heap_sort`
* `counting_sort`
* `shell_sort`
* `radix_sort`
* `bucket_sort`
* `tim_sort` (custom implementation)

### Example

```python
from dsa_builder import merge_sort

arr = [5,2,9,1]
print(merge_sort(arr))
```

---

## 📚 Linked List Structures

### Supported:

* `SinglyLL`
* `DoublyLinkedList`
* `CircularLinkedList`

### Example

```python
from dsa_builder import SinglyLL

ll = SinglyLL()
ll.insert_end(10)
ll.insert_end(20)
print(ll)
```

---

## 🧱 Stack & Queue

### Stack

* `Stack`
* `LinkedStack`

### Queue

* `DequeQueue`
* `LinkedQueue`

Example:

```python
from dsa_builder import Stack

s = Stack()
s.push(10)
s.push(20)
print(s.pop())  # 20
```

---

## 🌐 Graph Algorithms

### Included Algorithms:

| Algorithm             | Purpose                                |
| --------------------- | -------------------------------------- |
| BFS                   | traversal / shortest unweighted        |
| DFS                   | traversal / cycle detection            |
| Dijkstra              | shortest path (positive weights)       |
| Bellman-Ford          | negative weights + cycle detection     |
| Prim MST              | minimum spanning tree                  |
| Kruskal MST           | minimum spanning tree                  |
| SCC                   | strongly connected components          |
| detect_cycle_directed | detects cycle & returns cycle path     |
| reconstruct_path      | recreate shortest path from parent map |

### Example: Dijkstra

```python
from dsa_builder import Graph, shortest_path_dijkstra, reconstruct_path

g = Graph(directed=True, weighted=True)
g.add_edge("s","a",1)
g.add_edge("a","b",2)
g.add_edge("s","b",5)

dist, parent = shortest_path_dijkstra(g, "s")
print(dist)                    # {'s':0, 'a':1, 'b':3}
print(reconstruct_path(parent, "s", "b"))  # ['s','a','b']
```

---

## 📊 Complexity Module

`complexity.py` provides easy lookup tables:

```python
from dsa_builder import COMPLEXITY_SORT

print(COMPLEXITY_SORT["merge_sort"])  # O(n log n)
```

---

## 🎨 Auto Rich Printing Behavior

This package **overrides Python’s print globally**:

Inside `rich_print.py`:

```python
import builtins
from rich import print as rich_print
builtins.print = rich_print
```

Once `import dsa_builder` happens:

* All `print()` inside the package = Rich
* All `print()` inside user code = Rich
* No extra imports needed

---

## 🧪 Example Project (main.py)

Your included `main.py` demonstrates combining DSA operations:

```python
from dsa_builder import Graph, merge_sort, binary_search_iterative

g = Graph(directed=False)
g.add_edge(1,2)
g.add_edge(2,3)

print("Adjacency List:", g.to_adj_list())
print("Sorted:", merge_sort([9,1,3,7]))
print("Search:", binary_search_iterative([1,3,5,7], 5))
```

---

## 🛠 Contributing

Pull requests are welcome.
To contribute:

1. Fork the repository
2. Create a new branch
3. Add features or fix issues
4. Update documentation
5. Submit PR

All code should follow **PEP8** and include tests where appropriate.

---

## 📄 License

MIT License — simple and open.
You may freely use, modify, or distribute this library.

---

## 📌 Versioning

We follow **Semantic Versioning**:

```
MAJOR.MINOR.PATCH
```

Example:

* `1.0.0` — Initial release
* `1.1.0` — Added algorithms
* `1.1.1` — Bug fixes

---

# 🎉 Final Notes

`dsa_builder` aims to be:

* beginner-friendly
* powerful
* easy to extend
* rich-printed by default
* fully modular

It’s a perfect starting point for learning, building projects, interview prep, and classroom use.