Skip to content

Commit

Permalink
Reorder docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Fatal1ty committed Nov 14, 2023
1 parent 23d38c8 commit 36cfcdc
Showing 1 changed file with 40 additions and 36 deletions.
76 changes: 40 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ Table of contents
* [`serialization_strategy` config option](#serialization_strategy-config-option)
* [`aliases` config option](#aliases-config-option)
* [`serialize_by_alias` config option](#serialize_by_alias-config-option)
* [`allow_deserialization_not_by_alias` config option](#allow_deserialization_not_by_alias-config-option)
* [`omit_none` config option](#omit_none-config-option)
* [`omit_default` config option](#omit_default-config-option)
* [`namedtuple_as_dict` config option](#namedtuple_as_dict-config-option)
Expand All @@ -67,7 +68,6 @@ Table of contents
* [`discriminator` config option](#discriminator-config-option)
* [`lazy_compilation` config option](#lazy_compilation-config-option)
* [`sort_keys` config option](#sort_keys-config-option)
* [`allow_deserialization_not_by_alias` config option](#allow_deserialization_not_by_alias-config-option)
* [Passing field values as is](#passing-field-values-as-is)
* [Extending existing types](#extending-existing-types)
* [Dialects](#dialects)
Expand Down Expand Up @@ -973,8 +973,12 @@ x = DataClass.from_dict({"FieldA": 1, "#invalid": 2}) # DataClass(a=1, b=2)
x.to_dict() # {"a": 1, "b": 2} # no aliases on serialization by default
```

If you want to write all the field aliases in one place there is
[such a config option](#aliases-config-option).
If you want to write all the field aliases in one place, there is
[a config option](#aliases-config-option) for that.

If you want to deserialize all the fields by its names along with aliases,
there is [a config option](#allow_deserialization_not_by_alias-config-option)
for that.

If you want to serialize all the fields by aliases you have two options to do so:
* [`serialize_by_alias` config option](#serialize_by_alias-config-option)
Expand Down Expand Up @@ -1159,6 +1163,39 @@ class DataClass(DataClassDictMixin):
DataClass(field_a=1).to_dict() # {'FieldA': 1}
```

#### `allow_deserialization_not_by_alias` config option

When using aliases, the deserializer defaults to requiring the keys to match
what is defined as the alias.
If the flexibility to deserialize aliased and unaliased keys is required then
the config option `allow_deserialization_not_by_alias = True` can be set to
enable the feature.

```python
from dataclasses import dataclass, field
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig


@dataclass
class AliasedDataClass(DataClassDictMixin):
foo: int = field(metadata={"alias": "alias_foo"})
bar: int = field(metadata={"alias": "alias_bar"})

class Config(BaseConfig):
allow_deserialization_not_by_alias = True


alias_dict = {"alias_foo": 1, "alias_bar": 2}
t1 = AliasedDataClass.from_dict(alias_dict)

no_alias_dict = {"foo": 1, "bar": 2}
# This would raise `mashumaro.exceptions.MissingField`
# if allow_deserialization_not_by_alias was False
t2 = AliasedDataClass.from_dict(no_alias_dict)
assert t1 == t2
```

#### `omit_none` config option

All the fields with `None` values will be skipped during serialization by
Expand Down Expand Up @@ -1392,39 +1429,6 @@ t = SortedDataClass(1, 2)
assert t.to_dict() == {"bar": 2, "foo": 1}
```
#### `allow_deserialization_not_by_alias` config option

When using aliases, the deserializer defaults to requiring the keys to match
what is defined as the alias.
If the flexibility to deserialize aliased and unaliased keys is required then
the config option `allow_deserialization_not_by_alias = True` can be set to
enable the feature.

```python
from dataclasses import dataclass, field
from mashumaro import DataClassDictMixin
from mashumaro.config import BaseConfig


@dataclass
class AliasedDataClass(DataClassDictMixin):
foo: int = field(metadata={"alias": "alias_foo"})
bar: int = field(metadata={"alias": "alias_bar"})

class Config(BaseConfig):
allow_deserialization_not_by_alias = True


alias_dict = {"alias_foo": 1, "alias_bar": 2}
t1 = AliasedDataClass.from_dict(alias_dict)

no_alias_dict = {"foo": 1, "bar": 2}
# This would raise `mashumaro.exceptions.MissingField`
# if allow_deserialization_not_by_alias was False
t2 = AliasedDataClass.from_dict(no_alias_dict)
assert t1 == t2
```

### Passing field values as is

In some cases it's needed to pass a field value as is without any changes
Expand Down

0 comments on commit 36cfcdc

Please sign in to comment.