Class: Polars::Config

Inherits:
Object
  • Object
show all
Defined in:
lib/polars/config.rb

Overview

Configure polars; offers options for table formatting and more.

Constant Summary collapse

POLARS_CFG_ENV_VARS = 
[
  "POLARS_ACTIVATE_DECIMAL",
  "POLARS_AUTO_STRUCTIFY",
  "POLARS_FMT_MAX_COLS",
  "POLARS_FMT_MAX_ROWS",
  "POLARS_FMT_STR_LEN",
  "POLARS_FMT_TABLE_CELL_ALIGNMENT",
  "POLARS_FMT_TABLE_DATAFRAME_SHAPE_BELOW",
  "POLARS_FMT_TABLE_FORMATTING",
  "POLARS_FMT_TABLE_HIDE_COLUMN_DATA_TYPES",
  "POLARS_FMT_TABLE_HIDE_COLUMN_NAMES",
  "POLARS_FMT_TABLE_HIDE_COLUMN_SEPARATOR",
  "POLARS_FMT_TABLE_HIDE_DATAFRAME_SHAPE_INFORMATION",
  "POLARS_FMT_TABLE_INLINE_COLUMN_DATA_TYPE",
  "POLARS_FMT_TABLE_ROUNDED_CORNERS",
  "POLARS_STREAMING_CHUNK_SIZE",
  "POLARS_TABLE_WIDTH",
  "POLARS_VERBOSE"
]
POLARS_CFG_DIRECT_VARS = 
{"set_fmt_float" => Plr.method(:get_float_fmt)}

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(restore_defaults: false, **options) {|self.class| ... } ⇒ Config

Initialize a Config object instance for context manager usage.

Yields:

  • (self.class) 


27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/polars/config.rb', line 27

def initialize(restore_defaults: false, **options)
  @original_state = self.class.save

  if restore_defaults
    self.class.restore_defaults
  end

  options.each do |opt, value|
    opt = "set_#{opt}" unless opt.to_s.start_with?("set_")
    if !self.class.respond_to?(opt)
      raise ArgumentError, "Config has no #{opt} option"
    end
    self.class.public_send(opt, value)
  end

  yield self.class

  self.class.restore_defaults.load(@original_state)
  @original_state = ""
end

Class Method Details

.activate_decimals(active = true) ⇒ Config

Activate Decimal data types.

This is a temporary setting that will be removed later once the Decimal type stabilize. This will happens without it being considered a breaking change.

Currently, Decimal types are in an alpha state.

Returns:



116
117
118
119
120
121
122
123
 
# File 'lib/polars/config.rb', line 116

def self.activate_decimals(active = true)
  if !active
    ENV.delete("POLARS_ACTIVATE_DECIMAL")
  else
    ENV["POLARS_ACTIVATE_DECIMAL"] = "1"
  end
  self
end

.load(cfg) ⇒ Config

Load and set previously saved (or shared) Config options from json/file.

Returns:



51
52
53
54
55
56
57
58
59
60
 
# File 'lib/polars/config.rb', line 51

def self.load(cfg)
  options = JSON.parse(cfg)
  ENV.merge!(options["environment"])
  options.fetch("fetch", {}).each do |cfg_methodname, value|
    if POLARS_CFG_DIRECT_VARS.key?(cfg_methodname)
      public_send(cfg_methodname, value)
    end
  end
  self
end

.restore_defaults ⇒ Config

Reset all polars Config settings to their default state.

Returns:



65
66
67
68
69
70
71
 
# File 'lib/polars/config.rb', line 65

def self.restore_defaults
  POLARS_CFG_ENV_VARS.each do |var|
    ENV.delete(var)
  end
  set_fmt_float
  self
end

.save ⇒ Config

Save the current set of Config options as a json string or file.

Returns:



76
77
78
79
80
81
 
# File 'lib/polars/config.rb', line 76

def self.save
  environment_vars = POLARS_CFG_ENV_VARS.sort.select { |k| ENV.key?(k) }.to_h { |k| [k, ENV[k]] }
  direct_vars = POLARS_CFG_DIRECT_VARS.to_h { |cfg_methodname, get_value| [cfg_methodname, get_value.call] }
  options = JSON.generate({environment: environment_vars, direct: direct_vars})
  options
