Complete the filesystem parity checklist: pipe_file, version-aware mode, and fsspec registry DX

[laughingman7743]

WHAT

Completes the remaining items of the filesystem parity checklist in #722, designed around PyAthena's architecture (typed model classes, sync boto3 client with executor-based parallelism):

Direct-write pipe_file

• Data up to the block size is written with a single PutObject request (the checklist item); larger data and writes inside an fsspec transaction go through the buffered open() path, so the multipart upload orchestration keeps a single owner (S3File) and transactions keep their deferred-commit semantics.
• Preserves the previous behaviors of the inherited path: the filesystem-level and per-call s3_additional_kwargs, the open()-style block_size / max_worker kwargs, and bytes-like values. Supports fsspec's mode="create".
• Extracts _finish_multipart_upload — the complete-or-abort protocol shared by S3File.commit and _copy_object_with_multipart_upload, which now cancel remaining parts and abort the upload on failure instead of leaking incomplete uploads (abort failures are logged without masking the original error).
• Fixes a latent S3File._get_ranges bug that generated an empty trailing range when the size is an exact multiple of the block size (affected the concurrent read path too), and adds mode to AioS3FileSystem._pipe_file to match the fsspec signature.

Version-aware mode and object version listing

• version_aware=False constructor flag on both filesystems: when enabled, reads pin the object version observed at open/head time, and ls(path, versions=True) lists all versions of a prefix.
• object_version_info(path, delete_markers=False) lists the versions of the objects under a path as typed S3ObjectVersion instances (paginated ListObjectVersions).
• Adds s3:GetObjectVersion / s3:ListBucketVersions to the CI OIDC role (CloudFormation stack deployed).

fsspec registry DX (raised in #719)

• Registration goes through the new pyathena.filesystem.register_s3_filesystem, which registers PyAthena's filesystem class in the live fsspec registry and logs a warning when it overwrites an explicitly registered implementation (previously the shadowing was completely silent — pyathena s3 fsspec replacement file system not writing when used with transactions & a context manager #719). The docstring documents how to restore s3fs by re-registering it afterwards.

Async streaming reads (verification item)

Verified rather than changed: AioS3File dispatches parallel range reads through S3AioExecutor on the event loop and is covered by the existing async read tests. fsspec's open_async / AbstractAsyncStreamedFile protocol is intentionally not implemented — the executor-based model is the supported async read path.

Testing (following the minimize-mocking policy): real-S3 integration tests for the pipe round-trips (incl. a 6 MiB multipart case), mode="create" + ContentType, transaction commit/rollback, object version listing (an unversioned bucket reports the null version), and version-aware reads; mocked tests only for request shapes and failure injection (part splitting, abort-on-failure, error masking, pagination); pure-logic unit tests for S3ObjectVersion and the registry helper. just lint passes; changed-area tests pass against real AWS.

WHY

Closes #722. Together with #729 (directory operations, metadata/tags/ACL, multipart-upload management, error translation, S3File helpers), this completes the umbrella issue: users migrating from s3fs get the remaining API surface, and the registry no longer silently shadows an explicitly chosen implementation. The optional bucket-versioning helpers (make_bucket_versioned, etc.) are intentionally not implemented, consistent with the bucket-lifecycle design decision in #729 (infrastructure-level changes are out of scope for the filesystem; versioning configuration belongs to infrastructure management).

🤖 Generated with Claude Code