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:25 UTC
(iggy) 01/07: feat(python): add stream listing, update, delete, and purge
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 f1255a495d65795aa7954e639c96b8f838f53b9e
Author: Faisal Ahmed <fa...@gmail.com>
AuthorDate: Sun Jul 19 05:00:52 2026 +0530
feat(python): add stream listing, update, delete, and purge
Signed-off-by: Faisal Ahmed <fa...@gmail.com>
---
foreign/python/apache_iggy.pyi | 37 ++++
foreign/python/src/client.rs | 74 ++++++-
foreign/python/src/lib.rs | 3 +-
foreign/python/src/stream.rs | 38 +++-
foreign/python/tests/test_stream.py | 380 +++++++++++++++++++++++++++++++++++-
5 files changed, 528 insertions(+), 4 deletions(-)
diff --git a/foreign/python/apache_iggy.pyi b/foreign/python/apache_iggy.pyi
index 50b65786d..90d28292b 100644
--- a/foreign/python/apache_iggy.pyi
+++ b/foreign/python/apache_iggy.pyi
@@ -48,6 +48,7 @@ __all__ = [
"SendMessage",
"SendMessagesConfirmation",
"SendMessagesResponse",
+ "Stream",
"StreamDetails",
"StreamPermissions",
"TcpConfig",
@@ -1025,6 +1026,32 @@ class IggyClient:
ValueError: If the scope name is not one of the three above.
RuntimeError: If the request fails.
"""
+ def get_streams(self) -> collections.abc.Awaitable[list[Stream]]:
+ r"""
+ Gets all streams.
+ Returns a list of streams or a PyRuntimeError on failure.
+ """
+ def update_stream(
+ self, stream_id: builtins.str | builtins.int, name: builtins.str
+ ) -> collections.abc.Awaitable[None]:
+ r"""
+ Updates a stream's name by id.
+ Returns Ok(()) on successful update or a PyRuntimeError on failure.
+ """
+ def delete_stream(
+ self, stream_id: builtins.str | builtins.int
+ ) -> collections.abc.Awaitable[None]:
+ r"""
+ Deletes a stream by id.
+ Returns Ok(()) on successful deletion or a PyRuntimeError on failure.
+ """
+ def purge_stream(
+ self, stream_id: builtins.str | builtins.int
+ ) -> collections.abc.Awaitable[None]:
+ r"""
+ Purges all messages from a stream by id.
+ Returns Ok(()) on successful purge or a PyRuntimeError on failure.
+ """
def create_topic(
self,
stream: builtins.str | builtins.int,
@@ -1792,6 +1819,16 @@ class SendMessagesResponse:
with an offset a client has already recorded.
"""
+class Stream:
+ @property
+ def id(self) -> builtins.int: ...
+ @property
+ def name(self) -> builtins.str: ...
+ @property
+ def messages_count(self) -> builtins.int: ...
+ @property
+ def topics_count(self) -> builtins.int: ...
+
@typing.final
class StreamDetails:
@property
diff --git a/foreign/python/src/client.rs b/foreign/python/src/client.rs
index 816ba4e61..0bc15b93d 100644
--- a/foreign/python/src/client.rs
+++ b/foreign/python/src/client.rs
@@ -42,7 +42,7 @@ use crate::options::OptionSpec as PyOptionSpec;
use crate::permissions::Permissions as PyPermissions;
use crate::receive_message::{PollingStrategy, ReceiveMessage};
use crate::send_message::{SendMessage, SendMessagesResponse as PySendMessagesResponse};
-use crate::stream::StreamDetails;
+use crate::stream::{Stream, StreamDetails};
use crate::topic::{IggyExpiry, MaxTopicSize, Topic, TopicDetails};
use crate::user::{
UserInfo as PyUserInfo, UserInfoDetails as PyUserInfoDetails, UserStatus as PyUserStatus,
@@ -500,6 +500,78 @@ impl IggyClient {
})
}
+ /// Gets all streams.
+ /// Returns a list of streams or a PyRuntimeError on failure.
+ #[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();
+ future_into_py(py, async move {
+ let streams = inner
+ .get_streams()
+ .await
+ .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;
+ Ok(streams.into_iter().map(Stream::from).collect::<Vec<_>>())
+ })
+ }
+
+ /// Updates a stream's name by id.
+ /// Returns Ok(()) on successful update or a PyRuntimeError on failure.
+ #[gen_stub(override_return_type(type_repr="collections.abc.Awaitable[None]", imports=("collections.abc")))]
+ fn update_stream<'a>(
+ &self,
+ py: Python<'a>,
+ stream_id: PyIdentifier,
+ name: String,
+ ) -> PyResult<Bound<'a, PyAny>> {
+ let stream_id = Identifier::try_from(stream_id)?;
+ let inner = self.inner.clone();
+ future_into_py(py, async move {
+ inner
+ .update_stream(&stream_id, &name)
+ .await
+ .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;
+ Ok(())
+ })
+ }
+
+ /// Deletes a stream by id.
+ /// Returns Ok(()) on successful deletion or a PyRuntimeError on failure.
+ #[gen_stub(override_return_type(type_repr="collections.abc.Awaitable[None]", imports=("collections.abc")))]
+ fn delete_stream<'a>(
+ &self,
+ py: Python<'a>,
+ stream_id: PyIdentifier,
+ ) -> PyResult<Bound<'a, PyAny>> {
+ let stream_id = Identifier::try_from(stream_id)?;
+ let inner = self.inner.clone();
+ future_into_py(py, async move {
+ inner
+ .delete_stream(&stream_id)
+ .await
+ .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;
+ Ok(())
+ })
+ }
+
+ /// Purges all messages from a stream by id.
+ /// Returns Ok(()) on successful purge or a PyRuntimeError on failure.
+ #[gen_stub(override_return_type(type_repr="collections.abc.Awaitable[None]", imports=("collections.abc")))]
+ fn purge_stream<'a>(
+ &self,
+ py: Python<'a>,
+ stream_id: PyIdentifier,
+ ) -> PyResult<Bound<'a, PyAny>> {
+ let stream_id = Identifier::try_from(stream_id)?;
+ let inner = self.inner.clone();
+ future_into_py(py, async move {
+ inner
+ .purge_stream(&stream_id)
+ .await
+ .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;
+ Ok(())
+ })
+ }
+
/// Creates a new topic with the given parameters.
///
/// Args:
diff --git a/foreign/python/src/lib.rs b/foreign/python/src/lib.rs
index 7910af77b..d37d2a4de 100644
--- a/foreign/python/src/lib.rs
+++ b/foreign/python/src/lib.rs
@@ -40,7 +40,7 @@ use permissions::{GlobalPermissions, Permissions, StreamPermissions, TopicPermis
use pyo3::prelude::*;
use receive_message::{PollingStrategy, ReceiveMessage};
use send_message::{SendMessage, SendMessagesConfirmation, SendMessagesResponse};
-use stream::StreamDetails;
+use stream::{Stream, StreamDetails};
use topic::{IggyExpiry, MaxTopicSize, Partition, Topic, TopicDetails};
use user::{UserInfo, UserInfoDetails, UserStatus};
use user_headers::{HeaderKey, HeaderValue, UserHeaders};
@@ -57,6 +57,7 @@ fn apache_iggy(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
m.add_class::<TcpConfig>()?;
m.add_class::<TcpReconnectionConfig>()?;
m.add_class::<StreamDetails>()?;
+ m.add_class::<Stream>()?;
m.add_class::<Topic>()?;
m.add_class::<TopicDetails>()?;
m.add_class::<IggyExpiry>()?;
diff --git a/foreign/python/src/stream.rs b/foreign/python/src/stream.rs
index 7343d2c53..c4c7f5846 100644
--- a/foreign/python/src/stream.rs
+++ b/foreign/python/src/stream.rs
@@ -15,7 +15,7 @@
// specific language governing permissions and limitations
// under the License.
-use iggy::prelude::StreamDetails as RustStreamDetails;
+use iggy::prelude::{Stream as RustStream, StreamDetails as RustStreamDetails};
use pyo3::prelude::*;
use pyo3_stub_gen::derive::{gen_stub_pyclass, gen_stub_pymethods};
@@ -56,3 +56,39 @@ impl StreamDetails {
self.inner.topics_count
}
}
+
+#[gen_stub_pyclass]
+#[pyclass]
+pub struct Stream {
+ pub(crate) inner: RustStream,
+}
+
+impl From<RustStream> for Stream {
+ fn from(stream: RustStream) -> Self {
+ Self { inner: stream }
+ }
+}
+
+#[gen_stub_pymethods]
+#[pymethods]
+impl Stream {
+ #[getter]
+ pub fn id(&self) -> u32 {
+ self.inner.id
+ }
+
+ #[getter]
+ pub fn name(&self) -> String {
+ self.inner.name.to_string()
+ }
+
+ #[getter]
+ pub fn messages_count(&self) -> u64 {
+ self.inner.messages_count
+ }
+
+ #[getter]
+ pub fn topics_count(&self) -> u32 {
+ self.inner.topics_count
+ }
+}
diff --git a/foreign/python/tests/test_stream.py b/foreign/python/tests/test_stream.py
index 5e71a543a..8f757fab1 100644
--- a/foreign/python/tests/test_stream.py
+++ b/foreign/python/tests/test_stream.py
@@ -17,7 +17,7 @@
import pytest
-from apache_iggy import IggyClient
+from apache_iggy import IggyClient, SendMessage
from .utils import get_server_config, wait_for_ping, wait_for_server
@@ -203,3 +203,381 @@ class TestStreamOperations:
with pytest.raises(RuntimeError):
await client.create_stream(unique_name())
+
+
+class TestGetStreams:
+ """Test listing streams via get_streams."""
+
+ @pytest.mark.asyncio
+ async def test_get_streams_returns_created_streams(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test get_streams returns every stream created during the test."""
+ # Reverse-alphabetical names so that id-ascending (creation) order
+ # and name order disagree, proving the list isn't accidentally
+ # name-sorted. The client fixture is session-scoped, so other tests
+ # may have created streams; assert on the ones created here instead
+ # of the full server view.
+ created = [unique_name(f"z{index}") for index in range(3, 0, -1)]
+ for name in created:
+ await iggy_client.create_stream(name)
+
+ streams = await iggy_client.get_streams()
+ by_name = {stream.name: stream for stream in streams}
+ assert set(created).issubset(by_name)
+
+ mine = [by_name[name] for name in created]
+ assert [stream.id for stream in mine] == sorted(stream.id for stream in mine)
+ assert all(stream.messages_count == 0 for stream in mine)
+ assert all(stream.topics_count == 0 for stream in mine)
+
+ @pytest.mark.asyncio
+ async def test_get_streams_reflects_topic_count(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test get_streams reports the topic count for a listed stream."""
+ stream_name = unique_name()
+ topic_name = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+ await iggy_client.create_topic(
+ stream=stream_name, name=topic_name, partitions_count=1
+ )
+
+ streams = await iggy_client.get_streams()
+ listed = next(
+ (stream for stream in streams if stream.name == stream_name), None
+ )
+ assert listed is not None
+ assert listed.topics_count == 1
+
+ @pytest.mark.asyncio
+ async def test_get_streams_returns_same_result_when_called_repeatedly(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test repeated get_streams calls return an identically ordered view."""
+ await iggy_client.create_stream(unique_name())
+
+ first = await iggy_client.get_streams()
+ second = await iggy_client.get_streams()
+ assert [stream.id for stream in first] == [stream.id for stream in second]
+ assert [stream.name for stream in first] == [stream.name for stream in second]
+
+ @pytest.mark.asyncio
+ async def test_get_streams_before_connect_fails(self):
+ """Test get_streams requires an established connection."""
+ host, port = get_server_config()
+ client = IggyClient(f"{host}:{port}")
+
+ with pytest.raises(RuntimeError):
+ await client.get_streams()
+
+ @pytest.mark.asyncio
+ async def test_get_streams_before_login_fails(self):
+ """Test get_streams requires authentication."""
+ host, port = get_server_config()
+ wait_for_server(host, port)
+
+ client = IggyClient(f"{host}:{port}")
+ await client.connect()
+
+ with pytest.raises(RuntimeError):
+ await client.get_streams()
+
+
+class TestUpdateStream:
+ """Test updating streams via update_stream."""
+
+ @pytest.mark.asyncio
+ async def test_update_stream_renames_stream(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test update_stream renames a stream; old name no longer resolves."""
+ stream_name = unique_name()
+ new_name = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+
+ await iggy_client.update_stream(stream_id=stream_name, name=new_name)
+
+ renamed = await iggy_client.get_stream(new_name)
+ assert renamed is not None
+ assert renamed.name == new_name
+
+ old = await iggy_client.get_stream(stream_name)
+ assert old is None
+
+ @pytest.mark.asyncio
+ async def test_update_stream_preserves_id(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test update_stream keeps the same numeric id after a rename."""
+ stream_name = unique_name()
+ new_name = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+ before = await iggy_client.get_stream(stream_name)
+ assert before is not None
+
+ await iggy_client.update_stream(stream_id=stream_name, name=new_name)
+
+ after = await iggy_client.get_stream(new_name)
+ assert after is not None
+ assert after.id == before.id
+
+ @pytest.mark.asyncio
+ async def test_update_stream_by_numeric_id(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test update_stream accepts a numeric stream id."""
+ stream_name = unique_name()
+ new_name = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+ stream = await iggy_client.get_stream(stream_name)
+ assert stream is not None
+
+ await iggy_client.update_stream(stream_id=stream.id, name=new_name)
+
+ renamed = await iggy_client.get_stream(new_name)
+ assert renamed is not None
+ assert renamed.name == new_name
+
+ @pytest.mark.asyncio
+ async def test_update_stream_applies_repeated_updates(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test successive update_stream calls each take effect."""
+ stream_name = unique_name()
+ first_rename = unique_name()
+ second_rename = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+
+ await iggy_client.update_stream(stream_id=stream_name, name=first_rename)
+ after_first = await iggy_client.get_stream(first_rename)
+ assert after_first is not None
+ assert after_first.name == first_rename
+ assert await iggy_client.get_stream(stream_name) is None
+
+ await iggy_client.update_stream(stream_id=first_rename, name=second_rename)
+ after_second = await iggy_client.get_stream(second_rename)
+ assert after_second is not None
+ assert after_second.name == second_rename
+ assert await iggy_client.get_stream(first_rename) is None
+
+ @pytest.mark.asyncio
+ async def test_update_nonexistent_stream_fails(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test update_stream raises for a non-existent stream."""
+ with pytest.raises(RuntimeError):
+ await iggy_client.update_stream(stream_id=unique_name(), name=unique_name())
+
+ @pytest.mark.asyncio
+ async def test_update_stream_to_existing_name_fails(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test update_stream rejects renaming a stream to a name already in use."""
+ first_stream = unique_name()
+ second_stream = unique_name()
+
+ await iggy_client.create_stream(first_stream)
+ await iggy_client.create_stream(second_stream)
+
+ with pytest.raises(RuntimeError):
+ await iggy_client.update_stream(stream_id=second_stream, name=first_stream)
+
+ @pytest.mark.asyncio
+ async def test_update_stream_requires_connection_and_auth(self, unique_name):
+ """Test update_stream fails both before connecting and before logging in."""
+ host, port = get_server_config()
+ wait_for_server(host, port)
+
+ client = IggyClient(f"{host}:{port}")
+ with pytest.raises(RuntimeError):
+ await client.update_stream(stream_id=unique_name(), name=unique_name())
+
+ await client.connect()
+ with pytest.raises(RuntimeError):
+ await client.update_stream(stream_id=unique_name(), name=unique_name())
+
+
+class TestDeleteStream:
+ """Test deleting streams via delete_stream."""
+
+ @pytest.mark.asyncio
+ async def test_delete_stream_removes_stream(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test delete_stream removes the stream so it no longer resolves."""
+ stream_name = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+
+ await iggy_client.delete_stream(stream_name)
+
+ assert await iggy_client.get_stream(stream_name) is None
+
+ @pytest.mark.asyncio
+ async def test_delete_stream_by_numeric_id(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test delete_stream accepts a numeric stream id."""
+ stream_name = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+ stream = await iggy_client.get_stream(stream_name)
+ assert stream is not None
+
+ await iggy_client.delete_stream(stream.id)
+
+ assert await iggy_client.get_stream(stream_name) is None
+
+ @pytest.mark.asyncio
+ async def test_delete_stream_leaves_other_streams(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test delete_stream removes only the targeted stream."""
+ stream_to_delete = unique_name()
+ stream_to_keep = unique_name()
+
+ await iggy_client.create_stream(stream_to_delete)
+ await iggy_client.create_stream(stream_to_keep)
+
+ await iggy_client.delete_stream(stream_to_delete)
+
+ assert await iggy_client.get_stream(stream_to_delete) is None
+ kept = await iggy_client.get_stream(stream_to_keep)
+ assert kept is not None
+ assert kept.name == stream_to_keep
+
+ @pytest.mark.asyncio
+ async def test_delete_nonexistent_stream_fails(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test delete_stream raises for a non-existent stream."""
+ with pytest.raises(RuntimeError):
+ await iggy_client.delete_stream(unique_name())
+
+ @pytest.mark.asyncio
+ async def test_delete_stream_twice_fails_second_time(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test deleting an already-deleted stream raises on the second call."""
+ stream_name = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+
+ await iggy_client.delete_stream(stream_name)
+ with pytest.raises(RuntimeError):
+ await iggy_client.delete_stream(stream_name)
+
+ @pytest.mark.asyncio
+ async def test_delete_stream_requires_connection_and_auth(self, unique_name):
+ """Test delete_stream fails both before connecting and before logging in."""
+ host, port = get_server_config()
+ wait_for_server(host, port)
+
+ client = IggyClient(f"{host}:{port}")
+ with pytest.raises(RuntimeError):
+ await client.delete_stream(unique_name())
+
+ await client.connect()
+ with pytest.raises(RuntimeError):
+ await client.delete_stream(unique_name())
+
+
+class TestPurgeStream:
+ """Test purging stream messages via purge_stream."""
+
+ @pytest.mark.asyncio
+ async def test_purge_stream_clears_messages_but_keeps_stream(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test purge_stream empties the stream while leaving it in place."""
+ stream_name = unique_name()
+ topic_name = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+ await iggy_client.create_topic(
+ stream=stream_name, name=topic_name, partitions_count=1
+ )
+
+ messages = [SendMessage(f"payload-{index}") for index in range(5)]
+ await iggy_client.send_messages(stream_name, topic_name, 0, messages)
+
+ before = await iggy_client.get_stream(stream_name)
+ assert before is not None
+ assert before.messages_count == 5
+
+ await iggy_client.purge_stream(stream_name)
+
+ after = await iggy_client.get_stream(stream_name)
+ # Purging clears messages only; the stream itself survives (purge is
+ # not delete) and keeps its identity and topics.
+ assert after is not None
+ assert after.messages_count == 0
+ assert after.id == before.id
+ assert after.name == before.name
+ assert after.topics_count == before.topics_count
+
+ @pytest.mark.asyncio
+ async def test_purge_empty_stream_succeeds(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test purge_stream is a no-op on a stream with no messages."""
+ stream_name = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+
+ await iggy_client.purge_stream(stream_name)
+
+ stream = await iggy_client.get_stream(stream_name)
+ assert stream is not None
+ assert stream.messages_count == 0
+
+ @pytest.mark.asyncio
+ async def test_purge_stream_is_idempotent_when_called_repeatedly(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test purge_stream succeeds when called repeatedly on the same stream."""
+ stream_name = unique_name()
+ topic_name = unique_name()
+
+ await iggy_client.create_stream(stream_name)
+ await iggy_client.create_topic(
+ stream=stream_name, name=topic_name, partitions_count=1
+ )
+
+ messages = [SendMessage(f"payload-{index}") for index in range(5)]
+ await iggy_client.send_messages(stream_name, topic_name, 0, messages)
+
+ await iggy_client.purge_stream(stream_name)
+ await iggy_client.purge_stream(stream_name)
+
+ stream = await iggy_client.get_stream(stream_name)
+ assert stream is not None
+ assert stream.messages_count == 0
+
+ @pytest.mark.asyncio
+ async def test_purge_nonexistent_stream_fails(
+ self, iggy_client: IggyClient, unique_name
+ ):
+ """Test purge_stream raises for a non-existent stream."""
+ with pytest.raises(RuntimeError):
+ await iggy_client.purge_stream(unique_name())
+
+ @pytest.mark.asyncio
+ async def test_purge_stream_requires_connection_and_auth(self, unique_name):
+ """Test purge_stream fails both before connecting and before logging in."""
+ host, port = get_server_config()
+ wait_for_server(host, port)
+
+ client = IggyClient(f"{host}:{port}")
+ with pytest.raises(RuntimeError):
+ await client.purge_stream(unique_name())
+
+ await client.connect()
+ with pytest.raises(RuntimeError):
+ await client.purge_stream(unique_name())