[yayaha]

Rationale for this change

This PR is part 2 of 2. It depends on #4320. The first two commits are from #4320.

This PR adds Table.labels, the same as SupportsLabels in apache/iceberg#18046:

• The REST catalog sets Table.labels in load_table, create_table, and register_table. rename_table gets labels through load_table.
• Tables from other catalogs, staged tables from create_table_transaction, and tables built directly have empty labels.
• Labels are not table state, the same as in Java. Table.__eq__ ignores them. refresh() and commits keep the labels from the first load.
• View has no labels attribute. Java does not expose view labels either.

Difference from Java: a pickled table keeps its labels. Java does not serialize them.

table = catalog.load_table("db.events")
table.labels.object_labels  # {"owner": "team-a"}
for field in table.labels.fields:
    print(table.schema().find_column_name(field.field_id), field.labels)

Are these changes tested?

Yes. test_table_labels_from_rest_responses tests that load_table, create_table, and register_table set Table.labels. It also tests that a pickled table keeps its labels, __eq__ ignores labels, and refresh() keeps the first labels. test_labels_default_to_empty tests a table built without labels. I also loaded a tagged table from a Unity Catalog REST endpoint. Table.labels matched the labels JSON in the response.

Full unit suite: 4525 passed, 5 failed. The 5 failures are the same as in #4320.

Are there any user-facing changes?

Yes. Table has a new labels attribute and a new optional labels keyword argument. It is the last argument, so existing calls do not change. Please add the changelog label.

AI disclosure: This pull request and its description were written by Claude.

[laskoviymishka]

Thanks @yayaha.

With this, tables loaded from the REST catalog carry the catalog's labels, and the semantics follow Java's BaseTable: labels stay out of equality and survive refresh(). What's missing is a pickle test, since that's where we intentionally differ from Java.

I wrote the Java and Go sides of labels, so I'd like either @Fokko or @kevinjqliu to sign off on the new python side of Table API before this goes in.

[laskoviymishka]

Could this test also cover create_table and register_table? They hand labels to the same _response_to_table (create, register), but only load is exercised. Mocking the three responses and checking labels in a for loop here would do it, per AGENTS.md's preference for a loop over parametrize.

[yayaha]

Done in f1d11c0. The test now mocks load, create, and register, and it checks labels on all three tables. I renamed it to test_table_labels_from_rest_responses.

[laskoviymishka]

Could we pin the pickle behavior here? The description calls it the one difference from Java, where the field is private final transient, and no test under tests/ pickles a Table today.

Suggested change

	assert table.labels == expected
	assert table.labels == expected
	assert pickle.loads(pickle.dumps(table)).labels == expected

This also needs import pickle at the top of the file.

[yayaha]

Done in f1d11c0, with your suggestion and import pickle.

[Fokko]

Nice work! 🙌 The labels model is clean — the null/non-object handling matches Java's LabelsParser behavior, and the test coverage for create/register/pickle paths is exactly right. Thanks @yayaha!

[rambleraptor]

Late to the party on this one, but this looks great! Excited to get labels support out there.