Release history

Release history for the ffiec-data-connect Python library. The authoritative source is CHANGELOG.md upstream — if this page and that file disagree, the upstream file wins.

For migration guidance specific to the v2 → v3 cutover, see Docs → Migration from v2.

3.0.0 — current stable (2026-04-22)

First stable release of the 3.x line. Ships with the same code as 3.0.0rc6; the version bump exists so anyone landing on the latest version can see the full scope of 3.0.0 in one place, and so pip install ffiec-data-connect (no --pre) pulls the intended release.

Headline changes vs. 2.0.5:

• SOAP support removed. WebserviceCredentials, FFIECConnection, SOAPAdapter and friends now raise SOAPDeprecationError. REST with OAuth2Credentials is the only auth path.
• Simplified calling convention. collect_*(creds, ...) with no session argument. The v2-style session=None, creds=creds keyword form still works (with DeprecationWarning) for incremental migration.
• Python 3.11+ required, pandas 3.0+ baseline.
• Raw-bytes outputs (output_type="xbrl" and "pdf") for archive-friendly workflows.
• Tz-aware datetimes — date_output_format="python_format" labels output as America/New_York (FFIEC’s wall-clock zone), DST handled via zoneinfo.
• Silent v2 no-ops promoted to loud errors — output_type="bytes", output_type="polars" without the extra, and date_output_format stubs on list-returning methods now raise ValidationError.
• Async support via AsyncCompatibleClient + RateLimiter.
• Typed exception hierarchy (FFIECError base) — opt-in via disable_legacy_mode() or FFIEC_USE_LEGACY_ERRORS=false.

See the full CHANGELOG.md §3.0.0 for the authoritative list. The per-RC history below is preserved for anyone following along with development.

3.0.0rc6 — superseded by 3.0.0 stable (2026-04-22)

Vestigial-argument audit: runtime warnings on silently-ignored parameter combinations, completion of a previously-stubbed date_output_format feature, a consistency fix for polars-without-polars, and a pre-existing exception-wrapping bug that was masking real errors.

Added

• date_output_format now actually works on collect_reporting_periods, collect_ubpr_reporting_periods, and collect_filers_submission_date_time. Prior to rc6 the conversion was a # Future enhancement stub — the parameter was validated but silently ignored. "string_yyyymmdd" now produces "YYYYMMDD" strings; "python_format" returns tz-aware datetime objects labeled as America/New_York. FFIEC publishes all timestamps in Washington, DC local time with no tz marker on the wire, so the library attaches one for you — DST handled via zoneinfo. See Output formats.
• Shared _require_polars_available() helper consolidating the “polars extra not installed” raise.

Fixed

• Silent polars fallback → ValidationError. When output_type="polars" was requested but the polars extra wasn’t installed, five methods (collect_reporting_periods, collect_filers_since_date, collect_filers_submission_date_time, collect_filers_on_reporting_period, collect_ubpr_reporting_periods) silently returned a Python list instead. Now they raise ValidationError uniformly, matching collect_data’s long-standing behavior.
• Pre-existing ConnectionError re-raise bug. Four spots in the enhanced layer called raise_exception(ConnectionError, f"...") without the positional message argument that ConnectionError.__init__ requires. In non-legacy error mode, any caught exception there turned into TypeError instead of the intended ConnectionError. Fixed, and the surrounding except Exception handlers were narrowed to let typed FFIECError subclasses (plus programming errors like AttributeError, KeyError, TypeError) propagate untouched rather than being wrapped as a ConnectionError (which misleadingly suggests a network issue).
• Stale “endpoint may not be implemented” error text replaced with accurate “transient upstream, retry” wording. Live integration tests confirm the RetrieveFacsimile endpoint is implemented and working; an HTTP 500 there is almost always a transient service-side issue.

New runtime UserWarning on silently-ignored params

