add claude.md

Author: dilshod

CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+xlsx2csv is a Python utility that converts XLSX files to CSV format. It's designed to handle large XLSX files efficiently and supports multiple Python versions (2.4 to 3.14). The entire converter is implemented in a single Python file `xlsx2csv.py` (~54KB).
+
+## Development Commands
+
+### Testing
+```bash
+python3 test/run
+```
+This runs the comprehensive test suite that compares output from various test XLSX files against expected CSV files. Tests cover edge cases like datetime formatting, empty rows, hyperlinks, various delimiters, and multi-sheet files.
+
+### Building
+```bash
+python3 -m build
+```
+Uses the modern Python build system defined in `pyproject.toml`.
+
+### Installation for Development
+```bash
+pip install -e .
+```
+Install in editable mode for local development.
+
+## Code Architecture
+
+### Core Classes
+- **Xlsx2csv**: Main converter class that orchestrates the conversion process
+- **Workbook**: Represents the XLSX workbook structure and handles ZIP file extraction
+- **Sheet**: Handles individual worksheet conversion with SAX parsing for memory efficiency
+- **SharedStrings**: Manages the shared strings table
+- **Styles**: Handles cell formatting and number formats
+- **ContentTypes**: Manages XLSX content type definitions
+- **Relationships**: Handles XLSX relationship mappings
+
+### Key Design Patterns
+- **SAX Parsing**: Uses `xml.parsers.expat` for memory-efficient XML parsing of large files
+- **Streaming Processing**: Processes XLSX files without loading entire content into memory
+- **Format Detection**: Comprehensive format mapping system (`FORMATS` and `STANDARD_FORMATS` dicts) for proper type conversion
+- **Command-line Interface**: Uses argparse for Python 3+ and optparse fallback for Python 2.4
+
+### File Structure
+- `xlsx2csv.py`: Single-file implementation containing all classes and logic
+- `test/`: Contains test XLSX/CSV file pairs and the test runner
+- `test/run`: Python script that compares converter output against expected results
+
+## Testing Strategy
+The test suite uses a comparison-based approach:
+1. Converts test XLSX files using the converter
+2. Compares output with pre-generated expected CSV files
+3. Tests both file input and STDIN input modes
+4. Covers various edge cases: datetime formatting, hyperlinks, empty cells, multi-sheet files, different encodings
+
+## Key Features Supported
+- Multiple output formats and delimiters
+- Date/time formatting with custom patterns
+- Hyperlink extraction
+- Multi-sheet processing
+- Large file handling via streaming
+- Cross-platform compatibility (Windows/Linux/macOS)
+- Python 2.4 to 3.14 compatibility

README.md

@@ -6,10 +6,10 @@
 Converts xlsx files to csv format.
 Handles large XLSX files. Fast and easy to use.
 
-## Tested(supported) python versions:
+## Tested (supported) Python versions:
  - 2.4
  - 2.7
- - 3.4 to 3.13
+ - 3.4 to 3.14
 
 ## Installation:
 
@@ -23,7 +23,7 @@ pip install xlsx2csv
 ```
 
 
-  Also, works standalone with only the *xlsx2csv.py* script
+Also works standalone with only the *xlsx2csv.py* script.
 
 **Usage:**
 ```
@@ -47,53 +47,53 @@ pip install xlsx2csv
   -v, --version         show program's version number and exit
   -a, --all             export all sheets
   -c OUTPUTENCODING, --outputencoding OUTPUTENCODING
-                        encoding of output csv ** Python 3 only ** (default: utf-8)
+                        encoding of output CSV **Python 3 only** (default: utf-8)
   -s SHEETID, --sheet SHEETID
                         sheet number to convert, 0 for all
   -n SHEETNAME, --sheetname SHEETNAME
                         sheet name to convert
   -d DELIMITER, --delimiter DELIMITER
-                        delimiter - columns delimiter in csv, 'tab' or 'x09'
+                        delimiter - column delimiter in CSV, 'tab' or 'x09'
                         for a tab (default: comma ',')
   -l LINETERMINATOR, --lineterminator LINETERMINATOR
