rapcsv 0.0.2__cp38-cp38-manylinux_2_28_x86_64.whl → 0.2.0__cp38-cp38-manylinux_2_28_x86_64.whl

rapcsv/__init__.py

@@ -1,16 +1,423 @@
-"""Streaming async CSV — no fake async, no GIL stalls."""
+"""Streaming async CSV — no fake async, no GIL stalls.
+
+rapcsv provides true async CSV reading and writing for Python, backed by Rust and Tokio.
+Unlike libraries that wrap blocking I/O in async syntax, rapcsv guarantees that all CSV
+operations execute **outside the Python GIL**, ensuring event loops never stall under load.
+
+Features
+--------
+- True async CSV reading and writing
+- Streaming support for large files (incremental reading, no full file load)
+- Context manager support (``async with``)
+- aiocsv compatibility (AsyncReader/AsyncWriter aliases)
+- CSV-specific exception types (CSVError, CSVFieldCountError)
+- RFC 4180 compliant CSV parsing and writing
+
+Example
+-------
+.. code-block:: python
+
+    import asyncio
+    from rapcsv import Reader, Writer
+
+    async def main():
+        async with Writer("output.csv") as writer:
+            await writer.write_row(["name", "age"])
+            await writer.write_row(["Alice", "30"])
+
+        async with Reader("output.csv") as reader:
+            row = await reader.read_row()
+            print(row)  # ['name', 'age']
+
+    asyncio.run(main())
+
+For more information, see: https://github.com/eddiethedean/rapcsv
+"""
+
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class WithAsyncRead(Protocol):
+    """Protocol for async file-like objects with read method.
+
+    This protocol defines the interface for async file-like objects that can be used
+    with rapcsv's Reader and AsyncDictReader classes. Objects implementing this
+    protocol must provide an async ``read()`` method.
+
+    Examples
+    --------
+    Objects from ``aiofiles`` and ``rapfiles`` implement this protocol:
+
+    .. code-block:: python
+
+        import aiofiles
+        from rapcsv import Reader
+
+        async with aiofiles.open("data.csv", mode="r") as f:
+            reader = Reader(f)  # f implements WithAsyncRead
+    """
+
+    async def read(self, size: int) -> str:
+        """Read up to size bytes/characters from the file.
+
+        Args:
+            size: Number of bytes/characters to read.
+
+        Returns:
+            String containing the read data.
+        """
+        ...
+
+
+@runtime_checkable
+class WithAsyncWrite(Protocol):
+    """Protocol for async file-like objects with write method.
+
+    This protocol defines the interface for async file-like objects that can be used
+    with rapcsv's Writer and AsyncDictWriter classes. Objects implementing this
+    protocol must provide an async ``write()`` method.
+
+    Examples
+    --------
+    Objects from ``aiofiles`` and ``rapfiles`` implement this protocol:
+
+    .. code-block:: python
+
+        import aiofiles
+        from rapcsv import Writer
+
+        async with aiofiles.open("output.csv", mode="w") as f:
+            writer = Writer(f)  # f implements WithAsyncWrite
+    """
+
+    async def write(self, data: str) -> None:
+        """Write data to the file.
+
+        Args:
+            data: String data to write to the file.
+        """
+        ...
+
+
+# Internal helper function to call async file methods from any thread
+# This schedules the call on the event loop using run_coroutine_threadsafe
+def _call_file_method_threadsafe(file_handle, method_name, event_loop, *args):
+    """Call an async file method from any thread by scheduling it on the event loop.
+
+    This is used by the Rust extension to call rapfiles methods from spawn_blocking threads.
+    The function schedules the async method call on the provided event loop using
+    ``asyncio.run_coroutine_threadsafe()``.
+
+    Args:
+        file_handle: The file handle object with async methods.
+        method_name: Name of the method to call (e.g., "write", "read").
+        event_loop: The event loop to schedule the call on.
+        *args: Arguments to pass to the method.
+
+    Returns:
+        The result of the async method call.
+
+    Note:
+        This is an internal helper function and should not be called directly
+        by user code.
+    """
+    import asyncio
+
+    # Create a coroutine that calls the method
+    async def _call_method():
+        method = getattr(file_handle, method_name)
+        result = method(*args)
+        # If it returns a Future or coroutine, await it
+        if hasattr(result, "__await__"):
+            return await result
+        return result
+
+    # Schedule the coroutine on the event loop
+    # This will execute on the event loop thread, not the current thread
+    future = asyncio.run_coroutine_threadsafe(_call_method(), event_loop)
+    return future.result()
+
+
+# Internal helper function to wrap Futures into coroutines for run_coroutine_threadsafe
+# This is used by the Rust extension to convert rapfiles Futures to coroutines
+def _await_wrapper(fut):
+    """Wrap a Future into a coroutine using types.coroutine.
+
+    This function is called from Rust code to convert asyncio.Future objects
+    (like those returned by rapfiles) into coroutines that can be used with
+    ``asyncio.run_coroutine_threadsafe()``.
+
+    Args:
+        fut: A Future or coroutine object to wrap.
+
+    Returns:
+        A coroutine object that can be awaited.
+
+    Note:
+        This function must work even when called from a thread without an event loop.
+        This is an internal helper function and should not be called directly
+        by user code.
+    """
+    import inspect
+    import types
+
+    # Check if already a coroutine using inspect (doesn't need event loop)
+    if inspect.iscoroutine(fut):
+        return fut
+
+    # It's a Future - wrap it in a generator function, then use types.coroutine
+    # This approach doesn't require an event loop to be running
+    # The generator will be executed on the event loop via run_coroutine_threadsafe
+    def _gen_wrapper(fut):
+        # yield from will work when the coroutine is executed on the event loop
+        # This doesn't execute immediately - it just creates a generator
+        return (yield from fut)
+
+    # Wrap the generator function with types.coroutine to make it a coroutine function
+    coro_func = types.coroutine(_gen_wrapper)
+
+    # Call it to get a coroutine object (doesn't execute yet, no event loop needed)
+    # The coroutine will be executed later on the event loop
+    return coro_func(fut)
 
