OCDS Merge

https://ocds-merge.readthedocs.io
Admin
OCDS Merge is a Python package that creates records conforming to the Open Contracting Data Standard...
Tokens:20,027
Snippets:145
Trust Score:9.6
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install ocdsmerge with pip

Source: https://ocds-merge.readthedocs.io/en/latest/index.html

Install the ocdsmerge package using pip.

```bash
pip install ocdsmerge

```

--------------------------------

### Handle DuplicateIdValueWarning with warning filters

Source: https://ocds-merge.readthedocs.io/en/latest/handle-bad-data.html

Shows how to use Python's warnings module to turn the DuplicateIdValueWarning into an exception or ignore it. The example creates a compiled release from releases with duplicate award IDs, demonstrating both behaviors.

```python
import warnings

import ocdsmerge
from ocdsmerge.exceptions import DuplicateIdValueWarning

merger = ocdsmerge.Merger()

releases = [{"awards": [{"id": "1"}, {"id": "1"}]}]

# Raise an error, instead.
with warnings.catch_warnings():
    warnings.filterwarnings('error', category=DuplicateIdValueWarning)
    compiled_release = merger.create_compiled_release(releases)

# Ignore the warning, instead.
with warnings.catch_warnings():
    warnings.filterwarnings('ignore', category=DuplicateIdValueWarning)
    compiled_release = merger.create_compiled_release(releases)

# {'tag': ['compiled'], 'id': 'None-None', 'awards': [{'id': '1'}]}

```

--------------------------------

### Use rule_overrides to merge by position or append

Source: https://ocds-merge.readthedocs.io/en/latest/handle-bad-data.html

Shows how to set rule_overrides on a per-field basis to handle structural errors. The example uses APPEND for awards and MERGE_BY_POSITION for contract milestones, then creates a compiled release and shows the output.

```python
import ocdsmerge

merger = ocdsmerge.Merger(rule_overrides={
    ('awards',): ocdsmerge.APPEND,
    ('contracts', 'implementation', 'milestones'): ocdsmerge.MERGE_BY_POSITION,
})

releases = [{
    "date": "2001-02-03T00:00:00Z",
    "awards": [{"id": "1-append"}],
    "contracts": [{
        "id": "1-merge",
        "implementation": {
            "milestones": [{"id": "1-merge-by-position"}]
        }
    }]
}, {
    "date": "2004-05-06T00:00:00Z",
    "awards": [{"id": "1-append"}],
    "contracts": [{
        "id": "1-merge",
        "implementation": {
            "milestones": [{"id": "1-merge-by-position"}, {"id": "1-merge-by-position"}]
        }
    }]
}]

merger.create_compiled_release(releases)

# {'tag': ['compiled'],
#  'id': 'None-2004-05-06T00:00:00Z',
#  'date': '2004-05-06T00:00:00Z',
#  'awards': [{'id': '1-append'}, {'id': '1-append'}],
#  'contracts': [{'id': '1-merge',
#    'implementation': {'milestones': [{'id': '1-merge-by-position'},
#                                      {'id': '1-merge-by-position'}]}}]}

```

--------------------------------

### Define releases list for merging

Source: https://ocds-merge.readthedocs.io/en/latest/_sources/create-merged-releases.rst.txt

Defines a list of OCDS release objects to be merged. This assumes all releases have the same OCID and that no releases are missing. The comment notes that in a real-world example the releases might be loaded from local files or remote APIs.

```python
# In a real-world example, the OCDS releases might be loaded from local files or remote APIs.
releases = [
    {
        "ocid": "ocds-213czf-A",
        "id": "1",
        "date": "2014-01-01",
        "tag": ["tender"],
        "initiationType": "tender",
        "tender": {
            "id": "A",
            "procurementMethod": "selective"
        }
    },
    {
        "ocid": "ocds-213czf-A",
        "id": "2",
        "date": "2014-01-02",
        "tag": ["tender"],
        "initiationType": "tender",
        "tender": {
            "id": "A",
            "procurementMethod": "open"
        }
    }
]
```

--------------------------------

