implement stageOnly Commit

[yingjianwu98]

Rationale for this change

In java, snapshotProducer can create stageOnly snapshot meaning only the snapshot is created but the snapshot is not set to a ref.

This is a prerequisite to support wap.id in py-iceberg

Are these changes tested?

Yes, tests are added.

Are there any user-facing changes?

By default, it will stay with the current existing behavior.

[Fokko]

I think API wise, this makes more sense. In the case branch is None then we don't set the ref, if it is not None then we set the ref.

Suggested change

	branch: str = MAIN_BRANCH,
	stage_only: bool = False,
	branch: Optional[str] = MAIN_BRANCH

@kevinjqliu WDYT?

[kevinjqliu]

that make sense to me. Instead of setting stage_only=True, it would be branch=None

[yingjianwu98]

Make sense, thanks for taking a look!

[Fokko]

Looking at it a bit more, I think that's the way forward.

iceberg-python/pyiceberg/table/__init__.py

Lines 434 to 441 in 4b961f7

	def update_snapshot(self, snapshot_properties: Dict[str, str] = EMPTY_DICT, branch: Optional[str] = None) -> UpdateSnapshot:
	"""Create a new UpdateSnapshot to produce a new snapshot for the table.
	Returns:
	A new UpdateSnapshot
	"""
	if branch is None:
	branch = MAIN_BRANCH

We would change that into:

    def update_snapshot(self, snapshot_properties: Dict[str, str] = EMPTY_DICT, branch: Optional[str] = MAIN_BRANCH) -> UpdateSnapshot:
        """Create a new UpdateSnapshot to produce a new snapshot for the table.

        Returns:
            A new UpdateSnapshot
        """

There are a couple more places where we need to change the default to MAIN_BRANCH. Let me know what you think!

[yingjianwu98]

I think this makes sense.
I will take another deeper look to make sure it is backward compatible.

[Fokko]

@stevie9868 Thanks for resuming the work on this. I did a quick check over the changes, and it looks good to me. Could you resolve the conflicts? For some reason, the CI did not trigger.

[yingjianwu98]

@Fokko

Thanks for the quick review, and I have rebased my changes to resolve the conflicts.

[Fokko]

Left one minor comment, but apart from that, this looks good to me! 🙌 Thanks for working on this @stevie9868

[Fokko]

Thanks @stevie9868