@mseep/csv-editor 1.0.0

package/examples/auto_save_overwrite.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Example showing auto-save that overwrites the original file."""
+
+import asyncio
+import tempfile
+import os
+import pandas as pd
+from pathlib import Path
+
+# Setup path for imports
+import sys
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.csv_editor.models.csv_session import CSVSession
+from src.csv_editor.models.auto_save import AutoSaveConfig, AutoSaveMode, AutoSaveStrategy
+from src.csv_editor.models.data_models import OperationType
+
+
+async def overwrite_same_file_example():
+    """Demonstrate auto-save that updates the same file."""
+    
+    print("=" * 60)
+    print("Auto-Save: Overwrite Same File Example")
+    print("=" * 60)
+    
+    # Create a temporary CSV file
+    temp_dir = tempfile.mkdtemp()
+    original_file = os.path.join(temp_dir, "data.csv")
+    
+    # Create initial data
+    initial_data = pd.DataFrame({
+        'product': ['Laptop', 'Mouse', 'Keyboard'],
+        'price': [999.99, 29.99, 79.99],
+        'stock': [50, 200, 150]
+    })
+    
+    # Save initial data to file
+    initial_data.to_csv(original_file, index=False)
+    print(f"\n✓ Created file: {original_file}")
+    print(f"Initial content:\n{initial_data}")
+    
+    # Configure auto-save to OVERWRITE the same file
+    config = AutoSaveConfig(
+        enabled=True,
+        mode=AutoSaveMode.AFTER_OPERATION,  # Save after each operation
+        strategy=AutoSaveStrategy.OVERWRITE,  # Overwrite the original file
+    )
+    
+    # Create session with auto-save config
+    session = CSVSession(auto_save_config=config)
+    
+    # Load the CSV file
+    df = pd.read_csv(original_file)
+    session.load_data(df, file_path=original_file)  # Pass the original file path
+    
+    print(f"\n✓ Loaded data into session from: {original_file}")
+    
+    # Modify the data
+    print("\n--- Making changes to the data ---")
+    
+    # Change 1: Increase all prices by 10%
+    session.df['price'] = session.df['price'] * 1.1
+    session.record_operation(OperationType.TRANSFORM, {"operation": "price_increase_10%"})
+    await session.trigger_auto_save_if_needed()
+    print("✓ Increased prices by 10% and auto-saved to same file")
+    
+    # Verify the file was updated
+    df_check1 = pd.read_csv(original_file)
+    print(f"File content after price increase:\n{df_check1}")
+    
+    # Change 2: Add a new product
+    new_row = pd.DataFrame({
+        'product': ['Monitor'],
+        'price': [329.989],  # Will be rounded when saved
+        'stock': [75]
+    })
+    session.df = pd.concat([session.df, new_row], ignore_index=True)
+    session.record_operation(OperationType.ADD_COLUMN, {"operation": "add_monitor"})
+    await session.trigger_auto_save_if_needed()
+    print("\n✓ Added new product and auto-saved to same file")
+    
+    # Verify the file was updated again
+    df_check2 = pd.read_csv(original_file)
+    print(f"File content after adding product:\n{df_check2}")
+    
+    # Change 3: Filter out low stock items (this removes data)
+    session.df = session.df[session.df['stock'] >= 100]
+    session.record_operation(OperationType.FILTER, {"condition": "stock >= 100"})
+    await session.trigger_auto_save_if_needed()
+    print("\n✓ Filtered low stock items and auto-saved to same file")
+    
+    # Final verification
+    df_final = pd.read_csv(original_file)
+    print(f"Final file content:\n{df_final}")
+    
+    print("\n" + "=" * 60)
+    print("Summary:")
+    print("=" * 60)
+    print(f"✓ Original file: {original_file}")
+    print("✓ Same file was overwritten after each operation")
+    print("✓ No backup copies were created")
+    print(f"✓ Final file has {len(df_final)} rows (started with {len(initial_data)})")
+    
+    # Show that only one file exists (no backups)
+    files_in_dir = list(Path(temp_dir).glob("*.csv"))
+    print(f"\nFiles in directory: {[f.name for f in files_in_dir]}")
+    print(f"Total CSV files: {len(files_in_dir)} (only the original, no backups)")
+    
+    return original_file
+
+
+async def hybrid_example_with_overwrite():
+    """Example showing overwrite with periodic saves."""
+    
+    print("\n" + "=" * 60)
+    print("Hybrid Mode with Overwrite Example")
+    print("=" * 60)
+    
+    # Create a temporary CSV file
+    temp_dir = tempfile.mkdtemp()
+    original_file = os.path.join(temp_dir, "periodic_data.csv")
+    
+    # Create initial data
+    data = pd.DataFrame({
+        'id': [1, 2, 3],
+        'value': [100, 200, 300]
+    })
+    data.to_csv(original_file, index=False)
+    print(f"\n✓ Created file: {original_file}")
+    
+    # Configure hybrid mode with overwrite
+    config = AutoSaveConfig(
+        enabled=True,
+        mode=AutoSaveMode.HYBRID,  # Both periodic and after-operation
+        strategy=AutoSaveStrategy.OVERWRITE,
+        interval_seconds=2  # Save every 2 seconds
+    )
+    
+    session = CSVSession(auto_save_config=config)
+    df = pd.read_csv(original_file)
+    session.load_data(df, file_path=original_file)
+    
+    # Start periodic saves
+    await session.auto_save_manager.start_periodic_save(session._save_callback)
+    print("✓ Started periodic auto-save (every 2 seconds)")
+    
+    # Make some changes
+    print("\nMaking gradual changes...")
+    
+    # Change 1
+    session.df['value'] = session.df['value'] + 10
+    print("  Added 10 to all values")
+    
+    # Wait for periodic save
+    await asyncio.sleep(2.5)
+    
+    # Change 2
+    session.df['value'] = session.df['value'] * 2
+    session.record_operation(OperationType.TRANSFORM, {"operation": "double_values"})
+    await session.trigger_auto_save_if_needed()
+    print("  Doubled all values (triggered immediate save)")
+    
+    # Wait for another periodic save
+    await asyncio.sleep(2.5)
+    
+    # Stop periodic saves
+    await session.auto_save_manager.stop_periodic_save()
+    print("\n✓ Stopped periodic saves")
+    
+    # Check final file
+    df_final = pd.read_csv(original_file)
+    print(f"\nFinal file content:\n{df_final}")
+    
+    return original_file
+
+
+async def main():
+    """Run all examples."""
+    
+    # Example 1: Simple overwrite
+    file1 = await overwrite_same_file_example()
+    
+    # Example 2: Hybrid mode with overwrite
+    file2 = await hybrid_example_with_overwrite()
+    
+    print("\n" + "=" * 60)
+    print("✅ All examples completed!")
+    print("=" * 60)
+    print("\nKey Takeaways:")
+    print("• Use strategy='overwrite' to update the same file")
+    print("• Original file path must be provided when loading data")
+    print("• No backup copies are created with overwrite strategy")
+    print("• Works with all modes: after_operation, periodic, hybrid")
+    print("\nFor production use, consider:")
+    print("• Backup strategy for safety (creates copies)")
+    print("• Overwrite strategy for direct updates")
+    print("• Hybrid mode for maximum protection")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/examples/basic_usage.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python
+"""
+Basic usage example for CSV MCP Server
+
+This script demonstrates basic CSV operations using the server's tools.
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from src.csv_editor.tools.io_operations import (
+    load_csv_from_content,
+    export_csv,
+    get_session_info
+)
+from src.csv_editor.tools.transformations import (
+    filter_rows,
+    sort_data,
+    fill_missing_values
+)
+from src.csv_editor.tools.analytics import (
+    get_statistics,
+    get_column_statistics
+)
+
+# Sample CSV data
+SAMPLE_DATA = """product,category,price,quantity,date
+Laptop,Electronics,999.99,10,2024-01-15
+Mouse,Electronics,29.99,50,2024-01-16
+Desk,Furniture,299.99,5,2024-01-17
+Chair,Furniture,149.99,15,2024-01-18
+Keyboard,Electronics,79.99,25,2024-01-19
+Monitor,Electronics,399.99,8,2024-01-20
+Bookshelf,Furniture,199.99,7,2024-01-21
+Headphones,Electronics,89.99,20,2024-01-22
+Table,Furniture,499.99,3,2024-01-23
+Webcam,Electronics,59.99,30,2024-01-24
+"""
+
+async def main():
+    print("CSV MCP Server - Basic Usage Example")
+    print("=" * 40)
+    
+    # 1. Load CSV data
+    print("\n1. Loading CSV data...")
+    result = await load_csv_from_content(
+        content=SAMPLE_DATA,
+        delimiter=","
+    )
+    
+    if not result["success"]:
+        print(f"Failed to load data: {result.get('error', 'Unknown error')}")
+        return
+    
+    session_id = result["session_id"]
+    print(f"✓ Loaded {result['rows_affected']} rows")
+    print(f"  Session ID: {session_id}")
+    print(f"  Columns: {', '.join(result['columns_affected'])}")
+    
+    # 2. Get statistics
+    print("\n2. Calculating statistics...")
+    stats = await get_statistics(
+        session_id=session_id,
+        columns=["price", "quantity"]
+    )
+    
+    if stats["success"]:
+        print("✓ Statistics calculated:")
+        for col, col_stats in stats["statistics"].items():
+            if isinstance(col_stats, dict):
+                print(f"\n  {col}:")
+                print(f"    Mean: ${col_stats.get('mean', 0):.2f}" if col == "price" else f"    Mean: {col_stats.get('mean', 0):.1f}")
+                print(f"    Min: ${col_stats.get('min', 0):.2f}" if col == "price" else f"    Min: {col_stats.get('min', 0):.0f}")
+                print(f"    Max: ${col_stats.get('max', 0):.2f}" if col == "price" else f"    Max: {col_stats.get('max', 0):.0f}")
+    
+    # 3. Filter data
+    print("\n3. Filtering electronics over $50...")
+    filtered = await filter_rows(
+        session_id=session_id,
+        conditions=[
+            {"column": "category", "operator": "==", "value": "Electronics"},
+            {"column": "price", "operator": ">", "value": 50}
+        ],
+        mode="and"
+    )
+    
+    if filtered["success"]:
+        print(f"✓ Filtered: {filtered['rows_before']} → {filtered['rows_after']} rows")
+    
+    # 4. Sort data
+    print("\n4. Sorting by price (descending)...")
+    sorted_result = await sort_data(
+        session_id=session_id,
+        columns=[{"column": "price", "ascending": False}]
+    )
+    
+    if sorted_result["success"]:
+        print("✓ Data sorted by price")
+    
+    # 5. Export results
+    print("\n5. Exporting results...")
+    output_dir = Path("output")
+    output_dir.mkdir(exist_ok=True)
+    
+    # Export as JSON
+    json_file = output_dir / "filtered_products.json"
+    export_result = await export_csv(
+        session_id=session_id,
+        file_path=str(json_file),
+        format="json"
+    )
+    
+    if export_result["success"]:
+        print(f"✓ Exported to: {json_file}")
+    
+    # Export as CSV
+    csv_file = output_dir / "filtered_products.csv"
+    export_result = await export_csv(
+        session_id=session_id,
+        file_path=str(csv_file),
+        format="csv"
+    )
+    
+    if export_result["success"]:
+        print(f"✓ Exported to: {csv_file}")
+    
+    print("\n" + "=" * 40)
+    print("Example completed successfully!")
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/examples/demo.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python
+"""
+CSV MCP Server Demo
+
+Demonstrates the full capabilities of the CSV MCP Server.
+Run this to see all features in action.
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from src.csv_editor.tools.io_operations import load_csv_from_content
+from src.csv_editor.tools.transformations import filter_rows, sort_data
+from src.csv_editor.tools.analytics import get_statistics, profile_data
+from src.csv_editor.tools.validation import check_data_quality
+
+# Demo data
+DEMO_CSV = """employee_id,name,department,salary,years_experience,performance_rating
+1001,Alice Johnson,Engineering,95000,5,4.5
+1002,Bob Smith,Marketing,65000,3,3.8
+1003,Charlie Davis,Engineering,105000,7,4.7
+1004,Diana Wilson,Sales,72000,4,4.2
+1005,Eve Martinez,Engineering,88000,4,4.1
+1006,Frank Brown,Marketing,58000,2,3.5
+1007,Grace Lee,Sales,78000,5,4.4
+1008,Henry Taylor,Engineering,115000,10,4.9
+1009,Iris Chen,Marketing,70000,4,4.0
+1010,Jack White,Sales,68000,3,3.9
+"""
+
+class Demo:
+    @staticmethod
+    def header(title: str):
+        print(f"\n{'='*50}")
+        print(f"  {title}")
+        print(f"{'='*50}")
+    
+    @staticmethod
+    def success(msg: str):
+        print(f"✅ {msg}")
+    
+    @staticmethod
+    def info(msg: str):
+        print(f"ℹ️  {msg}")
+    
+    @staticmethod
+    def result(label: str, value: any):
+        print(f"   {label}: {value}")
+
+async def run_demo():
+    Demo.header("CSV MCP Server - Feature Demo")
+    
+    # Load data
+    Demo.info("Loading employee data...")
+    result = await load_csv_from_content(content=DEMO_CSV)
+    
+    if not result["success"]:
+        print(f"Error loading data: {result.get('error')}")
+        return
+    
+    session_id = result["session_id"]
+    Demo.success(f"Loaded {result['rows_affected']} employees")
+    
+    # Data Quality Check
+    Demo.header("Data Quality Assessment")
+    quality = await check_data_quality(session_id=session_id)
+    
+    if quality["success"]:
+        metrics = quality["quality_results"]["metrics"]
+        Demo.result("Overall Score", f"{quality['quality_results']['overall_score']:.1f}%")
+        Demo.result("Completeness", f"{metrics['completeness']:.1f}%")
+        Demo.result("Uniqueness", f"{metrics['uniqueness']:.1f}%")
+        Demo.result("Consistency", f"{metrics['consistency']:.1f}%")
+    
+    # Statistics
+    Demo.header("Salary Statistics by Department")
+    stats = await get_statistics(
+        session_id=session_id,
+        columns=["salary", "years_experience", "performance_rating"]
+    )
+    
+    if stats["success"]:
+        salary_stats = stats["statistics"].get("salary", {})
+        Demo.result("Average Salary", f"${salary_stats.get('mean', 0):,.2f}")
+        Demo.result("Salary Range", f"${salary_stats.get('min', 0):,.0f} - ${salary_stats.get('max', 0):,.0f}")
+        Demo.result("Median Salary", f"${salary_stats.get('50%', 0):,.2f}")
+    
+    # Filter high performers
+    Demo.header("High Performers Analysis")
+    filtered = await filter_rows(
+        session_id=session_id,
+        conditions=[
+            {"column": "performance_rating", "operator": ">=", "value": 4.0},
+            {"column": "salary", "operator": ">", "value": 70000}
+        ],
+        mode="and"
+    )
+    
+    if filtered["success"]:
+        Demo.success(f"Found {filtered['rows_after']} high performers")
+        Demo.info(f"({filtered['rows_after']}/{filtered['rows_before']} = {filtered['rows_after']/filtered['rows_before']*100:.1f}% of employees)")
+    
+    # Profile the data
+    Demo.header("Data Profile Summary")
+    profile = await profile_data(
+        session_id=session_id,
+        include_correlations=True,
+        include_outliers=False
+    )
+    
+    if profile["success"]:
+        summary = profile["profile"]["summary"]
+        Demo.result("Total Rows", summary["total_rows"])
+        Demo.result("Total Columns", summary["total_columns"])
+        Demo.result("Numeric Columns", summary["numeric_columns"])
+        Demo.result("Text Columns", summary["text_columns"])
+        
+        # Show correlations if any
+        if "correlations" in profile["profile"]:
+            correlations = profile["profile"]["correlations"]
+            if "significant_correlations" in correlations:
+                Demo.info("\nSignificant Correlations:")
+                for corr in correlations["significant_correlations"][:3]:
+                    Demo.result(
+                        f"{corr['column1']} ↔ {corr['column2']}",
+                        f"{corr['correlation']:.3f}"
+                    )
+    
+    Demo.header("Demo Complete!")
+    Demo.success("All features demonstrated successfully")
+    Demo.info(f"Session ID: {session_id}")
+    print()
+
+if __name__ == "__main__":
+    print("\n🚀 Starting CSV MCP Server Demo...\n")
+    asyncio.run(run_demo())