arborpy 0.1.0__tar.gz

arborpy-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @prabhav-jalan

arborpy-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug Report
+about: Report a bug in arborpy
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To reproduce**
+```python
+# Minimal code to reproduce
+```
+
+**Expected behavior**
+What should have happened.
+
+**Environment**
+- Python version:
+- arborpy version:
+- OS:

arborpy-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature Request
+about: Suggest a new feature for arborpy
+labels: enhancement
+---
+
+**Describe the feature**
+A clear description of what you'd like added.
+
+**Use case**
+Why is this feature useful? What problem does it solve?
+
+**Proposed API**
+```python
+# How you'd like to use the feature
+```
+
+**Alternatives considered**
+Any alternative solutions you've thought about.

arborpy-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Summary
+Brief description of what this PR does.
+
+## Type of change
+- [ ] New feature
+- [ ] Bug fix
+- [ ] Documentation
+- [ ] Refactoring
+- [ ] CI/CD
+
+## Checklist
+- [ ] Tests pass locally (`uv run pytest`)
+- [ ] Linting passes (`uv run ruff check src/ tests/`)
+- [ ] Type checking passes (`uv run mypy src/`)
+- [ ] Docstrings added for public API
+- [ ] CHANGELOG.md updated (if user-facing change)

arborpy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint with Ruff
+        run: uv run ruff check src/ tests/
+
+      - name: Format check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Type check with mypy
+        run: uv run mypy src/
+
+      - name: Run tests
+        run: uv run pytest --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.13' && matrix.os == 'ubuntu-latest'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml

arborpy-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create ${{ github.ref_name }} --generate-notes

arborpy-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# Docs
+docs/_build/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Distribution
+*.tar.gz
+*.whl

arborpy-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.8
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [pytest]
+        args: [--strict]

arborpy-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

arborpy-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-27
+
+### Added
+
+- `Node` class with value, left/right children, and `is_leaf()` method
+- `BinarySearchTree` with insert, delete, search, find_min, find_max, height
+- Traversal functions: inorder, preorder, postorder, level_order
+- Serialization: to_dict, from_dict, to_json, from_json
+- ASCII pretty-print visualization via `print(bst)`
+- Custom exceptions: EmptyTreeError, NodeNotFoundError, DuplicateKeyError
+- Support for `len(bst)`, `in` operator, and `bool(bst)`
+- Full test suite with 77 tests
+- CI pipeline with GitHub Actions (Python 3.13, 3.14 on Ubuntu and macOS)
+- Type hints throughout (PEP 561 compatible with py.typed marker)

