numpy 2.5.2: Prevent silent numeric narrowing with NumPy 2.5.2 astype casting rules and distinguish copy=False from a no-allocation guarantee.

# NumPy `astype` casting contract

`search_known_solution` returned `NO_SAFE_MATCH` for NumPy 2.5.2 and this
exact casting contract. The sample therefore proves the behavior directly.

The important distinction is between dtype-level and value-level safety.
`same_kind` allows narrowing within the integer kind, `safe` rejects the
dtype relationship categorically, and `same_value` inspects whether this
particular conversion changes any value. The contract also demonstrates that
`astype(copy=False)` may allocate when conversion is required.

{"case":{"believed":"casting='same_kind' prevents integer overflow during narrowing, while astype(copy=False) refuses any conversion that must allocate a new array.","caseId":"case:sha256:cf19be07a80e680fb5da3e1983e5fccd93a6304b5176a2a064ffcf61bea84ede","contract":["astype(casting='same_kind') accepts int64-to-int8 narrowing and wraps out-of-range values instead of checking them.","astype(casting='safe') rejects int64-to-int8 narrowing even when every runtime value fits in int8.","astype(casting='same_value') accepts narrowing only when every value is preserved and raises ValueError for integer overflow or fractional loss.","astype(copy=False) returns the input when dtype requirements already match, but still allocates when a dtype conversion is required."],"goal":"Prevent silent numeric narrowing with NumPy 2.5.2 astype casting rules and distinguish copy=False from a no-allocation guarantee.","kind":"HOW","packages":["pkg:pypi/numpy@2.5.2"],"schemaVersion":1,"symbols":["numpy.array","numpy.array_equal","numpy.ndarray.astype","numpy.shares_memory"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","runtimeVersion":"3.12","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/numpy@2.5.2"],"schemaVersion":1,"symbols":["numpy.array","numpy.array_equal","numpy.ndarray.astype","numpy.shares_memory"],"verifierAdapter":"python@1"}

numpy==2.5.2

# This file was autogenerated by uv via the following command:
#    uv pip compile requirements.in --output-file requirements.txt --generate-hashes --python-version 3.12
numpy==2.5.2 \
    --hash=sha256:0090ccdd57ec2703e9b49d0bf554767370581c1dd0a6b2bb2b2d9def317d042a \
    --hash=sha256:078f9b027b478c9379b9677babbf0f8b8f1ecfada27636d7b9a93990c638739f \
    --hash=sha256:07d4e89f3a9ab0a9ba24264ccdb642b3dd951b2281e8883a5481a4aa79cc31a7 \
    --hash=sha256:0a4035ae1129ff8777f08bfbd44f1e5d8e9c049ce0c2dd78fc0d92c13e7251c0 \
    --hash=sha256:0aadf13b60048d501e05fa699efaf7734e2494f3498a4c2a5521d822640324f3 \
    --hash=sha256:14e373cfc6387177e8409dac3c7159be8eb05cd77096cd7c950268b86f62831c \
    --hash=sha256:1ab3d4a901f844ea836c3e80bf463c6a27d7f3c14e8e292fcf28d348b25b9bce \
    --hash=sha256:24b9dc2e3d84aa58523798805194e23e736f3f6ce2d1a5b92583ae734e6dbda8 \
    --hash=sha256:27650bb0e7140fa3d37b9923b4803645e0b125d190f326eecfd3f4dad8e8ade1 \
    --hash=sha256:28ac63476ec7651484215ee7fa15a1f78b57c14621f01e392afe17b9a1390ce4 \
    --hash=sha256:29b86ff8a6cc556b47ec6b64b194815cc80e6bf5eedcc6cddfd65318cb0b4eee \
    --hash=sha256:29d81e97f668489cba8ebfd796b9bdd453525d35dd9e162e2daec94bf3fc7740 \
    --hash=sha256:2cc779226e476d1e1f08c74068c419e60f41a9e0e069c92f6671d31d5c985e98 \
    --hash=sha256:2ffa7bacab3e2ee1b19ed31766bb60bb380b68c23f051e199c5cc598afd68710 \
    --hash=sha256:318b9a4c845dbea06708a29c84ee429cc3065048db34cdb799047643492050ee \
    --hash=sha256:34c319e2963be042673fb46570501b2f06c41924e17e3563d58646b4380dfb68 \
    --hash=sha256:3a2f061cebd9e3d23bdcfaaded5e2293a4c6a5b60fa42df85d410a725ce621bf \
    --hash=sha256:3cdec01fa790a186d430433fdd4d4ffb70eed6f0eeb4bf05c8dbe2dce0a9bcb8 \
    --hash=sha256:3e4c367352d3747784248a227fbec218e193b56f7e6692e3b64fc805478ecfdf \
    --hash=sha256:40f4d451aed46a8046a1aae41c4e55fb3612273df9c502480135e1501576a34b \
    --hash=sha256:44ef9675d908e65f9953063837c3277730f3f4437615a4cdab67b366cabaf884 \
    --hash=sha256:4bbd96c833ecc8cc069ce518078fc8c60cb9cbfb0fea5b7a803ad65035596d03 \
    --hash=sha256:4ec954036759bcee3aa484f8603bd9c14f3e776293b85578b8734c2d72777c69 \
    --hash=sha256:4f9744f9fbdcea0bc552e8f19e1f141f811a3f9bc2be2cc6e86d982cab23e3f4 \
    --hash=sha256:50a68f4bacd8a2b33d8da3d2269d0d78500f86ea582e4786dc10f5ef2c2c6842 \
    --hash=sha256:50e500dc868e9313530ce12ba470fe50ff3afe3d62993ed6eff652dacd555b65 \
    --hash=sha256:52c808f96484f5571a5cc863775ce50247c17dfb3b0361f8ed6b4b0456f80080 \
    --hash=sha256:5f8e00be2ec6f45f4e8a41a527f68d44a7d96fee92a650e4d8b1326f77f61e6e \
    --hash=sha256:60e902ac295855348a5ca2ea4c89108989a9f5fddfad3dfc0a8f36b10358567e \
    --hash=sha256:65f188481f1669e26f62b701e8205d19e460fa4a9b52a1414ba382330e4a3414 \
    --hash=sha256:6950c4b7dd562453090548ba7f5da7e59f57f85663f15d5dcc60e249192f7e59 \
    --hash=sha256:6a9bb119fb8dd21ba30b3f0e555b7e2b081bd9883af21ec9c1c633d161cda3a8 \
    --hash=sha256:6b588cc8f902d6bff201c19fd00c43ab8545671e3554d014e12e14139e5e8617 \
    --hash=sha256:6df895598c0edcb41030126c89e0f353b07d93238116143b7405e937359736c4 \
    --hash=sha256:6e8172ddfcf5cf74b811d372b570b83c60bd2de87a6fbfbebdadb4a9bd9c6cbb \
    --hash=sha256:7354826bc6f8f69402e9b7fe28d15fcd34feebd74f856f111585c5b0c9fb0251 \
    --hash=sha256:7587f53dfbd5edc0f7b87c6217b4c6d2d1f2ef9c3da70bc1315e7db5f8d7ec9d \
    --hash=sha256:77843ca236b777e67f8d6b3660ea116e499612703a0ecd7093f316201eb9d8e2 \
    --hash=sha256:7999d4ddb0c4025018373fd787510d46e04c769467af22869707b3c1cfd459ab \
    --hash=sha256:85aaccb24182c25df891ad0ec333585967e115269d5f1b17f2c9ae005bc96657 \
    --hash=sha256:8e4cb9a754c8a0c62eaa88273a5fba3391f4a610d1dee893c0755da31c083f15 \
    --hash=sha256:8ee9c4eeb8454b3660a8b53493563c3e121c2fc94fbd72b848ef814ed7b676a9 \
    --hash=sha256:9a0731745a72a184490a582fb4af2533512bd071ace67785b5fdffc0ae58dce8 \
    --hash=sha256:9e9413326d726c2545bfa65d2c0876871e8d8386e77f992c1d426e180bbd4323 \
    --hash=sha256:a610dc7e3c52edd39c2bc2375ff9c3fd59cb3ad00e4472d36f83bc1457145788 \
    --hash=sha256:a839318485284a6fb31be4f8f2c91c8f2cb22f4543c4a8903f12b0671ffe07cc \
    --hash=sha256:afb3f0632d6b2e3ba04dbce8d1e48d321b369138b73830b5ca371a0e8d479d56 \
    --hash=sha256:b879fb674276e331513fb136b78dbc6bd3c848309e0d841cfd63be3896c4cfc1 \
    --hash=sha256:b9727f472d2f3888053b8a75ab0cb94745a9de224bb5846dbadc0092101bc71d \
    --hash=sha256:ba0a474801b8dc67b66bf465548abc90e82b44d2611b5770f33008dcabffe8ec \
    --hash=sha256:bd68ece1553d2023c09a4226d9e41c586ad2d20594d1a456186c33513d2cb3f2 \
    --hash=sha256:c081cbe16ba1ab53078e5ff29013621e33c509eedab055775d956427712c236e \
    --hash=sha256:c1f017dc0875c9209d219f97feceb7d54c2661bb243deb4114478e1295808af7 \
    --hash=sha256:cebc2d6dbb605a7703d59751dea4bd6b0ab127a5a4338a6f432df1936fef8b26 \
    --hash=sha256:cf7de32f486e4ac9e2d93b810f9e9ac72a728dd46a32a0bb403222f27f653514 \
    --hash=sha256:d482d171c406ae88c5b19cad3b6a1c4c5209f886ab74bc44c2c865c23f52d860 \
    --hash=sha256:d6a48072864e3324e194a8fbb3c657bcc5b5c869dbc64c9537b1d5c862572c0a \
    --hash=sha256:d787cf769c3baeb5f6235e778edb52c08dfa923789b5958f28e6450f96107cb1 \
    --hash=sha256:dc649493697006bc90614a5f0bbc8cb3cb1866715c474e473694968d7e6b99ab \
    --hash=sha256:ddf47472af2e4280d79bac82304f5e80150211f1b9e614b760061d5fdfbb6eba \
    --hash=sha256:e5651f3f87add730ee6608d915009e19c911fba0cb000c7e3ea994b7d768eb12 \
    --hash=sha256:e79aba74ffaf5f78a050d777c184cddf8fdffabab38acf5f3ef1fecbc17895d6 \
    --hash=sha256:eaa088384c46f519dacb93b7ec483a6d6b19a4a2085ae4f25ab9b1c43d387d1e \
    --hash=sha256:eaca7ff36f0f52e2111ec71f169d8fd3e889e7ddc0d2592e0d703fd8d3ce8fac \
    --hash=sha256:f06571a052127dc1b4e8b83029b4d1b20daa2b64a31cdd181fc6bc774e9000eb \
    --hash=sha256:fd0d703772bba096843785bd38371e31bb4a0c1151497ad5739d182114a73f7f
    # via -r requirements.in

from importlib.metadata import version

import numpy as np


def expect_exception(exception_type, callback):
    try:
        callback()
    except exception_type as error:
        return error
    raise AssertionError(f"expected {exception_type.__name__}")


assert version("numpy") == "2.5.2"
assert np.__version__ == "2.5.2"

# ``same_kind`` compares dtype categories, not the values being converted.
# Narrowing signed integers therefore succeeds even when values overflow.
out_of_range = np.array([-129, 128, 256], dtype=np.int64)
wrapped = out_of_range.astype(np.int8, casting="same_kind")
assert wrapped.dtype == np.dtype(np.int8)
assert np.array_equal(wrapped, np.array([127, -128, 0], dtype=np.int8))

# ``safe`` makes a decision from the source and destination dtypes. It rejects
# int64 -> int8 even when every value would fit exactly.
in_range = np.array([-128, -1, 0, 127], dtype=np.int64)
expect_exception(
    TypeError,
    lambda: in_range.astype(np.int8, casting="safe"),
)

# ``same_value`` checks the actual values. It permits a narrower dtype when all
# values survive unchanged, and rejects both integer overflow and float loss.
narrowed = in_range.astype(np.int8, casting="same_value", copy=False)
assert narrowed.dtype == np.dtype(np.int8)
assert np.array_equal(narrowed.astype(np.int64), in_range)
assert not np.shares_memory(narrowed, in_range)

expect_exception(
    ValueError,
    lambda: out_of_range.astype(np.int8, casting="same_value"),
)
expect_exception(
    ValueError,
    lambda: np.array([1.0, 2.5]).astype(np.int64, casting="same_value"),
)

integral_floats = np.array([-2.0, 0.0, 3.0], dtype=np.float64)
exact_integers = integral_floats.astype(np.int64, casting="same_value")
assert np.array_equal(exact_integers, np.array([-2, 0, 3], dtype=np.int64))

# For astype, copy=False is an optimization rather than a hard no-allocation
# guarantee: an unchanged dtype returns the input, while conversion allocates.
same = in_range.astype(np.int64, casting="same_value", copy=False)
assert same is in_range
assert np.shares_memory(same, in_range)
assert narrowed is not in_range

print("numpy astype casting contract passed")