# SimpleDSA
[](https://badge.fury.io/py/simpledsa)
[](https://github.com/dsalathe/simpledsa/actions/workflows/python-package.yml)
[](https://codecov.io/gh/dsalathe/simpledsa)
[](https://simpledsa.readthedocs.io/en/latest/?badge=latest)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/simpledsa/)
A simple and intuitive implementation of data structures and algorithms in Python.
## Installation
```bash
pip install simpledsa
```
## Usage
### Priority Queue
```python
from simpledsa import PriorityQueue
# Create a min-heap priority queue (smaller values have higher priority)
pq = PriorityQueue()
# Create a max-heap priority queue (larger values have higher priority)
max_pq = PriorityQueue(lambda x: -x)
# Using items as their own priority
pq.push(3)
pq.push(1)
pq.push(4)
print(pq.pop()) # Output: 1 (smallest value has highest priority)
print(pq.pop()) # Output: 3
print(pq.pop()) # Output: 4
# Using explicit priorities
task_queue = PriorityQueue()
task_queue.push("Write docs", priority=2)
task_queue.push("Fix bug", priority=1)
task_queue.push("Add feature", priority=3)
print(task_queue.pop()) # Output: "Fix bug" (priority 1)
print(task_queue.pop()) # Output: "Write docs" (priority 2)
print(task_queue.pop()) # Output: "Add feature" (priority 3)
# Check if queue is empty
if not pq:
print("Queue is empty")
# Get length of queue
print(len(pq)) # Output: 0
# Peek at highest priority item without removing it
task_queue.push("Important task", priority=1)
print(task_queue.peek()) # Output: "Important task"
```
## Advanced Usage Examples
### Context Manager (with statement)
```python
from simpledsa import PriorityQueue
# Queue is automatically cleared when exiting the with block
with PriorityQueue() as pq:
pq.push("task1", 1)
pq.push("task2", 2)
process_tasks(pq) # process tasks here
# queue is now empty
# Great for temporary task processing
with PriorityQueue() as pq:
pq.extend(tasks)
while pq:
process(pq.pop())
```
### Batch Operations
```python
# Add multiple items at once
pq = PriorityQueue()
pq.extend([1, 2, 3]) # items as their own priorities
pq.extend([("task1", 1), ("task2", 2)]) # For (item, priority) pairs
# Create queue from items
pq = PriorityQueue.from_items([1, 2, 3])
# Create queue from (item, priority) pairs
pq = PriorityQueue.from_items_with_priority([("task1", 1), ("task2", 2)])
```
### Iteration
```python
# Non-destructive iteration (keeps items in queue)
pq = PriorityQueue.from_items([3, 1, 4, 1, 5])
for item in pq:
print(item) # prints in priority order: 1, 1, 3, 4, 5
# Destructive iteration (removes items)
for item in pq.pop_all():
process(item) # process items in priority order
```
### Queue Merging
```python
# Merge multiple queues
pq1 = PriorityQueue.from_items([1, 3, 5])
pq2 = PriorityQueue.from_items([2, 4, 6])
merged = PriorityQueue.merge([pq1, pq2])
```
### Priority Functions
```python
from simpledsa import PriorityQueue, priority_functions
# Max heap (larger values have higher priority)
max_pq = PriorityQueue(priority_functions.reverse)
max_pq.extend([1, 2, 3])
print(max_pq.pop()) # 3
# Priority by length
length_pq = PriorityQueue(priority_functions.by_length)
length_pq.extend(["a", "ccc", "bb"])
print(length_pq.pop()) # "a" (shortest)
# Priority by attribute
class Task:
def __init__(self, name, priority):
self.name = name
self.priority = priority
task_pq = PriorityQueue(priority_functions.by_attr('priority'))
tasks = [Task("A", 2), Task("B", 1), Task("C", 3)]
task_pq.extend(tasks)
```
### Features
- Supports both min-heap (default) and max-heap behavior
- Items can serve as their own priority or have explicit priorities
- Stable sorting: items with equal priorities maintain their insertion order
- Standard Python container operations: `len()`, boolean evaluation
- O(log n) push and pop operations
- O(1) peek and is_empty operations
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Development
### Setting up development environment
```bash
# Clone the repository
git clone https://github.com/dsalathe/simpledsa.git
cd simpledsa
# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -
# Install dependencies
poetry install
# Run tests
poetry run pytest
# Format code
poetry run black .
poetry run isort .
# Type checking
poetry run mypy simpledsa
```
### Building documentation
```bash
cd docs
poetry run make html
```
The documentation will be available in `docs/_build/html`.
### Publishing a new version
1. Update version in pyproject.toml
2. Create and push a new tag:
```bash
git tag v0.1.1
git push origin v0.1.1
```
The GitHub Action will automatically build and publish to PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/dsalathe/simpledsa",
"name": "simpledsa",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8.1",
"maintainer_email": null,
"keywords": "data structures, algorithms, priority queue, heap",
"author": "David Salath\u00e9",
"author_email": "salathe.david@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e6/1e/5c24d75578ca16c38fb7fc5e6ee554838b60011c4e1c7f3fcfd6170dc3e9/simpledsa-0.2.1.tar.gz",
"platform": null,
"description": "# SimpleDSA\n\n[](https://badge.fury.io/py/simpledsa)\n[](https://github.com/dsalathe/simpledsa/actions/workflows/python-package.yml)\n[](https://codecov.io/gh/dsalathe/simpledsa)\n[](https://simpledsa.readthedocs.io/en/latest/?badge=latest)\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/simpledsa/)\n\nA simple and intuitive implementation of data structures and algorithms in Python.\n\n## Installation\n\n```bash\npip install simpledsa\n```\n\n## Usage\n\n### Priority Queue\n\n```python\nfrom simpledsa import PriorityQueue\n\n# Create a min-heap priority queue (smaller values have higher priority)\npq = PriorityQueue()\n\n# Create a max-heap priority queue (larger values have higher priority)\nmax_pq = PriorityQueue(lambda x: -x)\n\n# Using items as their own priority\npq.push(3)\npq.push(1)\npq.push(4)\nprint(pq.pop()) # Output: 1 (smallest value has highest priority)\nprint(pq.pop()) # Output: 3\nprint(pq.pop()) # Output: 4\n\n# Using explicit priorities\ntask_queue = PriorityQueue()\ntask_queue.push(\"Write docs\", priority=2)\ntask_queue.push(\"Fix bug\", priority=1)\ntask_queue.push(\"Add feature\", priority=3)\n\nprint(task_queue.pop()) # Output: \"Fix bug\" (priority 1)\nprint(task_queue.pop()) # Output: \"Write docs\" (priority 2)\nprint(task_queue.pop()) # Output: \"Add feature\" (priority 3)\n\n# Check if queue is empty\nif not pq:\n print(\"Queue is empty\")\n\n# Get length of queue\nprint(len(pq)) # Output: 0\n\n# Peek at highest priority item without removing it\ntask_queue.push(\"Important task\", priority=1)\nprint(task_queue.peek()) # Output: \"Important task\"\n```\n\n## Advanced Usage Examples\n\n### Context Manager (with statement)\n\n```python\nfrom simpledsa import PriorityQueue\n\n# Queue is automatically cleared when exiting the with block\nwith PriorityQueue() as pq:\n pq.push(\"task1\", 1)\n pq.push(\"task2\", 2)\n process_tasks(pq) # process tasks here\n# queue is now empty\n\n# Great for temporary task processing\nwith PriorityQueue() as pq:\n pq.extend(tasks)\n while pq:\n process(pq.pop())\n```\n\n### Batch Operations\n\n```python\n# Add multiple items at once\npq = PriorityQueue()\npq.extend([1, 2, 3]) # items as their own priorities\npq.extend([(\"task1\", 1), (\"task2\", 2)]) # For (item, priority) pairs\n\n# Create queue from items\npq = PriorityQueue.from_items([1, 2, 3])\n\n# Create queue from (item, priority) pairs\npq = PriorityQueue.from_items_with_priority([(\"task1\", 1), (\"task2\", 2)])\n```\n\n### Iteration\n\n```python\n# Non-destructive iteration (keeps items in queue)\npq = PriorityQueue.from_items([3, 1, 4, 1, 5])\nfor item in pq:\n print(item) # prints in priority order: 1, 1, 3, 4, 5\n\n# Destructive iteration (removes items)\nfor item in pq.pop_all():\n process(item) # process items in priority order\n```\n\n### Queue Merging\n\n```python\n# Merge multiple queues\npq1 = PriorityQueue.from_items([1, 3, 5])\npq2 = PriorityQueue.from_items([2, 4, 6])\nmerged = PriorityQueue.merge([pq1, pq2])\n```\n\n### Priority Functions\n\n```python\nfrom simpledsa import PriorityQueue, priority_functions\n\n# Max heap (larger values have higher priority)\nmax_pq = PriorityQueue(priority_functions.reverse)\nmax_pq.extend([1, 2, 3])\nprint(max_pq.pop()) # 3\n\n# Priority by length\nlength_pq = PriorityQueue(priority_functions.by_length)\nlength_pq.extend([\"a\", \"ccc\", \"bb\"])\nprint(length_pq.pop()) # \"a\" (shortest)\n\n# Priority by attribute\nclass Task:\n def __init__(self, name, priority):\n self.name = name\n self.priority = priority\n\ntask_pq = PriorityQueue(priority_functions.by_attr('priority'))\ntasks = [Task(\"A\", 2), Task(\"B\", 1), Task(\"C\", 3)]\ntask_pq.extend(tasks)\n```\n\n### Features\n\n- Supports both min-heap (default) and max-heap behavior\n- Items can serve as their own priority or have explicit priorities\n- Stable sorting: items with equal priorities maintain their insertion order\n- Standard Python container operations: `len()`, boolean evaluation\n- O(log n) push and pop operations\n- O(1) peek and is_empty operations\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Development\n\n### Setting up development environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/dsalathe/simpledsa.git\ncd simpledsa\n\n# Install Poetry\ncurl -sSL https://install.python-poetry.org | python3 -\n\n# Install dependencies\npoetry install\n\n# Run tests\npoetry run pytest\n\n# Format code\npoetry run black .\npoetry run isort .\n\n# Type checking\npoetry run mypy simpledsa\n```\n\n### Building documentation\n\n```bash\ncd docs\npoetry run make html\n```\n\nThe documentation will be available in `docs/_build/html`.\n\n### Publishing a new version\n\n1. Update version in pyproject.toml\n2. Create and push a new tag:\n\n```bash\ngit tag v0.1.1\ngit push origin v0.1.1\n```\n\nThe GitHub Action will automatically build and publish to PyPI.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple and intuitive implementation of data structures and algorithms",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://simpledsa.readthedocs.io",
"Homepage": "https://github.com/dsalathe/simpledsa",
"Repository": "https://github.com/dsalathe/simpledsa"
},
"split_keywords": [
"data structures",
" algorithms",
" priority queue",
" heap"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "accda95bdb431b952938a946082a1a6fc9b0aea4fc531e3a15e158f39e88227a",
"md5": "94be8a898489bf55dc8930c4093066e1",
"sha256": "cf1486dce672e8c6a3f06ad6ae5784bae65d9ce51bfe4bdebb3df575283b9b18"
},
"downloads": -1,
"filename": "simpledsa-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "94be8a898489bf55dc8930c4093066e1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8.1",
"size": 6388,
"upload_time": "2024-11-03T10:43:55",
"upload_time_iso_8601": "2024-11-03T10:43:55.071130Z",
"url": "https://files.pythonhosted.org/packages/ac/cd/a95bdb431b952938a946082a1a6fc9b0aea4fc531e3a15e158f39e88227a/simpledsa-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e61e5c24d75578ca16c38fb7fc5e6ee554838b60011c4e1c7f3fcfd6170dc3e9",
"md5": "949316146e100cad92c3f47149fccc76",
"sha256": "7fb384c9d26f021aab5dd4a32cc0eaa28b1eda0ec9cacc972983e2a32d5f0c38"
},
"downloads": -1,
"filename": "simpledsa-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "949316146e100cad92c3f47149fccc76",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8.1",
"size": 5620,
"upload_time": "2024-11-03T10:43:56",
"upload_time_iso_8601": "2024-11-03T10:43:56.402834Z",
"url": "https://files.pythonhosted.org/packages/e6/1e/5c24d75578ca16c38fb7fc5e6ee554838b60011c4e1c7f3fcfd6170dc3e9/simpledsa-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-03 10:43:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dsalathe",
"github_project": "simpledsa",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "simpledsa"
}
JSON
