api-response-cleaner 0.1.0__py3-none-any.whl

api_response_cleaner/__init__.py

@@ -0,0 +1,8 @@
+from .cleaner import Cleaner, CleanResult
+from .schema import Schema, Field
+from .errors import ErrorCode, FieldError, SchemaError, CleaningError
+
+__version__ = "0.1.0"
+
+def clean(data: dict, schema: Schema, aliases: dict = None, extra: str = "ignore") -> CleanResult:
+    return Cleaner(schema, aliases, extra).clean(data)

api_response_cleaner/cleaner.py

@@ -0,0 +1,199 @@
+import json
+import copy
+from typing import Any, Dict, List, Optional, Tuple
+from .errors import ErrorCode, FieldError, CleaningError, SchemaError
+from .schema import Schema, Field
+from .normalizer import normalize
+from .validator import validate_constraints
+
+class CleanResult:
+    def __init__(self, data: dict, errors: List[FieldError]):
+        self.data = data
+        self.errors = errors
+        self.ok = len(self.errors) == 0
+
+    def raise_for_errors(self):
+        if not self.ok:
+            raise CleaningError(self.errors)
+
+class Cleaner:
+    def __init__(self, schema: Schema, aliases: Optional[Dict[str, List[str]]] = None, extra: str = "ignore"):
+        self.extra = extra
+        self.fields = {}
+        self.aliases_map = aliases or {}
+        
+        self._all_known_names = set()
+        
+        for k, v in schema.items():
+            field = Field(k, v)
+            if k in self.aliases_map:
+                field.aliases = self.aliases_map[k] + field.aliases
+            self.fields[k] = field
+            self._all_known_names.add(k)
+            
+        alias_to_canon = {}
+        for k, f in self.fields.items():
+            for a in f.aliases:
+                if a in self._all_known_names:
+                    raise SchemaError(f"Alias {a} for field {k} collides with field name")
+                if a in alias_to_canon:
+                    raise SchemaError(f"Alias {a} is duplicated across fields")
+                alias_to_canon[a] = k
+                self._all_known_names.add(a)
+
+        for k in self.aliases_map:
+            if k not in self.fields:
+                raise SchemaError(f"aliases entry names unknown field: {k}")
+
+    def clean(self, data: Any) -> CleanResult:
+        if isinstance(data, (str, bytes)):
+            try:
+                data = json.loads(data)
+            except Exception:
+                return CleanResult({}, [FieldError("", ErrorCode.invalid_input, "Invalid JSON")])
+                
+        if not isinstance(data, dict):
+            return CleanResult({}, [FieldError("", ErrorCode.invalid_input, "Top-level input must be an object")])
+
+        errors = []
+        result_data, _ = self._clean_object(data, self.fields, "", self.extra, errors)
+        
+        return CleanResult(result_data, errors)
+
+    def _clean_object(self, input_obj: dict, fields: Dict[str, Field], 
+                      path_prefix: str, extra: str, errors: List[FieldError]) -> Tuple[dict, bool]:
+        out = {}
+        has_error = False
+        consumed_keys = set()
+        
+        for name, field in fields.items():
+            path = f"{path_prefix}.{name}" if path_prefix else name
+            
+            val = None
+            is_present = False
+            is_null = False
+            
+            candidates = [name] + field.aliases
+            for cand in candidates:
+                if cand in input_obj:
+                    consumed_keys.add(cand)
+                    if input_obj[cand] is not None:
+                        val = input_obj[cand]
+                        is_present = True
+                        break
+                    else:
+                        is_present = True
+                        is_null = True
+                        
+            if not is_present:
+                if field.required:
+                    errors.append(FieldError(path, ErrorCode.missing_required, "Missing required field"))
+                    has_error = True
+                elif field.has_default:
+                    out[name] = copy.deepcopy(field.default)
+                continue
+
+            if val is None and is_null:
+                if not field.nullable:
+                    errors.append(FieldError(path, ErrorCode.null_not_allowed, "Null not allowed"))
+                    has_error = True
+                else:
+                    out[name] = None
+                continue
+
+            norm_val, err_code = normalize(val, field.type_str, field.strip)
+            if err_code:
+                errors.append(FieldError(path, err_code, "Conversion failed"))
+                has_error = True
+                continue
+
+            # Nested schema
+            if field.schema is not None:
+                inner_fields = {}
+                for ik, iv in field.schema.items():
+                    inner_fields[ik] = Field(ik, iv)
+                
+                inner_known = set(inner_fields.keys())
+                for ik, inner_f in inner_fields.items():
+                    for a in inner_f.aliases:
+                        if a in inner_known:
+                            raise SchemaError(f"Alias {a} for field {ik} collides")
+                        inner_known.add(a)
+
+                inner_out, inner_has_err = self._clean_object(norm_val, inner_fields, path, extra, errors)
+                if inner_has_err:
+                    has_error = True
+                else:
+                    out[name] = inner_out
+                continue
+                
+            # List
+            if field.type_str == "list" and field.items is not None:
+                item_field = Field("item", field.items, is_items=True)
+                list_out = []
+                list_has_err = False
+                
+                for i, item_val in enumerate(norm_val):
+                    item_path = f"{path}[{i}]"
+                    
+                    if item_val is None:
+                        if not item_field.nullable:
+                            errors.append(FieldError(item_path, ErrorCode.null_not_allowed, "Null not allowed in list"))
+                            list_has_err = True
+                        else:
+                            list_out.append(None)
+                        continue
+                        
+                    item_norm, item_err = normalize(item_val, item_field.type_str, item_field.strip)
+                    if item_err:
+                        errors.append(FieldError(item_path, item_err, "List item conversion failed"))
+                        list_has_err = True
+                        continue
+                        
+                    if item_field.schema is not None:
+                        inner_fields = {ik: Field(ik, iv) for ik, iv in item_field.schema.items()}
+                        inner_out, inner_err = self._clean_object(item_norm, inner_fields, item_path, extra, errors)
+                        if inner_err:
+                            list_has_err = True
+                        else:
+                            list_out.append(inner_out)
+                    else:
+                        item_errs = validate_constraints(
+                            item_norm, item_field.type_str, item_field.min, item_field.max,
+                            item_field.min_length, item_field.max_length, item_field.choices
+                        )
+                        if item_errs:
+                            for c_err, c_msg in item_errs:
+                                errors.append(FieldError(item_path, c_err, c_msg))
+                            list_has_err = True
+                        else:
+                            list_out.append(item_norm)
+                            
+                if list_has_err:
+                    has_error = True
+                    continue
+                else:
+                    norm_val = list_out
+
+            errs = validate_constraints(
+                norm_val, field.type_str, field.min, field.max,
+                field.min_length, field.max_length, field.choices
+            )
+            if errs:
+                for c_err, c_msg in errs:
+                    errors.append(FieldError(path, c_err, c_msg))
+                has_error = True
+            else:
+                out[name] = norm_val
+                
+        # Handle extra fields
+        for k, v in input_obj.items():
+            if k not in consumed_keys:
+                if extra == "error":
+                    epath = f"{path_prefix}.{k}" if path_prefix else k
+                    errors.append(FieldError(epath, ErrorCode.unexpected_field, "Unexpected field"))
+                    has_error = True
+                elif extra == "keep":
+                    out[k] = copy.deepcopy(v)
+
+        return out, has_error

