Apa struktur proyek terbaik untuk aplikasi Python? [Tutup]

Bayangkan Anda ingin mengembangkan aplikasi desktop pengguna akhir (bukan web) yang tidak sepele dengan Python. Apa cara terbaik untuk menyusun hierarki folder proyek?

Fitur yang diinginkan adalah kemudahan perawatan, keramahan IDE, kesesuaian untuk percabangan / penggabungan kontrol sumber, dan pembuatan paket instalasi yang mudah.

Khususnya:

1. Di mana Anda meletakkan sumbernya?
2. Di mana Anda meletakkan skrip startup aplikasi?
3. Di mana Anda meletakkan proyek IDE cruft?
4. Di mana Anda menempatkan tes unit / penerimaan?
5. Di mana Anda meletakkan data non-Python seperti file konfigurasi?
6. Di mana Anda meletakkan sumber non-Python seperti C ++ untuk modul ekstensi pyd / binary?

Tidak terlalu penting. Apa pun yang membuat Anda bahagia akan berhasil. Tidak ada banyak aturan konyol karena proyek Python bisa sederhana.

• /scriptsatau /binuntuk hal-hal seperti antarmuka baris perintah
• /tests untuk tes Anda
• /lib untuk perpustakaan bahasa-C Anda
• /doc untuk sebagian besar dokumentasi
• /apidoc untuk dokumentasi API yang dihasilkan Epydoc.

Dan direktori tingkat atas dapat berisi README, Config's dan yang lainnya.

Pilihan yang sulit adalah apakah menggunakan /srcpohon atau tidak . Python tidak memiliki perbedaan antara /src, /libdan /binseperti Java atau C memiliki.

Karena /srcdirektori tingkat atas dilihat oleh beberapa orang sebagai tidak berarti, direktori tingkat atas Anda dapat menjadi arsitektur tingkat atas aplikasi Anda.

• /foo
• /bar
• /baz

Saya sarankan meletakkan semua ini di bawah direktori "nama-produk-saya". Jadi, jika Anda menulis aplikasi bernama quux, direktori yang berisi semua hal ini dinamai /quux.

Proyek lain PYTHONPATH, kemudian, dapat mencakup /path/to/quux/foountuk menggunakan kembali QUUX.foomodul.

Dalam kasus saya, karena saya menggunakan Komodo Edit, cuft IDE saya adalah file .KPF tunggal. Saya benar-benar meletakkannya di /quuxdirektori tingkat atas , dan mengabaikan menambahkannya ke SVN.

Menurut struktur Filesystem Jean-Paul Calderone dari proyek Python :

Project/
|-- bin/
|   |-- project
|
|-- project/
|   |-- test/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |   
|   |-- __init__.py
|   |-- main.py
|
|-- setup.py
|-- README

Posting blog ini oleh Jean-Paul Calderone umumnya diberikan sebagai jawaban dalam #python di Freenode.

Struktur sistem file proyek Python

Melakukan:

• beri nama direktori yang terkait dengan proyek Anda. Misalnya, jika proyek Anda bernama "Twisted", beri nama direktori tingkat atas untuk file sumbernya Twisted. Ketika Anda melakukan rilis, Anda harus menyertakan nomor versi akhiran: Twisted-2.5.
• buat direktori Twisted/bindan letakkan executable Anda di sana, jika Anda punya. Jangan beri mereka .pyekstensi, bahkan jika itu adalah file sumber Python. Jangan memasukkan kode apa pun di dalamnya kecuali impor dan panggil ke fungsi utama yang ditentukan di tempat lain di proyek Anda. (Sedikit kerutan: karena pada Windows, juru bahasa dipilih oleh ekstensi file, pengguna Windows Anda sebenarnya menginginkan ekstensi .py. Jadi, ketika Anda mengemas untuk Windows, Anda mungkin ingin menambahkannya. Sayangnya tidak ada trik distutil yang mudah yang Saya tahu untuk mengotomatiskan proses ini. Menimbang bahwa pada POSIX ekstensi .py hanya merupakan kutil, sedangkan pada Windows kekurangannya adalah bug yang sebenarnya, jika basis pengguna Anda mencakup pengguna Windows, Anda mungkin ingin memilih untuk hanya memiliki .py ekstensi di mana-mana.)
• Jika proyek Anda dapat diekspresikan sebagai file sumber Python tunggal, maka masukkan ke direktori dan beri nama sesuatu yang terkait dengan proyek Anda. Sebagai contoh Twisted/twisted.py,. Jika Anda memerlukan banyak file sumber, buat paket sebagai gantinya ( Twisted/twisted/, dengan kosong Twisted/twisted/__init__.py) dan tempatkan file sumber Anda di dalamnya. Sebagai contoh Twisted/twisted/internet.py,.
• letakkan tes unit Anda dalam sub-paket paket Anda (catatan - ini berarti bahwa opsi file sumber Python tunggal di atas adalah trik - Anda selalu memerlukan setidaknya satu file lain untuk pengujian unit Anda). Sebagai contoh Twisted/twisted/test/,. Tentu saja, buatlah paket dengan Twisted/twisted/test/__init__.py. Tempatkan tes di file seperti Twisted/twisted/test/test_internet.py.
• tambahkan Twisted/READMEdan Twisted/setup.pyjelaskan dan instal perangkat lunak Anda, jika Anda merasa senang.

Jangan:

• letakkan sumber Anda di direktori bernama srcatau lib. Ini membuatnya sulit dijalankan tanpa menginstal.
• letakkan tes Anda di luar paket Python Anda. Ini membuatnya sulit untuk menjalankan tes terhadap versi yang diinstal.
• buat paket yang hanya memiliki __init__.pydan kemudian masukkan semua kode Anda __init__.py. Buat saja modul alih-alih paket, itu lebih sederhana.
• cobalah untuk membuat hack ajaib untuk membuat Python dapat mengimpor modul atau paket Anda tanpa meminta pengguna menambahkan direktori yang berisi itu ke jalur impor mereka (baik melalui PYTHONPATH atau mekanisme lain). Anda tidak akan menangani semua kasus dengan benar dan pengguna akan marah kepada Anda ketika perangkat lunak Anda tidak berfungsi di lingkungan mereka.

Lihat Sumber Terbuka Proyek Python dengan Cara yang Benar .

Biarkan saya kutip bagian tata letak proyek dari artikel yang sangat baik:

Saat menyiapkan proyek, tata letak (atau struktur direktori) penting untuk dikerjakan dengan benar. Tata letak yang masuk akal berarti bahwa kontributor potensial tidak perlu menghabiskan selamanya mencari sepotong kode; lokasi file intuitif. Karena kita sedang berurusan dengan proyek yang sudah ada, itu berarti Anda mungkin perlu memindahkan beberapa barang.

Mari kita mulai dari atas. Sebagian besar proyek memiliki sejumlah file tingkat atas (seperti setup.py, README.md, requirement.txt, dll). Lalu ada tiga direktori yang harus dimiliki setiap proyek:

• Direktori dokumen yang berisi dokumentasi proyek
• Direktori yang dinamai dengan nama proyek yang menyimpan paket Python yang sebenarnya
• Direktori uji di salah satu dari dua tempat
  • Di bawah direktori paket yang berisi kode uji dan sumber daya
  • Sebagai direktori tingkat atas yang berdiri sendiri Untuk mendapatkan pemahaman yang lebih baik tentang bagaimana file Anda harus diatur, berikut ini snapshot sederhana dari tata letak untuk salah satu proyek saya, sandman:

$ pwd
~/code/sandman
$ tree
.
|- LICENSE
|- README.md
|- TODO.md
|- docs
|   |-- conf.py
|   |-- generated
|   |-- index.rst
|   |-- installation.rst
|   |-- modules.rst
|   |-- quickstart.rst
|   |-- sandman.rst
|- requirements.txt
|- sandman
|   |-- __init__.py
|   |-- exception.py
|   |-- model.py
|   |-- sandman.py
|   |-- test
|       |-- models.py
|       |-- test_sandman.py
|- setup.py

Seperti yang Anda lihat, ada beberapa file level atas, direktori docs (dihasilkan adalah direktori kosong tempat sphinx akan meletakkan dokumentasi yang dihasilkan), direktori sandman, dan direktori uji di bawah sandman.

"Otoritas Pengemasan Python" memiliki proyek sampl:

https://github.com/pypa/sampleproject

Ini adalah proyek sampel yang ada sebagai bantuan untuk Tutorial Panduan Pengguna Kemasan Python tentang Proyek Pengemasan dan Distribusi.

Coba mulai proyek menggunakan templat python_boilerplate . Ini sebagian besar mengikuti praktik terbaik (misalnya yang ada di sini ), tetapi lebih cocok jika Anda merasa ingin membagi proyek Anda menjadi lebih dari satu telur di beberapa titik (dan percayalah, dengan apa pun kecuali proyek paling sederhana, Anda akan melakukannya.) situasi umum adalah ketika Anda harus menggunakan versi perpustakaan orang lain yang dimodifikasi secara lokal).

• Di mana Anda meletakkan sumbernya?

  • Untuk proyek besar yang layak, masuk akal untuk membagi sumber menjadi beberapa telur. Setiap telur akan diletakkan sebagai layouttools-layout terpisah di bawahnya PROJECT_ROOT/src/<egg_name>.

• Di mana Anda meletakkan skrip startup aplikasi?

  • Pilihan yang ideal adalah membuat skrip startup aplikasi terdaftar sebagai entry_pointsalah satu dari sel telur.

• Di mana Anda meletakkan proyek IDE cruft?

  • Tergantung pada IDE. Banyak dari mereka menyimpan barang-barang mereka PROJECT_ROOT/.<something>di root proyek, dan ini baik-baik saja.

• Di mana Anda menempatkan tes unit / penerimaan?

  • Setiap telur memiliki serangkaian tes terpisah, disimpan dalam PROJECT_ROOT/src/<egg_name>/testsdirektori. Saya pribadi lebih suka menggunakan py.testuntuk menjalankannya.

• Di mana Anda meletakkan data non-Python seperti file konfigurasi?

  • Tergantung. Mungkin ada berbagai jenis data non-Python.
    • "Sumberdaya" , yaitu data yang harus dikemas dalam sebuah telur. Data ini masuk ke direktori telur yang sesuai, di suatu tempat di dalam namespace paket. Ini dapat digunakan melalui pkg_resourcespaket dari setuptools, atau karena Python 3.7 melalui importlib.resourcesmodul dari pustaka standar.
    • "File config" , yaitu file non-Python yang dianggap eksternal dari file sumber proyek, tetapi harus diinisialisasi dengan beberapa nilai ketika aplikasi mulai berjalan. Selama pengembangan saya lebih suka menyimpan file seperti itu di PROJECT_ROOT/config. Untuk penyebaran bisa ada berbagai opsi. Di Windows seseorang dapat menggunakan %APP_DATA%/<app-name>/config, di Linux, /etc/<app-name>atau /opt/<app-name>/config.
    • File yang dihasilkan , yaitu file yang dapat dibuat atau dimodifikasi oleh aplikasi selama eksekusi. Saya lebih suka menyimpannya PROJECT_ROOT/varselama pengembangan, dan di bawah /varselama penyebaran Linux.
• Di mana Anda meletakkan sumber non-Python seperti C ++ untuk modul ekstensi pyd / binary?
  • Ke PROJECT_ROOT/src/<egg_name>/native

Dokumentasi biasanya akan masuk PROJECT_ROOT/docatau PROJECT_ROOT/src/<egg_name>/doc(ini tergantung pada apakah Anda menganggap beberapa telur sebagai proyek besar yang terpisah). Beberapa konfigurasi tambahan akan ada di file seperti PROJECT_ROOT/buildout.cfgdan PROJECT_ROOT/setup.cfg.

Dalam pengalaman saya, itu hanya masalah iterasi. Letakkan data dan kode Anda ke mana pun menurut Anda. Kemungkinannya, toh Anda akan salah. Tetapi begitu Anda mendapatkan ide yang lebih baik tentang bagaimana keadaan akan terbentuk, Anda berada dalam posisi yang jauh lebih baik untuk membuat tebakan semacam ini.

Sejauh sumber ekstensi, kami memiliki direktori Code di bawah trunk yang berisi direktori untuk python dan direktori untuk berbagai bahasa lainnya. Secara pribadi, saya lebih cenderung mencoba memasukkan kode ekstensi apa pun ke dalam repositori sendiri di waktu mendatang.

Dengan mengatakan itu, saya kembali ke titik awal saya: jangan terlalu mempermasalahkan hal itu. Letakkan di suatu tempat yang tampaknya bekerja untuk Anda. Jika Anda menemukan sesuatu yang tidak berhasil, itu dapat (dan harus) diubah.

Data non-python terbaik dibundel di dalam modul Python Anda menggunakan package_datadukungan di setuptools . Satu hal yang saya sangat sarankan adalah menggunakan paket namespace untuk membuat ruang nama bersama yang dapat digunakan beberapa proyek - mirip dengan konvensi Java untuk memasukkan paket com.yourcompany.yourproject(dan dapat memiliki com.yourcompany.utilsnamespace bersama ).

Bercabang kembali dan menggabungkan, jika Anda menggunakan sistem kontrol sumber yang cukup baik, ia akan menangani penggabungan bahkan melalui penggantian nama; Bazaar sangat pandai dalam hal ini.

Bertentangan dengan beberapa jawaban lain di sini, saya +1 memiliki srcdirektori tingkat atas (dengan docdan testdirektori di samping). Konvensi khusus untuk pohon direktori dokumentasi akan bervariasi tergantung pada apa yang Anda gunakan; Sphinx , misalnya, memiliki konvensi sendiri yang didukung oleh alat cepatnya.

Tolong, tolong manfaatkan setuptools dan pkg_resources; ini membuatnya lebih mudah bagi proyek lain untuk bergantung pada versi spesifik kode Anda (dan untuk beberapa versi diinstal secara bersamaan dengan file non-kode yang berbeda, jika Anda menggunakan package_data).