[Elyahou]

Why the change

A failed or unchanged fetch emits no event today (only FETCHED, for a changed payload, and READY), so an application that wants to count fetch failures or track how old its definitions are has to patch requests itself; this adds a FETCH_COMPLETED event after every fetch, like the Java SDK's togglesFetched(ClientFeaturesResponse).

Special things to note

• FETCHED is unchanged and still fires only for a changed payload, so existing callbacks see the same events plus the new one.
• The event carries no HTTP status code: the transport turns the response into a FetchStatus that says what a listener should do about it.
• The transports emit it as soon as a fetch ends, before the result is applied, so it arrives before that poll's FETCHED/READY. It covers polling only; the streaming connector doesn't fetch, so it doesn't emit it.

Change outline

class FetchStatus(Enum):
    CHANGED = "changed"                    # 200 with a body
    NOT_CHANGED = "not_changed"            # 304
    UNAUTHORIZED = "unauthorized"          # 401, 403: won't recover on its own
    RATE_LIMITED = "rate_limited"          # 429: back off
    UNAVAILABLE = "unavailable"            # 5xx after retries, timeout, no response: transient
    INVALID_RESPONSE = "invalid_response"  # empty 200, any other status

@dataclass
class UnleashFetchCompletedEvent(BaseEvent):   # event_type=UnleashEventType.FETCH_COMPLETED
    status: FetchStatus

Counting fetch failures and tracking when definitions were last confirmed, through the existing event_callback:

from UnleashClient import UnleashClient
from UnleashClient.events import BaseEvent, FetchStatus, UnleashFetchCompletedEvent


def on_event(event: BaseEvent) -> None:
    if not isinstance(event, UnleashFetchCompletedEvent):
        return
    if event.status in (FetchStatus.CHANGED, FetchStatus.NOT_CHANGED):
        # Unleash answered with the current definitions
        last_successful_fetch.set_to_current_time()
    else:
        fetch_failures.inc(status=event.status.value)


client = UnleashClient(url=UNLEASH_URL, app_name="my-app", event_callback=on_event)
client.initialize_client()

_Transport / _AsyncTransport.fetch_features(etag)
  _fetch_features(etag)        # the request as before, plus how it ended as a FetchStatus
+ _emit_fetch_completed(...)   # FETCH_COMPLETED with that status
  return result                # the connectors apply it as before

Tests cover each status on both transports (200, 304, 401, 403, 429, a 500 after retries, 503, an unexpected 202, an empty 200, no response, and on the async one a body that times out), a listener that raises, and both clients delivering the event to their event_callback.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[sighphyre]

I think this is good. Want to wait for some feedback from others before I merge though

[alexanto]

I think the new event should also be documented in the readme

[sighphyre]

I think the new event should also be documented in the readme

Fair, but we're halfway through migrating docs to here: https://docs.getunleash.io/sdks/python

I think let's leave it in this PR, I can open a PR for that with the docs team (and maybe even clean up the README here to be what we agreed on with Documentation before they realize I haven't done that and they come for me)

from my view this is a sane addition, but lets wait for what the others think

[Copilot]

🟡 Changes recommended

Cache application errors suppress completion events in both polling connectors, breaking the per-fetch notification guarantee.

2 open issues

• Emit async fetch completion when cache writes fail · New
• Emit fetch completion when state application fails · New

_{Review effort: Balanced}

[ppicom]

@Elyahou thanks for the work on this PR, really appreciated. I left a question about including the http code in the event itself. The rest of it is looking nice!

[Elyahou]

@Elyahou thanks for the work on this PR, really appreciated. I left a question about including the http code in the event itself. The rest of it is looking nice!

Thanks ! I replied to your comment

[ppicom]

Looks good, I think FAILED got renamed to UNAVAILABLE again. If we sort that, we can merge 🚀