ezytools 0.2.0__tar.gz → 0.3.1__tar.gz

{ezytools-0.2.0 → ezytools-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ezytools
-Version: 0.2.0
+Version: 0.3.1
 Summary: A Python utility library for Yapper bot developers
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -17,6 +17,73 @@ All implementation lives in `src/ezytools/core.py`. The package initializer only
 re-exports it. Install with `python -m pip install .`, or copy `core.py` into your
 bot folder as `ezytools.py` to use it as a standalone file.
 
+## What's new
+
+**0.3.1 — documentation update:** voice documentation is now near the top,
+with navigation links below. No runtime behavior changed from 0.3.0.
+
+**Added in 0.3.0:** 12 voice helpers for moving/disconnecting members,
+bulk actions, voice membership lookups, and bot voice connections.
+
+```shell
+python -m pip install --upgrade ezytools
+```
+
+## Documentation
+
+- [Voice shortcuts and examples](#voice-shortcuts)
+- [Member, role, and channel workflows](#workflows)
+- [Bot-building helpers](#bot-building)
+- [Developer utilities](#developer-utilities)
+- [Moderation utilities](#moderation-utilities)
+- [License](https://github.com/Adecode-23/ezytools/blob/main/LICENSE)
+
+<a id="voice-shortcuts"></a>
+
+## Voice shortcuts
+
+
+Requires a Yapper SDK exposing `voice`, `move_member`, `disconnect_member`,
+`join_voice`, `leave_voice`, and (for audio) `connect_voice`.
+Existing utilities remain available. Implementations stay in `src/ezytools/core.py`.
+
+```python
+import ezytools as e
+
+members = e.voice_members(bot, server_id, channel_id)
+count = e.voice_member_count(bot, server_id, channel_id)
+current = e.member_voice_channel(bot, server_id, user_id)  # ID or None
+present = e.is_in_voice(bot, server_id, user_id)
+snapshot = e.voice_channels(bot, server_id)
+
+# Authorise the command user first (e.g. command_guard / require_roles).
+e.move_member(bot, server_id, user_id, destination_channel_id)
+e.disconnect_member(bot, server_id, user_id)
+e.move_members(bot, server_id, [user_id, other_id], destination_channel_id)
+e.disconnect_members(bot, server_id, [user_id, other_id])
+
+# A ticket alone does not connect audio; do not log its secret fields.
+ticket = e.join_voice(bot, server_id, channel_id)
+e.leave_voice(bot, server_id)
+
+# Inside an async function, with SDK audio dependencies installed:
+call = await e.connect_voice(bot, server_id, channel_id)
+try:
+    pass  # Use the SDK call.source to supply audio frames.
+finally:
+    await call.leave()
+```
+
+Moving requires a member already connected to voice; helpers cannot force
+someone to join a call. Server permissions and SDK errors still apply.
+Bulk actions validate all IDs first and deduplicate them; execution stops at
+the first failure, leaving earlier successful actions applied. Respect platform
+rate limits; there are no automatic retries or background moderation actions.
+Voice snapshots can change between lookup and action. Audio connections require
+the Yapper SDK's optional `livekit` and `cryptography` dependencies.
+
+<a id="workflows"></a>
+
 ## Faster workflows inside your handlers
 
 You write the command, decide who can run it, handle missing data, and choose the
@@ -75,6 +142,8 @@ or expression evaluation; supplied mentions and Markdown stay active.
 `msg.argv`. For strict quote validation with usage feedback, use
 `command_arguments(msg, ...)` instead.
 
+<a id="bot-building"></a>
+
 ## Yapper bot-building helpers
 
 These helpers use the synchronous Yapper SDK's command, event, member, role,
@@ -149,6 +218,8 @@ Help reads the command list when invoked, so later commands appear automatically
 `hidden=["internal"]` hides names from help only; guards enforce access.
 See [the runnable example](examples/yapper_bot.py) for environment-based setup.
 
+<a id="developer-utilities"></a>
+
 ## Developer utilities
 
 Install the package from this checkout (Python 3.10+):
@@ -283,6 +354,8 @@ your-project/
 import ezytools
 ```
 
+<a id="moderation-utilities"></a>
+
 ## 🛡️ Moderation Utilities
 
 Ezytools currently provides these moderation helpers:
@@ -451,3 +524,5 @@ Ezytools is a developing Python utility library focused on making bot developmen
 More utilities can be added as the library develops.
 
 
+
+