https://github.com/clarketm/mergedeep

A deep merge function for 🐍.
https://github.com/clarketm/mergedeep

deepmerge mapping merge mergedeep python

Last synced: 3 months ago
JSON representation

A deep merge function for 🐍.

• Host: GitHub
• URL: https://github.com/clarketm/mergedeep
• Owner: clarketm
• License: mit
• Created: 2019-02-04T01:30:45.000Z (almost 6 years ago)
• Default Branch: master
• Last Pushed: 2024-04-02T15:47:12.000Z (8 months ago)
• Last Synced: 2024-07-18T23:00:46.853Z (4 months ago)
• Topics: deepmerge, mapping, merge, mergedeep, python
• Language: Python
• Homepage: https://mergedeep.readthedocs.io/en/latest/
• Size: 94.7 KB
• Stars: 140
• Watchers: 4
• Forks: 10
• Open Issues: 10
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# [mergedeep](https://mergedeep.readthedocs.io/en/latest/)

[![PyPi release](https://img.shields.io/pypi/v/mergedeep.svg)](https://pypi.org/project/mergedeep/)

[![PyPi versions](https://img.shields.io/pypi/pyversions/mergedeep.svg)](https://pypi.org/project/mergedeep/)

[![Downloads](https://pepy.tech/badge/mergedeep)](https://pepy.tech/project/mergedeep)

[![Conda Version](https://img.shields.io/conda/vn/conda-forge/mergedeep.svg)](https://anaconda.org/conda-forge/mergedeep)

[![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/mergedeep.svg)](https://anaconda.org/conda-forge/mergedeep)

[![Documentation Status](https://readthedocs.org/projects/mergedeep/badge/?version=latest)](https://mergedeep.readthedocs.io/en/latest/?badge=latest)

A deep merge function for 🐍.

[Check out the mergedeep docs](https://mergedeep.readthedocs.io/en/latest/)

## Installation

```bash

$ pip install mergedeep

```

## Usage

```text

merge(destination: MutableMapping, *sources: Mapping, strategy: Strategy = Strategy.REPLACE) -> MutableMapping

```

Deep merge without mutating the source dicts.

```python3

from mergedeep import merge

a = {"keyA": 1}

b = {"keyB": {"sub1": 10}}

c = {"keyB": {"sub2": 20}}

merged = merge({}, a, b, c) 

print(merged)

# {"keyA": 1, "keyB": {"sub1": 10, "sub2": 20}}

```

Deep merge into an existing dict.

```python3

from mergedeep import merge

a = {"keyA": 1}

b = {"keyB": {"sub1": 10}}

c = {"keyB": {"sub2": 20}}

merge(a, b, c) 

print(a)

# {"keyA": 1, "keyB": {"sub1": 10, "sub2": 20}}

```

### Merge strategies:

1. Replace (*default*)

> `Strategy.REPLACE`

```python3

# When `destination` and `source` keys are the same, replace the `destination` value with one from `source` (default).

# Note: with multiple sources, the `last` (i.e. rightmost) source value will be what appears in the merged result. 

from mergedeep import merge, Strategy

dst = {"key": [1, 2]}

src = {"key": [3, 4]}

merge(dst, src, strategy=Strategy.REPLACE) 

# same as: merge(dst, src)

print(dst)

# {"key": [3, 4]}

```

2. Additive

> `Strategy.ADDITIVE`

```python3

# When `destination` and `source` values are both the same additive collection type, extend `destination` by adding values from `source`.

# Additive collection types include: `list`, `tuple`, `set`, and `Counter`

# Note: if the values are not additive collections of the same type, then fallback to a `REPLACE` merge.

from mergedeep import merge, Strategy

dst = {"key": [1, 2], "count": Counter({"a": 1, "b": 1})}

src = {"key": [3, 4], "count": Counter({"a": 1, "c": 1})}

merge(dst, src, strategy=Strategy.ADDITIVE) 

print(dst)

# {"key": [1, 2, 3, 4], "count": Counter({"a": 2, "b": 1, "c": 1})}

```

3. Typesafe replace

> `Strategy.TYPESAFE_REPLACE` or `Strategy.TYPESAFE`

```python3

# When `destination` and `source` values are of different types, raise `TypeError`. Otherwise, perform a `REPLACE` merge.

from mergedeep import merge, Strategy

dst = {"key": [1, 2]}

src = {"key": {3, 4}}

merge(dst, src, strategy=Strategy.TYPESAFE_REPLACE) # same as: `Strategy.TYPESAFE`  

# TypeError: destination type:  differs from source type:  for key: "key"

```

4. Typesafe additive

> `Strategy.TYPESAFE_ADDITIVE`

```python3

# When `destination` and `source` values are of different types, raise `TypeError`. Otherwise, perform a `ADDITIVE` merge.

from mergedeep import merge, Strategy

dst = {"key": [1, 2]}

src = {"key": {3, 4}}

merge(dst, src, strategy=Strategy.TYPESAFE_ADDITIVE) 

# TypeError: destination type:  differs from source type:  for key: "key"

```

## License

MIT © [**Travis Clarke**](https://blog.travismclarke.com/)