### Add a single release with append

Source: https://ocds-merge.readthedocs.io/en/latest/_sources/update-merged-releases.rst.txt

Adds a single release at a time; the release must be provided in date order.

```python
release = {
    "ocid": "ocds-213czf-A",
    "id": "3",
    "date": "2014-01-03",
    "tag": ["tender"],
    "initiationType": "tender",
    "tender": {
        "status": "complete"
    }
}

merger.append(release)

compiled_release = merger.asdict()
```

--------------------------------

### Import ocdsmerge and initialize Merger

Source: https://ocds-merge.readthedocs.io/en/latest/_sources/create-merged-releases.rst.txt

Initializes a Merger instance. The first block imports the library, then the subsequent blocks show four initialization options: with a patched schema (merger = ocdsmerge.Merger(patched_schema)), with an unpatched version (using get_release_schema_url), with a local schema file, and with the default latest version. The merger instance is reused repeatedly to create merged releases, and merge rules from the first initialization are cached when the same URL or file path is used again.

```python
import ocdsmerge
```

```python
merger = ocdsmerge.Merger(patched_schema)
```

```python
from ocdsmerge.util import get_release_schema_url

merger = ocdsmerge.Merger(get_release_schema_url('1__0__3'))
```

```python
from ocdsmerge.util import get_release_schema_url

# Using a relative file path…
merger = ocdsmerge.Merger(schema='release-schema.json')

# Using an absolute file path…
merger = ocdsmerge.Merger(schema='/absolute/path/to/release-schema.json')
```

```python
import ocdsmerge

merger = ocdsmerge.Merger()
```

--------------------------------

### Merger.__init__

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Constructor for the Merger class, initializing a reusable instance for merging releases.

```APIDOC
## Merger.__init__

### Description
Initializes a reusable Merger instance for creating merged releases. The schema, merge rules, and rule overrides can be provided to customize the merging behavior.

### Method
Constructor

### Parameters
- **schema** (dict or str) - Optional - The release schema. If not provided, defaults to the latest version of OCDS.
- **merge_rules** (dict[tuple[str, ...], str] | None) - Optional - The merge rules. If not provided, rules are determined from the schema.
- **rule_overrides** (dict[tuple[str, ...], MergeStrategy] | None) - Optional - Rule overrides where keys are field paths as tuples and values are either `ocdsmerge.APPEND` or `ocdsmerge.MERGE_BY_POSITION`.

### Returns
None
```

--------------------------------

### MergedRelease.__init__

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Constructor for the MergedRelease class, initializing a merged release.

```APIDOC
## MergedRelease.__init__

### Description
Initializes a merged release. The data, schema, merge rules, and rule overrides can be provided to customize the merging behavior.

### Method
Constructor

### Parameters
- **data** (dict[str, Any] | None) - Optional - The latest copy of the merged release, if any.
- **schema** (dict or str) - Optional - The release schema. If not provided, defaults to the latest version of OCDS.
- **merge_rules** (dict[tuple[str, ...], str] | None) - Optional - The merge rules. If not provided, rules are determined from the schema.
- **rule_overrides** (dict[tuple[str, ...], MergeStrategy] | None) - Optional - Rule overrides where keys are field paths as tuples and values are either `ocdsmerge.APPEND` or `ocdsmerge.MERGE_BY_POSITION`.

### Returns
None
```

--------------------------------

### Flatten JSON object to key-value pairs

Source: https://ocds-merge.readthedocs.io/en/latest/_modules/ocdsmerge/flatten.html

The `flatten` function converts a JSON object into a dictionary where keys are tuples representing JSON paths. It handles arrays by replacing numeric indices with special objects when objects have different `id` values. The docstring includes an example of input JSON and its flattened output.

```json
{
    "a": "I am a",
    "b": ["A", "list"],
    "c": [
        {"id": 1, "cb": "I am ca"},
        {"id": 2, "ca": "I am cb"}
    ]
}
```