-                        line terminator - lines terminator in csv, '\n' '\r\n'
+                        line terminator - line terminator in CSV, '\n' '\r\n'
                         or '\r' (default: os.linesep)
   -f DATEFORMAT, --dateformat DATEFORMAT
                         override date/time format (ex. %Y/%m/%d)
   --floatformat FLOATFORMAT
                         override float format (ex. %.15f)
   -i, --ignoreempty     skip empty lines
-  -e, --escape          Escape \r\n\t characters
+  -e, --escape          escape \r\n\t characters
   -p SHEETDELIMITER, --sheetdelimiter SHEETDELIMITER
                         sheet delimiter used to separate sheets, pass '' if
-                        you do not need delimiter, or 'x07' or '\\f' for form
+                        you do not need a delimiter, or 'x07' or '\\f' for form
                         feed (default: '--------')
   -q QUOTING, --quoting QUOTING
                         field quoting, 'none' 'minimal' 'nonnumeric' or 'all' (default: 'minimal')
   --hyperlinks, --hyperlinks
                         include hyperlinks
   -I INCLUDE_SHEET_PATTERN [INCLUDE_SHEET_PATTERN ...], --include_sheet_pattern INCLUDE_SHEET_PATTERN [INCLUDE_SHEET_PATTERN ...]
-                        only include sheets named matching given pattern, only
-                        effects when -a option is enabled.
+                        only include sheets with names matching the given pattern, only
+                        affects when -a option is enabled.
   -E EXCLUDE_SHEET_PATTERN [EXCLUDE_SHEET_PATTERN ...], --exclude_sheet_pattern EXCLUDE_SHEET_PATTERN [EXCLUDE_SHEET_PATTERN ...]
