DOC: to_markdown should not accept `str` for `buf` argument

[linceaerian]

Hello maintainer,

Is there's not an error in documentation for "to_markdown" function at:

pandas/pandas/core/frame.py

Line 2550 in 73c6825

buf: IO[str] | str | None = None,

The documentation indicate to be able to take a str in argument (Path), but when tested, it crash with:

pd.DataFrame(data).to_markdown(args.output_file, index=False)
  File "venv/lib/python3.6/site-packages/pandas/core/frame.py", line 2267, in to_markdown
    buf.writelines(result)
AttributeError: 'str' object has no attribute 'writelines'

In https://pandas.pydata.org/pandas-docs/version/1.0.1/reference/api/pandas.DataFrame.to_markdown.html
the documentation do not have mention of the "str" option.

Version of pandas: 1.1.5
Version of python: 3.6.9

That's all, have a nice day ;)

Regards

[mzeitlin11]

Thanks for reporting this @linceaerian, I see this on the latest docs too. I don't think there's ever a way to write to a string as a buffer (StringIO should be covered under IO[str]), so probably best to just remove that option from the docs and typing?

[twoertwein]

This should be working since pandas 1.2. In 1.2 get_handle is used to get a file-like object and then writelines is called on it:

pandas/pandas/core/frame.py

Line 2574 in 73c6825

handles.handle.writelines(result)

[twoertwein]

I think the type of buf currently too strict (IO[str] | str | None), it can be buf: FilePathOrBuffer[str] | None.

[mzeitlin11]

Ah, makes sense, thanks for explaining @twoertwein

[linceaerian]

Thanks @twoertwein @mzeitlin11, well i'll chose this issue then ;)