pardox 0.1.0__py3-none-any.whl

pardox/__init__.py

@@ -0,0 +1,7 @@
+# pardox/__init__.py
+
+from .frame import DataFrame
+from .io import read_csv, read_sql, from_arrow, read_prdx
+
+# Y lo exponemos públicamente aquí
+__all__ = ["DataFrame", "read_csv", "read_sql", "from_arrow", "read_prdx", "Series"]

pardox/frame.py

@@ -0,0 +1,439 @@
+import ctypes
+import json
+from .wrapper import lib, c_char_p, c_size_t, c_int32, c_double
+
+class DataFrame:
+    def __init__(self, manager_ptr):
+        """
+        Initializes a PardoX DataFrame.
+        DO NOT call directly. Use:
+        - px.read_csv()   (Native)
+        - px.read_sql()   (Native via Postgres/ODBC)
+        - px.from_arrow() (Universal Bridge)
+        """
+        if not manager_ptr:
+            raise ValueError("Null pointer received when creating DataFrame.")
+        self._ptr = manager_ptr
+
+    def __del__(self):
+        """
+        Destructor: Frees Rust memory when the Python object dies.
+        """
+        if self._ptr and lib:
+            # Check if lib is still available (interpreter shutdown safety)
+            if hasattr(lib, 'pardox_free_manager'):
+                lib.pardox_free_manager(self._ptr)
+            self._ptr = None
+
+    # =========================================================================
+    # VISUALIZATION MAGIC
+    # =========================================================================
+    
+    def __repr__(self):
+        """
+        Esta es la función mágica que Jupyter llama para mostrar el objeto.
+        En lugar de devolver el objeto raw, devolvemos la tabla ASCII.
+        """
+        # Por defecto mostramos 10 filas al imprimir el objeto
+        return self._fetch_ascii_table(10) or "<Empty PardoX DataFrame>"
+
+    def head(self, n=5):
+        """
+        Ahora devuelve un NUEVO DataFrame con las primeras n filas.
+        Al devolver un objeto, Jupyter llamará a su __repr__ y se verá bonito.
+        """
+        return self.iloc[0:n]
+
+    def tail(self, n=5):
+        """
+        Devuelve un NUEVO DataFrame con las últimas n filas.
+        """
+        if not hasattr(lib, 'pardox_tail_manager'):
+            raise NotImplementedError("tail() API not available in Core.")
+        
+        new_ptr = lib.pardox_tail_manager(self._ptr, n)
+        if not new_ptr:
+            raise RuntimeError("Failed to fetch tail.")
+        
+        return DataFrame(new_ptr)
+
+    def show(self, n=10):
+        """
+        Prints the first n rows to the console explicitly.
+        """
+        ascii_table = self._fetch_ascii_table(n)
+        if ascii_table:
+            print(ascii_table)
+        else:
+            print(f"<PardoX DataFrame at {hex(self._ptr or 0)}> (Empty or Error)")
+
+    # =========================================================================
+    # METADATA & INSPECTION
+    # =========================================================================
+
+    @property
+    def shape(self):
+        """
+        Returns a tuple representing the dimensionality of the DataFrame.
+        Format: (rows, columns)
+        """
+        if hasattr(lib, 'pardox_get_row_count'):
+            rows = lib.pardox_get_row_count(self._ptr)
+            cols = len(self.columns) 
+            return (rows, cols)
+        return (0, 0)
+
+    @property
+    def columns(self):
+        """
+        Returns the column labels of the DataFrame.
+        """
+        schema = self._get_schema_metadata()
+        if schema:
+            return [col['name'] for col in schema.get('columns', [])]
+        return []
+
+    @property
+    def dtypes(self):
+        """
+        Returns the data types in the DataFrame.
+        """
+        schema = self._get_schema_metadata()
+        if schema:
+            return {col['name']: col['type'] for col in schema.get('columns', [])}
+        return {}
+
+    # =========================================================================
+    # SELECTION & SLICING (Indexer)
+    # =========================================================================
+
+    def __getitem__(self, key):
+        """
+        Column Selection: df["col"] -> Series
+        Filtering: df[mask_series] -> DataFrame (Filtered)
+        """
+        # Case 1: Column Selection
+        if isinstance(key, str):
+            from .series import Series
+            return Series(self, key)
+        
+        # Case 2: Boolean Filtering (df[df['A'] > 5])
+        if hasattr(key, '_df') and hasattr(key, 'dtype'):
+            
+            if 'Boolean' not in str(key.dtype):
+                raise TypeError(f"Filter key must be a Boolean Series. Got: {key.dtype}")
+            
+            if not hasattr(lib, 'pardox_apply_filter'):
+                raise NotImplementedError("Filter application API missing in Core.")
+            
+            # Ahora sí accedemos al puntero a través del dataframe padre de la serie
+            mask_ptr = key._df._ptr 
+            mask_col = key.name.encode('utf-8')
+            
+            res_ptr = lib.pardox_apply_filter(self._ptr, mask_ptr, mask_col)
+            if not res_ptr:
+                raise RuntimeError("Filter operation returned null pointer.")
+                
+            return DataFrame(res_ptr)
+
+        raise NotImplementedError(f"Selection with type {type(key)} not supported yet.")
+
+    @property
+    def iloc(self):
+        """
+        Purely integer-location based indexing for selection by position.
+        Usage: df.iloc[100:200]
+        """
+        return self._IlocIndexer(self)
+
+    class _IlocIndexer:
+        def __init__(self, df):
+            self._df = df
+
+        def __getitem__(self, key):
+            if isinstance(key, slice):
+                # Resolve slice indices
+                start = key.start if key.start is not None else 0
+                stop = key.stop if key.stop is not None else self._df.shape[0]
+                
+                if start < 0: start = 0 # Simple clamping
+                if stop < start: stop = start
+                
+                length = stop - start
+                
+                # Call Rust Slicing API
+                if hasattr(lib, 'pardox_slice_manager'):
+                    new_ptr = lib.pardox_slice_manager(self._df._ptr, start, length)
+                    if not new_ptr:
+                        raise RuntimeError("Slice operation returned null pointer.")
+                    return DataFrame(new_ptr)
+                else:
+                    raise NotImplementedError("Slicing API missing in Core.")
+            else:
+                raise TypeError("iloc only supports slices (e.g., [0:10]) for now.")
+
+    # =========================================================================
+    # MUTATION & TRANSFORMATION
+    # =========================================================================
+
+    def cast(self, col_name, target_type):
+        """
+        Casts a column to a new type in-place.
+        """
+        if not hasattr(lib, 'pardox_cast_column'):
+            raise NotImplementedError("Cast API missing.")
+
+        res = lib.pardox_cast_column(
+            self._ptr, 
+            col_name.encode('utf-8'), 
+            target_type.encode('utf-8')
+        )
+        
+        if res != 1:
+            raise RuntimeError(f"Failed to cast column '{col_name}' to '{target_type}'. Check compatibility.")
+        
+        return self # Enable method chaining
+
+    def join(self, other, on=None, left_on=None, right_on=None, how="inner"):
+        """
+        Joins with another PardoX DataFrame.
+        """
+        if not isinstance(other, DataFrame):
+            raise TypeError("The object to join must be a pardox.DataFrame")
+
+        l_col = on if on else left_on
+        r_col = on if on else right_on
+
+        if not l_col or not r_col:
+            raise ValueError("You must specify 'on' or ('left_on' and 'right_on')")
+
+        # Call Rust Hash Join
+        result_ptr = lib.pardox_hash_join(
+            self._ptr,
+            other._ptr,
+            l_col.encode('utf-8'),
+            r_col.encode('utf-8')
+        )
+
+        if not result_ptr:
+            raise RuntimeError("Join failed (Rust returned null pointer).")
+
+        return DataFrame(result_ptr)
+
+    # =========================================================================
+    # PERSISTENCE (IO WRITERS)
+    # =========================================================================
+
+    def to_csv(self, path_or_buf):
+        """
+        Exports the DataFrame to a CSV file.
+        
+        Args:
+            path_or_buf (str): The file path where the CSV will be written.
+        
+        Returns:
+            bool: True if successful.
+        """
+        if not isinstance(path_or_buf, str):
+            raise TypeError("PardoX currently only supports writing to file paths (str).")
+
+        if not hasattr(lib, 'pardox_to_csv'):
+            raise NotImplementedError("API 'pardox_to_csv' not found in Core DLL. Re-compile Rust.")
+
+        # Call Rust Core
+        # Rust handles headers, buffering, and parallel iteration.
+        res = lib.pardox_to_csv(self._ptr, path_or_buf.encode('utf-8'))
+
+        if res != 1:
+            error_map = {
+                -1: "Invalid Manager Pointer",
+                -2: "Invalid Path String",
+                -3: "Failed to initialize CSV Writer (Check permissions/path)",
+                -4: "Failed to write Header",
+                -5: "Failed to write Data Block",
+                -6: "Failed to flush buffer to disk"
+            }
+            msg = error_map.get(res, f"Unknown Error Code: {res}")
+            raise RuntimeError(f"CSV Export Failed: {msg}")
+        
+        return True
+
+    def to_prdx(self, path_or_buf):
+        """
+        Exports the DataFrame to the native PardoX binary format (.prdx).
+        This format supports Zero-Copy loading in future sessions.
+        
+        Args:
+            path_or_buf (str): The file path (e.g., 'data.prdx').
+        """
+        if not isinstance(path_or_buf, str):
+            raise TypeError("Path must be a string.")
+
+        if not hasattr(lib, 'pardox_to_prdx'):
+            # Fallback warning if you haven't exposed api_to_prdx in Rust yet
+            raise NotImplementedError("API 'pardox_to_prdx' not available. Check api_writers.rs")
+
+        res = lib.pardox_to_prdx(self._ptr, path_or_buf.encode('utf-8'))
+
+        if res != 1:
+            raise RuntimeError(f"PRDX Export Failed with error code: {res}")
+        
+        return True
+
+    # =========================================================================
+    # INTERNAL HELPERS
+    # =========================================================================
+
+    def _fetch_ascii_table(self, limit):
+        """
+        Internal helper to fetch the ASCII table string from Rust.
+        """
+        if not hasattr(lib, 'pardox_manager_to_ascii'):
+            return self._fetch_json_dump(limit)
+
+        # 1. Call Rust to get the ASCII table string
+        ascii_ptr = lib.pardox_manager_to_ascii(self._ptr, limit)
+        
+        if not ascii_ptr:
+            return None
+
+        try:
+            # 2. Decode the C-String
+            return ctypes.cast(ascii_ptr, c_char_p).value.decode('utf-8')
+        finally:
+            # 3. Free memory
+            if hasattr(lib, 'pardox_free_string'):
+                lib.pardox_free_string(ascii_ptr)
+
+    def _fetch_json_dump(self, limit):
+        """Legacy helper for older DLLs."""
+        if hasattr(lib, 'pardox_manager_to_json'):
+            json_ptr = lib.pardox_manager_to_json(self._ptr, limit)
+            if json_ptr:
+                try:
+                    return ctypes.cast(json_ptr, c_char_p).value.decode('utf-8')
+                finally:
+                    if hasattr(lib, 'pardox_free_string'):
+                        lib.pardox_free_string(json_ptr)
+        return "Inspection API missing."
+
+    def _get_schema_metadata(self):
+        """
+        Internal helper to fetch schema JSON from Rust.
+        """
+        if not hasattr(lib, 'pardox_get_schema_json'):
+            return {}
+
+        json_ptr = lib.pardox_get_schema_json(self._ptr)
+        if not json_ptr:
+            return {}
+
+        try:
+            json_str = ctypes.cast(json_ptr, c_char_p).value.decode('utf-8')
+            return json.loads(json_str)
+        finally:
+            if hasattr(lib, 'pardox_free_string'):
+                lib.pardox_free_string(json_ptr)
+
+    @property
+    def _manager_ptr(self):
+        """Internal access to the pointer."""
+        return self._ptr
+    
+# =========================================================================
+# MUTATION & FEATURE ENGINEERING (New in v0.1.5)
+# =========================================================================
+
+    def __setitem__(self, key, value):
+        """
+        Enables column assignment: df['new_col'] = df['a'] * df['b']
+        """
+        # 1. Check if value is a PardoX Series (Result of arithmetic)
+        # CORRECCIÓN: Cambiamos '_col_name' por 'name' para coincidir con series.py
+        if hasattr(value, '_df') and hasattr(value, 'name'):
+            # It's a Series! We need to fuse it into this DataFrame.
+            
+            # Use the Series' parent DataFrame (which is a 1-column temporary DF)
+            source_mgr_ptr = value._df._ptr
+            col_name = key.encode('utf-8')
+
+            if not hasattr(lib, 'pardox_add_column'):
+                raise NotImplementedError("pardox_add_column API missing in Core.")
+
+            # Call Rust Core to Move the column
+            res = lib.pardox_add_column(self._ptr, source_mgr_ptr, col_name)
+
+            if res != 1:
+                error_map = {
+                    -1: "Invalid Pointers",
+                    -2: "Invalid Column Name String",
+                    -3: "Engine Logic Error (Row mismatch or Duplicate Name)"
+                }
+                msg = error_map.get(res, f"Unknown Error: {res}")
+                raise RuntimeError(f"Failed to assign column '{key}': {msg}")
+            
+            return # Success!
+
+        # 2. Future support for scalar assignment (df['new'] = 0)
+        # elif isinstance(value, (int, float, str)):
+        #     self._assign_scalar(key, value)
+        
+        else:
+            # Tip de Debugging: Imprimimos los atributos disponibles para ver qué pasó
+            available_attrs = dir(value)
+            raise TypeError(f"Assignment only supported for PardoX Series. Got: {type(value)}. Attributes detected: {available_attrs}")
+
+    def fillna(self, value):
+        """
+        Fills Null/NaN values in the ENTIRE DataFrame with the specified scalar.
+        This modifies the DataFrame in-place.
+        """
+        if not isinstance(value, (int, float)):
+             raise TypeError("fillna currently only supports numeric scalars.")
+             
+        if not hasattr(lib, 'pardox_fill_na'):
+            raise NotImplementedError("pardox_fill_na API missing in Core.")
+
+        # Iterate over all numeric columns and apply fillna kernel
+        # This is fast because the heavy lifting is done in Rust per column.
+        current_schema = self.dtypes
+        c_val = c_double(float(value))
+
+        for col_name, dtype in current_schema.items():
+            # Only apply to numeric types (Float/Int)
+            if dtype in ["Float64", "Int64"]:
+                res = lib.pardox_fill_na(
+                    self._ptr, 
+                    col_name.encode('utf-8'), 
+                    c_val
+                )
+                if res != 1:
+                    print(f"Warning: fillna failed for column '{col_name}'")
+        
+        return self # Enable method chaining
+
+    def round(self, decimals=0):
+        """
+        Rounds all numeric columns to the specified number of decimals.
+        This modifies the DataFrame in-place.
+        """
+        if not isinstance(decimals, int):
+            raise TypeError("decimals must be an integer.")
+
+        if not hasattr(lib, 'pardox_round'):
+             raise NotImplementedError("pardox_round API missing in Core.")
+
+        # Iterate over all columns. Rust kernel will safely ignore non-floats.
+        current_columns = self.columns
+        c_decimals = c_int32(decimals)
+
+        for col_name in current_columns:
+            # We call Rust blindly; the Kernel checks types internally for safety
+            lib.pardox_round(
+                self._ptr, 
+                col_name.encode('utf-8'), 
+                c_decimals
+            )
+        
+        return self # Enable method chaining
+    