api_response_cleaner/errors.py

@@ -0,0 +1,39 @@
+from enum import Enum
+
+class ErrorCode(str, Enum):
+    missing_required = "missing_required"
+    null_not_allowed = "null_not_allowed"
+    conversion_failed = "conversion_failed"
+    not_in_choices = "not_in_choices"
+    too_small = "too_small"
+    too_large = "too_large"
+    too_short = "too_short"
+    too_long = "too_long"
+    unexpected_field = "unexpected_field"
+    invalid_input = "invalid_input"
+
+class FieldError:
+    def __init__(self, field: str, code: ErrorCode, message: str):
+        self.field = field
+        self.code = code
+        self.message = message
+
+    def to_dict(self) -> dict:
+        return {
+            "field": self.field,
+            "code": self.code.value,
+            "message": self.message
+        }
+
+    def __repr__(self) -> str:
+        return f"FieldError({self.field!r}, {self.code!r}, {self.message!r})"
+
+class SchemaError(Exception):
+    """Raised at schema build time for invalid schema definitions."""
+    pass
+
+class CleaningError(Exception):
+    """Raised when raise_for_errors() is called and errors exist."""
+    def __init__(self, errors: list[FieldError]):
+        self.errors = errors
+        super().__init__("Cleaning failed")

api_response_cleaner/normalizer.py

