docs: clarify disnake.Embed re-using disnake.File objects when editing messages

[Snipy7374]

Summary

• Closes disnake.Embed methods supporting file param make the embed non-reusable #748

Checklist

• If code changes were made, then they have been tested
  • I have updated the documentation to reflect the changes
  • I have formatted the code properly by running task lint
  • I have type-checked the code by running task pyright
• This PR fixes an issue
• This PR adds something new (e.g. new method or parameters)
• This PR is a breaking change (e.g. methods or parameters removed/renamed)
• This PR is not a code change (e.g. documentation, README, ...)

[shiftinv]

Hmm, something I completely missed - fp.closed isn't necessarily a good indicator of a file not being usable, that only works with disnake.File(<path>), but not with disnake.File(io.BytesIO(<data>)).

Taking this as an example:

a = await ctx.author.display_avatar.read()
e = disnake.Embed(title="embed")
e.set_image(file=disnake.File(io.BytesIO(a), filename="avatar.png"))

m = await ctx.send(embed=e)
await m.edit("hi", embed=e)

The .edit call will send a zero-length file as the embed image (since the BytesIO wasn't closed yet), again resulting in the original issue.
Can't think of a solution off the top of my head right now, the API handles embed attachments in a weird way.

[Snipy7374]

Hmm, something I completely missed - fp.closed isn't necessarily a good indicator of a file not being usable, that only works with disnake.File(<path>), but not with disnake.File(io.BytesIO(<data>)).

Taking this as an example:

a = await ctx.author.display_avatar.read()
e = disnake.Embed(title="embed")
e.set_image(file=disnake.File(io.BytesIO(a), filename="avatar.png"))

m = await ctx.send(embed=e)
await m.edit("hi", embed=e)

The .edit call will send a zero-length file as the embed image (since the BytesIO wasn't closed yet), again resulting in the original issue.
Can't think of a solution off the top of my head right now, the API handles embed attachments in a weird way.

couldn't we introduce a new attribute closed that will be edited when the IO or File Like object will be closed? I could only think about this implementation

[Snipy7374]

Hi, at the moment this implementation works correctly however I would need some advice to make the fix more functional and to solve some problems with pyright :)

[Snipy7374]

thanks to @Enegg who helped me improve the code and delete some really shit that i wrote

[onerandomusername]

I feel like this could be fixed simply: document the error at runtime if the embed has any files attached that are not open, and then have a method which can clean the closed files.

[Snipy7374]

I feel like this could be fixed simply: document the error at runtime if the embed has any files attached that are not open, and then have a method which can clean the closed files.

Right now this works (at least I haven't found any bug) so why we should change it

[onerandomusername]

My biggest concern with this implement as it is is the amount of code and logic that is occuring in a finally of a try/except. If we could somehow minimize that, I would appreciate that.

That could be done by lazily clearing the files from an embed, but I'm also undecided on how this implementation works, it clears the files from an Embed object after they're sent.

However, most embed objects are only used once, so where this currently runs has a runtime impact on all embeds. I think I'd like to see it processed when an embed has a file when we attempt to send it, rather than after the embed is sent.

[shiftinv]

The docs of Embed.set_image and .set_thumbnail should mention that reusing embeds with files won't work in most cases (not sure on the wording).
looks good to me otherwise

[Snipy7374]

The docs of Embed.set_image and .set_thumbnail should mention that reusing embeds with files won't work in most cases (not sure on the wording). looks good to me otherwise

@shiftinv
What do you mean with reusing embeds with files won't work in most cases? Reusing embeds with files works if you don't modify images and if you modify them too

[shiftinv]

What do you mean with reusing embeds with files won't work in most cases? Reusing embeds with files works if you don't modify images and if you modify them too

@Snipy7374 There are a couple cases where it doesn't work, e.g. sending the same embed object in two separate messages; afaict they can only be reused as long as you're editing the same message the embed was sent in originally, right?

[Snipy7374]

What do you mean with reusing embeds with files won't work in most cases? Reusing embeds with files works if you don't modify images and if you modify them too

@Snipy7374 There are a couple cases where it doesn't work, e.g. sending the same embed object in two separate messages; afaict they can only be reused as long as you're editing the same message the embed was sent in originally, right?

@shiftinv This is true, I had not thought about it. However while I was testing what you said I found a bug, using the same embed object, changing files and editing a message you get an I/O error message on closed file.

reproducible code:

e = disnake.Embed()
e.set_image(file=disnake.File("..."))
e.set_thumbnail(file=disnake.File("..."))
await inter.response.send_message(embed=e)
e.set_image(file=disnake.File(...))
e.set_thumbnail(file=disnake.File(...))
await inter.edit_original_message(embed=e)
await inter.send(embed=e)

This is because we have to clear _files after an edit attempt too.

[Snipy7374]

https://canary.discord.com/channels/808030843078836254/913779868985090089/1035407513908154378 at the end we decided to just make a docs change

[shiftinv]

On an unrelated note, seems like GitHub workflows are broken - I very much doubt these changes are related to that issue, just figured I'd mention it. I'll look into it in a bit.

---

edit: fixed in #838

changes made