ساختار پروژه در Python؛ چه زمانی flat و چه زمانی src/ را انتخاب کنیم؟

چرا مهم است

اگر روی یک پروژهٔ Python کار می‌کنی، جای package فقط مسئلهٔ مرتب‌کردن فایل‌ها نیست. این انتخاب تعیین می‌کند کد چطور import و test شود و هنگام packaging چه چیزهایی همراه آن قرار بگیرد.

قبل از خواندن، این‌ها را بدان۴ مفهوم
flat layout

ساختاری که در آن package قابل import در ریشهٔ پروژه قرار دارد و بدون نصب پروژه می‌توان آن را import کرد.

در حال نگارش

src/ layout

ساختاری که package را زیر پوشهٔ src/ قرار می‌دهد و برای دسترسی به آن مرحلهٔ نصب لازم است؛ test‌ها در این حالت کد نصب‌شده را بررسی می‌کنند.

در حال نگارش

entry point

نقطه‌ای که اجرای برنامه از آن آغاز می‌شود؛ در پروژهٔ Python می‌توان آن را با __main__.py و تنظیمات pyproject.toml مشخص کرد.

در حال نگارش

CLI

روشی برای کار با برنامه از طریق واردکردن دستور در command line،؜ به‌جای استفاده از محیط گرافیکی.

در حال نگارش

راهنمای Real Python انتخاب ساختار پروژه در Python را از یک پرسش شروع می‌کند: قرار است script ساخته شود، application اجرا شود یا library در اختیار پروژه‌های دیگر قرار بگیرد؟ پاسخ، نقطهٔ شروع انتخاب میان flat layout و src/ layout است؛ دو ساختاری که تفاوت اصلی‌شان محل قرار گرفتن package نسبت به بقیهٔ فایل‌های پروژه است.

در این بحث، project و package یک معنا ندارند. project کل repository،؜ شامل تنظیمات، test‌ها و مستندات است؛ package همان بخشی است که می‌توان آن را import کرد. محل این بخش بر نحوهٔ import،؜ اجرای test و packaging اثر می‌گذارد. ساختار روشن همچنین کمک می‌کند مشارکت‌کنندهٔ تازه از روی نام و جای فایل‌ها بفهمد هر بخش کجاست.

در flat layout،؜ package در ریشهٔ پروژه قرار می‌گیرد و بدون نصب قابل import است. در src/ layout،؜ دسترسی به package به مرحلهٔ نصب وابسته می‌شود؛ در نتیجه test‌ها همان کدی را بررسی می‌کنند که به دست کاربران می‌رسد. راهنما src/ layout را انتخاب معمول برای library معرفی می‌کند، چون نصب بخشی از شیوهٔ استفاده از آن است و معمولاً از طریق PyPI یا یک index خصوصی توزیع می‌شود.

برای application،؜ انتخاب معمول flat layout است؛ بسیاری از web framework‌ها نیز پروژه را با همین ساختار ایجاد می‌کنند. وقتی packaging یا deployment با wheel اهمیت پیدا کند، تغییر به src/ مطرح می‌شود. script‌های کوچک الزاماً به چنین ساختاری نیاز ندارند و اغلب حتی بدون pyproject.toml اجرا می‌شوند؛ اگر بزرگ‌تر شوند، flat layout همراه این فایل قدم بعدی طبیعی است.

راهنما برای تعریف entry point،؜ یک فایل کم‌حجم __main__.py را در کنار بخش [project.scripts] در pyproject.toml پیشنهاد می‌کند و آن را جایگزین رویکردهای قدیمی‌تر مانند setup.py یا پوشهٔ bin/ می‌داند. برای پروژه‌ای که هم library و هم CLI است، توصیه این است که ساختار بر اساس بخش پرنیازتر، معمولاً library،؜ شکل بگیرد و CLI به‌صورت یک cli.py کم‌حجم اضافه شود.

درون package نیز subpackage‌هایی با نام متناسب با حوزهٔ مسئولیت، مانند core/ و api/، نسبت به module‌های همه‌منظوره‌ای مانند utils.py با رشد پروژه سازگارترند. مسیر تصمیم‌گیری پیشنهادی سه مرحله دارد: تشخیص نوع پروژه، انتخاب layout و سپس سازمان‌دهی اجزای داخلی package.

نکته کلیدی

پیش از انتخاب layout،؜ مشخص کن پروژه‌ات script،؜ application یا library است. برای library از src/ و برای application از flat به‌عنوان نقطهٔ شروع استفاده کن؛ اهمیت packaging می‌تواند این انتخاب را تغییر دهد.

خواندن مقاله اصلی (در زبانه‌ی جدید باز می‌شود)
برچسب‌ها (۳)