foreign/python/apache_iggy.pyi

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405

import asyncio
import builtins
import collections.abc
import datetime
import enum
import typing

__all__ = [
    "AutoCommit",
    "AutoCommitAfter",
    "AutoCommitWhen",
    "ConsumerGroup",
    "ConsumerGroupDetails",
    "ConsumerGroupMember",
    "GlobalPermissions",
    "IggyClient",
    "IggyConsumer",
    "Permissions",
    "PollingStrategy",
    "ReceiveMessage",
    "SendMessage",
    "StreamDetails",
    "StreamPermissions",
    "Topic",
    "TopicDetails",
    "TopicPermissions",
    "UserInfo",
    "UserInfoDetails",
    "UserStatus",
]

class AutoCommit:
    r"""
    The auto-commit configuration for storing the offset on the server.
    """
    @typing.final
    class Disabled(AutoCommit):
        r"""
        The auto-commit is disabled and the offset must be stored manually by the consumer.
        """

        __match_args__ = ()
        def __new__(cls) -> AutoCommit.Disabled: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    @typing.final
    class Interval(AutoCommit):
        r"""
        The auto-commit is enabled and the offset is stored on the server after a certain interval.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> datetime.timedelta: ...
        def __new__(cls, _0: datetime.timedelta) -> AutoCommit.Interval: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    @typing.final
    class IntervalOrWhen(AutoCommit):
        r"""
        The auto-commit is enabled and the offset is stored on the server after a certain interval or depending on the mode when consuming the messages.
        """

        __match_args__ = (
            "_0",
            "_1",
        )
        @property
        def _0(self) -> datetime.timedelta: ...
        @property
        def _1(self) -> AutoCommitWhen: ...
        def __new__(
            cls, _0: datetime.timedelta, _1: AutoCommitWhen
        ) -> AutoCommit.IntervalOrWhen: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    @typing.final
    class IntervalOrAfter(AutoCommit):
        r"""
        The auto-commit is enabled and the offset is stored on the server after a certain interval or depending on the mode after consuming the messages.
        """

        __match_args__ = (
            "_0",
            "_1",
        )
        @property
        def _0(self) -> datetime.timedelta: ...
        @property
        def _1(self) -> AutoCommitAfter: ...
        def __new__(
            cls, _0: datetime.timedelta, _1: AutoCommitAfter
        ) -> AutoCommit.IntervalOrAfter: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    @typing.final
    class When(AutoCommit):
        r"""
        The auto-commit is enabled and the offset is stored on the server depending on the mode when consuming the messages.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> AutoCommitWhen: ...
        def __new__(cls, _0: AutoCommitWhen) -> AutoCommit.When: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    @typing.final
    class After(AutoCommit):
        r"""
        The auto-commit is enabled and the offset is stored on the server depending on the mode after consuming the messages.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> AutoCommitAfter: ...
        def __new__(cls, _0: AutoCommitAfter) -> AutoCommit.After: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    ...

class AutoCommitAfter:
    r"""
    The auto-commit mode for storing the offset on the server **after** receiving the messages.
    """
    @typing.final
    class ConsumingAllMessages(AutoCommitAfter):
        r"""
        The offset is stored on the server after all the messages are consumed.
        """

        __match_args__ = ()
        def __new__(cls) -> AutoCommitAfter.ConsumingAllMessages: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    @typing.final
    class ConsumingEachMessage(AutoCommitAfter):
        r"""
        The offset is stored on the server after consuming each message.
        """

        __match_args__ = ()
        def __new__(cls) -> AutoCommitAfter.ConsumingEachMessage: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    @typing.final
    class ConsumingEveryNthMessage(AutoCommitAfter):
        r"""
        The offset is stored on the server after consuming every Nth message.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> builtins.int: ...
        def __new__(
            cls, _0: builtins.int
        ) -> AutoCommitAfter.ConsumingEveryNthMessage: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    ...

