ClientFeatures, deprecate experimental_event_style

Author: shayypy

.gitignore

@@ -8,4 +8,5 @@ testing/
 .vscode/
 *.pyc
 *.log
-venv/
+venv/
+.DS_Store

docs/api.rst

@@ -2688,6 +2688,12 @@ CategoryUserOverride
 .. autoclass:: CategoryUserOverride()
     :members:
 
+ClientFeatures
+~~~~~~~~~~~~~~~
+
+.. autoclass:: ClientFeatures()
+    :members:
+
 Embed
 ~~~~~~
 

guilded/client.py

@@ -82,6 +82,7 @@
 
 __all__ = (
     'Client',
+    'ClientFeatures',
 )
 
 
@@ -99,6 +100,30 @@ def __getattr__(self, attr: str) -> None:
 _loop: Any = _LoopSentinel()
 
 
+class ClientFeatures:
+    """Opt-in or out of Guilded or guilded.py features.
+
+    All parameters are optional.
+
+    Parameters
+    -----------
+    experimental_event_style: :class:`bool`
+        Enables a more simplified event handling interface.
+        Read more about this `here <https://www.guilded.gg/guilded-api/blog/updates/Event-style-experiment>`_.
+    official_markdown: :class:`bool`
+        Enables new (2024) markdown support for requests made by the client
+        as well as events received.
+    """
+    def __init__(
+        self,
+        *,
+        experimental_event_style: bool = False,
+        official_markdown: bool = False,
+    ) -> None:
+        self.experimental_event_style = experimental_event_style
+        self.official_markdown = official_markdown
+
+
 class Client:
     """The basic client class for interfacing with Guilded.
 
@@ -109,6 +134,8 @@ class Client:
     max_messages: Optional[:class:`int`]
         The maximum number of messages to store in the internal message cache.
         This defaults to ``1000``. Passing in ``None`` disables the message cache.
+    features: Optional[:class:`.ClientFeatures`]
+        Client features to opt in or out of.
 
     Attributes
     -----------
@@ -123,20 +150,29 @@ class Client:
     max_messages: Optional[:class:`int`]
         The maximum number of messages to store in the internal message cache.
         This defaults to ``1000``. Passing in ``None`` disables the message cache.
+    features: :class:`.ClientFeatures`
+        The features that are enabled or disabled for the client.
     """
 
     def __init__(
         self,
         *,
         internal_server_id: Optional[str] = None,
         max_messages: Optional[int] = MISSING,
+        features: Optional[ClientFeatures] = None,
         **options,
     ):
         # internal
         self.loop: asyncio.AbstractEventLoop = _loop
         self.max_messages: int = 1000 if max_messages is MISSING else max_messages
         self._listeners = {}
 
+        self.features = features or ClientFeatures()
+        # This option is deprecated
+        if options.get('experimental_event_style') is not None:
+            log.info("The `experimental_event_style` client parameter is deprecated, please switch to using ClientFeatures instead.")
+            self.features.experimental_event_style = options.pop('experimental_event_style', False)
+
         # state
         self._closed: bool = False
         self._ready: asyncio.Event = MISSING
@@ -145,7 +181,7 @@ def __init__(
         self.ws: Optional[GuildedWebSocket] = None
         self.http: HTTPClient = HTTPClient(
             max_messages=self.max_messages,
-            experimental_event_style=options.pop('experimental_event_style', False),
+            features=self.features,
         )
 
     async def __aenter__(self) -> Self:

guilded/http.py

@@ -81,6 +81,7 @@
     from .asset import Asset
     from .category import Category
     from .channel import DMChannel, Thread
+    from .client import ClientFeatures
     from .emote import Emote
     from .file import Attachment, File
     from .gateway import GuildedWebSocket
@@ -220,10 +221,10 @@ def __init__(self, method: str, path: str, *, override_base: str = None):
 
 class HTTPClientBase:
     GIL_ID = 'Ann6LewA'
-    def __init__(self, *, max_messages: int = 1000, experimental_event_style: bool = False):
+    def __init__(self, *, max_messages: int = 1000, features: Optional[ClientFeatures] = None):
         self.session: Optional[aiohttp.ClientSession] = None
         self._max_messages = max_messages
-        self._experimental_event_style = experimental_event_style
+        self._experimental_event_style = features.experimental_event_style if features else False
 
         self.ws: Optional[GuildedWebSocket] = None
         self.user: Optional[ClientUser] = None
@@ -468,8 +469,9 @@ def get_stripped_reaction_list(self):
 
 
 class HTTPClient(HTTPClientBase):
-    def __init__(self, *, max_messages=1000, experimental_event_style=False):
-        super().__init__(max_messages=max_messages, experimental_event_style=experimental_event_style)
+    def __init__(self, *, max_messages=1000, features=None):
+        super().__init__(max_messages=max_messages, features=features)
+        self.client_features = features
 
         self.token: Optional[str] = None
 
@@ -488,6 +490,12 @@ async def request(self, route, **kwargs):
         if self.token:
             headers['Authorization'] = f'Bearer {self.token}'
 
+        if self.client_features and self.client_features.official_markdown:
+            # There doesn't really seem to be a standard for boolean values in headers,
+            # and Guilded doesn't specify what the value should be - all values are
+            # treated the same. A lowercase `true` seemed appropriate.
+            headers['x-guilded-bot-api-use-official-markdown'] = "true"
+
         if 'json' in kwargs:
             headers['Content-Type'] = 'application/json'
             kwargs['data'] = json.dumps(kwargs.pop('json'))
@@ -591,6 +599,9 @@ async def ws_connect(self) -> aiohttp.ClientWebSocketResponse:
             # We have connected before, resume and catch up with missed messages
             headers['guilded-last-message-id'] = self.ws._last_message_id
 
+        if self.client_features and self.client_features.official_markdown:
+            headers['x-guilded-bot-api-use-official-markdown'] = "true"
+
         log_headers = headers.copy()
         log_headers['Authorization'] = 'Bearer [removed]'
         log.debug('Connecting to the gateway with %s', log_headers)