9. Довідник з API

Дивись також

Нові та змінені аргументи setup.py в setuptools

Проект setuptools додає нові можливості до функції setup та інших інтерфейсів API, робить API узгодженим для різних версій Python, і тому рекомендується замість безпосереднього використання distutils.

Примітка

Цей документ зберігається лише до тих пір, поки документація setuptools за адресою https://setuptools.readthedocs.io/en/latest/setuptools.html окремо не охопить всю відповідну інформацію, яка зараз включена тут.

9.1. distutils.core — Основні функції Distutils

Модуль distutils.core — це єдиний модуль, який потрібно встановити для використання Distutils. Він забезпечує setup() (який викликається зі сценарію налаштування). Опосередковано надає клас distutils.dist.Distribution і distutils.cmd.Command.

distutils.core.setup(arguments)

Основна функція «зроби все», яка робить майже все, що ви можете попросити від методу Distutils.

Функція налаштування приймає велику кількість аргументів. Вони наведені в наступній таблиці.

назва аргументу	значення	типу
ім’я	Назва пакета	рядок
версія	номер версії пакета; див. distutils.version	рядок
опис	Один рядок, що описує пакет	рядок
довгий_опис	Довший опис пакету	рядок
автор	Ім’я автора пакета	рядок
email_автора	Адреса електронної пошти автора пакета	рядок
супроводжувач	Ім’я поточного супроводжуючого, якщо воно відрізняється від автора. Зауважте, що якщо супроводжувач надано, distutils використовуватиме його як автора у PKG-INFO	рядок
email_maintainer_email	Електронна адреса поточного супроводжуючого, якщо вона відрізняється від автора	рядок
url	URL-адреса пакета (домашня сторінка)	рядок
URL-адреса_завантаження	URL-адреса для завантаження пакета	рядок
пакети	Список пакетів Python, якими distutils працюватиме	список рядків
py_modules	Список модулів Python, якими distutils працюватиме	список рядків
скрипти	Список автономних файлів сценаріїв, які потрібно створити та встановити	список рядків
ext_modules	Список розширень Python для створення	список екземплярів distutils.core.Extension
класифікатори	Список категорій для пакета	список рядків; дійсні класифікатори перераховані на PyPI.
distclass	клас Distribution для використання	підклас distutils.core.Distribution
script_name	Назва сценарію setup.py - за умовчанням sys.argv[0]	рядок
script_args	Аргументи для налаштування сценарію	список рядків
опції	параметри за замовчуванням для сценарію налаштування	словник
ліцензія	Ліцензія на пакет	рядок
ключові слова	Описові метадані див. PEP 314	список рядків або рядок, розділений комами
платформи		список рядків або рядок, розділений комами
cmdclass	Відображення назв команд на підкласи Command	словник
файли_даних	Список файлів даних для встановлення	список
package_dir	Відображення пакета в іменах каталогу	словник

distutils.core.run_setup(script_name[, script_args=None, stop_after='run'])

Запустіть сценарій налаштування в дещо контрольованому середовищі та поверніть екземпляр distutils.dist.Distribution, який керує діями. Це корисно, якщо вам потрібно дізнатися метадані розповсюдження (передані як аргументи ключового слова від script до setup()), або вміст конфігураційних файлів чи командного рядка.

script_name — це файл, який читатиметься та запускатиметься за допомогою exec(). sys.argv[0] буде замінено на script на час виклику. script_args — це список рядків; якщо надано, sys.argv[1:] буде замінено на script_args протягом тривалості виклику.

stop_after повідомляє setup(), коли зупинити обробку; можливі значення:

значення	опис
у цьому	Зупиніться після того, як екземпляр Distribution буде створено та заповнено ключовими аргументами для setup()
конфігурація	Зупинити після аналізу конфігураційних файлів (і їх даних, збережених в екземплярі Distribution)
командний рядок	Зупиніться після аналізу командного рядка (sys.argv[1:] або script_args) (і даних, збережених в екземплярі Distribution).
бігти	Зупиніться після виконання всіх команд (так само, якби setup() було викликано звичайним способом). Це значення за умовчанням.

Крім того, модуль distutils.core відкрив низку класів, які живуть в інших місцях.

• Extension з distutils.extension

• Command з distutils.cmd

• Distribution з distutils.dist

Нижче наведено короткий опис кожного з них, але повну довідку див. у відповідному модулі.

class distutils.core.Extension

Клас Extension описує один модуль розширення C або C++ у сценарії налаштування. Він приймає такі ключові аргументи у своєму конструкторі:

назва аргументу	значення	типу
ім’я	повна назва розширення, включаючи будь-які пакети — тобто. не ім’я файлу чи шлях, а ім’я Python із крапками	рядок
джерела	список імен вихідних файлів відносно кореня розповсюдження (де знаходиться сценарій встановлення), у формі Unix (розділені скісною рискою) для переносимості. Вихідними файлами можуть бути C, C++, SWIG (.i), файли ресурсів для певної платформи або будь-які інші файли, які розпізнаються командою build_ext як джерело для розширення Python.	список рядків
include_dirs	список каталогів для пошуку файлів заголовків C/C++ (у формі Unix для переносимості)	список рядків
define_macros	список макросів для визначення; кожен макрос визначається за допомогою 2-кортежу (ім’я, значення), де value є або рядком для його визначення, або None, щоб визначити його без певного значення (еквівалент # визначте FOO у джерелі або -DFOO в командному рядку компілятора Unix C)	список кортежів
undef_macros	список макросів для явного скасування визначення	список рядків
library_dirs	список каталогів для пошуку бібліотек C/C++ під час підключення	список рядків
бібліотеки	список імен бібліотек (не імен файлів чи шляхів), з якими потрібно посилатися	список рядків
каталоги_бібліотеки_запуску	список каталогів для пошуку бібліотек C/C++ під час виконання (для спільних розширень це час завантаження розширення)	список рядків
додаткові_об’єкти	список додаткових файлів, з якими можна зв’язатися (наприклад, об’єктні файли, які не передбачаються «джерелами», статична бібліотека, яку необхідно вказати явно, двійкові файли ресурсів тощо)	список рядків
extra_compile_args	будь-яка додаткова інформація про платформу та компілятор для використання під час компіляції вихідних файлів у «джерелах». Для платформ і компіляторів, де командний рядок має сенс, це зазвичай список аргументів командного рядка, але для інших платформ це може бути будь-що.	список рядків
extra_link_args	будь-яка додаткова інформація про платформу та компілятор, яку можна використовувати під час зв’язування об’єктних файлів разом для створення розширення (або для створення нового статичного інтерпретатора Python). Інтерпретація подібна до „extra_compile_args“.	список рядків
export_symbols	список символів, які потрібно експортувати зі спільного розширення. Не використовується на всіх платформах і не є загалом необхідним для розширень Python, які зазвичай експортують лише один символ: init + extension_name.	список рядків
залежить	список файлів, від яких залежить розширення	список рядків
мову	мова розширення (тобто 'c', 'c++', 'objc'). Буде виявлено з вихідних розширень, якщо їх не надано.	рядок
необов’язково	вказує, що помилка збірки в розширенні не повинна переривати процес збірки, а просто пропускати розширення.	логічне значення

Змінено в версії 3.8: В Unix розширення C більше не пов’язані з libpython, за винятком Android і Cygwin.

class distutils.core.Distribution

Distribution описує, як створити, встановити та запакувати програмний пакет Python.

Перегляньте функцію setup(), щоб переглянути список ключових аргументів, які приймає конструктор розподілу. setup() створює екземпляр Distribution.

Змінено в версії 3.7: Distribution тепер попереджає, якщо поля класифікатори, ключові слова та платформи не вказані як список або рядок.

class distutils.core.Command

Клас Command (точніше, екземпляр одного з його підкласів) реалізує одну команду distutils.

9.2. distutils.ccompiler — базовий клас CCompiler

Цей модуль надає абстрактний базовий клас для класів CCompiler. Екземпляр CCompiler можна використовувати для всіх кроків компіляції та зв’язування, необхідних для створення одного проекту. Надаються методи для встановлення опцій для компілятора — визначень макросів, включення каталогів, шляхів посилань, бібліотек тощо.

Цей модуль забезпечує такі функції.

distutils.ccompiler.gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)

