کتابخانه python-decouple در پایتون — معرفی و راهنمای کاربردی

python-decouple یک کتابخانه سبک و مفید برای جداسازی تنظیمات برنامه از کُد است. هدف اصلی آن تسهیل خواندن متغیرهای محیطی (environment variables) و فایل‌های .env و افزایش امنیت و قابلیت انتقال‌پذیری برنامه‌ها مطابق با اصول 12-factor apps است.

چرا از python-decouple استفاده کنیم؟

• جدا کردن تنظیمات از کد منجر به امنیت بهتر و مدیریت آسان‌تر می‌شود.
• پیکربندی‌های محلی و محیط‌های مختلف (dev/staging/prod) به سادگی قابل تعویض‌اند.
• رابط ساده برای تبدیل (cast) انواع داده‌ها، مقدار پیش‌فرض و خواندن لیست‌ها فراهم می‌کند.

نصب و فایل .env

نصب با pip:

pip install python-decouple

فایل .env نمونه:

# .env
SECRET_KEY="mysecret"
DEBUG=True
PORT=8000
ALLOWED_HOSTS=localhost,127.0.0.1
DATABASE_URL=postgres://user:pass@localhost:5432/dbname

این فایل به‌صورت معمول در ریشه پروژه قرار می‌گیرد و نباید آن را در سیستم کنترل نسخه (مثل Git) ثبت کنید. بهتر است یک فایل .env.example در مخزن قرار دهید که ساختار متغیرها را نشان دهد اما شامل مقادیر حساس نباشد.

مثال‌های پایه‌ای استفاده

from decouple import config, Csv

SECRET_KEY = config('SECRET_KEY')
DEBUG = config('DEBUG', default=False, cast=bool)
PORT = config('PORT', default=5000, cast=int)
ALLOWED_HOSTS = config('ALLOWED_HOSTS', cast=Csv())

در این مثال:

• config(‘KEY’) مقدار متغیر محیطی یا مقدار داخل .env را خوانده و به‌صورت رشته بازمی‌گرداند.
• با پارامتر default می‌توان مقدار پیش‌فرض تعیین کرد تا در صورت نبود متغیر از آن استفاده شود.
• پارامتر cast برای تبدیل رشته به انواع دیگر (bool، int، float، یا Csv) به کار می‌رود.
• Csv() لیستی از مقادیر جداشده با کاما را بازمی‌گرداند.

نحوه کار با Django

# settings.py در Django
from decouple import config, Csv
import dj_database_url

SECRET_KEY = config('SECRET_KEY')
DEBUG = config('DEBUG', default=False, cast=bool)

DATABASES = {
    'default': dj_database_url.parse(config('DATABASE_URL'))
}

ALLOWED_HOSTS = config('ALLOWED_HOSTS', default='localhost', cast=Csv())

توضیح: این قطعه کد نحوه جایگزینی تنظیمات حساس مانند SECRET_KEY و اطلاعات دیتابیس را نشان می‌دهد. با استفاده از dj-database-url می‌توان رشته URL دیتابیس را به دیکشنری مورد نیاز Django تبدیل کرد. استفاده از cast اطمینان می‌دهد نوع داده‌ها درست باشد.

AutoConfig و RepositoryEnv — کنترل بیشتر بر منبع تنظیمات

from decouple import AutoConfig

# AutoConfig به‌طور خودکار دنبال .env در مسیر پروژه می‌گردد
config = AutoConfig(search_path='.')
API_KEY = config('API_KEY', default=None)

توضیح: AutoConfig یک نمونه Config با Repository مناسب ایجاد می‌کند و برای پروژه‌هایی که ساختار دایرکتوری پیچیده دارند مفید است. می‌توانید search_path را تنظیم کنید تا جای درستی برای فایل .env مشخص کنید.

from decouple import Config, RepositoryEnv

repo = RepositoryEnv('.env.production')
config = Config(repo)
SECRET = config('SECRET')

توضیح: RepositoryEnv به شما امکان می‌دهد به صراحت یک فایل .env دلخواه را به عنوان منبع تنظیمات معرفی کنید؛ مناسب برای حالاتی که چندین فایل env برای محیط‌های مختلف دارید.

قواعد فایل .env

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

• هرگز فایل .env را به مخزن عمومی نپوشانید. از .gitignore استفاده کنید.
• در محیط تولید (production) بهتر است از سرویس‌های مدیریت اسرار (مثلاً AWS Secrets Manager، HashiCorp Vault) استفاده کنید و تنها در محیط توسعه از .env استفاده کنید.
• برای هماهنگی تیمی، یک فایل .env.example حاوی کلیدها اما بدون مقادیر حساس را منتشر کنید.
• محیط‌های کانتینری (Docker) و اورکستریشن (Kubernetes) معمولاً از متغیرهای محیطی یا secret mounts استفاده می‌کنند؛ python-decouple اولویت را به متغیرهای محیطی می‌دهد، بنابراین با Docker Compose یا Helm سازگار است.

مزایا و محدودیت‌ها — نکات تخصصی

• مزایا: ساده، کم‌حجم، یادگیری آسان، مناسب برای اکثر اپلیکیشن‌های وب و اسکریپت‌ها.
• محدودیت‌ها: هوش و مدیریت پیشرفته مثل روتینگ پیچیده یا چرخه تمدید خودکار اسرار را ندارد؛ برای نیازهای امنیتی حساس و نگهداری مقادیر رمزنگاری شده بهتر است از سرویس‌های مدیریت اسرار استفاده کنید.
• اگر نیاز به تایپ‌های پیچیده‌تر دارید، می‌توانید cast سفارشی یا Wrapper بنویسید تا تبدیل‌های دلخواه انجام شود.

مثال پیشرفته: cast سفارشی

from decouple import config

def csv_ints(value):
    if not value:
        return []
    return [int(x.strip()) for x in value.split(',')]

IDS = config('IDS', default='', cast=csv_ints)

توضیح: در این مثال یک تابع تبدیل سفارشی تعریف کرده‌ایم که یک رشته کاما-جدا را به لیستی از اعداد صحیح تبدیل می‌کند. cast می‌تواند تابعی باشد که مقدار رشته را گرفته و نوع موردنظر را برمی‌گرداند.

نتیجه‌گیری و توصیه‌های عملی

python-decouple یک ابزار ساده اما قدرتمند برای جداکردن پیکربندی از کد است. برای پروژه‌های کوچک تا متوسط و حتی پروژه‌های بزرگ با مدیریت درست می‌تواند بسیار مفید باشد. با این حال برای محیط‌های حساس و تولیدی حتماً از راهکارهای امن‌تر برای نگهداری اسرار استفاده کنید و تنها از python-decouple برای آسان‌سازی توسعه محلی و خواندن متغیرهای محیطی بهره ببرید.

برای شروع: فایل .env بسازید، مقادیر مورد نیاز را در settings یا فایل پیکربندی خوانده و با استفاده از cast و default نوشته‌ها را ایمن و قابل مدیریت کنید.

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

ارسال