feat(python): Add read_clipboard and DataFrame.write_clipboard (#…

…15272)

Cargo.toml

@@ -85,6 +85,7 @@ version_check = "0.9.4"
 xxhash-rust = { version = "0.8.6", features = ["xxh3"] }
 zstd = "0.13"
 uuid = { version = "1.7.0", features = ["v4"] }
+arboard = { version = "3.3.2", default-features = false }
 
 polars = { version = "0.38.3", path = "crates/polars", default-features = false }
 polars-compute = { version = "0.38.3", path = "crates/polars-compute", default-features = false }

py-polars/Cargo.toml

@@ -17,6 +17,7 @@ polars-plan = { workspace = true }
 polars-utils = { workspace = true }
 
 ahash = { workspace = true }
+arboard = { workspace = true, optional = true }
 ciborium = { workspace = true }
 either = { workspace = true }
 itoa = { workspace = true }
@@ -126,6 +127,7 @@ search_sorted = ["polars/search_sorted"]
 decompress = ["polars/decompress-fast"]
 regex = ["polars/regex"]
 csv = ["polars/csv"]
+clipboard = ["arboard"]
 object = ["polars/object"]
 extract_jsonpath = ["polars/extract_jsonpath"]
 pivot = ["polars/pivot"]
@@ -204,6 +206,7 @@ io = [
   "avro",
   "csv",
   "cloud",
+  "clipboard",
 ]
 
 optimizations = [

py-polars/docs/source/reference/io.rst

@@ -11,6 +11,14 @@ Avro
    read_avro
    DataFrame.write_avro
 
+Clipboard
+~~~~~~~~~
+.. autosummary::
+   :toctree: api/
+
+   read_clipboard
+   DataFrame.write_clipboard
+
 CSV
 ~~~
 .. autosummary::

py-polars/polars/__init__.py

@@ -180,6 +180,7 @@
 )
 from polars.io import (
     read_avro,
+    read_clipboard,
     read_csv,
     read_csv_batched,
     read_database,
@@ -316,6 +317,7 @@
     "scan_ndjson",
     "scan_parquet",
     "scan_pyarrow_dataset",
+    "read_clipboard",
     # polars.stringcache
     "StringCache",
     "disable_string_cache",

py-polars/polars/dataframe/frame.py

@@ -118,6 +118,7 @@
 with contextlib.suppress(ImportError):  # Module not available when building docs
     from polars.polars import PyDataFrame
     from polars.polars import dtype_str_repr as _dtype_str_repr
+    from polars.polars import write_clipboard_string as _write_clipboard_string
 
 if TYPE_CHECKING:
     import sys
@@ -2595,6 +2596,27 @@ def write_csv(
 
         return None
 
+    def write_clipboard(self, *, separator: str = "\t", **kwargs: Any) -> None:
+        """
+        Copy `DataFrame` in csv format to the system clipboard with `write_csv`.
+
+        Useful for pasting into Excel or other similar spreadsheet software.
+
+        Parameters
+        ----------
+        separator
+            Separate CSV fields with this symbol.
+        kwargs
+            Additional arguments to pass to `write_csv`.
+
+        See Also
+        --------
+        polars.read_clipboard: Read a DataFrame from the clipboard.
+        write_csv: Write to comma-separated values (CSV) file.
+        """
+        result: str = self.write_csv(file=None, separator=separator, **kwargs)
+        _write_clipboard_string(result)
+
     def write_avro(
         self,
         file: str | Path | IO[bytes],

py-polars/polars/io/__init__.py

@@ -1,6 +1,7 @@
 """Functions for reading data."""
 
 from polars.io.avro import read_avro
+from polars.io.clipboard import read_clipboard
 from polars.io.csv import read_csv, read_csv_batched, scan_csv
 from polars.io.database import read_database, read_database_uri
 from polars.io.delta import read_delta, scan_delta
@@ -35,4 +36,5 @@
     "scan_ndjson",
     "scan_parquet",
     "scan_pyarrow_dataset",
+    "read_clipboard",
 ]

py-polars/polars/io/clipboard.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import contextlib
+from io import StringIO
+from typing import TYPE_CHECKING, Any
+
+from polars.io.csv.functions import read_csv
+
+with contextlib.suppress(ImportError):
+    from polars.polars import read_clipboard_string as _read_clipboard_string
+
+if TYPE_CHECKING:
+    from polars import DataFrame
+
+
+def read_clipboard(separator: str = "\t", **kwargs: Any) -> DataFrame:
+    """
+    Read text from clipboard and pass to `read_csv`.
+
+    Useful for reading data copied from Excel or other similar spreadsheet software.
+
+    Parameters
+    ----------
+    separator
+        Single byte character to use as separator parsing csv from clipboard.
+    kwargs
+        Additional arguments passed to `read_csv`.
+
+    See Also
+    --------
+    read_csv : Read a csv file into a DataFrame.
+    DataFrame.write_clipboard : Write a DataFrame to the clipboard.
+    """
+    csv_string: str = _read_clipboard_string()
+    io_string = StringIO(csv_string)
+    return read_csv(source=io_string, separator=separator, **kwargs)

py-polars/src/functions/io.rs

@@ -56,3 +56,27 @@ fn fields_to_pydict(fields: &Vec<Field>, dict: &PyDict, py: Python) -> PyResult<
     }
     Ok(())
 }
+
+#[cfg(feature = "clipboard")]
+#[pyfunction]
+pub fn read_clipboard_string() -> PyResult<String> {
+    use arboard;
+    let mut clipboard =
+        arboard::Clipboard::new().map_err(|e| PyPolarsErr::Other(format!("{e}")))?;
+    let result = clipboard
+        .get_text()
+        .map_err(|e| PyPolarsErr::Other(format!("{e}")))?;
+    Ok(result)
+}
+
+#[cfg(feature = "clipboard")]
+#[pyfunction]
+pub fn write_clipboard_string(s: &str) -> PyResult<()> {
+    use arboard;
+    let mut clipboard =
+        arboard::Clipboard::new().map_err(|e| PyPolarsErr::Other(format!("{e}")))?;
+    clipboard
+        .set_text(s)
+        .map_err(|e| PyPolarsErr::Other(format!("{e}")))?;
+    Ok(())
+}

py-polars/src/lib.rs

@@ -217,6 +217,12 @@ fn polars(py: Python, m: &PyModule) -> PyResult<()> {
     #[cfg(feature = "parquet")]
     m.add_wrapped(wrap_pyfunction!(functions::read_parquet_schema))
         .unwrap();
+    #[cfg(feature = "clipboard")]
+    m.add_wrapped(wrap_pyfunction!(functions::read_clipboard_string))
+        .unwrap();
+    #[cfg(feature = "clipboard")]
+    m.add_wrapped(wrap_pyfunction!(functions::write_clipboard_string))
+        .unwrap();
 
     // Functions - meta
     m.add_wrapped(wrap_pyfunction!(functions::get_index_type))