search

mahtoid / DiscordChatExporterPy

A simple Discord chat exporter for Python Discord bots.
GNU General Public License v3.0
210 stars 75 forks source link
discord discordpy enhanced-dpy export pycord python

readme

[![Version][pypi-version]][pypi-url] [![Language][language-dom]][github-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![GPL License][license-shield]][license-url]

DiscordChatExporterPy

Export Discord chats with your discord.py (or fork) bots!
Join Discord · Report Bug · Request Feature

Installation

To install the library to your virtual environment, for bot usage, run the command:

pip install chat-exporter

To clone the repository locally, run the command:

git clone https://github.com/mahtoid/DiscordChatExporterPy

(back to top)

Usage

There are currently 3 methods (functions) to chat-exporter which you can use to export your chat.
Expand the blocks below to learn the functions, arguments and usages.

Basic Usage `.quick_export()` is the simplest way of using chat-exporter. Using the _quick_export_ function will gather the history of the channel you give, build the transcript then post the file and embed directly to the channel - returning a message object gathered from the message it posted. This is mostly seen as a demo function, as opposed to a command you should actually use. **Required Argument(s):**
`channel`: `discord.TextChannel` object, whether `ctx.channel` or any channel you gather. **Optional Argument(s):**
`bot`: `commands.Bot` object to gather members who are no longer in your guild. **Return Argument:**
`discord.Message`: The message _quick_export_ will send, containing the embed and exported chat file. **Example:** ```python import discord import chat_exporter from discord.ext import commands intents = discord.Intents.default() intents.members = True intents.message_content = True bot = commands.Bot(command_prefix="!", intents=intents) ... @bot.command() async def save(ctx: commands.Context): await chat_exporter.quick_export(ctx.channel) ... ```
Customisable Usage `.export()` is the most efficient and flexible method to export a chat using chat-exporter. Using the _export_ function will generate a transcript using the channel you pass in, along with using any of the custom kwargs passed in to set limits, timezone, 24h formats and more (listed below). This would be the main function to use within chat-exporter. **Required Argument(s):**
`channel`: `discord.TextChannel` object, whether `ctx.channel` or any channel you gather. **Optional Argument(s):**
`limit`: Integer value to set the limit (amount of messages) the chat exporter gathers when grabbing the history (default=unlimited).
`tz_info`: String value of a [TZ Database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) to set a custom timezone for the exported messages (default=UTC).
`guild`: `discord.Guild` object which can be passed in to solve bugs for certain forks.
`military_time`: Boolean value to set a 24h format for times within your exported chat (default=False | 12h format).
`fancy_times`: Boolean value which toggles the 'fancy times' (Today|Yesterday|Day).
`before`: `datetime.datetime` object which allows to gather messages from before a certain date.
`after`: `datetime.datetime` object which allows to gather messages from after a certain date.
`bot`: `commands.Bot` object to gather members who are no longer in your guild.
`attachment_handler`: `chat_exporter.AttachmentHandler` object to export assets to in order to make them available after the `channel` got deleted.
**Return Argument:**
`transcript`: The HTML build-up for you to construct the HTML File with Discord. **Example:** ```python import io ... @bot.command() async def save(ctx: commands.Context, limit: int = 100, tz_info: str = "UTC", military_time: bool = True): transcript = await chat_exporter.export( ctx.channel, limit=limit, tz_info=tz_info, military_time=military_time, bot=bot, ) if transcript is None: return transcript_file = discord.File( io.BytesIO(transcript.encode()), filename=f"transcript-{ctx.channel.name}.html", ) await ctx.send(file=transcript_file) ```
Raw Usage `.raw_export()` is for the crazy people who like to do their own thing when using chat-exporter. Using the _raw_export_ function will generate a transcript using the list of messages you pass in, along with using any of the custom kwargs passed in to set limits, timezone, 24h formats and more (listed below). This would be for people who want to filter what content to export. **Required Argument(s):**
`channel`: `discord.TextChannel` object, whether `ctx.channel` or any channel you gather (this is just for padding the header).
`messages`: A list of Message objects which you wish to export to an HTML file. **Optional Argument(s):**
`tz_info`: String value of a [TZ Database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) to set a custom timezone for the exported messages (default=UTC)
`military_time`: Boolean value to set a 24h format for times within your exported chat (default=False | 12h format)
`fancy_times`: Boolean value which toggles the 'fancy times' (Today|Yesterday|Day)
`bot`: `commands.Bot` object to gather members who are no longer in your guild. `attachment_handler`: `chat_exporter.AttachmentHandler` object to export assets to in order to make them available after the `channel` got deleted.
**Return Argument:**
`transcript`: The HTML build-up for you to construct the HTML File with Discord. **Example:** ```python import io ... @bot.command() async def purge(ctx: commands.Context, tz_info: str, military_time: bool): deleted_messages = await ctx.channel.purge() transcript = await chat_exporter.raw_export( ctx.channel, messages=deleted_messages, tz_info=tz_info, military_time=military_time, bot=bot, ) if transcript is None: return transcript_file = discord.File( io.BytesIO(transcript.encode()), filename=f"transcript-{ctx.channel.name}.html", ) await ctx.send(file=transcript_file) ```

(back to top)

Attachment Handler

Due to Discords newly introduced restrictions on to their CDN, we have introduced an Attachment Handler. This handler will assist you with circumventing the 'broken' and 'dead-assets' which arise when former attachments hosted by Discord reach their expiration date.

The AttachmentHandler serves as a template for you to implement your own asset handler. Below are two basic examples on how to use the AttachmentHandler. One using the example of storing files on a local webserver, with the other being an example of storing them on Discord (the latter merely just being an example, this will still obviously run in to the expiration issue).