```python
{
    ('a',): 'I am a',
    ('b',): ['A', 'list'],
    ('a', '1', 'cb'): 'I am ca',
    ('a', '1', 'id'): 1,
    ('a', '2', 'ca'): 'I am cb',
    ('a', '2', 'id'): 2,
}
```

--------------------------------

### Import ocdsmerge library

Source: https://ocds-merge.readthedocs.io/en/latest/create-merged-releases.html

Imports the ocdsmerge library. This is the first step before initializing a Merger instance.

```python
import ocdsmerge
```

--------------------------------

### CompiledRelease.__init__

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Constructor for the CompiledRelease class, initializing a compiled release.

```APIDOC
## CompiledRelease.__init__

### Description
Initializes a compiled release. The data and keyword arguments can be provided to customize the merging behavior.

### Method
Constructor

### Parameters
- **data** (dict[str, Any] | None) - Optional - The latest copy of the merged release, if any.
- **kwargs** - Optional - Additional keyword arguments, including schema, merge_rules, and rule_overrides.

### Returns
None
```

--------------------------------

### Initialize Merger with patched schema

Source: https://ocds-merge.readthedocs.io/en/latest/create-merged-releases.html

Initializes a Merger instance using a patched schema. Use this after patching the schema with extensions.

```python
merger = ocdsmerge.Merger(patched_schema)
```

--------------------------------

### Initialize Merger with local release schema

Source: https://ocds-merge.readthedocs.io/en/latest/create-merged-releases.html

Initializes a Merger instance using a locally stored release schema, either via a relative or absolute file path, to avoid remote requests.

```python
from ocdsmerge.util import get_release_schema_url

# Using a relative file path…
merger = ocdsmerge.Merger(schema='release-schema.json')

# Using an absolute file path…
merger = ocdsmerge.Merger(schema='/absolute/path/to/release-schema.json')
```

--------------------------------

### Initialize Merger with unpatched OCDS version

Source: https://ocds-merge.readthedocs.io/en/latest/create-merged-releases.html

Initializes a Merger instance using an unpatched version of OCDS, like 1.0.3, by fetching the release schema URL.

```python
from ocdsmerge.util import get_release_schema_url

merger = ocdsmerge.Merger(get_release_schema_url('1__0__3'))
```

--------------------------------

### Load merge rules from pickle file

Source: https://ocds-merge.readthedocs.io/en/latest/_sources/update-merged-releases.rst.txt

Loads previously saved merge rules from a pickle file to initialize the merger with the same rules used when the merged release was created.

```python
import pickle

with open('merge-rules.pickle', 'rb') as f:
    rules = pickle.load(f)
```

--------------------------------

### Create compiled and versioned releases

Source: https://ocds-merge.readthedocs.io/en/latest/create-merged-releases.html

Creates compiled and versioned releases from a list of releases. The releases must all have the same OCID and no missing releases.

```python
# In a real-world example, the OCDS releases might be loaded from local files or remote APIs.
releases = [
    {
        "ocid": "ocds-213czf-A",
        "id": "1",
        "date": "2014-01-01",
        "tag": ["tender"],
        "initiationType": "tender",
        "tender": {
            "id": "A",
            "procurementMethod": "selective"
        }
    },
    {
        "ocid": "ocds-213czf-A",
        "id": "2",
        "date": "2014-01-02",
        "tag": ["tender"],
        "initiationType": "tender",
        "tender": {
            "id": "A",
            "procurementMethod": "open"
        }
    }
]

compiled_release = merger.create_compiled_release(releases)

versioned_release = merger.create_versioned_release(releases)
```

--------------------------------

### Add one release at a time with append

Source: https://ocds-merge.readthedocs.io/en/latest/update-merged-releases.html

Adds a single release using the append method, ensuring releases are ordered by date. After appending, asdict() returns the updated compiled release.

```python
release = {
    "ocid": "ocds-213czf-A",
    "id": "3",
    "date": "2014-01-03",
    "tag": ["tender"],
    "initiationType": "tender",
    "tender": {
        "status": "complete"
    }
}

merger.append(release)

compiled_release = merger.asdict()

```

--------------------------------

### Add multiple releases with extend

