CLN/DOC: DataFrame.to_parquet supports file-like objects

[rhshadrach]

Adds documentation and type-hints for supporting file-like objects when engine == 'pyarrow'; relevant to #30081. Tests for this behavior currently exist in io.test_parquet.py:

@td.skip_if_no("pyarrow")
    def test_read_file_like_obj_support(self, df_compat):
        buffer = BytesIO()
        df_compat.to_parquet(buffer)
        df_from_buf = pd.read_parquet(buffer)
        tm.assert_frame_equal(df_compat, df_from_buf)

Perhaps the restrictions on the arguments when path is not a string:

• partition_cols must be None; and
• engine must end up being pyarrow

should be checked directly in DataFrame.to_parquet, but I'm leaving this out as that is an API change that could be made in a subsequent PR. The latter gives the clear error message TypeError: expected str, bytes or os.PathLike object, not _io.BytesIO but the former raises AttributeError: 'NoneType' object has no attribute '_isfilestore' which is slightly confusing.

Another API change that could be made subsequently is changing the path argument to path_or_buf, consistent with DataFrame.to_csv.

[jreback]

cc @TomAugspurger lgtm just typing

[jreback]

would take a separate PR for path -> path_or_buf (needs deprecation)

[TomAugspurger]

Thanks @rhshadrach.