# 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__ = [
    "Durability",
    "AutoCommit",
    "AutoCommitAfter",
    "AutoCommitWhen",
    "AutoLogin",
    "BackgroundProducerConfig",
    "BackpressureMode",
    "CacheMetrics",
    "CacheMetricsKey",
    "Consumer",
    "ConsumerGroup",
    "ConsumerGroupDetails",
    "ConsumerGroupMember",
    "DirectProducerConfig",
    "GlobalPermissions",
    "HeaderKey",
    "HeaderValue",
    "HttpConfig",
    "IggyClient",
    "IggyConsumer",
    "IggyExpiry",
    "IggyProducer",
    "MaxTopicSize",
    "OptionSpec",
    "Partition",
    "Partitioning",
    "Permissions",
    "PollingStrategy",
    "ProducerSendError",
    "ProducerSharding",
    "QuicConfig",
    "QuicReconnectionConfig",
    "ReceiveMessage",
    "SendMessage",
    "SendMessagesConfirmation",
    "SendMessagesResponse",
    "Stats",
    "Stream",
    "StreamDetails",
    "StreamPermissions",
    "TcpConfig",
    "TcpReconnectionConfig",
    "Topic",
    "TopicDetails",
    "TopicPermissions",
    "UserHeaders",
    "UserInfo",
    "UserInfoDetails",
    "UserStatus",
    "WebSocketConfig",
    "WebSocketFramingConfig",
    "WebSocketReconnectionConfig",
]

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: ...