Source: https://ocds-merge.readthedocs.io/en/latest/_sources/update-merged-releases.rst.txt

Adds multiple individual releases at once; the merger sorts them by date before updating the compiled release.

```python
releases = [
   {
       "ocid": "ocds-213czf-A",
       "id": "3",
       "date": "2014-01-03",
       "tag": ["tender"],
       "initiationType": "tender",
       "tender": {
           "status": "complete"
       }
   }
]

merger.extend(releases)

compiled_release = merger.asdict()
```

--------------------------------

### Initialize Merger with default OCDS schema

Source: https://ocds-merge.readthedocs.io/en/latest/create-merged-releases.html

Initializes a Merger instance using the release schema from the latest version of OCDS by default.

```python
import ocdsmerge

merger = ocdsmerge.Merger()
```

--------------------------------

### Initialize CompiledRelease with existing release

Source: https://ocds-merge.readthedocs.io/en/latest/_sources/update-merged-releases.rst.txt

Initializes a CompiledRelease instance with an existing compiled release and the loaded merge rules, enabling updates to the merged release.

```python
import ocdsmerge

compiled_release = {
    "tag": ["compiled"],
    "id": "ocds-213czf-A-2014-01-02T00:00:00Z",
    "date": "2014-01-02T00:00:00Z",
    "ocid": "ocds-213czf-A",
    "initiationType": "tender",
    "tender": {
        "id": "A",
        "procurementMethod": "open"
    }
}

merger = ocdsmerge.CompiledRelease(compiled_release, merge_rules=rules)
```

--------------------------------

### Save merge rules to a pickle file

Source: https://ocds-merge.readthedocs.io/en/latest/create-merged-releases.html

Stores the merge rules in a pickle file for later incremental updates of records.

```python
import pickle

with open('merge-rules.pickle', 'wb') as f:
    pickle.dump(merger.merge_rules, f)
```

--------------------------------

### get_tags()

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Returns a list of all OCDS version tags in alphabetical order.

```APIDOC
## get_tags()

### Description
Return the tags of all versions of OCDS in alphabetical order.

### Method
N/A (Python function)

### Endpoint
N/A

### Parameters
None

### Return Type
list[str]

### Return Example
["1.0", "1.1", "1.2"]
```

--------------------------------

### Create compiled and versioned releases

Source: https://ocds-merge.readthedocs.io/en/latest/_sources/create-merged-releases.rst.txt

Creates a compiled release and a versioned release from a list of releases using the merger object. The resulting objects can be used to create an OCDS record.

```python
compiled_release = merger.create_compiled_release(releases)
```

```python
versioned_release = merger.create_versioned_release(releases)
```

--------------------------------

### MissingDateKeyError(key, message)

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Exception raised when a release is missing a 'date' key.

```APIDOC
## MissingDateKeyError(key, message)

### Description
Raised when a release is missing a 'date' key.

### Method
N/A (Python exception)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **key** (str) - Required - The missing key name.
- **message** (str) - Required - The error message.

### Inherits From
OCDSMergeError
```

--------------------------------

### ocdsmerge.util module source code

Source: https://ocds-merge.readthedocs.io/en/latest/_modules/ocdsmerge/util.html

The complete source code of the ocdsmerge.util module. It provides get_tags() to fetch OCDS version tags, get_release_schema_url() to build schema URLs, and sorted_releases() to sort releases by date with detailed error handling for missing, null, non-string, and non-object date values.