If you do not specify an attachment handler, chat-exporter will continue to use the (proxy) URLs for the assets.

Concept The concept of implementing such an AttachmentHandler is very easy. In the following a short general procedure is described to write your own AttachmentHandler fitting your storage solution. Here we will assume, that we store the attachments in a cloud storage. 1. Subclassing Start by subclassing `chat_exporter.AttachmentHandler` and implement the `__init__` method if needed. This should look something like this: ```python from chat_exporter import AttachmentHandler from cloud_wrapper import CloudClient class MyAttachmentHandler(AttachmentHandler): def __init__(self, *args, **kwargs): # Your initialization code here # in your case we just create the cloud client self.cloud_client = CloudClient() ``` 2. Overwrite process_asset The `process_asset` method is the method that is called for each asset in the chat. Here we have to implement the upload logic and the generation of the asset url from the uploaded asset. ```python import io import aiohttp from chat_exporter import AttachmentHandler from cloud_wrapper import CloudClient from discord import Attachment class MyAttachmentHandler(AttachmentHandler): def __init__(self, *args, **kwargs): # Your initialization code here # in your case we just create the cloud client self.cloud_client = CloudClient() async def process_asset(self, attachment: Attachment): # Your upload logic here, in our example we just upload the asset to the cloud # first we need to authorize the client await self.cloud_client.authorize() # then we fetch the content of the attachment async with aiohttp.ClientSession() as session: async with session.get(attachment.url) as res: if res.status != 200: res.raise_for_status() data = io.BytesIO(await res.read()) data.seek(0) # and upload it to the cloud, back we get some sort of identifier for the uploaded file asset_id = await self.cloud_client.upload(data) # now we can generate the asset url from the identifier asset_url = await self.cloud_client.get_share_url(asset_id, shared_with="everyone") # and set the proxy url attribute of the attachment to the generated url attachment.proxy_url = asset_url return attachment ``` Note 1. The `process_asset` method should return the attachment object with the proxy_url attribute set to the generated url. 2. The `process_asset` method should be an async method, as it is likely that you have to do some async operations like fetching the content of the attachment or uploading it to the cloud. 3. You are free to add other methods in your class, and call them from `process_asset` if you need to do some operations before or after the upload of the asset. But the `process_asset` method is the only method that is called from chat-exporter.

Examples:

    AttachmentToLocalFileHostHandler Assuming you have a file server running, which serves the content of the folder `/usr/share/assets/` under `https://example.com/assets/`, you can easily use the `AttachmentToLocalFileHostHandler` like this: ```python import io import discord from discord.ext import commands import chat_exporter from chat_exporter import AttachmentToLocalFileHostHandler ... # Establish the file handler file_handler = AttachmentToLocalFileHostHandler( base_path="/usr/share/assets", url_base="https://example.com/assets/", ) @bot.command() async def save(ctx: commands.Context): transcript = await chat_exporter.export( ctx.channel, attachment_handler=file_handler, ) if transcript is None: return transcript_file = discord.File( io.BytesIO(transcript.encode()), filename=f"transcript-{ctx.channel.name}.html", ) await ctx.send(file=transcript_file) ```
    AttachmentToDiscordChannel Assuming you want to store your attachments in a discord channel, you can use the `AttachmentToDiscordChannel`. Please note that discord recent changes regarding content links will result in the attachments links being broken after 24 hours. While this is therefor not a recommended way to store your attachments, it should give you a good idea how to perform asynchronous storing of the attachments. ```python import io import discord from discord.ext import commands import chat_exporter from chat_exporter import AttachmentToDiscordChannel ... # Establish the file handler channel_handler = AttachmentToDiscordChannel( channel=bot.get_channel(CHANNEL_ID), ) @bot.command() async def save(ctx: commands.Context): transcript = await chat_exporter.export( ctx.channel, attachment_handler=channel_handler, ) if transcript is None: return transcript_file = discord.File( io.BytesIO(transcript.encode()), filename=f"transcript-{ctx.channel.name}.html", ) await ctx.send(file=transcript_file) ```

(back to top)

Screenshots

General
    Discord
    Chat-Exporter

(back to top)

Additional Functions

Link Function Downloading exported chats can build up a bunch of unwanted files on your PC which can get annoying, additionally - not everyone wants to download content from Discord. Due to these pain, and many requests - I have built a fancy PHP script which will show the transcript file within a browser.
    quick_link Similar in design to `.quick_export()` this is a bit of a demo function to produce a link and to give you an embed. **Required Argument(s):**
    `channel`: `discord.TextChannel` object, whether `ctx.channel` or any channel you gather.
    `message`: The Discord message containing the transcript file **Return Argument:**
    `discord.Message`: The message _quick_link_ will send, containing the embed. **Example:** ```python import chat_exporter ... @bot.command() async def save(ctx: commands.Context): message = await chat_exporter.quick_export(ctx.channel) await chat_exporter.quick_link(ctx.channel, message) ```
    link A simple function to return the link you will need to view the transcript online. **Required Argument(s):**
    `message`: The Discord message containing the transcript file **Return Argument:**
    `link`: The link to view the transcript file online **Example:** ```python import io import chat_exporter ... @bot.command() async def save(ctx: commands.Context): transcript = await chat_exporter.export(ctx.channel) if transcript is None: return transcript_file = discord.File( io.BytesIO(transcript.encode()), filename=f"transcript-{ctx.channel.name}.html", ) message = await ctx.send(file=transcript_file) link = await chat_exporter.link(message) await ctx.send("Click this link to view the transcript online: " + link) ```
_Please note that the PHP script does NOT store any information.
It simply makes a request to the given URL and echos (prints) the content for you to be able to view it._

Attributions

This project borrows CSS and HTML code from Tyrrrz's C# DiscordChatExporter repository.

(back to top)