numpy2 1.0.0__py3-none-any.whl

numpy2/__init__.py

@@ -0,0 +1,67 @@
+"""
+numpy2 - Advanced NumPy for Web Applications
+============================================
+
+A powerful library that bridges NumPy and web frameworks, solving critical pain points:
+- JSON serialization of NumPy types (int64, float64, etc.)
+- Automatic type conversion for web APIs
+- FastAPI/Flask/Django integration
+- Zero-configuration setup
+- Production-ready performance
+
+Build by: Mahesh Makvana
+GitHub: https://github.com/maheshmakvana/numpy2
+
+Example:
+    >>> import numpy2 as np2
+    >>> arr = np2.array([1, 2, 3])
+    >>> json_safe = np2.to_json(arr)
+    >>> fastapi_response = np2.serialize(arr)  # Ready for FastAPI JSONResponse
+"""
+
+__version__ = "1.0.0"
+__author__ = "Mahesh Makvana"
+__email__ = "mahesh@example.com"
+__license__ = "MIT"
+
+from .core import (
+    array,
+    ndarray,
+    to_json,
+    from_json,
+    serialize,
+    deserialize,
+    JSONEncoder,
+    JSONDecoder,
+)
+
+from .converters import (
+    numpy_to_python,
+    pandas_to_json,
+    python_to_numpy,
+)
+
+from .integrations import (
+    FastAPIResponse,
+    FlaskResponse,
+    DjangoResponse,
+    setup_json_encoder,
+)
+
+__all__ = [
+    "array",
+    "ndarray",
+    "to_json",
+    "from_json",
+    "serialize",
+    "deserialize",
+    "JSONEncoder",
+    "JSONDecoder",
+    "numpy_to_python",
+    "pandas_to_json",
+    "python_to_numpy",
+    "FastAPIResponse",
+    "FlaskResponse",
+    "DjangoResponse",
+    "setup_json_encoder",
+]

numpy2/converters.py