```python
from __future__ import annotations

import re
from functools import lru_cache
from operator import itemgetter
from typing import Any

import requests

from ocdsmerge.exceptions import (
    MissingDateKeyError,
    NonObjectReleaseError,
    NonStringDateValueError,
    NullDateValueError,
)




[docs]
@lru_cache
def get_tags() -> list[str]:
    """Return the tags of all versions of OCDS in alphabetical order."""
    response = requests.get("https://standard.open-contracting.org/schema/", timeout=10)
    response.raise_for_status()
    return re.findall(r'"(\d+__\d+__\d+)/', response.text)





[docs]
def get_release_schema_url(tag: str) -> str:
    """Return the URL of the release schema in the given version of OCDS."""
    return f"https://standard.open-contracting.org/schema/{tag}/release-schema.json"




# If we need a method to get dates from releases, see https://github.com/open-contracting/ocds-merge/issues/25


[docs]
def sorted_releases(releases: list[dict[str, Any]]) -> list[dict[str, Any]]:
    """Sort a list of releases by date."""
    # Avoids an error if sorting a single compiled release.
    if isinstance(releases, list) and len(releases) == 1 and isinstance(releases[0], dict):
        return releases
    try:
        return sorted(releases, key=itemgetter("date"))
    except KeyError as e:
        raise MissingDateKeyError("date", "The `date` field of at least one release is missing.") from e
    except TypeError as e:
        if " not supported between instances of " in e.args[0]:
            if "NoneType" in e.args[0]:
                raise NullDateValueError("The `date` field of at least one release is null.") from e
            raise NonStringDateValueError("The `date` field of at least one release is not a string.") from e
        if e.args[0] in {
            "string indices must be integers",
            "string indices must be integers, not 'str'",
            "string indices must be integers or slices, not str",
            "string indices must be integers or slices, not 'str'",
        }:
            raise NonObjectReleaseError(
                "At least one release is a string, not a dict. Use `json.loads` to parse the string as JSON."
            ) from e
        if e.args[0] in {
            "byte indices must be integers or slices, not str",
            "byte indices must be integers or slices, not 'str'",
        }:
            raise NonObjectReleaseError(
                "At least one release is a byte-string, not a dict. Use `json.loads` to parse the byte-string as JSON."
            ) from e
        if e.args[0] in {
            "list indices must be integers or slices, not str",
            "list indices must be integers or slices, not 'str'",
        }:
            raise NonObjectReleaseError("At least one release is a list, not a dict.") from e
        if e.args[0] in {
            "tuple indices must be integers or slices, not str",
            "tuple indices must be integers or slices, not 'str'",
        }:
            raise NonObjectReleaseError("At least one release is a tuple, not a dict.") from e
        if e.args[0] in {"'set' object is not subscriptable", "'set' object is not subscriptable (key 'date')"}:
            raise NonObjectReleaseError("At least one release is a set, not a dict.") from e
        raise

```

--------------------------------

### sorted_releases(releases)

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Sorts a list of release dictionaries by date.

```APIDOC
## sorted_releases(releases)

### Description
Sort a list of releases by date.

### Method
N/A (Python function)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **releases** (list[dict[str, Any]]) - Required - A list of release dictionaries, each containing a 'date' key.

### Return Type
list[dict[str, Any]]

### Return Example
[{"date": "2020-01-01", ...}, {"date": "2020-02-01", ...}]
```

--------------------------------

### Patch schema with extensions using ProfileBuilder

Source: https://ocds-merge.readthedocs.io/en/latest/create-merged-releases.html

Patches the release schema with a list of extensions using ProfileBuilder from the OCDS Extension Registry library. Use this when you already know every extension used in a dataset.

```python
from ocdsextensionregistry import ProfileBuilder

extensions = [
    'https://raw.githubusercontent.com/open-contracting-extensions/ocds_coveredBy_extension/master/extension.json',
    'https://raw.githubusercontent.com/open-contracting-extensions/ocds_legalBasis_extension/master/extension.json',
]

builder = ProfileBuilder('1__1__4', extensions)
patched_schema = builder.patched_release_schema()
```

--------------------------------

### MergedRelease.asdict

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Returns the merged release as a dictionary.

```APIDOC
## MergedRelease.asdict

### Description
Returns the merged release as a dictionary. This method is used to obtain the merged release data in a dictionary format.

### Method
Method

### Parameters
None

### Returns
dict[str, Any] - The merged release as a dictionary.
```

--------------------------------

### Merger.create_versioned_release

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Merges a list of releases into a versioned release.

