Cấu trúc dự án tốt nhất cho ứng dụng Python là gì? [đóng cửa]

Hãy tưởng tượng rằng bạn muốn phát triển một ứng dụng máy tính để bàn (không phải web) cho người dùng cuối không tầm thường trong Python. Cách tốt nhất để cấu trúc phân cấp thư mục của dự án là gì?

Các tính năng mong muốn là dễ bảo trì, thân thiện với IDE, sự phù hợp để phân nhánh / hợp nhất kiểm soát nguồn và tạo các gói cài đặt dễ dàng.

Đặc biệt:

1. Bạn đặt nguồn ở đâu?
2. Nơi nào bạn đặt các kịch bản khởi động ứng dụng?
3. Nơi nào bạn đặt dự án IDE cruft?
4. Nơi nào bạn đặt các bài kiểm tra đơn vị / chấp nhận?
5. Nơi nào bạn đặt dữ liệu không phải Python như tệp cấu hình?
6. Nơi nào bạn đặt các nguồn không phải Python như C ++ cho các mô đun mở rộng nhị phân pyd / so?

Không quá nhiều vấn đề. Bất cứ điều gì làm cho bạn hạnh phúc sẽ làm việc. Không có nhiều quy tắc ngớ ngẩn vì các dự án Python có thể đơn giản.

• /scriptshoặc /bincho loại công cụ giao diện dòng lệnh đó
• /tests cho bài kiểm tra của bạn
• /lib cho các thư viện ngôn ngữ C của bạn
• /doc cho hầu hết các tài liệu
• /apidoc cho các tài liệu API do Epydoc tạo.

Và thư mục cấp cao nhất có thể chứa README, Config và whatnot.

Sự lựa chọn khó khăn là có hay không sử dụng /srccây. Python không có một sự phân biệt giữa /src, /libvà /binnhư Java hay C có.

Vì một /srcthư mục cấp cao nhất được một số người coi là vô nghĩa, thư mục cấp cao nhất của bạn có thể là kiến ​​trúc cấp cao nhất của ứng dụng của bạn.

• /foo
• /bar
• /baz

Tôi khuyên bạn nên đặt tất cả những thứ này trong thư mục "tên sản phẩm của tôi". Vì vậy, nếu bạn đang viết một ứng dụng có tên quux, thư mục chứa tất cả những thứ này được đặt tên /quux.

PYTHONPATHSau đó, một dự án khác có thể bao gồm /path/to/quux/foođể sử dụng lại QUUX.foomô-đun.

Trong trường hợp của tôi, vì tôi sử dụng Komodo Edit, cuft IDE của tôi là một tệp .KPF duy nhất. Tôi thực sự đã đặt nó trong /quuxthư mục cấp cao nhất và bỏ qua việc thêm nó vào SVN.

Theo cấu trúc hệ thống tập tin của Jean-Paul Calderone trong một dự án Python :

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

Bài đăng trên blog này của Jean-Paul Calderone thường được đưa ra như một câu trả lời trong #python trên Freenode.

Cấu trúc hệ thống tệp của dự án Python

Làm:

• Đặt tên cho thư mục một cái gì đó liên quan đến dự án của bạn. Ví dụ: nếu dự án của bạn được đặt tên là "Twisted", hãy đặt tên thư mục cấp cao nhất cho các tệp nguồn của nó Twisted. Khi bạn phát hành, bạn nên bao gồm hậu tố số phiên bản : Twisted-2.5.
• tạo một thư mục Twisted/binvà đặt các tệp thực thi của bạn ở đó, nếu bạn có bất kỳ. Đừng cung cấp cho họ một .pyphần mở rộng, ngay cả khi chúng là các tệp nguồn Python. Đừng đặt bất kỳ mã nào vào chúng ngoại trừ việc nhập và gọi đến một hàm chính được xác định ở một nơi khác trong các dự án của bạn. (Hơi nhăn: vì trên Windows, trình thông dịch được chọn bởi phần mở rộng tệp, người dùng Windows của bạn thực sự muốn có phần mở rộng .py. Vì vậy, khi bạn đóng gói cho Windows, bạn có thể muốn thêm nó. Tôi biết để tự động hóa quá trình này. Xem xét rằng trên POSIX, phần mở rộng .py chỉ là một mụn cóc, trong khi trên Windows, thiếu là một lỗi thực tế, nếu cơ sở người dùng của bạn bao gồm người dùng Windows, bạn có thể muốn chọn chỉ có .py mở rộng ở mọi nơi.)
• Nếu dự án của bạn có thể biểu thị dưới dạng một tệp nguồn Python duy nhất, thì hãy đặt nó vào thư mục và đặt tên cho nó là một cái gì đó liên quan đến dự án của bạn. Ví dụ , Twisted/twisted.py. Nếu bạn cần nhiều tệp nguồn, hãy tạo một gói thay thế ( Twisted/twisted/, với một khoảng trống Twisted/twisted/__init__.py) và đặt các tệp nguồn của bạn vào đó. Ví dụ , Twisted/twisted/internet.py.
• đặt các bài kiểm tra đơn vị của bạn trong gói phụ của gói của bạn (lưu ý - điều này có nghĩa là tùy chọn tệp nguồn Python duy nhất ở trên là một mẹo - bạn luôn cần ít nhất một tệp khác cho các bài kiểm tra đơn vị của mình). Ví dụ , Twisted/twisted/test/. Tất nhiên, làm cho nó một gói với Twisted/twisted/test/__init__.py. Đặt thử nghiệm trong các tập tin như Twisted/twisted/test/test_internet.py.
• thêm Twisted/READMEvà Twisted/setup.pyđể giải thích và cài đặt phần mềm của bạn, tương ứng, nếu bạn cảm thấy tốt.

