Skip to content

Introduce ConfigurationError For Client Setup #205

Description

@GefMar

Goal

Replace indistinct ValueError mapping for raw client setup failures with a stable public configuration error type.

Context

create_raw_client currently catches _foghttp.FogHttpError and raises ValueError(str(exc)). That keeps construction failures user-visible, but it erases whether the failure came from TLS, proxy endpoint parsing, numeric config or runtime setup. Tests then match text strings, which is fragile for a stability milestone.

Scope

  • Add a public ConfigurationError in the FogHTTP error hierarchy.
  • Map raw client setup/configuration failures to ConfigurationError.
  • Consider subclassing ValueError if needed to preserve compatibility with existing callers.
  • Update tests to assert the error type and stable diagnostic fields/substrings rather than brittle full text.
  • Document the setup/configuration error class where public errors are listed.

Out Of Scope

  • Retyping every runtime request error.
  • Changing successful client construction behavior.

Acceptance Criteria

  • Client setup/config failures use ConfigurationError.
  • Compatibility with existing ValueError handling is preserved or explicitly documented as a 0.4.0-breaking decision.
  • Tests do not depend on fragile full error-message text.
  • Public docs list the new error type.

Test And Check Strategy

  • uv run pytest tests/client_proxy tests/client_tls tests/client_options tests/test_raw_client_errors.py
  • uv run mypy foghttp
  • uv run pre-commit run --all-files

Documentation Impact

  • Update error docs and 0.4.0 release notes.

Risks

  • Risk: changing exception type surprises early adopters.
    Mitigation: consider subclassing ValueError and document the migration path.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Ergonomics, documentation, CI, or polish

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions