open-shield-python 0.1.0__tar.gz

open_shield_python-0.1.0/.agent/rules.md

@@ -0,0 +1,19 @@
+# Agent Rules for Open Shield
+
+These rules apply to any AI agent working on this codebase.
+
+## 🛡️ Critical Workflows
+
+1. **Verify Before Push**: 
+   - You MUST run `./scripts/verify.sh` or use the `/safe-commit` workflow before pushing any code to `main` or `staging`.
+   - If verification fails, **DO NOT** push. Fix the errors first.
+
+2. **Clean Architecture**:
+   - Respect the dependency rule: `Domain` <- `Adapters` <- `App/API`.
+   - Domain entities/ports must NOT import from adapters or external frameworks (except generic types).
+
+3. **Conventional Commits**:
+   - Use strict conventional commits (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`).
+
+4. **Self-Correction**:
+   - If a tool fails (e.g., `ruff` finds errors), attempt to fix it automatically using the tool's suggestions (e.g., `ruff check --fix`) before asking the user, unless the fix is ambiguous.

open_shield_python-0.1.0/.agent/skills/python-packaging/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: python-packaging
+description: Create distributable Python packages with proper project structure, setup.py/pyproject.toml, and publishing to PyPI. Use when packaging Python libraries, creating CLI tools, or distributing Python code.
+---
+
+# Python Packaging
+
+Comprehensive guide to creating, structuring, and distributing Python packages using modern packaging tools, pyproject.toml, and publishing to PyPI.
+
+## Use this skill when
+
+- Creating Python libraries for distribution
+- Building command-line tools with entry points
+- Publishing packages to PyPI or private repositories
+- Setting up Python project structure
+- Creating installable packages with dependencies
+- Building wheels and source distributions
+- Versioning and releasing Python packages
+- Creating namespace packages
+- Implementing package metadata and classifiers
+
+## Do not use this skill when
+
+- The task is unrelated to python packaging
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.

open_shield_python-0.1.0/.agent/skills/python-packaging/resources/implementation-playbook.md

@@ -0,0 +1,405 @@
+# Python Packaging Implementation Playbook
+This file contains detailed patterns, checklists, and code samples referenced by the skill.
+
+# Python Packaging
+Comprehensive guide to creating, structuring, and distributing Python packages using modern packaging tools, pyproject.toml, and publishing to PyPI.
+
+### 1. Package Structure
+- **Source layout**: `src/package_name/` (recommended)
+- **Flat layout**: `package_name/` (simpler but less flexible)
+- **Package metadata**: pyproject.toml, setup.py, or setup.cfg
+- **Distribution formats**: wheel (.whl) and source distribution (.tar.gz)
+
+### 2. Modern Packaging Standards
+- **PEP 517/518**: Build system requirements
+- **PEP 621**: Metadata in pyproject.toml
+- **PEP 660**: Editable installs
+- **pyproject.toml**: Single source of configuration
+
+### 3. Build Backends
+- **setuptools**: Traditional, widely used
+- **hatchling**: Modern, opinionated
+- **flit**: Lightweight, for pure Python
+- **poetry**: Dependency management + packaging
+
+### 4. Distribution
+- **PyPI**: Python Package Index (public)
+- **TestPyPI**: Testing before production
+- **Private repositories**: JFrog, AWS CodeArtifact, etc.
+
+### Minimal Package Structure
+```
+my-package/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── src/
+│   └── my_package/
+│       ├── __init__.py
+│       └── module.py
+└── tests/
+    └── test_module.py
+```
+
+### Minimal pyproject.toml
+```toml
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "my-package"
+version = "0.1.0"
+description = "A short description"
+authors = [{name = "Your Name", email = "you@example.com"}]
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "black>=22.0",
+]
+```
+
+### Pattern 1: Source Layout (Recommended)
+```
+my-package/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── .gitignore
+├── src/
+│   └── my_package/
+│       ├── __init__.py
+│       ├── core.py
+│       ├── utils.py
+│       └── py.typed          # For type hints
+├── tests/
+│   ├── __init__.py
+│   ├── test_core.py
+│   └── test_utils.py
+└── docs/
+    └── index.md
+```
+
+**Advantages:**
+- Prevents accidentally importing from source
+- Cleaner test imports
+- Better isolation
+
+**pyproject.toml for source layout:**
+```toml
+[tool.setuptools.packages.find]
+where = ["src"]
+```
+
+### Pattern 2: Flat Layout
+```
+my-package/
+├── pyproject.toml
+├── README.md
+├── my_package/
+│   ├── __init__.py
+│   └── module.py
+└── tests/
+    └── test_module.py
+```
+
+**Simpler but:**
+- Can import package without installing
+- Less professional for libraries
+
+### Pattern 3: Multi-Package Project
+```
+project/
+├── pyproject.toml
+├── packages/
+│   ├── package-a/
+│   │   └── src/
+│   │       └── package_a/
+│   └── package-b/
+│       └── src/
+│           └── package_b/
+└── tests/
+```
+
+### Pattern 4: Full-Featured pyproject.toml
+```toml
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "my-awesome-package"
+version = "1.0.0"
+description = "An awesome Python package"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Your Name", email = "you@example.com"},
+]
+maintainers = [
+    {name = "Maintainer Name", email = "maintainer@example.com"},
+]
+keywords = ["example", "package", "awesome"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "requests>=2.28.0,<3.0.0",
+    "click>=8.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+docs = [
+    "sphinx>=5.0.0",
+    "sphinx-rtd-theme>=1.0.0",
+]
+all = [
+    "my-awesome-package[dev,docs]",
+]
+
+[project.urls]
+Homepage = "https://github.com/username/my-awesome-package"
+Documentation = "https://my-awesome-package.readthedocs.io"
+Repository = "https://github.com/username/my-awesome-package"
+"Bug Tracker" = "https://github.com/username/my-awesome-package/issues"
+Changelog = "https://github.com/username/my-awesome-package/blob/main/CHANGELOG.md"
+
+[project.scripts]
+my-cli = "my_package.cli:main"
+awesome-tool = "my_package.tools:run"
+
+[project.entry-points."my_package.plugins"]
+plugin1 = "my_package.plugins:plugin1"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+zip-safe = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["my_package*"]
+exclude = ["tests*"]
+
+[tool.setuptools.package-data]
+my_package = ["py.typed", "*.pyi", "data/*.json"]
+
+# Black configuration
+[tool.black]
+line-length = 100
+target-version = ["py38", "py39", "py310", "py311"]
+include = '\.pyi?$'
+
+# Ruff configuration
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+# MyPy configuration
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+# Pytest configuration
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --cov=my_package --cov-report=term-missing"
+
+# Coverage configuration
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+]
+```
+
+### Pattern 5: Dynamic Versioning
+```toml
+[build-system]
+requires = ["setuptools>=61.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "my-package"
+dynamic = ["version"]
+description = "Package with dynamic version"
+
+[tool.setuptools.dynamic]
+version = {attr = "my_package.__version__"}
+
+# Or use setuptools-scm for git-based versioning
+[tool.setuptools_scm]
+write_to = "src/my_package/_version.py"
+```
+
+**In __init__.py:**
+```python
+# src/my_package/__init__.py
+__version__ = "1.0.0"
+
+# Or with setuptools-scm
+from importlib.metadata import version
+__version__ = version("my-package")
+```
+
+### Pattern 8: Build Package Locally
+```bash
+# Install build tools
+pip install build twine
+
+# Build distribution
+python -m build
+
+# This creates:
+# dist/
+#   my-package-1.0.0.tar.gz (source distribution)
+#   my_package-1.0.0-py3-none-any.whl (wheel)
+
+# Check the distribution
+twine check dist/*
+```
+
+### Pattern 9: Publishing to PyPI
+```bash
+# Install publishing tools
+pip install twine
+
+# Test on TestPyPI first
+twine upload --repository testpypi dist/*
+
+# Install from TestPyPI to test
+pip install --index-url https://test.pypi.org/simple/ my-package
+
+# If all good, publish to PyPI
+twine upload dist/*
+```
+
+**Using API tokens (recommended):**
+```bash
+# Create ~/.pypirc
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-...your-token...
+
+[testpypi]
+username = __token__
+password = pypi-...your-test-token...
+```
+
+### Pattern 10: Automated Publishing with GitHub Actions
+```yaml
+# .github/workflows/publish.yml
+name: Publish to PyPI
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*
+```
+
+### Pattern 19: Multi-Architecture Wheels
+```yaml
+# .github/workflows/wheels.yml
+name: Build wheels
+
+on: [push, pull_request]
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.16.2
+
+      - uses: actions/upload-artifact@v3
+        with:
+          path: ./wheelhouse/*.whl
+```
+
+### Pattern 20: Private Package Index
+```bash
+# Install from private index
+pip install my-package --index-url https://private.pypi.org/simple/
+
+# Or add to pip.conf
+[global]
+index-url = https://private.pypi.org/simple/
+extra-index-url = https://pypi.org/simple/
+
+# Upload to private index
+twine upload --repository-url https://private.pypi.org/ dist/*
+```

open_shield_python-0.1.0/.agent/skills/python-pro/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: python-pro
+description: Master Python 3.12+ with modern features, async programming,
+  performance optimization, and production-ready practices. Expert in the latest
+  Python ecosystem including uv, ruff, pydantic, and FastAPI. Use PROACTIVELY
+  for Python development, optimization, or advanced Python patterns.
+metadata:
+  model: opus
+---
+You are a Python expert specializing in modern Python 3.12+ development with cutting-edge tools and practices from the 2024/2025 ecosystem.
+
+## Use this skill when
+- Writing or reviewing Python 3.12+ codebases
+- Implementing async workflows or performance optimizations
+- Designing production-ready Python services or tooling
+
+## Do not use this skill when
+- You need guidance for a non-Python stack
+- You only need basic syntax tutoring
+- You cannot modify Python runtime or dependencies
+
+## Instructions
+1. Confirm runtime, dependencies, and performance targets.
+2. Choose patterns (async, typing, tooling) that match requirements.
+3. Implement and test with modern tooling.
+4. Profile and tune for latency, memory, and correctness.
+
+## Purpose
+Expert Python developer mastering Python 3.12+ features, modern tooling, and production-ready development practices. Deep knowledge of the current Python ecosystem including package management with uv, code quality with ruff, and building high-performance applications with async patterns.
+
+## Capabilities
+
+### Modern Python Features
+- Python 3.12+ features including improved error messages, performance optimizations, and type system enhancements
+- Advanced async/await patterns with asyncio, aiohttp, and trio
+- Context managers and the `with` statement for resource management
+- Dataclasses, Pydantic models, and modern data validation
+- Pattern matching (structural pattern matching) and match statements
+- Type hints, generics, and Protocol typing for robust type safety
+- Descriptors, metaclasses, and advanced object-oriented patterns
+- Generator expressions, itertools, and memory-efficient data processing
+
+### Modern Tooling & Development Environment
+- Package management with uv (2024's fastest Python package manager)
+- Code formatting and linting with ruff (replacing black, isort, flake8)
+- Static type checking with mypy and pyright
+- Project configuration with pyproject.toml (modern standard)
+- Virtual environment management with venv, pipenv, or uv
+- Pre-commit hooks for code quality automation
+- Modern Python packaging and distribution practices
+- Dependency management and lock files
+
+### Testing & Quality Assurance
+- Comprehensive testing with pytest and pytest plugins
+- Property-based testing with Hypothesis
+- Test fixtures, factories, and mock objects
+- Coverage analysis with pytest-cov and coverage.py
+- Performance testing and benchmarking with pytest-benchmark
+- Integration testing and test databases
+- Continuous integration with GitHub Actions
+- Code quality metrics and static analysis
+
+### Performance & Optimization
+- Profiling with cProfile, py-spy, and memory_profiler
+- Performance optimization techniques and bottleneck identification
+- Async programming for I/O-bound operations
+- Multiprocessing and concurrent.futures for CPU-bound tasks
+- Memory optimization and garbage collection understanding
+- Caching strategies with functools.lru_cache and external caches
+- Database optimization with SQLAlchemy and async ORMs
+- NumPy, Pandas optimization for data processing
+
+### Web Development & APIs
+- FastAPI for high-performance APIs with automatic documentation
+- Django for full-featured web applications
+- Flask for lightweight web services
+- Pydantic for data validation and serialization
+- SQLAlchemy 2.0+ with async support
+- Background task processing with Celery and Redis
+- WebSocket support with FastAPI and Django Channels
+- Authentication and authorization patterns
+
+### Data Science & Machine Learning
+- NumPy and Pandas for data manipulation and analysis
+- Matplotlib, Seaborn, and Plotly for data visualization
+- Scikit-learn for machine learning workflows
+- Jupyter notebooks and IPython for interactive development
+- Data pipeline design and ETL processes
+- Integration with modern ML libraries (PyTorch, TensorFlow)
+- Data validation and quality assurance
+- Performance optimization for large datasets
+
+### DevOps & Production Deployment
+- Docker containerization and multi-stage builds
+- Kubernetes deployment and scaling strategies
+- Cloud deployment (AWS, GCP, Azure) with Python services
+- Monitoring and logging with structured logging and APM tools
+- Configuration management and environment variables
+- Security best practices and vulnerability scanning
+- CI/CD pipelines and automated testing
+- Performance monitoring and alerting
+
+### Advanced Python Patterns
+- Design patterns implementation (Singleton, Factory, Observer, etc.)
+- SOLID principles in Python development
+- Dependency injection and inversion of control
+- Event-driven architecture and messaging patterns
+- Functional programming concepts and tools
+- Advanced decorators and context managers
+- Metaprogramming and dynamic code generation
+- Plugin architectures and extensible systems
+
+## Behavioral Traits
+- Follows PEP 8 and modern Python idioms consistently
+- Prioritizes code readability and maintainability
+- Uses type hints throughout for better code documentation
+- Implements comprehensive error handling with custom exceptions
+- Writes extensive tests with high coverage (>90%)
+- Leverages Python's standard library before external dependencies
+- Focuses on performance optimization when needed
+- Documents code thoroughly with docstrings and examples
+- Stays current with latest Python releases and ecosystem changes
+- Emphasizes security and best practices in production code
+
+## Knowledge Base
+- Python 3.12+ language features and performance improvements
+- Modern Python tooling ecosystem (uv, ruff, pyright)
+- Current web framework best practices (FastAPI, Django 5.x)
+- Async programming patterns and asyncio ecosystem
+- Data science and machine learning Python stack
+- Modern deployment and containerization strategies
+- Python packaging and distribution best practices
+- Security considerations and vulnerability prevention
+- Performance profiling and optimization techniques
+- Testing strategies and quality assurance practices
+
+## Response Approach
+1. **Analyze requirements** for modern Python best practices
+2. **Suggest current tools and patterns** from the 2024/2025 ecosystem
+3. **Provide production-ready code** with proper error handling and type hints
+4. **Include comprehensive tests** with pytest and appropriate fixtures
+5. **Consider performance implications** and suggest optimizations
+6. **Document security considerations** and best practices
+7. **Recommend modern tooling** for development workflow
+8. **Include deployment strategies** when applicable
+
+## Example Interactions
+- "Help me migrate from pip to uv for package management"
+- "Optimize this Python code for better async performance"
+- "Design a FastAPI application with proper error handling and validation"
+- "Set up a modern Python project with ruff, mypy, and pytest"
+- "Implement a high-performance data processing pipeline"
+- "Create a production-ready Dockerfile for a Python application"
+- "Design a scalable background task system with Celery"
+- "Implement modern authentication patterns in FastAPI"

open_shield_python-0.1.0/.agent/skills/python-testing-patterns/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: python-testing-patterns
+description: Implement comprehensive testing strategies with pytest, fixtures, mocking, and test-driven development. Use when writing Python tests, setting up test suites, or implementing testing best practices.
+---
+
+# Python Testing Patterns
+
+Comprehensive guide to implementing robust testing strategies in Python using pytest, fixtures, mocking, parameterization, and test-driven development practices.
+
+## Use this skill when
+
+- Writing unit tests for Python code
+- Setting up test suites and test infrastructure
+- Implementing test-driven development (TDD)
+- Creating integration tests for APIs and services
+- Mocking external dependencies and services
+- Testing async code and concurrent operations
+- Setting up continuous testing in CI/CD
+- Implementing property-based testing
+- Testing database operations
+- Debugging failing tests
+
+## Do not use this skill when
+
+- The task is unrelated to python testing patterns
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.