setuptools.setup()gọi distutils.core.setup()và vượt qua nó **kwargslà tham số duy nhất, vì vậy mọi từ khóa distutilschấp nhận cũng sẽ được chấp nhận setuptools. Nếu chúng ta đi nhìn vàodistutils
setup_keywords = ('distclass', 'script_name', 'script_args',
'options', 'name', 'version', 'author',
'author_email', 'maintainer', 'maintainer_email',
'url', 'license', 'description',
'long_description', 'keywords', 'platforms',
'classifiers', 'download_url', 'requires',
'provides', 'obsoletes',
)
Hầu hết trong số này được ghi nhận ở đây nhưng một số không có trong bảng: gói , package_dir , package_data , kịch bản , obsoletes , proviodes , py_modules và data_files .
Một số trong số này cũng bị thiếu trong setup_keywordsbộ dữ liệu. Và nếu bạn grep chosetup_keywords nó không giống như nó thực sự được tham chiếu ở bất cứ đâu .... Nhưng đó là một câu chuyện cho một ngày khác. Dù sao, đây là danh sách (hy vọng đầy đủ).
đối số từ khóa distutils.core.setup ()
( Bắt buộc : tên , phiên bản và ít nhất một tác giả hoặc người bảo trì )
tác giả:
tên tác giả gói (bắt buộc nếu người bảo trì không được cung cấp)
tác giả_email:
địa chỉ email của tác giả gói
phân loại:
một danh sách các phân loại (xem: https://pypi.org/classifiers/ )
data_files :
Các data_files tùy chọn có thể được dùng để xác định tập tin bổ sung cần thiết cho phân phối mô-đun: file cấu hình, catalog tin nhắn, tập tin dữ liệu, bất cứ điều gì mà không phù hợp trong các danh mục trước đó.
data_fileschỉ định một chuỗi các (directory, files)cặp theo cách sau:
setup(...,
data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
('config', ['cfg/data.cfg'])],
)
Mỗi (directory, files)cặp trong chuỗi xác định thư mục cài đặt và các tệp để cài đặt ở đó. Mỗi tên tệp trong tệp được giải thích liên quan đến setup.pytập lệnh.
sự miêu tả:
ngắn gọn, mô tả tóm tắt của gói
download_url:
vị trí nơi gói có thể được tải xuống
từ khóa:
một danh sách các từ khóa (Cũng có một chuỗi. Nếu được phân tách bằng dấu phẩy, nó được chia thành một danh sách)
giấy phép:
giấy phép cho gói (Chỉ sử dụng nếu giấy phép không được liệt kê trong "phân loại trove". Xem: Phân loại)
Mô tả dài:
mô tả dài hơn về gói, được PyPI sử dụng để xây dựng trang dự án
người bảo trì:
tên người bảo trì gói (bắt buộc nếu tác giả không được cung cấp)
duy trì_email:
địa chỉ email của người bảo trì gói
Tên:
Tên của gói (yêu cầu bởi distutils)
lỗi thời :
Một gói có thể tuyên bố rằng nó làm lỗi các gói khác bằng cách sử dụng obsoletesđối số từ khóa. Giá trị này tương tự với requirestừ khóa: danh sách các chuỗi cung cấp mô-đun hoặc bộ xác định gói. Mỗi specifier bao gồm một mô-đun hoặc tên gói tùy chọn theo sau bởi một hoặc nhiều vòng loại phiên bản. Vòng loại phiên bản được đưa ra trong ngoặc đơn sau tên mô-đun hoặc gói
gói_data :
Dữ liệu gói có thể được thêm vào các gói bằng cách sử dụng package_datađối số từ khóa cho setup()hàm. Giá trị phải là ánh xạ từ tên gói đến danh sách các tên đường dẫn tương đối sẽ được sao chép vào gói. Các đường dẫn được hiểu là liên quan đến thư mục chứa gói (thông tin từ package_diránh xạ được sử dụng nếu thích hợp); nghĩa là, các tệp được dự kiến là một phần của gói trong các thư mục nguồn.
gói_dir :
Nếu bạn sử dụng một quy ước khác để bố trí thư mục nguồn của mình, thì đó không phải là vấn đề: bạn chỉ cần cung cấp package_dirtùy chọn để thông báo cho các Distutils về quy ước của bạn. Ví dụ: giả sử bạn giữ tất cả nguồn Python bên dưới lib, để các mô-đun trong gói gốc root của Google (tức là không có trong bất kỳ gói nào) lib, các mô-đun trong foogói nằm trong lib/foo, v.v. Sau đó, bạn sẽ đặt
package_dir = {'': 'lib'}
trong tập lệnh thiết lập của bạn. Các khóa của từ điển này là tên gói và tên gói trống là viết tắt của gói gốc. Các giá trị là tên thư mục liên quan đến gốc phân phối của bạn. Trong trường hợp này, khi bạn nói packages = ['foo'], bạn hứa rằng tập tinlib/foo/__init__.py tồn tại.
Một quy ước có thể khác là đặt foogói ngay lib, foo.bargói vào lib/bar, v.v. Điều này sẽ được viết trong tập lệnh thiết lập như
package_dir = {'foo': 'lib'}
Một package: dirmục trong package_dirtừ điển ngầm áp dụng cho tất cả các gói bên dưới gói, vì vậy foo.bartrường hợp được tự động xử lý ở đây. Trong ví dụ này, việc packages = ['foo', 'foo.bar']nói với các Distutils tìm kiếm lib/__init__.pyvà lib/bar/__init__.py. (Hãy nhớ rằng mặc dù package_diráp dụng đệ quy, bạn phải liệt kê rõ ràng tất cả các gói trong các gói: Distutils sẽ không quét đệ quy cây nguồn của bạn để tìm bất kỳ thư mục nào có __init__.pytệp.)
gói :
Dữ liệu gói có thể được thêm vào các gói bằng cách sử dụng package_datađối số từ khóa cho setup()hàm. Giá trị phải là ánh xạ từ tên gói đến danh sách các tên đường dẫn tương đối sẽ được sao chép vào gói. Các đường dẫn được hiểu là liên quan đến thư mục chứa gói (thông tin từ package_diránh xạ được sử dụng nếu thích hợp); nghĩa là, các tệp được dự kiến là một phần của gói trong các thư mục nguồn. Chúng có thể chứa các mẫu toàn cầu là tốt.
nền tảng:
một danh sách các nền tảng (Cũng có một chuỗi. Nếu được phân tách bằng dấu phẩy, nó được chia thành một danh sách)
cung cấp :
Bây giờ chúng tôi có thể chỉ định các phụ thuộc, chúng tôi cũng cần có thể chỉ định những gì chúng tôi cung cấp mà các bản phân phối khác có thể yêu cầu. Điều này được thực hiện bằng cách sử dụng providesđối số từ khóa để setup().
py_modules :
Đối với phân phối mô-đun nhỏ, bạn có thể thích liệt kê tất cả các mô-đun hơn là liệt kê các gói, đặc biệt là trường hợp của một mô-đun duy nhất có trong gói gốc Root, tức là không có gói nào.
py_modules = ['foo.py']
đây là một ví dụ liên quan nhiều hơn một chút:
py_modules = ['mod1', 'pkg.mod2']
Mô tả này mô tả hai mô-đun, một trong số chúng trong gói Root root, còn lại là pkggói. Một lần nữa, bố cục gói / thư mục mặc định ngụ ý rằng hai mô-đun này có thể được tìm thấy trong mod1.pyvà pkg/mod2.py, và điều đó cũng pkg/__init__.pytồn tại. Và một lần nữa, bạn có thể ghi đè tương ứng gói / thư mục bằng cách sử dụng package_dirtùy chọn.
kịch bản :
Các tập lệnh là các tệp chứa mã nguồn Python, dự định được bắt đầu từ dòng lệnh. Các kịch bản không yêu cầu Distutils làm bất cứ điều gì rất phức tạp. Tính năng thông minh duy nhất là nếu dòng đầu tiên của tập lệnh bắt đầu bằng #!và có chứa từ trăn trăn, thì Distutils sẽ điều chỉnh dòng đầu tiên để chỉ vị trí trình thông dịch hiện tại. Theo mặc định, nó được thay thế bằng vị trí thông dịch viên hiện tại. Các-- thực thi (hoặc-e ) tùy chọn sẽ cho phép con đường thông dịch viên để được ghi đè một cách rõ ràng.
Tùy chọn script đơn giản là một danh sách các tệp sẽ được xử lý theo cách này. Từ tập lệnh thiết lập PyXML:
setup(...,
scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
)
url:
trang chủ cho gói
phiên bản:
phiên bản của phiên bản này (bắt buộc bởi distutils)
đối số từ khóa setuptools.setup ()
Thậm chí còn có nhiều đối số setuptools.setup()sẽ chấp nhận, ngoài những đối số được sử dụng bởidistutils .
Mặc dù được gọi là "Từ khóa thiết lập mới và thay đổi" (theo tôi gợi ý thay đổi phiên bản), văn bản giới thiệu cho biết đây là "đối số từ khóa để thiết lập () [được] thêm hoặc thay đổi bởi setuptools" vì vậy tôi tin rằng liên kết thực sự cung cấp một danh sách đầy đủ. Tôi sẽ thêm nó ở đây cho đầy đủ.
(Vì setuptools.setup()các cuộc gọi distutils.core.setup(), các tham số tương tự là Bắt buộc : tên , phiên bản và ít nhất một trong số các tác giả hoặc người bảo trì )
convert_2to3_doctests:
Danh sách các tệp nguồn doctest cần được chuyển đổi với 2to3. Xem Hỗ trợ cả Python 2 và Python 3 với Setuptools để biết thêm chi tiết.
phụ thuộc_links:
Một danh sách các chuỗi đặt tên URL sẽ được tìm kiếm khi đáp ứng các phụ thuộc. Các liên kết này sẽ được sử dụng nếu cần để cài đặt các gói được chỉ định bởi setup_Vquires hoặc tests_Vquire. Chúng cũng sẽ được ghi vào siêu dữ liệu của trứng để sử dụng bởi các công cụ như EasyInstall để sử dụng khi cài đặt tệp .egg.
háo hức
Một danh sách các tài nguyên đặt tên chuỗi nên được trích xuất cùng nhau, nếu cần bất kỳ tài nguyên nào trong số chúng, hoặc nếu có bất kỳ phần mở rộng C nào có trong dự án được nhập. Đối số này chỉ hữu ích nếu dự án sẽ được cài đặt dưới dạng zipfile và cần phải có tất cả các tài nguyên được liệt kê để trích xuất vào hệ thống tệp dưới dạng một đơn vị. Các tài nguyên được liệt kê ở đây phải là '/' - các đường dẫn được phân tách, liên quan đến gốc nguồn, vì vậy để liệt kê một tài nguyên foo.png trong gói bar.baz, bạn sẽ bao gồm thanh chuỗi / baz / foo.png trong đối số này. Nếu bạn chỉ cần lấy tài nguyên một lần hoặc bạn không có bất kỳ tiện ích mở rộng C nào truy cập các tệp khác trong dự án (như tệp dữ liệu hoặc thư viện dùng chung), bạn có thể KHÔNG cần đối số này và không nên gây rối với nó. Để biết thêm chi tiết về cách hoạt động của đối số này,
các điểm nhập cảnh:
Một tên nhóm điểm nhập ánh xạ từ điển thành chuỗi hoặc danh sách các chuỗi xác định điểm nhập. Điểm vào được sử dụng để hỗ trợ khám phá động các dịch vụ hoặc plugin do dự án cung cấp. Xem Khám phá động về dịch vụ và plugin để biết chi tiết và ví dụ về định dạng của đối số này. Ngoài ra, từ khóa này được sử dụng để hỗ trợ Tạo tập lệnh tự động.
loại trừ_package_data:
Một tên gói ánh xạ từ điển đến danh sách các mẫu toàn cầu cần được loại trừ khỏi các thư mục gói của bạn. Bạn có thể sử dụng điều này để cắt bớt bất kỳ tập tin dư thừa nào được bao gồm bởi include_package_data. Để biết mô tả và ví dụ đầy đủ, hãy xem phần bên dưới về Bao gồm tệp dữ liệu.
ngoại lệ:
Một tên ánh xạ từ điển của các tính năng bổ sung, các tính năng tùy chọn của dự án của bạn) thành các chuỗi hoặc danh sách các chuỗi xác định các phân phối khác phải được cài đặt để hỗ trợ các tính năng đó. Xem phần bên dưới về Khai báo phụ thuộc để biết chi tiết và ví dụ về định dạng của đối số này.
bao gồm_package_data:
Nếu được đặt thành True, điều này sẽ báo cho setuptools tự động bao gồm mọi tệp dữ liệu mà nó tìm thấy trong các thư mục gói được chỉ định bởi tệp MANIFEST.in của bạn. Để biết thêm thông tin, hãy xem phần bên dưới về Bao gồm tệp dữ liệu.
cài đặt:
Một chuỗi hoặc danh sách các chuỗi xác định những phân phối khác cần được cài đặt khi chuỗi này là. Xem phần bên dưới về Khai báo phụ thuộc để biết chi tiết và ví dụ về định dạng của đối số này.
namepace_packages:
Một danh sách các chuỗi đặt tên cho các gói không gian tên của dự án là tên lửa. Gói không gian tên là gói có thể được phân chia trên nhiều bản phân phối dự án. Ví dụ, gói zope của Zope 3 là gói không gian tên, vì các gói con như zope.interface và zope.publisher có thể được phân phối riêng. Hệ thống thời gian chạy trứng có thể tự động hợp nhất các gói con đó vào một gói cha duy nhất trong thời gian chạy, miễn là bạn khai báo chúng trong mỗi dự án có chứa bất kỳ gói con nào của gói không gian tên và miễn là init .py của gói không gian tên không chứa bất kỳ mã nào khác với một khai báo không gian tên. Xem phần bên dưới trên Gói Namespace để biết thêm thông tin.
gói_data:
Một gói ánh xạ từ điển tên vào danh sách các mẫu toàn cầu. Để biết mô tả và ví dụ đầy đủ, hãy xem phần bên dưới về Bao gồm tệp dữ liệu. Bạn không cần sử dụng tùy chọn này nếu bạn đang sử dụng include_package_data, trừ khi bạn cần thêm ví dụ: các tệp được tạo bởi tập lệnh thiết lập và quá trình xây dựng của bạn. (Và do đó không nằm trong kiểm soát nguồn hoặc là các tệp mà bạn không muốn đưa vào phân phối nguồn của mình.)
dự án_urls:
Một bản đồ tùy ý các tên URL tới các siêu liên kết, cho phép nhiều tài liệu mở rộng hơn về nơi có thể tìm thấy các tài nguyên khác nhau so với các tùy chọn url và download_url đơn giản cung cấp.
python_Vquires:
Một chuỗi tương ứng với một công cụ xác định phiên bản (như được định nghĩa trong PEP 440) cho phiên bản Python, được sử dụng để chỉ định Yêu cầu-Python được xác định trong PEP 345.
setup_Vquires:
Một chuỗi hoặc danh sách các chuỗi xác định những gì các bản phân phối khác cần phải có để tập lệnh thiết lập chạy. setuptools sẽ cố gắng để có được những thứ này (thậm chí sẽ đi xa hơn để tải chúng xuống bằng EasyInstall) trước khi xử lý phần còn lại của tập lệnh hoặc lệnh thiết lập. Đối số này là cần thiết nếu bạn đang sử dụng tiện ích mở rộng distutils như một phần của quy trình xây dựng; ví dụ: các phần mở rộng xử lý các đối số thiết lập () và biến chúng thành các tệp siêu dữ liệu EGG-INFO. (Lưu ý: các dự án được liệt kê trong setup_Vquires sẽ KHÔNG được cài đặt tự động trên hệ thống nơi tập lệnh thiết lập đang được chạy. Chúng chỉ được tải xuống thư mục ./.egss nếu chúng không có sẵn tại địa phương. Nếu bạn muốn chúng được cài đặt , cũng như có sẵn khi tập lệnh thiết lập được chạy, bạn nên thêm chúng vào install_Vquires và setup_Vquires.)
test_loader:
Nếu bạn muốn sử dụng một cách khác để tìm các bài kiểm tra để chạy so với những gì setuptools thường sử dụng, bạn có thể chỉ định tên mô-đun và tên lớp trong đối số này. Lớp được đặt tên phải có thể thực hiện được mà không có đối số và các thể hiện của nó phải hỗ trợ phương thức loadTestsFromNames () như được định nghĩa trong lớp TestLoader của mô-đun unittest của Python. Setuptools sẽ chỉ vượt qua một thử nghiệm Tên tên nghiêm trọng trong đối số tên: giá trị được cung cấp cho đối số test_suite. Trình tải mà bạn chỉ định có thể diễn giải chuỗi này theo bất kỳ cách nào nó thích, vì không có hạn chế nào đối với những gì có thể có trong chuỗi test_suite. Tên mô-đun và tên lớp phải được phân tách bằng a :. Giá trị mặc định của đối số này là "setuptools.command.test: ScanningLoader". Nếu bạn muốn sử dụng hành vi unittest mặc định, bạn có thể chỉ định "unittest: TestLoader" làm đối số test_loader của bạn thay vào đó. Điều này sẽ ngăn tự động quét các mô hình con và gói con. Mô-đun và lớp bạn chỉ định ở đây có thể được chứa trong một gói khác, miễn là bạn sử dụng tùy chọn tests_Vquire để đảm bảo rằng gói chứa lớp trình nạp có sẵn khi lệnh kiểm tra được chạy.
test_suite:
Một chuỗi đặt tên một lớp con unittest.TestCase (hoặc một gói hoặc mô-đun chứa một hoặc nhiều trong số chúng, hoặc một phương thức của một lớp con đó) hoặc đặt tên một hàm có thể được gọi mà không có đối số và trả về một unittest.TestSuite. Nếu bộ được đặt tên là một mô-đun và mô-đun có hàm thêm_tests (), nó được gọi và kết quả được thêm vào các thử nghiệm sẽ được chạy. Nếu bộ được đặt tên là một gói, bất kỳ mô hình con và gói con nào sẽ được thêm đệ quy vào bộ thử nghiệm tổng thể. Việc chỉ định đối số này cho phép sử dụng lệnh kiểm tra để chạy bộ kiểm tra đã chỉ định, ví dụ: thông qua kiểm tra setup.py. Xem phần trên lệnh kiểm tra bên dưới để biết thêm chi tiết.
kiểm tra thông tin:
Nếu các thử nghiệm của dự án của bạn cần một hoặc nhiều gói bổ sung ngoài các gói cần thiết để cài đặt nó, bạn có thể sử dụng tùy chọn này để chỉ định chúng. Nó phải là một chuỗi hoặc danh sách các chuỗi xác định những gì các bản phân phối khác cần phải có để các thử nghiệm của gói chạy. Khi bạn chạy lệnh kiểm tra, setuptools sẽ cố gắng để có được những thứ này (thậm chí sẽ đi xa hơn để tải chúng xuống bằng EasyInstall). Lưu ý rằng các dự án bắt buộc này sẽ không được cài đặt trên hệ thống nơi chạy thử nghiệm mà chỉ được tải xuống thư mục thiết lập của dự án nếu chúng chưa được cài đặt cục bộ.
sử dụng_2 đến 3:
Chuyển đổi mã nguồn từ Python 2 sang Python 3 bằng 2to3 trong quá trình xây dựng. Xem Hỗ trợ cả Python 2 và Python 3 với Setuptools để biết thêm chi tiết.
sử dụng_2to3_exclude_fixers :
Theo mặc định, chuyển đổi sử dụng tất cả các sửa lỗi trong lib2to3.fixersgói. Để sử dụng các bộ sửa lỗi bổ sung, tham số use_2to3_fixerscó thể được đặt thành một danh sách tên của các gói chứa bộ sửa lỗi. Để loại trừ người sửa lỗi, tham số use_2to3_exclude_fixerscó thể được đặt thành tên người sửa lỗi được bỏ qua.
sử dụng_2to3_fixers :
Một danh sách các mô-đun để tìm kiếm các bộ sửa chữa bổ sung sẽ được sử dụng trong quá trình chuyển đổi 2to3. Xem Hỗ trợ cả Python 2 và Python 3 với Setuptools để biết thêm chi tiết.
zip_safe:
Cờ boolean (Đúng hoặc Sai) chỉ định xem dự án có thể được cài đặt và chạy an toàn từ tệp zip hay không. Nếu đối số này không được cung cấp, lệnh bdist_egg sẽ phải phân tích tất cả nội dung của dự án của bạn cho các vấn đề có thể xảy ra mỗi khi nó tạo trứng.
Tiện ích mở rộng
Xây dựng một phần mở rộng (chứ không phải là một mô-đun Python thuần túy) phức tạp hơn, vì về cơ bản nó yêu cầu bạn chỉ định các tham số và đối số cần thiết để xây dựng thành công phần mở rộng từ Ccác tệp nguồn. Điều này được thực hiện thông qua ext_modulestừ khóa, không có gì ngoài danh sách các Extensiontrường hợp (có thể nhập từ distutils.core). Các đối số từ khóa được Extensiontrình xây dựng lớp chấp nhận là vectơ đầu vào để chỉ định các bước xây dựng để biên dịch phần mở rộng.
Vì câu hỏi này là về setuptools.setup()cụ thể, tôi sẽ chỉ bao gồm định nghĩa ext_modules, nhưng tài liệu cho Extensionlớp cung cấp đầy đủ chi tiết. Để đầy đủ, đây là danh sách các từ khóa được chấp nhận cho hàm Extensiontạo:
extension_keywords = ('name', 'sources', 'include_dirs',
'define_macros', 'undef_macros',
'library_dirs', 'libraries',
'runtime_library_dirs', 'extra_objects',
'extra_compile_args', 'extra_link_args',
'swig_opts', 'export_symbols', 'depends',
'language')
ext_modules :
Một danh sách các trường hợp mở rộng, mỗi trường hợp mô tả một mô-đun mở rộng. Giả sử bản phân phối của bạn bao gồm một phần mở rộng duy nhất, được gọi là foo và được thực hiện bởi foo.c. Nếu không có hướng dẫn bổ sung nào cho trình biên dịch / trình liên kết là cần thiết, việc mô tả phần mở rộng này khá đơn giản:
from distutils.core import setup, Extension
setup(name='foo',
version='1.0',
ext_modules=[Extension('foo', ['foo.c'])],
)
Linh tinh
Cuối cùng, thậm chí còn có nhiều kwargs có thể được tìm thấy được triển khai trong setuptools.distvà ở nơi khác, nhưng vì một số lý do không bao giờ được thêm vào bất kỳ tài liệu setuptools / distutils chính nào:
tính năng (không dùng nữa):
một tùy chọn ánh xạ từ điển đặt tên cho các đối tượng 'setuptools.Feature'. Các tính năng là một phần của phân phối có thể được bao gồm hoặc loại trừ dựa trên tùy chọn người dùng, phụ thuộc giữa các tính năng và tính khả dụng trên hệ thống hiện tại. Các tính năng bị loại trừ được bỏ qua khỏi tất cả các lệnh thiết lập, bao gồm phân phối nguồn và nhị phân, do đó bạn có thể tạo nhiều bản phân phối từ cùng một cây nguồn.
long_description_content_type (Per "Tạo README thân thiện với PyPI ):
được đặt thành giá trị kiểu Kiểu nội dung được chấp nhận cho đánh dấu tệp README của bạn, chẳng hạn như văn bản / thuần tuý, văn bản / x-rst (đối với reSturationuredText) hoặc văn bản / đánh dấu.
cung cấp_extras (Per PEP566, được liệt kê là "Cung cấp thêm" ):
Một chuỗi chứa tên của một tính năng tùy chọn. Phải là một định danh Python hợp lệ. Có thể được sử dụng để làm cho một phụ thuộc có điều kiện về việc tính năng tùy chọn đã được yêu cầu.