Створення параметрів компонувальника для пошуку каталогів бібліотек і зв’язування з певними бібліотеками. libraries і library_dirs — це, відповідно, списки імен бібліотек (а не імен файлів!) і каталогів пошуку. Повертає список параметрів командного рядка, придатних для використання з деяким компілятором (залежно від двох переданих рядків формату).

distutils.ccompiler.gen_preprocess_options(macros, include_dirs)

Згенеруйте параметри попереднього процесора C (-D, -U, -I), які використовуються принаймні двома типами компіляторів: типовим компілятором Unix і Visual C++. макроси — це звичайна річ, список 1- або 2-кортежів, де (name,) означає undefine (-U) макрос name, а (name, значення) означає визначення (-D) назви макросу на значення. include_dirs — це лише список імен каталогів, які потрібно додати до шляху пошуку файлу заголовка (-I). Повертає список параметрів командного рядка, придатних для компіляторів Unix або Visual C++.

distutils.ccompiler.get_default_compiler(osname, platform)

Визначте компілятор за замовчуванням для даної платформи.

osname має бути одним із стандартних імен ОС Python (тобто тих, які повертає os.name), а platform — загальне значення, яке повертає sys.platform для відповідної платформи.

Значеннями за замовчуванням є os.name і sys.platform, якщо параметри не вказано.

distutils.ccompiler.new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)

Фабрична функція для створення екземпляра деякого підкласу CCompiler для наданої комбінації платформа/компілятор. plat за замовчуванням має os.name (наприклад, 'posix', 'nt'), а compiler за замовчуванням використовує компілятор за замовчуванням для цієї платформи. Наразі підтримуються лише 'posix' і 'nt', а компіляторами за замовчуванням є «традиційний інтерфейс Unix» (UnixCCompiler клас) і Visual C++ (MSVCCompiler клас ). Зауважте, що цілком можливо запросити об’єкт компілятора Unix під Windows і об’єкт компілятора Microsoft під Unix — якщо ви вказуєте значення для compiler, plat ігнорується.

distutils.ccompiler.show_compilers()

Надрукувати список доступних компіляторів (використовується параметрами --help-compiler для build, build_ext, build_clib).

class distutils.ccompiler.CCompiler([verbose=0, dry_run=0, force=0])

Абстрактний базовий клас CCompiler визначає інтерфейс, який має бути реалізований реальними класами компілятора. Клас також має деякі корисні методи, які використовуються кількома класами компілятора.

Основна ідея класу абстракції компілятора полягає в тому, що кожен екземпляр можна використовувати для всіх етапів компіляції/зв’язування в створенні одного проекту. Таким чином, атрибути, загальні для всіх цих етапів компіляції та зв’язування — включають каталоги, макроси для визначення, бібліотеки для зв’язування тощо — є атрибутами примірника компілятора. Щоб уможливити варіативність у тому, як обробляються окремі файли, більшість із цих атрибутів можна змінювати для кожної компіляції чи кожного посилання.

Конструктор для кожного підкласу створює екземпляр об’єкта Compiler. Прапори: verbose (показати докладний вихід), dry_run (фактично не виконувати кроки) і force (перебудувати все, незалежно від залежностей). Усі ці прапорці за замовчуванням мають значення 0 (вимкнено). Зауважте, що ви, мабуть, не бажаєте створювати екземпляр CCompiler або один із його підкласів напряму - використовуйте натомість фабричну функцію distutils.CCompiler.new_compiler().

Наступні методи дозволяють вручну змінювати параметри компілятора для екземпляра класу Compiler.

add_include_dir(dir)

Додайте dir до списку каталогів, у яких здійснюватиметься пошук файлів заголовків. Компілятор отримує вказівку шукати каталоги в тому порядку, в якому вони надаються послідовними викликами add_include_dir().

set_include_dirs(dirs)

Встановіть список каталогів, у яких здійснюватиметься пошук, як dirs (список рядків). Перевизначає будь-які попередні виклики add_include_dir(); наступні виклики add_include_dir() додають до списку, переданого set_include_dirs(). Це не впливає на список каталогів стандартного включення, які компілятор може шукати за замовчуванням.

add_library(libname)

Додайте libname до списку бібліотек, які будуть включені в усі посилання, керовані цим об’єктом компілятора. Зауважте, що libname має *не* бути назвою файлу, що містить бібліотеку, а назвою самої бібліотеки: фактичне ім’я файлу буде визначено компонувальником, компілятором або класом компілятора (залежно від платформа).

Пов’язувач отримає вказівку зв’язувати бібліотеки в тому порядку, в якому вони були надані в add_library() та/або set_libraries(). Цілком допустимо дублювати імена бібліотек; компонувальник отримає вказівку створити зв’язок із бібліотеками стільки разів, скільки вони згадуються.

set_libraries(libnames)

Встановіть список бібліотек, які будуть включені в усі посилання, керовані цим об’єктом компілятора, як libnames (список рядків). Це не впливає на стандартні системні бібліотеки, які компонувальник може включати за замовчуванням.

add_library_dir(dir)

Додайте dir до списку каталогів, у яких здійснюватиметься пошук бібліотек, указаних у add_library() і set_libraries(). Пов’язувач отримає вказівку шукати бібліотеки в тому порядку, в якому вони надані в add_library_dir() та/або set_library_dirs().

set_library_dirs(dirs)

Встановіть список каталогів пошуку бібліотек на dirs (список рядків). Це не впливає на будь-який стандартний шлях пошуку бібліотеки, який компонувальник може шукати за замовчуванням.

add_runtime_library_dir(dir)

Додайте dir до списку каталогів, у яких здійснюватиметься пошук спільних бібліотек під час виконання.

set_runtime_library_dirs(dirs)

Встановіть список каталогів для пошуку спільних бібліотек під час виконання на dirs (список рядків). Це не впливає на будь-який стандартний шлях пошуку, який компонувальник під час виконання може шукати за замовчуванням.

define_macro(name[, value=None])

Визначте макрос препроцесора для всіх компіляцій, керованих цим об’єктом компілятора. Додатковий параметр value має бути рядком; якщо він не наданий, то макрос буде визначено без явного значення, і точний результат залежить від використовуваного компілятора.

undefine_macro(name)

Скасуйте визначення макросу препроцесора для всіх компіляцій, керованих цим об’єктом компілятора. Якщо той самий макрос визначено define_macro() і не визначено undefine_macro(), останній виклик має перевагу (включно з кількома перевизначеннями або невизначеннями). Якщо макрос перевизначено/не визначено на основі кожної компіляції (тобто під час виклику compile()), то він має перевагу.

add_link_object(object)

Додайте об’єкт до списку об’єктних файлів (або аналогів, таких як бібліотечні файли з явною назвою або вихідні дані «компіляторів ресурсів»), які будуть включені в кожне посилання, кероване цим об’єктом компілятора.

set_link_objects(objects)

Встановіть список об’єктних файлів (або аналогів), які будуть включені до кожного посилання на об’єкти. Це не впливає на будь-які стандартні об’єктні файли, які компонувальник може включати за замовчуванням (наприклад, системні бібліотеки).

Наступні методи реалізують методи для автоматичного визначення параметрів компілятора, надаючи деякі функції, подібні до GNU autoconf.

detect_language(sources)

Визначити мову певного файлу або списку файлів. Використовує атрибути екземпляра language_map (словник) і language_order (список) для виконання завдання.

find_library_file(dirs, lib[, debug=0])

