You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iggy.apache.org by ri...@apache.org on 2026/08/16 08:03:27 UTC
(iggy) 03/07: add proper docs
This is an automated email from the ASF dual-hosted git repository.
slbotbm pushed a commit to branch feat/add-python-stream-management-functions
in repository https://gitbox.apache.org/repos/asf/iggy.git
commit be1c3214092e3d7287b551d79a6b5cd35d5ab39b
Author: Rimuksh Kansal <ni...@gmail.com>
AuthorDate: Tue Aug 4 17:14:17 2026 +0900
add proper docs
---
foreign/python/src/client.rs | 70 +++++++++++++++++++++++++++++++++++++++-----
1 file changed, 62 insertions(+), 8 deletions(-)
diff --git a/foreign/python/src/client.rs b/foreign/python/src/client.rs
index 0bc15b93d..1d3a391ef 100644
--- a/foreign/python/src/client.rs
+++ b/foreign/python/src/client.rs
@@ -500,8 +500,16 @@ impl IggyClient {
})
}
- /// Gets all streams.
- /// Returns a list of streams or a PyRuntimeError on failure.
+ /// Return all streams visible to the authenticated user.
+ ///
+ /// The result is ordered by ascending numeric stream ID.
+ ///
+ /// 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.
#[gen_stub(override_return_type(type_repr="collections.abc.Awaitable[list[Stream]]", imports=("collections.abc")))]
fn get_streams<'a>(&self, py: Python<'a>) -> PyResult<Bound<'a, PyAny>> {
let inner = self.inner.clone();
@@ -514,8 +522,25 @@ impl IggyClient {
})
}
- /// Updates a stream's name by id.
- /// Returns Ok(()) on successful update or a PyRuntimeError on failure.
+ /// 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.
+ ///
+ /// Returns:
+ /// None.
+ ///
+ /// Raises:
+ /// TypeError: If `stream_id` is neither `str` nor `int`, or `name` is not
+ /// `str`.
+ /// OverflowError: If an integer identifier is outside `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, the new name is invalid or already used, or
+ /// the request fails.
#[gen_stub(override_return_type(type_repr="collections.abc.Awaitable[None]", imports=("collections.abc")))]
fn update_stream<'a>(
&self,
@@ -534,8 +559,22 @@ impl IggyClient {
})
}
- /// Deletes a stream by id.
- /// Returns Ok(()) on successful deletion or a PyRuntimeError on failure.
+ /// 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 neither `str` nor `int`.
+ /// OverflowError: If an integer identifier is outside `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.
#[gen_stub(override_return_type(type_repr="collections.abc.Awaitable[None]", imports=("collections.abc")))]
fn delete_stream<'a>(
&self,
@@ -553,8 +592,23 @@ impl IggyClient {
})
}
- /// Purges all messages from a stream by id.
- /// Returns Ok(()) on successful purge or a PyRuntimeError on failure.
+ /// 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 neither `str` nor `int`.
+ /// OverflowError: If an integer identifier is outside `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.
#[gen_stub(override_return_type(type_repr="collections.abc.Awaitable[None]", imports=("collections.abc")))]
fn purge_stream<'a>(
&self,