Expert assistant for developing datafolio, a Python package for managing data science portfolios. Helps with handler-based architecture, dual-level testing, type annotations, and following project standards.
Expert assistant for developing datafolio, a Python package for managing data science portfolios with a handler-based architecture.
This skill helps you work on the datafolio codebase following established conventions:
Use UV for dependency management and Poe for task running:
```bash
uv sync
poe test # Run tests with coverage
poe doc-preview # Preview documentation
poe bump patch # Bump version (patch/minor/major)
```
**Never use system Python directly. Always use `uv run` or `poe` commands.**
**CRITICAL REQUIREMENT: All code must have complete type annotations.**
**Avoiding circular imports:**
```python
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from datafolio.folio import DataFolio
def my_method(self, folio: "DataFolio") -> None: # String quotes for forward reference
...
```
**Before writing any code, verify you understand the expected types. Read related code first.**
**REQUIRED: Implement BOTH levels of testing for every feature/fix.**
#### High-Level Integration Tests
#### Low-Level Unit Tests
**Coverage targets: >75% line coverage, >70% branch coverage**
DataFolio uses a modular handler system (~35-80 lines per handler):
**Core components:**
**Handler template:**
```python
from datafolio.base.handler import BaseHandler
class MyHandler(BaseHandler):
@property
def item_type(self) -> str:
return "my_type" # Must be in ITEM_TYPE_TO_CATEGORY
def can_handle(self, data: Any) -> bool:
return isinstance(data, MyDataType)
def add(self, folio, name, data, **kwargs) -> Dict[str, Any]:
# Write data, return metadata
...
def get(self, folio, name, **kwargs) -> Any:
# Read and return data
...
```
**Adding a new handler:**
1. Create file in `handlers/` directory
2. Inherit from `BaseHandler`, implement required methods
3. Add `item_type` to `ITEM_TYPE_TO_CATEGORY` in `storage/categories.py`
4. Register in `handlers/__init__.py`
5. Add comprehensive unit tests
6. Update integration tests
**Storage is auto-derived from item_type via ITEM_TYPE_TO_CATEGORY mapping.**
**For bug fixes (TDD approach):**
1. Write failing test first
2. Fully describe the problem to confirm it's actually a bug
3. Implement minimal fix
4. Ensure all tests pass
5. Verify type annotations are correct
6. Run full suite: `poe test`
**For new features:**
1. Read related code first to understand patterns
2. Design handler structure if needed (refer to ARCHITECTURE.md)
3. Write integration test for end-to-end workflow
4. Write unit tests for individual methods
5. Implement feature with full type annotations
6. Run `poe test` and ensure >75% coverage
Before any commit:
```bash
poe test
uv run ruff check src/ tests/
poe doc-preview
```
**All Python files must follow ruff guidelines for linting, imports, and code style.**
Use Google/NumPy style docstrings with examples:
```python
def add_points(
self,
data: pd.DataFrame,
point_column: Union[str, List[str]],
segment_column: Optional[str] = None
) -> Self:
"""Add point annotations to the viewer state.
Args:
data: DataFrame containing point data
point_column: Column name(s) for coordinates
segment_column: Optional column containing segment IDs
Returns:
Self for method chaining
Examples:
>>> vs = ViewerState()
>>> vs.add_points(df, point_column=['x', 'y', 'z'])
"""
```
**Adding support for Polars DataFrames:**
1. Create `handlers/polars_handler.py` inheriting from `BaseHandler`
2. Add "polars_dataframe" to `ITEM_TYPE_TO_CATEGORY` → "TABLES"
3. Register in `handlers/__init__.py`
4. Create `tests/test_handlers_polars.py` (unit tests for methods)
5. Update `tests/test_folio_basic.py` (integration test for add/save/load/delete)
6. Run `poe test` to verify >75% coverage
**Fixing a bug in PyTorch model handler:**
1. Write failing test in `tests/test_handlers_pytorch.py`
2. Describe issue to confirm it's a bug vs. intended behavior
3. Fix in `handlers/pytorch_handler.py`
4. Verify type annotations are correct
5. Run `poe test` to ensure all tests pass
6. Check coverage didn't drop
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/datafolio-development-assistant/raw