Document dotenv requirement and add optional handling (#51)

README.md

@@ -23,6 +23,13 @@ pip install -e .
 
 Requires Python 3.10 or newer.
 
+To run the example scripts, you'll need the `python-dotenv` package to load
+environment variables. Install the development extras with:
+
+```bash
+pip install "disagreement[dev]"
+```
+
 ## Basic Usage
 
 ```python

examples/basic_bot.py

@@ -39,8 +39,13 @@ except ImportError:
     )
     sys.exit(1)
 
+try:
     from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - example helper
+    load_dotenv = None
+    print("python-dotenv is not installed. Environment variables will not be loaded")
 
+if load_dotenv:
     load_dotenv()
 
 # Optional: Configure logging for more insight, especially for gateway events

examples/component_bot.py

@@ -37,8 +37,14 @@ from disagreement.interactions import (
     InteractionResponsePayload,
     InteractionCallbackData,
 )
-from dotenv import load_dotenv
 
+try:
+    from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - example helper
+    load_dotenv = None
+    print("python-dotenv is not installed. Environment variables will not be loaded")
+
+if load_dotenv:
     load_dotenv()
 
 # Get the bot token and application ID from the environment variables

examples/context_menus.py

@@ -15,8 +15,13 @@ from disagreement.ext.app_commands import (
 )
 from disagreement.models import User, Message
 
+try:
     from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - example helper
+    load_dotenv = None
+    print("python-dotenv is not installed. Environment variables will not be loaded")
 
+if load_dotenv:
     load_dotenv()
 
 BOT_TOKEN = os.environ.get("DISCORD_BOT_TOKEN", "")

examples/extension_management.py

@@ -4,7 +4,11 @@ import asyncio
 import os
 import sys
 
+try:
     from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - example helper
+    load_dotenv = None
+    print("python-dotenv is not installed. Environment variables will not be loaded")
 
 # Allow running from the examples folder without installing
 if os.path.join(os.getcwd(), "examples") == os.path.dirname(os.path.abspath(__file__)):
@@ -12,6 +16,7 @@ if os.path.join(os.getcwd(), "examples") == os.path.dirname(os.path.abspath(__fi
 
 from disagreement import Client
 
+if load_dotenv:
     load_dotenv()
 
 TOKEN = os.environ.get("DISCORD_BOT_TOKEN")

examples/hybrid_bot.py

@@ -36,8 +36,13 @@ from disagreement.enums import (
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
+try:
     from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - example helper
+    load_dotenv = None
+    print("python-dotenv is not installed. Environment variables will not be loaded")
 
+if load_dotenv:
     load_dotenv()
 
 

examples/message_history.py

@@ -10,8 +10,14 @@ if os.path.join(os.getcwd(), "examples") == os.path.dirname(os.path.abspath(__fi
 
 from disagreement.client import Client
 from disagreement.models import TextChannel
-from dotenv import load_dotenv
 
+try:
+    from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - example helper
+    load_dotenv = None
+    print("python-dotenv is not installed. Environment variables will not be loaded")
+
+if load_dotenv:
     load_dotenv()
 
 BOT_TOKEN = os.environ.get("DISCORD_BOT_TOKEN", "")

examples/modal_command.py

@@ -2,13 +2,19 @@
 
 import os
 import asyncio
+
+try:
     from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - example helper
+    load_dotenv = None
+    print("python-dotenv is not installed. Environment variables will not be loaded")
 
 from disagreement import Client, ui
 from disagreement.enums import GatewayIntent, TextInputStyle
 from disagreement.ext.app_commands.decorators import slash_command
 from disagreement.ext.app_commands.context import AppCommandContext
 
+if load_dotenv:
     load_dotenv()
 
 token = os.getenv("DISCORD_BOT_TOKEN", "")

examples/modal_send.py

@@ -3,7 +3,11 @@
 import os
 import sys
 
+try:
     from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - example helper
+    load_dotenv = None
+    print("python-dotenv is not installed. Environment variables will not be loaded")
 
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 
@@ -11,6 +15,7 @@ from disagreement import Client, GatewayIntent, ui  # type: ignore
 from disagreement.ext.app_commands.decorators import slash_command
 from disagreement.ext.app_commands.context import AppCommandContext
 
+if load_dotenv:
     load_dotenv()
 TOKEN = os.getenv("DISCORD_BOT_TOKEN", "")
 APP_ID = os.getenv("DISCORD_APPLICATION_ID", "")

examples/sharded_bot.py

@@ -9,8 +9,14 @@ if os.path.join(os.getcwd(), "examples") == os.path.dirname(os.path.abspath(__fi
     sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 
 import disagreement
-from dotenv import load_dotenv
 
+try:
+    from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - example helper
+    load_dotenv = None
+    print("python-dotenv is not installed. Environment variables will not be loaded")
+
+if load_dotenv:
     load_dotenv()
 
 TOKEN = os.environ.get("DISCORD_BOT_TOKEN")

examples/voice_bot.py

@@ -10,10 +10,15 @@ if os.path.join(os.getcwd(), "examples") == os.path.dirname(os.path.abspath(__fi
 
 from typing import cast
 
+try:
     from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - example helper
+    load_dotenv = None
+    print("python-dotenv is not installed. Environment variables will not be loaded")
 
 import disagreement
 
+if load_dotenv:
     load_dotenv()
 
 _TOKEN = os.getenv("DISCORD_BOT_TOKEN")