Skip to content

Improve the docstring of abstract.CloudEvent #247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ncouture opened this issue Dec 22, 2024 · 2 comments
Open

Improve the docstring of abstract.CloudEvent #247

ncouture opened this issue Dec 22, 2024 · 2 comments

Comments

@ncouture
Copy link

ncouture commented Dec 22, 2024

The getitem of this class goes on to describe that:

The `data` of the event should be accessed by the `.data` accessor rather
than this mapping.

providing a reason and perhaps a reference to an example would help developers understand why event.get() is discouraged by this helper method.

For instance, there is confusion in how the private _attributes data should be accessed expressed in #246.

@ncouture
Copy link
Author

I'm very curious about this, as a potential contributor, would someone care to provide examples of what's stated in the documentation?

My assumption is this is typing related and not directly related to using CloudEvents in Python. Is that somewhat right?

    @abstractmethod
    def _get_attributes(self) -> typing.Dict[str, typing.Any]:
        """
        Returns the attributes of the event.

        The implementation MUST assume that the returned value MAY be mutated.

        Having a function over a property simplifies integration for custom
        framework-specific implementations.

        :returns: Attributes of the event.
        """
        raise NotImplementedError()

@xSAVIKx
Copy link
Member

xSAVIKx commented Mar 19, 2025

Hi @ncouture,

data is not an attribute but the event payload. The line in the docs is there to help and navigate developers. What kind of example you'd like to see? How to access data from an event?

You can check e.g. test_http_cloudevent_mutates_equality to find examples of how .data is accessed.

I hope this clarifies it a bit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants