csv-diff-tool 0.1.0__tar.gz

csv_diff_tool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ashish Narmen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

csv_diff_tool-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: csv-diff-tool
+Version: 0.1.0
+Summary: A package for comparing CSV files
+Author-email: Ashish N <ashish012@e.ntu.edu.sg>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ashishnarmen/csv-diff-tool
+Project-URL: Issues, https://github.com/ashishnarmen/csv-diff-tool/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chardet
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Dynamic: license-file
+
+# csv-diff-tool
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+A Python library for comparing CSV files with detailed output including extra columns, extra rows, and mismatched cell values. Supports automatic encoding detection, data transformations, and flexible input methods.
+
+## Installation
+
+```bash
+pip install csv-diff-tool
+```
+
+## Quick Start
+
+### Compare two CSV files
+
+```python
+from csv_diff_tool import CSVComparer
+
+result = CSVComparer.from_files("report_v1.csv", "report_v2.csv").compare("id")
+
+print(result.match_result)              # True if files are identical
+print(result.extra_cols_in_first_file)  # Columns only in first file
+print(result.extra_rows_in_second_file) # Rows only in second file
+print(result.mismatched_rows)           # Cell-level differences
+```
+
+### Compare from in-memory data
+
+```python
+from csv_diff_tool import CSVComparer
+
+file_1 = ["id,name,score", "1,Alice,95", "2,Bob,87"]
+file_2 = ["id,name,score", "1,Alice,95", "2,Bob,90", "3,Carol,88"]
+
+result = CSVComparer.from_lines(file_1, file_2).compare("id")
+
+print(result)
+# First file: init from lines
+# Second file: init from lines
+# Match result: False
+# Extra rows in second file
+# 	3
+# Mismatched rows
+# 	row: 2, column: score, first: 87, second: 90
+```
+
+### Transform data before comparing
+
+```python
+from csv_diff_tool import CSVComparer
+
+comparer = CSVComparer.from_files("old.csv", "new.csv")
+
+# Strip whitespace from all cells
+comparer.strip_whitespace()
+
+# Drop columns you don't care about
+comparer.drop_columns(["timestamp", "metadata"])
+
+# Drop specific rows
+comparer.drop_rows("status", ["deleted", "archived"])
+
+# Apply custom transforms
+comparer.apply_transform("price", lambda row: str(round(float(row["price"]), 2)))
+
+result = comparer.compare("id")
+```
+
+### Work with CSVParser directly
+
+```python
+from csv_diff_tool import CSVParser
+
+parser = CSVParser.from_file("data.csv")
+
+# Inspect the data
+print(parser.column_names)
+print(parser.get_row("id", "42"))
+print(parser.row_values_in_column("name"))
+
+# Modify and write back
+parser.set_value("42", "status", "updated")
+parser.write_to_file()
+```
+
+## API Overview
+
+### CSVComparer
+
+The main comparison class. Create instances using factory methods:
+
+- `CSVComparer.from_files(first_file, second_file)` - Load from file paths
+- `CSVComparer.from_lines(first_lines, second_lines)` - Load from lists of strings
+- `CSVComparer.from_csv_parsers(parser1, parser2)` - Load from CSVParser objects
+
+**Transform methods** (applied to both files):
+- `strip_whitespace()` - Remove leading/trailing whitespace
+- `drop_columns(column_names)` - Remove specified columns
+- `drop_rows(column, values)` - Remove rows matching values
+- `drop_rows_by(predicate)` - Remove rows matching a function
+- `apply_transform(column, func)` - Apply a function to a column
+
+**Compare:**
+- `compare(index_column)` - Returns a `CSVCompareOutput` with the results
+
+### CSVParser
+
+Parses CSV data into a list of dictionaries with column-aware operations:
+
+- `CSVParser.from_file(path)` - Load from file (auto-detects encoding)
+- `CSVParser.from_lines(lines)` - Load from list of strings
+- `CSVParser.from_csv_text(text)` - Load from a single string
+- `get_row(column, value)` / `get_rows(column, value)` - Query rows
+- `get_value(row_id, column)` / `set_value(row_id, column, value)` - Cell access
+- `write_to_file()` - Write modifications back to the source file
+
+### CSVCompareOutput
+
+A dataclass containing comparison results:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `match_result` | `bool` | `True` if files are identical |
+| `extra_cols_in_first_file` | `List[str]` | Columns only in the first file |
+| `extra_cols_in_second_file` | `List[str]` | Columns only in the second file |
+| `extra_rows_in_first_file` | `List[str]` | Rows only in the first file |
+| `extra_rows_in_second_file` | `List[str]` | Rows only in the second file |
+| `mismatched_rows` | `List[Dict]` | Cell-level mismatches with row, column, first, second |
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/ashishnarmen/csv-diff-tool).
+
+```bash
+# Clone and install for development
+git clone https://github.com/ashishnarmen/csv-diff-tool.git
+cd csv-diff-tool
+pip install -e ".[test]"
+
+# Run tests with unittest and coverage
+coverage run -m unittest discover tests/
+coverage report -m
+
+# Or, if you prefer pytest (install separately)
+pip install pytest pytest-cov
+pytest tests/ -v --cov=csv_diff_tool
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

csv_diff_tool-0.1.0/README.md

@@ -0,0 +1,153 @@
+# csv-diff-tool
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+A Python library for comparing CSV files with detailed output including extra columns, extra rows, and mismatched cell values. Supports automatic encoding detection, data transformations, and flexible input methods.
+
+## Installation
+
+```bash
+pip install csv-diff-tool
+```
+
+## Quick Start
+
+### Compare two CSV files
+
+```python
+from csv_diff_tool import CSVComparer
+
+result = CSVComparer.from_files("report_v1.csv", "report_v2.csv").compare("id")
+
+print(result.match_result)              # True if files are identical
+print(result.extra_cols_in_first_file)  # Columns only in first file
+print(result.extra_rows_in_second_file) # Rows only in second file
+print(result.mismatched_rows)           # Cell-level differences
+```
+
+### Compare from in-memory data
+
+```python
+from csv_diff_tool import CSVComparer
+
+file_1 = ["id,name,score", "1,Alice,95", "2,Bob,87"]
+file_2 = ["id,name,score", "1,Alice,95", "2,Bob,90", "3,Carol,88"]
+
+result = CSVComparer.from_lines(file_1, file_2).compare("id")
+
+print(result)
+# First file: init from lines
+# Second file: init from lines
+# Match result: False
+# Extra rows in second file
+# 	3
+# Mismatched rows
+# 	row: 2, column: score, first: 87, second: 90
+```
+
+### Transform data before comparing
+
+```python
+from csv_diff_tool import CSVComparer
+
+comparer = CSVComparer.from_files("old.csv", "new.csv")
+
+# Strip whitespace from all cells
+comparer.strip_whitespace()
+
+# Drop columns you don't care about
+comparer.drop_columns(["timestamp", "metadata"])
+
+# Drop specific rows
+comparer.drop_rows("status", ["deleted", "archived"])
+
+# Apply custom transforms
+comparer.apply_transform("price", lambda row: str(round(float(row["price"]), 2)))
+
+result = comparer.compare("id")
+```
+
+### Work with CSVParser directly
+
+```python
+from csv_diff_tool import CSVParser
+
+parser = CSVParser.from_file("data.csv")
+
+# Inspect the data
+print(parser.column_names)
+print(parser.get_row("id", "42"))
+print(parser.row_values_in_column("name"))
+
+# Modify and write back
+parser.set_value("42", "status", "updated")
+parser.write_to_file()
+```
+
+## API Overview
+
+### CSVComparer
+
+The main comparison class. Create instances using factory methods:
+
+- `CSVComparer.from_files(first_file, second_file)` - Load from file paths
+- `CSVComparer.from_lines(first_lines, second_lines)` - Load from lists of strings
+- `CSVComparer.from_csv_parsers(parser1, parser2)` - Load from CSVParser objects
+
+**Transform methods** (applied to both files):
+- `strip_whitespace()` - Remove leading/trailing whitespace
+- `drop_columns(column_names)` - Remove specified columns
+- `drop_rows(column, values)` - Remove rows matching values
+- `drop_rows_by(predicate)` - Remove rows matching a function
+- `apply_transform(column, func)` - Apply a function to a column
+
+**Compare:**
+- `compare(index_column)` - Returns a `CSVCompareOutput` with the results
+
+### CSVParser
+
+Parses CSV data into a list of dictionaries with column-aware operations:
+
+- `CSVParser.from_file(path)` - Load from file (auto-detects encoding)
+- `CSVParser.from_lines(lines)` - Load from list of strings
+- `CSVParser.from_csv_text(text)` - Load from a single string
+- `get_row(column, value)` / `get_rows(column, value)` - Query rows
+- `get_value(row_id, column)` / `set_value(row_id, column, value)` - Cell access
+- `write_to_file()` - Write modifications back to the source file
+
+### CSVCompareOutput
+
+A dataclass containing comparison results:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `match_result` | `bool` | `True` if files are identical |
+| `extra_cols_in_first_file` | `List[str]` | Columns only in the first file |
+| `extra_cols_in_second_file` | `List[str]` | Columns only in the second file |
+| `extra_rows_in_first_file` | `List[str]` | Rows only in the first file |
+| `extra_rows_in_second_file` | `List[str]` | Rows only in the second file |
+| `mismatched_rows` | `List[Dict]` | Cell-level mismatches with row, column, first, second |
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/ashishnarmen/csv-diff-tool).
+
+```bash
+# Clone and install for development
+git clone https://github.com/ashishnarmen/csv-diff-tool.git
+cd csv-diff-tool
+pip install -e ".[test]"
+
+# Run tests with unittest and coverage
+coverage run -m unittest discover tests/
+coverage report -m
+
+# Or, if you prefer pytest (install separately)
+pip install pytest pytest-cov
+pytest tests/ -v --cov=csv_diff_tool
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

