polars-df 0.15.0 → 0.26.0

data/lib/polars/cat_name_space.rb

@@ -31,58 +31,158 @@ module Polars
 
     # Return whether or not the column is a local categorical.
     #
-    # @return [Boolean]
+    # Always returns false.
     #
-    # @example Categoricals constructed without a string cache are considered local.
-    #   s = Polars::Series.new(["a", "b", "a"], dtype: Polars::Categorical)
-    #   s.cat.is_local
-    #   # => true
+    # @deprecated
+    #   `cat.is_local` is deprecated; Categoricals no longer have a local scope.
     #
-    # @example Categoricals constructed with a string cache are considered global.
-    #   s = nil
-    #   Polars::StringCache.new do
-    #     s = Polars::Series.new(["a", "b", "a"], dtype: Polars::Categorical)
-    #   end
-    #   s.cat.is_local
-    #   # => false
+    # @return [Boolean]
     def is_local
       _s.cat_is_local
     end
 
-    # Convert a categorical column to its local representation.
+    # Simply returns the column as-is, local representations are deprecated.
+    #
+    # @return [Series]
+    def to_local
+      Utils.wrap_s(_s.cat_to_local)
+    end
+
+    # Indicate whether the Series uses lexical ordering.
     #
-    # This may change the underlying physical representation of the column.
+    # @deprecated
+    #   `cat.uses_lexical_ordering` is deprecated; Categoricals are now always ordered lexically.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   s = Polars::Series.new(["b", "a", "b"]).cast(Polars::Categorical)
+    #   s.cat.uses_lexical_ordering
+    #   # => true
+    def uses_lexical_ordering
+      _s.cat_uses_lexical_ordering
+    end
+
+    # Return the byte-length of the string representation of each value.
     #
     # @return [Series]
     #
-    # @example Compare the global and local representations of a categorical.
-    #   s = nil
-    #   Polars::StringCache.new do
-    #     _ = Polars::Series.new("x", ["a", "b", "a"], dtype: Polars::Categorical)
-    #     s = Polars::Series.new("y", ["c", "b", "d"], dtype: Polars::Categorical)
-    #   end
-    #   s.to_physical
+    # @example
+    #   s = Polars::Series.new(["Café", "345", "東京", nil], dtype: Polars::Categorical)
+    #   s.cat.len_bytes
     #   # =>
-    #   # shape: (3,)
-    #   # Series: 'y' [u32]
+    #   # shape: (4,)
+    #   # Series: '' [u32]
     #   # [
-    #   #         2
-    #   #         1
+    #   #         5
     #   #         3
+    #   #         6
+    #   #         null
     #   # ]
+    def len_bytes
+      super
+    end
+
+    # Return the number of characters of the string representation of each value.
+    #
+    # @return [Series]
     #
     # @example
-    #   s.cat.to_local.to_physical
+    #   s = Polars::Series.new(["Café", "345", "東京", nil], dtype: Polars::Categorical)
+    #   s.cat.len_chars
     #   # =>
-    #   # shape: (3,)
-    #   # Series: 'y' [u32]
+    #   # shape: (4,)
+    #   # Series: '' [u32]
     #   # [
-    #   #         0
-    #   #         1
+    #   #         4
+    #   #         3
     #   #         2
+    #   #         null
     #   # ]