@typing.final
class BackgroundProducerConfig:
    r"""
    Immutable configuration for a producer that queues sends on background workers.

    For detailed background-producer semantics, see
    https://iggy.apache.org/docs/sdk/rust/high-level-sdk/.
    """
    @property
    def num_shards(self) -> builtins.int:
        r"""
        Number of background worker shards, each with its own queue.
        A value of zero is treated as one shard.
        """
    @property
    def linger_time(self) -> datetime.timedelta:
        r"""
        Maximum time a worker holds a non-empty buffer before flushing it.
        A zero duration flushes as soon as the worker receives a send.
        """
    @property
    def batch_size(self) -> builtins.int:
        r"""
        Per-worker flush threshold in buffered bytes.
        A value of zero disables this threshold.
        """
    @property
    def batch_length(self) -> builtins.int:
        r"""
        Per-worker flush threshold in queued sends, not individual messages.
        A value of zero disables this threshold.
        """
    @property
    def max_buffer_size(self) -> builtins.int:
        r"""
        Maximum bytes buffered or in flight across all worker shards.
        A value of zero makes the byte budget unlimited.
        """
    @property
    def failure_mode(self) -> BackpressureMode:
        r"""
        Behavior when `max_buffer_size` is exhausted.
        """
    @property
    def max_in_flight(self) -> builtins.int:
        r"""
        Maximum number of requests written concurrently across all workers.
        A value of zero uses the runtime's maximum semaphore permit count.
        """
    @property
    def sharding(self) -> ProducerSharding:
        r"""
        Strategy used to assign each send to a worker shard.
        Ordered sharding preserves per-destination dispatch order, while balanced
        sharding distributes sends round-robin and may reorder them.
        """
    def __new__(
        cls,
        *,
        num_shards: builtins.int = 1,
        linger_time: datetime.timedelta = ...,
        batch_size: builtins.int = 1048576,
        batch_length: builtins.int = 1000,
        max_buffer_size: builtins.int = 33554432,
        failure_mode: BackpressureMode = ...,
        max_in_flight: builtins.int = 1,
        sharding: ProducerSharding = ...,
    ) -> BackgroundProducerConfig:
        r"""
        Constructs background batching, capacity, backpressure, and sharding configuration.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class BackpressureMode:
    r"""
    What a background send does when the producer buffer is full.
    """
    @property
    def timeout(self) -> datetime.timedelta | None:
        r"""
        The configured timeout, or `None` for modes without one.
        """
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    @staticmethod
    def block() -> BackpressureMode:
        r"""
        Wait indefinitely for buffer capacity.
        """
    @staticmethod
    def block_with_timeout(timeout: datetime.timedelta) -> BackpressureMode:
        r"""
        Wait up to `timeout` for buffer capacity.
        """
    @staticmethod
    def fail_immediately() -> BackpressureMode:
        r"""
        Fail immediately when the producer buffer is full.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class CacheMetrics:
    r"""
    Cache metrics for a specific partition.
    """
    @property
    def hits(self) -> builtins.int:
        r"""
        Number of cache hits.
        """
    @property
    def misses(self) -> builtins.int:
        r"""
        Number of cache misses.
        """
    @property
    def hit_ratio(self) -> builtins.float:
        r"""
        Hit ratio (hits / (hits + misses)).
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class CacheMetricsKey:
    r"""
    Key identifying the partition a `CacheMetrics` entry belongs to.

    Hashable and comparable, so it can key the `Stats.cache_metrics` dict.
    """
    @property
    def stream_id(self) -> builtins.int:
        r"""
        The unique identifier (numeric) of the stream.
        """
    @property
    def topic_id(self) -> builtins.int:
        r"""
        The unique identifier (numeric) of the topic within the stream.
        """
    @property
    def partition_id(self) -> builtins.int:
        r"""
        The unique identifier (numeric) of the partition within the topic.
        """
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __hash__(self) -> builtins.int: ...
    def __new__(
        cls, stream_id: builtins.int, topic_id: builtins.int, partition_id: builtins.int
    ) -> CacheMetricsKey: ...
    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 DirectProducerConfig:
    r"""
    Configuration for a producer that sends from the calling task.
    """
    @property
    def batch_length(self) -> builtins.int:
        r"""
        Maximum number of messages sent in one request.
        A value of zero uses the internal limit of 1,000,000 messages.
        """
    @property
    def linger_time(self) -> datetime.timedelta:
        r"""
        Minimum gap requested between sequential direct sends.
        """
    def __new__(
        cls, *, batch_length: builtins.int = 1000, linger_time: datetime.timedelta = ...
    ) -> DirectProducerConfig:
        r"""
        Constructs direct-producer batching and pacing configuration.
        """
    def __repr__(self) -> builtins.str: ...

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

    Every field is keyword-only and optional.

    There is no `AutoLogin` and no reconnection policy, and `connect()` does not
    dial: it only starts the heartbeat, so `login_user(...)` has to follow it.

    HTTP is single-consumer only. `consumer_group(...)` fails with
    `Feature is unavailable`, and so does a `Consumer.Group(...)` poll unless it
    names an explicit `partition_id`. With one, the consumer kind is not carried
    on the HTTP wire, so the poll is served as an ordinary consumer named after
    the group, with no membership, no partition assignment, and no rebalancing
    behind it. Pass `Consumer.Single(...)` explicitly.
    """
    @property
    def api_url(self) -> builtins.str: ...
    @property
    def retries(self) -> builtins.int: ...
    @property
    def has_jwt(self) -> builtins.bool:
        r"""
        Whether a JWT is configured, without exposing the token itself.
        """
    @property
    def heartbeat_interval(self) -> datetime.timedelta: ...
    def __new__(
        cls,
        *,
        api_url: builtins.str | None = None,
        retries: builtins.int | None = None,
        jwt: builtins.str | None = None,
        heartbeat_interval: datetime.timedelta | None = None,
    ) -> HttpConfig:
        r"""
        Constructs an HTTP configuration.

        Args:
            api_url: Base URL of the Iggy HTTP API, as `scheme://host[:port]`
                only - no path, query, fragment, or credentials. Defaults to
                `http://127.0.0.1:3000`.
            retries: Number of retries to perform on transient errors, each one
                replaying the full request (including its body) via automatic
                middleware. Defaults to 3. Delivery is therefore at-least-once:
                if the original request actually committed but its response
                was lost (e.g. to a timeout), a retried call applies the same
                operation again. Set to 0 to disable automatic replay and match
                the other transports, which surface the failure instead of
                silently resending.
            jwt: JWT token for A2A (Agent-to-Agent) authentication. Defaults to
                `None`. Stored trimmed, since a token read from a file carries a
                trailing newline that the `Authorization` header value rejects.
                Rejected if empty or whitespace-only: accepting it would make
                `has_jwt` report `True` while every call still fails
                `Unauthenticated`.
            heartbeat_interval: Interval between the client's liveness probes
                (a bare `GET /ping`). Defaults to 5 seconds. Unlike TCP/QUIC,
                HTTP has no persistent connection or session for this to keep
                alive; it only proves the server is reachable.

        Raises:
            ValueError: If `api_url` is not a valid URL, if `retries` is outside
                the range of an unsigned 32-bit integer, if `jwt` is empty or
                whitespace-only, if a duration is negative, or if
                `heartbeat_interval` is zero.
            OverflowError: If `retries` does not fit a signed 64-bit integer,
                raised by the underlying conversion before this constructor runs.
        """
    def __repr__(self) -> builtins.str: ...

