pkstruct 0.1.0__tar.gz → 0.1.2__tar.gz

pkstruct-0.1.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,46 @@
+---
+name: Bug Report
+about: Create a report to help us improve pkstruct
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear and concise description of what the bug is.
+
+## Reproduction
+
+```python
+# Minimal, runnable code that reproduces the issue
+```
+
+## Expected Behavior
+
+```python
+# What you expected to happen
+```
+
+## Actual Behavior
+
+```python
+# What actually happened (include full error output)
+```
+
+## Environment
+
+- Python version:
+- OS:
+- pkstruct version (pip show pkstruct):
+- Installed via: (pip / pipx / from source)
+
+## Additional Context
+
+Add any other context, screenshots, or ASCII visualizations here.
+
+## Checklist
+
+- [ ] I searched existing issues before filing this report
+- [ ] I am running the latest pkstruct version
+- [ ] This is a pkstruct bug, not a usage question

pkstruct-0.1.2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions & Discussions
+    url: https://github.com/prnvvv/pkstruct/discussions
+    about: Ask usage questions and discuss ideas here
+  - name: Security Issues
+    url: https://github.com/prnvvv/pkstruct/security/policy
+    about: Report security vulnerabilities here (do not open a public issue)

pkstruct-0.1.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,37 @@
+---
+name: Feature Request
+about: Suggest an idea for pkstruct
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+A clear description of what problem this feature would solve.
+Ex: I'm always frustrated when [...]
+
+## Proposed Solution
+
+A clear description of what you want to happen, including API design if applicable.
+
+```python
+# Optional: sketch of the API you envision
+```
+
+## Alternatives
+
+Any alternative solutions or workarounds you've considered.
+
+## Scope
+
+- [ ] New data structure
+- [ ] New algorithm / method
+- [ ] Performance improvement
+- [ ] Documentation
+- [ ] Testing
+- [ ] Other (describe below)
+
+## Additional Context
+
+Any other context, references, or examples.

pkstruct-0.1.2/.github/pull_request_template.md

@@ -0,0 +1,29 @@
+## Description
+
+Please include a summary of the changes and which issue is fixed.
+
+Fixes #(issue)
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change)
+- [ ] New feature (non-breaking change)
+- [ ] Breaking change (fix or feature that changes existing API)
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Test addition/improvement
+- [ ] CI/infrastructure change
+
+## Checklist
+
+- [ ] Code follows project style (ruff passes)
+- [ ] Type hints added/updated (mypy passes)
+- [ ] Tests added/updated for new code
+- [ ] All existing tests pass (`python -m pytest`)
+- [ ] CHANGELOG.md updated for user-facing changes
+- [ ] Documentation updated if API changed
+- [ ] I have read the CONTRIBUTING.md guide
+
+## Additional Notes
+
+Any additional context, benchmark results, or design decisions.

pkstruct-0.1.2/.gitignore