-    def to_local
-      Utils.wrap_s(_s.cat_to_local)
+    def len_chars
+      super
+    end
+
+    # Check if string representations of values start with a substring.
+    #
+    # @param prefix [String]
+    #     Prefix substring.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("fruits", ["apple", "mango", nil], dtype: Polars::Categorical)
+    #   s.cat.starts_with("app")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'fruits' [bool]
+    #   # [
+    #   #         true
+    #   #         false
+    #   #         null
+    #   # ]
+    def starts_with(prefix)
+      super
+    end
+
+    # Check if string representations of values end with a substring.
+    #
+    # @param suffix [String]
+    #   Suffix substring.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("fruits", ["apple", "mango", nil], dtype: Polars::Categorical)
+    #   s.cat.ends_with("go")
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'fruits' [bool]
+    #   # [
+    #   #         false
+    #   #         true
+    #   #         null
+    #   # ]
+    def ends_with(suffix)
+      super
+    end
+
+    # Extract a substring from the string representation of each string value.
+    #
+    # @param offset [Integer]
+    #   Start index. Negative indexing is supported.
+    # @param length [Integer]
+    #   Length of the slice. If set to `nil` (default), the slice is taken to the
+    #   end of the string.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new(["pear", nil, "papaya", "dragonfruit"], dtype: Polars::Categorical)
+    #   s.cat.slice(-3)
+    #   # =>
+    #   # shape: (4,)
+    #   # Series: '' [str]
+    #   # [
+    #   #         "ear"
+    #   #         null
+    #   #         "aya"
+    #   #         "uit"
+    #   # ]
+    #
+    # @example Using the optional `length` parameter
+    #   s.cat.slice(4, 3)
+    #   # =>
+    #   # shape: (4,)
+    #   # Series: '' [str]
+    #   # [
+    #   #         ""
+    #   #         null
+    #   #         "ya"
+    #   #         "onf"
+    #   # ]
+    def slice(offset, length = nil)
+      super
     end
   end
 end

data/lib/polars/catalog/unity/catalog_info.rb

@@ -0,0 +1,20 @@
+module Polars
+  class Catalog
+    module Unity
+      # Information for a catalog within a metastore.
+      CatalogInfo =
+        ::Struct.new(
+          :name,
+          :comment,
+          :properties,
+          :options,
+          :storage_location,
+          :created_at,
+          :created_by,
+          :updated_at,
+          :updated_by,
+          keyword_init: true
+        )
+    end
+  end
+end

data/lib/polars/catalog/unity/column_info.rb

@@ -0,0 +1,31 @@
+module Polars
+  class Catalog
+    module Unity
+      # Information for a column within a catalog table.
+      ColumnInfo =
+        ::Struct.new(
+          :name,
+          :type_name,
+          :type_text,
+          :type_json,
+          :position,
+          :comment,
+          :partition_index,
+          keyword_init: true
+        )
+
+      class ColumnInfo
+        # Get the native polars datatype of this column.
+        #
+        # @note
+        #   This functionality is considered **unstable**. It may be changed
+        #   at any point without it being considered a breaking change.
+        #
+        # @return [Object]
+        def get_polars_dtype
+          RbCatalogClient.type_json_to_polars_type(type_json)
+        end
+      end
+    end
+  end
+end

data/lib/polars/catalog/unity/namespace_info.rb

@@ -0,0 +1,21 @@
+module Polars
+  class Catalog
+    module Unity
+      # Information for a namespace within a catalog.
+      #
+      # This is also known by the name "schema" in unity catalog terminology.
+      NamespaceInfo =
+        ::Struct.new(
+          :name,
+          :comment,
+          :properties,
+          :storage_location,
+          :created_at,
+          :created_by,
+          :updated_at,
+          :updated_by,
+          keyword_init: true
+        )
+    end
+  end
+end

data/lib/polars/catalog/unity/table_info.rb

@@ -0,0 +1,50 @@
+module Polars
+  class Catalog
+    module Unity
+      # Information for a catalog table.
+      TableInfo =
+        ::Struct.new(
+          :name,
+          :comment,
+          :table_id,
+          :table_type,
+          :storage_location,
+          :data_source_format,
+          :columns,
+          :properties,
+          :created_at,
+          :created_by,
+          :updated_at,
+          :updated_by,
+          keyword_init: true
+        )
+
+      class TableInfo
+        # Get the native polars schema of this table.
+        #
+        # @note
+        #   This functionality is considered **unstable**. It may be changed
+        #   at any point without it being considered a breaking change.
+        #
+        # @return [Schema]
+        def get_polars_schema
+          if columns.nil?
+            return nil
+          end
+
+          schema = Schema.new(check_dtypes: false)
+
+          columns.each do |column_info|
+            if schema[column_info.name]
+              msg = "duplicate column name: #{column_info.name}"
+              raise DuplicateError, msg
+            end
+            schema[column_info.name] = column_info.get_polars_dtype
+          end
+
+          schema
+        end
+      end
+    end
+  end
+end