• force_null_types + output_type="xbrl" / "pdf" on collect_data and collect_ubpr_facsimile_data: raw-bytes outputs bypass parsing, so null-type selection has no effect.
• date_output_format + output_type="xbrl" / "pdf" on collect_data: same reasoning.
• force_null_types on the five methods where the parameter is a documented no-op (accepted for API symmetry only): the docstring already explained; rc6 surfaces the same message at runtime.

Legacy-mode note

The narrowed exception handling means that adapter ConnectionError propagates verbatim in legacy mode — previously it was re-wrapped with a "Failed to retrieve … via REST API: " prefix. The new message is cleaner but slightly different text; scripts that grep on the old prefix will need updating.

3.0.0rc5 — 2026-04-22 (superseded by rc6)

Hotfix for a regression shipped in rc4 plus a systematic test-coverage audit of every meaningful kwarg combination on the seven public collect_* methods. rc5 was never pushed to PyPI; its content ships as part of rc6.

Fixed

• collect_*(creds=creds, ...) pure-kwarg form no longer raises ValueError: Missing credentials argument. rc4’s resolver only inspected the first-positional slot and didn’t fall back to the creds= kwarg when neither the positional form nor the deprecated session= kwarg was given. Now:

  # All three calling conventions work:
  periods = collect_reporting_periods(creds, series="call")              # positional
  periods = collect_reporting_periods(creds=creds, series="call")        # pure kwarg ← new in rc5
  periods = collect_reporting_periods(session=None, creds=creds, ...)    # legacy (DeprecationWarning)

Tests

rc5 closed the testing gap that let the rc4 regression slip through: all meaningful combinations of (creds_or_session, creds, session) now have explicit coverage, and an assertion-tightening caught a family of tests that previously passed against the buggy resolver.

3.0.0rc4 — 2026-04-22 (superseded by rc6)

Deprecations, an output-format refactor, and several consistency fixes layered on top of rc3.

Added

• output_type="xbrl" on collect_data and collect_ubpr_facsimile_data returns raw UTF-8 XBRL XML bytes (beginning with the <?xml prolog). The library normalizes the UTF-8 BOM the UBPR endpoint emits so every XBRL response arrives in the same shape regardless of endpoint.
• output_type="pdf" on collect_data (Call Report series only) returns raw PDF bytes — the natural format for “archive an auditor-readable snapshot per quarter” use cases. The UBPR endpoint is XBRL-only per the FFIEC spec, so series="ubpr" with output_type="pdf" raises locally before any network call.
• force_null_types on all 7 collect_* methods (previously only on collect_data and collect_ubpr_facsimile_data). Documented as a no-op on the three methods that return plain lists — kept for API symmetry so callers don’t hit TypeError when switching methods.
• RESTAdapter.retrieve_facsimile(..., facsimile_format="XBRL" | "PDF") for callers using the adapter layer directly; previously the header was hard-coded to "XBRL".

Deprecated

• OAuth2Credentials(token_expires=...) — deprecated no-op. Expiration is always decoded from the JWT’s exp claim; any passed value is discarded after a DeprecationWarning.
• session= keyword argument on collect_*() methods — the 2.x-documented calling convention collect_reporting_periods(session=None, creds=creds, ...) had started raising TypeError in rc1–rc3 after the first parameter was renamed internally. It now works again with a DeprecationWarning.
• output_type="bytes" — deprecated alias for "xbrl" where supported. Translated transparently on collect_ubpr_facsimile_data (warn + still works); raises ValidationError on every other method (was silently misbehaving before — returning None on collect_data, a list on the other five).
• session= keyword on OAuth2Credentials.test_credentials() — a SOAP-era stub; passing any value emits DeprecationWarning. Drop it.

Fixed

• collect_*(session=None, creds=creds, ...) no longer raises TypeError.
• UBPR XBRL bytes no longer carry a leading UTF-8 BOM; both facsimile endpoints now return a clean <?xml prolog consistently.

3.0.0rc3 — 2026-04-21

Metadata-only update over rc2. No code, test, or public API changes. This release candidate exists to ship a corrected PyPI description — the README in rc2 still carried two stale ffiec-data-connect.readthedocs.io links from the retired Sphinx docs. The library’s [project.urls] already pointed at call.report in rc2; this release corrects the long-description text to match.