class AutoCommitWhen:
    r"""
    The auto-commit mode for storing the offset on the server.
    """
    @typing.final
    class PollingMessages(AutoCommitWhen):
        r"""
        The offset is stored on the server when the messages are received.
        """

        __match_args__ = ()
        def __new__(cls) -> AutoCommitWhen.PollingMessages: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    @typing.final
    class ConsumingAllMessages(AutoCommitWhen):
        r"""
        The offset is stored on the server when all the messages are consumed.
        """

        __match_args__ = ()
        def __new__(cls) -> AutoCommitWhen.ConsumingAllMessages: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    @typing.final
    class ConsumingEachMessage(AutoCommitWhen):
        r"""
        The offset is stored on the server when consuming each message.
        """

        __match_args__ = ()
        def __new__(cls) -> AutoCommitWhen.ConsumingEachMessage: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    @typing.final
    class ConsumingEveryNthMessage(AutoCommitWhen):
        r"""
        The offset is stored on the server when consuming every Nth message.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> builtins.int: ...
        def __new__(
            cls, _0: builtins.int
        ) -> AutoCommitWhen.ConsumingEveryNthMessage: ...
        def __len__(self) -> builtins.int: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...

    ...

@typing.final
class ConsumerGroup:
    @property
    def id(self) -> builtins.int:
        r"""
        Gets the unique identifier (numeric) of the consumer group.
        """
    @property
    def name(self) -> builtins.str:
        r"""
        Gets the name of the consumer group.
        """
    @property
    def partitions_count(self) -> builtins.int:
        r"""
        Gets the number of partitions the consumer group is consuming.
        """
    @property
    def members_count(self) -> builtins.int:
        r"""
        Gets the number of members in the consumer group.
        """

@typing.final
class ConsumerGroupDetails:
    @property
    def id(self) -> builtins.int:
        r"""
        Gets the unique identifier (numeric) of the consumer group.
        """
    @property
    def name(self) -> builtins.str:
        r"""
        Gets the name of the consumer group.
        """
    @property
    def partitions_count(self) -> builtins.int:
        r"""
        Gets the number of partitions the consumer group is consuming.
        """
    @property
    def members_count(self) -> builtins.int:
        r"""
        Gets the number of members in the consumer group.
        """
    @property
    def members(self) -> builtins.list[ConsumerGroupMember]:
        r"""
        Gets the collection of members in the consumer group.
        """

@typing.final
class ConsumerGroupMember:
    @property
    def id(self) -> builtins.int:
        r"""
        Gets the unique identifier (numeric) of the consumer group member.
        """
    @property
    def partitions_count(self) -> builtins.int:
        r"""
        Gets the number of partitions the consumer group member is consuming.
        """
    @property
    def partitions(self) -> builtins.list[builtins.int]:
        r"""
        Gets the collection of partitions the consumer group member is consuming.
        """

@typing.final
class GlobalPermissions:
    r"""
    Global permissions, applied to all streams without specifying them one by one.
    """
    @property
    def manage_servers(self) -> builtins.bool:
        r"""
        Whether managing servers is allowed; includes `read_servers`.
        """
    @property
    def read_servers(self) -> builtins.bool:
        r"""
        Whether reading server info (stats, clients) is allowed.
        """
    @property
    def manage_users(self) -> builtins.bool:
        r"""
        Whether managing users is allowed; includes `read_users`.
        """
    @property
    def read_users(self) -> builtins.bool:
        r"""
        Whether reading user info is allowed.
        """
    @property
    def manage_streams(self) -> builtins.bool:
        r"""
        Whether managing all streams is allowed; includes `read_streams` and
        `manage_topics`.
        """
    @property
    def read_streams(self) -> builtins.bool:
        r"""
        Whether reading all streams is allowed; includes `read_topics`.
        """
    @property
    def manage_topics(self) -> builtins.bool:
        r"""
        Whether managing all topics is allowed; includes `read_topics` and
        `send_messages`.
        """
    @property
    def read_topics(self) -> builtins.bool:
        r"""
        Whether reading all topics and managing consumer groups is allowed;
        includes `poll_messages`.
        """
    @property
    def poll_messages(self) -> builtins.bool:
        r"""
        Whether polling messages from all streams and managing consumer
        offsets is allowed.
        """
    @property
    def send_messages(self) -> builtins.bool:
        r"""
        Whether sending messages to all streams is allowed.
        """
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __new__(
        cls,
        *,
        manage_servers: builtins.bool = False,
        read_servers: builtins.bool = False,
        manage_users: builtins.bool = False,
        read_users: builtins.bool = False,
        manage_streams: builtins.bool = False,
        read_streams: builtins.bool = False,
        manage_topics: builtins.bool = False,
        read_topics: builtins.bool = False,
        poll_messages: builtins.bool = False,
        send_messages: builtins.bool = False,
    ) -> GlobalPermissions:
        r"""
        Create global permissions. Every flag defaults to `False`.

        The `includes` notes below are transitive: a flag also grants everything
        its included flags grant. For example `manage_streams` includes
        `manage_topics`, and through it `read_topics`, `poll_messages`, and
        `send_messages`.

        Args:
            manage_servers: Allow managing servers; includes `read_servers`.
            read_servers: Allow reading server info (stats, clients).
            manage_users: Allow managing users; includes `read_users`.
            read_users: Allow reading user info.
            manage_streams: Allow managing all streams; includes `read_streams`
                and `manage_topics`.
            read_streams: Allow reading all streams; includes `read_topics`.
            manage_topics: Allow managing all topics; includes `read_topics`
                and `send_messages`.
            read_topics: Allow reading all topics and managing consumer groups
                (including create and delete); includes `poll_messages`.
            poll_messages: Allow polling messages from all streams and managing
                consumer offsets.
            send_messages: Allow sending messages to all streams.
        """

@typing.final
class IggyClient:
    r"""
    A Python class representing the Iggy client.
    It wraps the RustIggyClient and provides asynchronous functionality
    through the contained runtime.
    """
    def __new__(cls, conn: builtins.str | None = None) -> IggyClient:
        r"""
        Constructs a new IggyClient from a TCP server address.
        This initializes a new runtime for asynchronous operations.
        Future versions might utilize asyncio for more Pythonic async.
        """
    @classmethod
    def from_connection_string(cls, connection_string: builtins.str) -> IggyClient:
        r"""
        Constructs a new IggyClient from a connection string.
        Returns an error if the connection string provided is invalid.
        """
    def ping(self) -> collections.abc.Awaitable[None]:
        r"""
        Sends a ping request to the server to check connectivity.
        Returns `Ok(())` if the server responds successfully, or a `PyRuntimeError`
        if the connection fails.
        """
    def login_user(
        self, username: builtins.str, password: builtins.str
    ) -> collections.abc.Awaitable[None]:
        r"""
        Logs in the user with the given credentials.
        Returns `Ok(())` on success, or a PyRuntimeError on failure.
        """
    def get_user(
        self, user_id: builtins.str | builtins.int
    ) -> collections.abc.Awaitable[UserInfoDetails | None]:
        r"""
        Get the info about a specific user by unique ID or username.

        Args:
            user_id: User identifier as `str | int`.

        Returns:
            An awaitable that resolves to `UserInfoDetails` if the user exists,
            or `None` otherwise.

        Raises:
            PyValueError: If a string identifier is invalid.
            PyRuntimeError: If the request fails.
        """
    def get_users(self) -> collections.abc.Awaitable[list[UserInfo]]:
        r"""
        Get the info about all the users.

        Returns:
            An awaitable that resolves to `list[UserInfo]`.

        Raises:
            PyRuntimeError: If the request fails.
        """
    def create_user(
        self,
        username: builtins.str,
        password: builtins.str,
        status: UserStatus | None = None,
        permissions: Permissions | None = None,
    ) -> collections.abc.Awaitable[UserInfoDetails]:
        r"""
        Create a new user.

        Args:
            username: Username as `str`.
            password: Password as `str`.
            status: User status as `UserStatus | None`; defaults to `UserStatus.Active`.
            permissions: Permissions as `Permissions | None`; the user has none when `None`.

        Returns:
            An awaitable that resolves to the created `UserInfoDetails`.

        Raises:
            PyRuntimeError: If an argument is invalid or the request fails.
        """
    def update_user(
        self,
        user_id: builtins.str | builtins.int,
        username: builtins.str | None = None,
        status: UserStatus | None = None,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Update a user by unique ID or username.

        Args:
            user_id: User identifier as `str | int`.
            username: New username as `str | None`; unchanged when `None`.
            status: New status as `UserStatus | None`; unchanged when `None`.

        Returns:
            An awaitable that resolves to `None` when the user is updated.

        Raises:
            PyValueError: If a string identifier is invalid.
            PyRuntimeError: If the request fails.
        """
    def delete_user(
        self, user_id: builtins.str | builtins.int
    ) -> collections.abc.Awaitable[None]:
        r"""
        Delete a user by unique ID or username.

        Args:
            user_id: User identifier as `str | int`.

        Returns:
            An awaitable that resolves to `None` when the user is deleted.

        Raises:
            PyValueError: If a string identifier is invalid.
            PyRuntimeError: If the request fails.
        """
    def update_permissions(
        self, user_id: builtins.str | builtins.int, permissions: Permissions | None
    ) -> collections.abc.Awaitable[None]:
        r"""
        Update the permissions of a user by unique ID or username.

        This is a full replacement: the given permissions overwrite the previous
        ones, and `None` removes them entirely.

        Args:
            user_id: User identifier as `str | int`.
            permissions: New permissions as `Permissions | None`.

        Returns:
            An awaitable that resolves to `None` when the permissions are updated.

        Raises:
            PyValueError: If a string identifier is invalid.
            PyRuntimeError: If the request fails.
        """
    def change_password(
        self,
        user_id: builtins.str | builtins.int,
        current_password: builtins.str,
        new_password: builtins.str,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Change the password of a user by unique ID or username.

        Args:
            user_id: User identifier as `str | int`.
            current_password: Current password as `str`.
            new_password: New password as `str`.

        Returns:
            An awaitable that resolves to `None` when the password is changed.

        Raises:
            PyValueError: If a string identifier is invalid.
            PyRuntimeError: If the current password is wrong or the request fails.
        """
    def logout_user(self) -> collections.abc.Awaitable[None]:
        r"""
        Log out the currently authenticated user.

        Returns:
            An awaitable that resolves to `None` when the user is logged out.

        Raises:
            PyRuntimeError: If the request fails.
        """
    def connect(self) -> collections.abc.Awaitable[None]:
        r"""
        Connects the IggyClient to its service.
        Returns Ok(()) on successful connection or a PyRuntimeError on failure.
        """
    def create_stream(self, name: builtins.str) -> collections.abc.Awaitable[None]:
        r"""
        Creates a new stream with the provided ID and name.
        Returns Ok(()) on successful stream creation or a PyRuntimeError on failure.
        """
    def get_stream(
        self, stream_id: builtins.str | builtins.int
    ) -> collections.abc.Awaitable[StreamDetails | None]:
        r"""
        Gets stream by id.
        Returns Option of stream details or a PyRuntimeError on failure.
        """
    def create_topic(
        self,
        stream: builtins.str | builtins.int,
        name: builtins.str,
        partitions_count: builtins.int,
        compression_algorithm: builtins.str | None = None,
        replication_factor: builtins.int | None = None,
        message_expiry: datetime.timedelta | None = None,
        max_topic_size: builtins.int | None = None,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Creates a new topic with the given parameters.
        Returns Ok(()) on successful topic creation or a PyRuntimeError on failure.
        """
    def get_topic(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
    ) -> collections.abc.Awaitable[TopicDetails | None]:
        r"""
        Gets topic by stream and id.
        Returns Option of topic details or a PyRuntimeError on failure.
        """
    def get_topics(
        self, stream_id: builtins.str | builtins.int
    ) -> collections.abc.Awaitable[list[Topic]]:
        r"""
        Get all topics in a stream.

        Args:
            stream_id: Stream identifier as `str | int`.

        Returns:
            An awaitable that resolves to `list[Topic]`.

        Raises:
            PyRuntimeError: If the identifier is invalid or the request fails.
        """
    def update_topic(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
        name: builtins.str,
        compression_algorithm: builtins.str | None = None,
        replication_factor: builtins.int | None = None,
        message_expiry: datetime.timedelta | None = None,
        max_topic_size: builtins.int | None = None,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Update an existing topic.

        This is a full replacement: any optional parameter left unset is reset to
        its server default rather than preserved.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.
            name: New topic name as `str`.
            compression_algorithm: Compression algorithm as `str | None`.
            replication_factor: Replication factor as `int | None`.
            message_expiry: Message expiry as `datetime.timedelta | None`.
            max_topic_size: Maximum topic size in bytes as `int | None`.

        Returns:
            An awaitable that resolves to `None` when the topic is updated.

        Raises:
            PyRuntimeError: If an argument is invalid or the request fails.
        """
    def delete_topic(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Delete a topic from a stream.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.

        Returns:
            An awaitable that resolves to `None` when the topic is deleted.

        Raises:
            PyRuntimeError: If an identifier is invalid or the request fails.
        """
    def purge_topic(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Purge all messages from a topic.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.

        Returns:
            An awaitable that resolves to `None` when the topic is purged.

        Raises:
            PyRuntimeError: If an identifier is invalid or the request fails.
        """
    def create_consumer_group(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
        name: builtins.str,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Create a consumer group for a stream and topic.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.
            name: Consumer group name as `str`.

        Returns:
            An awaitable that resolves to `None` when the consumer group is created.

        Raises:
            PyValueError: If an identifier is invalid.
            PyRuntimeError: If the request fails.
        """
    def get_consumer_group(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
        group_id: builtins.str | builtins.int,
    ) -> collections.abc.Awaitable[ConsumerGroupDetails | None]:
        r"""
        Retrieve details for a consumer group from the specified stream and topic.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.
            group_id: Consumer group identifier as `str | int`.

        Returns:
            An awaitable that resolves to `ConsumerGroupDetails` if the consumer group exists,
            or `None` otherwise.

        Raises:
            PyValueError: If an identifier is invalid.
            PyRuntimeError: If the request fails.
        """
    def get_consumer_groups(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
    ) -> collections.abc.Awaitable[list[ConsumerGroup]]:
        r"""
        Get all consumer groups for the specified stream and topic.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.

        Returns:
            An awaitable that resolves to `list[ConsumerGroup]`.

        Raises:
            PyValueError: If an identifier is invalid.
            PyRuntimeError: If the request fails.
        """
    def delete_consumer_group(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
        group_id: builtins.str | builtins.int,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Delete a consumer group for a stream and topic.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.
            group_id: Consumer group identifier as `str | int`.

        Returns:
            An awaitable that resolves to `None` when the consumer group is deleted.

        Raises:
            PyValueError: If a string identifier is invalid.
            PyRuntimeError: If the request fails.
        """
    def join_consumer_group(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
        group_id: builtins.str | builtins.int,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Join a consumer group for a stream and topic.

        This method only registers the current client as a group member. To consume messages
        as a group, use `consumer_group()`, which enables auto-join by default.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.
            group_id: Consumer group identifier as `str | int`.

        Returns:
            An awaitable that resolves to `None` when the client joins the consumer group.

        Raises:
            PyValueError: If a string identifier is invalid.
            PyRuntimeError: If the request fails, including `Feature is unavailable` on HTTP transport.
        """
    def leave_consumer_group(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
        group_id: builtins.str | builtins.int,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Leave a consumer group for a stream and topic.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.
            group_id: Consumer group identifier as `str | int`.

        Returns:
            An awaitable that resolves to `None` when the client leaves the consumer group.

        Note:
            Consumers created from this client for the same group share one server-side
            membership. Leaving revokes that membership. Consumers with auto-join enabled
            rejoin on their next poll.

        Raises:
            PyValueError: If a string identifier is invalid.
            PyRuntimeError: If the request fails, including `Feature is unavailable` on HTTP transport.
        """
    def send_messages(
        self,
        stream: builtins.str | builtins.int,
        topic: builtins.str | builtins.int,
        partitioning: builtins.int,
        messages: list[SendMessage],
    ) -> collections.abc.Awaitable[None]:
        r"""
        Sends a list of messages to the specified topic.
        Returns Ok(()) on successful sending or a PyRuntimeError on failure.
        """
    def poll_messages(
        self,
        stream: builtins.str | builtins.int,
        topic: builtins.str | builtins.int,
        partition_id: builtins.int,
        polling_strategy: PollingStrategy,
        count: builtins.int,
        auto_commit: builtins.bool,
    ) -> collections.abc.Awaitable[list[ReceiveMessage]]:
        r"""
        Polls for messages from the specified topic and partition.
        Returns a list of received messages or a PyRuntimeError on failure.
        """
    def consumer_group(
        self,
        name: builtins.str,
        stream: builtins.str,
        topic: builtins.str,
        partition_id: builtins.int | None = None,
        polling_strategy: PollingStrategy | None = None,
        batch_length: builtins.int | None = None,
        auto_commit: AutoCommit | None = None,
        create_consumer_group_if_not_exists: builtins.bool = True,
        auto_join_consumer_group: builtins.bool = True,
        poll_interval: datetime.timedelta | None = None,
        polling_retry_interval: datetime.timedelta | None = None,
        init_retries: builtins.int | None = None,
        init_retry_interval: datetime.timedelta | None = None,
        allow_replay: builtins.bool = False,
    ) -> collections.abc.Awaitable[IggyConsumer]:
        r"""
        Creates a new consumer group consumer.
        Returns the consumer or a PyRuntimeError on failure.
        """
    def send_binary_request(
        self, code: builtins.int, payload: builtins.bytes
    ) -> collections.abc.Awaitable[bytes]:
        r"""
        Send a command code with a payload and return the raw response bytes.

        Session-control codes are rejected client-side. HTTP transport does not
        support raw binary commands.

        Args:
            code: Command code as `int`.
            payload: Request payload as `bytes`.

        Returns:
            An awaitable that resolves to the raw response `bytes`.

        Raises:
            PyRuntimeError: If the command cannot be sent or the server returns an error.
        """

@typing.final
class IggyConsumer:
    r"""
    A Python class representing the Iggy consumer.
    It wraps the RustIggyConsumer and provides asynchronous functionality
    through the contained runtime.
    """
    def get_last_consumed_offset(
        self, partition_id: builtins.int
    ) -> builtins.int | None:
        r"""
        Get the last consumed offset or `None` if no offset has been consumed yet.
        """
    def get_last_stored_offset(self, partition_id: builtins.int) -> builtins.int | None:
        r"""
        Get the last stored offset or `None` if no offset has been stored yet.
        """
    def name(self) -> builtins.str:
        r"""
        Gets the name of the consumer group.
        """
    def partition_id(self) -> builtins.int:
        r"""
        Gets the current partition id or `0` if no messages have been polled yet.
        """
    def stream(self) -> builtins.str | builtins.int:
        r"""
        Gets the name of the stream this consumer group is configured for.
        """
    def topic(self) -> builtins.str | builtins.int:
        r"""
        Gets the name of the topic this consumer group is configured for.
        """
    def store_offset(
        self, offset: builtins.int, partition_id: builtins.int | None
    ) -> collections.abc.Awaitable[None]:
        r"""
        Stores the provided offset for the provided partition id or if none is specified
        uses the current partition id for the consumer group.
        Returns `Ok(())` if the server responds successfully, or a `PyRuntimeError`
        if the operation fails.
        """
    def delete_offset(
        self, partition_id: builtins.int | None
    ) -> collections.abc.Awaitable[None]:
        r"""
        Deletes the offset for the provided partition id or if none is specified
        uses the current partition id for the consumer group.
        Returns `Ok(())` if the server responds successfully, or a `PyRuntimeError`
        if the operation fails.
        """
    def iter_messages(self) -> collections.abc.AsyncIterator[ReceiveMessage]:
        r"""
        Asynchronously iterate over `ReceiveMessage`s.
        Returns an async iterator that raises `StopAsyncIteration` when no more messages are available
        or a `PyRuntimeError` on failure.
        Note: This method does not currently support `AutoCommit.After`.
        For `AutoCommit.IntervalOrAfter(datetime.timedelta, AutoCommitAfter)`,
        only the interval part is applied; the `after` mode is ignored.
        Use `consume_messages()` if you need commit-after-processing semantics.
        """
    def consume_messages(
        self,
        callback: collections.abc.Callable[
            [ReceiveMessage], collections.abc.Awaitable[None]
        ],
        shutdown_event: asyncio.Event | None,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Consumes messages continuously using a callback function and an optional `asyncio.Event` for signaling shutdown.
        Returns an awaitable that completes when shutdown is signaled or a PyRuntimeError on failure.
        """

@typing.final
class Permissions:
    r"""
    The permissions of a user: global permissions applied to all streams,
    optionally extended by per-stream permissions.
    """
    @property
    def global_permissions(self) -> GlobalPermissions:
        r"""
        The global permissions, applied to all streams.
        """
    @property
    def streams(self) -> dict[int, StreamPermissions] | None:
        r"""
        The per-stream permissions keyed by stream ID, or `None` when not set.
        """
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __new__(
        cls,
        global_permissions: GlobalPermissions | None = None,
        streams: dict[int, StreamPermissions] | None = None,
    ) -> Permissions:
        r"""
        Create permissions from global permissions and optional per-stream permissions.

        Args:
            global_permissions: Global permissions as `GlobalPermissions | None`;
                defaults to all denied.
            streams: Per-stream permissions keyed by stream ID as
                `dict[int, StreamPermissions] | None`; an empty dict is
                treated as `None`.
        """

class PollingStrategy:
    @typing.final
    class Offset(PollingStrategy):
        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> PollingStrategy.Offset: ...

    @typing.final
    class Timestamp(PollingStrategy):
        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> PollingStrategy.Timestamp: ...

    @typing.final
    class First(PollingStrategy):
        __match_args__ = ()
        def __new__(cls) -> PollingStrategy.First: ...

    @typing.final
    class Last(PollingStrategy):
        __match_args__ = ()
        def __new__(cls) -> PollingStrategy.Last: ...

    @typing.final
    class Next(PollingStrategy):
        __match_args__ = ()
        def __new__(cls) -> PollingStrategy.Next: ...

    ...

@typing.final
class ReceiveMessage:
    r"""
    A Python class representing a received message.
    This class wraps a Rust message, allowing for access to its payload and offset from Python.
    """
    def payload(self) -> bytes:
        r"""
        Retrieves the payload of the received message.
        The payload is returned as a Python bytes object.
        """
    def offset(self) -> builtins.int:
        r"""
        Retrieves the offset of the received message.
        The offset represents the position of the message within its topic.
        """
    def timestamp(self) -> builtins.int:
        r"""
        Retrieves the timestamp of the received message.
        The timestamp represents the time of the message within its topic.
        """
    def id(self) -> builtins.int:
        r"""
        Retrieves the id of the received message.
        The id represents unique identifier of the message within its topic.
        """
    def checksum(self) -> builtins.int:
        r"""
        Retrieves the checksum of the received message.
        The checksum represents the integrity of the message within its topic.
        """
    def length(self) -> builtins.int:
        r"""
        Retrieves the length of the received message.
        The length represents the length of the payload.
        """
    def partition_id(self) -> builtins.int:
        r"""
        Retrieves the partition this message belongs to.
        """

@typing.final
class SendMessage:
    r"""
    A Python class representing a message to be sent.
    This class wraps a Rust message meant for sending, facilitating
    the creation of such messages from Python and their subsequent use in Rust.
    """
    def __new__(cls, data: builtins.str | bytes) -> SendMessage:
        r"""
        Constructs a new `SendMessage` instance from a string or bytes.
        This method allows for the creation of a `SendMessage` instance
        directly from Python using the provided string or bytes data.
        """

@typing.final
class StreamDetails:
    @property
    def id(self) -> builtins.int: ...
    @property
    def name(self) -> builtins.str: ...
    @property
    def messages_count(self) -> builtins.int: ...
    @property
    def topics_count(self) -> builtins.int: ...

@typing.final
class StreamPermissions:
    r"""
    Permissions for a specific stream and all its topics, optionally refined per topic.
    They extend the global permissions, they do not override them.
    """
    @property
    def manage_stream(self) -> builtins.bool:
        r"""
        Whether managing the stream is allowed; includes `read_stream` and
        `manage_topics`.
        """
    @property
    def read_stream(self) -> builtins.bool:
        r"""
        Whether reading the stream is allowed; includes `read_topics`.
        """
    @property
    def manage_topics(self) -> builtins.bool:
        r"""
        Whether managing the stream topics is allowed; includes `read_topics`
        and `send_messages`.
        """
    @property
    def read_topics(self) -> builtins.bool:
        r"""
        Whether reading the stream topics and managing their consumer groups
        is allowed; includes `poll_messages`.
        """
    @property
    def poll_messages(self) -> builtins.bool:
        r"""
        Whether polling messages from the stream and managing its consumer
        offsets is allowed.
        """
    @property
    def send_messages(self) -> builtins.bool:
        r"""
        Whether sending messages to the stream is allowed.
        """
    @property
    def topics(self) -> dict[int, TopicPermissions] | None:
        r"""
        The per-topic permissions keyed by topic ID, or `None` when not set.
        """
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __new__(
        cls,
        *,
        manage_stream: builtins.bool = False,
        read_stream: builtins.bool = False,
        manage_topics: builtins.bool = False,
        read_topics: builtins.bool = False,
        poll_messages: builtins.bool = False,
        send_messages: builtins.bool = False,
        topics: dict[int, TopicPermissions] | None = None,
    ) -> StreamPermissions:
        r"""
        Create stream permissions. Every flag defaults to `False`.

        The `includes` notes below are transitive: a flag also grants everything
        its included flags grant. For example `manage_stream` includes
        `manage_topics`, and through it `read_topics`, `poll_messages`, and
        `send_messages`.

        Args:
            manage_stream: Allow managing the stream; includes `read_stream`
                and `manage_topics`.
            read_stream: Allow reading the stream; includes `read_topics`.
            manage_topics: Allow managing the stream topics; includes
                `read_topics` and `send_messages`.
            read_topics: Allow reading the stream topics and managing their
                consumer groups (including create and delete); includes
                `poll_messages`.
            poll_messages: Allow polling messages from the stream and managing
                its consumer offsets.
            send_messages: Allow sending messages to the stream.
            topics: Per-topic permissions keyed by topic ID as
                `dict[int, TopicPermissions] | None`; an empty dict is
                treated as `None`.
        """

@typing.final
class Topic:
    @property
    def id(self) -> builtins.int:
        r"""
        The unique identifier (numeric) of the topic.
        """
    @property
    def name(self) -> builtins.str:
        r"""
        The unique name of the topic.
        """
    @property
    def messages_count(self) -> builtins.int:
        r"""
        The total number of messages in the topic.
        """
    @property
    def partitions_count(self) -> builtins.int:
        r"""
        The total number of partitions in the topic.
        """

@typing.final
class TopicDetails:
    @property
    def id(self) -> builtins.int:
        r"""
        The unique identifier (numeric) of the topic.
        """
    @property
    def name(self) -> builtins.str:
        r"""
        The unique name of the topic.
        """
    @property
    def messages_count(self) -> builtins.int:
        r"""
        The total number of messages in the topic.
        """
    @property
    def partitions_count(self) -> builtins.int:
        r"""
        The total number of partitions in the topic.
        """
    @property
    def compression_algorithm(self) -> builtins.str:
        r"""
        Compression algorithm for the topic.
        """
    @property
    def replication_factor(self) -> builtins.int:
        r"""
        Replication factor for the topic.
        """

@typing.final
class TopicPermissions:
    r"""
    Permissions for a specific topic of a stream. The lowest level of permissions.
    They extend the stream and global permissions, they do not override them.
    """
    @property
    def manage_topic(self) -> builtins.bool:
        r"""
        Whether managing the topic is allowed; includes `read_topic` and
        `send_messages`.
        """
    @property
    def read_topic(self) -> builtins.bool:
        r"""
        Whether reading the topic and managing its consumer groups is allowed;
        includes `poll_messages`.
        """
    @property
    def poll_messages(self) -> builtins.bool:
        r"""
        Whether polling messages from the topic and managing its consumer
        offsets is allowed.
        """
    @property
    def send_messages(self) -> builtins.bool:
        r"""
        Whether sending messages to the topic is allowed.
        """
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __new__(
        cls,
        *,
        manage_topic: builtins.bool = False,
        read_topic: builtins.bool = False,
        poll_messages: builtins.bool = False,
        send_messages: builtins.bool = False,
    ) -> TopicPermissions:
        r"""
        Create topic permissions. Every flag defaults to `False`.

        The `includes` notes below are transitive: a flag also grants everything
        its included flags grant. For example `manage_topic` includes
        `read_topic` and `send_messages`, and through `read_topic` also
        `poll_messages`.

        Args:
            manage_topic: Allow managing the topic; includes `read_topic` and
                `send_messages`.
            read_topic: Allow reading the topic and managing its consumer
                groups (including create and delete); includes `poll_messages`.
            poll_messages: Allow polling messages from the topic and managing
                its consumer offsets.
            send_messages: Allow sending messages to the topic.
        """

@typing.final
class UserInfo:
    @property
    def id(self) -> builtins.int:
        r"""
        The unique identifier (numeric) of the user.
        """
    @property
    def created_at(self) -> builtins.int:
        r"""
        The timestamp when the user was created, in microseconds since the Unix epoch.
        """
    @property
    def status(self) -> UserStatus:
        r"""
        The status of the user.
        """
    @property
    def username(self) -> builtins.str:
        r"""
        The username of the user.
        """

@typing.final
class UserInfoDetails:
    @property
    def id(self) -> builtins.int:
        r"""
        The unique identifier (numeric) of the user.
        """
    @property
    def created_at(self) -> builtins.int:
        r"""
        The timestamp when the user was created, in microseconds since the Unix epoch.
        """
    @property
    def status(self) -> UserStatus:
        r"""
        The status of the user.
        """
    @property
    def username(self) -> builtins.str:
        r"""
        The username of the user.
        """
    @property
    def permissions(self) -> Permissions | None:
        r"""
        The permissions of the user, or `None` when the user has none assigned.
        """

@typing.final
class UserStatus(enum.Enum):
    r"""
    The status of a user account.
    """

    Active = ...
    r"""
    The user account is active and can be used.
    """
    Inactive = ...
    r"""
    The user account is inactive and cannot be used.
    """