DiscordPYComponents 1.3.1__tar.gz → 1.4.0__tar.gz

{discordpycomponents-1.3.1 → discordpycomponents-1.4.0}/DiscordPYComponents.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DiscordPYComponents
-Version: 1.3.1
+Version: 1.4.0
 Summary: Discord Components V2 for discord.py
 Author: 2gm49
 License: MIT
@@ -82,6 +82,9 @@ await ui.send(ctx)
 | `await ui.send(target, ephemeral=False, files=None)` | channel or interaction |
 | `await ui.reply(interaction, ...)` | same as send on an interaction |
 | `await ui.edit(target, message=None)` | edit interaction original / a Message |
+| `await ui.update(interaction)` | edit the message a button/select was used on |
+| `ui.count()` | total components, nested ones included |
+| `UI.from_payload(data)` | rebuild a UI from a raw payload or components list |
 
 `send` / `reply` try discord.py first (`ctx.send`, `interaction.response.send_message`, `followup.send`). Falls back to raw HTTP if that fails.
 
@@ -93,9 +96,21 @@ await ui.edit(interaction)
 await ui.edit(message)
 ```
 
-Also: `await send_ui(target, ui)` — same as `ui.send(target)`.
+Also: `await send_ui(target, ui)`, same as `ui.send(target)`.
 
-Loose `Button`s are auto-wrapped into `ActionRow`s (5 per row). Put selects in an `ActionRow` yourself.
+Loose `Button`s are auto-wrapped into `ActionRow`s (5 per row). Loose selects get their own `ActionRow`.
+
+`to_payload()` raises `ValueError` if the message would go over Discord's 40 component limit (nested components count too).
+
+### Send options
+
+```python
+await ui.send(ctx, silent=True)                      # no push notification
+await ui.send(ctx, allowed_mentions=discord.AllowedMentions.none())
+await ui.reply(interaction, ephemeral=True)
+```
+
+Pings inside `TextDisplay` follow `allowed_mentions`.
 
 ---
 
@@ -129,6 +144,8 @@ Thumbnail("https://cdn.discordapp.com/...", description="icon", spoiler=False)
 | `spoiler` | blur it |
 | `id` | optional |
 
+`url` can be `attachment://name.png` to use a file sent with the message.
+
 ### MediaGallery / MediaGalleryItem
 
 1–10 media items.
