polars-df 0.15.0 → 0.26.0

data/lib/polars/io/csv.rb

@@ -16,38 +16,55 @@ module Polars
     #   Rename columns right after parsing the CSV file. If the given
     #   list is shorter than the width of the DataFrame the remaining
     #   columns will have their original name.
-    # @param sep [String]
-    #   Single byte character to use as delimiter in the file.
-    # @param comment_char [String]
-    #   Single byte character that indicates the start of a comment line,
-    #   for instance `#`.
+    # @param separator [String]
+    #   Single byte character to use as separator in the file.
+    # @param comment_prefix [String]
+    #   A string used to indicate the start of a comment line. Comment lines are skipped
+    #   during parsing. Common examples of comment prefixes are `#` and `//`.
     # @param quote_char [String]
     #   Single byte character used for csv quoting.
     #   Set to nil to turn off special handling and escaping of quotes.
     # @param skip_rows [Integer]
     #   Start reading after `skip_rows` lines.
-    # @param dtypes [Object]
-    #   Overwrite dtypes during inference.
+    # @param skip_lines [Integer]
+    #   Start reading after `skip_lines` lines. The header will be parsed at this
+    #   offset. Note that CSV escaping will not be respected when skipping lines.
+    #   If you want to skip valid CSV rows, use `skip_rows`.
+    # @param schema [Object]
+    #   Provide the schema. This means that polars doesn't do schema inference.
+    #   This argument expects the complete schema, whereas `schema_overrides` can be
+    #   used to partially overwrite a schema. Note that the order of the columns in
+    #   the provided `schema` must match the order of the columns in the CSV being read.
+    # @param schema_overrides [Object]
+    #   Overwrite dtypes for specific or all columns during schema inference.
     # @param null_values [Object]
     #   Values to interpret as null values. You can provide a:
     #
     #   - `String`: All values equal to this string will be null.
     #   - `Array`: All values equal to any string in this array will be null.
     #   - `Hash`: A hash that maps column name to a null value string.
+    # @param missing_utf8_is_empty_string [Boolean]
+    #   By default a missing value is considered to be null; if you would prefer missing
+    #   utf8 values to be treated as the empty string you can set this param true.
     # @param ignore_errors [Boolean]
     #   Try to keep reading lines if some lines yield errors.
     #   First try `infer_schema_length: 0` to read all columns as
     #   `:str` to check which values might cause an issue.
-    # @param parse_dates [Boolean]
+    # @param try_parse_dates [Boolean]
     #   Try to automatically parse dates. If this does not succeed,
     #   the column remains of data type `:str`.
     # @param n_threads [Integer]
     #   Number of threads to use in csv parsing.
     #   Defaults to the number of physical cpu's of your system.
+    # @param infer_schema [Boolean]
+    #   When `true`, the schema is inferred from the data using the first
+    #   `infer_schema_length` rows.
+    #   When `false`, the schema is not inferred and will be `Polars::String` if not
+    #   specified in `schema` or `schema_overrides`.
     # @param infer_schema_length [Integer]
-    #   Maximum number of lines to read to infer schema.
-    #   If set to 0, all columns will be read as `:utf8`.
-    #   If set to `nil`, a full table scan will be done (slow).
+    #   The maximum number of rows to scan for schema inference.
+    #   If set to `nil`, the full data may be scanned *(this is slow)*.
+    #   Set `infer_schema: false` to read all columns as `Polars::String`.
     # @param batch_size [Integer]
     #   Number of lines to read into the buffer at once.
     #   Modify this to change performance.
@@ -70,15 +87,22 @@ module Polars
     #   particular storage connection.
     # @param skip_rows_after_header [Integer]
     #   Skip this number of rows when the header is parsed.
-    # @param row_count_name [String]
+    # @param row_index_name [String]
     #   If not nil, this will insert a row count column with the given name into
     #   the DataFrame.
-    # @param row_count_offset [Integer]
+    # @param row_index_offset [Integer]
     #   Offset to start the row_count column (only used if the name is set).
     # @param eol_char [String]
     #   Single byte end of line character.