```APIDOC
## Merger.create_versioned_release

### Description
Merges a list of releases into a versioned release. This method is used to combine multiple releases into a versioned release.

### Method
Method

### Parameters
- **releases** (list[dict[str, Any]]) - Required - The list of releases to merge.

### Returns
dict[str, Any] - The versioned release as a dictionary.
```

--------------------------------

### MergedRelease.extend

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Sorts and merges many releases into the merged release.

```APIDOC
## MergedRelease.extend

### Description
Sorts and merges many releases into the merged release. This method is used to extend the merged release with additional releases.

### Method
Method

### Parameters
- **releases** (list[dict[str, Any]]) - Required - The list of releases to merge.

### Returns
None
```

--------------------------------

### Merger.create_compiled_release

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Merges a list of releases into a compiled release.

```APIDOC
## Merger.create_compiled_release

### Description
Merges a list of releases into a compiled release. This method is used to combine multiple releases into a single compiled release.

### Method
Method

### Parameters
- **releases** (list[dict[str, Any]]) - Required - The list of releases to merge.

### Returns
dict[str, Any] - The compiled release as a dictionary.
```

--------------------------------

### get_release_schema_url(tag)

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Returns the URL of the release schema for a given OCDS version tag.

```APIDOC
## get_release_schema_url(tag)

### Description
Return the URL of the release schema in the given version of OCDS.

### Method
N/A (Python function)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **tag** (str) - Required - The OCDS version tag (e.g., "1.1").

### Return Type
str

### Return Example
"https://standard.open-contracting.org/1.1/en/release-schema.json"
```

--------------------------------

### Patch schema using extensions from record package metadata

Source: https://ocds-merge.readthedocs.io/en/latest/create-merged-releases.html

Patches the schema using the extensions list from a record package's metadata. Use this when you have a record package and want to add merged releases to each record.

```python
import json

from ocdsextensionregistry import ProfileBuilder

with open('package.json') as f:
    package = json.load(f)

extensions = package.get('extensions', [])

builder = ProfileBuilder('1__1__4', extensions)
patched_schema = builder.patched_release_schema()
```

--------------------------------

### MergedRelease.append

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Merges one release into the merged release.

```APIDOC
## MergedRelease.append

### Description
Merges one release into the merged release. This method is used to add a single release to the merged release.

### Method
Method

### Parameters
- **release** (dict[str, Any]) - Required - The release to merge.

### Returns
None
```

--------------------------------

### OCDS Merge exceptions and warnings module source

Source: https://ocds-merge.readthedocs.io/en/latest/_modules/ocdsmerge/exceptions.html

Defines the exception and warning classes for the ocdsmerge package. Includes base classes OCDSMergeError and OCDSMergeWarning, with specific subclasses for common data issues. The MissingDateKeyError class stores the key and message, overriding __str__ to return the message.

```python
[docs]
class OCDSMergeError(Exception):
    """Base class for exceptions from within this package."""






[docs]
class MissingDateKeyError(OCDSMergeError, KeyError):
    """Raised when a release is missing a 'date' key."""

    def __init__(self, key: str, message: str):
        self.key = key
        self.message = message

    def __str__(self) -> str:
        return str(self.message)






[docs]
class NonObjectReleaseError(OCDSMergeError, TypeError):
    """Raised when a release is not an object."""






[docs]
class NullDateValueError(OCDSMergeError, TypeError):
    """Raised when a release has a null 'date' value."""






[docs]
class NonStringDateValueError(OCDSMergeError, TypeError):
    """Raised when a release has a non-string 'date' value."""






[docs]
class InconsistentTypeError(OCDSMergeError, TypeError):
    """Raised when a path is a literal, an object, and/or an array in different releases."""






[docs]
class OCDSMergeWarning(UserWarning):
    """Base class for warnings from within this package."""






[docs]
class DuplicateIdValueWarning(OCDSMergeWarning):
    """Used when at least two objects in the same array have the same value for the 'id' field."""


```

--------------------------------

### CompiledRelease.flat_append

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Appends a flat release to the compiled release.