@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
        | QuicConfig
        | HttpConfig
        | WebSocketConfig
        | builtins.str
        | None = None,
    ) -> IggyClient:
        r"""
        Constructs a new IggyClient from a TCP server address, a `TcpConfig`, a
        `QuicConfig`, an `HttpConfig`, or a `WebSocketConfig`. Construction is
        synchronous; async methods return asyncio awaitables backed by the shared
        Tokio runtime.

        Args:
            conn: A `host:port` address, a `TcpConfig`, a `QuicConfig`, an
                `HttpConfig`, or a `WebSocketConfig`. Defaults to `127.0.0.1:8090`
                over TCP with auto-login disabled. A malformed address is reported
                differently depending on the form: the string form raises
                `RuntimeError` here, while every config type raises `ValueError`
                when it is constructed, before any of them 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, or if a `QuicConfig` client cannot bind its
                local UDP socket (for example the port is already in use).
        """
    @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 get_stats(self) -> collections.abc.Awaitable[Stats]:
        r"""
        Get the statistics and details of the server and its running process.

        Requires an authenticated session whose user holds the `read_servers`
        or `manage_servers` global permission.

        Returns:
            An awaitable that resolves to `Stats`.

        Raises:
            RuntimeError: If the client is not connected, the session is not
                authenticated, the user lacks the permission, or the request
                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,
        options: builtins.dict[builtins.str, builtins.str] | 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`.
            options: Reserved for future use. Additional option keys as
                `dict[str, str] | None`, forwarded to the server. No user update
                option key exists yet, so a current server rejects every key.

        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 and starts the heartbeat task.
        Raises `RuntimeError` if the connection fails. Over HTTP there is no
        connection to establish, so only the heartbeat starts and this call
        succeeds even against an unreachable server.
        """
    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 get_streams(self) -> collections.abc.Awaitable[list[Stream]]:
        r"""
        Return all streams.

        Returns:
            A list of `Stream` summaries.

        Raises:
            RuntimeError: If the client is not authenticated, the user lacks global
                `read_streams` or `manage_streams` permission, or the request fails.
        """
    def update_stream(
        self,
        stream_id: builtins.str | builtins.int,
        name: builtins.str,
        options: builtins.dict[builtins.str, builtins.str] | None = None,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Rename a stream selected by name or numeric ID.

        `stream_id` accepts a stream name as `str` or numeric ID as `int`. A
        decimal-only string is interpreted as a numeric ID. `name` must be unique
        and contain between 1 and 255 UTF-8 bytes. Renaming a stream to its current
        name succeeds without changing it.

        Args:
            stream_id: Stream identifier as `str | int`.
            name: New stream name as `str`.
            options: Additional option keys as `dict[str, str] | None`, forwarded
                to the server. Current server versions reject all stream update
                option keys.

        Returns:
            None.

        Raises:
            TypeError: If `stream_id` is not `str` or an integer in
                `0..=2**32 - 1`, or `name` is not `str`.
            ValueError: If a string identifier is empty or exceeds 255 UTF-8 bytes.
            RuntimeError: If the client is not authenticated, the user lacks global
                `manage_streams` or per-stream `manage_stream` permission, the
                stream does not exist, the new name is invalid or already used, or
                the request fails.
        """
    def delete_stream(
        self, stream_id: builtins.str | builtins.int
    ) -> collections.abc.Awaitable[None]:
        r"""
        Delete a stream selected by name or numeric ID.

        Deletion removes the stream and all of its topics, partitions, and messages.
        `stream_id` accepts a stream name as `str` or numeric ID as `int`. A
        decimal-only string is interpreted as a numeric ID.

        Returns:
            None.

        Raises:
            TypeError: If `stream_id` is not `str` or an integer in
                `0..=2**32 - 1`.
            ValueError: If a string identifier is empty or exceeds 255 UTF-8 bytes.
            RuntimeError: If the client is not authenticated, the user lacks global
                `manage_streams` or per-stream `manage_stream` permission, the
                stream does not exist, or the request fails.
        """
    def purge_stream(
        self, stream_id: builtins.str | builtins.int
    ) -> collections.abc.Awaitable[None]:
        r"""
        Delete all messages from every topic in a stream.

        The stream, topics, and partitions remain available. Repeated purges of an
        existing empty stream succeed. `stream_id` accepts a stream name as `str`
        or numeric ID as `int`. A decimal-only string is interpreted as a numeric
        ID.

        Returns:
            None.

        Raises:
            TypeError: If `stream_id` is not `str` or an integer in
                `0..=2**32 - 1`.
            ValueError: If a string identifier is empty or exceeds 255 UTF-8 bytes.
            RuntimeError: If the client is not authenticated, the user lacks global
                `manage_streams` or per-stream `manage_stream` permission, the
                stream does not exist, or the request fails.
        """
    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,
        durability: Durability | None = None,
        consumer_offset_durability: Durability | 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`, at most 1000.
            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`.
            durability: Message completion policy, defaulting to replicated.
            consumer_offset_durability: Independent offset policy, defaulting to replicated.
            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_partitions(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
        partitions_count: builtins.int,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Create partitions for a topic. New partition IDs continue from one past the
        current highest ID; IDs removed by deletion can be reused. Existing consumer
        groups are immediately rebalanced across all partitions, advancing their
        generation and dropping pending revocations.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.
            partitions_count: Number of partitions to create as `int`, between 1 and
                1000 inclusive.

        Returns:
            An awaitable that resolves to `None` when the partitions are committed;
            storage materialization completes asynchronously.

        Raises:
            ValueError: If an identifier is invalid.
            OverflowError: If `partitions_count` is outside the unsigned 32-bit range.
            RuntimeError: If the client is not authenticated, lacks global
                `manage_streams` or `manage_topics`, per-stream `manage_stream` or
                `manage_topics`, or per-topic `manage_topic` permission, or the
                request fails.
        """
    def delete_partitions(
        self,
        stream_id: builtins.str | builtins.int,
        topic_id: builtins.str | builtins.int,
        partitions_count: builtins.int,
    ) -> collections.abc.Awaitable[None]:
        r"""
        Delete the last partitions from a topic, including all messages stored in them.
        Existing consumer groups are immediately rebalanced across the remaining
        partitions, advancing their generation and dropping pending revocations.

        Args:
            stream_id: Stream identifier as `str | int`.
            topic_id: Topic identifier as `str | int`.
            partitions_count: Number of partitions to delete as `int` from the end of
                the topic; must be between 1 and 1000 inclusive and no greater than
                its current count.

        Returns:
            An awaitable that resolves to `None` when deletion is accepted; storage
            teardown completes asynchronously.

        Raises:
            ValueError: If an identifier is invalid.
            OverflowError: If `partitions_count` is outside the unsigned 32-bit range.
            RuntimeError: If the client is not authenticated, lacks global
                `manage_streams` or `manage_topics`, per-stream `manage_stream` or
                `manage_topics`, or per-topic `manage_topic` permission, 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: Partitioning | builtins.int,
        messages: list[SendMessage],
    ) -> collections.abc.Awaitable[SendMessagesResponse]:
        r"""
        Sends a batch of messages to a topic using the selected partitioning strategy.

        Args:
            stream: Stream identifier as `str | int`.
            topic: Topic identifier as `str | int`.
            partitioning: A `Partitioning` strategy or an integer partition ID.
                Use `Partitioning.balanced()`, `Partitioning.partition_id(id)`, or
                `Partitioning.messages_key(key)`. An integer is shorthand for
                `Partitioning.partition_id(id)`.
            messages: Messages to send as `list[SendMessage]`.

        Returns:
            An awaitable that resolves to `SendMessagesResponse`. Its confirmations
            report the committed partition and batch base offset. The list is empty
            when the server reports no offsets.

        Raises:
            ValueError: If a string stream or topic identifier is invalid.
            TypeError: If `partitioning` or `messages` has an unsupported type.
            OverflowError: If a numeric stream, topic, or partition ID is outside
                the supported unsigned 32-bit range.
            RuntimeError: If the request fails.
        """
    def producer(
        self,
        stream: builtins.str,
        topic: builtins.str,
        partitioning: Partitioning | None = None,
        mode: DirectProducerConfig | BackgroundProducerConfig | None = None,
        create_stream_if_not_exists: builtins.bool = True,
        create_topic_if_not_exists: builtins.bool = True,
        topic_partitions_count: builtins.int = 1,
        topic_message_expiry: IggyExpiry | None = None,
        topic_max_size: MaxTopicSize | None = None,
        send_retries: builtins.int | None = 3,
        send_retry_interval: datetime.timedelta | None = ...,
    ) -> collections.abc.Awaitable[IggyProducer]:
        r"""
        Creates and initializes a high-level producer bound to a stream and topic.

        This is a Python port of the Rust high-level producer API. For detailed
        producer semantics, see https://iggy.apache.org/docs/sdk/rust/high-level-sdk/.
        `None` selects direct mode. `BackgroundProducerConfig` starts background
        workers and makes successful sends mean queue acceptance rather than a
        server commit. The returned producer is ready to send.

        Raises `ValueError` for invalid names or numeric ranges and `RuntimeError`
        when stream/topic initialization fails.
        """
    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.

        Consumer groups are not available over HTTP. With `auto_join_consumer_group`
        left on, this call fails at the join with `Feature is unavailable`.
        Turning it off is not a workaround: the join is skipped, but a group
        member always polls without a partition, so the first poll fails with
        the same error. Use `Consumer.Single(...)` with `poll_messages(...)`
        instead - a `Consumer.Group(...)` poll with an explicit `partition_id`
        does reach the server, but is served as an ordinary consumer named
        after the group.
        """
    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: ...

    ...

@typing.final
class IggyProducer:
    r"""
    Python port of the Rust high-level producer API, bound to one stream and topic.

    For detailed producer semantics, see
    https://iggy.apache.org/docs/sdk/rust/high-level-sdk/.

    Direct sends complete after the server responds and contain commit confirmations.
    Background sends complete once accepted by a worker and contain no confirmations.
    Always use the async context manager or call `shutdown()` explicitly; dropping a
    background producer can lose accepted buffered messages.
    """
    def send(
        self, messages: list[SendMessage]
    ) -> collections.abc.Awaitable[SendMessagesResponse]:
        r"""
        Sends a batch to the producer's bound stream and topic.
        In background mode, success means accepted into the dispatcher and the
        returned confirmation list is empty.
        """
    def send_one(
        self, message: SendMessage
    ) -> collections.abc.Awaitable[SendMessagesResponse]:
        r"""
        Sends one message to the producer's bound stream and topic.
        It has the same mode-dependent completion semantics as `send()`.
        """
    def send_with_partitioning(
        self, messages: list[SendMessage], partitioning: Partitioning | None = None
    ) -> collections.abc.Awaitable[SendMessagesResponse]:
        r"""
        Sends a batch with an optional per-call partitioning override.
        It has the same mode-dependent completion semantics as `send()`.
        """
    def send_to(
        self,
        stream: builtins.str | builtins.int,
        topic: builtins.str | builtins.int,
        messages: list[SendMessage],
        partitioning: Partitioning | None = None,
    ) -> collections.abc.Awaitable[SendMessagesResponse]:
        r"""
        Sends a batch to another existing stream and topic.
        It has the same mode-dependent completion semantics as `send()` and does
        not create the alternate destination.
        """
    def shutdown(self) -> collections.abc.Awaitable[None]:
        r"""
        Waits for active sends and closes the producer. Repeated calls are safe.
        Background shutdown flushes every accepted buffered message before returning.
        """
    def __aenter__(self) -> collections.abc.Awaitable[IggyProducer]: ...
    def __aexit__(
        self, _exc_type: typing.Any, _exc_value: typing.Any, _traceback: typing.Any
    ) -> collections.abc.Awaitable[builtins.bool]: ...

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 Partitioning:
    r"""
    Defines how a batch of messages is assigned to a topic partition.
    """
    @staticmethod
    def balanced() -> Partitioning:
        r"""
        Routes the batch to one partition selected by round-robin.
        """
    @staticmethod
    def partition_id(partition_id: builtins.int) -> Partitioning:
        r"""
        Routes the batch to the specified partition.

        `partition_id` must be between 0 and `2**32 - 1`. The topic must contain
        that partition when the batch is sent.

        Raises:
            TypeError: If `partition_id` is not an integer.
            OverflowError: If `partition_id` is outside the supported unsigned
                32-bit range.
        """
    @staticmethod
    def messages_key(key: builtins.str | bytes) -> Partitioning:
        r"""
        Routes the batch to one partition selected by hashing `key`.

        `key` may be `str` or `bytes`. Strings are encoded as UTF-8; the encoded
        key must contain between 1 and 255 bytes.

        Raises:
            ValueError: If the encoded key is empty or exceeds 255 bytes.
            TypeError: If `key` is not `str` or `bytes`.
        """

@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 ProducerSendError(builtins.RuntimeError):
    r"""
    A direct producer error that preserves partial-send recovery state.
    """
    @property
    def cause(self) -> builtins.str:
        r"""
        The underlying Iggy error message.
        """
    @property
    def failed(self) -> builtins.list[SendMessage]:
        r"""
        Messages without a usable confirmation after the failure.
        An encryptor can leave these messages encrypted, so do not submit them
        to the same producer without restoring their original payloads.
        """
    @property
    def committed(self) -> builtins.list[SendMessagesConfirmation]:
        r"""
        Confirmations returned for chunks committed before the failure.
        """

@typing.final
class QuicConfig:
    r"""
    Configuration for the QUIC transport, accepted by `IggyClient(...)`.

    Every field is keyword-only and optional.
    """
    @property
    def server_address(self) -> builtins.str: ...
    @property
    def client_address(self) -> builtins.str: ...
    @property
    def server_name(self) -> builtins.str: ...
    @property
    def auto_login(self) -> AutoLogin: ...
    @property
    def reconnection(self) -> QuicReconnectionConfig: ...
    @property
    def heartbeat_interval(self) -> datetime.timedelta: ...
    @property
    def response_buffer_size(self) -> builtins.int: ...
    @property
    def max_concurrent_bidi_streams(self) -> builtins.int: ...
    @property
    def datagram_send_buffer_size(self) -> builtins.int: ...
    @property
    def initial_mtu(self) -> builtins.int: ...
    @property
    def send_window(self) -> builtins.int: ...
    @property
    def receive_window(self) -> builtins.int: ...
    @property
    def keep_alive_interval(self) -> datetime.timedelta: ...
    @property
    def max_idle_timeout(self) -> datetime.timedelta: ...
    @property
    def validate_certificate(self) -> builtins.bool: ...
    def __new__(
        cls,
        *,
        server_address: builtins.str | None = None,
        client_address: builtins.str | None = None,
        server_name: builtins.str | None = None,
        auto_login: AutoLogin | None = None,
        reconnection: QuicReconnectionConfig | None = None,
        heartbeat_interval: datetime.timedelta | None = None,
        response_buffer_size: builtins.int | None = None,
        max_concurrent_bidi_streams: builtins.int | None = None,
        datagram_send_buffer_size: builtins.int | None = None,
        initial_mtu: builtins.int | None = None,
        send_window: builtins.int | None = None,
        receive_window: builtins.int | None = None,
        keep_alive_interval: datetime.timedelta | None = None,
        max_idle_timeout: datetime.timedelta | None = None,
        validate_certificate: builtins.bool | None = None,
    ) -> QuicConfig:
        r"""
        Constructs a QUIC configuration.

        Args:
            server_address: `host:port` of the Iggy server. Defaults to `127.0.0.1:8080`.
            client_address: `host:port` to bind the local UDP socket to. Defaults to
                `127.0.0.1:0`, which binds to any available port. That exact value,
                passed or defaulted, binds `[::1]:0` instead when `server_address`
                resolves to IPv6, so the socket in use may not be the address read
                back here. Any other value binds as given.
            server_name: Server name used for the QUIC/TLS handshake. Defaults to
                `localhost`.
            auto_login: Credentials replayed on every connect. Defaults to `AutoLogin.disabled()`.
            reconnection: Reconnection policy. Defaults to `QuicReconnectionConfig()`.
            heartbeat_interval: Interval of heartbeats sent by the client. Defaults to 5 seconds.
            response_buffer_size: Size of the response buffer in bytes. Defaults to 10 MB.
            max_concurrent_bidi_streams: Maximum number of concurrent bidirectional
                streams. Defaults to 10,000.
            datagram_send_buffer_size: Size of the datagram send buffer in bytes.
                Defaults to 100,000.
            initial_mtu: Initial MTU in bytes. Defaults to 1200.
            send_window: Send window size in bytes. Defaults to 100,000.
            receive_window: Receive window size in bytes. Defaults to 100,000.
            keep_alive_interval: Interval between QUIC keep-alive pings, or a zero
                duration to disable them. Defaults to 5 seconds.
            max_idle_timeout: How long the connection tolerates silence before it is
                considered dead, or a zero duration to use quinn's own default (30
                seconds) instead, since `configure()` skips the setter entirely when
                zero. Defaults to 10 seconds.
            validate_certificate: Whether to validate the server certificate. Defaults
                to disabled; only the TCP transport validates by default.

        Raises:
            ValueError: If `server_address` or `client_address` is not a valid
                `host:port` pair, if a duration is negative, if
                `heartbeat_interval` is zero, if `keep_alive_interval` or
                `max_idle_timeout` is not a whole number of milliseconds, if
                `initial_mtu` is below quinn's minimum of 1200, or if a numeric
                field is outside the range of its underlying wire type.
            OverflowError: If a numeric field does not fit a signed 64-bit integer,
                raised by the underlying conversion before this constructor runs.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class QuicReconnectionConfig:
    r"""
    How the QUIC 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,
    ) -> QuicReconnectionConfig:
        r"""
        Constructs a reconnection policy.

        Args:
            enabled: Whether to reconnect at all. Defaults to enabled.
            max_retries: Redials of the configured server address after the first
                attempt, or `None` for unlimited; `0` still makes that first
                attempt. Unlike the TCP transport, QUIC redials the one address
                it was configured with rather than walking a cluster roster, so
                this counts dials. Defaults to unlimited, which means a call
                awaited while the server is down never returns: `connect()`
                waits inside the retry loop, as do `send_messages()` and
                `poll_messages()` once auto-login is configured. Set a finite
                number for request/reply style usage, so a call fails instead.
            interval: Delay before each redial. Defaults to 1 second.
            reestablish_after: Cooldown before redialing after a previously
                successful connection, measured from when it was established, so
                a session that outlived the interval is redialed at once.
                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.
            OverflowError: If `max_retries` does not fit a signed 64-bit integer,
                raised by the underlying conversion before this constructor runs.
        """
    def __repr__(self) -> builtins.str: ...

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

        Confirmation follows VSR quorum commit. A topic with persisted message
        durability also waits for recoverable stable-storage copies on the quorum.
        """

@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, so check whether
        it is empty before 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. Confirmation follows the topic's message
        durability policy: quorum commit, plus stable storage for persisted topics.
        """