csv_diff_tool-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "csv-diff-tool"
+version = "0.1.0"
+authors = [
+  { name="Ashish N", email="ashish012@e.ntu.edu.sg" },
+]
+description = "A package for comparing CSV files"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "chardet",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Utilities",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[project.optional-dependencies]
+test = ["coverage"]
+
+[project.urls]
+Homepage = "https://github.com/ashishnarmen/csv-diff-tool"
+Issues = "https://github.com/ashishnarmen/csv-diff-tool/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

csv_diff_tool-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

csv_diff_tool-0.1.0/src/csv_diff_tool/__init__.py

@@ -0,0 +1,11 @@
+"""csv_diff_tool - A library for comparing CSV files.
+
+Provides tools for parsing, transforming, and comparing CSV files with
+detailed output including extra columns, extra rows, and mismatched values.
+"""
+
+from .comparer import CSVComparer
+from .csv_compare_output import CSVCompareOutput
+from .csv_parser import CSVParser
+
+__all__ = ["CSVComparer", "CSVCompareOutput", "CSVParser"]

csv_diff_tool-0.1.0/src/csv_diff_tool/comparer.py

@@ -0,0 +1,213 @@
+"""CSV comparison module for comparing two parsed CSV files."""
+
+from typing import Callable, Dict, List
+
+from .csv_compare_output import CSVCompareOutput
+from .csv_parser import CSVParser, NullCSVParser
+
+
+class CSVComparer:
+    """Compares two CSV files and reports differences.
+
+    Supports loading from files, text lines, or pre-built CSVParser objects.
+    Provides methods to transform data before comparison.
+    """
+
+    first_file: CSVParser
+    second_file: CSVParser
+
+    def __init__(self) -> None:
+        self.first_file: CSVParser = NullCSVParser()
+        self.second_file: CSVParser = NullCSVParser()
+
+    @classmethod
+    def from_files(cls, first_file: str, second_file: str) -> "CSVComparer":
+        """Create an instance of CSVComparer from two CSV files.
+
+        Args:
+            first_file (str): File path of the first CSV file.
+            second_file (str): File path of the second CSV file.
+
+        Returns:
+            CSVComparer: A CSVComparer object with the parsed file contents.
+
+        Raises:
+            FileNotFoundError: If either file_path does not exist.
+            UnicodeDecodeError: If either file cannot be decoded with the detected encoding.
+        """
+        csv_comparer = cls()
+        csv_comparer.first_file = CSVParser.from_file(first_file)
+        csv_comparer.second_file = CSVParser.from_file(second_file)
+        return csv_comparer
+
+    @classmethod
+    def from_lines(
+        cls, first_file_lines: List[str], second_file_lines: List[str]
+    ) -> "CSVComparer":
+        """Create an instance of CSVComparer from two lists of CSV text lines.
+
+        Args:
+            first_file_lines (List[str]): List of text lines for the first CSV file.
+            second_file_lines (List[str]): List of text lines for the second CSV file.
+
+        Returns:
+            CSVComparer: A CSVComparer object with the parsed file contents.
+        """
+        csv_comparer = cls()
+        csv_comparer.first_file = CSVParser.from_lines(first_file_lines)
+        csv_comparer.second_file = CSVParser.from_lines(second_file_lines)
+        return csv_comparer
+
+    @classmethod
+    def from_csv_parsers(
+        cls, first_file_parser: CSVParser, second_file_parser: CSVParser
+    ) -> "CSVComparer":
+        """Create an instance of CSVComparer from two CSVParser objects.
+
+        Args:
+            first_file_parser (CSVParser): CSVParser object for the first CSV file.
+            second_file_parser (CSVParser): CSVParser object for the second CSV file.
+
+        Returns:
+            CSVComparer: A CSVComparer object with the parsed file contents.
+        """
+        csv_comparer = cls()
+        csv_comparer.first_file = first_file_parser
+        csv_comparer.second_file = second_file_parser
+        return csv_comparer
+
+    def strip_whitespace(self) -> None:
+        """Strip whitespace from all keys and values in both CSV files.
+
+        This method removes leading and trailing whitespace from column names
+        and all cell values in both the first and second CSV files.
+        """
+        self.first_file.strip_whitespace()
+        self.second_file.strip_whitespace()
+
+    def drop_columns(self, column_names: List[str]) -> None:
+        """Drop (remove) the specified columns from both CSV files.
+
+        Args:
+            column_names (List[str]): List of column names to drop (remove).
+        """
+        self.first_file.drop_columns(column_names)
+        self.second_file.drop_columns(column_names)
+
+    def drop_rows(self, index_column: str, row_values: List[str]) -> None:
+        """Drop (remove) the rows with matching values in both CSV files.
+
+        Args:
+            index_column (str): Column name to search.
+            row_values (List[str]): Values to match in the specified column.
+        """
+        self.first_file.drop_rows(index_column, row_values)
+        self.second_file.drop_rows(index_column, row_values)
+
+    def drop_rows_by(self, predicate: Callable) -> None:
+        """Drop (remove) rows based on a predicate function in both CSV files.
+
+        Args:
+            predicate (Callable): Predicate function applied on each row to determine
+                if it will be dropped.
+        """
+        self.first_file.drop_rows_by(predicate)
+        self.second_file.drop_rows_by(predicate)
+
+    def apply_transform(self, column_name: str, func: Callable) -> None:
+        """Apply a transform on a column on each row of the CSV files.
+
+        Args:
+            column_name (str): Column name on which the transform is to be applied.
+            func (Callable): Transformer function to execute on each row.
+        """
+        self.first_file.apply_transform(column_name, func)
+        self.second_file.apply_transform(column_name, func)
+
+    def compare(self, index_column: str) -> CSVCompareOutput:
+        """Compare two CSV files and return detailed comparison results.
+
+        Args:
+            index_column (str): Column name to use as the unique row identifier.
+
+        Returns:
+            CSVCompareOutput: An object containing match result and detailed comparison
+                information including extra/missing columns, extra/missing rows, and
+                mismatched cell values.
+
+        Raises:
+            ValueError: If index_column does not exist in either CSV file.
+        """
+        # Validate that index_column exists in both files
+        if index_column not in self.first_file.column_names:
+            raise ValueError(
+                f"Index column '{index_column}' not found in first file. Available columns: {self.first_file.column_names}"
+            )
+        if index_column not in self.second_file.column_names:
+            raise ValueError(
+                f"Index column '{index_column}' not found in second file. Available columns: {self.second_file.column_names}"
+            )
+
+        # Set the index column for both files
+        self.first_file.index_column = index_column
+        self.second_file.index_column = index_column
+
+        # Convert to sets for efficient lookups (O(1) instead of O(n))
+        first_cols = set(self.first_file.column_names)
+        second_cols = set(self.second_file.column_names)
+        first_rows = set(self.first_file.row_values_in_column(index_column))
+        second_rows = set(self.second_file.row_values_in_column(index_column))
+
+        # Find columns that exist in first file but not in second
+        extra_cols_in_first_file = list(first_cols - second_cols)
+
+        # Find columns that exist in second file but not in first
+        extra_cols_in_second_file = list(second_cols - first_cols)
+
+        # Find rows that exist in first file but not in second
+        extra_rows_in_first_file = list(first_rows - second_rows)
+
+        # Find rows that exist in second file but not in first
+        extra_rows_in_second_file = list(second_rows - first_rows)
+
+        # Find columns and rows that exist in both files
+        common_columns = list(first_cols & second_cols)
+        common_rows = list(first_rows & second_rows)
+
+        # Compare values in common rows and columns to find mismatches
+        mismatched_rows = []
+        for row in common_rows:
+            for column in common_columns:
+                first_val = self.first_file.get_value(row, column)
+                second_val = self.second_file.get_value(row, column)
+                if first_val != second_val:
+                    mismatched_rows.append(
+                        {
+                            "row": row,
+                            "column": column,
+                            "first": first_val,
+                            "second": second_val,
+                        }
+                    )
+
+        # Determine if files match: true only if there are no differences
+        match_result = not any(
+            [
+                extra_cols_in_first_file,
+                extra_cols_in_second_file,
+                extra_rows_in_first_file,
+                extra_rows_in_second_file,
+                mismatched_rows,
+            ]
+        )
+
+        return CSVCompareOutput(
+            match_result=match_result,
+            first_file=self.first_file.file_path,
+            second_file=self.second_file.file_path,
+            extra_cols_in_first_file=extra_cols_in_first_file,
+            extra_cols_in_second_file=extra_cols_in_second_file,
+            extra_rows_in_first_file=extra_rows_in_first_file,
+            extra_rows_in_second_file=extra_rows_in_second_file,
+            mismatched_rows=mismatched_rows,
+        )