Знайдіть у вказаному списку каталогів файл статичної або спільної бібліотеки lib і поверніть повний шлях до цього файлу. Якщо debug має значення true, знайдіть версію для налагодження (якщо це має сенс на поточній платформі). Повертає None, якщо lib не знайдено в жодному з указаних каталогів.

has_function(funcname[, includes=None, include_dirs=None, libraries=None, library_dirs=None])

Повертає логічне значення, яке вказує, чи підтримується funcname на поточній платформі. Необов’язкові аргументи можна використовувати для розширення середовища компіляції шляхом надання додаткових файлів і шляхів, а також бібліотек і шляхів.

library_dir_option(dir)

Повернути опцію компілятора, щоб додати dir до списку каталогів, у яких шукаються бібліотеки.

library_option(lib)

Поверніть опцію компілятора, щоб додати lib до списку бібліотек, пов’язаних із спільною бібліотекою або виконуваним файлом.

runtime_library_dir_option(dir)

Поверніть опцію компілятора, щоб додати dir до списку каталогів, у яких шукаються бібліотеки середовища виконання.

set_executables(**args)

Визначте виконувані файли (і параметри для них), які будуть запущені для виконання різних етапів компіляції. Точний набір виконуваних файлів, який можна вказати тут, залежить від класу компілятора (через атрибут класу „executables“), але більшість матиме:

атрибут	опис
компілятор	компілятор C/C++
linker_so	компонувальник, який використовується для створення спільних об’єктів і бібліотек
linker_exe	компонувальник, який використовується для створення двійкових виконуваних файлів
архіватор	творець статичної бібліотеки

На платформах із командним рядком (Unix, DOS/Windows) кожен із них є рядком, який буде розділено на ім’я виконуваного файлу та (необов’язковий) список аргументів. (Поділ рядка виконується подібно до того, як працюють оболонки Unix: слова розділені пробілами, але лапки та зворотні косі риски можуть замінити це. Див. distutils.util.split_quoted().)

Наступні методи викликають етапи процесу побудови.

compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])

Скомпілюйте один або кілька вихідних файлів. Створює об’єктні файли (наприклад, перетворює файл .c на файл .o.)

джерела мають бути списком імен файлів, швидше за все файлів C/C++, але насправді все, що може оброблятися певним компілятором і класом компілятора (наприклад, MSVCCompiler може обробляти файли ресурсів у джерелах) . Повертає список імен файлів об’єктів, по одному на ім’я вихідного файлу в джерелах. Залежно від реалізації, не всі вихідні файли обов’язково будуть скомпільовані, але будуть повернуті всі відповідні імена файлів об’єктів.

Якщо задано output_dir, об’єктні файли буде розміщено під ним, зберігаючи при цьому їхній початковий компонент шляху. Тобто foo/bar.c зазвичай компілюється до foo/bar.o (для реалізації Unix); якщо output_dir є build, тоді він скомпілюється до build/foo/bar.o.

макроси, якщо вказано, мають бути списком визначень макросів. Визначення макросу – це 2-кортеж (ім’я, значення)" або 1-кортеж ``(ім’я,). Перший визначає макрос; якщо значенням є None, макрос визначено без явного значення. Випадок 1-кортежу не визначає макрос. Пізніші визначення/перевизначення/невизначення мають пріоритет.

include_dirs, якщо задано, має бути списком рядків, каталогів, які потрібно додати до шляху пошуку файлів за замовчуванням лише для цієї компіляції.

debug є логічним; якщо істина, компілятор отримає вказівку вивести символи налагодження в (або поруч) з об’єктним файлом(ами).

extra_preargs і extra_postargs залежать від реалізації. На платформах, які мають поняття командного рядка (наприклад, Unix, DOS/Windows), це, швидше за все, списки рядків: додаткові аргументи командного рядка для додавання перед/до командного рядка компілятора. На інших платформах зверніться до документації класу реалізації. У будь-якому випадку, вони призначені як аварійний люк у тих випадках, коли структура абстрактного компілятора не вирішує проблеми.

depends, якщо вказано, це список імен файлів, від яких залежать усі цілі. Якщо вихідний файл старіший за будь-який файл у залежностях, вихідний файл буде перекомпільовано. Це підтримує відстеження залежностей, але лише з грубою деталізацією.

Викликає CompileError у разі помилки.

create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])

Зв’яжіть купу матеріалів разом, щоб створити файл статичної бібліотеки. «Кучка речей» складається зі списку об’єктних файлів, наданих як objects, додаткових об’єктних файлів, наданих у add_link_object() та/або set_link_objects(), бібліотек, наданих у add_library() та/або set_libraries(), а також бібліотеки, що надаються як бібліотеки (якщо такі є).

output_libname має бути назвою бібліотеки, а не назвою файлу; ім’я файлу буде виведено з назви бібліотеки. output_dir - це каталог, куди буде розміщено файл бібліотеки.

debug є логічним; якщо true, інформація про налагодження буде включена в бібліотеку (зауважте, що на більшості платформ це має значення на етапі компіляції: прапор debug включено тут лише для узгодженості).

target_lang — цільова мова, для якої компілюються ці об’єкти. Це дозволяє обробку певних мов у певний час зв’язування.

Викликає LibError у разі помилки.

link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

Пов’яжіть купу матеріалів разом, щоб створити виконуваний файл або файл спільної бібліотеки.

«Кучка речей» складається зі списку об’єктних файлів, які надаються як об’єкти. вихідна_назва_файлу має бути назвою файлу. Якщо вказано output_dir, output_filename є відносно нього (тобто output_filename може надати компоненти каталогу, якщо це необхідно).

libraries — це список бібліотек, з якими можна посилатися. Це назви бібліотек, а не назви файлів, оскільки вони перекладаються на назви файлів залежно від платформи (наприклад, foo стає libfoo.a в Unix і foo.lib в DOS/ вікна). Однак вони можуть містити компонент каталогу, що означає, що компонувальник шукатиме в цьому конкретному каталозі, а не шукатиме у всіх звичайних місцях.

library_dirs, якщо надається, має бути списком каталогів для пошуку бібліотек, які були вказані як голі імена бібліотек (тобто без компонента каталогу). Вони є поверх системних стандартних і тих, що надаються до add_library_dir() та/або set_library_dirs(). runtime_library_dirs — це список каталогів, які будуть вбудовані в спільну бібліотеку та використовуватимуться для пошуку інших спільних бібліотек, від яких *вона* залежить під час виконання. (Це може бути актуальним лише для Unix.)

export_symbols — це список символів, які буде експортовано спільною бібліотекою. (Здається, це стосується лише Windows.)

debug — це те саме, що стосується compile() і create_static_lib(), з тією невеликою різницею, що це насправді має значення на більшості платформ (на відміну від create_static_lib(), який переважно містить прапорець debug заради форми).

extra_preargs і extra_postargs схожі на compile() (звісно, за винятком того, що вони надають аргументи командного рядка для конкретного використовуваного компонувальника).

target_lang — цільова мова, для якої компілюються ці об’єкти. Це дозволяє обробку певних мов у певний час зв’язування.

Викликає LinkError у разі помилки.

link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])

Посилання на виконуваний файл. output_progname — це ім’я виконуваного файлу, тоді як objects — це список імен файлів об’єктів для посилань. Інші аргументи такі ж, як і для методу link().

link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

Пов’язати спільну бібліотеку. output_libname — це ім’я вихідної бібліотеки, тоді як objects — це список імен файлів об’єктів для посилань. Інші аргументи такі ж, як і для методу link().

link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

Пов’язати спільний об’єкт. output_filename — це ім’я спільного об’єкта, який буде створено, тоді як objects — це список імен файлів об’єктів для посилань. Інші аргументи такі ж, як і для методу link().

preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])

