Feature: Modernize Project, Add Dynamic Ruleset Injection & README Tests

[zinthose]

This pull request merges a comprehensive set of enhancements into master, significantly modernizing the pureshell project's development environment, improving code quality, and introducing key new features.

Key Highlights:

1. Dynamic Ruleset Injection:

   • StatefulEntity now supports the injection of a Ruleset instance at instantiation time. This allows for more flexible and dynamic behaviors, such as implementing the Strategy pattern or using mock rulesets for testing.
   • The PureShellMethod has been updated to prioritize instance-level rulesets if provided.
   • A new example, examples/dynamic_behavior_example.py, demonstrates this new capability.
   • Comprehensive unit tests have been added to cover various scenarios of dynamic ruleset usage.

2. Development Environment & Tooling Overhaul:

   • Modernized Toolchain: Integrated and configured pytest for testing, flake8 for linting, black for code formatting, isort for import sorting, mypy for static type checking, and coverage.py for test coverage analysis.
   • Pre-commit Hooks: Implemented pre-commit hooks to automate code quality checks (linting, formatting, type checking) before each commit, ensuring consistency and catching issues early.
   • Dependency Management: Updated and organized requirements.txt and requirements-dev.txt.
   • VS Code Integration: Added recommended VS Code extensions (.vscode/extensions.json) and settings (.vscode/settings.json) for an improved development experience.

3. Enhanced Testing Framework:

   • README Code Block Testing: Introduced a robust test (tests/test_readme_examples.py) that uses markdown-it-py to parse the README.md. This test extracts all Python code blocks under their respective headings and executes them, ensuring that all documented examples are correct and functional.
   • Improved Test Coverage: Addressed previous test failures, import errors, and increased overall test coverage.

4. Continuous Integration (CI):

   • Established a GitHub Actions workflow (.github/workflows/ci.yml) that automatically runs linters, formatters, type checkers, and executes the full test suite (including coverage reporting) on every push and pull request to master.

5. Code Quality & Organization:

   • Code Style: The entire codebase has been formatted with black and isort. All flake8 and mypy issues have been resolved.
   • Examples Refactor: Example scripts have been moved into a dedicated examples package and are now run via examples/run.py.
   • Documentation Updates: The README.md has been significantly updated to reflect the new features, improve installation instructions, and enhance clarity.

Verification:

• All pre-commit checks pass successfully.
• All pytest unit tests, including the new README example validation, pass.
• The GitHub Actions CI pipeline completes without errors.

This series of changes aims to make the pureshell project more robust, maintainable, developer-friendly, and feature-rich.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️