csv_diff_tool-0.1.0/src/csv_diff_tool/csv_compare_output.py

@@ -0,0 +1,80 @@
+"""Output model for CSV comparison results."""
+
+from dataclasses import dataclass
+from typing import Dict, List
+
+
+@dataclass
+class CSVCompareOutput:
+    """Contains the results of comparing two CSV files.
+
+    Attributes:
+        match_result: True if the files are identical, False otherwise.
+        first_file: Path or identifier of the first file.
+        second_file: Path or identifier of the second file.
+        extra_cols_in_first_file: Columns present in the first file but not the second.
+        extra_cols_in_second_file: Columns present in the second file but not the first.
+        extra_rows_in_first_file: Rows present in the first file but not the second.
+        extra_rows_in_second_file: Rows present in the second file but not the first.
+        mismatched_rows: List of dicts describing cell-level mismatches.
+    """
+
+    match_result: bool
+    first_file: str
+    second_file: str
+    extra_cols_in_first_file: List[str]
+    extra_cols_in_second_file: List[str]
+    extra_rows_in_first_file: List[str]
+    extra_rows_in_second_file: List[str]
+    mismatched_rows: List[Dict[str, str]]
+
+    def to_dict(self) -> Dict:
+        """Convert the comparison result to a dictionary.
+
+        Returns:
+            Dict: Dictionary representation of the comparison result.
+        """
+        return {
+            "first_file": self.first_file,
+            "second_file": self.second_file,
+            "match_result": self.match_result,
+            "extra_cols_in_first_file": self.extra_cols_in_first_file,
+            "extra_cols_in_second_file": self.extra_cols_in_second_file,
+            "extra_rows_in_first_file": self.extra_rows_in_first_file,
+            "extra_rows_in_second_file": self.extra_rows_in_second_file,
+            "mismatched_rows": self.mismatched_rows,
+        }
+
+    def __str__(self) -> str:
+        """Format the comparison result as a human-readable string.
+
+        Returns:
+            str: Multi-line summary of the comparison.
+        """
+        lines = []
+        lines.append(f"First file: {self.first_file}")
+        lines.append(f"Second file: {self.second_file}")
+        lines.append(f"Match result: {self.match_result}")
+
+        if self.extra_cols_in_first_file:
+            lines.append("Extra columns in first file")
+            lines.extend([f"\t{x}" for x in self.extra_cols_in_first_file])
+
+        if self.extra_cols_in_second_file:
+            lines.append("Extra columns in second file")
+            lines.extend([f"\t{x}" for x in self.extra_cols_in_second_file])
+        if self.extra_rows_in_first_file:
+            lines.append("Extra rows in first file")
+            lines.extend([f"\t{x}" for x in self.extra_rows_in_first_file])
+        if self.extra_rows_in_second_file:
+            lines.append("Extra rows in second file")
+            lines.extend([f"\t{x}" for x in self.extra_rows_in_second_file])
+        if self.mismatched_rows:
+            lines.append("Mismatched rows")
+            lines.extend(
+                [
+                    f"\trow: {x.get('row', '')}, column: {x.get('column', '')}, first: {x.get('first', '')}, second: {x.get('second', '')}"
+                    for x in self.mismatched_rows
+                ]
+            )
+        return "\n".join(lines)

