👌 return string if buf is set to None, use shared doc, change version introduced in to 1.0.0

Author: MarcoGorelli

pandas/core/frame.py

@@ -1966,31 +1966,30 @@ def to_feather(self, path):
 
         to_feather(self, path)
 
-    def to_markdown(
-        self,
-        buf: Optional[FilePathOrBuffer[str]] = None,
-        mode: Optional[str] = None,
-        **kwargs,
-    ) -> None:
+    @Appender(
         """
-        Print a DataFrame in Markdown-friendly format.
-
-        .. versionadded:: 1.0
-
-        Returns
-        -------
-        str
-            DataFrame in Markdown-friendly format.
-
         Examples
         --------
-        >>> df = pd.DataFrame(data={'col1': [1, 2], 'col2': [3, 4]})
+        >>> df = pd.DataFrame(
+        ...     data={"animal_1": ["elk", "pig"], "animal_2": ["dog", "quetzal"]}
+        ... )
         >>> print(df.to_markdown())
-        |    |   col1 |   col2 |
-        |---:|-------:|-------:|
-        |  0 |      1 |      3 |
-        |  1 |      2 |      4 |
+        |    | animal_1   | animal_2   |
+        |---:|:-----------|:-----------|
+        |  0 | elk        | dog        |
+        |  1 | pig        | quetzal    |
         """
+    )
+    @Substitution(klass="DataFrame")
+    @Appender(_shared_docs["to_markdown"])
+    def to_markdown(
+        self,
+        buf: Optional[FilePathOrBuffer[str]] = None,
+        mode: Optional[str] = None,
+        **kwargs,
+    ) -> Optional[str]:
+        kwargs.setdefault("headers", "keys")
+        kwargs.setdefault("tablefmt", "pipe")
         tabulate = import_optional_dependency("tabulate")
         result = tabulate.tabulate(self, **kwargs)
         if buf is None:

pandas/core/generic.py

@@ -2009,6 +2009,27 @@ def _repr_data_resource_(self):
     # ----------------------------------------------------------------------
     # I/O Methods
 
+    _shared_docs[
+        "to_markdown"
+    ] = """
+    Print %(klass)s in Markdown-friendly format.
+
+    .. versionadded:: 1.0.0
+
+    Parameters
+    ----------
+    buf : writable buffer, defaults to sys.stdout
+        Where to send the output. By default, the output is printed to
+        sys.stdout. Pass a writable buffer if you need to further process
+        the output.
+    mode : str, optional
+
+    Returns
+    -------
+    str
+        %(klass)s in Markdown-friendly format.
+    """
+
     _shared_docs[
         "to_excel"
     ] = """

pandas/core/series.py

@@ -8,6 +8,7 @@
 import warnings
 
 import numpy as np
+from pandas.core.generic import _shared_docs
 
 from pandas._config import get_option
 
@@ -1435,33 +1436,28 @@ def to_string(
                 with open(buf, "w") as f:
                     f.write(result)
 
-    def to_markdown(
-        self,
-        buf: Optional[FilePathOrBuffer[str]] = None,
-        mode: Optional[str] = None,
-        **kwargs,
-    ) -> str:
+    @Appender(
         """
-        Print a Series in Markdown-friendly format.
-
-        .. versionadded:: 1.0
-
-        Returns
-        -------
-        str
-            Series in Markdown-friendly format.
-
         Examples
         --------
-        >>> s = pd.Series([1, 2, 3, 4])
+        >>> s = pd.Series(["elk", "pig", "dog", "quetzal"], name="animal")
         >>> print(s.to_markdown())
-        |    |   0 |
-        |---:|----:|
-        |  0 |   1 |
-        |  1 |   2 |
-        |  2 |   3 |
-        |  3 |   4 |
+        |    | animal   |
+        |---:|:---------|
+        |  0 | elk      |
+        |  1 | pig      |
+        |  2 | dog      |
+        |  3 | quetzal  |
         """
+    )
+    @Substitution(klass="Series")
+    @Appender(_shared_docs["to_markdown"])
+    def to_markdown(
+        self,
+        buf: Optional[FilePathOrBuffer[str]] = None,
+        mode: Optional[str] = None,
+        **kwargs,
+    ) -> Optional[str]:
         return self.to_frame().to_markdown(buf, mode, **kwargs)
 
     # ----------------------------------------------------------------------

pandas/tests/io/formats/test_to_markdown.py

@@ -49,6 +49,7 @@ def test_series():
 
 def test_no_buf(capsys):
     df = pd.DataFrame([1, 2, 3])
-    df.to_markdown()
-    out, _ = capsys.readouterr()
-    assert out == "|    |   0 |\n|---:|----:|\n|  0 |   1 |\n|  1 |   2 |\n|  2 |   3 |"
+    result = df.to_markdown()
+    assert (
+        result == "|    |   0 |\n|---:|----:|\n|  0 |   1 |\n|  1 |   2 |\n|  2 |   3 |"
+    )