Попередньо обробіть один вихідний файл C/C++, названий у source. Вихідні дані буде записано у файл з назвою output_file або stdout, якщо output_file не надано. макроси — це список визначень макросів, як для compile(), який доповнює набір макросів за допомогою define_macro() і undefine_macro(). include_dirs — це список імен каталогів, які буде додано до списку за замовчуванням так само, як add_include_dir().

Викликає PreprocessError у разі помилки.

Наступні службові методи визначені класом CCompiler для використання різними конкретними підкласами.

executable_filename(basename[, strip_dir=0, output_dir=''])

Повертає назву виконуваного файлу для заданого базового імені. Зазвичай для платформ, відмінних від Windows, це те саме, що й базове ім’я, у той час як Windows додаватиме .exe.

library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])

Повертає назву файлу для заданої назви бібліотеки на поточній платформі. В Unix бібліотека з lib_type 'static' зазвичай матиме форму liblibname.a, тоді як lib_type 'dynamic' матиме форму: файл:liblibname.so.

object_filenames(source_filenames[, strip_dir=0, output_dir=''])

Повертає назву об’єктних файлів для заданих вихідних файлів. source_filenames має бути списком імен файлів.

shared_object_filename(basename[, strip_dir=0, output_dir=''])

Повертає назву файлу спільного об’єкта для заданого імені basename.

execute(func, args[, msg=None, level=1])

Викликає distutils.util.execute(). Цей метод викликає функцію Python func із заданими аргументами args після реєстрації та з урахуванням прапора dry_run.

spawn(cmd)

Викликає distutils.util.spawn(). Це викликає зовнішній процес для виконання даної команди.

mkpath(name[, mode=511])

Викликає distutils.dir_util.mkpath(). Це створює каталог і будь-які відсутні каталоги предків.

move_file(src, dst)

Викликає distutils.file_util.move_file(). Перейменовує src на dst.

announce(msg[, level=1])

Напишіть повідомлення за допомогою distutils.log.debug().

warn(msg)

Напишіть попередження msg до стандартної помилки.

debug_print(msg)

Якщо на цьому екземплярі CCompiler встановлено прапор debug, виведіть msg у стандартний вихід, інакше нічого не робіть.

9.3. distutils.unixccompiler — Компілятор Unix C

Цей модуль надає клас UnixCCompiler, підклас CCompiler, який обробляє типовий компілятор командного рядка C у стилі Unix:

• макроси, визначені за допомогою -Dname[=value]

• макроси невизначені з -Uname

• включати каталоги пошуку, визначені за допомогою -Idir

• бібліотеки, визначені за допомогою -llib

• каталоги пошуку бібліотек, указані за допомогою -Ldir

• компілюється за допомогою cc (або подібного) виконуваного файлу з опцією -c: компілює .c до .o

• зв’язати статичну бібліотеку, яка обробляється командою ar (можливо, за допомогою ranlib)

• посилання на спільну бібліотеку обробляється cc -shared

9.4. distutils.msvccompiler — Компілятор Microsoft

Цей модуль забезпечує MSVCCompiler, реалізацію абстрактного CCompiler класу для Microsoft Visual Studio. Як правило, модулі розширення потрібно скомпілювати за допомогою того самого компілятора, який використовувався для компіляції Python. Для Python 2.3 і раніших версій компілятором була Visual Studio 6. Для Python 2.4 і 2.5 компілятором була Visual Studio .NET 2003.

MSVCCompiler зазвичай самостійно вибере правильний компілятор, компонувальник тощо. Щоб перевизначити цей вибір, потрібно встановити обидві змінні середовища DISTUTILS_USE_SDK і MSSdk. MSSdk вказує на те, що поточне середовище було налаштовано за допомогою сценарію SetEnv.Cmd SDK або що змінні середовища були зареєстровані під час встановлення SDK; DISTUTILS_USE_SDK вказує, що користувач distutils зробив явний вибір перевизначити вибір компілятора за допомогою MSVCCompiler.

9.5. distutils.bcppcompiler — Компілятор Borland

Цей модуль надає BorlandCCompiler, підклас абстрактного CCompiler класу для компілятора Borland C++.

9.6. distutils.cygwincompiler — компілятор Cygwin

Цей модуль надає клас CygwinCCompiler, підклас UnixCCompiler, який обробляє порт Cygwin компілятора GNU C для Windows. Він також містить клас Mingw32CCompiler, який обробляє порт mingw32 GCC (те саме, що cygwin у режимі без cygwin).

9.7. distutils.archive_util — Утиліти архівування

Цей модуль надає кілька функцій для створення архівних файлів, таких як tar-файли або zip-файли.

distutils.archive_util.make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])

Створіть архівний файл (наприклад, zip або tar). base_name — це ім’я файлу, який потрібно створити, за вирахуванням розширення, що залежить від формату; format — це формат архіву: один із zip, tar, gztar, bztar, xztar або ztar. root_dir – це каталог, який буде кореневим каталогом архіву; тобто. ми зазвичай chdir в root_dir перед створенням архіву. base_dir - це каталог, з якого ми починаємо архівування; тобто. base_dir буде загальним префіксом для всіх файлів і каталогів в архіві. root_dir і base_dir за замовчуванням є поточним каталогом. Повертає назву архівного файлу.

Змінено в версії 3.5: Додано підтримку формату xztar.

distutils.archive_util.make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])

«Створіть (необов’язково стиснутий) архів як файл tar з усіх файлів у base_dir та під ним. compress має бути 'gzip' (за замовчуванням), 'bzip2', 'xz', 'compress' або None. Для методу 'стиснення'' утиліта стиснення, названа compress, має бути на шляху пошуку програми за замовчуванням, тому це, ймовірно, специфічно для Unix. Вихідний файл tar матиме назву base_dir.tar, можливо, з додаванням відповідного розширення стиснення (.gz, .bz2, .xz або .Z ). Повернути назву вихідного файлу.

Змінено в версії 3.5: Додано підтримку стиснення xz.

distutils.archive_util.make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])

Створіть файл zip з усіх файлів у base_dir і під ним. Вихідний zip-файл матиме назву base_name + .zip. Використовує або модуль zipfile Python (якщо доступний), або утиліту InfoZIP zip (якщо встановлено та знайдено на шляху пошуку за умовчанням). Якщо жоден інструмент недоступний, викликає DistutilsExecError. Повертає назву вихідного zip-файлу.

9.8. distutils.dep_util — Перевірка залежностей

Цей модуль надає функції для виконання простої залежності файлів і груп файлів на основі часових позначок; також функції, повністю засновані на такому аналізі залежностей часових позначок.

distutils.dep_util.newer(source, target)

Повертає істину, якщо джерело існує та змінено нещодавно, ніж ціль, або якщо джерело існує, а ціль ні. Повертає false, якщо обидва існують і ціль має той самий вік або новіший, ніж джерело. Викликати DistutilsFileError, якщо джерело не існує.

distutils.dep_util.newer_pairwise(sources, targets)

Перегляньте два списки імен файлів паралельно, перевіряючи, чи кожне джерело є новішим за відповідну ціль. Повертає пару списків (джерела, цілі), де джерело є новішим за ціль, відповідно до семантики newer().

distutils.dep_util.newer_group(sources, target[, missing='error'])

Повертає true, якщо target застарів щодо будь-якого файлу, зазначеного в джерелах. Іншими словами, якщо target існує і є новішим за всі файли в sources, поверніть false; інакше повертає true. missing контролює те, що ми робимо, коли вихідний файл відсутній; за замовчуванням ('помилка') вибухає з OSError зсередини os.stat(); якщо це 'ignore'', ми мовчки видаляємо всі відсутні джерельні файли; якщо він 'новіший', будь-які відсутні вихідні файли змушують нас вважати, що target застарів (це зручно в режимі «сухого запуску»: це змусить вас вдавати, що ви виконуєте команди це не спрацює, оскільки вхідні дані відсутні, але це не має значення, оскільки ви насправді не збираєтеся виконувати команди).

