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,9 +39,14 @@ except ImportError:
     )
     sys.exit(1)
 
-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")
 
-load_dotenv()
+if load_dotenv:
+    load_dotenv()
 
 # Optional: Configure logging for more insight, especially for gateway events
 # logging.basicConfig(level=logging.DEBUG) # For very verbose output

examples/component_bot.py

@@ -37,9 +37,15 @@ from disagreement.interactions import (
     InteractionResponsePayload,
     InteractionCallbackData,
 )
-from dotenv import load_dotenv
 
-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
 token = os.getenv("DISCORD_BOT_TOKEN")

examples/context_menus.py

@@ -15,9 +15,14 @@ from disagreement.ext.app_commands import (
 )
 from disagreement.models import User, Message
 
-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")
 
-load_dotenv()
+if load_dotenv:
+    load_dotenv()
 
 BOT_TOKEN = os.environ.get("DISCORD_BOT_TOKEN", "")
 APP_ID = os.environ.get("DISCORD_APPLICATION_ID", "")

examples/extension_management.py

@@ -4,7 +4,11 @@ import asyncio
 import os
 import sys
 
-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")
 
 # Allow running from the examples folder without installing
 if os.path.join(os.getcwd(), "examples") == os.path.dirname(os.path.abspath(__file__)):
@@ -12,7 +16,8 @@ if os.path.join(os.getcwd(), "examples") == os.path.dirname(os.path.abspath(__fi
 
 from disagreement import Client
 
-load_dotenv()
+if load_dotenv:
+    load_dotenv()
 
 TOKEN = os.environ.get("DISCORD_BOT_TOKEN")
 

examples/hybrid_bot.py

@@ -36,9 +36,14 @@ from disagreement.enums import (
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
-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")
 
-load_dotenv()
+if load_dotenv:
+    load_dotenv()
 
 
 # --- Define a Test Cog ---

examples/message_history.py

@@ -10,9 +10,15 @@ 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
 
-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", "")
 CHANNEL_ID = os.environ.get("DISCORD_CHANNEL_ID", "")

examples/modal_command.py

@@ -2,14 +2,20 @@
 
 import os
 import asyncio
-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")
 
 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
 
-load_dotenv()
+if load_dotenv:
+    load_dotenv()
 
 token = os.getenv("DISCORD_BOT_TOKEN", "")
 application_id = os.getenv("DISCORD_APPLICATION_ID", "")

examples/modal_send.py

@@ -3,7 +3,11 @@
 import os
 import sys
 
-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")
 
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 
@@ -11,7 +15,8 @@ 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
 
-load_dotenv()
+if load_dotenv:
+    load_dotenv()
 TOKEN = os.getenv("DISCORD_BOT_TOKEN", "")
 APP_ID = os.getenv("DISCORD_APPLICATION_ID", "")
 

examples/sharded_bot.py

@@ -9,9 +9,15 @@ 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
 
-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")
 if not TOKEN:

examples/voice_bot.py

@@ -10,11 +10,16 @@ if os.path.join(os.getcwd(), "examples") == os.path.dirname(os.path.abspath(__fi
 
 from typing import cast
 
-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")
 
 import disagreement
 
-load_dotenv()
+if load_dotenv:
+    load_dotenv()
 
 _TOKEN = os.getenv("DISCORD_BOT_TOKEN")
 _GUILD_ID = os.getenv("DISCORD_GUILD_ID")