setuptools.setup() вызывает distutils.core.setup() и передает свой собственный **kwargs в качестве единственного параметра, поэтому любые ключевые слова, которые принимает distutils, также будут приняты setuptools. Если мы посмотрим на distutils
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',
)
Большинство из них задокументированы здесь , но некоторые не включены в таблицу: packages , package_dir, package_data , сценарии , obsoletes , proviodes , py_modules и data_files .
Некоторые из них также отсутствуют в кортеже setup_keywords. И если вы наберете setup_keywords, это не похоже на то, что на него действительно ссылаются где-либо ... Но это история для другого дня. Во всяком случае, вот (надеюсь, полный) список.
аргументы ключевого слова distutils.core.setup ()
name:
имя пакета (требуется distutils)
версия:
версия этого выпуска (требуется distutils)
автор:
имя автора пакета (требуется, если сопровождающий не указан)
author_email:
адрес электронной почты автора пакета
сопровождающий:
имя сопровождающего пакета (требуется, если автор не указан)
keeper_email:
адрес электронной почты сопровождающего пакета
url:
домашняя страница для пакета
описание:
краткое, краткое описание пакета
long_description:
более подробное описание пакета, используемое PyPI для создания страницы проекта
download_url:
location где можно загрузить пакет
классификаторы:
a список классификаторов (см .: https://pypi.org/classifiers/)
платформ:
список платформ (также принимает строку. Если запятая разделена, она разбивается на список)
ключевые слова:
список ключевых слов (также принимает строку. Если запятая, она разделяется наlist)
лицензия:
лицензия на пакет (Используйте, только если лицензия не указана в «классификаторах трофеев». См .: Классификаторы)
предоставляет :
Теперь, когда мы можем указать зависимости, мы также должны иметь возможность указать то, что мы предоставляем, которые могут потребовать другие дистрибутивы. Это делается с помощью аргумента ключевого слова provides для setup().
obsoletes :
Пакет может объявить, что он отменяет другие пакеты, используя аргумент ключевого слова obsoletes. Значение для этого похоже на ключевое слово requires: список строк, дающих спецификаторы модуля или пакета. Каждый спецификатор состоит из имени модуля или пакета, за которым может следовать один или несколько определителей версии. Спецификаторы версий указываются в скобках после имени модуля или пакета
scripts :
Скрипты - это файлы, содержащие исходный код Python, предназначенные для запускаиз командной строки. Скрипты не требуют, чтобы Distutils делал что-то очень сложное. Единственная умная особенность заключается в том, что если первая строка скрипта начинается с #! и содержит слово «python», Distutils будет корректировать первую строку для ссылки на текущее местоположение интерпретатора. По умолчанию он заменяется текущим местоположением переводчика. Опция -- исполняемый (или -e) позволяет явно переопределить путь к интерпретатору.
Опция scripts просто представляет собой список файлов, которые будут обрабатываться таким образом. Из скрипта установки PyXML:
setup(...,
scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
)
пакетов :
PaДанные ckage могут быть добавлены в пакеты с помощью ключевого аргумента package_data для функции setup(). Значение должно быть отображением имени пакета в список относительных имен путей, которые должны быть скопированы в пакет. Пути интерпретируются как относящиеся к каталогу, содержащему пакет (при необходимости используется информация из сопоставления package_dir);то есть файлы должны быть частью пакета в исходных каталогах. Они также могут содержать шаблоны glob.
package_dir :
Если вы используете другое соглашение для размещения вашего исходного каталога, это не проблема: вам просто нужно указать опцию package_dir, чтобы сообщить Distutils о вашем соглашении. Например, допустим, вы храните весь исходный код Python в lib, поэтому модули в «корневом пакете» (т. Е. Не в любом пакете вообще) находятся в lib, а модули в пакете foo - в lib/foo, и так далее. Тогда вы бы поместили
package_dir = {'': 'lib'}
в ваш скрипт установки. Ключи этого словаря являются именами пакетов, а пустое имя пакета обозначает корневой пакет. Значения - это имена каталогов относительно корня вашего дистрибутива. В этом случае, когда вы говорите packages = ['foo'], вы обещаете, что файл lib/foo/__init__.py существует.
Другое возможное соглашение - поместить пакет foo прямо в lib, пакет foo.barв lib/bar и т. д. Это будет записано в сценарии установки как запись
package_dir = {'foo': 'lib'}
A package: dir в словаре package_dir неявно применяется ко всем пакетам ниже пакета, поэтому случай foo.barавтоматически обрабатывается здесь. В этом примере наличие packages = ['foo', 'foo.bar'] заставляет Distutils искать lib/__init__.py и lib/bar/__init__.py. (Имейте в виду, что хотя package_dir применяется рекурсивно, вы должны явно перечислить все пакеты в пакетах: Distutils не будет рекурсивно сканировать дерево исходных текстов в поисках любого каталога с файлом __init__.py.)
package_data :
Данные пакета могут быть добавлены в пакеты с помощью ключевого аргумента package_data для функции setup(). Значение должно быть отображением имени пакета в список относительных имен путей, которые должны быть скопированы в пакет. Пути интерпретируются как относящиеся к каталогу, содержащему пакет (при необходимости используется информация из сопоставления package_dir);то есть файлы, как ожидается, будут частью пакета в исходных каталогах.
py_modules :
Для дистрибутива небольшого модуля:Вы можете предпочесть перечислить все модули, а не перечислять пакеты, особенно в случае отдельного модуля, который входит в «корневой пакет» (т. е. вообще никакого пакета).
py_modules = ['foo.py']
Вот немного более сложный пример:
py_modules = ['mod1', 'pkg.mod2']
Здесь описываются два модуля, один из которых находится в «корневом» пакете, а другой - в pkg. Опять же, компоновка пакета / каталога по умолчанию подразумевает, что эти два модуля можно найти в mod1.py и pkg/mod2.py, а также существует pkg/__init__.py. И снова, вы можете переопределить соответствие пакета / каталога, используя опцию package_dir.
data_files :
Опция data_files можетиспользоваться для указания дополнительных файлов, необходимых для распространения модуля: файлов конфигурации, каталогов сообщений, файлов данных, всего, что не вписывается в предыдущие категории.
data_files указывает последовательность пар (directory, files) вследующим образом:
setup(...,
data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
('config', ['cfg/data.cfg'])],
)
Каждая пара (directory, files) в последовательности указывает каталог установки и файлы для установки там. Каждое имя файла в файлах интерпретируется относительно сценария setup.py.
setuptools.setup () ключевое слово arguments
Thereеще больше аргументов, которые setuptools.setup() примет, помимо тех, которые используются distutils.
Хотя это 'под названием «Новые и измененные ключевые слова установки» (что для меня предполагает журнал изменений версии), во вступительном тексте говорится, что это «ключевые аргументы для setup () [которые] добавляются или изменяются с помощью setuptools», поэтому ясчитаю, что ссылка на самом деле предоставляет полный список. Я добавлю это здесь для полноты.
include_package_data:
Если установлено значение True, это заставляет setuptools автоматически включать любые файлы данных, которые он находит в ваших каталогах пакетов, указанных в вашем манифесте. в файле. Для получения дополнительной информации см. Раздел «Включение файлов данных» ниже.
exclude_package_data:
Словарь сопоставляет имена пакетов со списками шаблонов глобусов, которые следует исключить из вашего пакета. каталоги. Вы можете использовать это, чтобы обрезать любые лишние файлы, включенные в include_package_data. Полное описание и примеры см. В разделе «Включение файлов данных» ниже.
package_data:
Словарь, сопоставляющий имена пакетов со списками шаблонов glob. Полное описание и примеры приведены в разделе «Включение файлов данных» ниже. Вам не нужно использовать эту опцию, если вы используете include_package_data, если только вам не нужно добавлять, например, файлы, которые создаются вашим сценарием установки и процессом сборки. (И поэтому не находятся в управлении исходным кодом или являются файлами, которые вы не хотите включать в исходный дистрибутив.)
zip_safe:
Логическое значение (True илиFalse) флаг, указывающий, можно ли безопасно установить и запустить проект из zip-файла. Если этот аргумент не указан, команда bdist_egg должна будет анализировать все содержимое вашего проекта на предмет возможных проблем при каждом построении яйца.
install_requires:
Aстрока или список строк, определяющих, какие другие дистрибутивы должны быть установлены, когда этот. См. Ниже раздел «Объявление зависимостей» для получения подробной информации и примеров формата этого аргумента.
entry_points:
Словарь сопоставляет имена групп точек входа со строками или спискамиСтроки, определяющие точки входа. Точки входа используются для поддержки динамического обнаружения сервисов или плагинов, предоставляемых проектом. Посмотрите Динамическое Обнаружение Сервисов и Плагинов для деталей и примеров формата этого аргумента. Кроме того, это ключевое слово используется для поддержки автоматического создания сценариев.
extras_require:
Словарь, сопоставляющий имена «extras» (дополнительные функции вашего проекта) со строкамиили списки строк, указывающие, какие другие дистрибутивы должны быть установлены для поддержки этих функций. См. Ниже раздел об объявлении зависимостей для получения подробной информации и примеров формата этого аргумента.
python_requires:
Строка, соответствующая спецификатору версии (как определено в PEP440) для версии Python, используемой для указания Requ-Python, определенного в PEP 345.
setup_requires:
Строка или список строк, указывающих, что нужно другим дистрибутивамприсутствовать для запуска сценария установки. setuptools попытается получить их (даже до того, как загрузить их с помощью EasyInstall) перед обработкой остальной части сценария установки или команд. Этот аргумент необходим, если вы используете расширения distutils как часть процесса сборки;например, расширения, которые обрабатывают аргументы setup () и превращают их в файлы метаданных EGG-INFO. (Примечание: проекты, перечисленные в setup_requires, НЕ будут автоматически установлены в системе, где выполняется сценарий установки. Они просто загружаются в каталог ./.eggs, если они уже не доступны локально. Если вы хотите, чтобы они были установленыКроме того, что он доступен при запуске сценария установки, вы должны добавить его в install_requires и setup_requires.)
dependency_links:
Aсписок строк с именами URL для поиска при удовлетворении зависимостей. Эти ссылки будут использоваться при необходимости для установки пакетов, указанных в setup_requires или tests_require. Они также будут записаны в метаданные яйца для использования такими инструментами, как EasyInstall, для использования при установке файла .egg.
namespace_packages:
Список строк с именами«пакеты пространства имен» проекта. Пакет пространства имен - это пакет, который может быть разбит на несколько дистрибутивов проекта. Например, пакет zope Zope 3 является пакетом пространства имен, поскольку такие подпакеты, как zope.interface и zope.publisher, могут распространяться отдельно. Система времени выполнения egg может автоматически объединять такие подпакеты в один родительский пакет во время выполнения, если вы объявляете их в каждом проекте, который содержит любые подпакеты пакета пространства имен, и до тех пор, пока init пакета пространства имен. py не содержит никакого кода, кроме объявления пространства имен. См. Ниже раздел «Пакеты пространства имен» для получения дополнительной информации.
test_suite:
Строка с именем подкласса unittest.TestCase (или пакета или модуля, содержащего один или несколько изих, или метод такого подкласса), или именование функции, которая может быть вызвана без аргументов и возвращает unittest.TestSuite. Если именованный набор является модулем, и модуль имеет функцию Additional_tests (), он вызывается, и результаты добавляются в выполняемые тесты. Если названный набор является пакетом, любые субмодули и подпакеты рекурсивно добавляются в общий набор тестов. Указание этого аргумента позволяет использовать команду test для запуска указанного набора тестов, например, через тест setup.py. Для получения более подробной информации см. Раздел о тестовой команде ниже.
tests_require:
Если тестам вашего проекта требуется один или несколько дополнительных пакетов помимо тех, которые необходимы для его установки, выможете использовать эту опцию, чтобы указать их. Это должна быть строка или список строк, указывающих, какие другие дистрибутивы должны присутствовать для запуска тестов пакета. Когда вы запускаете тестовую команду, setuptools будет пытаться получить их (даже до загрузки их с помощью EasyInstall). Обратите внимание, что эти необходимые проекты не будут установлены в системе, в которой выполняются тесты, а будут загружены только в каталог установки проекта, если они еще не установлены локально.
test_loader:
Если вы хотите использовать другой способ поиска тестов, отличающийся от того, который обычно использует setuptools, вы можете указать имя модуля и имя класса в этом аргументе. Именованный класс должен быть инстанцируемым без аргументов, а его экземпляры должны поддерживать метод loadTestsFromNames (), как это определено в классе TestLoader модуля unittest Python. Setuptools передаст только одно тестовое «имя» в аргументе names: значение, предоставленное для аргумента test_suite. Указанный вами загрузчик может интерпретировать эту строку по своему усмотрению, поскольку нет ограничений на то, что может содержаться в строке test_suite. Имя модуля и имя класса должны быть разделены:. Значением этого аргумента по умолчанию является «setuptools.command.test: ScanningLoader». Если вы хотите использовать стандартное поведение unittest, вы можете вместо этого указать в качестве аргумента test_loader «unittest: TestLoader». Это предотвратит автоматическое сканирование субмодулей и подпакетов. Указанный здесь модуль и класс могут содержаться в другом пакете, если вы используете опцию tests_require, чтобы гарантировать, что пакет, содержащий класс загрузчика, доступен при выполнении команды test.
eager_resources:
Список строкименование ресурсов, которые должны быть извлечены вместе, если какой-либо из них необходим, или если какие-либо расширения C, включенные в проект, импортируются. Этот аргумент полезен только в том случае, если проект будет установлен в виде zip-файла, и необходимо, чтобы все перечисленные ресурсы были извлечены в файловую систему как единое целое. Ресурсы, перечисленные здесь, должны быть путями, разделенными '/', относительно корня источника, поэтому, чтобы перечислить ресурс foo.png в пакете bar.baz, вы должны включить строку bar / baz / foo.png в этот аргумент. Если вам нужно получать ресурсы только по одному или у вас нет расширений C, которые обращаются к другим файлам в проекте (например, к файлам данных или общим библиотекам), вам, вероятно, НЕ нужен этот аргумент, и вы не должны связываться с ним. с этим. Для получения дополнительной информации о том, как работает этот аргумент, см. Ниже раздел «Автоматическое извлечение ресурсов».
use_2to3:
Преобразование исходного кода из Python 2 в Python 3 с помощью 2to3во время процесса сборки. Дополнительные сведения см. В разделе «Поддержка Python 2 и Python 3 с помощью Setuptools».
convert_2to3_doctests:
Список исходных файлов doctest, которые необходимо преобразовать с помощью 2to3. Дополнительные сведения см. В разделе «Поддержка Python 2 и Python 3 с помощью Setuptools».
use_2to3_fixers :
Список модулей для поиска дополнительных исправлений дляиспользоваться во время преобразования 2to3. Дополнительные сведения см. В разделе «Поддержка Python 2 и Python 3 с помощью Setuptools».
use_2to3_exclude_fixers :
По умолчанию при преобразовании используются все исправления вlib2to3.fixers упаковка. Чтобы использовать дополнительные средства исправления, для параметра use_2to3_fixers можно задать список имен пакетов, содержащих средства исправления. Чтобы исключить фиксаторы, для параметра use_2to3_exclude_fixers можно указать пропускаемые имена фиксаторов.
project_urls:
Произвольное сопоставление имен URL с гиперссылками, что позволяетрасширяемая документация о том, где можно найти различные ресурсы, отличные от простых опций url и download_url.
Расширения
Создание расширения (а не просто модуль Python) более сложный, так как он требует указания параметров и аргументов для успешного построения расширения из исходных файлов C. Это делается с помощью ключевого слова ext_modules, которое представляет собой не что иное, как список Extension экземпляров (импортируемых из distutils.core). Аргументы ключевого слова, принятые конструктором класса Extension, являются входным вектором для указания шагов сборки для компиляции расширения.
Поскольку этот вопрос конкретно касается setuptools.setup(), я включу только определение ext_modules, но документация для Extension класса предоставляет полную информацию. Для полноты, это список допустимых ключевых слов для конструктора Extension:
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 :
Список экземпляров Extension, каждыйиз которых описывает один модуль расширения. Предположим, что ваш дистрибутив включает одно расширение, называемое foo и реализованное foo.c. Если никаких дополнительных инструкций для компилятора / компоновщика не требуется, описание этого расширения довольно просто:
from distutils.core import setup, Extension
setup(name='foo',
version='1.0',
ext_modules=[Extension('foo', ['foo.c'])],
)
Наконец, есть еще больше kwargs, которые можно найти реализованными в setuptools.dist и в других местах, но по какой-то причине никогда не были добавлены в основную документацию setuptools / distutils:
provide_extras (Per PEP566, указан как «Обеспечивает-Extra» ):
Строка, содержащая имя дополнительной функции. Должен быть действительным идентификатором Python. Может использоваться, чтобы сделать зависимость зависимой от того, была ли запрошена дополнительная функция.
long_description_content_type (Per "Создание удобного для PyPI README ):
установите в качестве допустимого значения стиля Content-Type для разметки файла README, например text / plain, text / x-rst (для reStructuredText) или text / markdown.
функции (устарело):
словарь, отображающий имена опций для объектов 'setuptools.Feature'. Компоненты - это часть дистрибутива, которая может быть включена или исключена на основе пользовательских параметров, межфункциональных зависимостей и доступности в текущей системе. Исключенные функции опущены во всех командах установки, включая исходные и бинарные дистрибутивы, поэтому вы можете создавать несколько дистрибутивов из одного и того же исходного дерева.