Đừng:

• đặt nguồn của bạn trong một thư mục được gọi là srchoặc lib. Điều này làm cho nó khó chạy mà không cần cài đặt.
• đặt các bài kiểm tra của bạn bên ngoài gói Python của bạn. Điều này khiến cho việc chạy thử nghiệm đối với phiên bản đã cài đặt trở nên khó khăn.
• tạo một gói chỉ có một __init__.pyvà sau đó đặt tất cả mã của bạn vào __init__.py. Chỉ cần tạo một mô-đun thay vì một gói, nó đơn giản hơn.
• cố gắng đưa ra các bản hack ma thuật để làm cho Python có thể nhập mô-đun hoặc gói của bạn mà không cần người dùng thêm thư mục chứa nó vào đường dẫn nhập của chúng (thông qua PYTHONPATH hoặc một số cơ chế khác). Bạn sẽ không xử lý chính xác tất cả các trường hợp và người dùng sẽ tức giận với bạn khi phần mềm của bạn không hoạt động trong môi trường của họ.

Kiểm tra nguồn mở một dự án Python đúng cách .

Hãy để tôi trích đoạn phần bố trí dự án của bài viết xuất sắc đó:

Khi thiết lập một dự án, bố cục (hoặc cấu trúc thư mục) rất quan trọng để có được quyền. Bố cục hợp lý có nghĩa là những người đóng góp tiềm năng không phải mất thời gian để săn lùng một đoạn mã; vị trí tập tin là trực quan. Vì chúng tôi đang xử lý một dự án hiện có, điều đó có nghĩa là bạn có thể sẽ cần phải di chuyển một số thứ xung quanh.

Hãy bắt đầu từ đầu. Hầu hết các dự án đều có một số tệp cấp cao nhất (như setup.py, README.md, tests.txt, v.v.). Sau đó, có ba thư mục mà mọi dự án nên có:

• Một thư mục tài liệu chứa tài liệu dự án
• Một thư mục có tên của dự án lưu trữ gói Python thực tế
• Một thư mục thử nghiệm ở một trong hai nơi
  • Trong thư mục gói chứa mã kiểm tra và tài nguyên
  • Là một thư mục cấp cao nhất độc lập Để hiểu rõ hơn về cách tổ chức các tệp của bạn, đây là một ảnh chụp đơn giản về bố cục cho một trong các dự án của tôi, 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

Như bạn có thể thấy, có một số tệp cấp cao nhất, thư mục docs (được tạo là một thư mục trống trong đó nhân sư sẽ đặt tài liệu đã tạo), thư mục sandman và thư mục kiểm tra dưới sandman.

"Cơ quan đóng gói Python" có một dự án mẫu:

https://github.com/pypa/sampleproject

Đây là một dự án mẫu tồn tại dưới dạng trợ giúp cho Hướng dẫn sử dụng bao bì và phân phối dự án của Hướng dẫn sử dụng bao bì Python.

Hãy thử bắt đầu dự án bằng cách sử dụng mẫu python_boilerplate . Nó chủ yếu tuân theo các thực tiễn tốt nhất (ví dụ như ở đây ), nhưng phù hợp hơn trong trường hợp bạn thấy mình sẵn sàng chia dự án của bạn thành nhiều quả trứng vào một lúc nào đó (và tin tôi, với bất cứ điều gì trừ các dự án đơn giản nhất, bạn sẽ làm. tình huống phổ biến là bạn phải sử dụng phiên bản sửa đổi cục bộ của thư viện của người khác).

• Bạn đặt nguồn ở đâu?

  • Đối với các dự án lớn, thật hợp lý khi chia nguồn thành nhiều quả trứng. Mỗi quả trứng sẽ là một bố cục thiết lập riêng biệt bên dưới PROJECT_ROOT/src/<egg_name>.

• Nơi nào bạn đặt các kịch bản khởi động ứng dụng?

  • Tùy chọn lý tưởng là có tập lệnh khởi động ứng dụng được đăng ký như một entry_pointtrong những quả trứng.

• Nơi nào bạn đặt dự án IDE cruft?

  • Phụ thuộc vào IDE. Nhiều người trong số họ giữ công cụ của họ PROJECT_ROOT/.<something>trong thư mục gốc của dự án, và điều này là tốt.