@@ -0,0 +1,218 @@
+# ==========================================
+# Python
+# ==========================================
+
+__pycache__/
+*.pyc
+*.pyo
+*.py[cod]
+*$py.class
+
+# Compiled extensions
+*.so
+*.pyd
+*.dll
+
+# Distribution / packaging
+.Python
+build/
+dist/
+downloads/
+develop-eggs/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.whl
+MANIFEST
+*.manifest
+*.spec
+
+# PyPI / packaging tools
+pip-wheel-metadata/
+pip-log.txt
+pip-delete-this-directory.txt
+
+# ==========================================
+# Virtual Environments
+# ==========================================
+
+venv/
+env/
+ENV/
+.venv/
+
+# ==========================================
+# Testing / Coverage
+# ==========================================
+
+.pytest_cache/
+.benchmarks/
+.coverage
+.coverage.*
+coverage/
+coverage.xml
+htmlcov/
+*.cover
+*.py,cover
+.tox/
+.nox/
+
+# Benchmark / profiling outputs
+*.prof
+
+# ==========================================
+# Type Checking / Linting
+# ==========================================
+
+.mypy_cache/
+.pyre/
+.pytype/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# Property-based testing cache
+.hypothesis/
+
+# Merge conflict artifacts
+*.orig
+*.patch
+
+# Node.js (for any JS tooling)
+node_modules/
+
+# pyenv
+.python-version
+
+# Jupyter
+# ==========================================
+
+.ipynb_checkpoints/
+
+# ==========================================
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+*.code-workspace
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+desktop.ini
+
+# ==========================================
+# Logs
+# ==========================================
+
+*.log
+
+# ==========================================
+# Environment Variables
+# ==========================================
+
+.env
+.env.*
+
+# ==========================================
+# Documentation Builds
+# ==========================================
+
+docs/_build/
+site/
+
+# ==========================================
+# MkDocs / Sphinx
+# ==========================================
+
+*.doctree
+
+# ==========================================
+# Temporary Files
+# ==========================================
+
+*.tmp
+*.temp
+*.bak
+
+# ==========================================
+# Package-specific
+# ==========================================
+
+# Generated benchmark results
+benchmarks/results/
+
+# Local experiment scripts
+experiments/
+
+# Local datasets
+data/
+
+# Local test environment (virtual env)
+pkstruct_test_env/
+
+# Manual visual test script
+testing_final.py
+
+# Scratch / experimentation
+*.scratch
+
+# Scratch / experimentation
+eg.py
+manual_test.py
+dsa_testing.py
+
+# pytest speedup files (generated by pytest-xdist)
+*.pytest_cache/
+
+# Cython debug
+cython_debug/
+
+# ==========================================
+# Optional: Ignore generated lock files
+# Uncomment if needed
+
+# poetry.lock
+# Pipfile.lock
+
+# ==========================================
+# OS-specific
+# ==========================================
+*.pyproj
+*.sln
+*.suo
+*.user
+*.userosscache
+*.userprefs
+.vs/
+
+# ==========================================
+# Package build artifacts
+# ==========================================
+*.tar.gz
+PKSTRUCT-INFO
+
+# ==========================================
+# Development artifacts
+# ==========================================
+*.history
+AGENTS.md
+requirements-dev.txt
+
+.gitlab-ci.yml

pkstruct-0.1.2/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to pkstruct will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.2] - 2026-06-16
+
+### Added
+- CONTRIBUTING.md, CODE_OF_CONDUCT.md, MAINTAINERS.md with project governance
+- Issue templates (bug report, feature request) and PR template
+- `py.typed` marker already present for PEP 561 compliance
+
+### Changed
+- README restructured: added "Why pkstruct?" section, removed maintainer-only publishing docs
+- pyproject.toml: updated author list with founders, expanded keywords, added classifiers
+- Badge URLs fixed to match `prnvvv/pkstruct` repository
+
+### Removed
+- AGENTS.md and requirements-dev.txt removed from repository (gitignored)
+- .github/ removed from .gitignore so templates are tracked
+
+## [0.1.1] - 2026-06-02
+
+### Added
+- `__bool__` to all tree types (BST, RedBlack, BTree, BPlus, Interval, Segment, Fenwick) and Graph
+- `__iter__` to SegmentTree, FenwickTree
+- `__contains__` to all 6 linear adapters (ArrayStack, LinkedStack, LinkedQueue, CircularQueue, PriorityQueue, LinkedDeque), SegmentTree, FenwickTree
+- `copy()` to BTree, BPlusTree, IntervalTree, SegmentTree, FenwickTree
+- `validate()`, `to_list()`, `from_list()` to Graph (inherited by DirectedGraph, WeightedGraph)
+- `HelpMixin` to all 6 linear adapters
+- Side validation in `LinkedDeque.append()`, `LinkedDeque.pop()`, `LinkedDeque.peek()`
+
+### Changed
+- BST/AVL `serialize()` now encodes each node as a `[key, value]` pair to prevent data loss on round-trip
+- BST/AVL `deserialize()` handles both new `[key, value]` and legacy bare-key formats
+- BTree/BPlusTree use `InvalidOrderError` instead of `ValueError` in `__init__`
+- `module_help()` raises `ValueError` for invalid targets instead of silently returning `""`
+
+### Fixed
+- BST/AVL serialization no longer silently drops values during round-trip
+- README `str(sll)` example corrected from `"1 2 3"` to `"[1, 2, 3]"`
+
+## [0.1.0] - 2026-06-01
+
+### Added
+- `pkstruct.linear` module with `SinglyLinkedList`, `DoublyLinkedList`, `CircularLinkedList`
+- Full CRUD operations: `insert`, `delete`, `get`, `replace`, `extend`, `clear`
+- Algorithmic operations: `sort`, `merge`, `partition`, `reverse`, `rotate`, `swap`
+- Interview problems: `detect_cycle`, `intersection_node`, `palindrome`, `reorder`, `segregate_even_odd`
+- Serialization: `from_list`, `from_json`, `to_list`, `copy`
+- ASCII visualization with `visualize()` and `debug()` introspection
+- Thread-safe operations via `RLock`
+- Custom exception hierarchy via `pkstruct.linear.exceptions`
+- Shared subsystem (`pkstruct.shared`) for validators, serializers, threading, benchmarking
+- Full pytest suite with edge cases, randomization, and threading tests
+- Benchmark suite comparing against `list` and `collections.deque`
+- Type annotations, mypy strict compliance
+- PyPI-ready packaging with `hatchling`

