کتابخانه dotenv در پایتون — مدیریت امن و سادهٔ پیکربندی

کتابخانه dotenv (معمولاً python-dotenv) یکی از ابزارهای پراستفاده برای خواندن متغیرهای محیطی از فایل‌های .env است. هدف آن جداسازی پیکربندی از کد است تا اطلاعات حساس مانند کلیدها، رمزها و تنظیمات قابل تغییر را به‌صورت امن و قابل نگهداری مدیریت کنیم.

چرا از dotenv استفاده کنیم؟

• جدا کردن پیکربندی از سورس‌کد (12-factor app).
• سهولت در توسعه محلی: تعریف متغیرها در فایل .env بدون نیاز به تنظیم دستی در سیستم.
• قابلیت استفاده در فریم‌ورک‌ها مانند Flask و Django.
• پیشگیری از افشای اطلاعات حساس در مخزن گیت (با استفاده از .gitignore).

نصب و فایل .env

نصب کتابخانه با pip بسیار ساده است:

pip install python-dotenv

فایل .env معمولاً در ریشهٔ پروژه قرار می‌گیرد و ساختارش شبیه زیر است:

# .env
DEBUG=True
SECRET_KEY=mysupersecretkey
DATABASE_URL=postgres://user:pass@localhost:5432/dbname

این فایل باید به فایل .gitignore اضافه شود تا از نشر ناخواسته جلوگیری شود.

استفادهٔ پایه‌ای در اسکریپت پایتون

from dotenv import load_dotenv
import os

load_dotenv()  # فایل .env را در مسیر جاری بارگذاری می‌کند

debug = os.getenv("DEBUG", "False")  # مقدار پیش‌فرض "False"
secret = os.environ.get("SECRET_KEY")

در این مثال، load_dotenv() مقادیر موجود در .env را به متغیرهای محیطی فرآیند اضافه می‌کند. سپس با os.getenv یا os.environ می‌توان به آن‌ها دسترسی داشت. استفاده از os.getenv امکان تعیین مقدار پیش‌فرض را فراهم می‌کند.

توضیح دقیق‌تر عملکرد و گزینه‌ها

• load_dotenv(path=None, override=False): مسیر فایل .env را بارگیری می‌کند؛ اگر override=True باشد، متغیرهای موجود در محیط را بازنویسی می‌کند.
• find_dotenv(): مسیر فایل .env را در دایرکتوری‌های والد پیدا می‌کند.
• dotenv_values(path): مقادیر را به‌صورت دیکشنری بازمی‌گرداند بدون اینکه متغیرهای محیطی را تغییر دهد.
• set_key/unset_key: برای ویرایش فایل .env استفاده می‌شوند.

نمونهٔ استفادهٔ پیشرفته — بارگذاری با اولویت‌ها و تایپ‌کست

from dotenv import load_dotenv
import os

# بارگذاری فایل .env در مسیر مشخص
load_dotenv(".env", override=False)

def get_bool(name, default=False):
    val = os.getenv(name)
    if val is None:
        return default
    return val.lower() in ("1", "true", "yes", "on")

DEBUG = get_bool("DEBUG", False)
PORT = int(os.getenv("PORT", "8000"))

در این کد نشان داده‌ایم چگونه مقدار بولی و عددی را با تبدیل صحیح دریافت کنیم. توجه کنید که load_dotenv با override=False باعث می‌شود متغیرهای تعریف‌شده در محیط سیستم که ممکن است در سرور تولیدی تنظیم شوند، بازنویسی نشوند.

یکپارچه‌سازی با Flask و Django

در Flask می‌توان به‌سادگی .env را بارگذاری کرد:

from flask import Flask
from dotenv import load_dotenv
import os

load_dotenv()
app = Flask(__name__)
app.config['SECRET_KEY'] = os.getenv("SECRET_KEY", "fallback")

در Django معمولاً متغیرها را در settings.py می‌خوانیم:

import os
from dotenv import load_dotenv
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
load_dotenv(BASE_DIR / ".env")

SECRET_KEY = os.getenv("SECRET_KEY")
DEBUG = os.getenv("DEBUG", "False").lower() == "true"

در هر دو مثال، توصیه می‌شود برای محیط تولیدی از متغیرهای محیطی واقعی (مانند systemd, Docker, CI secrets manager) استفاده کنید و .env را فقط برای توسعه نگه دارید.

جدول توابع پراستفاده

نکات امنیتی و بهترین شیوه‌ها

• فایل .env را به مخزن گیت اضافه نکنید؛ از .gitignore استفاده کنید.
• در تولید از secret managerهای سرویس‌دهنده (AWS Secrets Manager, GCP Secret Manager, Vault) استفاده کنید.
• از override=False در load_dotenv استفاده کنید تا متغیرهای محیطی سرور بازنویسی نشوند مگر خواسته باشید.
• برای تست، فایل .env.example داشته باشید که فقط کلیدها را بدون مقادیر حساس نشان دهد.

تست و CI

در محیط CI معمولاً متغیرهای محیطی از رابط CI (مثل GitHub Actions secrets) ست می‌شوند. برای تست محلی می‌توان از فایل .env.test استفاده و به‌صورت موقت بارگذاری کرد:

from dotenv import load_dotenv
load_dotenv(".env.test", override=True)

این روش اجازه می‌دهد تنظیمات تست از تنظیمات توسعه یا تولید جدا بماند و به‌راحتی قابل تکرار باشد.

مثال عملی: خواندن متغیرهای سرویس و fallback

from dotenv import dotenv_values
import os

# فقط می‌خواهیم مقادیر را بدون تغییر محیط بخوانیم
cfg = dotenv_values(".env")  

db_url = os.getenv("DATABASE_URL") or cfg.get("DATABASE_URL") or "sqlite:///local.db"

در این مثال ابتدا سعی می‌کنیم متغیر را از محیط بخوانیم، اگر نبود از محتویات .env استفاده می‌کنیم و در نهایت مقدار پیش‌فرض تعیین می‌شود. این ترتیب برای تطبیق بهتر با محیط‌های مختلف مفید است.

نکات تخصصی و اشکال‌زدایی

• اگر متغیرها خوانده نمی‌شوند، مسیر فایل .env را با find_dotenv یا چاپ Current Working Directory بررسی کنید.
• فرمت مقادیر می‌تواند شامل نقل‌قول باشد. python-dotenv نقل‌قول‌ها را حذف می‌کند.
• برای تغییر فایل .env به‌صورت برنامه‌ای از set_key استفاده کنید، اما مراقب رقابت چندفرایندی (race condition) باشید.

کتابخانه dotenv یک ابزار ساده اما قدرتمند برای مدیریت پیکربندی پروژه‌های پایتون است. با رعایت بهترین شیوه‌های امنیتی و استفادهٔ مناسب در توسعه و محیط‌های تولیدی، می‌توان توسعهٔ امن‌تر و قابل انتقال‌تری داشت.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال