# 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",
    "AutoLogin",
    "Consumer",
    "ConsumerGroup",
    "ConsumerGroupDetails",
    "ConsumerGroupMember",
    "GlobalPermissions",
    "HeaderKey",
    "HeaderValue",
    "IggyClient",
    "IggyConsumer",
    "IggyExpiry",
    "MaxTopicSize",
    "OptionSpec",
    "Partition",
    "Permissions",
    "PollingStrategy",
    "ReceiveMessage",
    "SendMessage",
    "SendMessagesConfirmation",
    "SendMessagesResponse",
    "StreamDetails",
    "StreamPermissions",
    "TcpConfig",
    "TcpReconnectionConfig",
    "Topic",
    "TopicDetails",
    "TopicPermissions",
    "UserHeaders",
    "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 AutoLogin:
    r"""
    The credentials replayed by the client every time it (re)connects.

    `IggyClient` only recovers a lost session when it has credentials to replay,
    so a long-running consumer should pass one of the enabled variants.
    """
    @property
    def enabled(self) -> builtins.bool:
        r"""
        Whether automatic login is enabled.
        """
    @property
    def username(self) -> builtins.str | None:
        r"""
        The username to log in with, or `None` for the disabled and token variants.
        """
    @staticmethod
    def disabled() -> AutoLogin:
        r"""
        No automatic login. `login_user()` must be called by hand after every connect.
        """
    @staticmethod
    def username_password(username: builtins.str, password: builtins.str) -> AutoLogin:
        r"""
        Log in with the given username and password on every connect.
        """
    @staticmethod
    def personal_access_token(token: builtins.str) -> AutoLogin:
        r"""
        Log in with the given personal access token on every connect.
        """
    def __repr__(self) -> builtins.str: ...

class Consumer:
    r"""
    The consumer polling the messages. It selects both the consumer kind and the
    identifier the server keys the stored offset on.
    """
    @typing.final
    class Single(Consumer):
        r"""
        A regular consumer, owning its offset on the polled partition.
        """

        __match_args__ = ("id",)
        @property
        def id(self) -> builtins.str | builtins.int: ...
        def __new__(cls, id: builtins.str | builtins.int) -> Consumer.Single: ...

    @typing.final
    class Group(Consumer):
        r"""
        A member of the consumer group, sharing the group's offset.
        """

        __match_args__ = ("id",)
        @property
        def id(self) -> builtins.str | builtins.int: ...
        def __new__(cls, id: builtins.str | builtins.int) -> Consumer.Group: ...

    ...

@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.
        """

class HeaderKey:
    r"""
    Typed key for an Iggy user header.

    Use these constructors when the header key must preserve an explicit
    wire type instead of using the common string-key dictionary form.
    """
    def __hash__(self) -> builtins.int: ...
    def __richcmp__(self, other: typing.Any, op: int) -> typing.Any: ...
    def __repr__(self) -> builtins.str: ...
    @typing.final
    class Raw(HeaderKey):
        r"""
        Raw bytes key. The byte length must be 1..=255.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> bytes: ...
        def __new__(cls, value: bytes) -> HeaderKey.Raw: ...

    @typing.final
    class String(HeaderKey):
        r"""
        UTF-8 string key. The encoded byte length must be 1..=255.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.str: ...
        def __new__(cls, value: builtins.str) -> HeaderKey.String: ...

    @typing.final
    class Bool(HeaderKey):
        r"""
        Boolean key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.bool: ...
        def __new__(cls, value: builtins.bool) -> HeaderKey.Bool: ...

    @typing.final
    class Int8(HeaderKey):
        r"""
        Signed 8-bit integer key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderKey.Int8: ...

    @typing.final
    class Int16(HeaderKey):
        r"""
        Signed 16-bit integer key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderKey.Int16: ...

    @typing.final
    class Int32(HeaderKey):
        r"""
        Signed 32-bit integer key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderKey.Int32: ...

    @typing.final
    class Int64(HeaderKey):
        r"""
        Signed 64-bit integer key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderKey.Int64: ...

    @typing.final
    class Int128(HeaderKey):
        r"""
        Signed 128-bit integer key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderKey.Int128: ...

    @typing.final
    class UnsignedInt8(HeaderKey):
        r"""
        Unsigned 8-bit integer key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderKey.UnsignedInt8: ...

    @typing.final
    class UnsignedInt16(HeaderKey):
        r"""
        Unsigned 16-bit integer key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderKey.UnsignedInt16: ...

    @typing.final
    class UnsignedInt32(HeaderKey):
        r"""
        Unsigned 32-bit integer key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderKey.UnsignedInt32: ...

    @typing.final
    class UnsignedInt64(HeaderKey):
        r"""
        Unsigned 64-bit integer key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderKey.UnsignedInt64: ...

    @typing.final
    class UnsignedInt128(HeaderKey):
        r"""
        Unsigned 128-bit integer key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderKey.UnsignedInt128: ...

    @typing.final
    class Float32(HeaderKey):
        r"""
        32-bit floating point key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.float: ...
        def __new__(cls, value: builtins.float) -> HeaderKey.Float32: ...

    @typing.final
    class Float64(HeaderKey):
        r"""
        64-bit floating point key.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.float: ...
        def __new__(cls, value: builtins.float) -> HeaderKey.Float64: ...

