context7.json

{
  "$schema": "https://context7.com/schema/context7.json",
  "projectTitle": "marshmallow-recipe",
  "description": "Convenient serialization/deserialization of Python dataclasses using marshmallow. Supports both marshmallow v2 and v3 simultaneously with automatic schema generation. Includes high-performance Rust backend (mr.nuked), JSON Schema Draft 2020-12 generation, Generic types, cyclic references, Literal types, PEP 695 type aliases, bytes with base64, flexible field configuration, naming case conversion, PATCH operations with mr.MISSING, validation, and decimal precision control.",
  "folders": ["examples"],
  "excludeFolders": ["tests", ".github", "benchmarks"],
  "excludeFiles": [],
  "rules": [
    "Works with both marshmallow v2 and v3 - no version-specific code needed",
    "Basic usage: mr.dump(obj) to serialize, mr.load(Class, data) to deserialize",
    "All Python types supported: str, int, float, bool, bytes, decimal.Decimal, datetime.datetime, datetime.date, datetime.time, uuid.UUID, enums, Literal, Any",
    "Collections: list[T], set[T], frozenset[T], tuple[T, ...], dict[K, V] - all work automatically",
    "Nested dataclasses work automatically without special configuration",
    "Optional types with T | None - None values excluded from output by default",
    "For custom field names use: Annotated[T, mr.meta(name='newName')]",
    "For string transformations: Annotated[str, mr.str_meta(strip_whitespaces=True, post_load=func)]",
    "For decimal precision validation: Annotated[decimal.Decimal, mr.decimal_meta(places=N)] - validates max decimal places, raises ValidationError if exceeded",
    "For decimal rounding: Annotated[decimal.Decimal, mr.decimal_meta(places=N, rounding=decimal.ROUND_HALF_UP)] - rounds to N places instead of validating",
    "For decimal range validation: Annotated[decimal.Decimal, mr.decimal_meta(gt=0, lte=100)] - operators: gt (>), gte (>=), lt (<), lte (<=); accepts both int and Decimal bounds (int auto-converted to Decimal)",
    "For decimal range custom errors: mr.decimal_meta(gt=Decimal('0'), gt_error='Must be positive') - each operator has a corresponding _error param",
    "For validation: Annotated[T, mr.meta(validate=lambda x: condition)] or mr.regexp_validate(regex, error=msg)",
    "For email validation: Annotated[str, mr.str_meta(validate=mr.email_validate())] or with custom error: mr.email_validate(error='msg')",
    "For custom field error messages: Annotated[T, mr.meta(required_error='msg', none_error='msg', invalid_error='msg')]",
    "For collection item validation: mr.list_meta(validate_item=func), mr.set_meta(validate_item=func), mr.tuple_meta(validate_item=func)",
    "GLOBAL PARAMETERS: Three parameters can be passed to load/dump/schema - naming_case, none_value_handling, decimal_places",
    "Global parameter naming_case: mr.dump(obj, naming_case=mr.CAMEL_CASE) converts field names at runtime",
    "Global parameter none_value_handling: mr.dump(obj, none_value_handling=mr.NoneValueHandling.INCLUDE) includes None values",
    "Global parameter decimal_places: mr.dump(obj, decimal_places=2) validates max decimal places for all decimals at runtime",
    "Use @mr.options(naming_case=mr.CAMEL_CASE) for camelCase conversion on entire dataclass",
    "Use @mr.options(naming_case=mr.CAPITAL_CAMEL_CASE) for PascalCase conversion",
    "Use @mr.options(naming_case=mr.UPPER_SNAKE_CASE) for UPPER_SNAKE_CASE conversion",
    "Use @mr.options(none_value_handling=mr.NoneValueHandling.INCLUDE) to include None values in output",
    "Use @mr.options(decimal_places=N) to validate max decimal places for all Decimal fields in a dataclass",
    "Nested dataclasses keep their own @mr.options settings - NOT inherited from parent",
    "For PATCH operations use mr.MISSING as default: field: T = mr.MISSING to distinguish null from missing fields",
    "mr.MISSING fields are excluded from dump output, allowing partial updates",
    "With none_value_handling=INCLUDE, you can distinguish: field not sent (MISSING), field=null (None), field=value",
    "Generic types with TypeVar work: class Container(Generic[T]) with full inheritance support",
    "Cyclic/self-referencing structures: Type hints with quotes work: 'ClassName | None' or list['ClassName']",
    "Use @mr.pre_load decorator on static methods to transform data before deserialization",
    "Use mr.add_pre_load(Class, func) to programmatically add pre_load hooks without decorator",
    "Custom datetime formats: Annotated[datetime.datetime, mr.datetime_meta(format='%Y-%m-%d %H:%M:%S')]",
    "Use mr.validate(condition, error='msg') helper for readable validation with custom error messages",
    "collections.abc types supported: Sequence (→list), Set (→set), Mapping (→dict) work transparently",
    "NewType support: NewType('UserId', int) works transparently - treated as underlying type",
    "Literal types: Literal['a', 'b', 'c'] validates values on both dump and load - works with str, int, and bool literals",
    "Literal types: Optional literals (Literal['x', 'y'] | None), defaults, and mr.MISSING all supported",
    "Literal types: JSON Schema maps Literal['a', 'b'] to {\"type\": \"string\", \"enum\": [\"a\", \"b\"]}, Literal[1, 2] to {\"type\": \"integer\", \"enum\": [1, 2]}, Literal[True, False] to {\"type\": \"boolean\", \"enum\": [true, false]}",
    "Schemas generated and cached automatically - mr.schema(Class) returns marshmallow Schema, cached per (naming_case, none_value_handling, decimal_places)",
    "Use mr.load_many(Class, list_data) and mr.dump_many(list_objs) for lists of objects",
    "Use mr.get_validation_field_errors(exc) to get structured ValidationError details",
    "JSON SCHEMA GENERATION: Use mr.json_schema(Class) to generate JSON Schema Draft 2020-12 from dataclasses",
    "JSON Schema: All Python types automatically mapped - str→string, int→integer, float→number, bool→boolean, etc.",
    "JSON Schema: DateTime types include format - datetime→date-time, date→date, time→time, uuid.UUID→uuid",
    "JSON Schema: Enums include enum values - Status(str, Enum) → {\"type\": \"string\", \"enum\": [values]}",
    "JSON Schema: Literal types include allowed values - Literal['a', 'b'] → {\"type\": \"string\", \"enum\": [\"a\", \"b\"]}",
    "JSON Schema: Collections mapped - list→array, set→array with uniqueItems, dict→object with additionalProperties",
    "JSON Schema: Union types (str | int) mapped to anyOf - {\"anyOf\": [{\"type\": \"string\"}, {\"type\": \"integer\"}]}",
    "JSON Schema: Optional fields (T | None) not in required array, but type is not anyOf with null",
    "JSON Schema: Nested dataclasses use $defs and $ref for reusability - {\"$ref\": \"#/$defs/ClassName\"}",
    "JSON Schema: Cyclic/self-referential types handled automatically without infinite recursion",
    "JSON Schema: Field descriptions via Annotated[T, mr.meta(description='...')] → {\"description\": \"...\"}",
    "JSON Schema: Collection item descriptions via mr.list_meta(item_description='...'), mr.set_meta(item_description='...'), mr.tuple_meta(item_description='...')",
    "JSON Schema: Schema-level documentation via @mr.options(title='...', description='...') sets top-level title and description",
    "JSON Schema: Default values included in schema - field: int = 42 → {\"type\": \"integer\", \"default\": 42}",
    "JSON Schema: Naming case conversion - mr.json_schema(Class, naming_case=mr.CAMEL_CASE) converts field names",
    "JSON Schema: Decimal representation controlled by metadata - mr.decimal_meta(as_string=True) → string, as_string=False → number",
    "JSON Schema: Decimal range constraints emitted - gt→exclusiveMinimum, gte→minimum, lt→exclusiveMaximum, lte→maximum (values as strings)",
    "JSON Schema: Not cached (unlike mr.schema) - generates fresh dict each call, similar to mr.dump()",
    "JSON Schema: Override title per call - mr.json_schema(User, title='Custom') overrides @mr.options(title='...')",
    "NUKED SCHEMA: mr.nuked.schema(Class) generates marshmallow Schema for introspection (apispec), delegates load() and dump() to Rust backend — automatic speedup without extra effort",
    "NUKED SCHEMA: Schema fields available for apispec/OpenAPI, but actual serialization runs through Rust — drop-in replacement for mr.schema() with speedup",
    "NUKED SCHEMA: Supports many=True — mr.nuked.schema(Class, many=True).load(list_data) for batch loading",
    "NUKED SCHEMA: Accepts same parameters as mr.schema() — naming_case, none_value_handling, decimal_places",
    "NUKED SCHEMA: Cached per (cls, many, naming_case, none_value_handling, decimal_places) — same instance returned for same args",
    "NUKED SCHEMA: Supports pre_load hooks",
    "NUKED ROOT COLLECTIONS: mr.nuked.dump(dict[str, T], data) and mr.nuked.load(dict[str, T], data) work with any T — primitives (str, int, float, bool, datetime, date, time, Decimal, UUID), enums, dataclasses, nested collections, optionals, and Any",
    "NUKED ROOT COLLECTIONS: No dataclass wrapper needed — pass bare dict/list types directly as root type",
    "Literal types: Values must be homogeneous — all str or all int, bools rejected for int literals",
    "PEP 695 type aliases: type X = str | int works transparently as field types — unwrapped automatically",
    "PEP 695 type aliases: Works in dump/load/dump_many/load_many — type Message = UserMessage | AssistantMessage; mr.dump(Message, obj), mr.load(Message, data), mr.dump_many(Message, objs), mr.load_many(Message, data)",
    "PEP 695 type aliases: Works in nuked — mr.nuked.dump(Message, obj), mr.nuked.load(Message, data), mr.nuked.dump(list[Message], objs), mr.nuked.load(list[Message], data)",
    "PEP 695 type aliases: Discriminated unions with Literal fields — type Message = UserMsg | AssistantMsg where role: Literal['user'] vs role: Literal['assistant'] enables correct dispatch on load",
    "Bytes type: bytes fields automatically encoded to base64 string on dump, decoded from base64 string on load",
    "Bytes type: JSON Schema maps bytes to {\"type\": \"string\", \"format\": \"byte\"} (OpenAPI standard for base64)"
  ],
  "previousVersions": []
}