Configuration — Call.Report

Two tiny modules’ worth of configuration. Most projects will call disable_legacy_mode() once at startup and otherwise ignore this page.

Legacy error mode

v3.0.0 can raise two different exception styles:

Typed mode (modern): specific subclasses of FFIECError — CredentialError, ValidationError, etc.
Legacy mode (default, for v2 back-compat): plain ValueError everywhere, with the original v2 error messages and no structured details.

The default is legacy mode on, so that v2 except ValueError blocks keep catching. New code should opt out.

The environment variable

FFIEC_USE_LEGACY_ERRORS=true|false

Read once at import time into Config._use_legacy_errors. Truthy values are "true", "1", "yes" (case-insensitive). Default "true". Setting this to false at the shell is the cleanest way to opt into typed exceptions — no code change required.

`enable_legacy_mode()`

from ffiec_data_connect import enable_legacy_mode
enable_legacy_mode()

Turns legacy mode on (raise ValueError instead of typed exceptions). Equivalent to set_legacy_errors(True). Use this only if you’re porting v2 code incrementally and aren’t ready to rewrite your except blocks.

`disable_legacy_mode()`

from ffiec_data_connect import disable_legacy_mode
disable_legacy_mode()

Turns legacy mode off (raise typed FFIECError subclasses). Equivalent to set_legacy_errors(False). Call this once at startup in new code — it’s the only way to get structured error information for observability, retry logic, or richer error rendering.

import ffiec_data_connect as ffiec

ffiec.disable_legacy_mode()

# from here on, errors are typed
try:
    ffiec.collect_data(creds, reporting_period="bad", rssd_id="480228", series="call")
except ffiec.ValidationError as e:
    print(e.details)
    # {"field": "reporting_period", "provided_value": "bad", ...}

`set_legacy_errors(enabled: bool)`

Direct setter. Equivalent to enable_legacy_mode() / disable_legacy_mode() — exposed because some integration code prefers a bool flag to a pair of verb functions.

`use_legacy_errors() -> bool`

Predicate. Returns the current setting. Also emits a one-shot DeprecationWarning the first time it’s called in legacy mode, warning that the default will flip in a future release.

from ffiec_data_connect import use_legacy_errors
use_legacy_errors()  # True by default

When the flag is consulted

Internal raise_exception(...) helper checks use_legacy_errors() at every raise site. So changing the flag at runtime takes effect on the very next call — no need to restart the process. Flipping it mid-request will leave in-flight calls alone, but new raises will follow the new setting.

SOAP cache shims

Both of these are no-op stubs retained for v2 compatibility. They exist so v2 code that called them doesn’t crash at import; they do nothing useful in v3.0.0.

`clear_soap_cache()`

from ffiec_data_connect import clear_soap_cache
clear_soap_cache()

No-op. Emits a DeprecationWarning. In v2 this cleared a cached zeep client. In v3.0.0 there is no SOAP client to cache, so the call does nothing. Remove calls to this from your codebase.

`get_cache_stats()`

from ffiec_data_connect import get_cache_stats
get_cache_stats()
# {"size": 0, "max_size": 0, "hit_ratio": 0.0, "keys": [], "deprecated": True}

Returns a constant “cache is empty and deprecated” dict. Emits a DeprecationWarning. The "deprecated": True key is how you programmatically detect that you’re on v3.0.0 rather than v2.

Recommended startup block for new code

import ffiec_data_connect as ffiec

# Opt into typed exceptions immediately.
ffiec.disable_legacy_mode()

# Everything else — credentials, client, collect_* — as normal.
creds = ffiec.OAuth2Credentials(username="...", bearer_token="eyJ...")

Pair that with FFIEC_USE_LEGACY_ERRORS=false in your deployment environment and you’re fully on the modern error surface.

Legacy error mode

The environment variable

enable_legacy_mode()

disable_legacy_mode()

set_legacy_errors(enabled: bool)

use_legacy_errors() -> bool