9.9. distutils.dir_util — Операції з деревом каталогів

Цей модуль надає функції для роботи з каталогами та деревами каталогів.

distutils.dir_util.mkpath(name[, mode=0o777, verbose=0, dry_run=0])

Створіть каталог і будь-які відсутні каталоги предків. Якщо каталог уже існує (або якщо name є порожнім рядком, що означає поточний каталог, який, звичайно, існує), тоді нічого не робити. Викликати DistutilsFileError, якщо неможливо створити певний каталог (наприклад, якийсь підшлях існує, але це файл, а не каталог). Якщо verbose має значення true, вивести однорядковий підсумок кожного mkdir у стандартний вихід. Повертає список фактично створених каталогів.

distutils.dir_util.create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])

Створіть усі порожні каталоги в base_dir, необхідні для розміщення туди файлів. base_dir — це просто назва каталогу, який ще не обов’язково існує; files — це список імен файлів, які слід інтерпретувати відносно base_dir. base_dir + частина каталогу кожного файлу в files буде створена, якщо вона ще не існує. Прапори mode, verbose і dry_run такі ж, як і для mkpath().

distutils.dir_util.copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])

Скопіюйте все дерево каталогів src до нового розташування dst. І src, і dst мають бути іменами каталогів. Якщо src не є каталогом, викликайте DistutilsFileError. Якщо dst не існує, він створюється за допомогою mkpath(). Кінцевим результатом копіювання є те, що кожен файл у src копіюється в dst, а каталоги в src рекурсивно копіюються в dst. Повертає список файлів, які були скопійовані або могли бути скопійовані, використовуючи їхні вихідні назви. На повернене значення не впливають update або dry_run: це просто список усіх файлів у src, імена яких змінено на dst.

preserve_mode і preserve_times такі самі, як і для distutils.file_util.copy_file(); зауважте, що вони застосовуються лише до звичайних файлів, а не до каталогів. Якщо preserve_symlinks має значення true, символічні посилання буде скопійовано як символічні посилання (на платформах, які їх підтримують!); інакше (за замовчуванням) місце призначення символічного посилання буде скопійовано. update і verbose такі самі, як і для copy_file().

Files in src that begin with .nfs are skipped (more information on these files is available in answer D2 of the NFS FAQ page).

Змінено в версії 3.3.1: Файли NFS ігноруються.

distutils.dir_util.remove_tree(directory[, verbose=0, dry_run=0])

Рекурсивно видаліть каталог і всі файли та каталоги під ним. Будь-які помилки ігноруються (крім повідомлень у sys.stdout, якщо verbose має значення true).

9.10. distutils.file_util — Операції з одним файлом

Цей модуль містить деякі службові функції для роботи з окремими файлами.

distutils.file_util.copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])

Скопіюйте файл src в dst. Якщо dst є каталогом, то src копіюється туди з таким же ім’ям; інакше це має бути ім’я файлу. (Якщо файл існує, його буде безжально знищено.) Якщо preserve_mode має значення true (за замовчуванням), режим файлу (тип і біти дозволу або щось аналогічне на поточній платформі) копіюється. Якщо preserve_times має значення true (за замовчуванням), час останньої зміни та останнього доступу також копіюється. Якщо update має значення true, src буде скопійовано, лише якщо dst не існує, або якщо dst існує, але він старіший за src.

link дозволяє створювати жорсткі посилання (за допомогою os.link()) або символічні посилання (за допомогою os.symlink()) замість копіювання: установіть значення 'hard' або 'сим'; якщо значення None (за замовчуванням), файли копіюються. Не встановлюйте посилання на системах, які його не підтримують: copy_file() не перевіряє наявність жорсткого чи символічного зв’язування. Він використовує _copy_file_contents() для копіювання вмісту файлу.

Повертає кортеж (dest_name, copied): dest_name є фактичною назвою вихідного файлу, а copied має значення true, якщо файл було скопійовано (або було б скопійовано, якщо dry_run true).

distutils.file_util.move_file(src, dst[, verbose, dry_run])

Перемістити файл src до dst. Якщо dst є каталогом, файл буде переміщено до нього з таким же ім’ям; інакше src просто перейменовується на dst. Повертає нову повну назву файлу.

Попередження

Обробляє переміщення між пристроями в Unix за допомогою copy_file(). А як щодо інших систем?

distutils.file_util.write_file(filename, contents)

Створіть файл під назвою filename і запишіть у нього contents (послідовність рядків без символів закінчення рядків).

9.11. distutils.util — Інші інші службові функції

Цей модуль містить інші різні частини, які не підходять до жодного іншого службового модуля.

distutils.util.get_platform()

Повертає рядок, що ідентифікує поточну платформу. Це використовується в основному для того, щоб розрізнити каталоги збірок для певної платформи та побудовані дистрибутиви для конкретної платформи. Зазвичай включає назву та версію ОС та архітектуру (як надає „os.uname()“), хоча точна включена інформація залежить від ОС; наприклад, у Linux версія ядра не особливо важлива.

Приклади повернених значень:

• linux-i586

• linux-альфа

• solaris-2.6-sun4u

Для платформ, відмінних від POSIX, наразі повертає лише sys.platform.

Для систем macOS версія ОС відображає мінімальну версію, на якій запускатимуться двійкові файли (тобто значення MACOSX_DEPLOYMENT_TARGET під час збирання Python), а не версію ОС поточної системи.

Для універсальних двійкових збірок на macOS значення архітектури відображає статус універсального двійкового файлу замість архітектури поточного процесора. Для 32-розрядних універсальних двійкових файлів архітектура fat, для 64-розрядних універсальних двійкових файлів архітектура fat64, а для 4-сторонніх універсальних двійкових файлів архітектура universal. Починаючи з Python 2.7 і Python 3.2, архітектура fat3 використовується для тристоронньої універсальної збірки (ppc, i386, x86_64), а intel використовується для універсальної збірки з архітектурами i386 і x86_64

Приклади повернених значень у macOS:

• macosx-10.3-ppc

• macosx-10.3-fat

• macosx-10.5-universal

• macosx-10.6-intel

Для AIX Python 3.9 і пізніших версій повертає рядок, що починається з «aix», за яким ідуть додаткові поля (розділені «-«), які представляють об’єднані значення версії AIX, випуску та рівня технології (перше поле), Build Дата (друге поле) і бітовий розмір (третє поле). Python 3.8 і попередні версії повертали лише одне додаткове поле з версією та випуском AIX.

Приклади повернених значень в AIX:

• aix-5307-0747-32 # 32-розрядна збірка на AIX oslevel -s: 5300-07-00-0000

• aix-7105-1731-64 # 64-розрядна збірка на AIX oslevel -s: 7100-05-01-1731

• aix-7.2 # Застаріла форма, представлена в Python 3.8 і раніше

Змінено в версії 3.9: Формат рядка платформи AIX тепер також включає рівень технології, дату збірки та бітовий розмір ABI.

distutils.util.convert_path(pathname)

Поверніть «pathname» як ім’я, яке працюватиме у рідній файловій системі, тобто розділіть його на «/» і знову об’єднайте, використовуючи поточний роздільник каталогів. Необхідно, тому що імена файлів у сценарії встановлення завжди надаються у стилі Unix і мають бути перетворені відповідно до локальної угоди, перш ніж ми зможемо фактично використовувати їх у файловій системі. Викликає ValueError на системах, що не підтримують Unix, якщо шлях починається або закінчується скісною рискою.

distutils.util.change_root(new_root, pathname)

Повернути pathname з new_root перед початком. Якщо pathname є відносним, це еквівалентно os.path.join(new_root,pathname). В іншому випадку потрібно зробити pathname відносним, а потім об’єднати два, що складно в DOS/Windows.

distutils.util.check_environ()

Переконайтеся, що «os.environ» містить усі змінні середовища, які ми гарантуємо, що користувачі можуть використовувати у файлах конфігурації, параметрах командного рядка тощо. Наразі це включає:

• HOME - домашній каталог користувача (тільки для Unix)

• PLAT - опис поточної платформи, включаючи обладнання та ОС (див. get_platform())

distutils.util.subst_vars(s, local_vars)

Виконайте підстановку змінної у стилі shell/Perl на s. Кожне входження $, після якого йде ім’я, вважається змінною, а змінна замінюється значенням, знайденим у словнику local_vars або в os.environ, якщо його немає в local_vars. os.environ спочатку перевіряється/доповнюється, щоб гарантувати, що він містить певні значення: див. check_environ(). Викликати ValueError для будь-яких змінних, не знайдених ні в local_vars, ні в os.environ.

Note that this is not a full-fledged string interpolation function. A valid $variable can consist only of upper and lower case letters, numbers and an underscore. No { } or ( ) style quoting is available.

distutils.util.split_quoted(s)

Розділіть рядок відповідно до правил оболонки Unix для лапок і зворотних косих риск. Коротше кажучи: слова розділені пробілами, якщо ці пробіли не виділені зворотною скісною рискою або всередині рядка в лапках. Одинарні та подвійні лапки еквівалентні, а символи лапок можна екранувати зворотною скісною рискою. Зворотний слеш видаляється з будь-якої послідовності екранування з двох символів, залишаючи лише екранований символ. Символи лапок видаляються з будь-якого рядка в лапках. Повертає список слів.

distutils.util.execute(func, args[, msg=None, verbose=0, dry_run=0])

Виконайте певну дію, яка впливає на зовнішній світ (наприклад, запис у файлову систему). Такі дії є особливими, тому що вони вимкнені прапором dry_run. Цей метод подбає про всю цю бюрократію за вас; все, що вам потрібно зробити, це надати функцію для виклику та кортеж аргументів для неї (щоб втілити «зовнішню дію», що виконується), і додаткове повідомлення для друку.

distutils.util.strtobool(val)

Перетворення рядкового представлення правди в істину (1) або хибність (0).

Справжніми значеннями є y, yes, t, true, on і 1; помилковими значеннями є n, no, f, false, off і 0. Викликає ValueError, якщо val є чимось іншим.

distutils.util.byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])

Байтова компіляція колекції вихідних файлів Python у файли .pyc у підкаталозі __pycache__ (див. PEP 3147 і PEP 488). py_files — список файлів для компіляції; будь-які файли, які не закінчуються на .py мовчки пропускаються. optimize має бути одним із таких:

• 0 - не оптимізувати

• 1 - звичайна оптимізація (наприклад, python -O)

• 2 - додаткова оптимізація (наприклад, python -OO)

Якщо force має значення true, усі файли перекомпільовуються незалежно від позначок часу.

Ім’я вихідного файлу, закодоване в кожному файлі bytecode, за замовчуванням відповідає назвам файлів, указаним у py_files; ви можете змінити їх за допомогою prefix і basedir. префікс — це рядок, який буде видалено з імені кожного вихідного файлу, а base_dir — це ім’я каталогу, яке буде додано перед (після видалення префікса). Ви можете вказати один або обидва (або жоден) з prefix і base_dir, як хочете.

Якщо dry_run має значення true, фактично не робить нічого, що могло б вплинути на файлову систему.

Компіляція байтів виконується або безпосередньо в цьому процесі інтерпретатора за допомогою стандартного модуля py_compile, або опосередковано шляхом написання тимчасового сценарію та його виконання. Зазвичай ви повинні дозволити byte_compile() визначити, використовувати пряму компіляцію чи ні (дивіться джерело для деталей). Прапор прямий використовується сценарієм, згенерованим у непрямому режимі; Якщо ви не знаєте, що робите, залиште значення None.

Змінено в версії 3.2.3: Створюйте файли .pyc із магічним тегом імпорту у своєму імені в підкаталозі __pycache__ замість файлів без тегу в поточному каталозі.

Змінено в версії 3.5: Створіть файли .pyc відповідно до PEP 488.

distutils.util.rfc822_escape(header)

Повертає екрановану версію заголовка для включення в заголовок RFC 822, переконавшись, що після кожного нового рядка є 8 пробілів. Зауважте, що він не виконує інших модифікацій рядка.

9.12. distutils.dist — Клас розподілу

Цей модуль надає клас Distribution, який представляє дистрибутив модуля, який створюється/встановлюється/розповсюджується.

9.13. distutils.extension — Клас розширення

Цей модуль надає клас Extension, який використовується для опису модулів розширення C/C++ у сценаріях налаштування.

9.14. distutils.debug — Режим налагодження Distutils

Цей модуль надає позначку DEBUG.

9.15. distutils.errors — винятки Distutils

Надає винятки, які використовуються модулями Distutils. Зауважте, що модулі Distutils можуть викликати стандартні винятки; зокрема, SystemExit зазвичай викликається для помилок, які, очевидно, є помилкою кінцевого користувача (наприклад, неправильні аргументи командного рядка).

Цей модуль безпечно використовувати в режимі from ... import *; він експортує лише символи, імена яких починаються з Distutils і закінчуються Error.

9.16. distutils.fancy_getopt — Обгортка навколо стандартного модуля getopt

Цей модуль надає оболонку стандартного модуля getopt, яка надає наступні додаткові функції:

• короткі і довгі варіанти зв’язуються разом

• параметри мають рядки довідки, тому fancy_getopt() потенційно може створити повний підсумок використання

• параметри встановлюють атрибути переданого об’єкта

• логічні параметри можуть мати «негативні псевдоніми» — наприклад. якщо --quiet є «негативним псевдонімом» --verbose, тоді --quiet у командному рядку встановлює для verbose значення false.

distutils.fancy_getopt.fancy_getopt(options, negative_opt, object, args)

Функція обгортки. options — це список (long_option, short_option, help_string) 3-кортежів, як описано в конструкторі для FancyGetopt. negative_opt має бути словником, який зіставляє назви параметрів з назвами параметрів, і ключ, і значення мають бути в списку параметрів. object — це об’єкт, який використовуватиметься для зберігання значень (дивіться метод getopt() класу FancyGetopt). args — список аргументів. Використовуватиме sys.argv[1:], якщо ви передасте None як args.

distutils.fancy_getopt.wrap_text(text, width)

Переносить текст на ширину менше ширини.

class distutils.fancy_getopt.FancyGetopt([option_table=None])

Таблиця_опцій — це список із трьох кортежів: (long_option, short_option, help_string)

Якщо параметр приймає аргумент, до його long_option має бути додано '='; short_option має бути лише одним символом, ні в якому разі не ':''. short_option має бути None, якщо long_option не має відповідного short_option. Усі кортежі параметрів повинні мати довгі параметри.

Клас FancyGetopt надає такі методи:

FancyGetopt.getopt([args=None, object=None])

Розібрати параметри командного рядка в args. Зберігати як атрибути на об’єкті.

Якщо args має значення None або не надається, використовується sys.argv[1:]. Якщо object має значення None або не надано, створює новий екземпляр OptionDummy, зберігає там значення параметрів і повертає кортеж (args, object). Якщо надається object, він змінюється на місці, і getopt() просто повертає args; в обох випадках повернутий args є модифікованою копією переданого списку args, який залишається недоторканим.

FancyGetopt.get_option_order()

Повертає список кортежів (option, value), оброблених попереднім запуском getopt() Викликає RuntimeError, якщо getopt() ще не було викликано.

FancyGetopt.generate_help([header=None])

Згенеруйте довідковий текст (список рядків, по одному на запропонований рядок виводу) з таблиці параметрів для цього об’єкта FancyGetopt.

Якщо надається, друкує наданий заголовок у верхній частині довідки.

9.17. distutils.filelist — Клас FileList

Цей модуль надає клас FileList, який використовується для вивчення файлової системи та створення списків файлів.

