feat(pubsub): allow explicit ack/nack on messages

[TheKevJames]

Summary

Adds new ack() and nack() methods on SubscriberMessage which allow users
to forcibly mark a messsage as getting acked or nacked, regardless of
the success of the callback. In plain English:

When callback terminates, if .ack() has been called it acks. Else,
if .nack() has been called it nacks. Else, it acks if no exception was
raised and nacks otherwise.

Fixes #837

[gemini-code-assist]

Summary of Changes

Hello @TheKevJames, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the Pub/Sub subscriber by providing more granular control over message acknowledgment. It allows developers to programmatically decide whether a message should be acknowledged or negatively acknowledged, independent of whether the message processing callback completes successfully or raises an exception. This change offers greater flexibility in handling message lifecycle within the application.

Highlights

• Explicit Message Acknowledgment: Introduced ack() and nack() methods on SubscriberMessage to allow users to explicitly control message acknowledgment (ack) or negative acknowledgment (nack), overriding the default behavior tied to callback success or failure.
• New acknack Attribute: Added a new acknack attribute to SubscriberMessage to store the user's explicit acknowledgment preference.
• Refactored Acknowledgment Logic: Implemented a new internal ack_or_nack helper function in subscriber.py to centralize and apply the acknowledgment logic, considering the new explicit acknack status.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a useful feature to allow explicit acknowledgement (ack) or negative acknowledgement (nack) of messages within the subscriber callback, overriding the default behavior. The implementation is sound, adding a state to SubscriberMessage and a helper function ack_or_nack to handle the logic. My review includes suggestions to improve code clarity and maintainability by renaming the new state variable for better descriptiveness and to simplify some conditional logic for better readability.