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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions