sdk: tighten ReadableSpan.attributes to non-Optional Mapping (#4569)

[WatchTree-19]

Description

ReadableSpan.attributes is annotated as types.Attributes, which resolves to Optional[Mapping[str, AttributeValue]]. The implementation always returns MappingProxyType(self._attributes or {}) - the or {} fallback ensures we never return None at runtime.

Pyright / Pylance flags Object of type "None" is not subscriptable on span.attributes["key"], forcing assert span.attributes is not None boilerplate at every call site.

This PR tightens the return annotation on ReadableSpan.attributes to the non-Optional Mapping[str, types.AttributeValue]. Implementation unchanged. Mapping is already imported in the file.

Scope:

• ReadableSpan.attributes only. Inherited by Span and _Span, no further changes needed.
• Event.attributes and Link.attributes return self._attributes directly (which can be None) and stay Optional.
• types.Attributes global alias is unchanged for the same reason.

Per the comment thread on #4569 from @exekis and @tekumara, the implementation has never returned None from ReadableSpan.attributes, so this is type-system tightening rather than a behaviour change. Technically a breaking change for any caller explicitly handling None on the return; in practice there shouldn't be any.

Fixes #4569

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

• patched file parses cleanly via python -m ast
• existing call sites are unchanged, only the return-type annotation is narrower
• have not run the project test suite locally; happy to chase a green CI here if anything trips

Does This PR Require a Contrib Repo Change?

• Yes. - Link to PR:
• No.

Checklist:

• Followed the style guidelines of this project
• Changelogs have been updated
• Unit tests have been added
• Documentation has been updated

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: WatchTree-19 / name: WatchTree-19 (2fb0968, 97d0d2a)

[MikeGoldsmith]

Thanks @WatchTree-19 - left some feedback on things we need to tidy up

[MikeGoldsmith]

Looks like you got some other changelog entries in here - please can you clean this up?

[MikeGoldsmith]

This is very verbose, can we tighten this up?

[MikeGoldsmith]

Do / should we update the API definition too?

[WatchTree-19]

thanks @MikeGoldsmith. pushed a follow-up addressing all three:

1. CHANGELOG.md: hadn't realised the repo had moved to towncrier since my first commit went up - sorry for the noise. reverted the CHANGELOG.md edit to upstream/main and added .changelog/5183.changed as a one-line fragment per CONTRIBUTING.md.

2. docstring: tightened to a single line.

@property
def attributes(self) -> Mapping[str, types.AttributeValue]:
    # `or {}` keeps the return non-None; see #4569.
    return MappingProxyType(self._attributes or {})

3. API definition: looked at opentelemetry-api/src/opentelemetry/trace/span.py. the abstract trace_api.Span class defines set_attributes and set_attribute but no attributes property - that's only on the SDK's ReadableSpan. so no parallel API change is needed; the narrower annotation lives entirely in the SDK layer. happy to add a @property to the abstract API with the same Mapping[str, types.AttributeValue] return type if you'd prefer the surface symmetrical, but that'd be an API addition rather than a fix.

let me know if there's anything else.

[emdneto]

Thanks for the PR!

Just a heads-up: we no longer update CHANGELOG.md directly. The changelog is now generated from changelog fragments using Towncrier.

Please add the appropriate changelog fragment for this change instead of editing CHANGELOG.md manually. You can find the instructions and expected format in CONTRIBUTING.md.

[WatchTree-19]

@emdneto already addressed in the follow-up - reverted the CHANGELOG.md edit and added .changelog/5183.changed per CONTRIBUTING.md. see the latest commit + comment above.

[WatchTree-19]

@MikeGoldsmith @emdneto gentle bump - rebased onto current main to clear the CHANGELOG.md conflict that came in with the towncrier migration. branch is now one commit (SDK annotation tightening + .changelog/5183.changed fragment), DCO signed. ready for another look when you have time.