9.18. distutils.log — Просте журналювання у стилі PEP 282

9.19. distutils.spawn — Створення підпроцесу

Цей модуль надає функцію spawn(), інтерфейс для різних функцій, специфічних для платформи, для запуску іншої програми в підпроцесі. Також надає find_executable() для пошуку шляху для вказаного імені виконуваного файлу.

9.20. distutils.sysconfig — Інформація про конфігурацію системи

Застаріло починаючи з версії 3.10: distutils.sysconfig було об’єднано в sysconfig.

Модуль distutils.sysconfig забезпечує доступ до низькорівневої конфігураційної інформації Python. Конкретні доступні змінні конфігурації значною мірою залежать від платформи та конфігурації. Конкретні змінні залежать від процесу збирання для конкретної версії Python, що виконується; змінні знаходяться в Makefile та заголовку конфігурації, які встановлено разом з Python у системах Unix. Заголовок конфігурації називається pyconfig.h для версій Python, починаючи з 2.2, і config.h для попередніх версій Python.

Надаються деякі додаткові функції, які виконують деякі корисні маніпуляції для інших частин пакета distutils.

distutils.sysconfig.PREFIX

Результат os.path.normpath(sys.prefix).

distutils.sysconfig.EXEC_PREFIX

Результат os.path.normpath(sys.exec_prefix).

distutils.sysconfig.get_config_var(name)

Повертає значення однієї змінної. Це еквівалентно get_config_vars().get(name).

distutils.sysconfig.get_config_vars(...)

Повертає набір визначень змінних. Якщо аргументів немає, повертається словник, який зіставляє імена змінних конфігурації зі значеннями. Якщо надано аргументи, вони мають бути рядками, а значення, що повертається, буде послідовністю, що надає пов’язані значення. Якщо задане ім’я не має відповідного значення, для цієї змінної буде включено значення «Немає».

distutils.sysconfig.get_config_h_filename()

Повертає повну назву шляху до заголовка конфігурації. Для Unix це буде заголовок, згенерований сценарієм configure; для інших платформ заголовок буде надано безпосередньо вихідним кодом Python. Файл є текстовим файлом для конкретної платформи.

distutils.sysconfig.get_makefile_filename()

Повертає повну назву шляху до Makefile, який використовується для створення Python. Для Unix це буде файл, згенерований сценарієм configure; значення для інших платформ буде іншим. Файл є текстовим файлом певної платформи, якщо він існує. Ця функція корисна лише на платформах POSIX.

Наступні функції застаріли разом із цим модулем і не мають прямої заміни.

distutils.sysconfig.get_python_inc([plat_specific[, prefix]])

Повертає каталог для загальних або залежних від платформи C-файлів включення. Якщо plat_specific має значення true, повертається залежний від платформи каталог включення; якщо false або опущено, повертається незалежний від платформи каталог. Якщо вказано префікс, він використовується або як префікс замість PREFIX, або як префікс exec замість EXEC_PREFIX, якщо plat_specific має значення true.

distutils.sysconfig.get_python_lib([plat_specific[, standard_lib[, prefix]]])

Поверніть каталог для встановлення загальної або залежної від платформи бібліотеки. Якщо plat_specific має значення true, повертається залежний від платформи каталог включення; якщо false або опущено, повертається незалежний від платформи каталог. Якщо вказано префікс, він використовується або як префікс замість PREFIX, або як префікс exec замість EXEC_PREFIX, якщо plat_specific має значення true. Якщо standard_lib має значення true, повертається каталог для стандартної бібліотеки, а не каталог для встановлення розширень сторонніх розробників.

Наступна функція призначена лише для використання в пакеті distutils.

distutils.sysconfig.customize_compiler(compiler)

Виконайте будь-яке налаштування екземпляра distutils.ccompiler.CCompiler для певної платформи.

На даний момент ця функція потрібна тільки в Unix, але її слід викликати постійно, щоб підтримувати сумісність. Він вставляє інформацію, яка різниться в різних варіантах Unix і зберігається в файлі Makefile Python. Ця інформація включає вибраний компілятор, параметри компілятора та компонувальника, а також розширення, яке використовує компонувальник для спільних об’єктів.

Ця функція ще більш спеціального призначення, і її слід використовувати лише з власних процедур збірки Python.

distutils.sysconfig.set_python_build()

Повідомте модуль distutils.sysconfig, що він використовується як частина процесу збирання для Python. Це змінює багато відносних розташувань файлів, дозволяючи їм розташовуватися в області збірки, а не у встановленому Python.

9.21. distutils.text_file — Клас TextFile

Цей модуль надає клас TextFile, який надає інтерфейс для текстових файлів, який (необов’язково) піклується про видалення коментарів, ігнорування порожніх рядків і об’єднання рядків зворотними похилими рисками.

class distutils.text_file.TextFile([filename=None, file=None, **options])

