diff --git a/docs/wavelink.rst b/docs/wavelink.rst index a150d7cd..633fe471 100644 --- a/docs/wavelink.rst +++ b/docs/wavelink.rst @@ -387,6 +387,11 @@ Filters .. autoclass:: LowPass :members: +.. attributetable:: PluginFilters + +.. autoclass:: PluginFilters + :members: + Utils ----- diff --git a/pyproject.toml b/pyproject.toml index 37aab24d..4b207406 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "wavelink" -version = "3.3.0" +version = "3.4.0" authors = [ { name="PythonistaGuild, EvieePy", email="evieepy@gmail.com" }, ] diff --git a/wavelink/__init__.py b/wavelink/__init__.py index 7cabbbf6..256f08b5 100644 --- a/wavelink/__init__.py +++ b/wavelink/__init__.py @@ -26,7 +26,7 @@ __author__ = "PythonistaGuild, EvieePy" __license__ = "MIT" __copyright__ = "Copyright 2019-Present (c) PythonistaGuild, EvieePy" -__version__ = "3.3.0" +__version__ = "3.4.0" from .enums import * diff --git a/wavelink/filters.py b/wavelink/filters.py index ffa20b1b..f5aef604 100644 --- a/wavelink/filters.py +++ b/wavelink/filters.py @@ -24,7 +24,7 @@ from __future__ import annotations -from typing import TYPE_CHECKING, TypedDict +from typing import TYPE_CHECKING, Any, TypedDict if TYPE_CHECKING: @@ -56,6 +56,7 @@ "Distortion", "ChannelMix", "LowPass", + "PluginFilters", ) @@ -70,6 +71,7 @@ class FiltersOptions(TypedDict, total=False): distortion: Distortion channel_mix: ChannelMix low_pass: LowPass + plugin_filters: PluginFilters reset: bool @@ -583,6 +585,68 @@ def __repr__(self) -> str: return f"" +class PluginFilters: + """The PluginFilters class. + + This class handles setting filters on plugins that support setting filter values. + See the documentation of the Lavalink Plugin for more information on the values that can be set. + + This class takes in a ``dict[str, Any]`` usually in the form of: + + .. code:: python3 + + {"pluginName": {"filterKey": "filterValue"}, ...} + + + .. warning:: + + Do NOT include the ``"pluginFilters"`` top level key when setting your values for this class. + """ + + def __init__(self, payload: dict[str, Any]) -> None: + self._payload = payload + + def set(self, **options: dict[str, Any]) -> Self: + """Set the properties of this filter. + + This method accepts keyword argument pairs OR you can alternatively unpack a dictionary. + See the documentation of the Lavalink Plugin for more information on the values that can be set. + + Examples + -------- + + .. code:: python3 + + plugin_filters: PluginFilters = PluginFilters() + plugin_filters.set(pluginName={"filterKey": "filterValue", ...}) + + # OR... + + plugin_filters.set(**{"pluginName": {"filterKey": "filterValue", ...}}) + """ + self._payload.update(options) + return self + + def reset(self) -> Self: + """Reset this filter to its defaults.""" + self._payload: dict[str, Any] = {} + return self + + @property + def payload(self) -> dict[str, Any]: + """The raw payload associated with this filter. + + This property returns a copy. + """ + return self._payload.copy() + + def __str__(self) -> str: + return "PluginFilters" + + def __repr__(self) -> str: + return f" None: self._distortion: Distortion = Distortion({}) self._channel_mix: ChannelMix = ChannelMix({}) self._low_pass: LowPass = LowPass({}) + self._plugin_filters: PluginFilters = PluginFilters({}) if data: self._create_from(data) @@ -674,6 +739,7 @@ def _create_from(self, data: FilterPayload) -> None: self._distortion = Distortion(data.get("distortion", {})) self._channel_mix = ChannelMix(data.get("channelMix", {})) self._low_pass = LowPass(data.get("lowPass", {})) + self._plugin_filters = PluginFilters(data.get("pluginFilters", {})) def _set_with_reset(self, filters: FiltersOptions) -> None: self._volume = filters.get("volume") @@ -686,6 +752,7 @@ def _set_with_reset(self, filters: FiltersOptions) -> None: self._distortion = filters.get("distortion", Distortion({})) self._channel_mix = filters.get("channel_mix", ChannelMix({})) self._low_pass = filters.get("low_pass", LowPass({})) + self._plugin_filters = filters.get("plugin_filters", PluginFilters({})) def set_filters(self, **filters: Unpack[FiltersOptions]) -> None: """Set multiple filters at once to a standalone Filter object. @@ -713,6 +780,8 @@ def set_filters(self, **filters: Unpack[FiltersOptions]) -> None: The ChannelMix filter to apply to the player. low_pass: :class:`wavelink.LowPass` The LowPass filter to apply to the player. + plugin_filters: :class:`wavelink.PluginFilters` + The extra Plugin Filters to apply to the player. See :class:`~wavelink.PluginFilters` for more details. reset: bool Whether to reset all filters that were not specified. """ @@ -732,6 +801,7 @@ def set_filters(self, **filters: Unpack[FiltersOptions]) -> None: self._distortion = filters.get("distortion", self._distortion) self._channel_mix = filters.get("channel_mix", self._channel_mix) self._low_pass = filters.get("low_pass", self._low_pass) + self._plugin_filters = filters.get("plugin_filters", self._plugin_filters) def _reset(self) -> None: self._volume = None @@ -744,6 +814,7 @@ def _reset(self) -> None: self._distortion = Distortion({}) self._channel_mix = ChannelMix({}) self._low_pass = LowPass({}) + self._plugin_filters = PluginFilters({}) def reset(self) -> None: """Method which resets this object to an original state. @@ -778,6 +849,8 @@ def from_filters(cls, **filters: Unpack[FiltersOptions]) -> Self: The ChannelMix filter to apply to the player. low_pass: :class:`wavelink.LowPass` The LowPass filter to apply to the player. + plugin_filters: :class:`wavelink.PluginFilters` + The extra Plugin Filters to apply to the player. See :class:`~wavelink.PluginFilters` for more details. reset: bool Whether to reset all filters that were not specified. """ @@ -844,6 +917,11 @@ def low_pass(self) -> LowPass: """Property which returns the :class:`~wavelink.LowPass` filter associated with this Filters payload.""" return self._low_pass + @property + def plugin_filters(self) -> PluginFilters: + """Property which returns the :class:`~wavelink.PluginFilters` filters associated with this Filters payload.""" + return self._plugin_filters + def __call__(self) -> FilterPayload: payload: FilterPayload = { "volume": self._volume, @@ -856,6 +934,7 @@ def __call__(self) -> FilterPayload: "distortion": self._distortion._payload, "channelMix": self._channel_mix._payload, "lowPass": self._low_pass._payload, + "pluginFilters": self._plugin_filters._payload, } for key, value in payload.copy().items(): @@ -869,5 +948,5 @@ def __repr__(self) -> str: f"" + f" low_pass={self._low_pass!r}, plugin_filters={self._plugin_filters!r}>" )