@@ -0,0 +1,80 @@
+import math
+from typing import Any, Tuple, Optional
+from .errors import ErrorCode
+
+def normalize(value: Any, type_str: str, strip: bool = True) -> Tuple[Any, Optional[ErrorCode]]:
+    if type_str == "object":
+        return value, None
+
+    if type_str == "str":
+        if isinstance(value, str):
+            return value.strip() if strip else value, None
+        if isinstance(value, (int, float)):
+            if isinstance(value, bool):
+                return None, ErrorCode.conversion_failed
+            if isinstance(value, float) and not math.isfinite(value):
+                return None, ErrorCode.conversion_failed
+            val = str(value)
+            return val.strip() if strip else val, None
+        return None, ErrorCode.conversion_failed
+
+    if type_str == "int":
+        if isinstance(value, bool):
+            return None, ErrorCode.conversion_failed
+        if isinstance(value, int):
+            return value, None
+        if isinstance(value, float):
+            if math.isfinite(value) and value.is_integer():
+                return int(value), None
+            return None, ErrorCode.conversion_failed
+        if isinstance(value, str):
+            try:
+                f_val = float(value)
+                if math.isfinite(f_val) and f_val.is_integer():
+                    return int(f_val), None
+            except ValueError:
+                pass
+        return None, ErrorCode.conversion_failed
+
+    if type_str == "float":
+        if isinstance(value, bool):
+            return None, ErrorCode.conversion_failed
+        if isinstance(value, (int, float)):
+            if not math.isfinite(value):
+                return None, ErrorCode.conversion_failed
+            return float(value), None
+        if isinstance(value, str):
+            try:
+                f_val = float(value)
+                if not math.isfinite(f_val):
+                    return None, ErrorCode.conversion_failed
+                return f_val, None
+            except ValueError:
+                pass
+        return None, ErrorCode.conversion_failed
+
+    if type_str == "bool":
+        if isinstance(value, bool):
+            return value, None
+        if isinstance(value, int) and not isinstance(value, bool):
+            if value in (0, 1):
+                return bool(value), None
+        if isinstance(value, str):
+            v_lower = value.strip().lower()
+            if v_lower in ("true", "yes", "y", "on", "1"):
+                return True, None
+            if v_lower in ("false", "no", "n", "off", "0"):
+                return False, None
+        return None, ErrorCode.conversion_failed
+
+    if type_str == "list":
+        if isinstance(value, (list, tuple)):
+            return list(value), None
+        return None, ErrorCode.conversion_failed
+
+    if type_str == "dict":
+        if isinstance(value, dict):
+            return value, None
+        return None, ErrorCode.conversion_failed
+
+    return None, ErrorCode.conversion_failed

api_response_cleaner/py.typed

@@ -0,0 +1 @@
+ 

api_response_cleaner/schema.py