Installable from PyPI with pip install --pre ffiec-data-connect or a pinned ffiec-data-connect==3.0.0rc3.

3.0.0 final is not yet released. Everything below describes the 3.0.0 work — rc3 is what you actually get today.

3.0.0rc2 — 2026-04 (superseded)

Prior pre-release. Same API and behavior as rc3; only difference is the README-based long description on the PyPI project page pointed at the retired RTD docs. 3.0.0rc2 is still installable via explicit pin but users are encouraged to use rc3.

3.0.0 (target) — SOAP removed, REST-only

SOAP support removed. REST-only. New calling convention.

This release removes all SOAP API support following the FFIEC’s discontinuation of the SOAP webservice on 2026-02-28. The library is now REST-only with a simplified calling convention.

Breaking changes

• SOAP removed. WebserviceCredentials, FFIECConnection, SOAPAdapter, and all SOAP-related code are gone. Using them raises SOAPDeprecationError.
• New calling convention. collect_* functions take credentials as the first positional argument: collect_*(creds, ...) instead of collect_*(session=..., creds=..., ...). The session parameter is gone.
• Token expiration is auto-detected from the JWT payload. token_expires no longer needs to be passed to OAuth2Credentials.
• Python 3.11 minimum. Python 3.10 support is dropped (EOL 2026-10-04). Matches pandas 3.0’s own floor.
• pandas 3.0 baseline. pandas>=3.0.0,<4.0.0 (up from >=1.3.0,<3.0.0). Users on pandas 2.x or earlier must upgrade before installing.

Dependencies

• Removed: zeep, requests
• Added: httpx (async-capable HTTP client)
• Upper bounds raised: httpx<2.0, polars<2.0, lxml<7.0 (needed for Python 3.14 wheels), xmltodict<2.0, pyarrow<24.0

Supported Python versions

3.11, 3.12, 3.13, 3.14 (tested in CI).

Quality

• 100% statement test coverage: 652 unit tests + 26 integration tests.
• All tests pass against pandas 3.0.2 with zero deprecation warnings in library code paths.

v2.0.0 — 2025-09-05

Production release with REST API support.

Major release introducing REST API support, OAuth2 authentication, and a dual-protocol architecture (REST alongside legacy SOAP).

New features

• REST API support. Full OAuth2-based REST client alongside SOAP.
• AsyncCompatibleClient. Full async/await support with rate limiting and concurrency control.
• Parallel collection across institutions.
• Direct XBRL → Polars pipeline preserving maximum numeric precision.
• Rich exception types with structured context.
• Resource cleanup via context managers; SOAP client caching.
• Thread safety across concurrent access paths.
• force_null_types parameter for pandas/numpy null-handling override.
• New collection methods:
  • collect_filers_on_reporting_period()
  • collect_filers_since_date()
  • collect_filers_submission_date_time()

Security

• Comprehensive input validation for every public method.
• Credential masking in logs and repr.
• XXE prevention via hardened XML parsers.
• Immutable credentials after construction.

Performance

• Memory leak fixes throughout.
• SOAP client caching to amortize setup cost.
• Up to 5× throughput with async operations on wide workloads.
• 253 tests covering the new surfaces.

Data processing

• Type-specific columns: int_data, float_data, bool_data, str_data.
• Consistent NumPy dtypes end-to-end.
• List, pandas, and Polars outputs from every collector.

Docs

• Jupyter notebook demo added.
• Security, memory, and performance analysis notes.
• Migration guidance for users of 0.x.

v0.3.0 — 2024

• Direct XBRL → Polars conversion.
• NumPy dtype consistency improvements.
• Expanded notebook demos.
• Memory management and thread-safety work.
• Connection stability.

v0.2.0 — 2020-07-28

• Fixed a crash when credentials were supplied via environment variables.
• Improved error handling and validation.
• Session management cleanup.

v0.1.0 — 2020-07-27

Initial beta release. Basic FFIEC webservice integration and core data collection.