Enhance README and CLI: Add support for ignoring folders, output formats, and improve error handling

Author: codeperfectplus

README.md

@@ -1,31 +1,35 @@
-## 📦 extliner
+# 📦 extliner
 
-**extliner** is a lightweight Python package that counts lines in files (with and without empty lines) grouped by file extension — perfect for analyzing codebases or text-heavy directories.
+**extliner** is a lightweight Python package that recursively counts lines in files — distinguishing between total lines and non-empty lines — grouped by file extension. It's perfect for analyzing codebases, writing statistics, or cleaning up documentation-heavy directories.
 
 ---
 
-### 🚀 Features
-
-* 📂 Recursive directory traversal
-* 🔍 Counts:
-
-  * Total lines **with** whitespace
-  * Total lines **excluding** empty lines
-* 🎯 Extension-based grouping (`.py`, `.txt`, `NO_EXT`, etc.)
-* 🚫 Option to **ignore specific file extensions**
-* 📊 Beautiful **tabulated output**
-* 🧩 Easily extensible class-based design
-* 🧪 CLI support
+## 🚀 Features
+
+- 📂 Recursive directory scanning
+- 🧮 Counts:
+  - Total lines (with whitespace)
+  - Non-empty lines (ignores blank lines)
+- 🔠 Groups results by file extension (`.py`, `.js`, `NO_EXT`, etc.)
+- 🚫 Support for ignoring specific extensions or folders
+- 📊 Output formats:
+  - Pretty CLI table
+  - JSON / CSV / Markdown exports
+- 🧩 Clean, extensible class-based design
+- 🧪 Fully tested with `unittest`
+- 🔧 CLI and Python API support
 
 ---
 
-### 📥 Installation
+## 📥 Installation
+
+Install via pip:
 
 ```bash
 pip install extliner
 ```
 
-(Or if using locally during development:)
+Or install locally for development:
 
 ```bash
 git clone https://github.com/extliner/extliner.git
@@ -35,62 +39,107 @@ pip install -e .
 
 ---
 
-### 🧑‍💻 Usage
+## ⚙️ CLI Usage
 
-#### ✅ CLI
+### ✅ Basic
 
 ```bash
-extliner -d <directory_path> --ignore .log .json
+extliner -d <directory_path>
 ```
 
-#### Example
+### 🔍 Ignoring Extensions
 
 ```bash
 extliner -d ./myproject --ignore .md .log
 ```
 
-#### Output
+### Ignoring Folders
+
+```bash
+extliner -d ./myproject --folders .venv __pycache__
+```
+
+### 🧾 Output Example
 
 ```
-+------------+---------------+-------------------+--------------+
-| Extension  | With Spaces   | Without Spaces    | % of Total   |
-+------------+---------------+-------------------+--------------+
-| .py        | 320           | 280               | 65.31%       |
-| .txt       | 170           | 150               | 34.69%       |
-+------------+---------------+-------------------+--------------+
++-------------+---------------+------------------+---------+--------------+
+| Extension   |   With Spaces |   Without Spaces |   Files | % of Total   |
++=============+===============+==================+=========+==============+
+| .py         |           443 |              362 |       7 | 32.15%       |
++-------------+---------------+------------------+---------+--------------+
+| no_ext      |           361 |              287 |       8 | 26.20%       |
++-------------+---------------+------------------+---------+--------------+
+| .pyc        |           151 |              125 |       3 | 10.96%       |
++-------------+---------------+------------------+---------+--------------+
 ```
 
 ---
+## 🧱 Python API
 
-### 🧱 Python API
+### ✅ Count Lines Programmatically
 
 ```python
-from linecountx.main import LineCounter
+from extliner.main import LineCounter
 from pathlib import Path
 
 counter = LineCounter(ignore_extensions=[".log", ".json"])
 result = counter.count_lines(Path("./your_directory"))
 
+# Output as JSON
 print(counter.to_json(result))
+
+# Output as Markdown
+print(counter.to_markdown(result))
+
+# Output as CSV
+print(counter.to_csv(result))
 ```
 
 ---
 
-### ⚙️ Options
+## 🛠️ Configuration Options
+
+| Flag        | Description                       | Example                       | Optioal/Required |
+| ----------- | --------------------------------- | ----------------------------- | ---------------- |
+| `-d`        | Directory to scan      | `-d ./src`                    |  Required         |
+| `--ignore`  | File extensions to ignore         | `--ignore .log .md .json`     | Optional         |
+| `--folders` | Folder names to ignore | `--folders .venv __pycache__` | Optional         |
+
+---
+
+## 📂 Supported Formats
 
-| Flag       | Description                  | Example                   |
-| ---------- | ---------------------------- | ------------------------- |
-| `-d`       | Directory to scan (required) | `-d ./src`                |
-| `--ignore` | File extensions to ignore    | `--ignore .log .md .json` |
+| Output Method       | Description            |
+| ------------------- | ---------------------- |
+| `to_json(data)`     | Returns JSON string    |
+| `to_csv(data)`      | Returns CSV string     |
+| `to_markdown(data)` | Returns Markdown table |
 
+---
+
+## ✅ Testing
+
+To run tests:
+
+```bash
+python -m unittest discover tests
+```
+
+Or using `pytest` (if installed):
+
+```bash
+pytest
+```
+
+---
 
-### 📄 License
+## 📄 License
 
-MIT License
+This project is licensed under the MIT License.
 
 ---
 
-### 👨‍💻 Author
+## 👨‍💻 Author
 
 Made with ❤️ by [Deepak Raj](https://github.com/extliner)
 

extliner/cli.py

@@ -4,25 +4,38 @@
 
 from extliner.main import LineCounter
 
+
 def main():
-    parser = argparse.ArgumentParser(description="Count lines in files by extension.")
+    parser = argparse.ArgumentParser(
+        description="📦 Count lines in files grouped by extension (with/without empty lines)."
+    )
     parser.add_argument(
         "-d", "--directory", type=Path, required=True,
-        help="Directory to count lines in."
+        help="Input directory to count lines in (default: current directory)"
+    )
+    parser.add_argument(
+        "-i", "--ignore", nargs="*", default=[],
+        help="File extensions to ignore (e.g., .log .json)"
+    )
+    parser.add_argument(
+        "-f", "--folders", nargs="*", default=[],
+        help="Folder names to ignore (e.g., .venv __pycache__)"
     )
     parser.add_argument(
-        "-i",
-        "--ignore", nargs="*", default=[],
-        help="List of file extensions to ignore (e.g., .log .json)"
+        "--format", choices=["table", "json", "csv", "md"], default="table",
+        help="Output format: table (default), json, csv, or md (markdown)"
     )
 
     args = parser.parse_args()
 
     if not args.directory.is_dir():
-        print(f"Error: {args.directory} is not a valid directory")
+        print(f"❌ Error: {args.directory} is not a valid directory.")
         return
 
-    counter = LineCounter(ignore_extensions=args.ignore)
+    counter = LineCounter(
+        ignore_extensions=args.ignore,
+        ignore_folder=args.folders,
+    )
     result = counter.count_lines(args.directory)
 
     # Remove extensions with 0 lines
@@ -31,26 +44,31 @@ def main():
         if counts["with_spaces"] > 0 or counts["without_spaces"] > 0
     }
 
-    # Sort result by extension
-    result = dict(sorted(result.items()))
+    # Sort by line count (with spaces) in descending order
+    result = dict(sorted(result.items(), key=lambda item: item[1]["with_spaces"], reverse=True))
 
     total_with_spaces = sum(counts["with_spaces"] for counts in result.values())
-    
-    # sort the result by the number of lines with spaces
-    result = dict(sorted(result.items(), key=lambda item: item[1]["with_spaces"], reverse=True))
 
-    table = []
-    for ext, counts in result.items():
-        with_spaces = counts["with_spaces"]
-        without_spaces = counts["without_spaces"]
-        percent = (with_spaces / total_with_spaces * 100) if total_with_spaces else 0
-        table.append([ext, with_spaces, without_spaces, f"{percent:.2f}%"])
-
-    print(tabulate(
-        table,
-        headers=["Extension", "With Spaces", "Without Spaces", "% of Total"],
-        tablefmt="grid"
-    ))
+    if args.format == "json":
+        print(counter.to_json(result))
+    elif args.format == "csv":
+        print(counter.to_csv(result))
+    elif args.format == "md":
+        print(counter.to_markdown(result))
+    else:
+        # Default: tabular CLI output
+        table = []
+        for ext, counts in result.items():
+            with_spaces = counts["with_spaces"]
+            without_spaces = counts["without_spaces"]
+            percent = (with_spaces / total_with_spaces * 100) if total_with_spaces else 0
+            table.append([ext, with_spaces, without_spaces, counts["file_count"], f"{percent:.2f}%"])
+
+        print(tabulate(
+            table,
+            headers=["Extension", "With Spaces", "Without Spaces", "Files", "% of Total"],
+            tablefmt="grid"
+        ))
 
 
 if __name__ == "__main__":

extliner/main.py

@@ -6,27 +6,33 @@
 
 
 class LineCounter:
-    def __init__(self, ignore_extensions: Optional[List[str]] = None):
+    def __init__(self, ignore_extensions: Optional[List[str]] = None, ignore_folder: Optional[List[str]] = None, encoding: str = "utf-8"):
+        self.encoding = encoding
+        self.ignore_folder = set(ignore_folder or [])
         self.ignore_extensions = set(ignore_extensions or [])
         self.with_spaces: Dict[str, int] = defaultdict(int)
         self.without_spaces: Dict[str, int] = defaultdict(int)
+        self.file_count: Dict[str, int] = defaultdict(int)
 
     def count_lines(self, directory: Path) -> Dict[str, Dict[str, int]]:
         directory = Path(directory)
         if not directory.is_dir():
             raise ValueError(f"{directory} is not a valid directory")
-
-        for root, _, files in os.walk(directory):
+        
+        for root, dirs, files in os.walk(directory):
+            # Remove ignored folders from traversal
+            dirs[:] = [d for d in dirs if d not in self.ignore_folder]
             for file in files:
                 filepath = Path(root) / file
-                ext = filepath.suffix or "NO_EXT"
+                ext = (filepath.suffix or "NO_EXT").lower()
 
                 if ext in self.ignore_extensions:
                     continue
 
                 try:
-                    with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+                    with open(filepath, "r", encoding=self.encoding, errors="ignore") as f:
                         lines = f.readlines()
+                        self.file_count[ext] += 1
                         self.with_spaces[ext] += len(lines)
                         self.without_spaces[ext] += sum(1 for line in lines if line.strip())
                 except Exception as e:
@@ -39,36 +45,34 @@ def _build_result(self) -> Dict[str, Dict[str, int]]:
             ext: {
                 "with_spaces": self.with_spaces[ext],
                 "without_spaces": self.without_spaces[ext],
+                "file_count": self.file_count[ext],
             }
             for ext in sorted(set(self.with_spaces) | set(self.without_spaces))
         }
 
-    def to_json(self, data: Dict) -> str:
+    @staticmethod
+    def to_json(data: Dict) -> str:
         return json.dumps(data, indent=2)
-
-    def to_dict(self, data: Dict) -> Dict:
-        return data
 
-    def to_csv(self, data: Dict) -> str:
+    @staticmethod
+    def to_csv(data: Dict) -> str:
         import csv
         from io import StringIO
 
         output = StringIO()
         writer = csv.writer(output)
-        writer.writerow(["Extension", "With Spaces", "Without Spaces"])
+        writer.writerow(["Extension", "With Spaces", "Without Spaces", "File Count"])
 
         for ext, counts in data.items():
-            writer.writerow([ext, counts["with_spaces"], counts["without_spaces"]])
+            writer.writerow([ext, counts["with_spaces"], counts["without_spaces"], counts["file_count"]])
 
         return output.getvalue()
 
-
-    def to_markdown(self, data: Dict) -> str:
-        output = "| Extension | With Spaces | Without Spaces |\n"
-        output += "|-----------|-------------|----------------|\n"
-
+    @staticmethod
+    def to_markdown(data: Dict) -> str:
+        output = "| Extension | With Spaces | Without Spaces | File Count |\n"
+        output += "|-----------|-------------|----------------|------------|\n"
         for ext, counts in data.items():
-            output += f"| {ext} | {counts['with_spaces']} | {counts['without_spaces']} |\n"
+            output += f"| {ext} | {counts['with_spaces']} | {counts['without_spaces']} | {counts['file_count']} |\n"
 
         return output
-