diff --git a/redbot/core/utils/__init__.py b/redbot/core/utils/__init__.py index 16edae454..dc3687f6d 100644 --- a/redbot/core/utils/__init__.py +++ b/redbot/core/utils/__init__.py @@ -540,6 +540,27 @@ def get_end_user_data_statement(file: Union[Path, str]) -> Optional[str]: This function attempts to get the ``end_user_data_statement`` key from cog's ``info.json``. This will log the reason if ``None`` is returned. + Example + ------- + + You can use this function in cog package's top-level ``__init__.py`` + to conveniently reuse end user data statement from ``info.json`` file + placed in the same directory: + + .. code-block:: python + + from redbot.core.utils import get_end_user_data_statement + + __red_end_user_data_statement__ = get_end_user_data_statement(__file__) + + + async def setup(bot): + ... + + To help detect issues with the ``info.json`` file while still allowing the cog to load, + this function logs an error if ``info.json`` file doesn't exist, can't be parsed, + or doesn't have an ``end_user_data_statement`` key. + Parameters ---------- file: Union[pathlib.Path, str] @@ -550,14 +571,6 @@ def get_end_user_data_statement(file: Union[Path, str]) -> Optional[str]: Optional[str] The end user data statement found in the info.json or ``None`` if there was an issue finding one. - - Examples - -------- - >>> # In cog's `__init__.py` - >>> from redbot.core.utils import get_end_user_data_statement - >>> __red_end_user_data_statement__ = get_end_user_data_statement(__file__) - >>> async def setup(bot): - ... ... """ try: file = Path(file).parent.absolute() @@ -586,6 +599,27 @@ def get_end_user_data_statement_or_raise(file: Union[Path, str]) -> str: """ This function attempts to get the ``end_user_data_statement`` key from cog's ``info.json``. + Example + ------- + + You can use this function in cog package's top-level ``__init__.py`` + to conveniently reuse end user data statement from ``info.json`` file + placed in the same directory: + + .. code-block:: python + + from redbot.core.utils import get_end_user_data_statement_or_raise + + __red_end_user_data_statement__ = get_end_user_data_statement_or_raise(__file__) + + + async def setup(bot): + ... + + In order to ensure that you won't end up with no end user data statement, + this function raises if ``info.json`` file doesn't exist, can't be parsed, + or doesn't have an ``end_user_data_statement`` key. + Parameters ---------- file: Union[pathlib.Path, str]