-from typing import List
 
 try:
-    from _rapcsv import Reader, Writer  # type: ignore[import-not-found]
+    from _rapcsv import (
+        AsyncDictReader,
+        AsyncDictWriter,
+        CSVError,
+        CSVFieldCountError,
+        Reader,
+        Writer,
+    )  # type: ignore[import-not-found]
 except ImportError:
     try:
-        from rapcsv._rapcsv import Reader, Writer
-    except ImportError:
+        from rapcsv._rapcsv import (
+            AsyncDictReader,
+            AsyncDictWriter,
+            CSVError,
+            CSVFieldCountError,
+            Reader,
+            Writer,
+        )
+    except ImportError as err:
         raise ImportError(
             "Could not import _rapcsv. Make sure rapcsv is built with maturin."
-        )
+        ) from err
+
+# API compatibility with aiocsv
+# aiocsv uses AsyncReader and AsyncWriter as class names
+AsyncReader = Reader
+"""Alias for :class:`Reader` for aiocsv compatibility.
+
+This alias allows drop-in replacement of aiocsv code.
+
+Example:
+    .. code-block:: python
+
+        from rapcsv import AsyncReader  # Instead of from aiocsv import AsyncReader
+        reader = AsyncReader("data.csv")
+"""
+
+AsyncWriter = Writer
+"""Alias for :class:`Writer` for aiocsv compatibility.
+
+This alias allows drop-in replacement of aiocsv code.
+
+Example:
+    .. code-block:: python
+
+        from rapcsv import AsyncWriter  # Instead of from aiocsv import AsyncWriter
+        writer = AsyncWriter("output.csv")
+"""
+
+__version__: str = "0.2.0"
+
+# Dialect presets for common CSV formats
+EXCEL_DIALECT: Dict[str, Any] = {
+    "delimiter": ",",
+    "quotechar": '"',
+    "lineterminator": "\r\n",
+    "quoting": 1,  # QUOTE_MINIMAL
+    "double_quote": True,
+}
+"""Excel-compatible CSV dialect preset.
+
+This dialect matches Microsoft Excel's CSV format:
+- Delimiter: comma (``,``)
+- Quote character: double quote (``"``)
+- Line terminator: CRLF (``\\r\\n``)
+- Quoting: QUOTE_MINIMAL (1)
+- Double quote: enabled
+
+Example:
+    .. code-block:: python
+
+        from rapcsv import Writer, EXCEL_DIALECT
+
+        writer = Writer("output.csv", **EXCEL_DIALECT)
+        await writer.write_row(["col1", "col2"])
+"""
+
+UNIX_DIALECT: Dict[str, Any] = {
+    "delimiter": ",",
+    "quotechar": '"',
+    "lineterminator": "\n",
+    "quoting": 1,  # QUOTE_MINIMAL
+    "double_quote": True,
+}
+"""Unix-compatible CSV dialect preset.
+
+This dialect uses Unix-style line endings:
+- Delimiter: comma (``,``)
+- Quote character: double quote (``"``)
+- Line terminator: LF (``\\n``)
+- Quoting: QUOTE_MINIMAL (1)
+- Double quote: enabled
+
+Example:
+    .. code-block:: python
+
+        from rapcsv import Writer, UNIX_DIALECT
+
+        writer = Writer("output.csv", **UNIX_DIALECT)
+        await writer.write_row(["col1", "col2"])
+"""
+
+RFC4180_DIALECT: Dict[str, Any] = {
+    "delimiter": ",",
+    "quotechar": '"',
+    "lineterminator": "\r\n",
+    "quoting": 1,  # QUOTE_MINIMAL
+    "double_quote": True,
+}
+"""RFC 4180 compliant CSV dialect preset.
+
+This dialect strictly follows RFC 4180 specification:
+- Delimiter: comma (``,``)
+- Quote character: double quote (``"``)
+- Line terminator: CRLF (``\\r\\n``)
+- Quoting: QUOTE_MINIMAL (1)
+- Double quote: enabled
+
+Example:
+    .. code-block:: python
+
+        from rapcsv import Writer, RFC4180_DIALECT
+
+        writer = Writer("output.csv", **RFC4180_DIALECT)
+        await writer.write_row(["col1", "col2"])
+"""
+
+
+def convert_types(row: List[str], converters: Optional[Dict[int, Any]] = None) -> List[Any]:
+    """Convert row fields to appropriate types.
+
+    Automatically infers types (int, float, bool) or applies custom converter functions
+    per column. If a converter fails, the original string value is preserved.
+
+    Args:
+        row: List of string values from CSV row.
+        converters: Optional dictionary mapping column index (int) to converter
+            function (callable). If provided, only specified columns are converted
+            using the provided functions. Other columns use automatic inference.
+
+    Returns:
+        List with converted values. Types may be int, float, bool, or str.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        from rapcsv import Reader, convert_types
+
+        reader = Reader("data.csv")
+        row = await reader.read_row()  # ['Alice', '30', 'NYC']
+
+        # Automatic type conversion
+        converted = convert_types(row)
+        # ['Alice', 30, 'NYC']  # age converted to int
+
+        # Per-column converters
+        converters = {1: int, 2: str.upper}
+        converted = convert_types(row, converters)
+        # ['Alice', 30, 'NYC']  # column 1 to int, column 2 to uppercase
+    """
+    if converters:
+        result = []
+        for i, value in enumerate(row):
+            if i in converters:
+                try:
+                    result.append(converters[i](value))
+                except (ValueError, TypeError):
+                    result.append(value)  # Keep original if conversion fails
+            else:
+                result.append(_auto_convert(value))
+        return result
+    else:
+        return [_auto_convert(v) for v in row]
+
+
+def _auto_convert(value: str) -> Any:
+    """Automatically convert a string value to appropriate type.
+
+    Attempts type conversion in the following order:
+    1. Integer (if no decimal point or scientific notation)
+    2. Float
+    3. Boolean (true/false, yes/no, 1/0, on/off)
+    4. Original string (if no conversion succeeds)
+
+    Args:
+        value: String value to convert.
+
+    Returns:
+        Converted value (int, float, bool, or str).
+
+    Note:
+        This is an internal helper function used by ``convert_types()``.
+        Empty strings are returned as-is.
+    """
+    if not value or value.strip() == "":
+        return value
+
+    # Try int
+    try:
+        if "." not in value and "e" not in value.lower():
+            return int(value)
+    except ValueError:
+        pass
+
+    # Try float
+    try:
+        return float(value)
+    except ValueError:
+        pass
+
+    # Try bool
+    lower = value.lower().strip()
+    if lower in ("true", "yes", "1", "on"):
+        return True
+    if lower in ("false", "no", "0", "off", ""):
+        return False
+
+    # Return as string
+    return value
+
 
