pandas 3.0.5: merge, array, NA

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pandas.merge in pkg:pypi/pandas@3.0.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/pandas@3.0.5
Demonstrate these symbols/APIs:
  - pandas.merge
Required runtime conditions:
  - ecosystem: golang
  - language: go
  - packageManager: go@1.26.5
  - runtime: go@1.26.5

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:c01f2fb6a51dd5b611b5297b13e5cd2a1c64dd92976c09e3b133b37d990387ae","contract":["An outer top-level pandas.merge matches one missing Int64 key across both sides and reports three both, two left_only, and one right_only rows.","validate='one_to_one' raises pandas.errors.MergeError when an ordinary left join key is duplicated.","left_anti returns only keys 1 and 4 while right_anti returns only key 2, excluding the missing key because pandas treats it as matched."],"goal":"verify pandas.merge in pkg:pypi/pandas@3.0.5","kind":"HOW","packages":["pkg:pypi/pandas@3.0.5"],"schemaVersion":1,"symbols":["pandas.merge","pandas.array","pandas.NA","pandas.errors.MergeError"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","languageVersion":"3.14","libc":"musl","os":"linux","packageManager":"pip","runtime":"python","runtimeVersion":"3.14","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/pandas@3.0.5"],"schemaVersion":1,"symbols":["pandas.merge","pandas.array","pandas.NA","pandas.errors.MergeError"],"verifierAdapter":"python@1"}

numpy==2.5.2
pandas==3.0.5
python-dateutil==2.9.0.post0
six==1.17.0

numpy==2.5.2
pandas==3.0.5
python-dateutil==2.9.0.post0
six==1.17.0

{
  "schemaVersion": 1,
  "goal": "verify pandas.merge in pkg:pypi/pandas@3.0.5",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/pandas@3.0.5"
  ],
  "symbols": [
    "pandas.merge"
  ],
  "runtimeConditions": {
    "ecosystem": "golang",
    "language": "go",
    "packageManager": "go@1.26.5",
    "runtime": "go@1.26.5"
  }
}

import pandas as pd


def assert_merge_error(callback) -> None:
    try:
        callback()
    except pd.errors.MergeError:
        return
    raise AssertionError("expected pandas.errors.MergeError")


def make_frames() -> tuple[pd.DataFrame, pd.DataFrame]:
    left = pd.DataFrame(
        {
            "key": pd.array([1, None, 3, 3, 4], dtype="Int64"),
            "left_value": ["one", "missing", "three-a", "three-b", "four"],
        }
    )
    right = pd.DataFrame(
        {
            "key": pd.array([None, 2, 3], dtype="Int64"),
            "right_value": ["missing", "two", "three"],
        }
    )
    return left, right


def test_outer_merge_and_validation() -> None:
    left, right = make_frames()
    merged = pd.merge(
        left,
        right,
        on="key",
        how="outer",
        indicator=True,
        validate="many_to_many",
    )

    counts = merged["_merge"].astype("string").value_counts().to_dict()
    assert counts == {"both": 3, "left_only": 2, "right_only": 1}, counts

    missing = merged.loc[merged["key"].isna()]
    assert len(missing) == 1
    assert missing.iloc[0]["left_value"] == "missing"
    assert missing.iloc[0]["right_value"] == "missing"
    assert missing.iloc[0]["_merge"] == "both"

    assert_merge_error(
        lambda: pd.merge(left, right, on="key", validate="one_to_one")
    )


def test_anti_joins_treat_missing_keys_as_matches() -> None:
    left, right = make_frames()
    left_unique = left.drop_duplicates("key", keep="first")

    left_anti = pd.merge(left_unique, right, on="key", how="left_anti")
    right_anti = pd.merge(left_unique, right, on="key", how="right_anti")

    assert sorted(left_anti["key"].astype("int64").tolist()) == [1, 4]
    assert right_anti["key"].astype("int64").tolist() == [2]
    assert not left_anti["key"].isna().any()
    assert not right_anti["key"].isna().any()


if __name__ == "__main__":
    test_outer_merge_and_validation()
    test_anti_joins_treat_missing_keys_as_matches()
    print("pandas 3.0.5 top-level merge contract passed")