|
1 | | -# 1.x -> 2.x Migration Guide |
2 | | -2.x Was a rewrite of various parts of Naff, and as such, there are a few breaking changes. This guide will help you migrate your code from 1.x to 2.x. |
3 | | - |
4 | | -Please note; there are other additions to 2.x, but they are not breaking changes, and as such, are not covered in this guide. |
5 | | - |
6 | | -## Misc. |
7 | | -- All `edit` methods are now keyword arguments only. |
8 | | - - The exception is `content` on message edits, which is positional. |
9 | | -- `context.interaciton_id` is now an `int` instead of a `str`. |
10 | | - |
11 | | -## Selects |
12 | | -To simplify SelectMenus, NAFF made some changes to how SelectMenus are used. |
13 | | -- Options can now be and *reasonable* type, be it `SelectOption`, `dict`, `iterable` or `str` |
14 | | -- All parameters are now keyword only, excpet for `options` which remains positional or keyword |
15 | | -- `Select` was renamed to `StringSelectMenu` |
16 | | -- New select menus were implemented to support API changes |
17 | | - - https://discord.com/developers/docs/interactions/message-components#select-menus |
18 | | - - `UserSelectMenu` |
19 | | - - `RoleSelectMenu` |
20 | | - - `MentionableSelectMenu` |
21 | | - - `ChannelSelectMenu` |
22 | | - - `ChannelSelectMenu` |
23 | | - |
24 | | -### Before |
25 | | -```python |
26 | | -from naff import Select, SelectOption |
27 | | -await channel.send( |
28 | | - "Old SelectUX", |
29 | | - components=Select( |
30 | | - options=[ |
31 | | - SelectOption("test1", "test1"), |
32 | | - SelectOption("test2", "test2"), |
33 | | - SelectOption("test3", "test3"), |
34 | | - ], |
35 | | - placeholder="test", |
36 | | - ), |
37 | | - ) |
38 | | -``` |
39 | | - |
40 | | -### After |
41 | | -```python |
42 | | -from naff import StringSelectMenu |
43 | | - |
44 | | -await channel.send( |
45 | | - "New SelectMenu Menu UX test", components=StringSelectMenu(["test1", "test2", "test3"], placeholder="test") |
46 | | - ) |
47 | | -``` |
48 | | - |
49 | | -## Listeners |
50 | | -Listeners have received a series of ease-of-use updates for both extension and bot developers alike. |
51 | | - |
52 | | -- All internal listeners now have a `is_default_listener` attribute to make it easier to differentiate between the library's listeners and user defined listeners. |
53 | | -- `override_default_listeners` allows you to completely override the library's listeners with your own. |
54 | | - - Note it might be worth looking into processors if you're doing this; as they allow acting on the raw-payloads before they're processed by the library. |
55 | | -- All event objects now have a shortcut to listen to them via `BaseEvent.listen(coro, Client)` |
56 | | -- Listeners can now be delayed until the client is ready with a `delay_until_ready` argument. |
57 | | - |
58 | | -## Events |
59 | | -- All event objects now have a shortcut to listen to them via `BaseEvent.listen(coro, Client)` |
60 | | -- New Events! |
61 | | - - `ComponentCompletion` - Dispatched after the library ran any component callback. |
62 | | - - `AutocompleteCompletion` - Dispatched after the library ran any autocomplete callback. |
63 | | - - `ModalCompletion` - Dispatched after the library ran any modal callback. |
64 | | - - `Error` - Dispatched whenever the libray encounters an unhandled exception. |
65 | | - - Previously this was done by overriding the `on_error` method on the client, or in extensions |
66 | | - - `CommandError` - Dispatched whenever a command encounters an unhandled exception. |
67 | | - - `ComponentError` - Dispatched whenever a component encounters an unhandled exception. |
68 | | - - `AutocompleteError` - Dispatched whenever an autocomplete encounters an unhandled exception. |
69 | | - - `ModalError` - Dispatched whenever a modal encounters an unhandled exception. |
70 | | - - `NewThreadCreate` - Dispatched whenever a thread is newly created |
71 | | - - `GuildAvailable` - Dispatched whenever a guild becomes available |
72 | | - - note this requires the guild cache to be enabled |
73 | | - - `ApplicationCommandPermissionsUpdate` - Dispatched whenever a guild's application command permissions are updated |
74 | | - - `VoiceUserDeafen` - Dispatched whenever a user's deafen status changes |
75 | | - - `VoiceUserJoin` - Dispatched whenever a user joins a voice channel |
76 | | - - `VoiceUserLeave` - Dispatched whenever a user leaves a voice channel |
77 | | - - `VoiceUserMove` - Dispatched whenever a user moves to a different voice channel |
78 | | - - `VoiceUserMute` - Dispatched whenever a user's mute status changes |
79 | | -- Event Renamed |
80 | | - - `Button` has been renamed to `ButtonPressed` to avoid naming conflicts |
81 | | -- All events with a `context` attribute have had it renamed to `ctx` for consistency |
82 | | - |
83 | | -## Client Changes |
84 | | -- dm commands can now be disabled completely via the `disable_dm_commands` kwarg |
85 | | -- `Client.interaction_tree` offers a command tree of all application commands registered to the client |
86 | | -- The `Client` now sanity checks the cache configuration |
87 | | -- The `Client` will no longer warn you if a cache timeout occurs during startup |
88 | | - - These are caused by T&S shadow-deleting guilds, and are not a concern |
89 | | -- `async_startup_tasks` are now performed as soon as the client successfully connects to the REST API |
90 | | - - Note this is before the gateway connection is established, use a `on_ready` listener if you need to wait for the gateway connection |
91 | | -- Application Command syncing is now more error tolerant |
92 | | - |
93 | | -## Extensions |
94 | | -- Extensions no longer require a `setup` entrypoint function. |
95 | | - - For complex setups, I would still advise using an entrypoint function |
96 | | - |
97 | | -## Caching |
98 | | -- A `NullCache` object is now used to represent a disabled cache, to use it use `create_cache(0, 0, 0)` in a client kwarg as before |
99 | | - - This is a very niche-use-case and most people won't need to use it |
100 | | -- The `Client` will log a warning if `NullCache` is used for sanity checking |
101 | | -- The serializer now respects `no_export` metadata when using `as_dict` |
102 | | - |
103 | | -## Forums |
104 | | -- Forums now utilise the new API spec instead of the private-beta API |
105 | | -- A new `NewThreadCreate` event is now dispatched for brand new threads |
106 | | -- Add various helper methods to `Forum` objects |
107 | | -- `create_post` now handles `str`, `int` `Tag` objects for available tags |
108 | | - |
109 | | -## Emoji |
110 | | -- `PartialEmoji.from_str` can now return None if no emoji is found |
| 1 | +!!! Placeholder for 2.x migration guide |
0 commit comments