-__version__: str = "0.0.2"
-__all__: List[str] = ["Reader", "Writer"]
+__all__: List[str] = [
+    "Reader",
+    "Writer",
+    "AsyncDictReader",
+    "AsyncDictWriter",
+    "AsyncReader",  # aiocsv compatibility
+    "AsyncWriter",  # aiocsv compatibility
+    "CSVError",
+    "CSVFieldCountError",
+    "WithAsyncRead",  # Protocol for type checking
+    "WithAsyncWrite",  # Protocol for type checking
+    "EXCEL_DIALECT",  # Dialect preset
+    "UNIX_DIALECT",  # Dialect preset
+    "RFC4180_DIALECT",  # Dialect preset
+    "convert_types",  # Type conversion utility
+]

rapcsv/_rapcsv.pyi

@@ -1,11 +1,453 @@
-"""Type stubs for _rapcsv Rust extension module."""
+"""Type stubs for _rapcsv Rust extension module.
 
-from typing import Coroutine, Any, List
+This module provides type information for the Rust-compiled extension module.
+All classes and methods are implemented in Rust and exposed to Python via PyO3.
+
+Note:
+    This is a type stub file (``.pyi``) used for static type checking.
+    The actual implementation is in the compiled Rust extension module.
+"""
+
+from typing import Any, Coroutine, Dict, List, Optional
 
 class Reader:
-    def __init__(self, path: str) -> None: ...
-    def read_row(self) -> Coroutine[Any, Any, List[str]]: ...
+    """Async CSV reader for streaming CSV files.
+
+    Provides true async CSV reading with GIL-independent operations.
+    Files are streamed incrementally without loading the entire file into memory.
+
+    Args:
+        path: Path to CSV file or async file-like object (WithAsyncRead).
+        delimiter: Field delimiter character (default: ',').
+        quotechar: Quote character (default: '"').
+        escapechar: Escape character (default: None).
+        quoting: Quoting style: 0=QUOTE_NONE, 1=QUOTE_MINIMAL, 2=QUOTE_ALL,
+            3=QUOTE_NONNUMERIC, 4=QUOTE_NOTNULL, 6=QUOTE_STRINGS (default: 1).
+        lineterminator: Line terminator string (default: '\\r\\n').
+        skipinitialspace: Skip whitespace after delimiter (default: False).
+        strict: Strict mode for field count validation (default: False).
+        double_quote: Handle doubled quotes (default: True).
+        read_size: Buffer size for reading chunks in bytes (default: 8192).
+        field_size_limit: Maximum field size in bytes (default: None).
+
+    Examples
+    --------
+    .. code-block:: python
+
+        from rapcsv import Reader
+
+        # Read from file path
+        reader = Reader("data.csv")
+        row = await reader.read_row()
+
+        # Read from async file handle
+        import aiofiles
+        async with aiofiles.open("data.csv", mode="r") as f:
+            reader = Reader(f)
+            row = await reader.read_row()
+    """
+
+    def __init__(
+        self,
+        path: str,
+        delimiter: Optional[str] = None,
+        quotechar: Optional[str] = None,
+        escapechar: Optional[str] = None,
+        quoting: Optional[int] = None,
+        lineterminator: Optional[str] = None,
+        skipinitialspace: Optional[bool] = None,
+        strict: Optional[bool] = None,
+        double_quote: Optional[bool] = None,
+        read_size: Optional[int] = None,
+        field_size_limit: Optional[int] = None,
+    ) -> None: ...
+    def read_row(self) -> Coroutine[Any, Any, List[str]]:
+        """Read the next row from the CSV file.
+
+        Returns:
+            List of string values for the row, or empty list if EOF.
+
+        Raises:
+            IOError: If the file cannot be read.
+            CSVError: If the CSV file is malformed or cannot be parsed.
+
+        Note:
+            The Reader maintains position state across calls, reading sequentially.
+            Files are streamed incrementally without loading the entire file.
+        """
+        ...
+
+    def read_rows(self, n: int) -> Coroutine[Any, Any, List[List[str]]]:
+        """Read multiple rows at once.
+
+        Args:
+            n: Number of rows to read.
+
+        Returns:
+            List of rows, where each row is a list of string values.
+        """
+        ...
+
+    def skip_rows(self, n: int) -> Coroutine[Any, Any, None]:
+        """Skip multiple rows efficiently without parsing.
+
+        Args:
+            n: Number of rows to skip.
+        """
+        ...
+
+    @property
+    def line_num(self) -> int:
+        """Current line number (1-based).
+
+        For multi-line records, this counts actual lines, not just records.
+        """
+        ...
+
+    def __aiter__(self) -> Reader:
+        """Async iterator protocol - returns self."""
+        ...
+
+    def __anext__(self) -> Coroutine[Any, Any, List[str]]:
+        """Async iterator next - returns next row or raises StopAsyncIteration."""
+        ...
+
+    def __aenter__(self) -> Coroutine[Any, Any, Reader]:
+        """Async context manager entry."""
+        ...
+
+    def __aexit__(
+        self,
+        exc_type: Optional[Any],
+        exc_val: Optional[Any],
+        exc_tb: Optional[Any],
+    ) -> Coroutine[Any, Any, None]:
+        """Async context manager exit - closes the file handle."""
+        ...
 
 class Writer:
-    def __init__(self, path: str) -> None: ...
-    def write_row(self, row: List[str]) -> Coroutine[Any, Any, None]: ...
+    """Async CSV writer for streaming CSV files.
+
+    Provides true async CSV writing with GIL-independent operations.
+    The Writer reuses file handles across multiple write operations for efficiency.
+
+    Args:
+        path: Path to CSV file or async file-like object (WithAsyncWrite).
+        delimiter: Field delimiter character (default: ',').
+        quotechar: Quote character (default: '"').
+        escapechar: Escape character (default: None).
+        quoting: Quoting style: 0=QUOTE_NONE, 1=QUOTE_MINIMAL, 2=QUOTE_ALL,
+            3=QUOTE_NONNUMERIC, 4=QUOTE_NOTNULL, 6=QUOTE_STRINGS (default: 1).
+        lineterminator: Line terminator string (default: '\\r\\n').
+        double_quote: Handle doubled quotes (default: True).
+        write_size: Buffer size for writing chunks in bytes (default: 8192).
+
+    Examples
+    --------
+    .. code-block:: python
+
+        from rapcsv import Writer
+
+        # Write to file path
+        writer = Writer("output.csv")
+        await writer.write_row(["name", "age"])
+
+        # Write to async file handle
+        import aiofiles
+        async with aiofiles.open("output.csv", mode="w") as f:
+            writer = Writer(f)
+            await writer.write_row(["name", "age"])
+    """
+
+    def __init__(
+        self,
+        path: str,
+        delimiter: Optional[str] = None,
+        quotechar: Optional[str] = None,
+        escapechar: Optional[str] = None,
+        quoting: Optional[int] = None,
+        lineterminator: Optional[str] = None,
+        double_quote: Optional[bool] = None,
+        write_size: Optional[int] = None,
+    ) -> None: ...
+    def write_row(self, row: List[str]) -> Coroutine[Any, Any, None]:
+        """Write a row to the CSV file.
+
+        Args:
+            row: List of string values to write as a CSV row.
+
+        Raises:
+            IOError: If the file cannot be written.
+
+        Note:
+            The Writer reuses the file handle across multiple calls for efficiency.
+            Proper RFC 4180 compliant CSV escaping and quoting is applied automatically.
+        """
+        ...
+
+    def writerows(self, rows: List[List[str]]) -> Coroutine[Any, Any, None]:
+        """Write multiple rows to the CSV file efficiently.
+
+        Args:
+            rows: List of rows, where each row is a list of string values.
+        """
+        ...
+
+    def close(self) -> Coroutine[Any, Any, None]:
+        """Explicitly close the file handle and flush any pending writes."""
+        ...
+
+    def __aenter__(self) -> Coroutine[Any, Any, Writer]:
+        """Async context manager entry."""
+        ...
+
+    def __aexit__(
+        self,
+        exc_type: Optional[Any],
+        exc_val: Optional[Any],
+        exc_tb: Optional[Any],
+    ) -> Coroutine[Any, Any, None]:
+        """Async context manager exit - closes the file handle and flushes writes."""
+        ...
+
+class AsyncDictReader:
+    """Async dictionary-based CSV reader.
+
+    Returns rows as dictionaries mapping field names to values.
+    Supports automatic header detection and header manipulation.
+
+    Args:
+        path: Path to CSV file or async file-like object (WithAsyncRead).
+        fieldnames: Optional list of field names. If None, first row is used as header.
+        restkey: Key name for extra values when row has more fields than fieldnames
+            (default: None).
+        restval: Default value for missing fields when row has fewer fields
+            (default: None).
+        delimiter: Field delimiter character (default: ',').
+        quotechar: Quote character (default: '"').
+        escapechar: Escape character (default: None).
+        quoting: Quoting style (default: 1, QUOTE_MINIMAL).
+        lineterminator: Line terminator string (default: '\\r\\n').
+        skipinitialspace: Skip whitespace after delimiter (default: False).
+        strict: Strict mode for field count validation (default: False).
+        double_quote: Handle doubled quotes (default: True).
+        read_size: Buffer size for reading chunks in bytes (default: 8192).
+
+    Examples
+    --------
+    .. code-block:: python
+
+        from rapcsv import AsyncDictReader
+
+        # Automatic header detection
+        reader = AsyncDictReader("data.csv")
+        row = await reader.read_row()  # {'name': 'Alice', 'age': '30'}
+
+        # Explicit fieldnames
+        reader = AsyncDictReader("data.csv", fieldnames=["name", "age", "city"])
+        row = await reader.read_row()
+    """
+
+    def __init__(
+        self,
+        path: str,
+        fieldnames: Optional[List[str]] = None,
+        restkey: Optional[str] = None,
+        restval: Optional[str] = None,
+        delimiter: Optional[str] = None,
+        quotechar: Optional[str] = None,
+        escapechar: Optional[str] = None,
+        quoting: Optional[int] = None,
+        lineterminator: Optional[str] = None,
+        skipinitialspace: Optional[bool] = None,
+        strict: Optional[bool] = None,
+        double_quote: Optional[bool] = None,
+        read_size: Optional[int] = None,
+    ) -> None: ...
+    def read_row(self) -> Coroutine[Any, Any, Dict[str, str]]:
+        """Read the next row as a dictionary.
+
+        Returns:
+            Dictionary mapping field names to values, or empty dict if EOF.
+        """
+        ...
+
+    def get_fieldnames(self) -> Coroutine[Any, Any, Optional[List[str]]]:
+        """Get fieldnames (lazy loaded).
+
+        Returns:
+            List of field names, or None if fieldnames haven't been loaded yet.
+        """
+        ...
+
+    def add_field(self, field_name: str) -> Coroutine[Any, Any, None]:
+        """Add a field to the fieldnames list.
+
+        Args:
+            field_name: Name of the field to add.
+        """
+        ...
+
+    def remove_field(self, field_name: str) -> Coroutine[Any, Any, None]:
+        """Remove a field from the fieldnames list.
+
+        Args:
+            field_name: Name of the field to remove.
+        """
+        ...
+
+    def rename_field(self, old_name: str, new_name: str) -> Coroutine[Any, Any, None]:
+        """Rename a field in the fieldnames list.
+
+        Args:
+            old_name: Current field name.
+            new_name: New field name.
+
+        Raises:
+            ValueError: If old_name is not found in fieldnames.
+            RuntimeError: If fieldnames haven't been loaded yet.
+        """
+        ...
+
+    @property
+    def fieldnames(self) -> Optional[List[str]]:
+        """Property for accessing fieldnames.
+
+        May be None until first row is read. For reliable access, use
+        ``get_fieldnames()`` coroutine instead.
+        """
+        ...
+
+    def __aiter__(self) -> AsyncDictReader:
+        """Async iterator protocol - returns self."""
+        ...
+
+    def __anext__(self) -> Coroutine[Any, Any, Dict[str, str]]:
+        """Async iterator next - returns next row as dict or raises StopAsyncIteration."""
+        ...
+
+class AsyncDictWriter:
+    """Async dictionary-based CSV writer.
+
+    Writes rows from dictionaries mapping field names to values.
+    Requires explicit fieldnames to define CSV structure.
+
+    Args:
+        path: Path to CSV file or async file-like object (WithAsyncWrite).
+        fieldnames: List of column names defining CSV structure (required).
+        restval: Default value for missing keys in dictionary (default: '').
+        extrasaction: Action for extra keys: 'raise' (default) or 'ignore'.
+        delimiter: Field delimiter character (default: ',').
+        quotechar: Quote character (default: '"').
+        escapechar: Escape character (default: None).
+        quoting: Quoting style (default: 1, QUOTE_MINIMAL).
+        lineterminator: Line terminator string (default: '\\r\\n').
+        double_quote: Handle doubled quotes (default: True).
+        write_size: Buffer size for writing chunks in bytes (default: 8192).
+
+    Examples
+    --------
+    .. code-block:: python
+
+        from rapcsv import AsyncDictWriter
+
+        writer = AsyncDictWriter("output.csv", fieldnames=["name", "age", "city"])
+        await writer.writeheader()
+        await writer.writerow({"name": "Alice", "age": "30", "city": "NYC"})
+    """
+
+    def __init__(
+        self,
+        path: str,
+        fieldnames: List[str],
+        restval: Optional[str] = None,
+        extrasaction: Optional[str] = None,
+        delimiter: Optional[str] = None,
+        quotechar: Optional[str] = None,
+        escapechar: Optional[str] = None,
+        quoting: Optional[int] = None,
+        lineterminator: Optional[str] = None,
+        double_quote: Optional[bool] = None,
+        write_size: Optional[int] = None,
+    ) -> None: ...
+    def writeheader(self) -> Coroutine[Any, Any, None]:
+        """Write header row with fieldnames."""
+        ...
+
+    def writerow(self, row: Dict[str, str]) -> Coroutine[Any, Any, None]:
+        """Write a single dictionary row.
+
+        Args:
+            row: Dictionary mapping field names to values.
+
+        Raises:
+            ValueError: If extrasaction='raise' and row contains extra keys
+                not in fieldnames.
+        """
+        ...
+
+    def writerows(self, rows: List[Dict[str, str]]) -> Coroutine[Any, Any, None]:
+        """Write multiple dictionary rows efficiently.
+
+        Args:
+            rows: List of dictionaries to write.
+        """
+        ...
+
+    def close(self) -> Coroutine[Any, Any, None]:
+        """Explicitly close the file handle and flush any pending writes."""
+        ...
+
+    def __aenter__(self) -> Coroutine[Any, Any, AsyncDictWriter]:
+        """Async context manager entry."""
+        ...
+
+    def __aexit__(
+        self,
+        exc_type: Optional[Any],
+        exc_val: Optional[Any],
+        exc_tb: Optional[Any],
+    ) -> Coroutine[Any, Any, None]:
+        """Async context manager exit - closes the file handle and flushes writes."""
+        ...
+
+class CSVError(Exception):
+    """Raised when a CSV parsing error occurs.
+
+    This exception is raised when the CSV file is malformed or cannot be parsed.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        from rapcsv import Reader, CSVError
+
+        try:
+            reader = Reader("malformed.csv")
+            row = await reader.read_row()
+        except CSVError as e:
+            print(f"CSV parsing error: {e}")
+    """
+
+    ...
+
+class CSVFieldCountError(Exception):
+    """Raised when there's a mismatch in the number of fields between rows.
+
+    This exception is raised when strict mode is enabled and rows have
+    inconsistent field counts.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        from rapcsv import Reader, CSVFieldCountError
+
+        try:
+            reader = Reader("data.csv", strict=True)
+            row = await reader.read_row()
+        except CSVFieldCountError as e:
+            print(f"Field count mismatch: {e}")
+    """
+
+    ...