class HeaderValue:
    r"""
    Typed value for an Iggy user header.

    Use these constructors when the header value must preserve an explicit
    wire type instead of using the common Python scalar dictionary form.
    """
    def __hash__(self) -> builtins.int: ...
    def __richcmp__(self, other: typing.Any, op: int) -> typing.Any: ...
    def __repr__(self) -> builtins.str: ...
    @typing.final
    class Raw(HeaderValue):
        r"""
        Raw bytes value. The byte length must be 1..=255.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> bytes: ...
        def __new__(cls, value: bytes) -> HeaderValue.Raw: ...

    @typing.final
    class String(HeaderValue):
        r"""
        UTF-8 string value. The encoded byte length must be 1..=255.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.str: ...
        def __new__(cls, value: builtins.str) -> HeaderValue.String: ...

    @typing.final
    class Bool(HeaderValue):
        r"""
        Boolean value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.bool: ...
        def __new__(cls, value: builtins.bool) -> HeaderValue.Bool: ...

    @typing.final
    class Int8(HeaderValue):
        r"""
        Signed 8-bit integer value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderValue.Int8: ...

    @typing.final
    class Int16(HeaderValue):
        r"""
        Signed 16-bit integer value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderValue.Int16: ...

    @typing.final
    class Int32(HeaderValue):
        r"""
        Signed 32-bit integer value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderValue.Int32: ...

    @typing.final
    class Int64(HeaderValue):
        r"""
        Signed 64-bit integer value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderValue.Int64: ...

    @typing.final
    class Int128(HeaderValue):
        r"""
        Signed 128-bit integer value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderValue.Int128: ...

    @typing.final
    class UnsignedInt8(HeaderValue):
        r"""
        Unsigned 8-bit integer value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderValue.UnsignedInt8: ...

    @typing.final
    class UnsignedInt16(HeaderValue):
        r"""
        Unsigned 16-bit integer value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderValue.UnsignedInt16: ...

    @typing.final
    class UnsignedInt32(HeaderValue):
        r"""
        Unsigned 32-bit integer value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderValue.UnsignedInt32: ...

    @typing.final
    class UnsignedInt64(HeaderValue):
        r"""
        Unsigned 64-bit integer value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderValue.UnsignedInt64: ...

    @typing.final
    class UnsignedInt128(HeaderValue):
        r"""
        Unsigned 128-bit integer value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.int: ...
        def __new__(cls, value: builtins.int) -> HeaderValue.UnsignedInt128: ...

    @typing.final
    class Float32(HeaderValue):
        r"""
        32-bit floating point value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.float: ...
        def __new__(cls, value: builtins.float) -> HeaderValue.Float32: ...

    @typing.final
    class Float64(HeaderValue):
        r"""
        64-bit floating point value.
        """

        __match_args__ = ("value",)
        @property
        def value(self) -> builtins.float: ...
        def __new__(cls, value: builtins.float) -> HeaderValue.Float64: ...

