[python] Fix FileSystemBranchManager from-tag and fast-forward path computation

[TheR1sing3un]

Purpose

Fix a pre-existing bug in FileSystemBranchManager._copy_with_branch that made create_branch(tag_name=...) and fast_forward raise SameFileError: the SnapshotManager it produced still pointed at the main-branch snapshot directory, so copy_file(src, dst) collapsed to src == dst.

The fix mirrors Java SnapshotManager.copyWithBranch (paimon-core/.../utils/SnapshotManager.java:89-95): the Python SnapshotManager now carries an explicit branch field and a copy_with_branch(branch_name) factory, so its snapshot_dir / get_snapshot_path(...) resolve to {table_path}/branch/branch-{name}/snapshot/... for non-main branches. FileSystemBranchManager._copy_with_branch then dispatches to the per-manager factories (SnapshotManager.copy_with_branch / SchemaManager.copy_with_branch) instead of blindly reconstructing a main-branch SnapshotManager.

SnapshotLoader is rebranched in lockstep so REST-path catalog loads target the requested branch rather than falling back to the main-branch identifier (mirrors Java SnapshotLoaderImpl.copyWithBranch).

In scope

• pypaimon/snapshot/snapshot_manager.py: constructor accepts an optional branch argument (defaults to inheriting table.current_branch()); new branch field; branch-aware snapshot_dir / latest_file; new copy_with_branch(branch_name) factory that also rebranches the snapshot loader.
• pypaimon/snapshot/snapshot_loader.py: new copy_with_branch(branch) returning a loader whose Identifier carries the new branch (mirrors Java SnapshotLoaderImpl.copyWithBranch).
• pypaimon/branch/filesystem_branch_manager.py: _copy_with_branch dispatches to manager.copy_with_branch(branch) for SnapshotManager / SchemaManager (the latter already had the factory). TagManager is still rebuilt directly because the Python TagManager has no copy_with_branch factory yet.
• pypaimon/tests/branch_manager_test.py: two new test classes -- SnapshotManagerBranchAwarenessTest pins down the branch-aware path computation and the loader rebranching, and FileSystemBranchManagerEndToEndTest regresses both the from-tag happy path and the fast-forward happy path that previously raised SameFileError.
• pypaimon/tests/snapshot_manager_test.py: existing Mock() tables now explicitly set current_branch.return_value = "main", since the constructor now calls table.current_branch() for the default branch.

Out of scope

• Re-enabling the two from-tag / fast-forward happy-path tests skipped in [python] Implement branch CRUD on FileSystemCatalog #7755 (filesystem_catalog_branch_test.py). That file is only on the [python] Implement branch CRUD on FileSystemCatalog #7755 branch; once [python] Implement branch CRUD on FileSystemCatalog #7755 merges, the skipped tests can be re-enabled in a follow-up.
• Consolidating FileSystemBranchManager._normalize_branch with BranchManager.normalize_branch -- out of diff, separate cleanup.

Tests

From paimon-python/:

pytest pypaimon/tests/branch_manager_test.py -v             # 19 passed (14 existing + 5 new)
pytest pypaimon/tests/snapshot_manager_test.py -v           # 3 passed (mock fixture fix)
pytest pypaimon/tests/branch/ pypaimon/tests/rest/rest_branch_test.py \
       pypaimon/tests/api/test_branch_dto_serde.py \
       pypaimon/tests/filesystem_catalog_tag_test.py -q     # 87 passed
flake8 --config=dev/cfg.ini <touched files>                  # clean

The two new end-to-end tests in FileSystemBranchManagerEndToEndTest (test_create_branch_from_tag_lands_files_under_branch_dir and test_fast_forward_after_create_branch_from_tag) deterministically reproduce the SameFileError on master and pass on this branch. test_copy_with_branch_rebranches_snapshot_loader covers the new loader rebranching.

Anti-divergence checklist

• SnapshotManager.copy_with_branch matches Java SnapshotManager.copyWithBranch semantics: a fresh manager whose path accessors flow through BranchManager.branch_path(table_root, branch), plus a snapshot loader rebranched via SnapshotLoader.copy_with_branch(branch) when one is present.
• SnapshotLoader.copy_with_branch matches Java SnapshotLoaderImpl.copyWithBranch: same catalog_loader, new Identifier(database, object, branch).
• branch == "main" keeps existing paths bit-identical (branch_path(p, "main") == p), so all current SnapshotManager(table) call sites stay zero-regression.
• FileStoreTable.snapshot_manager() is unchanged; the new optional branch parameter defaults to table.current_branch() which is already the production behavior.

Generative AI disclosure

Drafted with assistance from a generative AI tool. All code, tests, and Java alignment were reviewed and validated by the contributor.

[JingsongLi]

+1