pardox/io.py

@@ -0,0 +1,193 @@
+import ctypes
+import json
+import os
+from .wrapper import lib, c_char_p
+from .frame import DataFrame
+
+# Default configuration for Rust CSV Reader
+DEFAULT_CSV_CONFIG = {
+    "delimiter": 44,        # Comma (,)
+    "quote_char": 34,       # Double Quote (")
+    "has_header": True,
+    "chunk_size": 16 * 1024 * 1024  # 16MB Chunk
+}
+
+# =============================================================================
+# ARROW C DATA INTERFACE (ABI)
+# =============================================================================
+class ArrowSchema(ctypes.Structure):
+    _fields_ = [
+        ("format", ctypes.c_char_p),
+        ("name", ctypes.c_char_p),
+        ("metadata", ctypes.c_char_p),
+        ("flags", ctypes.c_int64),
+        ("n_children", ctypes.c_int64),
+        ("children", ctypes.POINTER(ctypes.c_void_p)),
+        ("dictionary", ctypes.c_void_p),
+        ("release", ctypes.c_void_p),
+        ("private_data", ctypes.c_void_p),
+    ]
+
+class ArrowArray(ctypes.Structure):
+    _fields_ = [
+        ("length", ctypes.c_int64),
+        ("null_count", ctypes.c_int64),
+        ("offset", ctypes.c_int64),
+        ("n_buffers", ctypes.c_int64),
+        ("n_children", ctypes.c_int64),
+        ("buffers", ctypes.POINTER(ctypes.c_void_p)),
+        ("children", ctypes.POINTER(ctypes.c_void_p)),
+        ("dictionary", ctypes.c_void_p),
+        ("release", ctypes.c_void_p),
+        ("private_data", ctypes.c_void_p),
+    ]
+
+# =============================================================================
+# PUBLIC API (NATIVE INGESTION)
+# =============================================================================
+
+def read_csv(path, schema=None):
+    """
+    Reads a CSV file directly into PardoX using the native Rust engine.
+    
+    Args:
+        path (str): Path to the CSV file.
+        schema (dict, optional): Manual schema definition.
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"File not found: {path}")
+
+    path_bytes = path.encode('utf-8')
+    config_bytes = json.dumps(DEFAULT_CSV_CONFIG).encode('utf-8')
+
+    if schema:
+        cols = [{"name": k, "type": v} for k, v in schema.items()]
+        schema_json_str = json.dumps({"columns": cols})
+    else:
+        schema_json_str = "{}" 
+
+    schema_bytes = schema_json_str.encode('utf-8')
+
+    manager_ptr = lib.pardox_load_manager_csv(path_bytes, schema_bytes, config_bytes)
+
+    if not manager_ptr:
+        raise RuntimeError(f"Failed to load CSV: {path}.")
+
+    return DataFrame(manager_ptr)
+
+
+def read_sql(connection_string, query):
+    """
+    Reads data directly from a SQL database using PardoX's NATIVE Rust drivers.
+    
+    This function bypasses Python completely. The Rust engine connects to the
+    database, executes the query, and fills the memory buffers directly.
+    
+    Args:
+        connection_string (str): URL (e.g., "postgresql://user:pass@localhost:5432/db")
+        query (str): SQL Query (e.g., "SELECT * FROM clients")
+        
+    Returns:
+        pardox.DataFrame: A PardoX DataFrame containing the query results.
+    """
+    # 1. Check if the Core has Native SQL capabilities
+    if not hasattr(lib, 'pardox_scan_sql'):
+        raise NotImplementedError("This PardoX Core build does not support Native SQL.")
+
+    # 2. Encode to C-Strings (UTF-8)
+    conn_bytes = connection_string.encode('utf-8')
+    query_bytes = query.encode('utf-8')
+
+    # 3. Call Rust Core (Native Driver)
+    manager_ptr = lib.pardox_scan_sql(conn_bytes, query_bytes)
+
+    if not manager_ptr:
+        raise RuntimeError("SQL Query failed. Check console/stderr for Rust driver errors.")
+
+    return DataFrame(manager_ptr)
+
+
+def from_arrow(data):
+    """
+    Ingests an Apache Arrow Table or RecordBatch into PardoX using Zero-Copy.
+    
+    Use this for sources not yet supported natively (e.g., Parquet, Snowflake via Arrow).
+    """
+    try:
+        import pyarrow as pa
+    except ImportError as e:
+        raise ImportError("from_arrow requires 'pyarrow' installed.") from e
+
+    try:
+        if isinstance(data, pa.Table):
+            data = data.combine_chunks()
+            if data.num_rows == 0:
+                raise ValueError("Input Arrow Table is empty.")
+            batch = data.to_batches()[0]
+        elif isinstance(data, pa.RecordBatch):
+            batch = data
+        else:
+            raise TypeError("Input must be a pyarrow.Table or pyarrow.RecordBatch.")
+
+        if batch.num_rows == 0:
+             raise ValueError("Input Arrow Batch is empty.")
+
+        c_schema = ArrowSchema()
+        c_array = ArrowArray()
+
+        batch._export_to_c(
+            ctypes.addressof(c_array), 
+            ctypes.addressof(c_schema)
+        )
+
+        mgr_ptr = lib.pardox_ingest_arrow_stream(
+            ctypes.byref(c_array), 
+            ctypes.byref(c_schema)
+        )
+
+        if not mgr_ptr:
+            raise RuntimeError("PardoX Core returned NULL pointer (Ingestion Failed).")
+            
+        return DataFrame(mgr_ptr)
+
+    except Exception as e:
+         raise RuntimeError(f"PardoX Arrow Ingestion Failed: {e}")
+
+
+def read_prdx(path, limit=100):
+    """
+    Reads a native PardoX (.prdx) file.
+    
+    NOTE: Currently in V0.1 Beta Showcase Mode.
+    This uses the Native Reader to inspect the file structure and data integrity.
+    It returns a list of dictionaries (JSON equivalent) for preview purposes.
+    
+    Args:
+        path (str): Path to the .prdx file.
+        limit (int): Number of rows to inspect (Head).
+        
+    Returns:
+        list: A list of dicts containing the data rows.
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"File not found: {path}")
+        
+    path_bytes = path.encode('utf-8')
+    
+    if not hasattr(lib, 'pardox_read_head_json'):
+        raise NotImplementedError("API 'pardox_read_head_json' not found in Core.")
+        
+    # Call Rust Native Reader
+    json_ptr = lib.pardox_read_head_json(path_bytes, limit)
+    
+    if not json_ptr:
+        raise RuntimeError("Failed to read PRDX file (Rust returned NULL).")
+        
+    try:
+        # Decode Pointer -> String
+        json_str = ctypes.cast(json_ptr, c_char_p).value.decode('utf-8')
+        return json.loads(json_str)
+    finally:
+        # Free Rust Memory
+        if hasattr(lib, 'pardox_free_string'):
+            lib.pardox_free_string(json_ptr)