+    # @param raise_if_empty [Boolean]
+    #   When there is no data in the source, `NoDataError` is raised. If this parameter
+    #   is set to false, an empty DataFrame (with no columns) is returned instead.
     # @param truncate_ragged_lines [Boolean]
     #   Truncate lines that are longer than the schema.
+    # @param decimal_comma [Boolean]
+    #   Parse floats using a comma as the decimal separator instead of a period.
+    # @param glob [Boolean]
+    #   Expand path given via globbing rules.
     #
     # @return [DataFrame]
     #
@@ -92,30 +116,36 @@ module Polars
       has_header: true,
       columns: nil,
       new_columns: nil,
-      sep: ",",
-      comment_char: nil,
+      separator: ",",
+      comment_prefix: nil,
       quote_char: '"',
       skip_rows: 0,
-      dtypes: nil,
+      skip_lines: 0,
+      schema: nil,
+      schema_overrides: nil,
       null_values: nil,
+      missing_utf8_is_empty_string: false,
       ignore_errors: false,
-      parse_dates: false,
+      try_parse_dates: false,
       n_threads: nil,
+      infer_schema: true,
       infer_schema_length: N_INFER_DEFAULT,
       batch_size: 8192,
       n_rows: nil,
       encoding: "utf8",
       low_memory: false,
-      rechunk: true,
+      rechunk: false,
       storage_options: nil,
       skip_rows_after_header: 0,
-      row_count_name: nil,
-      row_count_offset: 0,
+      row_index_name: nil,
+      row_index_offset: 0,
       eol_char: "\n",
-      truncate_ragged_lines: false
+      raise_if_empty: true,
+      truncate_ragged_lines: false,
+      decimal_comma: false,
+      glob: true
     )
-      Utils._check_arg_is_1byte("sep", sep, false)
-      Utils._check_arg_is_1byte("comment_char", comment_char, false)
+      Utils._check_arg_is_1byte("separator", separator, false)
       Utils._check_arg_is_1byte("quote_char", quote_char, true)
       Utils._check_arg_is_1byte("eol_char", eol_char, false)
 
@@ -131,8 +161,8 @@ module Polars
         end
       end
 
-      if projection || new_columns
-        raise Todo
+      if !infer_schema
+        infer_schema_length = 0
       end
 
       df = nil
@@ -141,14 +171,17 @@ module Polars
           data,
           has_header: has_header,
           columns: columns || projection,
-          sep: sep,
-          comment_char: comment_char,
+          separator: separator,
+          comment_prefix: comment_prefix,
           quote_char: quote_char,
           skip_rows: skip_rows,
-          dtypes: dtypes,
+          skip_lines: skip_lines,
+          schema_overrides: schema_overrides,
+          schema: schema,
           null_values: null_values,
+          missing_utf8_is_empty_string: missing_utf8_is_empty_string,
           ignore_errors: ignore_errors,
-          parse_dates: parse_dates,
+          try_parse_dates: try_parse_dates,
           n_threads: n_threads,
           infer_schema_length: infer_schema_length,
           batch_size: batch_size,
@@ -157,10 +190,13 @@ module Polars
           low_memory: low_memory,
           rechunk: rechunk,
           skip_rows_after_header: skip_rows_after_header,
-          row_count_name: row_count_name,
-          row_count_offset: row_count_offset,
+          row_index_name: row_index_name,
+          row_index_offset: row_index_offset,
           eol_char: eol_char,
-          truncate_ragged_lines: truncate_ragged_lines
+          raise_if_empty: raise_if_empty,
+          truncate_ragged_lines: truncate_ragged_lines,
+          decimal_comma: decimal_comma,
+          glob: glob
         )
       end
 
@@ -176,26 +212,27 @@ module Polars
       file,
       has_header: true,
       columns: nil,
-      sep: ",",
-      comment_char: nil,
+      separator: ",",
+      comment_prefix: nil,
       quote_char: '"',
       skip_rows: 0,