@@ -0,0 +1,149 @@
+import math
+from typing import Any, Dict, List, Optional, Union
+from .errors import SchemaError
+from .normalizer import normalize
+from .validator import validate_constraints
+
+ALLOWED_KEYS = {
+    "type", "required", "default", "nullable", "aliases", "strip",
+    "choices", "min", "max", "min_length", "max_length", "schema", "items"
+}
+
+TYPE_MAP = {
+    str: "str", int: "int", float: "float", bool: "bool",
+    list: "list", dict: "dict", object: "object"
+}
+
+class Field:
+    def __init__(self, name: str, spec: Any, is_items: bool = False):
+        self.name = name
+        
+        if isinstance(spec, type) and spec in TYPE_MAP:
+            spec = {"type": spec}
+        elif not isinstance(spec, dict):
+            raise SchemaError(f"Field {name} spec must be a dict or a supported type")
+
+        for k in spec:
+            if k not in ALLOWED_KEYS:
+                raise SchemaError(f"Unknown spec key {k} in field {name}")
+
+        type_val = spec.get("type", dict if "schema" in spec else None)
+        if type_val not in TYPE_MAP and type_val not in TYPE_MAP.values():
+            raise SchemaError(f"Unsupported type {type_val} in field {name}")
+
+        self.type_str = type_val if isinstance(type_val, str) else TYPE_MAP[type_val]
+        self.strip = spec.get("strip", True)
+        
+        if is_items:
+            for bad_key in ("required", "default", "aliases"):
+                if bad_key in spec:
+                    raise SchemaError(f"items spec cannot contain {bad_key}")
+            self.required = False
+            self.aliases = []
+            self.has_default = False
+            self.default = None
+        else:
+            self.required = spec.get("required", False)
+            self.aliases = spec.get("aliases", [])
+            if not isinstance(self.aliases, list):
+                raise SchemaError(f"aliases must be a list for field {name}")
+            self.has_default = "default" in spec
+            self.default = spec.get("default")
+            
+        self.nullable = spec.get("nullable", False)
+        
+        self.min = spec.get("min")
+        self.max = spec.get("max")
+        self.min_length = spec.get("min_length")
+        self.max_length = spec.get("max_length")
+        self.choices = spec.get("choices")
+        self.schema = spec.get("schema")
+        self.items = spec.get("items")
+
+        if self.schema is not None:
+            for ik, iv in self.schema.items():
+                Field(ik, iv)
+                
+        if self.items is not None:
+            Field("item", self.items, is_items=True)
+
+        self._validate_constraints()
+        self._normalize_choices()
+        self._check_default()
+
+    def _validate_constraints(self):
+        if self.required and self.has_default:
+            raise SchemaError(f"Field {self.name} cannot be both required and have a default")
+
+        if self.min is not None or self.max is not None:
+            if self.type_str not in ("int", "float"):
+                raise SchemaError(f"min/max constraints used on unsupported type {self.type_str}")
+            if isinstance(self.min, bool) or isinstance(self.max, bool):
+                raise SchemaError("min/max cannot be bool")
+            if self.min is not None and not math.isfinite(self.min):
+                raise SchemaError("min must be finite")
+            if self.max is not None and not math.isfinite(self.max):
+                raise SchemaError("max must be finite")
+            if self.min is not None and self.max is not None and self.min > self.max:
+                raise SchemaError("min > max")
+
+        if self.min_length is not None or self.max_length is not None:
+            if self.type_str not in ("str", "list"):
+                raise SchemaError(f"min_length/max_length constraints used on unsupported type {self.type_str}")
+            if isinstance(self.min_length, bool) or isinstance(self.max_length, bool):
+                raise SchemaError("min_length/max_length cannot be bool")
+            if self.min_length is not None and (not isinstance(self.min_length, int) or self.min_length < 0):
+                raise SchemaError("min_length must be non-negative int")
+            if self.max_length is not None and (not isinstance(self.max_length, int) or self.max_length < 0):
+                raise SchemaError("max_length must be non-negative int")
+            if self.min_length is not None and self.max_length is not None and self.min_length > self.max_length:
+                raise SchemaError("min_length > max_length")
+
+        if self.choices is not None:
+            if self.type_str in ("list", "dict"):
+                raise SchemaError(f"choices constraint used on unsupported type {self.type_str}")
+            if isinstance(self.choices, (str, bytes)) or not hasattr(self.choices, '__iter__') or not self.choices:
+                raise SchemaError("choices must be a non-empty iterable (not str/bytes)")
+
+    def _normalize_choices(self):
+        if self.choices is not None:
+            normalized_choices = []
+            for c in self.choices:
+                val, err = normalize(c, self.type_str, self.strip)
+                if err:
+                    raise SchemaError(f"Choice {c} fails normalization for type {self.type_str}")
+                normalized_choices.append(val)
+            self.choices = normalized_choices
+
+    def _check_default(self):
+        if not self.has_default:
+            return
+            
+        if self.default is None:
+            return
+            
+        if self.schema is not None:
+            if not isinstance(self.default, dict):
+                raise SchemaError("default for nested schema must be a dict")
+            return
+            
+        if self.type_str == "list":
+            if not isinstance(self.default, list):
+                raise SchemaError("default for list field must be a list")
+            return
+            
+        # Scalar default checking
+        val, err = normalize(self.default, self.type_str, self.strip)
+        if err:
+            raise SchemaError(f"Scalar default fails normalization: {err.name if hasattr(err, 'name') else err}")
+            
+        errs = validate_constraints(
+            val, self.type_str, self.min, self.max, 
+            self.min_length, self.max_length, self.choices
+        )
+        if errs:
+            raise SchemaError("Scalar default fails constraints")
+            
+        self.default = val
+
+Schema = Dict[str, Any]