arborpy-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing to ArborPy
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+1. Fork and clone the repo:
+   ```bash
+   git clone git@github.com:your-username/arborpy.git
+   cd arborpy
+   ```
+
+2. Install [uv](https://docs.astral.sh/uv/):
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+3. Install dependencies:
+   ```bash
+   uv sync
+   ```
+
+4. Install pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
+
+## Running Tests
+
+```bash
+uv run pytest                       # all tests
+uv run pytest tests/test_node.py    # single file
+uv run pytest -x                    # stop on first failure
+uv run pytest -v                    # verbose output
+```
+
+## Code Quality
+
+```bash
+uv run ruff check src/ tests/       # lint
+uv run ruff format src/ tests/      # format
+uv run mypy src/                    # type check
+```
+
+Or run everything at once:
+
+```bash
+make check
+```
+
+## Branch Naming
+
+| Prefix | Use for |
+|--------|---------|
+| `feat/` | New features |
+| `fix/` | Bug fixes |
+| `docs/` | Documentation |
+| `refactor/` | Code refactoring |
+| `test/` | Adding or fixing tests |
+
+## Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add AVL tree with self-balancing insert
+fix: correct BST delete when node has two children
+docs: update README with AVL usage examples
+test: add edge case tests for empty tree operations
+```
+
+## Pull Request Process
+
+1. Create a feature branch from `develop`
+2. Write tests for your changes
+3. Ensure all checks pass (`make check`)
+4. Submit PR against `develop`
+5. Fill in the PR template
+
+## Code Style
+
+- Type hints on all public functions and methods
+- Google-style docstrings on all public classes and methods
+- Line length limit: 88 characters
+- Ruff handles formatting and linting automatically

arborpy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prabhav Jalan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arborpy-0.1.0/Makefile

@@ -0,0 +1,21 @@
+.PHONY: test lint format typecheck clean build check
+
+test:
+	uv run pytest
+
+lint:
+	uv run ruff check src/ tests/
+
+format:
+	uv run ruff format src/ tests/
+
+typecheck:
+	uv run mypy src/
+
+check: lint typecheck test
+
+clean:
+	rm -rf dist/ build/ *.egg-info .pytest_cache .mypy_cache htmlcov/
+
+build: clean
+	uv build

arborpy-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: arborpy
+Version: 0.1.0
+Summary: A comprehensive Python library for tree data structures
+Project-URL: Homepage, https://github.com/prabhav-jalan/arborpy
+Project-URL: Documentation, https://arborpy.readthedocs.io
+Project-URL: Repository, https://github.com/prabhav-jalan/arborpy
+Project-URL: Issues, https://github.com/prabhav-jalan/arborpy/issues
+Project-URL: Changelog, https://github.com/prabhav-jalan/arborpy/blob/main/CHANGELOG.md
+Author-email: Prabhav Jalan <prabhavjalan12@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: avl,binary-tree,bst,data-structures,heap,tree,trie
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# ArborPy 🌳
+
+[![CI](https://github.com/prabhav-jalan/arborpy/actions/workflows/ci.yml/badge.svg)](https://github.com/prabhav-jalan/arborpy/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/arborpy.svg)](https://pypi.org/project/arborpy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/arborpy)](https://pypi.org/project/arborpy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A comprehensive, typed, and well-tested Python library for tree data structures.
+
+## Installation
+
+```bash
+pip install arborpy
+```
+
+## Quick Start
+
+```python
+from arborpy import BinarySearchTree
+
+bst = BinarySearchTree()
+for val in [5, 3, 7, 1, 4]:
+    bst.insert(val)
+
+print(bst.inorder())    # [1, 3, 4, 5, 7]
+print(bst.search(4))    # True
+print(5 in bst)         # True
+print(len(bst))         # 5
+print(bst)              # Pretty-printed tree
+```
+
+## Features
+
+### Binary Search Tree
+
+```python
+from arborpy import BinarySearchTree
+
+bst = BinarySearchTree()
+
+# Insert values
+for val in [5, 3, 7, 1, 4, 6, 8]:
+    bst.insert(val)
+
+# Search
+bst.search(4)       # True
+bst.search(99)      # False
+
+# Delete
+bst.delete(3)
+
+# Min and max
+bst.find_min()      # 1
+bst.find_max()      # 8
+
+# Tree properties
+bst.height()        # 2
+len(bst)            # 7
+```
+
+### Traversals
+
+```python
+from arborpy import BinarySearchTree
+
+bst = BinarySearchTree()
+for val in [5, 3, 7, 1, 4, 6, 8]:
+    bst.insert(val)
+
+bst.inorder()       # [1, 3, 4, 5, 6, 7, 8]
+bst.preorder()      # [5, 3, 1, 4, 7, 6, 8]
+bst.postorder()     # [1, 4, 3, 6, 8, 7, 5]
+bst.level_order()   # [[5], [3, 7], [1, 4, 6, 8]]
+```
+
+### Serialization
+
+```python
+from arborpy import BinarySearchTree, to_json, from_json, to_dict, from_dict
+
+bst = BinarySearchTree()
+for val in [5, 3, 7]:
+    bst.insert(val)
+
+# To/from dictionary
+d = to_dict(bst.root)
+node = from_dict(d)
+
+# To/from JSON
+json_str = to_json(bst.root)
+node = from_json(json_str)
+```
+
+### Standalone Traversal Functions
+
+```python
+from arborpy import Node, inorder, preorder, postorder, level_order
+
+# Build a tree manually
+root = Node(1, Node(2, Node(4), Node(5)), Node(3))
+
+inorder(root)       # [4, 2, 5, 1, 3]
+preorder(root)      # [1, 2, 4, 5, 3]
+postorder(root)     # [4, 5, 2, 3, 1]
+level_order(root)   # [[1], [2, 3], [4, 5]]
+```
+
+## Roadmap
+
+- [x] Binary Search Tree
+- [x] Traversals (inorder, preorder, postorder, level-order)
+- [x] Serialization (dict, JSON)
+- [x] ASCII visualization
+- [ ] AVL Tree (self-balancing)
+- [ ] Min/Max Heap
+- [ ] Red-Black Tree
+- [ ] Trie (prefix tree)
+- [ ] Segment Tree
+- [ ] Fenwick Tree (Binary Indexed Tree)
+- [ ] N-ary Tree
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

arborpy-0.1.0/README.md

@@ -0,0 +1,128 @@
+# ArborPy 🌳
+
+[![CI](https://github.com/prabhav-jalan/arborpy/actions/workflows/ci.yml/badge.svg)](https://github.com/prabhav-jalan/arborpy/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/arborpy.svg)](https://pypi.org/project/arborpy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/arborpy)](https://pypi.org/project/arborpy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A comprehensive, typed, and well-tested Python library for tree data structures.
+
+## Installation
+
+```bash
+pip install arborpy
+```
+
+## Quick Start
+
+```python
+from arborpy import BinarySearchTree
+
+bst = BinarySearchTree()
+for val in [5, 3, 7, 1, 4]:
+    bst.insert(val)
+
+print(bst.inorder())    # [1, 3, 4, 5, 7]
+print(bst.search(4))    # True
+print(5 in bst)         # True
+print(len(bst))         # 5
+print(bst)              # Pretty-printed tree
+```
+
+## Features
+
+### Binary Search Tree
+
+```python
+from arborpy import BinarySearchTree
+
+bst = BinarySearchTree()
+
+# Insert values
+for val in [5, 3, 7, 1, 4, 6, 8]:
+    bst.insert(val)
+
+# Search
+bst.search(4)       # True
+bst.search(99)      # False
+
+# Delete
+bst.delete(3)
+
+# Min and max
+bst.find_min()      # 1
+bst.find_max()      # 8
+
+# Tree properties
+bst.height()        # 2
+len(bst)            # 7
+```
+
+### Traversals
+
+```python
+from arborpy import BinarySearchTree
+
+bst = BinarySearchTree()
+for val in [5, 3, 7, 1, 4, 6, 8]:
+    bst.insert(val)
+
+bst.inorder()       # [1, 3, 4, 5, 6, 7, 8]
+bst.preorder()      # [5, 3, 1, 4, 7, 6, 8]
+bst.postorder()     # [1, 4, 3, 6, 8, 7, 5]
+bst.level_order()   # [[5], [3, 7], [1, 4, 6, 8]]
+```
+
+### Serialization
+
+```python
+from arborpy import BinarySearchTree, to_json, from_json, to_dict, from_dict
+
+bst = BinarySearchTree()
+for val in [5, 3, 7]:
+    bst.insert(val)
+
+# To/from dictionary
+d = to_dict(bst.root)
+node = from_dict(d)
+
+# To/from JSON
+json_str = to_json(bst.root)
+node = from_json(json_str)
+```
+
+### Standalone Traversal Functions
+
+```python
+from arborpy import Node, inorder, preorder, postorder, level_order
+
+# Build a tree manually
+root = Node(1, Node(2, Node(4), Node(5)), Node(3))
+
+inorder(root)       # [4, 2, 5, 1, 3]
+preorder(root)      # [1, 2, 4, 5, 3]
+postorder(root)     # [4, 5, 2, 3, 1]
+level_order(root)   # [[1], [2, 3], [4, 5]]
+```
+
+## Roadmap
+
+- [x] Binary Search Tree
+- [x] Traversals (inorder, preorder, postorder, level-order)
+- [x] Serialization (dict, JSON)
+- [x] ASCII visualization
+- [ ] AVL Tree (self-balancing)
+- [ ] Min/Max Heap
+- [ ] Red-Black Tree
+- [ ] Trie (prefix tree)
+- [ ] Segment Tree
+- [ ] Fenwick Tree (Binary Indexed Tree)
+- [ ] N-ary Tree
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.