pkstruct-0.1.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,113 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards.
+They have the right and responsibility to remove, edit, or reject comments,
+commits, code, wiki edits, issues, and other contributions that are not
+aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies
+when an individual is representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**conduct@pkstruct.dev**. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of
+the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation, sustained
+harassment, or aggression toward individuals or classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

pkstruct-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,133 @@
+# Contributing to pkstruct
+
+Thank you for your interest in contributing to pkstruct! This document provides guidelines and instructions for contributing.
+
+## Code of Conduct
+
+By participating, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). Please report unacceptable behavior.
+
+## How to Contribute
+
+### Reporting Bugs
+
+1. Search [existing issues](https://github.com/prnvvv/pkstruct/issues) to avoid duplicates.
+2. Use the **Bug Report** issue template.
+3. Include:
+   - Python version and OS
+   - Minimal reproduction code
+   - Expected vs actual behavior
+   - Full error output if applicable
+
+### Suggesting Features
+
+1. Search [existing issues](https://github.com/prnvvv/pkstruct/issues) first.
+2. Use the **Feature Request** issue template.
+3. Explain the use case and why it belongs in pkstruct.
+
+### Questions
+
+Use the **Question** issue template or start a [Discussion](https://github.com/prnvvv/pkstruct/discussions).
+
+## Development Setup
+
+```bash
+git clone https://github.com/prnvvv/pkstruct.git
+cd pkstruct
+pip install -e ".[dev]"
+```
+
+## Coding Standards
+
+- **Python**: >= 3.10
+- **Type hints**: Required for all public APIs. Run `mypy src/pkstruct` — no errors allowed.
+- **Style**: Run `ruff check src/pkstruct` — no violations allowed.
+- **Line length**: 100 characters.
+- **Imports**: Use Ruff's import ordering (`I` rule set).
+
+### Rules
+
+- No `eval()` or `exec()`.
+- All mutable state must be protected by `threading.RLock`.
+- Public API methods must have type annotations and docstrings.
+- Internal/private methods prefixed with `_`.
+
+## Testing
+
+```bash
+# Run all tests
+python -m pytest
+
+# Run with coverage
+python -m pytest --cov=src/pkstruct
+
+# Run specific test file
+python -m pytest src/pkstruct/linear/tests/test_linked_list.py
+```
+
+- All new code must include tests.
+- Tests should cover normal paths, edge cases, and error conditions.
+- Test files go in the corresponding `tests/` directory.
+
+## Pull Request Process
+
+1. **Create an issue** first for bugs or feature requests (unless trivial).
+2. **Fork the repository** and create a branch from `main`:
+   ```
+   git checkout -b fix/issue-42-description
+   ```
+3. **Make your changes** following the coding standards.
+4. **Run tests** locally to ensure nothing is broken.
+5. **Run type checks** with `mypy src/pkstruct`.
+6. **Run linter** with `ruff check src/pkstruct`.
+7. **Commit** with a clear message:
+   ```
+   feat: add range_update to SegmentTree
+   fix: handle empty list in SinglyLinkedList.sort
+   docs: update README examples
+   ```
+8. **Push** and open a Pull Request.
+9. **Address review feedback** promptly.
+
+## Pull Request Checklist
+
+- [ ] Code follows style guidelines
+- [ ] Type hints added/updated
+- [ ] Tests added/updated
+- [ ] All tests pass
+- [ ] mypy passes with no errors
+- [ ] ruff passes with no violations
+- [ ] CHANGELOG.md updated (if user-facing change)
+- [ ] Documentation updated (if API change)
+
+## Review Expectations
+
+- Maintainers review within 5 business days.
+- Changes may be requested — this is normal.
+- Two approving reviews required for significant changes.
+
+## Project Structure
+
+```
+src/pkstruct/
+├── __init__.py          # Package root, registry, help()
+├── linear/             # Linked lists, stacks, queues, deques
+│   ├── linked_lists/
+│   ├── stacks/
+│   ├── queues/
+│   ├── deques/
+│   ├── tests/
+│   ├── utils/
+│   └── visualization/
+├── trees/              # BST, AVL, Red-Black, B-Tree, Fenwick, Segment, Interval
+│   ├── tests/
+│   └── visualization/
+├── graphs/             # Graph, DirectedGraph, algorithms
+│   └── tests/
+└── shared/             # Validators, serializers, threading, benchmarking
+```
+
+## Getting Help
+
+- Open a [Discussion](https://github.com/prnvvv/pkstruct/discussions)
+- Ask in issue comments
+- Tag `@prnvvv` for maintainer attention

pkstruct-0.1.2/MAINTAINERS.md

@@ -0,0 +1,62 @@
+# Maintainer Guide
+
+This document is for maintainers and release managers of pkstruct.
+
+## Project Leadership
+
+- **Founder & Maintainer**: [Prannavakhanth](https://github.com/prnvvv) — prannavakhanth12@gmail.com
+- **Co-Founder & Maintainer**: [Priyanka Kaliraj](https://github.com/pri-23-k) — pri2303k@gmail.com
+
+## Publishing a Release
+
+```bash
+# 1. Clean any previous builds
+rm -rf dist/
+
+# 2. Build distribution packages
+python -m build
+
+# 3. Verify distribution
+twine check dist/*
+
+# 4. Upload to PyPI
+twine upload dist/*
+
+# 5. Tag the release
+git tag v$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+git push origin --tags
+```
+
+## Before a Release
+
+- [ ] All tests pass: `python -m pytest`
+- [ ] Type check passes: `mypy src/pkstruct`
+- [ ] Lint passes: `ruff check src/pkstruct`
+- [ ] CHANGELOG.md is up to date
+- [ ] Version is bumped in `pyproject.toml`
+- [ ] README example code is verified against release
+
+## Versioning
+
+pkstruct follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html):
+
+- **Patch** (`0.1.0` → `0.1.1`): Bug fixes, minor improvements, no breaking API changes.
+- **Minor** (`0.1.0` → `0.2.0`): New features, deprecations, no breaking API changes (once stable).
+- **Major** (`1.0.0`): Breaking API changes.
+
+## Managing Issues
+
+- Apply appropriate labels: `bug`, `enhancement`, `question`, `good first issue`.
+- Respond to new issues within 48 hours.
+- Close resolved issues with a comment linking to the PR.
+
+## Managing Pull Requests
+
+- Review within 5 business days.
+- Ensure all CI checks pass before merging.
+- Use **Squash and Merge** for feature branches.
+- Update CHANGELOG.md when merging user-facing changes.
+
+## Security Vulnerabilities
+
+See [SECURITY.md](SECURITY.md) for the reporting process.