@typing.final
class Stats:
    r"""
    The statistics and details of the server and its running process.

    The fields are gathered from several sources while the request is served
    (metadata counters, a process probe, a disk probe), so they are not an
    atomic snapshot of one instant.
    """
    @property
    def process_id(self) -> builtins.int:
        r"""
        The unique identifier of the server process.
        """
    @property
    def cpu_usage(self) -> builtins.float:
        r"""
        The CPU usage of the server process, in percent summed over the cores
        it ran on, so it exceeds 100 whenever the process uses more than one
        core.

        Measured as a delta since the previous `get_stats` served by the same
        server shard, so the first sample a shard serves is 0.
        """
    @property
    def total_cpu_usage(self) -> builtins.float:
        r"""
        The total CPU usage of the system, in percent averaged over the cores
        the server may run on when confined by an affinity/cpuset mask (over
        every host core otherwise), so it stays within 0-100.

        Same per-shard delta sampling as `cpu_usage`: the first sample a shard
        serves is 0.
        """
    @property
    def memory_usage(self) -> builtins.int:
        r"""
        The memory usage of the server process, in bytes.
        """
    @property
    def total_memory(self) -> builtins.int:
        r"""
        The total memory of the system, in bytes, or the effective cgroup memory
        limit when the server runs inside a memory-capped cgroup (container,
        systemd slice).
        """
    @property
    def available_memory(self) -> builtins.int:
        r"""
        The available memory of the system, in bytes, scoped to the cgroup
        limit when one applies.
        """
    @property
    def run_time(self) -> datetime.timedelta:
        r"""
        The run time of the server process, with whole-second precision.
        """
    @property
    def start_time(self) -> builtins.int:
        r"""
        The start time of the server process, in microseconds since the Unix
        epoch, with whole-second precision.
        """
    @property
    def read_bytes(self) -> builtins.int:
        r"""
        The total number of bytes read.
        """
    @property
    def written_bytes(self) -> builtins.int:
        r"""
        The total number of bytes written.
        """
    @property
    def messages_size_bytes(self) -> builtins.int:
        r"""
        The total size of the messages, in bytes.
        """
    @property
    def streams_count(self) -> builtins.int:
        r"""
        The total number of streams.
        """
    @property
    def topics_count(self) -> builtins.int:
        r"""
        The total number of topics.
        """
    @property
    def partitions_count(self) -> builtins.int:
        r"""
        The total number of partitions.
        """
    @property
    def segments_count(self) -> builtins.int:
        r"""
        The total number of segments.
        """
    @property
    def messages_count(self) -> builtins.int:
        r"""
        The total number of messages.
        """
    @property
    def clients_count(self) -> builtins.int:
        r"""
        The total number of connected clients.
        """
    @property
    def consumer_groups_count(self) -> builtins.int:
        r"""
        The total number of consumer groups.
        """
    @property
    def hostname(self) -> builtins.str:
        r"""
        The name of the host the server runs on.
        """
    @property
    def os_name(self) -> builtins.str:
        r"""
        The name of the operating system.
        """
    @property
    def os_version(self) -> builtins.str:
        r"""
        The version of the operating system.
        """
    @property
    def kernel_version(self) -> builtins.str:
        r"""
        The version of the kernel.
        """
    @property
    def iggy_server_version(self) -> builtins.str:
        r"""
        The version of the Iggy server.
        """
    @property
    def iggy_server_semver(self) -> builtins.int | None:
        r"""
        The numeric semantic version of the Iggy server, or `None` when unknown.
        E.g. 1.2.3 -> 1002003 (major * 1000000 + minor * 1000 + patch).
        """
    @property
    def cache_metrics(self) -> builtins.dict[CacheMetricsKey, CacheMetrics]:
        r"""
        Cache metrics per partition.

        Current servers do not populate this and reply with an empty map. Each
        access builds a fresh dict, so mutating the returned dict does not
        change the stats.
        """
    @property
    def threads_count(self) -> builtins.int:
        r"""
        The number of threads in the server process.
        """
    @property
    def free_disk_space(self) -> builtins.int:
        r"""
        The available (free) disk space for the data directory, in bytes.

        0 when the server does not know its data directory or the disk probe
        fails.
        """
    @property
    def total_disk_space(self) -> builtins.int:
        r"""
        The total disk space for the data directory, in bytes.

        0 when the server does not know its data directory or the disk probe
        fails.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class Stream:
    r"""
    Summary information returned by `IggyClient.get_streams()`.

    `created_at` is Unix time in microseconds. `size` is the stream's current
    stored size in bytes.
    """
    @property
    def id(self) -> builtins.int:
        r"""
        Numeric stream identifier.
        """
    @property
    def created_at(self) -> builtins.int:
        r"""
        Stream creation time as Unix time in microseconds.
        """
    @property
    def name(self) -> builtins.str:
        r"""
        Unique stream name.
        """
    @property
    def size(self) -> builtins.int:
        r"""
        Current stored stream size in bytes.
        """
    @property
    def messages_count(self) -> builtins.int:
        r"""
        Total messages across all topics in the stream.
        """
    @property
    def topics_count(self) -> builtins.int:
        r"""
        Number of topics in the stream.
        """

@typing.final
class StreamDetails:
    @property
    def created_at(self) -> builtins.int:
        r"""
        Stream creation time as Unix time in microseconds.
        """
    @property
    def id(self) -> builtins.int: ...
    @property
    def name(self) -> builtins.str: ...
    @property
    def size(self) -> builtins.int:
        r"""
        Current stored stream size in bytes.
        """
    @property
    def messages_count(self) -> builtins.int: ...
    @property
    def topics_count(self) -> builtins.int: ...
    @property
    def topics(self) -> builtins.list[Topic]:
        r"""
        Returns the topics in the stream.
        """

@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.
            OverflowError: If `max_retries` does not fit a signed 64-bit integer,
                raised by the underlying conversion before this constructor runs.
        """
    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 WebSocketConfig:
    r"""
    Configuration for the WebSocket 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) -> WebSocketReconnectionConfig: ...
    @property
    def heartbeat_interval(self) -> datetime.timedelta: ...
    @property
    def framing(self) -> WebSocketFramingConfig: ...
    @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: ...
    def __new__(
        cls,
        *,
        server_address: builtins.str | None = None,
        auto_login: AutoLogin | None = None,
        reconnection: WebSocketReconnectionConfig | None = None,
        heartbeat_interval: datetime.timedelta | None = None,
        framing: WebSocketFramingConfig | 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,
    ) -> WebSocketConfig:
        r"""
        Constructs a WebSocket configuration.

        Args:
            server_address: `host:port` of the Iggy server. Defaults to `127.0.0.1:8092`.
            auto_login: Credentials replayed on every connect. Defaults to `AutoLogin.disabled()`.
            reconnection: Reconnection policy. Defaults to `WebSocketReconnectionConfig()`.
            heartbeat_interval: Interval of heartbeats sent by the client. Defaults to 5 seconds.
            framing: Frame- and buffer-level options. Defaults to `WebSocketFramingConfig()`.
            tls_enabled: Whether to connect over TLS. Defaults to disabled.
            tls_domain: Domain to validate the certificate against. Defaults to
                `localhost`. Empty means it is taken from the IP `server_address`
                resolves to.
            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 `False`; only the TCP transport validates by default.
                Disabling this accepts any certificate the server presents,
                including self-signed and mismatched ones, and takes precedence
                over `tls_ca_file`.

        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 WebSocketFramingConfig:
    r"""
    Frame- and buffer-level options passed through to the underlying WebSocket
    implementation, accepted by `WebSocketConfig`'s `framing` argument.

    Every field is keyword-only and optional; unset fields fall back to the
    underlying WebSocket library's own defaults.
    """
    @property
    def read_buffer_size(self) -> builtins.int | None: ...
    @property
    def write_buffer_size(self) -> builtins.int | None: ...
    @property
    def max_write_buffer_size(self) -> builtins.int | None: ...
    @property
    def max_message_size(self) -> builtins.int | None: ...
    @property
    def max_frame_size(self) -> builtins.int | None: ...
    @property
    def accept_unmasked_frames(self) -> builtins.bool: ...
    def __new__(
        cls,
        *,
        read_buffer_size: builtins.int | None = None,
        write_buffer_size: builtins.int | None = None,
        max_write_buffer_size: builtins.int | None = None,
        max_message_size: builtins.int | None = 64 << 20,
        max_frame_size: builtins.int | None = 16 << 20,
        accept_unmasked_frames: builtins.bool | None = None,
    ) -> WebSocketFramingConfig:
        r"""
        Constructs a WebSocket framing configuration.

        Args:
            read_buffer_size: Read buffer size in bytes. Defaults to 128 KiB.
            write_buffer_size: Write buffer size in bytes. Defaults to 128 KiB.
            max_write_buffer_size: Maximum write buffer size in bytes. Defaults to
                unbounded, which reads back as the largest value a pointer-sized
                unsigned integer holds rather than as `None`.
            max_message_size: Maximum message size in bytes, or an explicit `None`
                to lift the limit entirely. Omitting the argument is not the same
                as passing `None`: it keeps the underlying default of 64 MiB.
                Lifting the limit lets a peer queue an arbitrarily large message
                in memory, so prefer a finite value.
            max_frame_size: Maximum frame size in bytes, or an explicit `None` to
                lift the limit entirely. Omitting the argument keeps the
                underlying default of 16 MiB, with the same caveat as
                `max_message_size`.
            accept_unmasked_frames: Whether to accept unmasked frames. Defaults to
                `False`; clients should typically keep this off for RFC compliance.

        Raises:
            ValueError: If a numeric field is outside the range of a pointer-sized
                unsigned integer, or if `max_write_buffer_size` does not come out
                greater than `write_buffer_size`. tungstenite enforces the same
                invariant with an `assert!` at connect time, which would otherwise
                surface as an unrecoverable Rust panic instead of a `ValueError`.
            OverflowError: If a numeric field does not fit a signed 128-bit integer,
                raised by the underlying conversion before this constructor runs.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class WebSocketReconnectionConfig:
    r"""
    How the WebSocket 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,
    ) -> WebSocketReconnectionConfig:
        r"""
        Constructs a reconnection policy.

        Args:
            enabled: Whether to reconnect at all. Defaults to enabled.
            max_retries: Redials of the configured server address after the first
                attempt, or `None` for unlimited; `0` still makes that first
                attempt. Unlike the TCP transport, WebSocket redials the one
                address it was configured with rather than walking a cluster
                roster, so this counts dials. Defaults to unlimited, which means
                a call awaited while the server is down never returns:
                `connect()` waits inside the retry loop, as do `send_messages()`
                and `poll_messages()` once auto-login is configured. Set a finite
                number for request/reply style usage, so a call fails instead.
            interval: Delay before each redial. Defaults to 1 second.
            reestablish_after: Cooldown before redialing after a previously
                successful connection, measured from when it was established, so
                a session that outlived the interval is redialed at once. Applied
                from the first redial onward, not to the initial connect.
                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.
            OverflowError: If `max_retries` does not fit a signed 64-bit integer,
                raised by the underlying conversion before this constructor runs.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class ProducerSharding(enum.Enum):
    r"""
    How a background producer distributes sends among its workers.
    """

    ORDERED = ...
    BALANCED = ...

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

class Durability(str, enum.Enum):
    REPLICATED = "replicated"
    PERSISTED = "persisted"