pip tools
7.4.1
Seperangkat alat baris perintah untuk membantu Anda menjaga paket berbasis pip tetap segar, bahkan ketika Anda telah menyematkannya. Anda memang menyematkannya, bukan? (Dalam membangun aplikasi Python dan dependensinya untuk produksi, Anda ingin memastikan bahwa build Anda dapat diprediksi dan deterministik.)
Mirip dengan pip , pip-tools harus diinstal di setiap lingkungan virtual proyek Anda:
$ source /path/to/venv/bin/activate
(venv) $ python -m pip install pip-toolsCatatan : semua contoh perintah yang tersisa mengasumsikan Anda telah mengaktifkan lingkungan virtual proyek Anda.
pip-compile Perintah pip-compile memungkinkan Anda mengkompilasi file requirements.txt dari dependensi Anda, yang ditentukan dalam pyproject.toml , setup.cfg , setup.py , atau requirements.in .
Jalankan dengan pip-compile atau python -m piptools compile (atau pipx run --spec pip-tools pip-compile jika pipx diinstal dengan versi Python yang sesuai). Jika Anda menggunakan beberapa versi Python, Anda juga dapat menjalankan py -XY -m piptools compile di Windows dan pythonX.Y -m piptools compile di sistem lain.
pip-compile harus dijalankan dari lingkungan virtual yang sama dengan proyek Anda sehingga dependensi bersyarat yang memerlukan versi Python tertentu, atau penanda lingkungan lainnya, dapat diselesaikan secara relatif terhadap lingkungan proyek Anda.
Catatan : Jika pip-compile menemukan file requirements.txt yang memenuhi dependensi maka tidak ada perubahan yang akan dilakukan, meskipun pembaruan tersedia. Untuk mengkompilasi dari awal, pertama-tama hapus file requirements.txt yang ada, atau lihat Memperbarui persyaratan untuk pendekatan alternatif.
pyproject.toml File pyproject.toml adalah standar terbaru untuk mengonfigurasi paket dan aplikasi, dan direkomendasikan untuk proyek baru. pip-compile mendukung penginstalan project.dependencies Anda serta project.optional-dependencies Anda. Berkat fakta bahwa ini adalah standar resmi, Anda dapat menggunakan pip-compile untuk menyematkan dependensi dalam proyek yang menggunakan alat pengemasan yang mengikuti standar modern seperti Setuptools, Hatch, atau flit.
Misalkan Anda memiliki aplikasi Python 'foobar' yang dikemas menggunakan Setuptools , dan Anda ingin menyematkannya untuk produksi. Anda dapat mendeklarasikan metadata proyek sebagai:
[ build-system ]
requires = [ " setuptools " , " setuptools-scm " ]
build-backend = " setuptools.build_meta "
[ project ]
requires-python = " >=3.9 "
name = " foobar "
dynamic = [ " dependencies " , " optional-dependencies " ]
[ tool . setuptools . dynamic ]
dependencies = { file = [ " requirements.in " ] }
optional-dependencies.test = { file = [ " requirements-test.txt " ] }
Jika Anda mempunyai aplikasi Django yang dikemas menggunakan Hatch , dan Anda ingin menyematkannya untuk produksi. Anda juga ingin menyematkan alat pengembangan Anda dalam file pin terpisah. Anda mendeklarasikan django sebagai ketergantungan dan membuat ketergantungan opsional dev yang mencakup pytest :
[ build-system ]
requires = [ " hatchling " ]
build-backend = " hatchling.build "
[ project ]
name = " my-cool-django-app "
version = " 42 "
dependencies = [ " django " ]
[ project . optional-dependencies ]
dev = [ " pytest " ]Anda dapat membuat file pin Anda semudah:
$ pip-compile -o requirements.txt pyproject.toml
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
# pip-compile --output-file=requirements.txt pyproject.toml
#
asgiref==3.6.0
# via django
django==4.1.7
# via my-cool-django-app (pyproject.toml)
sqlparse==0.4.3
# via django
$ pip-compile --extra dev -o dev-requirements.txt pyproject.toml
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
# pip-compile --extra=dev --output-file=dev-requirements.txt pyproject.toml
#
asgiref==3.6.0
# via django
attrs==22.2.0
# via pytest
django==4.1.7
# via my-cool-django-app (pyproject.toml)
exceptiongroup==1.1.1
# via pytest
iniconfig==2.0.0
# via pytest
packaging==23.0
# via pytest
pluggy==1.0.0
# via pytest
pytest==7.2.2
# via my-cool-django-app (pyproject.toml)
sqlparse==0.4.3
# via django
tomli==2.0.1
# via pytestIni bagus untuk menyematkan aplikasi Anda, tetapi juga untuk menjaga CI paket Python sumber terbuka Anda tetap stabil.
setup.py dan setup.cfg pip-compile juga memiliki dukungan penuh untuk proyek berbasis setup.py dan setup.cfg yang menggunakan setuptools .
Cukup tentukan dependensi dan tambahan Anda seperti biasa dan jalankan pip-compile seperti di atas.
requirements.in Anda juga dapat menggunakan file teks biasa untuk kebutuhan Anda (misalnya jika Anda tidak ingin aplikasi Anda menjadi sebuah paket). Untuk menggunakan berkas requirements.in untuk mendeklarasikan ketergantungan Django:
# requirements.in
django
Sekarang, jalankan pip-compile requirements.in :
$ pip-compile requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
# pip-compile requirements.in
#
asgiref==3.6.0
# via django
django==4.1.7
# via -r requirements.in
sqlparse==0.4.3
# via django Dan itu akan menghasilkan requirements.txt Anda, dengan semua dependensi Django (dan semua dependensi yang mendasarinya) disematkan.
(memperbarui-persyaratan)=
pip-compile menghasilkan file requirements.txt menggunakan versi terbaru yang memenuhi dependensi yang Anda tentukan di file yang didukung.
Jika pip-compile menemukan file requirements.txt yang memenuhi dependensi maka tidak ada perubahan yang akan dilakukan, meskipun pembaruan tersedia.
Untuk memaksa pip-compile memperbarui semua paket dalam requirements.txt yang ada, jalankan pip-compile --upgrade .
Untuk memperbarui paket tertentu ke versi terbaru atau versi tertentu, gunakan tanda --upgrade-package atau -P :
# only update the django package
$ pip-compile --upgrade-package django
# update both the django and requests packages
$ pip-compile --upgrade-package django --upgrade-package requests
# update the django package to the latest, and requests to v2.0.0
$ pip-compile --upgrade-package django --upgrade-package requests==2.0.0 Anda dapat menggabungkan --upgrade dan --upgrade-package dalam satu perintah, untuk memberikan batasan pada peningkatan yang diizinkan. Misalnya untuk mengupgrade semua paket sambil membatasi permintaan ke versi terbaru kurang dari 3.0:
$ pip-compile --upgrade --upgrade-package ' requests<3.0 ' Jika Anda ingin menggunakan Mode Pemeriksaan Hash yang tersedia di pip sejak versi 8.0, pip-compile menawarkan tanda --generate-hashes :
$ pip-compile --generate-hashes requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
# pip-compile --generate-hashes requirements.in
#
asgiref==3.6.0
--hash=sha256:71e68008da809b957b7ee4b43dbccff33d1b23519fb8344e33f049897077afac
--hash=sha256:9567dfe7bd8d3c8c892227827c41cce860b368104c3431da67a0c5a65a949506
# via django
django==4.1.7
--hash=sha256:44f714b81c5f190d9d2ddad01a532fe502fa01c4cb8faf1d081f4264ed15dcd8
--hash=sha256:f2f431e75adc40039ace496ad3b9f17227022e8b11566f4b363da44c7e44761e
# via -r requirements.in
sqlparse==0.4.3
--hash=sha256:0323c0ec29cd52bceabc1b4d9d579e311f3e4961b98d174201d5622a23b85e34
--hash=sha256:69ca804846bb114d2ec380e4360a8a340db83f0ccf3afceeb1404df028f57268
# via django Untuk menampilkan persyaratan yang disematkan dalam nama file selain requirements.txt , gunakan --output-file . Ini mungkin berguna untuk mengkompilasi banyak berkas, misalnya dengan batasan berbeda pada Django untuk menguji pustaka dengan kedua versi menggunakan tox:
$ pip-compile --upgrade-package ' django<1.0 ' --output-file requirements-django0x.txt
$ pip-compile --upgrade-package ' django<2.0 ' --output-file requirements-django1x.txt Atau untuk menghasilkan keluaran standar, gunakan --output-file=- :
$ pip-compile --output-file=- > requirements.txt
$ pip-compile - --output-file=- < requirements.in > requirements.txtpip Flag atau argumen pip apa pun yang valid dapat diteruskan dengan opsi --pip-args pip-compile , misalnya
$ pip-compile requirements.in --pip-args " --retries 10 --timeout 30 " Anda dapat menentukan default tingkat proyek untuk pip-compile dan pip-sync dengan menuliskannya ke file konfigurasi di direktori yang sama dengan file input kebutuhan Anda (atau direktori kerja saat ini jika memipakan input dari stdin). Secara default, pip-compile dan pip-sync akan mencari file .pip-tools.toml terlebih dahulu, lalu di pyproject.toml Anda. Anda juga dapat menentukan file konfigurasi TOML alternatif dengan opsi --config .
Dimungkinkan untuk menentukan nilai konfigurasi baik secara global maupun khusus perintah. Misalnya, untuk secara default menghasilkan hash pip dalam output file persyaratan yang dihasilkan, Anda dapat menentukannya dalam file konfigurasi:
[ tool . pip-tools ]
generate-hashes = true Opsi untuk pip-compile dan pip-sync yang dapat digunakan lebih dari sekali harus didefinisikan sebagai daftar dalam file konfigurasi, meskipun hanya memiliki satu nilai.
pip-tools mendukung nilai default untuk semua tanda baris perintah yang valid dari subperintahnya. Kunci konfigurasi mungkin berisi garis bawah, bukan tanda hubung, sehingga kode di atas juga dapat ditentukan dalam format ini:
[ tool . pip-tools ]
generate_hashes = true Konfigurasi default khusus untuk pip-compile dan pip-sync dapat ditempatkan di bawah bagian terpisah. Misalnya, untuk secara default melakukan uji coba dengan pip-compile :
[ tool . pip-tools . compile ] # "sync" for pip-sync
dry-run = true Ini tidak mempengaruhi perintah pip-sync , yang juga memiliki opsi --dry-run . Perhatikan bahwa pengaturan lokal lebih diutamakan daripada pengaturan global dengan nama yang sama, setiap kali keduanya dideklarasikan, sehingga hal ini juga akan membuat pip-compile menghasilkan hash, namun membuang pengaturan dry-run global:
[ tool . pip-tools ]
generate-hashes = true
dry-run = true
[ tool . pip-tools . compile ]
dry-run = false Anda mungkin membungkus perintah pip-compile dalam skrip lain. Untuk menghindari membingungkan konsumen skrip khusus Anda, Anda dapat mengganti perintah pembaruan yang dihasilkan di bagian atas file persyaratan dengan mengatur variabel lingkungan CUSTOM_COMPILE_COMMAND .
$ CUSTOM_COMPILE_COMMAND= " ./pipcompilewrapper " pip-compile requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
# ./pipcompilewrapper
#
asgiref==3.6.0
# via django
django==4.1.7
# via -r requirements.in
sqlparse==0.4.3
# via djangoJika Anda memiliki lingkungan berbeda di mana Anda perlu menginstal paket yang berbeda namun kompatibel, maka Anda dapat membuat file persyaratan berlapis dan menggunakan satu lapisan untuk membatasi lapisan lainnya.
Misalnya, jika Anda mempunyai proyek Django di mana Anda ingin rilis 2.1 terbaru dalam produksi dan ketika pengembangan Anda ingin menggunakan toolbar debug Django, maka Anda dapat membuat dua berkas *.in , satu untuk setiap lapisan:
# requirements.in
django<2.2
Di bagian atas persyaratan pengembangan dev-requirements.in Anda menggunakan -c requirements.txt untuk membatasi persyaratan dev pada paket yang sudah dipilih untuk produksi di requirements.txt .
# dev-requirements.in
-c requirements.txt
django-debug-toolbar<2.2
Pertama, kompilasi requirements.txt seperti biasa:
$ pip-compile
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
# pip-compile
#
django==2.1.15
# via -r requirements.in
pytz==2023.3
# via django
Sekarang kompilasi persyaratan dev dan file requirements.txt digunakan sebagai batasan:
$ pip-compile dev-requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
# pip-compile dev-requirements.in
#
django==2.1.15
# via
# -c requirements.txt
# django-debug-toolbar
django-debug-toolbar==2.1
# via -r dev-requirements.in
pytz==2023.3
# via
# -c requirements.txt
# django
sqlparse==0.4.3
# via django-debug-toolbar Seperti yang Anda lihat di atas, meskipun rilis 2.2 dari Django tersedia, persyaratan pengembang hanya mencakup Django versi 2.1 karena dibatasi. Sekarang kedua file persyaratan yang dikompilasi dapat diinstal dengan aman di lingkungan dev.
Untuk menginstal persyaratan dalam penggunaan tahap produksi:
$ pip-syncAnda dapat menginstal persyaratan dalam tahap pengembangan dengan:
$ pip-sync requirements.txt dev-requirements.txt Anda mungkin menggunakan pip-compile sebagai pengait untuk pra-komit. Lihat dokumen pra-komit untuk petunjuknya. Contoh .pre-commit-config.yaml :
repos :
- repo : https://github.com/jazzband/pip-tools
rev : 7.4.1
hooks :
- id : pip-compile Anda mungkin ingin menyesuaikan argumen pip-compile dengan mengonfigurasi args dan/atau files , misalnya:
repos :
- repo : https://github.com/jazzband/pip-tools
rev : 7.4.1
hooks :
- id : pip-compile
files : ^requirements/production.(in|txt)$
args : [--index-url=https://example.com, requirements/production.in]Jika Anda memiliki beberapa file persyaratan, pastikan Anda membuat kait untuk setiap file.
repos :
- repo : https://github.com/jazzband/pip-tools
rev : 7.4.1
hooks :
- id : pip-compile
name : pip-compile setup.py
files : ^(setup.py|requirements.txt)$
- id : pip-compile
name : pip-compile requirements-dev.in
args : [requirements-dev.in]
files : ^requirements-dev.(in|txt)$
- id : pip-compile
name : pip-compile requirements-lint.in
args : [requirements-lint.in]
files : ^requirements-lint.(in|txt)$
- id : pip-compile
name : pip-compile requirements.in
args : [requirements.in]
files : ^requirements.(in|txt)$pip-sync Sekarang setelah Anda memiliki requirements.txt , Anda dapat menggunakan pip-sync untuk memperbarui lingkungan virtual Anda agar mencerminkan apa yang sebenarnya ada di sana. Ini akan menginstal/meningkatkan/mencopot pemasangan semua yang diperlukan agar sesuai dengan konten requirements.txt .
Jalankan dengan pip-sync atau python -m piptools sync . Jika Anda menggunakan beberapa versi Python, Anda juga dapat menjalankan py -XY -m piptools sync di Windows dan pythonX.Y -m piptools sync di sistem lain.
pip-sync harus diinstal dan dijalankan dari lingkungan virtual yang sama dengan proyek Anda untuk mengidentifikasi paket mana yang akan diinstal atau ditingkatkan.
Hati-hati : pip-sync dimaksudkan untuk digunakan hanya dengan requirements.txt yang dihasilkan oleh pip-compile .
$ pip-sync
Uninstalling flake8-2.4.1:
Successfully uninstalled flake8-2.4.1
Collecting click==4.1
Downloading click-4.1-py2.py3-none-any.whl (62kB)
100% |................................| 65kB 1.8MB/s
Found existing installation: click 4.0
Uninstalling click-4.0:
Successfully uninstalled click-4.0
Successfully installed click-4.1 Untuk menyinkronkan beberapa daftar ketergantungan *.txt , teruskan saja melalui argumen baris perintah, misalnya
$ pip-sync dev-requirements.txt requirements.txt Melewati argumen kosong akan menyebabkannya menjadi default ke requirements.txt .
Tanda atau argumen pip install apa pun yang valid dapat diteruskan dengan opsi --pip-args pip-sync , misalnya
$ pip-sync requirements.txt --pip-args " --no-cache-dir --no-deps " Catatan : pip-sync tidak akan mengupgrade atau menghapus instalasi alat pengemasan seperti setuptools , pip , atau pip-tools itu sendiri. Gunakan python -m pip install --upgrade untuk memutakhirkan paket-paket tersebut.
requirements.in dan requirements.txt ke kontrol sumber? Secara umum, ya. Jika Anda ingin instalasi lingkungan yang dapat direproduksi tersedia dari kontrol sumber Anda, maka ya, Anda harus memasukkan requirements.in dan requirements.txt ke kontrol sumber.
Perhatikan bahwa jika Anda menerapkan pada beberapa lingkungan Python (baca bagian di bawah), maka Anda harus melakukan file keluaran terpisah untuk setiap lingkungan Python. Kami menyarankan untuk menggunakan format {env}-requirements.txt (misal: win32-py3.7-requirements.txt , macos-py3.10-requirements.txt , dll.).
requirements.in / requirements.txt dan pip-compile lintas lingkunganKetergantungan suatu paket dapat berubah tergantung pada lingkungan Python di mana paket tersebut diinstal. Di sini, kami mendefinisikan lingkungan Python sebagai kombinasi Sistem Operasi, versi Python (3.7, 3.8, dll.), dan implementasi Python (CPython, PyPy, dll.). Untuk definisi yang tepat, lihat kemungkinan kombinasi penanda lingkungan PEP 508.
Karena requirements.txt yang dihasilkan dapat berbeda untuk setiap lingkungan, pengguna harus menjalankan pip-compile pada setiap lingkungan Python secara terpisah untuk menghasilkan requirements.txt yang valid untuk setiap lingkungan tersebut. requirements.in yang sama.in dapat digunakan sebagai file sumber untuk semua lingkungan, menggunakan penanda lingkungan PEP 508 sesuai kebutuhan, cara yang sama dilakukan untuk penggunaan lintas lingkungan pip biasa.
Jika requirements.txt yang dihasilkan tetap sama persis untuk semua lingkungan Python, maka persyaratan tersebut dapat digunakan di seluruh lingkungan Python dengan aman. Namun pengguna harus berhati-hati karena pembaruan paket apa pun dapat menimbulkan ketergantungan yang bergantung pada lingkungan, sehingga membuat requirements.txt yang baru dibuat juga bergantung pada lingkungan. Sebagai aturan umum, disarankan agar pengguna tetap menjalankan pip-compile pada setiap lingkungan Python yang ditargetkan untuk menghindari masalah.
pip-tools adalah alat yang hebat untuk meningkatkan reproduktifitas build. Namun ada beberapa hal yang perlu diingat.
pip-compile akan menghasilkan hasil yang berbeda di lingkungan yang berbeda seperti yang dijelaskan di bagian sebelumnya.pip harus digunakan dengan variabel lingkungan PIP_CONSTRAINT untuk mengunci dependensi di lingkungan build seperti yang didokumentasikan di #8439. Melanjutkan contoh pyproject.toml dari sebelumnya, membuat satu file kunci dapat dilakukan seperti:
$ pip-compile --all-build-deps --all-extras --output-file=constraints.txt --strip-extras pyproject.toml
#
# This file is autogenerated by pip-compile with Python 3.9
# by the following command:
#
# pip-compile --all-build-deps --all-extras --output-file=constraints.txt --strip-extras pyproject.toml
#
asgiref==3.5.2
# via django
attrs==22.1.0
# via pytest
backports-zoneinfo==0.2.1
# via django
django==4.1
# via my-cool-django-app (pyproject.toml)
editables==0.3
# via hatchling
hatchling==1.11.1
# via my-cool-django-app (pyproject.toml::build-system.requires)
iniconfig==1.1.1
# via pytest
packaging==21.3
# via
# hatchling
# pytest
pathspec==0.10.2
# via hatchling
pluggy==1.0.0
# via
# hatchling
# pytest
py==1.11.0
# via pytest
pyparsing==3.0.9
# via packaging
pytest==7.1.2
# via my-cool-django-app (pyproject.toml)
sqlparse==0.4.2
# via django
tomli==2.0.1
# via
# hatchling
# pytest Beberapa backend build juga dapat meminta dependensi build secara dinamis menggunakan hook get_requires_for_build_ yang dijelaskan dalam PEP 517 dan PEP 660. Hal ini akan ditunjukkan dalam output dengan salah satu sufiks berikut:
(pyproject.toml::build-system.backend::editable)(pyproject.toml::build-system.backend::sdist)(pyproject.toml::build-system.backend::wheel)pip-compile-multi - pembungkus perintah pip-compile untuk beberapa file persyaratan referensi silang.
pipdeptree untuk mencetak pohon ketergantungan dari paket yang diinstal.
penyorotan sintaksis requirements.in / requirements.txt :
Bagian ini mencantumkan fitur pip-tools yang saat ini tidak digunakan lagi.
--allow-unsafe akan diaktifkan secara default (#989). Gunakan --no-allow-unsafe untuk mempertahankan perilaku lama. Disarankan untuk meneruskan --allow-unsafe sekarang untuk beradaptasi dengan perubahan yang akan datang.--resolver=backtracking .--strip-extras akan diaktifkan secara default (#1613). Gunakan --no-strip-extras untuk mempertahankan perilaku lama.Anda dapat memilih antara penyelesai penelusuran balik default atau penyelesai lama yang tidak digunakan lagi.
Resolver lama terkadang gagal menyelesaikan dependensi. Resolver backtracking lebih kuat, namun dapat memakan waktu lebih lama untuk dijalankan secara umum.
Anda dapat terus menggunakan penyelesai lama dengan --resolver=legacy meskipun perhatikan bahwa penyelesai lama sudah tidak digunakan lagi dan akan dihapus pada rilis mendatang.
