Skip to content
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

Consumer.offsets_for_times return type documentation is incomplete. #1067

Closed
jzvandenoever opened this issue Oct 30, 2024 · 0 comments · Fixed by #1068
Closed

Consumer.offsets_for_times return type documentation is incomplete. #1067

jzvandenoever opened this issue Oct 30, 2024 · 0 comments · Fixed by #1068

Comments

@jzvandenoever
Copy link
Contributor

jzvandenoever commented Oct 30, 2024

Describe the bug
Currently the return type documentation for the offsets_for_times function is:

Returns:
            dict(TopicPartition, OffsetAndTimestamp): mapping from
            partition to the timestamp and offset of the first message with
            timestamp greater than or equal to the target timestamp.

See https://aiokafka.readthedocs.io/en/stable/api.html#aiokafka.AIOKafkaConsumer.offsets_for_times
The most recent kafka javadocs for this function state:

a mapping from partition to the timestamp and offset of the first message with timestamp greater than
or equal to the target timestamp. null will be returned for the partition if there is no such message.

See https://kafka.apache.org/38/javadoc/org/apache/kafka/clients/consumer/KafkaConsumer.html#offsetsForTimes(java.util.Map)

It is missing the returns None if there is no message that fulfils the timestamp condition. This is extra confusing because the function description includes a section stating:

If the message format version in a partition is before 0.10.0, i.e.
the messages do not have timestamps, ``None`` will be returned for that
partition.

The docs now say that None only happens if the cluster is dealing with an outdated message format. Rather than it being part of the normal interface.

Expected behaviour
The offsets_for_times documentations is brought in line with the kafka javadocs and the actual behaviour of the function.

Environment (please complete the following information):

  • aiokafka version: 0.12.0
  • Kafka Broker version (kafka-topics.sh --version): Not relevant
  • Other information (Confluent Cloud version, etc.): Not relevant

Reproducible example
Go to https://github.com/aio-libs/aiokafka/blob/master/aiokafka/consumer/consumer.py#L906 and see the docstring.

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

Successfully merging a pull request may close this issue.

1 participant