polars-df 0.14.0-x86_64-darwin → 0.16.0-x86_64-darwin

data/LICENSE.txt

@@ -1,5 +1,6 @@
 Copyright (c) 2020 Ritchie Vink
 Copyright (c) 2022-2024 Andrew Kane
+Some portions Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -14,18 +14,17 @@ gem "polars-df"
 
 ## Getting Started
 
-This library follows the [Polars Python API](https://pola-rs.github.io/polars/py-polars/html/reference/index.html).
+This library follows the [Polars Python API](https://docs.pola.rs/api/python/stable/reference/index.html).
 
 ```ruby
-Polars.read_csv("iris.csv")
-  .lazy
+Polars.scan_csv("iris.csv")
   .filter(Polars.col("sepal_length") > 5)
   .group_by("species")
   .agg(Polars.all.sum)
   .collect
 ```
 
-You can follow [Polars tutorials](https://pola-rs.github.io/polars-book/user-guide/) and convert the code to Ruby in many cases. Feel free to open an issue if you run into problems.
+You can follow [Polars tutorials](https://docs.pola.rs/user-guide/getting-started/) and convert the code to Ruby in many cases. Feel free to open an issue if you run into problems.
 
 ## Reference
 
@@ -89,6 +88,15 @@ From Avro
 Polars.read_avro("file.avro")
 ```
 
+From Delta Lake (requires [deltalake-rb](https://github.com/ankane/delta-ruby)) [experimental, unreleased]
+
+```ruby
+Polars.read_delta("./table")
+
+# or lazily with
+Polars.scan_delta("./table")
+```
+
 From a hash
 
 ```ruby
@@ -337,6 +345,32 @@ Parquet
 df.write_parquet("file.parquet")
 ```
 
+JSON
+
+```ruby
+df.write_json("file.json")
+# or
+df.write_ndjson("file.ndjson")
+```
+
+Feather / Arrow IPC
+
+```ruby
+df.write_ipc("file.arrow")
+```
+
+Avro
+
+```ruby
+df.write_avro("file.avro")
+```
+
+Delta Lake [experimental, unreleased]
+
+```ruby
+df.write_delta("./table")
+```
+
 Numo array
 
 ```ruby

data/lib/polars/batched_csv_reader.rb

@@ -26,7 +26,6 @@ module Polars
       skip_rows_after_header: 0,
       row_count_name: nil,
       row_count_offset: 0,
-      sample_size: 1024,
       eol_char: "\n",
       new_columns: nil,
       raise_if_empty: true,
@@ -79,7 +78,6 @@ module Polars
         parse_dates,
         skip_rows_after_header,
         Utils.parse_row_index_args(row_count_name, row_count_offset),
-        sample_size,
         eol_char,
         raise_if_empty,
         truncate_ragged_lines,

data/lib/polars/binary_expr.rb

@@ -11,32 +11,112 @@ module Polars
 
     # Check if binaries in Series contain a binary substring.
     #
-    # @param lit [String]
+    # @param literal [String]
     #   The binary substring to look for
     #
     # @return [Expr]
-    def contains(lit)
-      Utils.wrap_expr(_rbexpr.binary_contains(lit))
+    #
+    # @example
+    #   colors = Polars::DataFrame.new(
+    #     {
+    #       "name" => ["black", "yellow", "blue"],
+    #       "code" => ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b],
+    #       "lit" => ["\x00".b, "\xff\x00".b, "\xff\xff".b]
+    #     }
+    #   )
+    #   colors.select(
+    #     "name",
+    #     Polars.col("code").bin.contains("\xff".b).alias("contains_with_lit"),
+    #     Polars.col("code").bin.contains(Polars.col("lit")).alias("contains_with_expr"),
+    #   )
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌────────┬───────────────────┬────────────────────┐
+    #   # │ name   ┆ contains_with_lit ┆ contains_with_expr │
+    #   # │ ---    ┆ ---               ┆ ---                │
+    #   # │ str    ┆ bool              ┆ bool               │
+    #   # ╞════════╪═══════════════════╪════════════════════╡
+    #   # │ black  ┆ false             ┆ true               │
+    #   # │ yellow ┆ true              ┆ true               │
+    #   # │ blue   ┆ true              ┆ false              │
+    #   # └────────┴───────────────────┴────────────────────┘
+    def contains(literal)
+      literal = Utils.parse_into_expression(literal, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.binary_contains(literal))
     end
 
     # Check if string values end with a binary substring.
     #
-    # @param sub [String]
+    # @param suffix [String]
     #   Suffix substring.
     #
     # @return [Expr]
-    def ends_with(sub)
-      Utils.wrap_expr(_rbexpr.binary_ends_with(sub))
+    #
+    # @example
+    #   colors = Polars::DataFrame.new(
+    #     {
+    #       "name" => ["black", "yellow", "blue"],
+    #       "code" => ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b],
+    #       "suffix" => ["\x00".b, "\xff\x00".b, "\x00\x00".b]
+    #     }
+    #   )
+    #   colors.select(
+    #     "name",
+    #     Polars.col("code").bin.ends_with("\xff".b).alias("ends_with_lit"),
+    #     Polars.col("code").bin.ends_with(Polars.col("suffix")).alias("ends_with_expr")
+    #   )
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌────────┬───────────────┬────────────────┐
+    #   # │ name   ┆ ends_with_lit ┆ ends_with_expr │
+    #   # │ ---    ┆ ---           ┆ ---            │
+    #   # │ str    ┆ bool          ┆ bool           │
+    #   # ╞════════╪═══════════════╪════════════════╡
+    #   # │ black  ┆ false         ┆ true           │
+    #   # │ yellow ┆ false         ┆ true           │
+    #   # │ blue   ┆ true          ┆ false          │
+    #   # └────────┴───────────────┴────────────────┘
+    def ends_with(suffix)
+      suffix = Utils.parse_into_expression(suffix, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.binary_ends_with(suffix))
     end
 
     # Check if values start with a binary substring.
     #
-    # @param sub [String]
+    # @param prefix [String]
     #   Prefix substring.
     #
     # @return [Expr]
-    def starts_with(sub)
-      Utils.wrap_expr(_rbexpr.binary_starts_with(sub))
+    #
+    # @example
+    #   colors = Polars::DataFrame.new(
+    #     {
+    #       "name": ["black", "yellow", "blue"],
+    #       "code": ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b],
+    #       "prefix": ["\x00".b, "\xff\x00".b, "\x00\x00".b]
+    #     }
+    #   )
+    #   colors.select(
+    #     "name",
+    #     Polars.col("code").bin.starts_with("\xff".b).alias("starts_with_lit"),
+    #     Polars.col("code")
+    #     .bin.starts_with(Polars.col("prefix"))
+    #     .alias("starts_with_expr")
+    #   )
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌────────┬─────────────────┬──────────────────┐
+    #   # │ name   ┆ starts_with_lit ┆ starts_with_expr │
+    #   # │ ---    ┆ ---             ┆ ---              │
+    #   # │ str    ┆ bool            ┆ bool             │
+    #   # ╞════════╪═════════════════╪══════════════════╡
+    #   # │ black  ┆ false           ┆ true             │
+    #   # │ yellow ┆ true            ┆ false            │
+    #   # │ blue   ┆ false           ┆ true             │
+    #   # └────────┴─────────────────┴──────────────────┘
+    def starts_with(prefix)
+      prefix = Utils.parse_into_expression(prefix, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.binary_starts_with(prefix))
     end
 
     # Decode a value using the provided encoding.
@@ -48,6 +128,28 @@ module Polars
     #   otherwise mask out with a null value.
     #
     # @return [Expr]
+    #
+    # @example
+    #   colors = Polars::DataFrame.new(
+    #     {
+    #       "name" => ["black", "yellow", "blue"],
+    #       "encoded" => ["000000".b, "ffff00".b, "0000ff".b]
+    #     }
+    #   )
+    #   colors.with_columns(
+    #     Polars.col("encoded").bin.decode("hex").alias("code")
+    #   )
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌────────┬───────────┬─────────────────┐
+    #   # │ name   ┆ encoded   ┆ code            │
+    #   # │ ---    ┆ ---       ┆ ---             │
+    #   # │ str    ┆ binary    ┆ binary          │
+    #   # ╞════════╪═══════════╪═════════════════╡
+    #   # │ black  ┆ b"000000" ┆ b"\x00\x00\x00" │
+    #   # │ yellow ┆ b"ffff00" ┆ b"\xff\xff\x00" │
+    #   # │ blue   ┆ b"0000ff" ┆ b"\x00\x00\xff" │
+    #   # └────────┴───────────┴─────────────────┘
     def decode(encoding, strict: true)
       if encoding == "hex"
         Utils.wrap_expr(_rbexpr.binary_hex_decode(strict))
@@ -64,6 +166,28 @@ module Polars
     #   The encoding to use.
     #
     # @return [Expr]
+    #
+    # @example
+    #   colors = Polars::DataFrame.new(
+    #     {
+    #       "color" => ["black", "yellow", "blue"],
+    #       "code" => ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b]
+    #     }
+    #   )
+    #   colors.with_columns(
+    #     Polars.col("code").bin.encode("hex").alias("encoded")
+    #   )
+    #   # =>
+    #   # shape: (3, 3)
+    #   # ┌────────┬─────────────────┬─────────┐
+    #   # │ color  ┆ code            ┆ encoded │
+    #   # │ ---    ┆ ---             ┆ ---     │
+    #   # │ str    ┆ binary          ┆ str     │
+    #   # ╞════════╪═════════════════╪═════════╡
+    #   # │ black  ┆ b"\x00\x00\x00" ┆ 000000  │
+    #   # │ yellow ┆ b"\xff\xff\x00" ┆ ffff00  │
+    #   # │ blue   ┆ b"\x00\x00\xff" ┆ 0000ff  │
+    #   # └────────┴─────────────────┴─────────┘
     def encode(encoding)
       if encoding == "hex"
         Utils.wrap_expr(_rbexpr.binary_hex_encode)

data/lib/polars/binary_name_space.rb

@@ -12,31 +12,67 @@ module Polars
 
     # Check if binaries in Series contain a binary substring.
     #
-    # @param lit [String]
+    # @param literal [String]
     #   The binary substring to look for
     #
     # @return [Series]
-    def contains(lit)
+    #
+    # @example
+    #   s = Polars::Series.new("colors", ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b])
+    #   s.bin.contains("\xff".b)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'colors' [bool]
+    #   # [
+    #   #         false
+    #   #         true
+    #   #         true
+    #   # ]
+    def contains(literal)
       super
     end
 
     # Check if string values end with a binary substring.
     #
-    # @param sub [String]
+    # @param suffix [String]
     #   Suffix substring.
     #
     # @return [Series]
-    def ends_with(sub)
+    #
+    # @example
+    #   s = Polars::Series.new("colors", ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b])
+    #   s.bin.ends_with("\x00".b)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'colors' [bool]
+    #   # [
+    #   #         true
+    #   #         true
+    #   #         false
+    #   # ]
+    def ends_with(suffix)
       super
     end
 
     # Check if values start with a binary substring.
     #
-    # @param sub [String]
+    # @param prefix [String]
     #   Prefix substring.
     #
     # @return [Series]
-    def starts_with(sub)
+    #
+    # @example
+    #   s = Polars::Series.new("colors", ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b])
+    #   s.bin.starts_with("\x00".b)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'colors' [bool]
+    #   # [
+    #   #         true
+    #   #         false
+    #   #         true
+    #   # ]
+    def starts_with(prefix)
       super
     end
 
@@ -49,6 +85,42 @@ module Polars
     #   otherwise mask out with a null value.
     #
     # @return [Series]
+    #
+    # @example Decode values using hexadecimal encoding.
+    #   s = Polars::Series.new("colors", ["000000".b, "ffff00".b, "0000ff".b])
+    #   s.bin.decode("hex")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'colors' [binary]
+    #   # [
+    #   #         b"\x00\x00\x00"
+    #   #         b"\xff\xff\x00"
+    #   #         b"\x00\x00\xff"
+    #   # ]
+    #
+    # @example Decode values using Base64 encoding.
+    #   s = Polars::Series.new("colors", ["AAAA".b, "//8A".b, "AAD/".b])
+    #   s.bin.decode("base64")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'colors' [binary]
+    #   # [
+    #   #         b"\x00\x00\x00"
+    #   #         b"\xff\xff\x00"
+    #   #         b"\x00\x00\xff"
+    #   # ]
+    #
+    # @example Set `strict=False` to set invalid values to null instead of raising an error.
+    #   s = Polars::Series.new("colors", ["000000".b, "ffff00".b, "invalid_value".b])
+    #   s.bin.decode("hex", strict: false)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'colors' [binary]
+    #   # [
+    #   #         b"\x00\x00\x00"
+    #   #         b"\xff\xff\x00"
+    #   #         null
+    #   # ]
     def decode(encoding, strict: true)
       super
     end
@@ -59,6 +131,29 @@ module Polars
     #   The encoding to use.
     #
     # @return [Series]
+    #
+    # @example Encode values using hexadecimal encoding.
+    #   s = Polars::Series.new("colors", ["\x00\x00\x00".b, "\xff\xff\x00".b, "\x00\x00\xff".b])
+    #   s.bin.encode("hex")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'colors' [str]
+    #   # [
+    #   #         "000000"
+    #   #         "ffff00"
+    #   #         "0000ff"
+    #   # ]
+    #
+    # @example Encode values using Base64 encoding.
+    #   s.bin.encode("base64")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'colors' [str]
+    #   # [
+    #   #         "AAAA"
+    #   #         "//8A"
+    #   #         "AAD/"
+    #   # ]
     def encode(encoding)
       super
     end

data/lib/polars/config.rb

@@ -527,4 +527,8 @@ module Polars
       self
     end
   end
+
+  def self.config(...)
+    Config.new(...)
+  end
 end