-      dtypes: nil,
+      skip_lines: 0,
       schema: nil,
+      schema_overrides: nil,
       null_values: nil,
       missing_utf8_is_empty_string: false,
       ignore_errors: false,
-      parse_dates: false,
+      try_parse_dates: false,
       n_threads: nil,
       infer_schema_length: N_INFER_DEFAULT,
       batch_size: 8192,
       n_rows: nil,
       encoding: "utf8",
       low_memory: false,
-      rechunk: true,
+      rechunk: false,
       skip_rows_after_header: 0,
-      row_count_name: nil,
-      row_count_offset: 0,
+      row_index_name: nil,
+      row_index_offset: 0,
       eol_char: "\n",
       raise_if_empty: true,
       truncate_ragged_lines: false,
@@ -213,16 +250,16 @@ module Polars
 
       dtype_list = nil
       dtype_slice = nil
-      if !dtypes.nil?
-        if dtypes.is_a?(Hash)
+      if !schema_overrides.nil?
+        if schema_overrides.is_a?(Hash)
           dtype_list = []
-          dtypes.each do |k, v|
-            dtype_list << [k, Utils.rb_type_to_dtype(v)]
+          schema_overrides.each do |k, v|
+            dtype_list << [k, Utils.parse_into_dtype(v)]
           end
-        elsif dtypes.is_a?(::Array)
-          dtype_slice = dtypes
+        elsif schema_overrides.is_a?(::Array)
+          dtype_slice = schema_overrides
         else
-          raise ArgumentError, "dtype arg should be list or dict"
+          raise TypeError, "dtype arg should be array or hash"
         end
       end
 