@@ -0,0 +1,265 @@
+"""
+numpy2.converters - Data type conversion utilities
+
+Handles conversions between NumPy, pandas, Python types, and JSON
+with automatic type inference and data integrity preservation.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Any, Dict, List, Union, Optional
+
+
+def numpy_to_python(obj: Any) -> Any:
+    """
+    Convert NumPy types to native Python types.
+
+    SOLVES: Silent data loss from NumPy type conversions
+
+    Args:
+        obj: NumPy object to convert
+
+    Returns:
+        Native Python type
+
+    Example:
+        >>> import numpy as np
+        >>> import numpy2 as np2
+        >>> val = np.int64(42)
+        >>> result = np2.numpy_to_python(val)
+        >>> type(result)
+        <class 'int'>
+    """
+
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    elif isinstance(obj, np.integer):
+        return int(obj)
+    elif isinstance(obj, np.floating):
+        if np.isnan(obj) or np.isinf(obj):
+            return None
+        return float(obj)
+    elif isinstance(obj, np.bool_):
+        return bool(obj)
+    elif isinstance(obj, np.datetime64):
+        return str(obj)
+    elif isinstance(obj, np.generic):
+        return obj.item()
+    elif isinstance(obj, (list, tuple)):
+        return type(obj)(numpy_to_python(item) for item in obj)
+    elif isinstance(obj, dict):
+        return {k: numpy_to_python(v) for k, v in obj.items()}
+    else:
+        return obj
+
+
+def pandas_to_json(
+    df: pd.DataFrame,
+    orient: str = 'records',
+    include_index: bool = False
+) -> Dict[str, Any]:
+    """
+    Convert pandas DataFrame to JSON-safe dictionary.
+
+    SOLVES: JSON serialization of DataFrames with NumPy columns
+
+    Args:
+        df: pandas DataFrame
+        orient: DataFrame orientation ('records', 'list', 'dict', 'split', 'tight', 'index', 'columns', 'values')
+        include_index: Include index in output
+
+    Returns:
+        JSON-safe dictionary
+
+    Example:
+        >>> import pandas as pd
+        >>> import numpy2 as np2
+        >>> df = pd.DataFrame({'A': [1, 2], 'B': [3.5, 4.5]})
+        >>> result = np2.pandas_to_json(df)
+        >>> type(result)
+        <class 'dict'>
+    """
+
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError(f"Expected pandas DataFrame, got {type(df)}")
+
+    # Convert all NumPy types to Python types
+    df_converted = df.copy()
+
+    for col in df_converted.columns:
+        if df_converted[col].dtype == 'object':
+            continue
+        if hasattr(df_converted[col].dtype, 'name'):
+            if 'int' in str(df_converted[col].dtype) or 'float' in str(df_converted[col].dtype):
+                df_converted[col] = df_converted[col].astype(str).apply(
+                    lambda x: int(x) if '.' not in x else float(x)
+                )
+
+    result = df_converted.to_dict(orient=orient)
+
+    if include_index and orient == 'records':
+        result = [
+            {**row, '__index__': idx}
+            for idx, row in enumerate(result)
+        ]
+
+    return result
+
+
+def python_to_numpy(
+    data: Any,
+    dtype: Optional[str] = None
+) -> np.ndarray:
+    """
+    Convert Python types to NumPy array.
+
+    Args:
+        data: Python data (list, tuple, dict, etc.)
+        dtype: Target NumPy dtype
+
+    Returns:
+        NumPy ndarray
+
+    Example:
+        >>> import numpy2 as np2
+        >>> data = [1, 2, 3]
+        >>> arr = np2.python_to_numpy(data, dtype='float32')
+        >>> arr.dtype
+        dtype('float32')
+    """
+
+    return np.array(data, dtype=dtype)
+
+
+def infer_dtype(data: Any) -> str:
+    """
+    Intelligently infer appropriate NumPy dtype from data.
+
+    SOLVES: Type inference problems in web APIs
+
+    Args:
+        data: Data to analyze
+
+    Returns:
+        Inferred NumPy dtype string
+
+    Example:
+        >>> import numpy2 as np2
+        >>> dtype = np2.infer_dtype([1, 2, 3])
+        >>> dtype
+        'int64'
+    """
+
+    if isinstance(data, (list, tuple)):
+        if not data:
+            return 'float64'
+
+        # Check first element type
+        first = data[0]
+
+        if isinstance(first, bool):
+            return 'bool'
+        elif isinstance(first, int):
+            # Check range to choose appropriate int type
+            values = [x for x in data if isinstance(x, int)]
+            if all(-128 <= v < 128 for v in values):
+                return 'int8'
+            elif all(-32768 <= v < 32768 for v in values):
+                return 'int16'
+            elif all(-2147483648 <= v < 2147483648 for v in values):
+                return 'int32'
+            else:
+                return 'int64'
+        elif isinstance(first, float):
+            return 'float64'
+        elif isinstance(first, str):
+            return 'object'
+        elif isinstance(first, (list, tuple)):
+            return infer_dtype(first)
+
+    elif isinstance(data, dict):
+        return 'object'
+
+    elif isinstance(data, np.ndarray):
+        return str(data.dtype)
+
+    return 'object'
+
+
+def safe_cast(
+    value: Any,
+    target_dtype: str,
+    raise_on_error: bool = False
+) -> Any:
+    """
+    Safely cast value to target dtype with error handling.
+
+    SOLVES: Type conversion errors breaking web APIs
+
+    Args:
+        value: Value to cast
+        target_dtype: Target NumPy dtype
+        raise_on_error: Raise exception on failure (default: return original)
+
+    Returns:
+        Casted value or original value on failure
+
+    Example:
+        >>> import numpy2 as np2
+        >>> result = np2.safe_cast("123", 'int32')
+        >>> result
+        123
+    """
+
+    try:
+        if target_dtype in ['int8', 'int16', 'int32', 'int64']:
+            return int(value)
+        elif target_dtype in ['float16', 'float32', 'float64']:
+            return float(value)
+        elif target_dtype == 'bool':
+            return bool(value)
+        else:
+            return np.array([value], dtype=target_dtype)[0]
+    except (ValueError, TypeError) as e:
+        if raise_on_error:
+            raise
+        return value
+
+
+def batch_convert(
+    data: List[Dict[str, Any]],
+    dtype_map: Optional[Dict[str, str]] = None
+) -> List[Dict[str, Any]]:
+    """
+    Convert batch of records with consistent type handling.
+
+    SOLVES: Bulk data conversion issues in APIs
+
+    Args:
+        data: List of dictionaries to convert
+        dtype_map: Mapping of field names to target dtypes
+
+    Returns:
+        Converted data
+
+    Example:
+        >>> import numpy2 as np2
+        >>> data = [{'id': 1, 'value': 3.14}]
+        >>> converted = np2.batch_convert(data, {'id': 'int32', 'value': 'float32'})
+    """
+
+    if dtype_map is None:
+        dtype_map = {}
+
+    converted = []
+    for record in data:
+        new_record = {}
+        for key, value in record.items():
+            target_dtype = dtype_map.get(key)
+            if target_dtype:
+                new_record[key] = safe_cast(value, target_dtype)
+            else:
+                new_record[key] = numpy_to_python(value)
+        converted.append(new_record)
+
+    return converted

numpy2/core.py

@@ -0,0 +1,360 @@
+"""
+numpy2.core - Core serialization and type conversion utilities
+
+Solves NumPy JSON serialization issues:
+- TypeError: Object of type int64 is not JSON serializable
+- Silent data loss from NumPy type conversions
+- Performance degradation in web APIs
+- Framework incompatibility with NumPy dtypes
+"""
+
+import json
+import numpy as np
+import pandas as pd
+from typing import Any, Dict, List, Union, Optional
+from decimal import Decimal
+
+
+class JSONEncoder(json.JSONEncoder):
+    """
+    Custom JSON encoder that handles NumPy and pandas data types.
+
+    SOLVES: TypeError: Object of type int64 is not JSON serializable
+
+    Features:
+    - Automatic NumPy dtype conversion
+    - pandas Series/DataFrame support
+    - Preserves data integrity
+    - Zero configuration
+
+    Example:
+        >>> import json
+        >>> import numpy as np
+        >>> arr = np.array([1, 2, 3], dtype=np.int64)
+        >>> json.dumps(arr, cls=JSONEncoder)
+        '[1, 2, 3]'
+    """
+
+    def default(self, obj: Any) -> Any:
+        """Convert non-standard types to JSON-serializable format."""
+
+        # NumPy integer types
+        if isinstance(obj, np.integer):
+            return int(obj)
+
+        # NumPy float types
+        elif isinstance(obj, np.floating):
+            # Handle special float values
+            if np.isnan(obj):
+                return None  # or "NaN" if preferred
+            elif np.isinf(obj):
+                return None  # or "Infinity" if preferred
+            return float(obj)
+
+        # NumPy arrays
+        elif isinstance(obj, np.ndarray):
+            return obj.tolist()
+
+        # NumPy scalar types
+        elif isinstance(obj, np.generic):
+            return obj.item()
+
+        # pandas Series
+        elif isinstance(obj, pd.Series):
+            return obj.to_dict()
+
+        # pandas DataFrame
+        elif isinstance(obj, pd.DataFrame):
+            return obj.to_dict(orient='records')
+
+        # pandas Index
+        elif isinstance(obj, pd.Index):
+            return obj.tolist()
+
+        # Decimal support
+        elif isinstance(obj, Decimal):
+            return float(obj)
+
+        # datetime64
+        elif isinstance(obj, np.datetime64):
+            return str(obj)
+
+        # timedelta64
+        elif isinstance(obj, np.timedelta64):
+            return str(obj)
+
+        # complex numbers
+        elif isinstance(obj, (complex, np.complexfloating)):
+            return {"real": obj.real, "imag": obj.imag}
+
+        # Default fallback
+        return super().default(obj)
+
+
+class JSONDecoder(json.JSONDecoder):
+    """
+    Custom JSON decoder that reconstructs NumPy arrays from JSON.
+
+    SOLVES: Data type loss when converting JSON back to NumPy
+
+    Features:
+    - Intelligent type inference
+    - Preserves numeric precision
+    - Optional NumPy array reconstruction
+
+    Example:
+        >>> import json
+        >>> data = '[1, 2, 3]'
+        >>> decoder = JSONDecoder()
+        >>> decoder.decode(data)
+        [1, 2, 3]
+    """
+
+    def __init__(self, to_numpy: bool = False, dtype: Optional[str] = None, *args, **kwargs):
+        """
+        Initialize decoder.
+
+        Args:
+            to_numpy: If True, convert lists to numpy arrays
+            dtype: NumPy dtype to use for arrays (e.g., 'int64', 'float32')
+        """
+        self.to_numpy = to_numpy
+        self.dtype = dtype
+        super().__init__(object_hook=self.object_hook, *args, **kwargs)
+
+    def object_hook(self, obj: Dict) -> Any:
+        """Convert objects back to appropriate types."""
+        if self.to_numpy and isinstance(obj, dict) and "real" in obj and "imag" in obj:
+            return complex(obj["real"], obj["imag"])
+        return obj
+
+
+def to_json(obj: Any, indent: Optional[int] = None, **kwargs) -> str:
+    """
+    Convert NumPy arrays and pandas objects to JSON string.
+
+    SOLVES: TypeError: Object of type int64 is not JSON serializable
+
+    Args:
+        obj: NumPy array, pandas object, or standard Python object
+        indent: JSON indentation level
+        **kwargs: Additional arguments for json.dumps
+
+    Returns:
+        JSON string representation
+
+    Example:
+        >>> import numpy as np
+        >>> import numpy2 as np2
+        >>> arr = np.array([1, 2, 3], dtype=np.int64)
+        >>> json_str = np2.to_json(arr)
+        >>> print(json_str)
+        [1, 2, 3]
+    """
+    return json.dumps(obj, cls=JSONEncoder, indent=indent, **kwargs)
+
+
+def from_json(
+    json_str: str,
+    to_numpy: bool = False,
+    dtype: Optional[str] = None
+) -> Any:
+    """
+    Deserialize JSON string to Python objects (optionally NumPy arrays).
+
+    Args:
+        json_str: JSON string to deserialize
+        to_numpy: Convert to numpy arrays
+        dtype: Target numpy dtype
+
+    Returns:
+        Deserialized Python object or NumPy array
+
+    Example:
+        >>> import numpy2 as np2
+        >>> json_str = '[1, 2, 3]'
+        >>> arr = np2.from_json(json_str, to_numpy=True, dtype='int64')
+        >>> type(arr)
+        <class 'numpy.ndarray'>
+    """
+    decoder = JSONDecoder(to_numpy=to_numpy, dtype=dtype)
+    result = decoder.decode(json_str)
+
+    if to_numpy and isinstance(result, list):
+        result = np.array(result, dtype=dtype)
+
+    return result
+
+
+def serialize(obj: Any, include_metadata: bool = False) -> Dict[str, Any]:
+    """
+    Serialize NumPy/pandas objects to JSON-safe dictionary.
+
+    SOLVES: Web framework incompatibility with NumPy dtypes
+
+    Perfect for FastAPI JSONResponse, Flask jsonify, Django JsonResponse
+
+    Args:
+        obj: Object to serialize
+        include_metadata: Include shape, dtype, and other metadata
+
+    Returns:
+        JSON-safe dictionary
+
+    Example:
+        >>> import numpy as np
+        >>> import numpy2 as np2
+        >>> arr = np.array([[1, 2], [3, 4]], dtype=np.int32)
+        >>> result = np2.serialize(arr, include_metadata=True)
+        >>> result
+        {
+            'data': [[1, 2], [3, 4]],
+            'shape': [2, 2],
+            'dtype': 'int32',
+            'size': 4
+        }
+    """
+
+    if isinstance(obj, np.ndarray):
+        result = {
+            'data': obj.tolist(),
+        }
+        if include_metadata:
+            result.update({
+                'shape': list(obj.shape),
+                'dtype': str(obj.dtype),
+                'size': int(obj.size),
+                'ndim': int(obj.ndim),
+            })
+        return result
+
+    elif isinstance(obj, pd.DataFrame):
+        result = {
+            'data': obj.to_dict(orient='records'),
+        }
+        if include_metadata:
+            result.update({
+                'shape': list(obj.shape),
+                'columns': list(obj.columns),
+                'index': obj.index.tolist(),
+            })
+        return result
+
+    elif isinstance(obj, pd.Series):
+        result = {
+            'data': obj.to_dict(),
+        }
+        if include_metadata:
+            result.update({
+                'name': obj.name,
+                'dtype': str(obj.dtype),
+                'index': obj.index.tolist(),
+            })
+        return result
+
+    elif isinstance(obj, dict):
+        # Recursively serialize nested structures
+        return {k: serialize(v, include_metadata) if isinstance(v, (np.ndarray, pd.DataFrame, pd.Series)) else v
+                for k, v in obj.items()}
+
+    elif isinstance(obj, (list, tuple)):
+        return [serialize(item, include_metadata) if isinstance(item, (np.ndarray, pd.DataFrame, pd.Series)) else item
+                for item in obj]
+
+    else:
+        return json.loads(json.dumps(obj, cls=JSONEncoder))
+
+
+def deserialize(
+    data: Dict[str, Any],
+    to_numpy: bool = True,
+    dtype: Optional[str] = None
+) -> Union[np.ndarray, pd.DataFrame, Any]:
+    """
+    Deserialize JSON-safe dictionary back to NumPy/pandas objects.
+
+    Args:
+        data: Dictionary with 'data' key and optional metadata
+        to_numpy: Convert to NumPy array (if False, returns list)
+        dtype: Target dtype for conversion
+
+    Returns:
+        NumPy array, pandas DataFrame, or raw data
+
+    Example:
+        >>> import numpy2 as np2
+        >>> serialized = {
+        ...     'data': [[1, 2], [3, 4]],
+        ...     'shape': [2, 2],
+        ...     'dtype': 'int32'
+        ... }
+        >>> arr = np2.deserialize(serialized)
+        >>> type(arr)
+        <class 'numpy.ndarray'>
+    """
+
+    if not isinstance(data, dict):
+        return data
+
+    if 'data' not in data:
+        return data
+
+    array_data = data['data']
+
+    if to_numpy:
+        target_dtype = dtype or data.get('dtype', None)
+        return np.array(array_data, dtype=target_dtype)
+
+    return array_data
+
+
+def array(
+    data: Any,
+    dtype: Optional[str] = None,
+    **kwargs
+) -> np.ndarray:
+    """
+    Create NumPy array with automatic type handling.
+
+    Wrapper around numpy.array with better type inference for web data.
+
+    Args:
+        data: Array data
+        dtype: Data type
+        **kwargs: Additional arguments for numpy.array
+
+    Returns:
+        NumPy ndarray
+    """
+    return np.array(data, dtype=dtype, **kwargs)
+
+
+class ndarray:
+    """
+    Enhanced NumPy ndarray wrapper with web-friendly methods.
+
+    Adds convenience methods for serialization without modifying
+    the original NumPy array.
+    """
+
+    def __init__(self, data: Any, dtype: Optional[str] = None):
+        self._array = np.array(data, dtype=dtype)
+
+    def to_json(self, indent: Optional[int] = None) -> str:
+        """Convert to JSON string."""
+        return to_json(self._array, indent=indent)
+
+    def to_dict(self, include_metadata: bool = False) -> Dict:
+        """Convert to JSON-safe dictionary."""
+        return serialize(self._array, include_metadata=include_metadata)
+
+    @property
+    def numpy(self) -> np.ndarray:
+        """Get underlying NumPy array."""
+        return self._array
+
+    def __repr__(self) -> str:
+        return f"numpy2.ndarray({self._array})"
+
+    def __str__(self) -> str:
+        return str(self._array)