Цей клас надає файлоподібний об’єкт, який піклується про всі речі, які ви зазвичай хочете робити під час обробки текстового файлу, який має деякий рядковий синтаксис: видалення коментарів (за умови, що # є вашим символом коментаря ), пропускати порожні рядки, об’єднувати суміжні рядки шляхом екранування символу нового рядка (тобто зворотної косої риски в кінці рядка), видаляти пробіли на початку та/або в кінці. Усі вони необов’язкові та управляються незалежно.

Клас надає метод warn(), щоб ви могли генерувати попередження, які повідомляють номер фізичного рядка, навіть якщо відповідний логічний рядок охоплює кілька фізичних рядків. Також надає unreadline() для реалізації построкового перегляду.

TextFile екземпляри створюються з filename, file або обома. RuntimeError виникає, якщо обидва мають значення None. filename має бути рядком, а file — файловим об’єктом (або чимось, що надає методи readline() і close()). Рекомендовано вказати принаймні ім’я файлу, щоб TextFile міг включити його в попередження. Якщо file не вказано, TextFile створює власний за допомогою вбудованої функції open().

Усі параметри є логічними і впливають на значення, які повертає readline()

назва опції	опис	за замовчуванням
strip_comments	смуга від '#' до кінця рядка, а також будь-які пробіли, що ведуть до '#'— якщо це не екрановано зворотною скісною рискою	правда
lstrip_ws	видаляти початкові пробіли з кожного рядка перед поверненням	помилковий
rstrip_ws	видаляти кінцеві пробіли (включно з символом закінчення рядка!) з кожного рядка перед поверненням.	правда
skip_blanks	пропускати порожні рядки *після* видалення коментарів і пробілів. (Якщо і lstrip_ws, і rstrip_ws false, то деякі рядки можуть складатися лише з пробілів: вони *не* будуть пропущені, навіть якщо skip_blanks має значення true.)	правда
join_lines	якщо зворотна скісна риска є останнім символом у рядку після видалення коментарів і пробілів, приєднайте наступний рядок до нього, щоб утворити один логічний рядок; якщо N послідовних рядків закінчуються зворотною скісною рискою, тоді N+1 фізичний рядок буде об’єднано в один логічний рядок.	помилковий
collapse_join	видаляти початкові пробіли з рядків, які приєднані до їх попереднього; має значення лише якщо (join_lines, а не lstrip_ws)	помилковий

Зауважте, що оскільки rstrip_ws може видаляти кінцевий новий рядок, семантика readline() має відрізнятися від методу readline() вбудованого файлового об’єкта! Зокрема, readline() повертає None для кінця файлу: порожній рядок може бути просто порожнім рядком (або рядком із пробілами), якщо rstrip_ws має значення true, але skip_blanks не.

open(filename)

Відкрийте новий файл назва файлу. Це перевизначає будь-які аргументи конструктора file або filename.

close()

Закрийте поточний файл і забудьте все, що ми знаємо про нього (включно з назвою файлу та номером поточного рядка).

warn(msg[, line=None])

Вивести (у stderr) попереджувальне повідомлення, прив’язане до поточного логічного рядка в поточному файлі. Якщо поточний логічний рядок у файлі охоплює кілька фізичних рядків, попередження стосується всього діапазону, наприклад «рядків 3-5». Якщо вказано рядок, він замінює поточний номер рядка; це може бути список або кортеж для позначення діапазону фізичних рядків або ціле число для окремого фізичного рядка.

readline()

Читання та повернення одного логічного рядка з поточного файлу (або з внутрішнього буфера, якщо рядки раніше були «непрочитаними» за допомогою unreadline()). Якщо параметр join_lines має значення true, це може передбачати читання кількох фізичних рядків, об’єднаних в один рядок. Оновлює номер поточного рядка, тому виклик warn() після readline() видає попередження про щойно прочитаний фізичний рядок(и). Повертає None у кінці файлу, оскільки порожній рядок може виникнути, якщо rstrip_ws має значення true, а strip_blanks — ні.

readlines()

Прочитати та повернути список усіх логічних рядків, що залишилися в поточному файлі. Це оновить номер поточного рядка до останнього рядка файлу.

unreadline(line)

Надішліть рядок (рядок) у внутрішній буфер, який перевірятиметься майбутніми викликами readline(). Зручно для реалізації синтаксичного аналізатора з построковим переглядом. Зауважте, що рядки, які є «непрочитаними» за допомогою unreadline(), згодом не очищаються повторно (видаляються пробіли чи щось інше), коли читаються за допомогою readline(). Якщо перед викликом readline() зроблено декілька викликів unreadline(), рядки буде повернуто в найновішому першому порядку.

9.22. distutils.version — Класи номерів версій

9.23. distutils.cmd — Абстрактний базовий клас для команд Distutils

Цей модуль надає абстрактний базовий клас Command.

class distutils.cmd.Command(dist)

Абстрактний базовий клас для визначення класів команд, «робочих бджіл» Distutils. Корисною аналогією для класів команд є розглядати їх як підпрограми з локальними змінними, які називаються options. Параметри оголошені в initialize_options() і визначені (враховуючи їх кінцеві значення) в finalize_options(), обидва з яких повинні бути визначені кожним класом команд. Розрізнення між цими двома параметрами є необхідним, оскільки значення параметрів можуть надходити із зовнішнього світу (командний рядок, конфігураційний файл, …), а будь-які параметри, залежні від інших параметрів, мають бути обчислені після обробки цих зовнішніх впливів — отже finalize_options(). Тіло підпрограми, де вона виконує всю свою роботу на основі значень своїх параметрів, є методом run(), який також має бути реалізований кожним класом команд.

Конструктор класу приймає один аргумент dist, екземпляр Distribution.

9.24. Створення нової команди Distutils

У цьому розділі описано кроки для створення нової команди Distutils.

Нова команда міститься в модулі в пакеті distutils.command. У цьому каталозі є зразок шаблону під назвою command_template. Скопіюйте цей файл до нового модуля з такою ж назвою, як і нова команда, яку ви реалізуєте. Цей модуль має реалізовувати клас із такою самою назвою, як і модуль (і команда). Отже, наприклад, щоб створити команду peel_banana (щоб користувачі могли запускати setup.py peel_banana), ви повинні скопіювати command_template до distutils/command/peel_banana .py, потім відредагуйте його так, щоб він реалізував клас peel_banana, підклас distutils.cmd.Command.

Підкласи Command повинні визначати такі методи.

Command.initialize_options()

Установіть значення за замовчуванням для всіх параметрів, які підтримує ця команда. Зауважте, що ці параметри за замовчуванням можуть бути замінені іншими командами, сценарієм налаштування, файлами конфігурації або командним рядком. Таким чином, це не місце для кодування залежностей між параметрами; загалом, реалізації initialize_options() — це просто купа призначень self.foo = None.

Command.finalize_options()

Установіть остаточні значення для всіх параметрів, які підтримує ця команда. Це завжди викликається якомога пізніше, тобто. після виконання будь-яких призначень параметрів із командного рядка чи інших команд. Таким чином, це місце для кодування залежностей параметрів: якщо foo залежить від bar, тоді безпечно встановити foo з bar, якщо foo все ще має те саме значення, яке було призначено в ініціалізувати_параметри().

Command.run()

Сенс існування команди: виконати дію, для виконання якої вона існує, що контролюється параметрами, ініціалізованими в initialize_options(), налаштованими іншими командами, сценарієм налаштування, командним рядком і файлами конфігурації, а також завершеними в finalize_options(). Весь вихід терміналу та взаємодія з файловою системою має здійснюватися за допомогою run().

Command.sub_commands

sub_commands формалізує поняття «сімейства» команд, напр. install як батьківський з підкомандами install_lib, install_headers тощо. Батьківський елемент сімейства команд визначає sub_commands як атрибут класу; це список із двох кортежів (назва_команди, предикат), де назва_команди є рядком, а предикат — функцією, рядком або None. предикат — це метод батьківської команди, який визначає, чи застосовна відповідна команда в поточній ситуації. (Наприклад, install_headers застосовний, лише якщо у нас є файли заголовків C для встановлення.) Якщо predicate має значення None, ця команда завжди застосовна.

sub_commands зазвичай визначається в кінці класу, оскільки предикати можуть бути методами класу, тому вони повинні бути вже визначені. Канонічним прикладом є команда install.

9.25. distutils.command — Окремі команди Distutils

9.26. distutils.command.bdist — Створення бінарного інсталятора

9.27. distutils.command.bdist_packager — Абстрактний базовий клас для пакувальників

9.28. distutils.command.bdist_dumb — Створення «тупого» інсталятора

9.29. distutils.command.bdist_rpm — Створення бінарного дистрибутива як Redhat RPM і SRPM

9.30. distutils.command.sdist — Створення вихідного дистрибутива

9.31. distutils.command.build — Збірка всіх файлів пакета

9.32. distutils.command.build_clib — Збірка будь-яких бібліотек C у пакунок

9.33. distutils.command.build_ext — Створення будь-яких розширень у пакеті

9.34. distutils.command.build_py — Створення файлів .py/.pyc пакета

class distutils.command.build_py.build_py

class distutils.command.build_py.build_py_2to3

Альтернативна реалізація build_py, яка також запускає бібліотеку перетворення 2to3 для кожного файлу .py, який буде встановлено. Щоб використовувати це у файлі setup.py для дистрибутива, призначеного для роботи з Python 2.x і 3.x, додайте:

try:
    from distutils.command.build_py import build_py_2to3 as build_py
except ImportError:
    from distutils.command.build_py import build_py

до вашого setup.py, а пізніше:

cmdclass = {'build_py': build_py}

до виклику setup().

9.35. distutils.command.build_scripts — Збірка сценаріїв пакета

9.36. distutils.command.clean — Очистити область збірки пакета

Ця команда видаляє тимчасові файли, створені build та його підкомандами, як-от проміжні скомпільовані об’єктні файли. З опцією --all буде видалено повний каталог збірки.

Модулі розширення, створені in place, не будуть очищені, оскільки їх немає в каталозі збірки.

9.37. distutils.command.config — Виконати налаштування пакета

9.38. distutils.command.install — Встановити пакет

9.39. distutils.command.install_data — Встановити файли даних із пакета

9.40. distutils.command.install_headers — Встановити файли заголовків C/C++ із пакета

9.41. distutils.command.install_lib — Встановити файли бібліотеки з пакета

9.42. distutils.command.install_scripts — Встановити файли сценарію з пакета

9.43. distutils.command.register — Реєстрація модуля в індексі пакетів Python

Команда register реєструє пакет в індексі пакетів Python. Це описано більш детально в PEP 301.

9.44. distutils.command.check — Перевірити метадані пакета

Команда check виконує деякі перевірки метаданих пакета. Наприклад, він перевіряє, що всі необхідні метадані надано як аргументи, передані до функції setup().