api_response_cleaner/validator.py

@@ -0,0 +1,32 @@
+from typing import Any, List, Tuple
+from .errors import ErrorCode
+
+def validate_constraints(
+    value: Any,
+    type_str: str,
+    min_val: Any = None,
+    max_val: Any = None,
+    min_length: Any = None,
+    max_length: Any = None,
+    choices: Any = None
+) -> List[Tuple[ErrorCode, str]]:
+    errs = []
+
+    if choices is not None:
+        if value not in choices:
+            errs.append((ErrorCode.not_in_choices, f"Value not in choices"))
+
+    if type_str in ("int", "float"):
+        if min_val is not None and value < min_val:
+            errs.append((ErrorCode.too_small, f"Value is less than {min_val}"))
+        if max_val is not None and value > max_val:
+            errs.append((ErrorCode.too_large, f"Value is greater than {max_val}"))
+
+    if type_str in ("str", "list"):
+        length = len(value)
+        if min_length is not None and length < min_length:
+            errs.append((ErrorCode.too_short, f"Length {length} is less than {min_length}"))
+        if max_length is not None and length > max_length:
+            errs.append((ErrorCode.too_long, f"Length {length} is greater than {max_length}"))
+
+    return errs

api_response_cleaner-0.1.0.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: api-response-cleaner
+Version: 0.1.0
+Summary: Turns inconsistent API responses into validated Python data using a developer-defined schema.
+Author: Narala Vamsi Krishna
+License: MIT
+Project-URL: Homepage, https://github.com/VamsiKrishnaNarala/api-response-cleaner
+Project-URL: Repository, https://github.com/VamsiKrishnaNarala/api-response-cleaner
+Project-URL: Issues, https://github.com/VamsiKrishnaNarala/api-response-cleaner/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# api-response-cleaner
+
+Turns inconsistent API responses into validated Python data using a developer-defined schema. Zero dependencies.
+
+## Why Use This Library? (Use Cases)
+
+- **[Standardize third-party APIs](#example-a--standardizing-apis)**: Normalize inconsistent field types and response formats into a predictable output schema.
+- **[Handle legacy and inconsistent data](#example-b--legacy-field-names-and-defaults)**: Support field aliases, optional fields, defaults, and explicit missing/null behavior.
+- **Lightweight alternative to Pydantic**: A smaller, standard-library-runtime-dependency-free option for dictionary-based cleaning and validation when you don't need arbitrary object models.
+- **[Validate nested JSON safely](#example-c--nested-data)**: Perform nested schema validation and error reporting without manual chains of `.get()` calls.
+
+## Installation
+
+```bash
+pip install api-response-cleaner
+```
+
+## Quick Start
+
+```python
+from api_response_cleaner import clean
+
+result = clean(
+    {"full_name": " Ravi ", "age": "25"},
+    schema={"name": {"type": str, "required": True},
+            "age": {"type": int, "required": True}},
+    aliases={"name": ["full_name"]},
+)
+print(result.data)    # {"name": "Ravi", "age": 25}
+print(result.errors)  # []
+```
+
+## Schema Reference
+
+Define fields as dictionaries. Supported keys:
+- `type`: `str`, `int`, `float`, `bool`, `list`, `dict`, `object`
+- `required`: boolean, default `False`
+- `default`: fallback value if key absent
+- `nullable`: boolean, default `False`
+- `aliases`: list of alternative keys
+- `strip`: boolean, default `True` (for strings)
+- `choices`: iterable of allowed values
+- `min`, `max`: bounds for `int` and `float`
+- `min_length`, `max_length`: length bounds for `str` and `list`
+- `schema`: dictionary of sub-fields (implies `type` dict)
+- `items`: type or spec for list elements
+
+Shorthand: `{"age": int}` is equivalent to `{"age": {"type": int}}`.
+
+## Missing and Null Decision Table
+
+| Input state                 | optional       | required              | default=7 | nullable=True         |
+|-----------------------------|----------------|-----------------------|-----------|-----------------------|
+| key absent                  | key omitted    | missing_required      | 7         | key omitted           |
+| key present, value null     | key omitted    | null_not_allowed      | 7         | None (null preserved) |
+| key present, value "25"     | 25             | 25                    | 25        | 25                    |
+| key present, value ""       | conversion_failed in all four columns                                      |
+
+Note: `nullable=True` + `required=True` with key absent gives `missing_required`.
+
+## Alias and Nested Rules
+
+- Aliases are tried in order if canonical name is missing. 
+- If canonical name and alias are both present and non-null, canonical wins.
+- Alias keys are consumed; they are not reported as extra or unexpected.
+- Errors are reported on canonical paths.
+- Nested schema values must be objects (dict).
+- Inner errors are collected and reported with full dotted paths (e.g. `address.city`).
+- If an inner error occurs, the whole nested key is omitted from result data.
+
+## Structured Defaults Warning
+
+A structured default (`list` or `dict`) is **trusted**. It is returned as-is (deep copied) and its contents are NOT normalized, constraint-checked, or mapped for aliases. Structured defaults must already be in their final valid form.
+
+## Constraints
+
+| Constraint                | Supported Types         |
+|---------------------------|-------------------------|
+| `min`, `max`              | `int`, `float`          |
+| `min_length`, `max_length`| `str`, `list`           |
+| `choices`                 | `str`, `int`, `float`, `bool`, `object` |
+
+## Conversion Rules
+
+- `str`: Accepts strings, ints, finite floats. Strips whitespace by default.
+- `int`: Accepts ints, whole floats (e.g., `25.0`), and numeric strings.
+- `float`: Accepts finite floats, ints, and numeric strings.
+- `bool`: Accepts booleans, ints `0` and `1`, strings `true`, `false`, `yes`, `no`, `on`, `off`, `1`, `0`.
+- `list`: Accepts lists and tuples.
+- `dict`: Accepts dicts.
+- `object`: Accepts anything.
+
+## Error Codes
+
+- `missing_required`
+- `null_not_allowed`
+- `conversion_failed`
+- `not_in_choices`
+- `too_small`
+- `too_large`
+- `too_short`
+- `too_long`
+- `unexpected_field`
+- `invalid_input`
+
+## Examples
+
+### Example A — Standardizing APIs
+
+Normalize inconsistent payloads into a predictable shape.
+
+```python
+from api_response_cleaner import clean
+
+schema = {
+    "name": {"type": str, "aliases": ["full_name"], "required": True},
+    "age": {"type": int, "nullable": True}
+}
+
+api_a = {"name": "Ravi", "age": 25}
+api_b = {"name": "Ravi", "age": "25"}
+api_c = {"full_name": "Ravi", "age": None}
+
+for api, payload in zip(["A", "B", "C"], [api_a, api_b, api_c]):
+    res = clean(payload, schema)
+    print(f"API {api}: data={res.data}, errors={res.errors}")
+```
+
+*Note that API C's `age=None` is handled exactly according to the schema (preserved because `nullable=True`). It is never silently converted to a zero value or a default unless explicitly configured.*
+
+### Example B — Legacy field names and defaults
+
+Define canonical fields while supporting old aliases and providing sensible defaults.
+
+```python
+from api_response_cleaner import clean
+
+schema = {
+    "theme": {"type": str, "aliases": ["ui_theme", "color_mode"], "default": "light"}
+}
+
+# 1. Canonical key works normally
+print(clean({"theme": "dark"}, schema).data) 
+# -> {"theme": "dark"}
+
+# 2. Alias is seamlessly mapped to the canonical key
+print(clean({"ui_theme": "dark"}, schema).data) 
+# -> {"theme": "dark"}
+
+# 3. Missing key falls back to the default
+print(clean({}, schema).data) 
+# -> {"theme": "light"}
+
+# 4. Explicit null ignores the default unless the field is nullable
+res = clean({"theme": None}, schema)
+print(res.errors[0].code) 
+# -> ErrorCode.null_not_allowed
+```
+
+### Example C — Nested data
+
+Safely parse nested user/address data without manual `.get()` chains. Invalid nested objects are omitted entirely instead of returned partially cleaned.
+
+```python
+from api_response_cleaner import Cleaner
+
+cleaner = Cleaner({
+    "address": {
+        "schema": {
+            "city": {"type": str, "required": True},
+            "zip": int
+        }
+    }
+})
+
+# Valid payload
+res_valid = cleaner.clean({"address": {"city": "NY", "zip": "10001"}})
+print(res_valid.data)
+# -> {"address": {"city": "NY", "zip": 10001}}
+
+# Invalid payload
+res_invalid = cleaner.clean({"address": {"zip": "abc"}})
+print("Errors:", [(e.field, e.code.value) for e in res_invalid.errors])
+# -> Errors: [('address.city', 'missing_required'), ('address.zip', 'conversion_failed')]
+print("Data:", res_invalid.data)
+# -> Data: {}
+```
+
+### Example D — List validation
+
+Validate lists of typed items. Bad elements are reported by their original index, and the whole list is omitted from data if any element is invalid.
+
+```python
+from api_response_cleaner import clean
+
+schema = {
+    "scores": {"type": list, "items": int}
+}
+
+res = clean({"scores": ["1", "x", None, "3"]}, schema)
+print("Errors:", [(e.field, e.code.value) for e in res.errors])
+# -> Errors: [('scores[1]', 'conversion_failed'), ('scores[2]', 'null_not_allowed')]
+print("Data:", res.data)
+# -> Data: {}
+```
+
+## Development Commands
+
+```bash
+pip install -e .[dev]
+pytest
+python -m build
+twine check dist/*
+```
+
+## Releasing
+
+- [ ] pytest passes on Python 3.11 and the newest installed Python
+- [ ] python -m build produces one sdist and one wheel
+- [ ] twine check dist/* passes
+- [ ] the wheel installs into a clean virtual environment and the quick-start example runs
+- [ ] [project.urls], author and license holder are filled in
+- [ ] the package name is confirmed available on PyPI, then upload to TestPyPI first

api_response_cleaner-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+api_response_cleaner/__init__.py,sha256=H_fbzmliBfgGjk2BMWRuX00vyfnG0PDBF6crCUhxJwo,324
+api_response_cleaner/cleaner.py,sha256=z8GnZKO9lbJDs6j0m967ugjZ4KMU2Bbu8ZtaXbU5zo4,8171
+api_response_cleaner/errors.py,sha256=wrasO5umoUF_pUxX3qkp8RQXbWI4y9AFaq6CXiFBQ80,1184
+api_response_cleaner/normalizer.py,sha256=_WfbetsRXcwcQpgveV5VvHZ0HFPxZzTGvlGRRd7DuKM,2957
+api_response_cleaner/py.typed,sha256=4W8VliAYUP1KY2gLJ_YDy2TmcXYVm-PY7XikQD_bFwA,2
+api_response_cleaner/schema.py,sha256=QeNJdzuBI9Br6P20ScDtaWz0Vcdb3lxp5rx0AVdgM9o,6432
+api_response_cleaner/validator.py,sha256=OepTfdRv-5p513sDzihIDPk2ypi0N_bU7eWOF0aH3ZY,1138
+api_response_cleaner-0.1.0.dist-info/licenses/LICENSE,sha256=QmM4n-igqz_SUin4liyZCmgxdfPdArWHkLErKR_9y1I,1077
+api_response_cleaner-0.1.0.dist-info/METADATA,sha256=flro4mhUHWHnDrQbIiSFsZ39N79X4ENnc6e7XkBKE7I,9055
+api_response_cleaner-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+api_response_cleaner-0.1.0.dist-info/top_level.txt,sha256=18fg4tObVVHg8TYajzpXnoi2H-78OAFtzxmKkp_Gpfw,21
+api_response_cleaner-0.1.0.dist-info/RECORD,,

api_response_cleaner-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

api_response_cleaner-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Narala Vamsi Krishna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

api_response_cleaner-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+api_response_cleaner