Metadata-Version: 2.4
Name: algocode
Version: 0.1.1
Summary: Call an algorithm by name and get its source code, explanation, complexity, and a step-by-step trace on your own data.
License: MIT
Project-URL: Homepage, https://github.com/yourname/algocode
Keywords: algorithms,competitive-programming,sorting,education,code-generation
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Education
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# algocode

**Call an algorithm by name and get its source code, a plain-English explanation, its time/space complexity, and an optional step-by-step trace on your own data.**

Built for competitive programming and learning: grab a clean, ready-to-paste implementation in seconds, or watch exactly how an algorithm behaves on a specific input.

\---

## Installation

Install from PyPI with pip:

```bash
pip install algocode
```

To upgrade to the latest version later:

```bash
pip install --upgrade algocode
```

Requires **Python 3.8 or newer**. No external dependencies.

\---

## Quick start

```python
import algocode as ac

algo = ac.get("quicksort")

print(algo.code())                   # source code as a ready-to-paste string
print(algo.explain())                # summary + complexity + stability
algo.trace(\[2, 4, 6, 8, 1, 3, 5])    # prints the step-by-step run

ac.available()                       # list every algorithm name
```

The pattern is always the same: **`ac.get("name")`** to fetch an algorithm, then call **`.code()`**, **`.explain()`**, or **`.trace()`** on it.

\---

## What you can call

Two top-level functions:

|Call|What it does|
|-|-|
|`ac.available()`|Returns a sorted list of every algorithm name.|
|`ac.get("name")`|Returns an algorithm object (accepts aliases like `"quick"`, `"binary"`).|

Methods on the object returned by `ac.get(...)`:

|Method|What it returns|
|-|-|
|`.code()`|The source code as a string, ready to copy-paste.|
|`.code(\[your, data])`|The same source **plus** a runnable usage line filled in with your data.|
|`.explain()`|Summary of how it works, its best/average/worst time, space, and whether it's stable.|
|`.trace(\[your, data])`|Prints a step-by-step walkthrough on your data, and returns the steps as a list.|

\---

## Available algorithms

Currently **9 algorithms**, grouped by category.

### Sorting

|Name|Idea|Time (best / avg / worst)|Space|Stable|
|-|-|-|-|-|
|`quicksort`|Divide \& conquer around a pivot|O(n log n) / O(n log n) / O(n²)|O(log n)|no|
|`mergesort`|Split in half, sort, merge|O(n log n) / O(n log n) / O(n log n)|O(n)|yes|
|`bubblesort`|Swap adjacent out-of-order pairs|O(n) / O(n²) / O(n²)|O(1)|yes|
|`insertionsort`|Insert each element into the sorted left part|O(n) / O(n²) / O(n²)|O(1)|yes|
|`selectionsort`|Repeatedly grab the minimum|O(n²) / O(n²) / O(n²)|O(1)|no|

### Searching

|Name|Idea|Time (best / avg / worst)|Space|
|-|-|-|-|
|`binarysearch`|Halve a **sorted** array each step|O(1) / O(log n) / O(log n)|O(1)|
|`linearsearch`|Scan left to right|O(1) / O(n) / O(n)|O(1)|

### Math / utility

|Name|Idea|Time|Space|
|-|-|-|-|
|`gcd`|Euclid's algorithm for greatest common divisor|O(log(min(a, b)))|O(1)|
|`reverse`|Two-pointer in-place array reversal|O(n)|O(1)|

Get this list at any time with `ac.available()`.

\---

## Aliases

Short names and common variants resolve to the right algorithm:

|You type|You get|
|-|-|
|`"quick"`, `"quick\_sort"`|`quicksort`|
|`"merge"`, `"merge\_sort"`|`mergesort`|
|`"bubble"`|`bubblesort`|
|`"insertion"`|`insertionsort`|
|`"selection"`|`selectionsort`|
|`"binary"`, `"binary\_search"`|`binarysearch`|
|`"linear"`|`linearsearch`|
|`"hcf"`|`gcd`|

\---

## Examples

**Get ready-to-run code for your data:**

```python
import algocode as ac
print(ac.get("quicksort").code(\[2, 4, 6, 8, 1, 3, 5]))
```

```python
def quicksort(arr):
    if len(arr) <= 1:
        return arr
    pivot = arr\[len(arr) // 2]
    left  = \[x for x in arr if x < pivot]
    mid   = \[x for x in arr if x == pivot]
    right = \[x for x in arr if x > pivot]
    return quicksort(left) + mid + quicksort(right)

# usage
print(quicksort(\[2, 4, 6, 8, 1, 3, 5]))
```

**Watch it work step by step:**

```python
ac.get("bubblesort").trace(\[5, 1, 4, 2, 8])
```