end

.set_ascii_tables(active = true) ⇒ Config

Use ASCII characters to display table outlines (set False to revert to UTF8).

Examples:

df = Polars::DataFrame.new({"abc" => [1.0, 2.5, 5.0], "xyz" => [true, false, true]})
Polars::Config.new(ascii_tables: true) do
  p df
end
# =>
# shape: (3, 2)
# +-----+-------+
# | abc | xyz   |
# | --- | ---   |
# | f64 | bool  |
# +=============+
# | 1.0 | true  |
# | 2.5 | false |
# | 5.0 | true  |
# +-----+-------+

Returns:



145
146
147
148
149
 
# File 'lib/polars/config.rb', line 145

def self.set_ascii_tables(active = true)
  fmt = active ? "ASCII_FULL_CONDENSED" : "UTF8_FULL_CONDENSED"
  ENV["POLARS_FMT_TABLE_FORMATTING"] = fmt
  self
end

.set_auto_structify(active = true) ⇒ Config

Allow multi-output expressions to be automatically turned into Structs.

Returns:



154
155
156
157
 
# File 'lib/polars/config.rb', line 154

def self.set_auto_structify(active = true)
  ENV["POLARS_AUTO_STRUCTIFY"] = active ? "1" : "0"
  self
end

.set_fmt_float(fmt = "mixed") ⇒ Config

Control how floating point values are displayed.

Parameters:

  • fmt ("mixed", "full") (defaults to: "mixed") —

    How to format floating point numbers

Returns:



165
166
167
168
 
# File 'lib/polars/config.rb', line 165

def self.set_fmt_float(fmt = "mixed")
  Plr.set_float_fmt(fmt)
  self
end

.set_fmt_str_lengths(n) ⇒ Config

Set the number of characters used to display string values.

Examples:

df = Polars::DataFrame.new(
  {
    "txt" => [
      "Play it, Sam. Play 'As Time Goes By'.",
      "This is the beginning of a beautiful friendship.",
    ]
  }
)
Polars::Config.new(fmt_str_lengths: 50) do
  p df
end
# =>
# shape: (2, 1)
# ┌──────────────────────────────────────────────────┐
# │ txt                                              │
# │ ---                                              │
# │ str                                              │
# ╞══════════════════════════════════════════════════╡
# │ Play it, Sam. Play 'As Time Goes By'.            │
# │ This is the beginning of a beautiful friendship. │
# └──────────────────────────────────────────────────┘

Parameters:

  • n (Integer) —

    number of characters to display

Returns:



199
200
201
202
203
204
205
206
 
# File 'lib/polars/config.rb', line 199

def self.set_fmt_str_lengths(n)
  if n <= 0
    raise ArgumentError, "number of characters must be > 0"
  end

  ENV["POLARS_FMT_STR_LEN"] = n.to_s
  self
end

.set_streaming_chunk_size(size) ⇒ Config

Overwrite chunk size used in streaming engine.

By default, the chunk size is determined by the schema and size of the thread pool. For some datasets (esp. when you have large string elements) this can be too optimistic and lead to Out of Memory errors.

Parameters:

  • size (Integer) —

    Number of rows per chunk. Every thread will process chunks of this size.

Returns:



220
221
222
223
224
225
226
227
 
# File 'lib/polars/config.rb', line 220

def self.set_streaming_chunk_size(size)
  if size < 1
    raise ArgumentError, "number of rows per chunk must be >= 1"
  end

  ENV["POLARS_STREAMING_CHUNK_SIZE"] = size.to_s
  self
end

.set_tbl_cell_alignment(format) ⇒ Config

Set table cell alignment.

Examples:

df = Polars::DataFrame.new(
  {"column_abc" => [1.0, 2.5, 5.0], "column_xyz" => [true, false, true]}
)
Polars::Config.new(tbl_cell_alignment: "RIGHT") do
  p df
end
# =>
# shape: (3, 2)
# ┌────────────┬────────────┐
# │ column_abc ┆ column_xyz │
# │        --- ┆        --- │
# │        f64 ┆       bool │
# ╞════════════╪════════════╡
# │        1.0 ┆       true │
# │        2.5 ┆      false │
# │        5.0 ┆       true │
# └────────────┴────────────┘