• Nơi nào bạn đặt các bài kiểm tra đơn vị / chấp nhận?

  • Mỗi quả trứng có một bộ thử nghiệm riêng, được giữ trong PROJECT_ROOT/src/<egg_name>/teststhư mục của nó . Cá nhân tôi thích sử dụng py.testđể chạy chúng.

• Nơi nào bạn đặt dữ liệu không phải Python như tệp cấu hình?

  • Nó phụ thuộc. Có thể có nhiều loại dữ liệu không phải là Python.
    • "Tài nguyên" , tức là dữ liệu phải được đóng gói trong một quả trứng. Dữ liệu này đi vào thư mục trứng tương ứng, ở đâu đó trong không gian tên gói. Nó có thể được sử dụng thông qua pkg_resourcesgói từ setuptoolshoặc từ Python 3.7 qua importlib.resourcesmô-đun từ thư viện chuẩn.
    • "Tệp cấu hình" , tức là các tệp không phải Python được coi là bên ngoài đối với các tệp nguồn dự án, nhưng phải được khởi tạo với một số giá trị khi ứng dụng bắt đầu chạy. Trong quá trình phát triển, tôi thích giữ các tập tin như vậy PROJECT_ROOT/config. Để triển khai có thể có nhiều lựa chọn khác nhau. Trên Windows người ta có thể sử dụng %APP_DATA%/<app-name>/config, trên Linux, /etc/<app-name>hoặc /opt/<app-name>/config.
    • Các tệp được tạo , tức là các tệp có thể được tạo hoặc sửa đổi bởi ứng dụng trong khi thực thi. Tôi muốn giữ chúng trong PROJECT_ROOT/varquá trình phát triển và /vartrong quá trình triển khai Linux.
• Nơi nào bạn đặt các nguồn không phải Python như C ++ cho các mô đun mở rộng nhị phân pyd / so?
  • Vào PROJECT_ROOT/src/<egg_name>/native

Tài liệu thường đi vào PROJECT_ROOT/dochoặc PROJECT_ROOT/src/<egg_name>/doc(điều này phụ thuộc vào việc bạn coi một số trứng là một dự án lớn riêng biệt). Một số cấu hình bổ sung sẽ có trong các tập tin như PROJECT_ROOT/buildout.cfgvà PROJECT_ROOT/setup.cfg.

Theo kinh nghiệm của tôi, đó chỉ là vấn đề lặp đi lặp lại. Đặt dữ liệu và mã của bạn bất cứ nơi nào bạn nghĩ rằng họ đi. Rất có thể, dù sao bạn cũng sẽ sai. Nhưng một khi bạn có được một ý tưởng tốt hơn về chính xác mọi thứ sẽ hình thành như thế nào, bạn sẽ ở một vị trí tốt hơn nhiều để đưa ra những loại dự đoán này.

Theo như các nguồn mở rộng, chúng tôi có một thư mục Code trong thân cây chứa một thư mục cho python và một thư mục cho các ngôn ngữ khác nhau. Cá nhân, tôi có xu hướng thử đưa bất kỳ mã mở rộng nào vào kho lưu trữ của riêng mình vào lần tới.

Như đã nói, tôi quay trở lại điểm ban đầu của mình: đừng tạo ra một thỏa thuận quá lớn từ nó. Đặt nó ở một nơi nào đó dường như làm việc cho bạn. Nếu bạn tìm thấy một cái gì đó không hoạt động, nó có thể (và nên) được thay đổi.

Dữ liệu không phải python được gói tốt nhất bên trong các mô-đun Python của bạn bằng cách sử dụng package_datahỗ trợ trong setuptools . Một điều tôi đặc biệt khuyên bạn là sử dụng các gói không gian tên để tạo các không gian tên được chia sẻ mà nhiều dự án có thể sử dụng - giống như quy ước Java về việc đặt các gói vào com.yourcompany.yourproject(và có thể có một com.yourcompany.utilskhông gian tên được chia sẻ ).

Phân nhánh lại và sáp nhập, nếu bạn sử dụng một hệ thống kiểm soát nguồn đủ tốt, nó sẽ xử lý việc hợp nhất ngay cả thông qua đổi tên; Bazaar đặc biệt tốt trong việc này.

Trái với một số câu trả lời khác ở đây, tôi +1 về việc có một srcthư mục cấp cao nhất (có docvà testthư mục bên cạnh). Các quy ước cụ thể cho cây thư mục tài liệu sẽ thay đổi tùy thuộc vào những gì bạn đang sử dụng; Sphinx , ví dụ, có các quy ước riêng mà công cụ khởi động nhanh của nó hỗ trợ.

Xin vui lòng, hãy tận dụng setuptools và pkg_resource; điều này giúp các dự án khác dễ dàng hơn nhiều dựa vào các phiên bản mã cụ thể của bạn (và cho nhiều phiên bản được cài đặt đồng thời với các tệp không phải mã khác nhau, nếu bạn đang sử dụng package_data).