Utilities & helpers

The package re-exports several optional helpers for schema caching, data profiling, local file ingest, and Excel workbooks. All symbols below are available from the top-level dealcloud_sdk import.

These helpers are not DealCloud HTTP APIs: they run locally to support migrations, reporting, and offline analysis. For download/upload against DealCloud entries, use the Files API.

Schema cache

SchemaCache and get_schema_cache() provide a thread-safe, in-memory cache keyed by site URL. The main DealCloud client also exposes cache_schema, schema_cache_ttl, refresh_schema(), and clear_schema_cache()—see API reference and Advanced configuration.

from dealcloud_sdk import SchemaCache, get_schema_cache
 
# Singleton-style access (default TTL 300 seconds)
cache = get_schema_cache()
 
# Or use SchemaCache.get_instance()
cache = SchemaCache.get_instance(default_ttl=300.0)
 
# Low-level usage (advanced): check / set by site and cache type
if cache.has("yoursite.dealcloud.com", "schema"):
    schema = cache.get("yoursite.dealcloud.com", "schema")
cache.clear("yoursite.dealcloud.com")  # or cache.clear_all()

Data profiling

Helpers in dealcloud_sdk.utils.profiling suggest field types and summarize columns—useful before defining schema or mapping ingest files.

Symbol	Role
`DataType`	String constants for inferred types (e.g. `DataType.CURRENCY`, `DataType.EMAIL`)
`PROFILE_COLUMNS`	Column names for the profiling result table
`estimate_field_type`	Infer type from a single value
`detect_choice_field`	Heuristic for Choice vs free text
`analyze_field_values`	Stats dict for a list of values
`profile_series` / `profile_dataframe`	Profile one column or an entire `pandas.DataFrame`
`profile_files`	Profile multiple paths (uses file utilities to read each file)

from dealcloud_sdk import profile_dataframe, profile_files
 
profile = profile_dataframe(df, source_name="export.csv")
# Columns match PROFILE_COLUMNS: Source, Field, Count, Populated, Unique, Datatype, TopValues, Choices

For runtime memory comparison of reads, see Performance tuning (e.g. tracemalloc).

File ingest helpers

dealcloud_sdk.utils.file_utils reads CSV/Excel from local paths or fsspec URIs (s3://, file://, …). This is separate from download_file() (DealCloud attachment API).

Symbol	Role
`SUPPORTED_CSV_EXTENSIONS`, `SUPPORTED_EXCEL_EXTENSIONS`, `ALL_SUPPORTED_EXTENSIONS`	Tuple constants
`detect_encoding`	Guess encoding for text files
`is_supported_file` / `should_skip_file`	Filter paths
`read_csv`, `read_excel`, `read_file`	Load into `pandas`
`get_data_files`	List supported data files under a directory

from dealcloud_sdk import read_file, get_data_files, ALL_SUPPORTED_EXTENSIONS
 
df = read_file("s3://bucket/path/data.csv")

Excel workbook helpers

dealcloud_sdk.utils.excel_utils builds arbitrary workbooks (sanitize names/cells, multi-sheet export). This is not the same as export_schema_to_excel(), which generates the schema documentation workbook—see Schema export.

Symbol	Role
`sanitize_sheet_name`, `sanitize_cell_value`, `sanitize_dataframe`	Excel compatibility
`export_to_excel`, `export_with_formatting`	Write DataFrame(s) to path or URI
`read_excel_sheets`, `append_to_excel`	Read/append sheets
`create_data_validation_dropdown`	Optional data validation
`ILLEGAL_CHARACTERS_RE`, `INVALID_SHEET_NAME_CHARS`	Regex constants

from dealcloud_sdk import export_to_excel
 
export_to_excel({"Sheet1": df1, "Summary": df2}, "report.xlsx")

Row error helpers

Exported from dealcloud_sdk for Rows write responses (HTTP 200 with optional per-row "Errors"):

Symbol	Role
`split_row_results(response)`	Returns `(ok_rows, row_error_rows)`
`finalize_list_response(response, ...)`	Log and/or raise; returns `(all_rows, row_error_rows)`
`format_row_error_message(error_row)`	Basic string summary (unchanged; no schema enrichment)

Opt-in error enrichment

Separate from the helpers above—call explicitly after a write when you need schema-aware messages. See Error Enrichment.

Symbol	Role
`get_field_lookup(object_id)`	On `DealCloud`; `{field_id: {name, apiName}}`
`build_field_lookup(field_map, object_name, ...)`	Lookup from `get_field_map()` output
`enrich_row_errors(error_row, field_lookup, ...)`	Structured items with `fieldName`, `apiName`
`format_error_with_metadata(item)`	Log-oriented message with bracketed metadata
`format_error_message_english(item)`	Plain English message (no raw ids)
`format_row_error_with_metadata(...)`	Row wrapper for metadata mode
`format_row_error_message_english(...)`	Row wrapper for English mode

See Error handling, Error enrichment, and Exceptions.

Not covered here

Internal modules used by the SDK implementation—data_utils, pagination internals—are not part of the stable public surface beyond the helpers above. Use the documented DealCloud methods and the Exceptions reference for error types.