rapcsv-0.2.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: rapcsv
+Version: 0.2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
+Requires-Dist: sphinx>=7.0 ; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=1.3.0 ; extra == 'docs'
+Requires-Dist: myst-parser>=2.0.0 ; extra == 'docs'
+Requires-Dist: ruff>=0.1.0 ; extra == 'lint'
+Requires-Dist: pytest>=7.0 ; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23.8 ; extra == 'test'
+Requires-Dist: pytest-timeout>=2.0 ; extra == 'test'
+Requires-Dist: aiocsv>=0.3.0 ; extra == 'test'
+Requires-Dist: aiofiles>=23.0 ; extra == 'test'
+Requires-Dist: rapfiles>=0.2.1 ; extra == 'test'
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: lint
+Provides-Extra: test
+Summary: Streaming async CSV — no fake async, no GIL stalls.
+Keywords: async,csv,streaming,async-io
+Author: RAP Project
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://rapcsv.readthedocs.io/
+Project-URL: Homepage, https://github.com/eddiethedean/rapcsv
+Project-URL: Issues, https://github.com/eddiethedean/rapcsv/issues
+Project-URL: Repository, https://github.com/eddiethedean/rapcsv
+
+# rapcsv
+
+**Streaming async CSV — no fake async, no GIL stalls.**
+
+[![PyPI version](https://img.shields.io/pypi/v/rapcsv.svg)](https://pypi.org/project/rapcsv/)
+[![Downloads](https://pepy.tech/badge/rapcsv)](https://pepy.tech/project/rapcsv)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+`rapcsv` provides true async CSV reading and writing for Python, backed by Rust and Tokio. Unlike libraries that wrap blocking I/O in `async` syntax, `rapcsv` guarantees that all CSV operations execute **outside the Python GIL**, ensuring event loops never stall under load, even when processing large files.
+
+**Roadmap Goal**: Achieve drop-in replacement compatibility with `aiocsv`, enabling seamless migration with true async performance. See [docs/ROADMAP.md](https://github.com/eddiethedean/rapcsv/blob/main/docs/ROADMAP.md) for details.
+
+## Why `rap*`?
+
+Packages prefixed with **`rap`** stand for **Real Async Python**. Unlike many libraries that merely wrap blocking I/O in `async` syntax, `rap*` packages guarantee that all I/O work is executed **outside the Python GIL** using native runtimes (primarily Rust). This means event loops are never stalled by hidden thread pools, blocking syscalls, or cooperative yielding tricks. If a `rap*` API is `async`, it is *structurally non-blocking by design*, not by convention. The `rap` prefix is a contract: measurable concurrency, real parallelism, and verifiable async behavior under load.
+
+See the [rap-manifesto](https://github.com/eddiethedean/rap-manifesto) for philosophy and guarantees.
+
+## Features
+
+- ✅ **True async** CSV reading and writing
+- ✅ **Streaming support** for large files
+- ✅ **Native Rust-backed** execution (Tokio)
+- ✅ **Zero Python thread pools**
+- ✅ **Event-loop-safe** concurrency under load
+- ✅ **GIL-independent** I/O operations
+- ✅ **Verified** by Fake Async Detector
+- ✅ **aiofiles compatibility** (drop-in replacement)
+
+### Feature Categories
+
+- **Core Operations** - Read and write CSV files with true async I/O
+- **File Handles** - Support for file paths and async file-like objects (`aiofiles`, `rapfiles`)
+- **Context Managers** - Async context manager support (`async with`)
+- **Dict Readers/Writers** - Dictionary-based CSV operations (`AsyncDictReader`, `AsyncDictWriter`)
+- **Streaming** - Incremental reading without loading entire files into memory
+- **Error Handling** - CSV-specific exceptions (`CSVError`, `CSVFieldCountError`)
+- **Compatibility** - aiocsv compatibility aliases for easy migration
+
+## Requirements
+
+- Python 3.8+ (including Python 3.13 and 3.14)
+- Rust 1.70+ (for building from source)
+
+## Installation
+
+```bash
+pip install rapcsv
+```
+
+For detailed installation instructions, including building from source and development setup, see [Installation Guide](https://github.com/eddiethedean/rapcsv/blob/main/docs/INSTALLATION.md).
+
+## Documentation
+
+Comprehensive documentation is available in the `docs/` directory:
+
+### User Guides
+
+- **[Usage Guide](https://github.com/eddiethedean/rapcsv/blob/main/docs/USAGE_GUIDE.md)** - Comprehensive examples and usage patterns
+- **[API Reference](https://github.com/eddiethedean/rapcsv/blob/main/docs/API_REFERENCE.md)** - Complete API documentation
+- **[Installation Guide](https://github.com/eddiethedean/rapcsv/blob/main/docs/INSTALLATION.md)** - Installation and setup instructions
+
+### Project Documentation
+
+- **[Status](https://github.com/eddiethedean/rapcsv/blob/main/docs/STATUS.md)** - Current development status and feature completion
+- **[Roadmap](https://github.com/eddiethedean/rapcsv/blob/main/docs/ROADMAP.md)** - Detailed development plans and feature roadmap
+- **[Changelog](https://github.com/eddiethedean/rapcsv/blob/main/CHANGELOG.md)** - Version history and changes
+- **[Bugs and Improvements](https://github.com/eddiethedean/rapcsv/blob/main/BUGS_AND_IMPROVEMENTS.md)** - Known issues and limitations tracker
+- **[Testing Guide](https://github.com/eddiethedean/rapcsv/blob/main/docs/README_TESTING.md)** - Local development setup instructions
+- **[Release Checklist](https://github.com/eddiethedean/rapcsv/blob/main/docs/RELEASE_CHECKLIST.md)** - Release process and validation
+- **[Security](https://github.com/eddiethedean/rapcsv/blob/main/SECURITY.md)** - Security policy and vulnerability reporting
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from rapcsv import Reader, Writer
+
+async def main():
+    # Write CSV file
+    async with Writer("output.csv") as writer:
+        await writer.write_row(["name", "age", "city"])
+        await writer.write_row(["Alice", "30", "New York"])
+    
+    # Read CSV file
+    async with Reader("output.csv") as reader:
+        row = await reader.read_row()
+        print(row)  # Output: ['name', 'age', 'city']
+
+asyncio.run(main())
+```
+
+For comprehensive usage examples and patterns, see [Usage Guide](https://github.com/eddiethedean/rapcsv/blob/main/docs/USAGE_GUIDE.md).
+
+## API Reference
+
+For complete API documentation, see [API Reference](https://github.com/eddiethedean/rapcsv/blob/main/docs/API_REFERENCE.md).
+
+**Main Classes:**
+- `Reader` - Async CSV reader
+- `Writer` - Async CSV writer
+- `AsyncDictReader` - Dictionary-based CSV reader
+- `AsyncDictWriter` - Dictionary-based CSV writer
+
+**Exception Types:**
+- `CSVError` - CSV parsing errors
+- `CSVFieldCountError` - Field count mismatches
+
+## Testing
+
+`rapcsv` includes comprehensive test coverage with tests adapted from the [aiocsv test suite](https://github.com/MKuranowski/aiocsv/tree/master/tests) to validate compatibility.
+
+For detailed testing instructions, see [Testing Guide](https://github.com/eddiethedean/rapcsv/blob/main/docs/README_TESTING.md).
+
+## Status
+
+**Current Version**: v0.2.0 - Phase 2 Complete ✅
+
+For detailed status information, feature completion, and known limitations, see [Status](https://github.com/eddiethedean/rapcsv/blob/main/docs/STATUS.md).
+
+## Benchmarks
+
+This package passes the [Fake Async Detector](https://github.com/eddiethedean/rap-bench). Benchmarks are available in the [rap-bench](https://github.com/eddiethedean/rap-bench) repository.
+
+Run the detector yourself:
+
+```bash
+pip install rap-bench
+rap-bench detect rapcsv
+```
+
+## Related Projects
+
+- [rap-manifesto](https://github.com/eddiethedean/rap-manifesto) - Philosophy and guarantees
+- [rap-bench](https://github.com/eddiethedean/rap-bench) - Fake Async Detector CLI
+- [rapfiles](https://github.com/eddiethedean/rapfiles) - True async filesystem I/O
+- [rapsqlite](https://github.com/eddiethedean/rapsqlite) - True async SQLite
+
+For detailed release notes, see [CHANGELOG.md](https://github.com/eddiethedean/rapcsv/blob/main/CHANGELOG.md).
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/eddiethedean/rapcsv).
+
+## License
+
+MIT
+
+

rapcsv-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+rapcsv/__init__.py,sha256=ZaHtTLNRLYpbW5prkcdeRMjYDeMLTlCl5cEOIbG20tI,12705
+rapcsv/_rapcsv.cpython-38-x86_64-linux-gnu.so,sha256=XofNnYKlRiTQBh2QX7YqwlYpDVHGIXu-GuI4GQS9OTM,2284648
+rapcsv/_rapcsv.pyi,sha256=SfV4FqMQMOgWFcgU78Tg5QFsdhuvlMW98vFRbFvo130,14942
+rapcsv/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rapcsv-0.2.0.dist-info/METADATA,sha256=nW0xo5FjlVIE2NEGSo6O0vtFaXhPVaUBC8H20yrIVxc,8660
+rapcsv-0.2.0.dist-info/WHEEL,sha256=3N5EpdPBJMYIW1be1E4XQax3kkFUj46lEw0Ks8eIJi4,107
+rapcsv-0.2.0.dist-info/RECORD,,

rapcsv-0.0.2.dist-info/METADATA

@@ -1,226 +0,0 @@
-Metadata-Version: 2.4
-Name: rapcsv
-Version: 0.0.2
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Summary: Streaming async CSV — no fake async, no GIL stalls.
-Keywords: async,csv,streaming,async-io
-Author: RAP Project
-License: MIT
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-
-# rapcsv
-
-**Streaming async CSV — no fake async, no GIL stalls.**
-
-[![PyPI version](https://img.shields.io/pypi/v/rapcsv.svg)](https://pypi.org/project/rapcsv/)
-[![Downloads](https://pepy.tech/badge/rapcsv)](https://pepy.tech/project/rapcsv)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## Overview
-
-`rapcsv` provides true async CSV reading and writing for Python, backed by Rust and Tokio. Unlike libraries that wrap blocking I/O in `async` syntax, `rapcsv` guarantees that all CSV operations execute **outside the Python GIL**, ensuring event loops never stall under load, even when processing large files.
-
-**Roadmap Goal**: Achieve drop-in replacement compatibility with `aiocsv`, enabling seamless migration with true async performance. See [ROADMAP.md](https://github.com/eddiethedean/rapcsv/blob/main/ROADMAP.md) for details.
-
-## Why `rap*`?
-
-Packages prefixed with **`rap`** stand for **Real Async Python**. Unlike many libraries that merely wrap blocking I/O in `async` syntax, `rap*` packages guarantee that all I/O work is executed **outside the Python GIL** using native runtimes (primarily Rust). This means event loops are never stalled by hidden thread pools, blocking syscalls, or cooperative yielding tricks. If a `rap*` API is `async`, it is *structurally non-blocking by design*, not by convention. The `rap` prefix is a contract: measurable concurrency, real parallelism, and verifiable async behavior under load.
-
-See the [rap-manifesto](https://github.com/eddiethedean/rap-manifesto) for philosophy and guarantees.
-
-## Features
-
-- ✅ **True async** CSV reading and writing
-- ✅ **Streaming support** for large files
-- ✅ **Native Rust-backed** execution (Tokio)
-- ✅ **Zero Python thread pools**
-- ✅ **Event-loop-safe** concurrency under load
-- ✅ **GIL-independent** I/O operations
-- ✅ **Verified** by Fake Async Detector
-
-## Requirements
-
-- Python 3.8+
-- Rust 1.70+ (for building from source)
-
-## Installation
-
-```bash
-pip install rapcsv
-```
-
-### Building from Source
-
-```bash
-git clone https://github.com/eddiethedean/rapcsv.git
-cd rapcsv
-pip install maturin
-maturin develop
-```
-
----
-
-## Usage
-
-```python
-import asyncio
-from rapcsv import Reader, Writer
-
-async def main():
-    # Write CSV file (one row per Writer instance for MVP)
-    writer = Writer("output.csv")
-    await writer.write_row(["name", "age", "city"])
-    
-    # Read CSV file (reads first row)
-    reader = Reader("output.csv")
-    row = await reader.read_row()
-    print(row)  # Output: ['name', 'age', 'city']
-
-asyncio.run(main())
-```
-
-### Writing Multiple Rows
-
-```python
-import asyncio
-from rapcsv import Writer
-
-async def main():
-    # Write multiple rows with a single Writer instance (file handle reused)
-    writer = Writer("output.csv")
-    rows = [
-        ["name", "age", "city"],
-        ["Alice", "30", "New York"],
-        ["Bob", "25", "London"],
-    ]
-    
-    for row in rows:
-        await writer.write_row(row)
-    
-    # Verify file contents
-    with open("output.csv") as f:
-        print(f.read())
-
-asyncio.run(main())
-```
-
-**Note**: The Writer reuses the file handle across multiple `write_row()` calls for efficient writing. The Reader maintains position state across `read_row()` calls.
-
-## API Reference
-
-### `Reader(path: str)`
-
-Create a new async CSV reader.
-
-**Parameters:**
-- `path` (str): Path to the CSV file to read
-
-**Example:**
-```python
-reader = Reader("data.csv")
-```
-
-### `Reader.read_row() -> List[str]`
-
-Read the next row from the CSV file.
-
-**Returns:**
-- `List[str]`: A list of string values for the row, or an empty list if EOF
-
-**Raises:**
-- `IOError`: If the file cannot be read or parsed
-
-**Note**: The Reader maintains position state across `read_row()` calls, reading sequentially through the file.
-
-### `Writer(path: str)`
-
-Create a new async CSV writer.
-
-**Parameters:**
-- `path` (str): Path to the CSV file to write
-
-**Example:**
-```python
-writer = Writer("output.csv")
-```
-
-### `Writer.write_row(row: List[str]) -> None`
-
-Write a row to the CSV file.
-
-**Parameters:**
-- `row` (List[str]): A list of string values to write as a CSV row
-
-**Raises:**
-- `IOError`: If the file cannot be written
-
-**Note**: The Writer reuses the file handle across multiple `write_row()` calls for efficient writing. Proper RFC 4180 compliant CSV escaping and quoting is applied automatically.
-
-## Benchmarks
-
-This package passes the [Fake Async Detector](https://github.com/eddiethedean/rap-bench). Benchmarks are available in the [rap-bench](https://github.com/eddiethedean/rap-bench) repository.
-
-Run the detector yourself:
-
-```bash
-pip install rap-bench
-rap-bench detect rapcsv
-```
-
-## Roadmap
-
-See [ROADMAP.md](https://github.com/eddiethedean/rapcsv/blob/main/ROADMAP.md) for detailed development plans. Key goals include:
-- Drop-in replacement for `aiocsv` (Phase 1)
-- Full streaming support for large files
-- Comprehensive CSV dialect support
-- Zero-copy optimizations
-
-## Related Projects
-
-- [rap-manifesto](https://github.com/eddiethedean/rap-manifesto) - Philosophy and guarantees
-- [rap-bench](https://github.com/eddiethedean/rap-bench) - Fake Async Detector CLI
-- [rapfiles](https://github.com/eddiethedean/rapfiles) - True async filesystem I/O
-- [rapsqlite](https://github.com/eddiethedean/rapsqlite) - True async SQLite
-
-## Limitations (v0.0.2)
-
-**Current limitations:**
-- Reader still reads entire file into memory on each call (streaming improvements planned)
-- No advanced CSV dialect support (delimiters, quote characters, line terminators)
-- No header detection or manipulation
-- Not yet a drop-in replacement for `aiocsv` (goal for Phase 1)
-- Not designed for synchronous use cases
-
-**Recent improvements (v0.0.2):**
-- ✅ Security fixes: Upgraded dependencies (pyo3 0.27, pyo3-async-runtimes 0.27), fixed CSV injection vulnerability
-- ✅ Position tracking: Reader now maintains position state across `read_row()` calls
-- ✅ File handle reuse: Writer reuses file handle across multiple `write_row()` calls
-- ✅ CSV escaping: Implemented RFC 4180 compliant CSV escaping and quoting
-- ✅ Input validation: Added path validation (non-empty, no null bytes)
-- ✅ Improved error handling: Enhanced error messages with file path context
-- ✅ Type stubs: Added `.pyi` type stubs for better IDE support and type checking
-
-**Roadmap**: See [ROADMAP.md](https://github.com/eddiethedean/rapcsv/blob/main/ROADMAP.md) for planned improvements. Our goal is to achieve drop-in replacement compatibility with `aiocsv` while providing true async performance with GIL-independent I/O.
-
-## Contributing
-
-Contributions are welcome! Please see our [contributing guidelines](https://github.com/eddiethedean/rapcsv/blob/main/CONTRIBUTING.md) (coming soon).
-
-## License
-
-MIT
-
-## Changelog
-
-See [CHANGELOG.md](https://github.com/eddiethedean/rapcsv/blob/main/CHANGELOG.md) (coming soon) for version history.
-

rapcsv-0.0.2.dist-info/RECORD

@@ -1,7 +0,0 @@
-rapcsv/__init__.py,sha256=sMhUUCdC2oVTKMic67GXxx2bs2nyKAvy5jp41aXlKEE,454
-rapcsv/_rapcsv.cpython-38-x86_64-linux-gnu.so,sha256=OXkIqEexG4kGesbeMO8o61S-8as-NEGoOY5bglF10ac,1086888
-rapcsv/_rapcsv.pyi,sha256=kHxUy6naJjUfEBGrM6p6FuOLIyTlJ0Fm2W8IlcYQsF0,353
-rapcsv/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rapcsv-0.0.2.dist-info/METADATA,sha256=gc2lMrQADF-WHhZJptugq70WcKhYb0s4U_iqmLhX6lg,7726
-rapcsv-0.0.2.dist-info/WHEEL,sha256=3N5EpdPBJMYIW1be1E4XQax3kkFUj46lEw0Ks8eIJi4,107
-rapcsv-0.0.2.dist-info/RECORD,,