@@ -242,11 +279,13 @@ module Polars
         scan = scan_csv(
           file,
           has_header: has_header,
-          sep: sep,
-          comment_char: comment_char,
+          separator: separator,
+          comment_prefix: comment_prefix,
           quote_char: quote_char,
           skip_rows: skip_rows,
-          dtypes: dtypes_dict,
+          skip_lines: skip_lines,
+          schema: schema,
+          schema_overrides: dtypes_dict,
           null_values: null_values,
           missing_utf8_is_empty_string: missing_utf8_is_empty_string,
           ignore_errors: ignore_errors,
@@ -255,9 +294,10 @@ module Polars
           low_memory: low_memory,
           rechunk: rechunk,
           skip_rows_after_header: skip_rows_after_header,
-          row_count_name: row_count_name,
-          row_count_offset: row_count_offset,
+          row_index_name: row_index_name,
+          row_index_offset: row_index_offset,
           eol_char: eol_char,
+          raise_if_empty: raise_if_empty,
           truncate_ragged_lines: truncate_ragged_lines,
           decimal_comma: decimal_comma,
           glob: glob
@@ -282,8 +322,9 @@ module Polars
           ignore_errors,
           n_rows,
           skip_rows,
+          skip_lines,
           projection,
-          sep,
+          separator,
           rechunk,
           columns,
           encoding,
@@ -292,13 +333,13 @@ module Polars
           dtype_list,
           dtype_slice,
           low_memory,
-          comment_char,
+          comment_prefix,
           quote_char,
           processed_null_values,
           missing_utf8_is_empty_string,
-          parse_dates,
+          try_parse_dates,
           skip_rows_after_header,
-          Utils.parse_row_index_args(row_count_name, row_count_offset),
+          Utils.parse_row_index_args(row_index_name, row_index_offset),
           eol_char,
           raise_if_empty,
           truncate_ragged_lines,
@@ -315,11 +356,14 @@ module Polars
     # file chunks. After that work will only be done
     # if `next_batches` is called.
     #
+    # @deprecated
+    #   Use `scan_csv().collect_batches` instead.
+    #
     # @param source [Object]
     #   Path to a file or a file-like object.
     # @param has_header [Boolean]
     #   Indicate if the first row of dataset is a header or not.
-    #   If set to False, column names will be autogenerated in the
+    #   If set to false, column names will be autogenerated in the
     #   following format: `column_x`, with `x` being an
     #   enumeration over every column in the dataset starting at 1.
     # @param columns [Object]
@@ -329,17 +373,21 @@ module Polars
     #   Rename columns right after parsing the CSV file. If the given
     #   list is shorter than the width of the DataFrame the remaining
     #   columns will have their original name.
-    # @param sep [String]
-    #   Single byte character to use as delimiter in the file.
-    # @param comment_char [String]
-    #   Single byte character that indicates the start of a comment line,
-    #   for instance `#`.
+    # @param separator [String]
+    #   Single byte character to use as separator in the file.
+    # @param comment_prefix [String]
+    #   A string used to indicate the start of a comment line. Comment lines are skipped
+    #   during parsing. Common examples of comment prefixes are `#` and `//`.
     # @param quote_char [String]
     #   Single byte character used for csv quoting, default = `"`.
     #   Set to nil to turn off special handling and escaping of quotes.
     # @param skip_rows [Integer]
     #   Start reading after `skip_rows` lines.
-    # @param dtypes [Object]
+    # @param skip_lines [Integer]
+    #   Start reading after `skip_lines` lines. The header will be parsed at this
+    #   offset. Note that CSV escaping will not be respected when skipping lines.
+    #   If you want to skip valid CSV rows, use `skip_rows`.
+    # @param schema_overrides [Object]
     #   Overwrite dtypes during inference.
     # @param null_values [Object]
     #   Values to interpret as null values. You can provide a:
@@ -347,11 +395,14 @@ module Polars
     #   - `String`: All values equal to this string will be null.
     #   - `Array`: All values equal to any string in this array will be null.
     #   - `Hash`: A hash that maps column name to a null value string.
+    # @param missing_utf8_is_empty_string [Boolean]
+    #   By default a missing value is considered to be null; if you would prefer missing
+    #   utf8 values to be treated as the empty string you can set this param true.
     # @param ignore_errors [Boolean]
     #   Try to keep reading lines if some lines yield errors.
     #   First try `infer_schema_length: 0` to read all columns as
     #   `:str` to check which values might cause an issue.
-    # @param parse_dates [Boolean]
+    # @param try_parse_dates [Boolean]
     #   Try to automatically parse dates. If this does not succeed,
     #   the column remains of data type `:str`.
     # @param n_threads [Integer]
@@ -380,21 +431,26 @@ module Polars
     #   aggregating the chunks into a single array.
     # @param skip_rows_after_header [Integer]
     #   Skip this number of rows when the header is parsed.
-    # @param row_count_name [String]
+    # @param row_index_name [String]
     #   If not nil, this will insert a row count column with the given name into
     #   the DataFrame.
-    # @param row_count_offset [Integer]
+    # @param row_index_offset [Integer]
     #   Offset to start the row_count column (only used if the name is set).
     # @param eol_char [String]
     #   Single byte end of line character.
+    # @param raise_if_empty [Boolean]
+    #   When there is no data in the source,`NoDataError` is raised. If this parameter
+    #   is set to false, `nil` will be returned from `next_batches(n)` instead.
     # @param truncate_ragged_lines [Boolean]
     #   Truncate lines that are longer than the schema.
+    # @param decimal_comma [Boolean]
+    #   Parse floats using a comma as the decimal separator instead of a period.
     #
     # @return [BatchedCsvReader]
     #
     # @example
     #   reader = Polars.read_csv_batched(
-    #     "./tpch/tables_scale_100/lineitem.tbl", sep: "|", parse_dates: true
+    #     "./tpch/tables_scale_100/lineitem.tbl", separator: "|", try_parse_dates: true
     #   )
     #   reader.next_batches(5)
     def read_csv_batched(
@@ -402,25 +458,26 @@ module Polars
       has_header: true,
       columns: nil,
       new_columns: nil,
-      sep: ",",
-      comment_char: nil,
+      separator: ",",
+      comment_prefix: nil,
       quote_char: '"',
       skip_rows: 0,
-      dtypes: nil,
+      skip_lines: 0,
+      schema_overrides: nil,
       null_values: nil,
       missing_utf8_is_empty_string: false,
       ignore_errors: false,
-      parse_dates: false,
+      try_parse_dates: false,
       n_threads: nil,
       infer_schema_length: N_INFER_DEFAULT,
       batch_size: 50_000,
       n_rows: nil,
       encoding: "utf8",
       low_memory: false,
-      rechunk: true,
+      rechunk: false,
       skip_rows_after_header: 0,
-      row_count_name: nil,
-      row_count_offset: 0,
+      row_index_name: nil,
+      row_index_offset: 0,
       eol_char: "\n",
       raise_if_empty: true,
       truncate_ragged_lines: false,
@@ -436,23 +493,20 @@ module Polars
         end
       end
 
-      if projection || new_columns
-        raise Todo
-      end
-
       BatchedCsvReader.new(
         source,
         has_header: has_header,
         columns: columns || projection,
-        sep: sep,
-        comment_char: comment_char,
+        separator: separator,
+        comment_prefix: comment_prefix,
         quote_char: quote_char,
         skip_rows: skip_rows,
-        dtypes: dtypes,
+        skip_lines: skip_lines,
+        schema_overrides: schema_overrides,
         null_values: null_values,
         missing_utf8_is_empty_string: missing_utf8_is_empty_string,
         ignore_errors: ignore_errors,
-        parse_dates: parse_dates,
+        try_parse_dates: try_parse_dates,
         n_threads: n_threads,
         infer_schema_length: infer_schema_length,
         batch_size: batch_size,
@@ -461,8 +515,8 @@ module Polars
         low_memory: low_memory,
         rechunk: rechunk,
         skip_rows_after_header: skip_rows_after_header,
-        row_count_name: row_count_name,
-        row_count_offset: row_count_offset,
+        row_index_name: row_index_name,
+        row_index_offset: row_index_offset,
         eol_char: eol_char,
         new_columns: new_columns,
         raise_if_empty: raise_if_empty,
@@ -484,25 +538,37 @@ module Polars
     #   If set to false, column names will be autogenerated in the
     #   following format: `column_x`, with `x` being an
     #   enumeration over every column in the dataset starting at 1.
-    # @param sep [String]
-    #   Single byte character to use as delimiter in the file.
-    # @param comment_char [String]
-    #   Single byte character that indicates the start of a comment line,
-    #   for instance `#`.
+    # @param separator [String]
+    #   Single byte character to use as separator in the file.
+    # @param comment_prefix [String]
+    #   A string used to indicate the start of a comment line. Comment lines are skipped
+    #   during parsing. Common examples of comment prefixes are `#` and `//`.
     # @param quote_char [String]
     #   Single byte character used for csv quoting.
-    #   Set to None to turn off special handling and escaping of quotes.
+    #   Set to nil to turn off special handling and escaping of quotes.
     # @param skip_rows [Integer]
     #   Start reading after `skip_rows` lines. The header will be parsed at this
     #   offset.
-    # @param dtypes [Object]
-    #   Overwrite dtypes during inference.
+    # @param skip_lines [Integer]
+    #   Start reading after `skip_lines` lines. The header will be parsed at this
+    #   offset. Note that CSV escaping will not be respected when skipping lines.
+    #   If you want to skip valid CSV rows, use `skip_rows`.
+    # @param schema [Object]
+    #   Provide the schema. This means that polars doesn't do schema inference.
+    #   This argument expects the complete schema, whereas `schema_overrides` can be
+    #   used to partially overwrite a schema. Note that the order of the columns in
+    #   the provided `schema` must match the order of the columns in the CSV being read.
+    # @param schema_overrides [Object]
+    #   Overwrite dtypes for specific or all columns during schema inference.
     # @param null_values [Object]
     #   Values to interpret as null values. You can provide a:
     #
     #   - `String`: All values equal to this string will be null.
     #   - `Array`: All values equal to any string in this array will be null.
     #   - `Hash`: A hash that maps column name to a null value string.
+    # @param missing_utf8_is_empty_string [Boolean]
+    #   By default a missing value is considered to be null; if you would prefer missing
+    #   utf8 values to be treated as the empty string you can set this param true.
     # @param ignore_errors [Boolean]
     #   Try to keep reading lines if some lines yield errors.
     #   First try `infer_schema_length: 0` to read all columns as
@@ -513,6 +579,11 @@ module Polars
     #   Apply a function over the column names.
     #   This can be used to update a schema just in time, thus before
     #   scanning.
+    # @param infer_schema [Boolean]
+    #   When `true`, the schema is inferred from the data using the first
+    #   `infer_schema_length` rows.
+    #   When `false`, the schema is not inferred and will be `Polars::String` if not
+    #   specified in `schema` or `schema_overrides`.
     # @param infer_schema_length [Integer]
     #   Maximum number of lines to read to infer schema.
     #   If set to 0, all columns will be read as `:str`.
@@ -528,64 +599,167 @@ module Polars
     #   Reallocate to contiguous memory when all chunks/ files are parsed.
     # @param skip_rows_after_header [Integer]
     #   Skip this number of rows when the header is parsed.
-    # @param row_count_name [String]
+    # @param row_index_name [String]
     #   If not nil, this will insert a row count column with the given name into
     #   the DataFrame.
-    # @param row_count_offset [Integer]
+    # @param row_index_offset [Integer]
     #   Offset to start the row_count column (only used if the name is set).
-    # @param parse_dates [Boolean]
+    # @param try_parse_dates [Boolean]
     #   Try to automatically parse dates. If this does not succeed,
     #   the column remains of data type `:str`.
     # @param eol_char [String]
     #   Single byte end of line character.
+    # @param new_columns [Array]
+    #   Provide an explicit list of string column names to use (for example, when
+    #   scanning a headerless CSV file). If the given list is shorter than the width of
+    #   the DataFrame the remaining columns will have their original name.
+    # @param raise_if_empty [Boolean]
+    #   When there is no data in the source, `NoDataError` is raised. If this parameter
+    #   is set to false, an empty LazyFrame (with no columns) is returned instead.
     # @param truncate_ragged_lines [Boolean]
     #   Truncate lines that are longer than the schema.
+    # @param decimal_comma [Boolean]
+    #   Parse floats using a comma as the decimal separator instead of a period.
+    # @param glob [Boolean]
+    #   Expand path given via globbing rules.
+    # @param storage_options [Hash]
+    #   Options that indicate how to connect to a cloud provider.
+    #
+    #   The cloud providers currently supported are AWS, GCP, and Azure.
+    #   See supported keys here:
+    #
+    #   * [aws](https://docs.rs/object_store/latest/object_store/aws/enum.AmazonS3ConfigKey.html)
+    #   * [gcp](https://docs.rs/object_store/latest/object_store/gcp/enum.GoogleConfigKey.html)
+    #   * [azure](https://docs.rs/object_store/latest/object_store/azure/enum.AzureConfigKey.html)
+    #   * Hugging Face (`hf://`): Accepts an API key under the `token` parameter: \
+    #     `{'token': '...'}`, or by setting the `HF_TOKEN` environment variable.
+    #
+    #   If `storage_options` is not provided, Polars will try to infer the information
+    #   from environment variables.
+    # @param credential_provider [Object]
+    #   Provide a function that can be called to provide cloud storage
+    #   credentials. The function is expected to return a hash of
+    #   credential keys along with an optional credential expiry time.
+    # @param retries [Integer]
+    #   Number of retries if accessing a cloud instance fails.
+    # @param file_cache_ttl [Integer]
+    #   Amount of time to keep downloaded cloud files since their last access time,
+    #   in seconds. Uses the `POLARS_FILE_CACHE_TTL` environment variable
+    #   (which defaults to 1 hour) if not given.
+    # @param include_file_paths [String]
+    #   Include the path of the source file(s) as a column with this name.
+    # @param missing_columns ['insert', 'raise']
+    #   Configuration for behavior when columns defined in the schema are
+    #   missing from the data:
+    #
+    #   * `"insert"`: Insert the missing columns with NULL values.
+    #   * `"raise"`: Raise an error.
     #
     # @return [LazyFrame]
     def scan_csv(
       source,
       has_header: true,
-      sep: ",",
-      comment_char: nil,
+      separator: ",",
+      comment_prefix: nil,
       quote_char: '"',
       skip_rows: 0,
-      dtypes: nil,
+      skip_lines: 0,
+      schema: nil,
+      schema_overrides: nil,
       null_values: nil,
       missing_utf8_is_empty_string: false,
       ignore_errors: false,
-      cache: true,
+      cache: nil,
       with_column_names: nil,
+      infer_schema: true,
       infer_schema_length: N_INFER_DEFAULT,
       n_rows: nil,
       encoding: "utf8",
       low_memory: false,
-      rechunk: true,
+      rechunk: false,
       skip_rows_after_header: 0,
-      row_count_name: nil,
-      row_count_offset: 0,
-      parse_dates: false,
+      row_index_name: nil,
+      row_index_offset: 0,
+      try_parse_dates: false,
       eol_char: "\n",
+      new_columns: nil,
       raise_if_empty: true,
       truncate_ragged_lines: false,
       decimal_comma: false,
-      glob: true
+      glob: true,
+      storage_options: nil,
+      credential_provider: "auto",
+      retries: nil,
+      file_cache_ttl: nil,
+      include_file_paths: nil,
+      missing_columns: nil
     )
-      Utils._check_arg_is_1byte("sep", sep, false)
-      Utils._check_arg_is_1byte("comment_char", comment_char, false)
+      if new_columns&.any? && schema_overrides.is_a?(::Array)
+        msg = "expected 'schema_overrides' hash, found #{schema_overrides.inspect}"
+        raise TypeError, msg
+      elsif new_columns&.any?
+        if with_column_names
+          msg = "cannot set both `with_column_names` and `new_columns`; mutually exclusive"
+          raise ArgumentError, msg
+        end
+        if schema_overrides && schema_overrides.is_a?(::Array)
+          schema_overrides = new_columns.zip(schema_overrides).to_h
+        end
+
+        # wrap new column names as a callable
+        with_column_names = lambda do |cols|
+          if cols.length > new_columns.length
+            new_columns + cols[new_columns.length..]
+          else
+            new_columns
+          end
+        end
+      end
+
+      Utils._check_arg_is_1byte("separator", separator, false)
       Utils._check_arg_is_1byte("quote_char", quote_char, true)
 
       if Utils.pathlike?(source)
         source = Utils.normalize_filepath(source)
       end
 
+      if !infer_schema
+        infer_schema_length = 0
+      end
+
+      if !retries.nil?
+        msg = "the `retries` parameter was deprecated in 0.25.0; specify 'max_retries' in `storage_options` instead."
+        Utils.issue_deprecation_warning(msg)
+        storage_options = storage_options || {}
+        storage_options["max_retries"] = retries
+      end
+
+      if !file_cache_ttl.nil?
+        msg = "the `file_cache_ttl` parameter was deprecated in 0.25.0; specify 'file_cache_ttl' in `storage_options` instead."
+        Utils.issue_deprecation_warning(msg)
+        storage_options = storage_options || {}
+        storage_options["file_cache_ttl"] = file_cache_ttl
+      end
+
+      if !missing_columns.nil?
+        msg = "The `missing_columns` parameter of `scan_csv` is considered unstable."
+        Utils.issue_unstable_warning(msg)
+      end
+
+      credential_provider_builder = _init_credential_provider_builder(
+        credential_provider, source, storage_options, "scan_csv"
+      )
+
       _scan_csv_impl(
         source,
         has_header: has_header,
-        sep: sep,
-        comment_char: comment_char,
+        separator: separator,
+        comment_prefix: comment_prefix,
         quote_char: quote_char,
         skip_rows: skip_rows,
-        dtypes: dtypes,
+        skip_lines: skip_lines,
+        schema_overrides: schema_overrides,
+        schema: schema,
         null_values: null_values,
         ignore_errors: ignore_errors,
         cache: cache,
@@ -596,11 +770,18 @@ module Polars
         rechunk: rechunk,
         skip_rows_after_header: skip_rows_after_header,
         encoding: encoding,
-        row_count_name: row_count_name,
-        row_count_offset: row_count_offset,
-        parse_dates: parse_dates,
+        row_index_name: row_index_name,
+        row_index_offset: row_index_offset,
+        try_parse_dates: try_parse_dates,
         eol_char: eol_char,
-        truncate_ragged_lines: truncate_ragged_lines
+        raise_if_empty: raise_if_empty,
+        truncate_ragged_lines: truncate_ragged_lines,
+        decimal_comma: decimal_comma,
+        glob: glob,
+        storage_options: storage_options,
+        credential_provider: credential_provider_builder,
+        include_file_paths: include_file_paths,
+        missing_columns: missing_columns
       )
     end
 
@@ -608,12 +789,15 @@ module Polars
     def _scan_csv_impl(
       source,
       has_header: true,
-      sep: ",",
-      comment_char: nil,
+      separator: ",",
+      comment_prefix: nil,
       quote_char: '"',
       skip_rows: 0,
-      dtypes: nil,
+      skip_lines: 0,
+      schema: nil,
+      schema_overrides: nil,
       null_values: nil,
+      missing_utf8_is_empty_string: false,
       ignore_errors: false,
       cache: true,
       with_column_names: nil,
@@ -621,19 +805,26 @@ module Polars
       n_rows: nil,
       encoding: "utf8",
       low_memory: false,
-      rechunk: true,
+      rechunk: false,
       skip_rows_after_header: 0,
-      row_count_name: nil,
-      row_count_offset: 0,
-      parse_dates: false,
+      row_index_name: nil,
+      row_index_offset: 0,
+      try_parse_dates: false,
       eol_char: "\n",
-      truncate_ragged_lines: true
+      raise_if_empty: true,
+      truncate_ragged_lines: true,
+      decimal_comma: false,
+      glob: true,
+      storage_options: nil,
+      credential_provider: nil,
+      include_file_paths: nil,
+      missing_columns: nil
     )
       dtype_list = nil
-      if !dtypes.nil?
+      if !schema_overrides.nil?
         dtype_list = []
-        dtypes.each do |k, v|
-          dtype_list << [k, Utils.rb_type_to_dtype(v)]
+        schema_overrides.each do |k, v|
+          dtype_list << [k, Utils.parse_into_dtype(v)]
         end
       end
       processed_null_values = Utils._process_null_values(null_values)
@@ -645,30 +836,47 @@ module Polars
         sources = []
       end
 
+      # TODO: This is a hack. We conditionally set `missing_columns` to mimic
+      # existing behavior. This should be removed once the workaround is no
+      # longer needed.
+      if missing_columns.nil? && !schema.nil? && has_header
+        missing_columns = "insert"
+      end
+
       rblf =
         RbLazyFrame.new_from_csv(
           source,
-          sep,
+          sources,
+          separator,
           has_header,
           ignore_errors,
           skip_rows,
+          skip_lines,
           n_rows,
           cache,
           dtype_list,
           low_memory,
-          comment_char,
+          comment_prefix,
           quote_char,
           processed_null_values,
+          missing_utf8_is_empty_string,
           infer_schema_length,
           with_column_names,
           rechunk,
           skip_rows_after_header,
           encoding,
-          Utils.parse_row_index_args(row_count_name, row_count_offset),
-          parse_dates,
+          Utils.parse_row_index_args(row_index_name, row_index_offset),
+          try_parse_dates,
           eol_char,
+          raise_if_empty,
           truncate_ragged_lines,
-          sources
+          decimal_comma,
+          glob,
+          schema,
+          storage_options,
+          credential_provider,
+          include_file_paths,
+          missing_columns
         )
       Utils.wrap_ldf(rblf)
     end