@@ -145,7 +162,12 @@ MediaGallery(
 | `*items` | urls and/or `MediaGalleryItem` |
 | `id` | optional |
 
-`MediaGalleryItem(url, description=None, spoiler=False)`
+`MediaGalleryItem(url, description=None, spoiler=False)`. Description max 1024.
+
+```python
+gallery = MediaGallery("https://example.com/a.png")
+gallery.add("https://example.com/b.png")
+```
 
 ### File
 
@@ -162,13 +184,15 @@ File("attachment://report.pdf", spoiler=True)
 | `spoiler` | blur it |
 | `id` | optional |
 
+When you read a File back from a message (`UI.from_payload`), `.name` and `.size` are filled in from Discord.
+
 ---
 
 ## Layout components
 
 ### ActionRow
 
-Holds up to 5 buttons **or** one select.
+Holds up to 5 buttons **or** one select. Mixing them raises `ValueError`.
 
 ```python
 ActionRow(
@@ -180,7 +204,7 @@ ActionRow(StringSelect("pick", options=[...]))
 
 ### Section
 
-1–3 TextDisplays + optional accessory (Button or Thumbnail).
+1–3 TextDisplays + optional accessory (Button or Thumbnail). Plain strings are turned into TextDisplays.
 
 ```python
 Section(
@@ -219,11 +243,13 @@ Container(
 )
 ```
 
-Children can be ActionRow, TextDisplay, Section, MediaGallery, Separator, File.
+Children can be ActionRow, TextDisplay, Section, MediaGallery, Separator, File. Anything else raises `ValueError`.
+
+`accent_color` takes an int (`0x000000`–`0xFFFFFF`) or a `discord.Colour`. `accent_colour=` works too.
 
 ```python
-c = Container(TextDisplay("x"))
-c.add(Separator())
+c = Container(TextDisplay("x"), accent_color=discord.Colour.blurple())
+c.add(Separator(), TextDisplay("more"))
 ```
 
 ---
@@ -250,7 +276,7 @@ Button(
 | `LINK` | 5 | url= |
 | `PREMIUM` | 6 | sku_id= |
 
-Lowercase aliases work too: `ButtonStyle.primary`, etc.
+Lowercase aliases work too: `ButtonStyle.primary`, and the discord.py names `blurple`, `grey`, `green`, `red`, `url`.
 
 ```python
 Button("docs", style=ButtonStyle.LINK, url="https://discord.com/developers/docs")
@@ -260,7 +286,11 @@ Button("nope", custom_id="x", disabled=True)
 
 Must sit in an ActionRow or as a Section accessory. UI auto-wraps loose buttons.
 
-Label max 80 chars. custom_id 1–100 chars.
+Rules (checked when you create the button):
+- needs a `label` or an `emoji` (except PREMIUM)
+- label max 80, custom_id 1–100, url max 512
+- LINK: `url`, no `custom_id`
+- PREMIUM: `sku_id` only, no label, emoji, url or custom_id
 
 ---
 
@@ -268,6 +298,8 @@ Label max 80 chars. custom_id 1–100 chars.
 
 All selects need a `custom_id`. In messages they go inside an ActionRow (one select per row). In modals they go inside a Label.
 
+Shared rules: `placeholder` max 150, `min_values` 0–25, `max_values` 1–25, `min_values <= max_values`. If you set `required=True`, `min_values` must be at least 1.
+
 ### SelectOption (StringSelect only)
 
 ```python
@@ -278,8 +310,12 @@ SelectOption(
     emoji="🔴",
     default=False,
 )
+
+SelectOption("Red")   # value defaults to the label
 ```
 
+Label, value and description max 100.
+
 ### StringSelect
 
 ```python
@@ -297,7 +333,7 @@ StringSelect(
 )
 ```
 
-1–25 options.
+1–25 options with unique values. `max_values` can't be more than the number of options. Plain strings work as options: `StringSelect("colour", ["red", "blue"])`.
 
 ### UserSelect / RoleSelect / MentionableSelect / ChannelSelect
 
@@ -322,8 +358,23 @@ ChannelSelect(
 )
 ```
 
-`default_values` entries: `{"id": "<snowflake>", "type": "user"|"role"|"channel"}`.
+`default_values` takes any of:
+
+```python
+from py_components import SelectDefaultValue, ChannelType
 
+UserSelect("u", default_values=[member, 1234567890])            # objects or ids
+RoleSelect("r", default_values=[SelectDefaultValue.role(role)])
+MentionableSelect("m", default_values=[
+    SelectDefaultValue.user(111),
+    SelectDefaultValue.role(222),
+])
+ChannelSelect("c", channel_types=[ChannelType.text, ChannelType.voice],
+              default_values=[channel])
+{"id": "<snowflake>", "type": "user"}                            # raw dicts still work
+```
+
+The number of defaults has to fit between `min_values` and `max_values`, and the type has to match the select (MentionableSelect needs `SelectDefaultValue.user/role` for bare ids).
 `required` only matters in modals. `disabled` only in messages (modals error if disabled).
 
 ---
@@ -337,6 +388,8 @@ make_emoji("🔥")
 make_emoji("pepe", id=123456789012345678, animated=True)
 ```
 
+Anywhere an emoji is accepted you can pass a unicode string, a `<:name:id>` / `<a:name:id>` string, a dict, or a discord.py `Emoji` / `PartialEmoji`.
+
 Buttons and SelectOptions also take a plain unicode string:
 
 ```python
@@ -370,6 +423,19 @@ replace_by_id(payload["components"], 10, TextDisplay("x", id=10).to_dict())
 
 Use this when editing a message and only changing one piece.
 
+Ids are only added to components, never to media gallery items.
+
+### Reading components back
+
+```python
+from py_components import UI, component_from_dict
+
+ui = UI.from_payload(raw_message_dict)       # or a components list
+first = component_from_dict(raw_message_dict["components"][0])
+```
+
+Every component class builds from its raw dict. Component types this library doesn't know yet come back as `UnknownComponent`, which keeps the raw data and sends it back unchanged.
+
 ---
 
 ## Modals
@@ -377,7 +443,7 @@ Use this when editing a message and only changing one piece.
 ```python
 from py_components import (
     Modal, Label, TextInput, TextInputStyle,
-    RadioGroup, RadioGroupOption, CheckboxGroup, Checkbox,
+    RadioGroup, RadioGroupOption, CheckboxGroup, GroupOption, Checkbox,
     FileUpload, StringSelect, SelectOption,
 )
 
@@ -415,7 +481,9 @@ async def report(interaction):
     await modal.open(interaction)
 ```
 
-Max **5** top-level components. Top-level should be `Label` (or `TextDisplay`). Interactive controls go **inside** Label.
+Max **5** top-level components. Top-level must be `Label` or `TextDisplay`. Interactive controls go **inside** a Label. Components inside a modal can't be `disabled`. All of this is checked when you build the modal.
+
+`modal.open(interaction)` must be the first response to the interaction. It raises if you've already responded.
 
 ### Modal
 
@@ -435,7 +503,7 @@ Title max 45 chars. custom_id 1–100.
 Label("visible label", child_component, description="optional helper text")
 ```
 
-Label text max 45. Description max 100. One child.
+Label text max 45. Description max 100. One child: TextInput, any select, FileUpload, RadioGroup, CheckboxGroup or Checkbox.
 
 ### TextInput
 
@@ -451,6 +519,10 @@ TextInput(
 )
 ```
 
+min_length 0–4000, max_length 1–4000, value max 4000, placeholder max 100.
+
+`TextInput(..., label="...")` still works for old ActionRow modals but gives a `DeprecationWarning`. Use `Label` instead.
+
 ### FileUpload
 
 ```python
@@ -463,6 +535,8 @@ FileUpload(
 )
 ```
 
+Up to 10 files, up to 10 `file_types` (`image`, `video`, `audio` or a `.ext`). File size follows the user's own upload limit.
+
 ### RadioGroup / CheckboxGroup / Checkbox
 
 ```python
@@ -478,10 +552,12 @@ CheckboxGroup(
     required=True,
 )
 
-# single yes/no — label comes from the Label wrapper
+# single yes/no, label comes from the Label wrapper
 Checkbox("agree", default=False)
 ```
 
+A Checkbox can't be required. For a "must tick" box, use a CheckboxGroup with one option and `required=True`. RadioGroup allows one `default` option.
+
 `GroupOption` / `RadioGroupOption` / `CheckboxGroupOption` are the same thing:
 
 ```python
@@ -490,7 +566,39 @@ GroupOption("label", "value", description="...", default=False)
 
 Selects also work inside Label in modals (StringSelect, UserSelect, etc.).
 
-On submit you get a `MODAL_SUBMIT` interaction. Values are under `interaction.data["components"]` (each Label wraps its filled child).
+### Reading a modal submit
+
+```python
+from py_components import ModalSubmit
+
+@bot.event
+async def on_interaction(interaction):
+    if interaction.type.name == "modal_submit" and interaction.data["custom_id"] == "apply":
+        form = ModalSubmit(interaction)
+
+        why = form.text("why")                 # TextInput -> str
+        level = form.get("exp", "none")        # RadioGroup -> str or None
+        teams = form.selected("teams")         # CheckboxGroup / selects -> list[str]
+        agreed = form.checked("rules")         # Checkbox -> bool
+        files = form.attachments("shots")      # FileUpload -> attachment dicts
+        refs = form.users("ref")               # UserSelect -> resolved user dicts
+
+        await interaction.response.send_message(f"thanks, got {len(files)} files", ephemeral=True)
+```
+
+| method | returns |
+|--------|---------|
+| `form["id"]` | raw value |
+| `form.get("id", default)` | value, or default if empty |
+| `form.text("id")` | str |
+| `form.checked("id")` | bool |
+| `form.selected("id")` | list of str |
+| `form.attachments("id")` | uploaded attachment dicts |
+| `form.users / members / roles / channels("id")` | resolved objects for selects |
+| `form.values()` | dict of every custom_id and value |
+| `form.fields` | `SubmittedField` objects (custom_id, type, id, value, raw) |
+
+Works with a discord.py `Interaction` or a raw interaction dict. `parse_modal(x)` is the same as `ModalSubmit(x)`.
 
 ---
 
@@ -553,9 +661,29 @@ Wire it up in your bot:
 ```python
 @bot.event
 async def on_interaction(interaction):
-    if interaction.type.name == "component":
-        cid = interaction.data.get("custom_id")
-        await default_registry.dispatch(cid, interaction)
+    if interaction.type.name in ("component", "modal_submit"):
+        await default_registry.dispatch_interaction(interaction)
+```
+
+`dispatch_interaction` reads the custom_id for you and returns False if nothing matched. Views have the same method, plus `view.add_select(select, callback=...)`.
+
+### Reading a button or select
+
+```python
+from py_components import ComponentClick
+
+click = ComponentClick(interaction)
+click.custom_id      # "range"
+click.values         # ["7d"] for selects, [] for buttons
+click.value          # first value or None
+click.is_select      # True
+click.resolved       # users / roles / channels for entity selects
+```
+
+Answer by editing the message in place:
+
+```python
+await new_ui.update(interaction)
 ```
 
 ---
@@ -583,11 +711,18 @@ API base: `https://discord.com/api/v10`.
 
 ```python
 from py_components import (
-    ComponentType,      # ACTION_ROW=1, BUTTON=2, ... CHECKBOX=23
-    ButtonStyle,        # PRIMARY..PREMIUM
-    TextInputStyle,     # SHORT=1, PARAGRAPH=2
-    SeparatorSpacing,   # SMALL=1, LARGE=2
-    IS_COMPONENTS_V2,   # 1 << 15
+    ComponentType,             # ACTION_ROW=1, BUTTON=2, ... CHECKBOX=23
+    ButtonStyle,               # PRIMARY..PREMIUM
+    TextInputStyle,            # SHORT=1, PARAGRAPH=2
+    SeparatorSpacing,          # SMALL=1, LARGE=2
+    ChannelType,               # GUILD_TEXT=0, GUILD_VOICE=2, ... (for ChannelSelect)
+    InteractionResponseType,   # UPDATE_MESSAGE=7, MODAL=9, ...
+    MessageFlags,              # EPHEMERAL, SUPPRESS_NOTIFICATIONS, IS_COMPONENTS_V2
+    IS_COMPONENTS_V2,          # 1 << 15
+    EPHEMERAL,                 # 1 << 6
+    SUPPRESS_NOTIFICATIONS,    # 1 << 12
+    MAX_MESSAGE_COMPONENTS,    # 40
+    MAX_MODAL_COMPONENTS,      # 5
 )
 ```
 
@@ -685,9 +820,30 @@ await modal.open(interaction)
 - 40 components max per message
 - buttons: ActionRow or Section accessory
 - one select per ActionRow
-- modals: max 5 top-level components
+- modals: max 5 top-level components, title ≤45
 - Label label ≤45, description ≤100
-- Button label ≤80, custom_id ≤100
+- Button label ≤80, custom_id ≤100, url ≤512
+- select placeholder ≤150, 0–25 values, 25 options
+- TextDisplay ≤4000, thumbnail/gallery descriptions ≤1024
+- component `id` is a 32-bit int, unique in the message
+
+The library checks these when you build components, so mistakes show up as a `ValueError` in your code instead of a 400 from Discord.
+
+## Changelog
+
+### 1.4.0
+- Read components back: `UI.from_payload`, `component_from_dict`, `UnknownComponent` for future types
+- `ModalSubmit` / `parse_modal` to read modal answers, including file uploads and resolved users, roles and channels
+- `ComponentClick` / `parse_component` for buttons and selects
+- `Registry.dispatch_interaction` and `View.dispatch_interaction` for components and modals
+- `SelectDefaultValue` and object/id support for select `default_values`
+- `ChannelType`, `InteractionResponseType`, `MessageFlags` enums
+- `ui.send(silent=True, allowed_mentions=...)`, `ui.update()`, `ui.count()`
+- Loose selects in a `UI` or `View` are wrapped in an ActionRow automatically
+- Validation for every Discord limit: 40 component cap, placeholder, option counts, min/max values, file types, button rules, container and section children, modal children, accent colour range
+- Emoji accepts `<:name:id>` strings and discord.py emoji objects; Container accepts `discord.Colour`
+- `TextInput(label=...)` kept for legacy modals with a deprecation warning
+- Fixed: ids were being added to media gallery items
 
 ## License
 

{discordpycomponents-1.3.1 → discordpycomponents-1.4.0}/DiscordPYComponents.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ py_components/components.py
 py_components/enums.py
 py_components/http.py
 py_components/ids.py
+py_components/interactions.py
 py_components/modal.py
 py_components/registry.py
 py_components/ui.py