Parameters:

  • format (String) —
    • "LEFT": left aligned
    • "CENTER": center aligned
    • "RIGHT": right aligned

Returns:



256
257
258
259
 
# File 'lib/polars/config.rb', line 256

def self.set_tbl_cell_alignment(format)
  ENV["POLARS_FMT_TABLE_CELL_ALIGNMENT"] = format
  self
end

.set_tbl_cols(n) ⇒ Config

Set the number of columns that are visible when displaying tables.

Examples:

Set number of displayed columns to a low value:

Polars::Config.new do |cfg|
  cfg.set_tbl_cols(5)
  df = Polars::DataFrame.new(100.times.to_h { |i| [i.to_s, [i]] })
  p df
end
# =>
# shape: (1, 100)
# ┌─────┬─────┬─────┬───┬─────┬─────┐
# │ 0   ┆ 1   ┆ 2   ┆ … ┆ 98  ┆ 99  │
# │ --- ┆ --- ┆ --- ┆   ┆ --- ┆ --- │
# │ i64 ┆ i64 ┆ i64 ┆   ┆ i64 ┆ i64 │
# ╞═════╪═════╪═════╪═══╪═════╪═════╡
# │ 0   ┆ 1   ┆ 2   ┆ … ┆ 98  ┆ 99  │
# └─────┴─────┴─────┴───┴─────┴─────┘

Parameters:

  • n (Integer) —

    number of columns to display; if n < 0 (eg: -1), display all columns.

Returns:



283
284
285
286
 
# File 'lib/polars/config.rb', line 283

def self.set_tbl_cols(n)
  ENV["POLARS_FMT_MAX_COLS"] = n.to_s
  self
end

.set_tbl_column_data_type_inline(active = true) ⇒ Config

Moves the data type inline with the column name (to the right, in parentheses).

Examples:

df = Polars::DataFrame.new({"abc" => [1.0, 2.5, 5.0], "xyz" => [true, false, true]})
Polars::Config.new(tbl_column_data_type_inline: true) do
  p df
end
# =>
# shape: (3, 2)
# ┌───────────┬────────────┐
# │ abc (f64) ┆ xyz (bool) │
# ╞═══════════╪════════════╡
# │ 1.0       ┆ true       │
# │ 2.5       ┆ false      │
# │ 5.0       ┆ true       │
# └───────────┴────────────┘

Returns:



306
307
308
309
 
# File 'lib/polars/config.rb', line 306

def self.set_tbl_column_data_type_inline(active = true)
  ENV["POLARS_FMT_TABLE_INLINE_COLUMN_DATA_TYPE"] = active ? "1" : "0"
  self
end

.set_tbl_dataframe_shape_below(active = true) ⇒ Config

Print the dataframe shape below the dataframe when displaying tables.

Examples:

df = Polars::DataFrame.new({"abc" => [1.0, 2.5, 5.0], "xyz" => [true, false, true]})
Polars::Config.new(tbl_dataframe_shape_below: true) do
  p df
end
# =>
# ┌─────┬───────┐
# │ abc ┆ xyz   │
# │ --- ┆ ---   │
# │ f64 ┆ bool  │
# ╞═════╪═══════╡
# │ 1.0 ┆ true  │
# │ 2.5 ┆ false │
# │ 5.0 ┆ true  │
# └─────┴───────┘
# shape: (3, 2)

Returns:



331
332
333
334
 
# File 'lib/polars/config.rb', line 331

def self.set_tbl_dataframe_shape_below(active = true)
  ENV["POLARS_FMT_TABLE_DATAFRAME_SHAPE_BELOW"] = active ? "1" : "0"
  self
end

.set_tbl_formatting(format = nil, rounded_corners: false) ⇒ Config

Note:

The UTF8 styles all use one or more of the semigraphic box-drawing characters found in the Unicode Box Drawing block, which are not ASCII compatible: https://en.wikipedia.org/wiki/Box-drawing_character#Box_Drawing

Set table formatting style.

Examples:

df = Polars::DataFrame.new(
  {"abc" => [-2.5, 5.0], "mno" => ["hello", "world"], "xyz" => [true, false]}
)
Polars::Config.new(
  tbl_formatting: "ASCII_MARKDOWN",
  tbl_hide_column_data_types: true,
  tbl_hide_dataframe_shape: true
) do
  p df
end
# =>
# | abc  | mno   | xyz   |
# |------|-------|-------|
# | -2.5 | hello | true  |
# | 5.0  | world | false |

Parameters:

  • format (String) (defaults to: nil) —
    • "ASCII_FULL": ASCII, with all borders and lines, including row dividers.
    • "ASCII_FULL_CONDENSED": Same as ASCII_FULL, but with dense row spacing.
    • "ASCII_NO_BORDERS": ASCII, no borders.
    • "ASCII_BORDERS_ONLY": ASCII, borders only.
    • "ASCII_BORDERS_ONLY_CONDENSED": ASCII, borders only, dense row spacing.
    • "ASCII_HORIZONTAL_ONLY": ASCII, horizontal lines only.
    • "ASCII_MARKDOWN": ASCII, Markdown compatible.
    • "UTF8_FULL": UTF8, with all borders and lines, including row dividers.
    • "UTF8_FULL_CONDENSED": Same as UTF8_FULL, but with dense row spacing.
    • "UTF8_NO_BORDERS": UTF8, no borders.
    • "UTF8_BORDERS_ONLY": UTF8, borders only.
    • "UTF8_HORIZONTAL_ONLY": UTF8, horizontal lines only.
    • "NOTHING": No borders or other lines.
  • rounded_corners (Boolean) (defaults to: false) —

    apply rounded corners to UTF8-styled tables (no-op for ASCII formats).

Returns:



378
379
380
381
382
383
384
 
# File 'lib/polars/config.rb', line 378

def self.set_tbl_formatting(format = nil, rounded_corners: false)
  if format
    ENV["POLARS_FMT_TABLE_FORMATTING"] = format
  end
  ENV["POLARS_FMT_TABLE_ROUNDED_CORNERS"] = rounded_corners ? "1" : "0"
  self
end

.set_tbl_hide_column_data_types(active = true) ⇒ Config

Hide table column data types (i64, f64, str etc.).

Examples:

df = Polars::DataFrame.new({"abc" => [1.0, 2.5, 5.0], "xyz" => [true, false, true]})
Polars::Config.new(tbl_hide_column_data_types: true) do
  p df
end
# =>
# shape: (3, 2)
# ┌─────┬───────┐
# │ abc ┆ xyz   │
# ╞═════╪═══════╡
# │ 1.0 ┆ true  │
# │ 2.5 ┆ false │
# │ 5.0 ┆ true  │
# └─────┴───────┘

Returns:



404
405
406
407
 
# File 'lib/polars/config.rb', line 404

def self.set_tbl_hide_column_data_types(active = true)
  ENV["POLARS_FMT_TABLE_HIDE_COLUMN_DATA_TYPES"] = active ? "1" : "0"
  self
end

.set_tbl_hide_column_names(active = true) ⇒ Config

Hide table column names.

Examples:

df = Polars::DataFrame.new({"abc" => [1.0, 2.5, 5.0], "xyz" => [true, false, true]})
Polars::Config.new(tbl_hide_column_names: true) do
  p df
end
# =>
# shape: (3, 2)
# ┌─────┬───────┐
# │ f64 ┆ bool  │
# ╞═════╪═══════╡
# │ 1.0 ┆ true  │
# │ 2.5 ┆ false │
# │ 5.0 ┆ true  │
# └─────┴───────┘

Returns:



427
428
429
430
 
# File 'lib/polars/config.rb', line 427

def self.set_tbl_hide_column_names(active = true)
  ENV["POLARS_FMT_TABLE_HIDE_COLUMN_NAMES"] = active ? "1" : "0"
  self
end

.set_tbl_hide_dataframe_shape(active = true) ⇒ Config

Hide the shape information of the dataframe when displaying tables.

Examples:

df = Polars::DataFrame.new({"abc" => [1.0, 2.5, 5.0], "xyz" => [true, false, true]})
Polars::Config.new(tbl_hide_dataframe_shape: true) do
  p df
