راهنمای 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.