-                        exclude sheets named matching given pattern, only
-                        effects when -a option is enabled.
+                        exclude sheets with names matching the given pattern, only
+                        affects when -a option is enabled.
   -m, --merge-cells     merge cells
 ```
 
-Usage with folder containing multiple `xlxs` files:
+Usage with a folder containing multiple `xlsx` files:
 ```
     python xlsx2csv.py /path/to/input/dir /path/to/output/dir
 ```
-will output each file in the input dir converted to `.csv` in the output dir. If omitting the output dir it will output the converted files in the input dir
+will output each file in the input directory converted to `.csv` in the output directory. If omitting the output directory, it will output the converted files in the input directory.
 
 Usage from within Python:
 ```
   from xlsx2csv import Xlsx2csv
   Xlsx2csv("myfile.xlsx", outputencoding="utf-8").convert("myfile.csv")
 ```
 
-Expat SAX parser used for xml parsing.
+Expat SAX parser is used for XML parsing.
 
 See alternatives:
 
@@ -119,6 +119,6 @@ http://poi.apache.org/
 
   Dilshod Temirkhdojaev – [email protected]
 
-Distributed under the MIT LICENSE. See ``LICENSE`` for more information.
+Distributed under the MIT license. See ``LICENSE`` for more information.
 
 [https://github.com/dilshod](https://github.com/dilshod)

pyproject.toml

@@ -35,6 +35,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Office/Business",
     "Topic :: Utilities",
 ]

xlsx2csv.py

@@ -313,7 +313,7 @@ def _convert(self, sheet_index, outfile):
             elif sys.version_info[0] == 3:
                 outfile = open(outfile, 'w+', encoding=self.options['outputencoding'], newline="")
             else:
-                raise XlsxException("error: version of your python is not supported: " + str(sys.version_info) + "\n")
+                raise XlsxException("error: version of your Python is not supported: " + str(sys.version_info) + "\n")
             closefile = True
         elif hasattr(outfile, "open"):
             outfile = outfile.open("w+", encoding=self.options['outputencoding'], newline="")
@@ -1112,7 +1112,7 @@ def main():
     if "ArgumentParser" in globals():
         parser = ArgumentParser(description="xlsx to csv converter")
         parser.add_argument('infile', metavar='xlsxfile', help="xlsx file path, use '-' to read from STDIN")
-        parser.add_argument('outfile', metavar='outfile', nargs='?', help="output csv file path")
+        parser.add_argument('outfile', metavar='outfile', nargs='?', help="output CSV file path")
         parser.add_argument('-v', '--version', action='version', version=__version__)
         nargs_plus = "+"
         argparser = True
@@ -1129,17 +1129,17 @@ def main():
     parser.add_argument("-a", "--all", dest="all", default=False, action="store_true",
                         help="export all sheets")
     parser.add_argument("-c", "--outputencoding", dest="outputencoding", default="utf-8", action="store",
-                        help="encoding of output csv ** Python 3 only ** (default: utf-8)")
+                        help="encoding of output CSV **Python 3 only** (default: utf-8)")
     parser.add_argument("-d", "--delimiter", dest="delimiter", default=",",
-                        help="delimiter - columns delimiter in csv, 'tab' or 'x09' for a tab (default: comma ',')")
+                        help="delimiter - column delimiter in CSV, 'tab' or 'x09' for a tab (default: comma ',')")
     parser.add_argument("--hyperlinks", "--hyperlinks", dest="hyperlinks", action="store_true", default=False,
                         help="include hyperlinks")
     parser.add_argument("-e", "--escape", dest='escape_strings', default=False, action="store_true",
-                        help="Escape \\r\\n\\t characters")
+                        help="escape \\r\\n\\t characters")
     parser.add_argument("--no-line-breaks", "--no-line-breaks", dest='no_line_breaks', default=False, action="store_true",
-                        help="Replace \\r\\n\\t with space")
+                        help="replace \\r\\n\\t with space")
     parser.add_argument("-E", "--exclude_sheet_pattern", nargs=nargs_plus, dest="exclude_sheet_pattern", default="",
-                        help="exclude sheets named matching given pattern, only effects when -a option is enabled.")
+                        help="exclude sheets with names matching the given pattern, only affects when -a option is enabled.")
     parser.add_argument("-f", "--dateformat", dest="dateformat",
                         help="override date/time format (ex. %%Y/%%m/%%d)")
     parser.add_argument("-t", "--timeformat", dest="timeformat",
@@ -1149,13 +1149,13 @@ def main():
     parser.add_argument("--sci-float", dest="scifloat", default=False, action="store_true",
                         help="force scientific notation to float")
     parser.add_argument("-I", "--include_sheet_pattern", nargs=nargs_plus, dest="include_sheet_pattern", default="^.*$",
-                        help="only include sheets named matching given pattern, only effects when -a option is enabled.")
+                        help="only include sheets with names matching the given pattern, only affects when -a option is enabled.")
     parser.add_argument("--exclude_hidden_sheets", default=False, action="store_true",
-                        help="Exclude hidden sheets from the output, only effects when -a option is enabled.")
+                        help="exclude hidden sheets from the output, only affects when -a option is enabled.")
     parser.add_argument("--ignore-formats", nargs=nargs_plus, type=str, dest="ignore_formats", default=[''],
-                        help="Ignores format for specific data types.")
+                        help="ignore format for specific data types")
     parser.add_argument("-l", "--lineterminator", dest="lineterminator", default="\n",
-                        help="line terminator - lines terminator in csv, '\\n' '\\r\\n' or '\\r' (default: \\n)")
+                        help="line terminator - line terminator in CSV, '\\n' '\\r\\n' or '\\r' (default: \\n)")
     parser.add_argument("-m", "--merge-cells", dest="merge_cells", default=False, action="store_true",
                         help="merge cells")
     parser.add_argument("-n", "--sheetname", dest="sheetname", default=None,
@@ -1165,10 +1165,10 @@ def main():
     parser.add_argument("--skipemptycolumns", dest="skip_trailing_columns", default=False, action="store_true",
                         help="skip trailing empty columns")
     parser.add_argument("-p", "--sheetdelimiter", dest="sheetdelimiter", default="--------",
-                        help="sheet delimiter used to separate sheets, pass '' if you do not need delimiter, or 'x07' "
+                        help="sheet delimiter used to separate sheets, pass '' if you do not need a delimiter, or 'x07' "
                              "or '\\f' for form feed (default: '--------')")
     parser.add_argument("-q", "--quoting", dest="quoting", default="minimal",
-                        help="quoting - fields quoting in csv, 'none' 'minimal' 'nonnumeric' or 'all' (default: minimal)")
+                        help="quoting - field quoting in CSV, 'none' 'minimal' 'nonnumeric' or 'all' (default: minimal)")
     parser.add_argument("-s", "--sheet", dest="sheetid", default=1, type=inttype,
                         help="sheet number to convert")
     parser.add_argument("--include-hidden-rows", dest="include_hidden_rows", default=False, action="store_true",