```APIDOC
## CompiledRelease.flat_append

### Description
Appends a flat release to the compiled release. This method is used internally for merging flat releases.

### Method
Method

### Parameters
- **flat** (dict[tuple[int | str, ...], Any]) - Required - The flat release data.
- **ocid** (str | None) - Optional - The OCID.
- **release_id** (str | None) - Optional - The release ID.
- **date** (str | None) - Optional - The release date.
- **tag** (str | None) - Optional - The release tag.

### Returns
None
```

--------------------------------

### VersionedRelease.flat_append method

Source: https://ocds-merge.readthedocs.io/en/latest/_modules/ocdsmerge/merge.html

Overrides flat_append to remove the 'ocid' from the flat dictionary, set it directly, and for each key-value pair, if the key is not versioned or the value is unchanged, it skips; otherwise, it appends a versioned entry with releaseID, releaseDate, releaseTag, and value.

```python
    def flat_append(
        self,
        flat: Flattened,
        ocid: str | None,
        release_id: str | None,
        date: str | None,
        tag: str | None,
    ) -> None:
        # Don't version the OCID.
        flat.pop(("ocid",), None)
        self.data[("ocid",)] = ocid

        for key, value in flat.items():
            # If key is not versioned, continue. If the value is unchanged, don't add it to the history.
            if key in self.data and (type(self.data[key]) is not list or value == self.data[key][-1]["value"]):
                continue

            self.data.setdefault(key, []).append(
                {
                    "releaseID": release_id,
                    "releaseDate": date,
                    "releaseTag": tag,
                    "value": value,
                }
            )
```

--------------------------------

### NullDateValueError

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Exception raised when a release has a null 'date' value.

```APIDOC
## NullDateValueError

### Description
Raised when a release has a null 'date' value.

### Method
N/A (Python exception)

### Endpoint
N/A

### Parameters
None

### Inherits From
OCDSMergeError
```

--------------------------------

### class ocdsmerge.flatten.MergeStrategy

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Defines merge strategy constants for flattening operations.

```APIDOC
## class ocdsmerge.flatten.MergeStrategy

### Description
Defines merge strategy constants for flattening operations.

### Attributes
- **APPEND** (int) - Value 1. Append strategy.
- **MERGE_BY_POSITION** (int) - Value 2. Merge by position strategy.
```

--------------------------------

### OCDSMergeError

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Base exception class for all errors raised by the OCDS Merge package.

```APIDOC
## OCDSMergeError

### Description
Base class for exceptions from within this package.

### Method
N/A (Python exception)

### Endpoint
N/A

### Parameters
None

### Inherits From
Exception
```

--------------------------------

### MergedRelease.flat_append method

Source: https://ocds-merge.readthedocs.io/en/latest/_modules/ocdsmerge/merge.html

Adds an 'id' and 'date' to the flattened data, sets the 'ocid' field, and updates with the provided flat dictionary. Note that in OCDS 1.0, 'ocid' incorrectly sets 'mergeStrategy': 'ocdsOmit'.

```python
    def flat_append(
        self,
        flat: Flattened,
        ocid: str | None,
        release_id: str | None,  # noqa: ARG002
        date: str | None,
        tag: str | None,  # noqa: ARG002
    ) -> None:
        # Add an `id` and `date`.
        self.data[("id",)] = f"{ocid}-{date}"
        self.data[("date",)] = date
        # In OCDS 1.0, `ocid` incorrectly sets "mergeStrategy": "ocdsOmit".
        self.data[("ocid",)] = ocid

        self.data.update(flat)
```

--------------------------------

### ocdsmerge.rules.get_merge_rules

Source: https://ocds-merge.readthedocs.io/en/latest/api/index.html

Returns merge rules as key-value pairs, where the key is a JSON path tuple and the value is the merge rule string.

```APIDOC
## ocdsmerge.rules.get_merge_rules

### Description
Returns merge rules as key-value pairs, where the key is a JSON path tuple and the value is the merge rule string.

### Parameters
- **schema** (str | dict[str, Any] | None) - Optional - The schema to get merge rules for.

### Return Type
dict[tuple[str, ...], str]
```
Tokens:
Raw