dbf-processor

SKILL.md

---
name: dbf-processor
description: Process DBF (dBase) files - read, write, convert to CSV/Excel, filter/query data, validate structure, and edit/append records. Use this when users mention DBF files, dBase, FoxPro, or need to work with .dbf files.
---

# DBF File Processor Skill

Process DBF (dBase/FoxPro) files with comprehensive read/write capabilities.

## Core Capabilities

1. **Read DBF files** - Extract data and metadata from DBF files
2. **Write DBF files** - Create new DBF files or modify existing ones
3. **Convert formats** - Export DBF to CSV or Excel, import from CSV
4. **Filter & query** - Search, filter, and query DBF records
5. **Validate structure** - Check DBF file integrity and schema
6. **Edit records** - Modify or append records to DBF files

## Prerequisites

Install required Python packages:
```bash
pip install dbfread dbf pandas openpyxl
```

## Available Scripts

All executable code is located in the `scripts/` directory:

| Script | Purpose |
|--------|---------|
| `read_dbf.py` | Read and display DBF file metadata and sample records |
| `dbf_to_csv.py` | Convert DBF file to CSV format |
| `dbf_to_excel.py` | Convert DBF file to Excel format |
| `filter_dbf.py` | Filter and query records from a DBF file |
| `validate_dbf.py` | Validate DBF file structure and integrity |
| `create_dbf.py` | Create a new DBF file with specified structure |
| `edit_dbf.py` | Edit existing records or append new ones |
| `security_utils.py` | Security utilities for safe file handling |

## Common Workflows

### 1. Read a DBF File

**Input:** User asks to read or inspect a DBF file
**Action:**
- Use the `scripts/read_dbf.py` script
- Display basic metadata (field names, types, record count)
- Show a sample of the data (first 5-10 records)

**Example:**
```bash
python scripts/read_dbf.py path/to/file.dbf utf-8 5
```

### 2. Convert DBF to CSV

**Input:** User wants to convert DBF to CSV
**Action:** Use `scripts/dbf_to_csv.py`

**Example:**
```bash
python scripts/dbf_to_csv.py input.dbf output.csv utf-8
```

### 3. Convert DBF to Excel

**Input:** User wants to convert DBF to Excel
**Action:** Use `scripts/dbf_to_excel.py`

**Example:**
```bash
python scripts/dbf_to_excel.py input.dbf output.xlsx utf-8
```

### 4. Filter/Query DBF Data

**Input:** User wants to filter or query specific records
**Action:** Use `scripts/filter_dbf.py`

**Example:**
```bash
# Equals comparison
python scripts/filter_dbf.py data.dbf STATUS ACTIVE equals utf-8

# Contains comparison
python scripts/filter_dbf.py data.dbf NAME "John" contains utf-8
```

### 5. Validate DBF Structure

**Input:** User wants to check DBF file integrity or schema
**Action:** Use `scripts/validate_dbf.py`

**Example:**
```bash
python scripts/validate_dbf.py file.dbf utf-8
```

### 6. Create/Write DBF File

**Input:** User wants to create a new DBF file or write data
**Action:** Use `scripts/create_dbf.py`

**Example:**
```bash
python scripts/create_dbf.py output.dbf 'NAME C(50)' 'AGE N(3,0)' 'EMAIL C(100)' 'ACTIVE L'
```

### 7. Edit/Append Records

**Input:** User wants to modify existing records or add new ones
**Action:** Use `scripts/edit_dbf.py`

**Example:**
```bash
# Append a single record
python scripts/edit_dbf.py existing.dbf append "New Name" 30 "email@example.com" True

# Append from JSON file
python scripts/edit_dbf.py existing.dbf append_json records.json
```

## Encoding Considerations

DBF files often use specific encodings. Common encodings to try:
- `'utf-8'` - Standard UTF-8
- `'latin-1'` - Western European
- `'cp1252'` - Windows Latin-1
- `'gbk'` - Chinese simplified
- `'cp850'` - DOS Latin-1

If you encounter encoding errors, try different encodings.

## Security Best Practices

When working with DBF files, always follow these security guidelines:

1. **Validate File Inputs** - Use `security_utils.py` for safe file path handling
2. **Avoid Executing Code** - Never use `exec()` or `eval()` with data from DBF files
3. **Sanitize Outputs** - Sanitize data when exporting to other formats
4. **Use Principle of Least Privilege** - Run scripts with minimum permissions needed
5. **Backup Before Modifications** - Always create backups before modifying DBF files

See `scripts/security_utils.py` for security utilities and examples.

## Progressive Disclosure

When the user asks about DBF files:
1. First understand what they want to accomplish (read, write, convert, etc.)
2. Ask for the file path if not provided
3. Offer to show metadata first, then sample data
4. Ask about specific filters or transformations needed
5. Point them to the appropriate script in the `scripts/` directory