csv_diff_tool-0.1.0/src/csv_diff_tool/csv_parser.py

@@ -0,0 +1,430 @@
+"""CSV parsing module for reading, transforming, and writing CSV data."""
+
+import csv
+import io
+import logging
+import os
+from collections import defaultdict
+from typing import Callable, Dict, List, Optional
+
+import chardet
+
+
+class CSVParser:
+    """Parses CSV data from files, text, or lines into a list of dictionaries.
+
+    Supports encoding detection, column/row manipulation, transforms,
+    and writing modified data back to files.
+    """
+
+    def __init__(self) -> None:
+        self.list_of_dicts: List[Dict[str, str]] = []
+        self.column_names: List[str] = []
+        self.file_text: str = ""
+        self._index_column: str = ""
+        self.file_path: str = ""
+        self._encoding: str = "utf-8"
+
+    @staticmethod
+    def get_encoding(file_path: str) -> Optional[str]:
+        """Detect the encoding of the file.
+
+        Args:
+            file_path (str): File path of the text file.
+
+        Returns:
+            Optional[str]: Detected encoding, or None if detection fails.
+        """
+        with open(file_path, "rb") as f:
+            rawdata = b"".join(f.readlines())
+        return chardet.detect(rawdata)["encoding"]
+
+    @classmethod
+    def from_file(cls, file_path: str, column_names: Optional[List[str]] = None) -> "CSVParser":
+        """Create an instance of CSVParser from a file.
+
+        Args:
+            file_path (str): File Path (CSV file).
+            column_names: Optional list of column names. If None or empty, uses the CSV header row.
+
+        Returns:
+            CSVParser: A CSVParser object with the parsed file content.
+
+        Raises:
+            FileNotFoundError: If the file_path does not exist.
+            TypeError: If column_names contains non-string elements.
+            UnicodeDecodeError: If the file cannot be decoded with the detected encoding.
+        """
+        if not os.path.isfile(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        try:
+            encoding = cls.get_encoding(file_path) or "utf-8"
+        except (OSError, LookupError) as e:
+            encoding = "utf-8"
+            logging.warning(f"Warning: Encoding detection failed, using utf-8: {e}")
+
+        file_text = ""
+        try:
+            with open(file_path, encoding=encoding) as file:
+                file_text = file.read()
+        except UnicodeDecodeError as e:
+            raise UnicodeDecodeError(
+                e.encoding,
+                e.object,
+                e.start,
+                e.end,
+                f"Failed to decode {file_path} with encoding {encoding}: {e.reason}",
+            ) from e
+
+        csv_parser = CSVParser.from_csv_text(file_text, column_names)
+        csv_parser.file_path = file_path
+        csv_parser._encoding = encoding
+        return csv_parser
+
+    @classmethod
+    def from_lines(cls, csv_lines: List[str], column_names: Optional[List[str]] = None) -> "CSVParser":
+        """Create an instance of CSVParser from a list of text lines.
+
+        Args:
+            csv_lines (List[str]): List of text lines.
+            column_names: Optional list of column names. If None or empty, uses the CSV header row.
+
+        Returns:
+            CSVParser: A CSVParser object with the parsed file content.
+        """
+        file_text = "\n".join(csv_lines)
+        csv_parser = CSVParser.from_csv_text(file_text, column_names)
+        csv_parser.file_path = "init from lines"
+        return csv_parser
+
+    @classmethod
+    def from_csv_text(cls, file_text: str, column_names: Optional[List[str]] = None) -> "CSVParser":
+        """Create an instance of CSVParser from CSV text as a string.
+
+        Args:
+            file_text (str): CSV content as text.
+            column_names: Optional list of column names. If None or empty, uses the CSV header row.
+
+        Returns:
+            CSVParser: A CSVParser object with the parsed file content.
+        """
+        if column_names is not None and column_names:
+            if not all(isinstance(col, str) for col in column_names):
+                raise TypeError("All column names must be strings")
+        csv_parser = cls()
+        csv_parser.file_path = "init from text"
+        csv_parser.file_text = file_text
+        csv_parser.column_names = (
+            csv_parser._get_column_names_from_header_row(file_text)
+            if not column_names
+            else column_names
+        )
+        with io.StringIO(file_text) as file:
+            dict_reader = csv.DictReader(file, column_names)
+            csv_parser.list_of_dicts = list(dict_reader)
+        return csv_parser
+
+    def _get_column_names_from_header_row(self, file_text: str) -> List[str]:
+        """Extract column names from the first row of CSV text.
+
+        Args:
+            file_text (str): CSV content as text.
+
+        Returns:
+            List[str]: List of column names, with duplicates made unique.
+        """
+        with io.StringIO(file_text) as file:
+            reader = csv.reader(file)
+            try:
+                header_row = next(reader)
+            except StopIteration:
+                return []
+        return self._unique_vals(header_row)
+
+    def strip_whitespace(self) -> None:
+        """Strip leading and trailing whitespace from all keys and values."""
+        self.list_of_dicts = [
+            {
+                (key.strip() if isinstance(key, str) else key): (
+                    value.strip() if isinstance(value, str) else value
+                )
+                for key, value in item.items()
+            }
+            for item in self.list_of_dicts
+        ]
+        self.column_names = [x.strip() for x in self.column_names if isinstance(x, str)]
+        if isinstance(self._index_column, str):
+            self._index_column = self._index_column.strip()
+
+    def apply_transform(self, column_name: str, func: Callable) -> None:
+        """Apply a transform on a column on each row of the CSV file.
+
+        Args:
+            column_name (str): Column name on which the transform is to be applied.
+            func (Callable): Transformer function to execute on each row.
+        """
+        self.list_of_dicts = [
+            {**item, column_name: func(item)} for item in self.list_of_dicts
+        ]
+        if column_name not in self.column_names:
+            self.column_names.append(column_name)
+
+    def get_row(self, column_name: str, row_value: str) -> Dict[str, str]:
+        """Get the contents of the first matching row as a dictionary.
+
+        Args:
+            column_name (str): Column name to search.
+            row_value (str): Value to match in the specified column.
+
+        Returns:
+            Dict[str, str]: Dictionary representation of the first matching row
+                or an empty dictionary if a match is not found.
+        """
+        row: Dict[str, str] = {}
+        rows = self.get_rows(column_name, row_value)
+        if rows:
+            row = rows[0]
+        return row
+
+    def get_rows(self, column_name: str, row_value: str) -> List[Dict[str, str]]:
+        """Get the contents of matching rows as a list of dictionaries.
+
+        Args:
+            column_name (str): Column name to search.
+            row_value (str): Value to match in the specified column.
+
+        Returns:
+            List[Dict[str, str]]: List of dictionaries of the matching rows
+                or an empty list if a match is not found.
+        """
+        rows: List[Dict[str, str]] = []
+        if column_name in self.column_names:
+            matching_row = lambda row: row.get(column_name) == row_value
+            rows = list(filter(matching_row, self.list_of_dicts))
+        return rows
+
+    @property
+    def has_error(self) -> bool:
+        """Check if there are any errors in the CSV file.
+
+        Returns:
+            bool: True if there are any errors (e.g., inconsistent column counts),
+                otherwise False.
+        """
+        reader = csv.reader(io.StringIO(self.file_text))
+        try:
+            header = next(reader)
+        except StopIteration:
+            return False
+        expected_cols = len(header)
+        for _, row in enumerate(reader, start=2):
+            if len(row) != expected_cols:
+                return True
+        return False
+
+    def drop_columns(self, column_names: List[str]) -> None:
+        """Drop (remove) the columns.
+
+        Args:
+            column_names (List[str]): List of column names to drop (remove).
+        """
+        list_of_dicts = []
+        for dict_row in self.list_of_dicts:
+            list_of_dicts.append(
+                {
+                    key: value
+                    for key, value in dict_row.items()
+                    if key not in column_names
+                }
+            )
+        self.list_of_dicts = list_of_dicts
+        self.column_names = [
+            col_name for col_name in self.column_names if col_name not in column_names
+        ]
+
+    def drop_rows_by(self, predicate: Callable) -> None:
+        """Drop (remove) rows based on a predicate function that is applied on the row.
+
+        Args:
+            predicate (Callable): Predicate function applied on each row to determine
+                if it will be dropped.
+        """
+        self.list_of_dicts = [
+            dict_row for dict_row in self.list_of_dicts if not predicate(dict_row)
+        ]
+
+    def drop_rows(self, column_name: str, row_values: List[str]) -> None:
+        """Drop (remove) the rows with matching values in a specified column.
+
+        Args:
+            column_name (str): Column name to search.
+            row_values (List[str]): Values to match in the specified column.
+        """
+        if column_name not in self.column_names:
+            return
+        row_val_check = lambda x: x[column_name] in row_values
+        self.drop_rows_by(row_val_check)
+
+    def row_values_in_column(self, column_name: str) -> List[str]:
+        """Get a list of row values in the specified column.
+
+        Args:
+            column_name (str): Column name.
+
+        Returns:
+            List[str]: List of all the row values in that column.
+        """
+        row_values: List[str] = []
+        if column_name in self.column_names:
+            row_values = [x.get(column_name, "") for x in self.list_of_dicts]
+        return row_values
+
+    def _unique_vals(self, values: List[str]) -> List[str]:
+        """Make duplicate values unique by appending numeric suffixes.
+
+        Args:
+            values (List[str]): List of values that may contain duplicates.
+
+        Returns:
+            List[str]: List with duplicates renamed (e.g., col, col.1, col.2).
+        """
+        result = list(values)
+        unique_values = set()
+        suffix_counts = defaultdict(int)
+        for idx, val in enumerate(result):
+            if val not in unique_values:
+                unique_values.add(val)
+            else:
+                while True:
+                    suffix_counts[val] += 1
+                    new_val = f"{val}.{suffix_counts[val]}"
+                    if new_val not in unique_values:
+                        unique_values.add(new_val)
+                        result[idx] = new_val
+                        break
+        return result
+
+    @property
+    def index_column(self) -> str:
+        """Get the index column.
+
+        Returns:
+            str: Column name.
+        """
+        if not self.column_names:
+            raise ValueError("No columns available to set or get the index column")
+        return self._index_column or self.column_names[0]
+
+    @index_column.setter
+    def index_column(self, value: str) -> None:
+        """Set the index column. If there are duplicate column names, append a numeric
+        index to the column name (col, col.1, col.2).
+
+        Args:
+            value (str): Column name.
+        """
+        if not self.column_names:
+            raise ValueError("No columns available to set the index column")
+        if value not in self.column_names:
+            raise ValueError(f"Column '{value}' not found in column names")
+        self._index_column = value
+        row_vals = self._unique_vals(self.row_values_in_column(self._index_column))
+        for idx, row in enumerate(self.list_of_dicts):
+            row[self.index_column] = row_vals[idx]
+
+    def get_value(self, row_value_in_index_column: str, column_name: str) -> str:
+        """Get value of the cell in the specified row and column.
+
+        Args:
+            row_value_in_index_column (str): Row identifier.
+            column_name (str): Column name.
+
+        Returns:
+            str: Value contained in the cell.
+        """
+        row = self.get_row(self.index_column, row_value_in_index_column)
+        return row.get(column_name, "")
+
+    def set_value(self, row_value_in_index_column: str, column_name: str, new_value: str) -> None:
+        """Set value of cell in the specified row and column.
+
+        Args:
+            row_value_in_index_column (str): Row identifier.
+            column_name (str): Column name.
+            new_value (str): New value to set for the cell.
+        """
+        row = self.get_row(self.index_column, row_value_in_index_column)
+        if row and column_name in row:
+            row[column_name] = new_value
+
+    def write_to_file(self) -> None:
+        """Write the CSV data back to the source file.
+
+        Raises:
+            ValueError: If the CSVParser was not initialized from a file.
+        """
+        if not os.path.isfile(self.file_path):
+            raise ValueError(
+                f"Cannot write: '{self.file_path}' is not a valid file path. "
+                "write_to_file is only supported when initialized via from_file."
+            )
+        with open(self.file_path, "w", newline="", encoding=self._encoding) as f:
+            writer = csv.DictWriter(f, fieldnames=self.column_names)
+            writer.writeheader()
+            normalized_rows = [
+                {key: value for key, value in row.items() if key in self.column_names}
+                for row in self.list_of_dicts
+            ]
+            writer.writerows(normalized_rows)
+
+
+class NullCSVParser(CSVParser):
+    """Null Object implementation of CSVParser.
+
+    All mutation methods are no-ops. Used as a default placeholder
+    when no CSV data has been loaded yet.
+    """
+
+    def __init__(self) -> None:
+        self.list_of_dicts: List[Dict[str, str]] = []
+        self.column_names: List[str] = []
+        self.file_text: str = ""
+        self._index_column: str = ""
+        self.file_path: str = "null"
+        self._encoding: str = "utf-8"
+
+    def strip_whitespace(self) -> None:
+        pass
+
+    def apply_transform(self, column_name: str, func: Callable) -> None:
+        pass
+
+    def drop_columns(self, column_names: List[str]) -> None:
+        pass
+
+    def drop_rows_by(self, predicate: Callable) -> None:
+        pass
+
+    def drop_rows(self, column_name: str, row_values: List[str]) -> None:
+        pass
+
+    def row_values_in_column(self, column_name: str) -> List[str]:
+        return []
+
+    def get_value(self, row_value_in_index_column: str, column_name: str) -> str:
+        return ""
+
+    def set_value(self, row_value_in_index_column: str, column_name: str, new_value: str) -> None:
+        pass
+
+    @property
+    def index_column(self) -> str:
+        return self._index_column
+
+    @index_column.setter
+    def index_column(self, value: str) -> None:
+        pass
+
+    def write_to_file(self) -> None:
+        pass

csv_diff_tool-0.1.0/src/csv_diff_tool.egg-info/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: csv-diff-tool
+Version: 0.1.0
+Summary: A package for comparing CSV files
+Author-email: Ashish N <ashish012@e.ntu.edu.sg>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ashishnarmen/csv-diff-tool
+Project-URL: Issues, https://github.com/ashishnarmen/csv-diff-tool/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chardet
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Dynamic: license-file
+
+# csv-diff-tool
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+A Python library for comparing CSV files with detailed output including extra columns, extra rows, and mismatched cell values. Supports automatic encoding detection, data transformations, and flexible input methods.
+
+## Installation
+
+```bash
+pip install csv-diff-tool
+```
+
+## Quick Start
+
+### Compare two CSV files
+
+```python
+from csv_diff_tool import CSVComparer
+
+result = CSVComparer.from_files("report_v1.csv", "report_v2.csv").compare("id")
+
+print(result.match_result)              # True if files are identical
+print(result.extra_cols_in_first_file)  # Columns only in first file
+print(result.extra_rows_in_second_file) # Rows only in second file
+print(result.mismatched_rows)           # Cell-level differences
+```
+
+### Compare from in-memory data
+
+```python
+from csv_diff_tool import CSVComparer
+
+file_1 = ["id,name,score", "1,Alice,95", "2,Bob,87"]
+file_2 = ["id,name,score", "1,Alice,95", "2,Bob,90", "3,Carol,88"]
+
+result = CSVComparer.from_lines(file_1, file_2).compare("id")
+
+print(result)
+# First file: init from lines
+# Second file: init from lines
+# Match result: False
+# Extra rows in second file
+# 	3
+# Mismatched rows
+# 	row: 2, column: score, first: 87, second: 90
+```
+
+### Transform data before comparing
+
+```python
+from csv_diff_tool import CSVComparer
+
+comparer = CSVComparer.from_files("old.csv", "new.csv")
+
+# Strip whitespace from all cells
+comparer.strip_whitespace()
+
+# Drop columns you don't care about
+comparer.drop_columns(["timestamp", "metadata"])
+
+# Drop specific rows
+comparer.drop_rows("status", ["deleted", "archived"])
+
+# Apply custom transforms
+comparer.apply_transform("price", lambda row: str(round(float(row["price"]), 2)))
+
+result = comparer.compare("id")
+```
+
+### Work with CSVParser directly
+
+```python
+from csv_diff_tool import CSVParser
+
+parser = CSVParser.from_file("data.csv")
+
+# Inspect the data
+print(parser.column_names)
+print(parser.get_row("id", "42"))
+print(parser.row_values_in_column("name"))
+
+# Modify and write back
+parser.set_value("42", "status", "updated")
+parser.write_to_file()
+```
+
+## API Overview
+
+### CSVComparer
+
+The main comparison class. Create instances using factory methods:
+
+- `CSVComparer.from_files(first_file, second_file)` - Load from file paths
+- `CSVComparer.from_lines(first_lines, second_lines)` - Load from lists of strings
+- `CSVComparer.from_csv_parsers(parser1, parser2)` - Load from CSVParser objects
+
+**Transform methods** (applied to both files):
+- `strip_whitespace()` - Remove leading/trailing whitespace
+- `drop_columns(column_names)` - Remove specified columns
+- `drop_rows(column, values)` - Remove rows matching values
+- `drop_rows_by(predicate)` - Remove rows matching a function
+- `apply_transform(column, func)` - Apply a function to a column
+
+**Compare:**
+- `compare(index_column)` - Returns a `CSVCompareOutput` with the results
+
+### CSVParser
+
+Parses CSV data into a list of dictionaries with column-aware operations:
+
+- `CSVParser.from_file(path)` - Load from file (auto-detects encoding)
+- `CSVParser.from_lines(lines)` - Load from list of strings
+- `CSVParser.from_csv_text(text)` - Load from a single string
+- `get_row(column, value)` / `get_rows(column, value)` - Query rows
+- `get_value(row_id, column)` / `set_value(row_id, column, value)` - Cell access
+- `write_to_file()` - Write modifications back to the source file
+
+### CSVCompareOutput
+
+A dataclass containing comparison results:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `match_result` | `bool` | `True` if files are identical |
+| `extra_cols_in_first_file` | `List[str]` | Columns only in the first file |
+| `extra_cols_in_second_file` | `List[str]` | Columns only in the second file |
+| `extra_rows_in_first_file` | `List[str]` | Rows only in the first file |
+| `extra_rows_in_second_file` | `List[str]` | Rows only in the second file |
+| `mismatched_rows` | `List[Dict]` | Cell-level mismatches with row, column, first, second |
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/ashishnarmen/csv-diff-tool).
+
+```bash
+# Clone and install for development
+git clone https://github.com/ashishnarmen/csv-diff-tool.git
+cd csv-diff-tool
+pip install -e ".[test]"
+
+# Run tests with unittest and coverage
+coverage run -m unittest discover tests/
+coverage report -m
+
+# Or, if you prefer pytest (install separately)
+pip install pytest pytest-cov
+pytest tests/ -v --cov=csv_diff_tool
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

csv_diff_tool-0.1.0/src/csv_diff_tool.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/csv_diff_tool/__init__.py
+src/csv_diff_tool/comparer.py
+src/csv_diff_tool/csv_compare_output.py
+src/csv_diff_tool/csv_parser.py
+src/csv_diff_tool.egg-info/PKG-INFO
+src/csv_diff_tool.egg-info/SOURCES.txt
+src/csv_diff_tool.egg-info/dependency_links.txt
+src/csv_diff_tool.egg-info/requires.txt
+src/csv_diff_tool.egg-info/top_level.txt

csv_diff_tool-0.1.0/src/csv_diff_tool.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

csv_diff_tool-0.1.0/src/csv_diff_tool.egg-info/requires.txt

@@ -0,0 +1,4 @@
+chardet
+
+[test]
+coverage

csv_diff_tool-0.1.0/src/csv_diff_tool.egg-info/top_level.txt

@@ -0,0 +1 @@
+csv_diff_tool