@typing.final
class IggyClient:
    r"""
    A Python class representing the Iggy client.
    It provides asynchronous functionality through the contained runtime.
    """
    def __new__(cls, conn: TcpConfig | builtins.str | None = None) -> IggyClient:
        r"""
        Constructs a new IggyClient from a TCP server address or a `TcpConfig`.
        This initializes a new runtime for asynchronous operations.
        Future versions might utilize asyncio for more Pythonic async.

        Args:
            conn: Either a `host:port` address, or a `TcpConfig` carrying the full
                transport configuration. Defaults to `127.0.0.1:8090` with auto-login
                disabled. A malformed address is reported differently by the two
                forms: the string form raises `RuntimeError` here, while `TcpConfig`
                raises `ValueError` when it is constructed, before it ever reaches
                this call. Neither exception is a subclass of the other.

        Raises:
            RuntimeError: If the address passed as a string is not a valid
                `host:port` pair.
        """
    @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.
        Raises `RuntimeError` if the connection fails.
        """
    def describe_options(
        self, scope: builtins.str
    ) -> collections.abc.Awaitable[list[OptionSpec]]:
        r"""
        Describe the option catalog for a resource scope.

        This is the discovery surface for the `options` argument on
        `create_topic`/`update_topic`: a key outside the catalog is refused at
        create, and the binary transports carry only the error code back.

        Args:
            scope: One of `"topic"`, `"stream"`, `"user"`.

        Returns:
            An awaitable that resolves to `list[OptionSpec]`, empty for a scope
            with no keys yet.

        Raises:
            ValueError: If the scope name is not one of the three above.
            RuntimeError: If the request fails.
        """
    def login_user(
        self, username: builtins.str, password: builtins.str
    ) -> collections.abc.Awaitable[None]:
        r"""
        Logs in the user with the given credentials.
        Raises `RuntimeError` 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:
            ValueError: If a string identifier is invalid.
            RuntimeError: 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:
            RuntimeError: 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:
            RuntimeError: 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:
            ValueError: If a string identifier is invalid.
            RuntimeError: 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:
            ValueError: If a string identifier is invalid.
            RuntimeError: 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:
            ValueError: If a string identifier is invalid.
            RuntimeError: 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:
            ValueError: If a string identifier is invalid.
            RuntimeError: 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:
            RuntimeError: If the request fails.
        """
    def connect(self) -> collections.abc.Awaitable[None]:
        r"""
        Connects the IggyClient to its service.
        Raises `RuntimeError` if the connection fails.
        """
    def create_stream(self, name: builtins.str) -> collections.abc.Awaitable[None]:
        r"""
        Creates a new stream with the provided ID and name.
        Raises `RuntimeError` if the stream cannot be created.
        """
    def get_stream(
        self, stream_id: builtins.str | builtins.int
    ) -> collections.abc.Awaitable[StreamDetails | None]:
        r"""
        Gets stream by id.
        Returns the stream details, or `None` if the stream does not exist.
        Raises `RuntimeError` on failure.
        """
    def create_topic(
        self,
        stream: builtins.str | builtins.int,
        name: builtins.str,
        partitions_count: builtins.int,
        compression_algorithm: builtins.str | None = None,
        message_expiry: IggyExpiry | None = None,
        max_topic_size: MaxTopicSize | None = None,
        segment_size: builtins.int | None = None,
        enforce_fsync: builtins.bool | None = None,
        messages_required_to_save: builtins.int | None = None,
        size_of_messages_required_to_save: builtins.int | None = None,
        preallocate_segments: builtins.bool | None = None,
        options: builtins.dict[builtins.str, builtins.str] | None = None,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Creates a new topic with the given parameters.

        Args:
            stream: Stream identifier as `str | int`.
            name: Topic name as `str`.
            partitions_count: Number of partitions as `int`.
            compression_algorithm: Compression algorithm as `str | None`.
            message_expiry: Message expiry as `IggyExpiry | None`.
            max_topic_size: Maximum topic size as `MaxTopicSize | None`.
            segment_size: Per-topic segment size in bytes as `int | None`.
            enforce_fsync: Per-topic fsync enforcement as `bool | None`.
            messages_required_to_save: Message-count flush threshold as `int | None`.
            size_of_messages_required_to_save: Byte flush threshold as `int | None`.
            preallocate_segments: Reserve segment bytes on open as `bool | None`.
            options: Additional option keys as `dict[str, str] | None`, sent
                verbatim so a newer server key can be set from this build.

        Every option left as `None` resolves against the server default at
        admission.

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

        Raises:
            ValueError: If `message_expiry` or `max_topic_size` is out of range.
            PyRuntimeError: If another argument is invalid or the request fails.
        """
    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 the topic details, or `None` if the topic does not exist.
        Raises `RuntimeError` 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:
            RuntimeError: 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,
        message_expiry: IggyExpiry | None = None,
        max_topic_size: MaxTopicSize | None = None,
        options: builtins.dict[builtins.str, builtins.str] | None = None,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Update an existing topic.

        A patch, not a replacement: every setting rides the options block, so a
        field left unset keeps the topic's current value rather than resetting
        it to a server default.

        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`.
            message_expiry: Message expiry as `IggyExpiry | None`.
            max_topic_size: Maximum topic size as `MaxTopicSize | None`.
            options: Additional option keys as `dict[str, str] | None`, sent
                verbatim so an updatable server key can be set from this build.
                A create-only key is refused by name.

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

        Raises:
            ValueError: If `message_expiry` or `max_topic_size` is out of range.
            PyRuntimeError: If another 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:
            RuntimeError: 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:
            RuntimeError: 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:
            ValueError: If an identifier is invalid.
            RuntimeError: 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:
            ValueError: If an identifier is invalid.
            RuntimeError: 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:
            ValueError: If an identifier is invalid.
            RuntimeError: 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:
            ValueError: If a string identifier is invalid.
            RuntimeError: 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:
            ValueError: If a string identifier is invalid.
            RuntimeError: 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:
            ValueError: If a string identifier is invalid.
            RuntimeError: 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[SendMessagesResponse]:
        r"""
        Sends a list of messages to the specified topic.
        Returns a SendMessagesResponse carrying the per-partition commit
        confirmations, or a PyRuntimeError on failure. The confirmation list is
        empty when the server reports no offsets, and the legacy server never
        reports any.
        """
    def poll_messages(
        self,
        stream: builtins.str | builtins.int,
        topic: builtins.str | builtins.int,
        *,
        consumer: Consumer,
        polling_strategy: PollingStrategy,
        count: builtins.int,
        auto_commit: builtins.bool,
        partition_id: builtins.int | None = None,
    ) -> collections.abc.Awaitable[list[ReceiveMessage]]:
        r"""
        Polls for messages from the specified topic on behalf of the given consumer.
        Omitting `partition_id` reads partition 0 for a regular consumer, and
        polls the member's assigned partitions for a consumer group.
        Returns a list of received messages or a RuntimeError 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.
        `partition_id` is ignored for a consumer group: the member reads the partitions
        the server assigns to it.
        Returns the consumer or a RuntimeError on failure. Raises `ValueError` if
        `poll_interval`, `polling_retry_interval`, `init_retry_interval` or an
        `AutoCommit` interval is negative, or if any of those except `poll_interval`
        is zero.
        """
    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:
            RuntimeError: 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 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 for the given partition, or `None` while that partition
        is untracked. Polling starts tracking a partition at `0`, so `0` also means
        "seen, nothing consumed yet".
        """
    def get_last_stored_offset(self, partition_id: builtins.int) -> builtins.int | None:
        r"""
        Get the last stored offset for the given partition, or `None` while that partition is
        untracked. Polling starts tracking a partition at `0`, so `0` also means
        "seen, nothing stored yet", including under `AutoCommit.Disabled()`.
        """
    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 identifier of the stream this consumer group is configured for.
        """
    def topic(self) -> builtins.str | builtins.int:
        r"""
        Gets the identifier 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.
        Raises `RuntimeError` 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.
        Raises `RuntimeError` 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 `RuntimeError` 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 RuntimeError on failure.
        """

class IggyExpiry:
    r"""
    The expiry of the messages in a topic.
    """
    @typing.final
    class ServerDefault(IggyExpiry):
        r"""
        Use the message expiry configured on the server for this topic,
        rather than an explicit value set by the client.
        """

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

    @typing.final
    class ExpireDuration(IggyExpiry):
        r"""
        Expire messages this long after they are appended to the topic.

        `duration` must be greater than zero and less than the maximum
        microsecond count a `u64` can hold (about 584,542 years): those two
        values are reserved on the wire for `ServerDefault` and `NeverExpire`
        respectively, so a `duration` at either boundary raises `ValueError`
        when passed to `create_topic`/`update_topic`. A negative `timedelta`
        also raises `ValueError`.
        """

        __match_args__ = ("duration",)
        @property
        def duration(self) -> datetime.timedelta: ...
        def __new__(cls, duration: datetime.timedelta) -> IggyExpiry.ExpireDuration: ...

    @typing.final
    class NeverExpire(IggyExpiry):
        r"""
        Retain messages indefinitely; they never expire.
        """

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

    ...

class MaxTopicSize:
    r"""
    The maximum size of a topic.
    """
    @typing.final
    class ServerDefault(MaxTopicSize):
        r"""
        Use the maximum topic size configured on the server, rather than an
        explicit value set by the client.
        """

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

    @typing.final
    class Custom(MaxTopicSize):
        r"""
        Cap the topic at this many bytes; as the topic approaches this size,
        the server deletes the oldest sealed segments to make room for new
        messages.

        `bytes` must be greater than zero and less than the maximum value of
        an unsigned 64-bit integer: those two values are reserved on the wire
        for `ServerDefault` and `Unlimited` respectively, so a `Custom` size
        at either boundary raises `ValueError` when passed to
        `create_topic`/`update_topic`.
        """

        __match_args__ = ("bytes",)
        @property
        def bytes(self) -> builtins.int: ...
        def __new__(cls, bytes: builtins.int) -> MaxTopicSize.Custom: ...

    @typing.final
    class Unlimited(MaxTopicSize):
        r"""
        Do not cap the topic size; it may grow without bound.
        """

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

    ...

@typing.final
class OptionSpec:
    r"""
    One entry of a resource's option catalog, as served by `describe_options`.
    """
    @property
    def key(self) -> builtins.str:
        r"""
        The option key a create command accepts.
        """
    @property
    def kind(self) -> builtins.str:
        r"""
        Name of this key's canonical kind: what the server encodes its default
        under, and what a value set by `create_topic` is stored as whatever kind
        it was sent in, since create admission re-encodes the block from its own
        parse. `update_topic` stores what the client sent verbatim and is the
        exception.
        """
    @property
    def default_value(self) -> HeaderValue | None:
        r"""
        The key's default as a `HeaderValue`, or `None` when the key has no
        default.

        The same type message user headers use, so the usual accessors read it;
        options ride that codec.
        """
    @property
    def description(self) -> builtins.str:
        r"""
        What the option does, including the bounds its value is checked against.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class Partition:
    @property
    def id(self) -> builtins.int:
        r"""
        The unique identifier (numeric) of the partition.
        """
    @property
    def created_at(self) -> builtins.int:
        r"""
        The timestamp of the partition creation, in microseconds.
        """
    @property
    def segments_count(self) -> builtins.int:
        r"""
        The number of segments in the partition.
        """
    @property
    def current_offset(self) -> builtins.int:
        r"""
        The current offset of the partition.
        """
    @property
    def size(self) -> builtins.int:
        r"""
        The size of the partition in bytes.
        """
    @property
    def messages_count(self) -> builtins.int:
        r"""
        The number of messages in the partition.
        """

@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.
    It provides access to the message payload and offset.
    """
    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 origin_timestamp(self) -> builtins.int:
        r"""
        Retrieves the origin timestamp of the received message.
        The origin timestamp represents when the message was originally created.
        """
    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.
        """
    def user_headers(self) -> UserHeaders | None:
        r"""
        Retrieves user headers attached to the received message.

        Returns `None` when no headers are present or when the headers
        on the wire are structurally malformed (those errors are logged
        internally). Only known semantic decode errors raise `ValueError`.
        """

@typing.final
class SendMessage:
    r"""
    A Python class representing a message to be sent.
    """
    def __new__(
        cls,
        data: builtins.str | bytes,
        user_headers: dict | None = None,
        id: builtins.int | None = None,
    ) -> 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 SendMessagesConfirmation:
    r"""
    A Python class representing the commit confirmation for one partition
    written by a send.
    """
    @property
    def stream_id(self) -> builtins.int:
        r"""
        Gets the unique identifier (numeric) of the stream the batch was written to.
        """
    @property
    def topic_id(self) -> builtins.int:
        r"""
        Gets the unique identifier (numeric) of the topic the batch was written to.
        """
    @property
    def partition_id(self) -> builtins.int:
        r"""
        Gets the identifier of the partition the batch was written to.
        """
    @property
    def base_offset(self) -> builtins.int:
        r"""
        Gets the offset assigned to the first message of the batch in this partition.

        The offset locates the batch, it does not identify it. Delivery is
        at-least-once, so an earlier retry may already have committed these
        messages at a lower offset.

        A batch is confirmed once it is committed in memory, not once it is
        fsynced. A crash-restart can stamp a later batch with an offset a client
        has already recorded.

        The legacy server confirms nothing, so its confirmation list is empty
        and this value is never reached.
        """

@typing.final
class SendMessagesResponse:
    r"""
    A Python class representing the outcome of a successful send.
    """
    @property
    def confirmations(self) -> builtins.list[SendMessagesConfirmation]:
        r"""
        Gets the commit confirmations, one per partition the batch was written to.

        The list is empty when the server reports no offsets, and the legacy
        server never reports any, so branch on it being empty rather than
        indexing into it.

        A reported `base_offset` never implies uniqueness, because delivery is
        at-least-once and an earlier retry may already have committed the same
        messages at a lower offset. A batch is confirmed once it is committed in
        memory, not once it is fsynced. A crash-restart can stamp a later batch
        with an offset a client has already recorded.
        """

@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 TcpConfig:
    r"""
    Configuration for the TCP transport, accepted by `IggyClient(...)`.

    Every field is keyword-only and optional.
    """
    @property
    def server_address(self) -> builtins.str: ...
    @property
    def auto_login(self) -> AutoLogin: ...
    @property
    def reconnection(self) -> TcpReconnectionConfig: ...
    @property
    def heartbeat_interval(self) -> datetime.timedelta: ...
    @property
    def tls_enabled(self) -> builtins.bool: ...
    @property
    def tls_domain(self) -> builtins.str: ...
    @property
    def tls_ca_file(self) -> builtins.str | None: ...
    @property
    def tls_validate_certificate(self) -> builtins.bool: ...
    @property
    def nodelay(self) -> builtins.bool: ...
    def __new__(
        cls,
        *,
        server_address: builtins.str | None = None,
        auto_login: AutoLogin | None = None,
        reconnection: TcpReconnectionConfig | None = None,
        heartbeat_interval: datetime.timedelta | None = None,
        tls_enabled: builtins.bool | None = None,
        tls_domain: builtins.str | None = None,
        tls_ca_file: builtins.str | None = None,
        tls_validate_certificate: builtins.bool | None = None,
        nodelay: builtins.bool | None = None,
    ) -> TcpConfig:
        r"""
        Constructs a TCP configuration.

        Args:
            server_address: `host:port` of the Iggy server. Defaults to `127.0.0.1:8090`.
            auto_login: Credentials replayed on every connect. Defaults to `AutoLogin.disabled()`.
            reconnection: Reconnection policy. Defaults to `TcpReconnectionConfig()`.
            heartbeat_interval: Interval of heartbeats sent by the client. Defaults to 5 seconds.
            tls_enabled: Whether to connect over TLS. Defaults to disabled.
            tls_domain: Domain to validate the certificate against. Empty means it is
                taken from `server_address`.
            tls_ca_file: Path to the CA file for TLS. Read only when `tls_enabled`
                and `tls_validate_certificate` are both on; with either one off it
                is kept but never consulted, so pairing it with
                `tls_validate_certificate=False` pins nothing.
            tls_validate_certificate: Whether to validate the server certificate.
                Defaults to validating. Disabling this accepts any certificate the
                server presents, including self-signed and mismatched ones, and
                takes precedence over `tls_ca_file`; intended for local development
                only.
            nodelay: Disable the Nagle algorithm for the TCP socket. Defaults to
                leaving it on.

        Raises:
            ValueError: If `server_address` is not a valid `host:port` pair, if a
                duration is negative, or if `heartbeat_interval` is zero.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class TcpReconnectionConfig:
    r"""
    How the TCP client reconnects after the connection to the server is lost.
    """
    @property
    def enabled(self) -> builtins.bool: ...
    @property
    def max_retries(self) -> builtins.int | None: ...
    @property
    def interval(self) -> datetime.timedelta: ...
    @property
    def reestablish_after(self) -> datetime.timedelta: ...
    def __new__(
        cls,
        *,
        enabled: builtins.bool | None = None,
        max_retries: builtins.int | None = None,
        interval: datetime.timedelta | None = None,
        reestablish_after: datetime.timedelta | None = None,
    ) -> TcpReconnectionConfig:
        r"""
        Constructs a reconnection policy.

        Args:
            enabled: Whether to reconnect at all. Defaults to enabled.
            max_retries: Passes over the known endpoints after the first, or
                `None` for unlimited; `0` still makes that first pass. One pass
                tries the endpoint the client is on, the address it was
                configured with, and every node the roster named, so this counts
                passes rather than dials. Defaults
                to unlimited, which means a call awaited while the server is
                down never returns: `connect()`, `send_messages()` and
                `poll_messages()` all wait inside the retry loop. Set a finite
                number for request/reply style usage, so a call fails instead.
            interval: Delay between passes. Defaults to 1 second. The first pass
                runs at once when more than one endpoint is known.
            reestablish_after: Cooldown before redialing the endpoint of the last
                successful connection, measured from when it was established, so
                a session that outlived the interval is redialed at once. Owed to
                that endpoint alone. Defaults to 5 seconds.

        Raises:
            ValueError: If a duration is negative, if `max_retries` is outside the
                range of an unsigned 32-bit integer, or if `interval` is zero.
        """
    def __repr__(self) -> builtins.str: ...

@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.
        """
    @property
    def created_at(self) -> builtins.int:
        r"""
        The timestamp when the topic was created, in microseconds.
        """
    @property
    def size(self) -> builtins.int:
        r"""
        The total size of the topic in bytes.
        """
    @property
    def message_expiry(self) -> IggyExpiry:
        r"""
        The expiry of the messages in the topic.
        """
    @property
    def compression_algorithm(self) -> builtins.str:
        r"""
        Compression algorithm for the topic.
        """
    @property
    def max_topic_size(self) -> MaxTopicSize:
        r"""
        The maximum size of the topic.
        """
    @property
    def options(self) -> UserHeaders:
        r"""
        Options the creating client set explicitly.

        The same `dict[HeaderKey, HeaderValue]` that `ReceiveMessage.user_headers`
        returns, since options ride that codec; call `to_scalar_dict()` for the
        plain-scalar form.
        """
    @property
    def derived_options(self) -> UserHeaders:
        r"""
        Options admission resolved for the keys the client did not send.

        Same shape as `options`. These would have resolved differently
        under another server configuration.
        """

@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 created_at(self) -> builtins.int:
        r"""
        The timestamp when the topic was created, in microseconds.
        """
    @property
    def size(self) -> builtins.int:
        r"""
        The total size of the topic in bytes.
        """
    @property
    def message_expiry(self) -> IggyExpiry:
        r"""
        The expiry of the messages in the topic.
        """
    @property
    def compression_algorithm(self) -> builtins.str:
        r"""
        Compression algorithm for the topic.
        """
    @property
    def max_topic_size(self) -> MaxTopicSize:
        r"""
        The maximum size of the topic.
        """
    @property
    def options(self) -> UserHeaders:
        r"""
        Options the creating client set explicitly.

        The same `dict[HeaderKey, HeaderValue]` that `ReceiveMessage.user_headers`
        returns, since options ride that codec; call `to_scalar_dict()` for the
        plain-scalar form.
        """
    @property
    def derived_options(self) -> UserHeaders:
        r"""
        Options admission resolved for the keys the client did not send.

        Same shape as `options`. These would have resolved differently
        under another server configuration.
        """
    @property
    def partitions(self) -> builtins.list[Partition]:
        r"""
        The collection of partitions in the topic.

        Rebuilds the list from scratch on every access; cache the result
        rather than reading this repeatedly in a loop.
        """

@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 UserHeaders(dict):
    r"""
    User headers dictionary returned by `ReceiveMessage.user_headers`.

    This is a regular `dict[HeaderKey, HeaderValue]` (so all mapping
    operations work) that additionally exposes `to_scalar_dict` for the convenient
    scalar form.
    """
    def __new__(cls, mapping: dict | None = None) -> UserHeaders:
        r"""
        Wraps a mapping so its entries gain the `to_scalar_dict` helper.

        Accepts a dict whose keys and values can each independently be
        `HeaderKey`/`HeaderValue` or a plain scalar (`str | bytes | bool |
        int | float`). The inherited `dict` initializer copies the provided
        mapping.
        """
    def __setitem__(self, key: typing.Any, value: typing.Any) -> None: ...
    def to_scalar_dict(
        self,
    ) -> dict[str | bytes | bool | int | float, str | bytes | bool | int | float]:
        r"""
        Converts these headers into the convenient plain dictionary form.

        Returns an error if two distinct typed keys map to the same plain
        Python scalar (e.g., `UnsignedInt8(1)` and `UnsignedInt16(1)` both
        become `int(1)`), or if a stored field cannot be decoded.
        """

@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.
    """