مدیریت تنظیمات پروژه در پایتون با ConfigParser (config.ini) و python-dotenv (.env)

۱. چرا مدیریت اصولی تنظیمات در پایتون حیاتی است؟

مدیریت تنظیمات در پایتون به معنای جداسازی کامل کدهای برنامه از متغیرهای پیکربندی (مانند آدرس دیتابیس، کلیدهای دسترسی و پورت‌ها) است. این کار امنیت پروژه را تضمین کرده و فرآیند انتقال برنامه بین سیستم‌های توسعه، تست و سرور اصلی را بدون نیاز به تغییر در سورس‌کد ممکن می‌سازد.

وقتی پروژه شما بزرگ‌تر می‌شود، تغییر مداوم آدرس‌ها یا کلیدهای امنیتی درون کدهای اصلی عملاً غیرممکن و خطرناک است. اگر کدهای خود را در گیت‌هاب قرار دهید، افشای یک کلید ساده می‌تواند کل پروژه شما را به خطر بیندازد. از این رو، استانداردهای توسعه نرم‌افزار (مانند اصول ۱۲ فاکتوری) به شدت تاکید دارند که تنظیمات برنامه باید کاملاً از کد جدا باشند. برای پیاده‌سازی حرفه‌ای این مفاهیم، استفاده از ابزارهای آماده در تکه‌کدهای پایتون می‌تواند سرعت کار شما را چند برابر کند.

۲. مدیریت تنظیمات ساختاریافته با config.ini

فایل‌های با پسوند .ini ساختاری بخش‌بندی شده (Section-based) دارند. این روش برای تنظیمات غیرحساس که ساختار درختی و تودرتو دارند (مثل تنظیمات ظاهری، ابعاد تصویر یا لاگینگ) فوق‌العاده است. پایتون به صورت پیش‌فرض از کتابخانه داخلی configparser برای خواندن این فایل‌ها استفاده می‌کند.

ساختار یک فایل config.ini استاندارد:

[settings]
debug = true
port = 8080

[database]
host = localhost
db_name = main_db

نحوه خواندن فایل ini در پایتون (همراه با ترفند تبدیل نوع داده):

یک اشتباه رایج این است که فراموش می‌کنیم تمام مقادیر خوانده شده از فایل‌های ini به صورت متنی (String) هستند. برای حل این مشکل، باید از متدهای اختصاصی تبدیل نوع استفاده کنیم:

import configparser

config = configparser.ConfigParser()
config.read('config.ini')

# روش اشتباه (خروجی متنی است):
# is_debug = config['settings']['debug'] # "true" (رشته متنی، نه بولین)

# روش صحیح با تبدیل نوع خودکار:
is_debug = config.getboolean('settings', 'debug')
port_number = config.getint('settings', 'port')
db_host = config.get('database', 'host')

print(f"Debug: {is_debug} ({type(is_debug)})")
print(f"Port: {port_number} ({type(port_number)})")

۳. مدیریت اطلاعات حساس با فایل .env

اطلاعات حساس (Secrets) مانند توکن‌های API، پسورد دیتابیس و کلیدهای خصوصی هرگز نباید در کدهای پروژه یا فایل‌های با ساختار عمومی قرار گیرند. بهترین روش، ذخیره آن‌ها در فایل .env و بارگذاری آن‌ها به عنوان متغیرهای محیطی سیستم (Environment Variables) است.

مراحل راه‌اندازی و استفاده از python-dotenv:

1. ابتدا کتابخانه مورد نیاز را با دستور pip install python-dotenv نصب کنید.
2. یک فایل به نام دقیق .env در ریشه اصلی پروژه خود بسازید.
3. اطلاعات حساس خود را به صورت کلید و مقدار (بدون فاصله دور مساوی) بنویسید.

محتوای فایل .env:

DATABASE_PASSWORD=SuperSecretPassword123
API_KEY=ur8934yn98y23rhnf9823hrn
export DEBUG=True

کد پایتون برای بارگذاری متغیرهای محیطی:

import os
from dotenv import load_dotenv

# بارگذاری متغیرها از فایل .env در سیستم عامل به صورت موقت
load_dotenv()

# دسترسی به متغیرها با استفاده از کتابخانه داخلی os
db_password = os.getenv("DATABASE_PASSWORD")
api_key = os.getenv("API_KEY")

# برای امنیت بیشتر، همیشه یک مقدار پیش‌فرض جایگزین مشخص کنید
debug_mode = os.getenv("DEBUG", "False")

print(f"Password Loaded: {bool(db_password)}")  # برای امنیت مقدار واقعی را پرینت نکنید

۴. جدول مقایسه جامع: config.ini در برابر .env

۵. سناریوی واقعی: ترکیب هر دو روش در یک پروژه

بهترین الگوی معماری نرم‌افزار، استفاده همزمان از این دو روش است. شما تنظیمات ظاهری و رفتاری پروژه را در config.ini قرار می‌دهید، اما بخش‌های حساس مانند رمز عبور را به صورت پویا با استفاده از .env فراخوانی می‌کنید. این ترکیب کارآمدترین روش برای پروژه‌های بزرگ و تیمی است.

یک مثال عملی از تلفیق دو ساختار:

فرض کنید می‌خواهیم به یک پایگاه داده متصل شویم. مشخصات کلی اتصال در فایل ini قرار دارد اما رمز عبور آن از طریق متغیر محیطی بارگذاری می‌شود:

import os
import configparser
from dotenv import load_dotenv

# ۱. بارگذاری متغیرهای محیطی حساس
load_dotenv()

# ۲. بارگذاری پیکربندی‌های ساختاری
config = configparser.ConfigParser()
config.read('config.ini')

# ۳. ترکیب داده‌ها برای ساختن کانکشن استرینگ نهایی
db_host = config.get('database', 'host')
db_user = config.get('database', 'user')

# دریافت رمز عبور از متغیرهای محیطی امن
db_password = os.getenv("DB_PASSWORD") 

connection_uri = f"postgresql://{db_user}:{db_password}@{db_host}/my_database"
print("Connection URI successfully constructed!")

۶. عیب‌یابی سریع و رفع خطاهای رایج

هنگام کار با فایل‌های تنظیمات در پایتون، با خطاهای مختلفی مواجه می‌شوید. در این بخش راه‌حل‌های فوری برای سه مشکل پر تکرار را بررسی می‌کنیم:

• خطای مقدار None برای متغیرهای .env: اگر متغیرها بارگذاری نمی‌شوند و خروجی None دریافت می‌کنید، مطمئن شوید که تابع load_dotenv() را دقیقاً قبل از فراخوانی os.getenv() فراخوانی کرده‌اید. همچنین مسیر اجرای ترمینال شما باید در ریشه اصلی پروژه (همان‌جایی که فایل .env قرار دارد) باشد.
• خطای NoSectionError در ConfigParser: این خطا زمانی اتفاق می‌افتد که بخش نوشته شده در متد (مثلاً [database]) دقیقاً با نام بخش در فایل config.ini همخوانی نداشته باشد (به کوچک و بزرگ بودن حروف حساس است). همچنین بررسی کنید مسیر فایل خوانده شده درست باشد.
• عدم اعمال تغییرات فایل .env در زمان اجرا: اگر متغیری را در سیستم‌عامل از قبل به صورت گلوبال تعریف کرده باشید، به صورت پیش‌فرض کتابخانه dotenv آن را بازنویسی نمی‌کند. برای اجبار به بازنویسی متغیرهای سیستم‌عامل، از آرگومان override استفاده کنید: load_dotenv(override=True).

۷. پرسش‌های متداول