end
# =>
# ┌─────┬───────┐
# │ abc ┆ xyz   │
# │ --- ┆ ---   │
# │ f64 ┆ bool  │
# ╞═════╪═══════╡
# │ 1.0 ┆ true  │
# │ 2.5 ┆ false │
# │ 5.0 ┆ true  │
# └─────┴───────┘

Returns:



475
476
477
478
 
# File 'lib/polars/config.rb', line 475

def self.set_tbl_hide_dataframe_shape(active = true)
  ENV["POLARS_FMT_TABLE_HIDE_DATAFRAME_SHAPE_INFORMATION"] = active ? "1" : "0"
  self
end

.set_tbl_hide_dtype_separator(active = true) ⇒ Config

Hide the '---' separator between the column names and column types.

Examples:

df = Polars::DataFrame.new({"abc" => [1.0, 2.5, 5.0], "xyz" => [true, false, true]})
Polars::Config.new(tbl_hide_dtype_separator: true) do
  p df
end
# =>
# shape: (3, 2)
# ┌─────┬───────┐
# │ abc ┆ xyz   │
# │ f64 ┆ bool  │
# ╞═════╪═══════╡
# │ 1.0 ┆ true  │
# │ 2.5 ┆ false │
# │ 5.0 ┆ true  │
# └─────┴───────┘

Returns:



451
452
453
454
 
# File 'lib/polars/config.rb', line 451

def self.set_tbl_hide_dtype_separator(active = true)
  ENV["POLARS_FMT_TABLE_HIDE_COLUMN_SEPARATOR"] = active ? "1" : "0"
  self
end

.set_tbl_rows(n) ⇒ Config

Set the max number of rows used to draw the table (both Dataframe and Series).

Examples:

df = Polars::DataFrame.new(
  {"abc" => [1.0, 2.5, 3.5, 5.0], "xyz" => [true, false, true, false]}
)
Polars::Config.new(tbl_rows: 2) do
  p df
end
# =>
# shape: (4, 2)
# ┌─────┬───────┐
# │ abc ┆ xyz   │
# │ --- ┆ ---   │
# │ f64 ┆ bool  │
# ╞═════╪═══════╡
# │ 1.0 ┆ true  │
# │ …   ┆ …     │
# │ 5.0 ┆ false │
# └─────┴───────┘

Parameters:

  • n (Integer) —

    number of rows to display; if n < 0 (eg: -1), display all rows (DataFrame) and all elements (Series).

Returns:



506
507
508
509
 
# File 'lib/polars/config.rb', line 506

def self.set_tbl_rows(n)
  ENV["POLARS_FMT_MAX_ROWS"] = n.to_s
  self
end

.set_tbl_width_chars(width) ⇒ Config

Set the number of characters used to draw the table.

Parameters:

  • width (Integer) —

    number of chars

Returns:



517
518
519
520
 
# File 'lib/polars/config.rb', line 517

def self.set_tbl_width_chars(width)
  ENV["POLARS_TABLE_WIDTH"] = width.to_s
  self
end

.set_verbose(active = true) ⇒ Config

Enable additional verbose/debug logging.

Returns:



525
526
527
528
 
# File 'lib/polars/config.rb', line 525

def self.set_verbose(active = true)
  ENV["POLARS_VERBOSE"] = active ? "1" : "0"
  self
end

.state(if_set: false, env_only: false) ⇒ Object

Show the current state of all Config variables as a dict.

Parameters:

  • if_set (Boolean) (defaults to: false) —

    by default this will show the state of all Config environment variables. change this to true to restrict the returned dictionary to include only those that have been set to a specific value.

  • env_only (Boolean) (defaults to: false) —

    include only Config environment variables in the output; some options (such as "set_fmt_float") are set directly, not via an environment variable.

Returns:



94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/polars/config.rb', line 94

def self.state(if_set: false, env_only: false)
  config_state = POLARS_CFG_ENV_VARS.sort
    .select { |var| !if_set || !ENV[var].nil? }
    .to_h { |var| [var, ENV[var]] }
  if !env_only
    POLARS_CFG_DIRECT_VARS.each do |cfg_methodname, get_value|
      config_state[cfg_methodname] = get_value.call
    end
  end

  config_state
end