kennethreitz/pipenv
1
0
Fork 0
mirror of https://github.com/kennethreitz/pipenv.git synced 2026-06-05 06:46:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Doc revisions1 (#5621)

Browse Source 
* Begin reviewing the basics docs.

* Check in delta

* More doc revisions.

* Split apart basics docs.

* Refactor based on building docs

* add the files back as markdown.

* more conversions to markdown.

* more conversions to markdown.

* fix markdown formatting.

* convert index to markdown.

* More docs review

* More markdown and doc revisions.

* Fix docs.

* Update doc build requirements.

* fix lint

* Fix build with update/upgrade command.

* remove useless quickstart and update the commands section.

* Fix lint

* change ordering of table of contents.

* fix changelog duplicate headings.

* Start splitting advanced topics.

* minor nits

* Move some sections from advanced to shell.

* remove this section as its stale and kind of off topic.

* move scripts out into its own section.

* Wrap up revisions1

* fix lint

* address PR feedback and other nits.

* fix lint

* Try improving ordering of table of contents, fix issue with indexes.md file location.

* fix lint

* PR feedback.
This commit is contained in:
Matt Davis
2023-03-18 03:44:58 -04:00
committed by GitHub
parent 08ce3f7d5e
commit 761a03d088
26 changed files with 1424 additions and 1468 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.rst
-42
View File
@@ -1,6 +1,4 @@
2023.2.18 (2023-02-18)
======================
Pipenv 2023.2.18 (2023-02-18)
=============================
@@ -32,8 +30,6 @@ Improved Documentation
2023.2.4 (2023-02-04)
=====================
Pipenv 2023.2.4 (2023-02-04)
============================
@@ -51,8 +47,6 @@ Removals and Deprecations
2022.12.19 (2022-12-19)
=======================
Pipenv 2022.12.19 (2022-12-19)
==============================
@@ -63,8 +57,6 @@ Bug Fixes
2022.12.17 (2022-12-17)
=======================
Pipenv 2022.12.17 (2022-12-17)
==============================
@@ -89,8 +81,6 @@ Vendored Libraries
2022.11.30 (2022-11-30)
=======================
Pipenv 2022.11.30 (2022-11-30)
==============================
@@ -101,8 +91,6 @@ Bug Fixes
2022.11.25 (2022-11-24)
=======================
Pipenv 2022.11.25 (2022-11-24)
==============================
@@ -113,8 +101,6 @@ Bug Fixes
2022.11.24 (2022-11-24)
=======================
Pipenv 2022.11.24 (2022-11-24)
==============================
@@ -125,8 +111,6 @@ Bug Fixes
2022.11.23 (2022-11-23)
=======================
Pipenv 2022.11.23 (2022-11-23)
==============================
@@ -151,8 +135,6 @@ Vendored Libraries
2022.11.11 (2022-11-11)
=======================
Pipenv 2022.11.11 (2022-11-11)
==============================
@@ -163,8 +145,6 @@ Bug Fixes
2022.11.5 (2022-11-05)
======================
Pipenv 2022.11.5 (2022-11-05)
=============================
@@ -175,8 +155,6 @@ Bug Fixes
2022.11.4 (2022-11-04)
======================
Pipenv 2022.11.4 (2022-11-04)
=============================
@@ -200,8 +178,6 @@ Vendored Libraries
2022.10.25 (2022-10-25)
=======================
Pipenv 2022.10.25 (2022-10-25)
==============================
@@ -222,8 +198,6 @@ Removals and Deprecations
2022.10.12 (2022-10-12)
=======================
Pipenv 2022.10.12 (2022-10-12)
==============================
@@ -234,8 +208,6 @@ Improved Documentation
2022.10.11 (2022-10-11)
=======================
Pipenv 2022.10.11 (2022-10-11)
==============================
@@ -246,8 +218,6 @@ Bug Fixes
2022.10.10 (2022-10-10)
=======================
Pipenv 2022.10.10 (2022-10-10)
==============================
@@ -264,8 +234,6 @@ Bug Fixes
2022.10.9 (2022-10-09)
======================
Pipenv 2022.10.9 (2022-10-09)
=============================
@@ -281,8 +249,6 @@ Relates to dev process changes
2022.10.4 (2022-10-04)
======================
Pipenv 2022.10.4 (2022-10-04)
=============================
@@ -299,8 +265,6 @@ Vendored Libraries
2022.9.24 (2022-09-24)
======================
Pipenv 2022.9.24 (2022-09-24)
=============================
@@ -311,8 +275,6 @@ Bug Fixes
2022.9.21 (2022-09-21)
======================
Pipenv 2022.9.21 (2022-09-21)
=============================
@@ -323,8 +285,6 @@ Bug Fixes
2022.9.20 (2022-09-20)
======================
Pipenv 2022.9.20 (2022-09-20)
=============================
@@ -361,8 +321,6 @@ Vendored Libraries
2022.9.8 (2022-09-08)
=====================
Pipenv 2022.9.8 (2022-09-08)
============================
Pipfile
+2
View File
@@ -21,11 +21,13 @@ gunicorn = {version = "*", markers="sys_platform == 'linux'"}
parse = "*"
importlib-metadata = {version = "*", markers="python_version < '3.8'"}
colorama= {version = "*", markers="sys_platform == 'win32'"}
myst-parser = {extras = ["linkify"], version = "*"}
invoke = "==2.0.0"
exceptiongroup = "==1.1.0"
tomli = "*"
[packages]
pytz = "*"
[scripts]
tests = "bash ./run-tests.sh"
Pipfile.lock
Generated
+126 -75
View File
@@ -1,7 +1,7 @@
{
"_meta": {
"hash": {
"sha256": "58f7dcd5928c25e71f8bc645bd59ac27fd268b7fd5af541f4fd4d5b8dcb3ce5f"
"sha256": "eb62088849429f204f99c914f3043a4952ab00589b6c4bd14354cff8bf95e8d9"
},
"pipfile-spec": 6,
"requires": {},
@@ -13,7 +13,16 @@
}
]
},
"default": {},
"default": {
"pytz": {
"hashes": [
"sha256:01a0681c4b9684a28304615eba55d1ab31ae00bf68ec157ec3708a8182dbbcd0",
"sha256:78f4f37d8198e0627c5f1143240bb0206b8691d8d7ac6d78fee88b78733f8c4a"
],
"index": "pypi",
"version": "==2022.7.1"
}
},
"develop": {
"alabaster": {
"hashes": [
@@ -34,6 +43,7 @@
"hashes": [
"sha256:81b2c9071a49367a7f770170e5eec8cb66567cfbbc8c73d20ce5ca4a8d71cf11"
],
"index": "pypi",
"markers": "sys_platform == 'win32'",
"version": "==1.4.1"
},
@@ -47,11 +57,11 @@
},
"babel": {
"hashes": [
"sha256:1ad3eca1c885218f6dce2ab67291178944f810a10a9b5f3cb8382a5a232b64fe",
"sha256:5ef4b3226b0180dedded4229651c8b0e1a3a6a2837d45a073272f313e4cf97f6"
"sha256:b4246fb7677d3b98f501a39d43396d3cafdc8eadb045f4a31be01863f655c610",
"sha256:cc2d99999cd01d44420ae725a21c9e3711b3aadc7976d6147f622d8581963455"
],
"markers": "python_version >= '3.6'",
"version": "==2.11.0"
"markers": "python_version >= '3.7'",
"version": "==2.12.1"
},
"beautifulsoup4": {
"hashes": [
@@ -199,7 +209,6 @@
"sha256:f9d0c5c045a3ca9bedfc35dca8526798eb91a07aa7a2c0fee134c6c6f321cbd7",
"sha256:ff6f3db31555657f3163b15a6b7c6938d08df7adbfc9dd13d9d19edad678f1e8"
],
"markers": "python_full_version >= '3.6.0'",
"version": "==3.0.1"
},
"click": {
@@ -221,6 +230,7 @@
"sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44",
"sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"
],
"index": "pypi",
"markers": "sys_platform == 'win32'",
"version": "==0.4.6"
},
@@ -229,60 +239,60 @@
"toml"
],
"hashes": [
"sha256:04481245ef966fbd24ae9b9e537ce899ae584d521dfbe78f89cad003c38ca2ab",
"sha256:0c45948f613d5d18c9ec5eaa203ce06a653334cf1bd47c783a12d0dd4fd9c851",
"sha256:10188fe543560ec4874f974b5305cd1a8bdcfa885ee00ea3a03733464c4ca265",
"sha256:218fe982371ac7387304153ecd51205f14e9d731b34fb0568181abaf7b443ba0",
"sha256:29571503c37f2ef2138a306d23e7270687c0efb9cab4bd8038d609b5c2393a3a",
"sha256:2a60d6513781e87047c3e630b33b4d1e89f39836dac6e069ffee28c4786715f5",
"sha256:2bf1d5f2084c3932b56b962a683074a3692bce7cabd3aa023c987a2a8e7612f6",
"sha256:3164d31078fa9efe406e198aecd2a02d32a62fecbdef74f76dad6a46c7e48311",
"sha256:32df215215f3af2c1617a55dbdfb403b772d463d54d219985ac7cd3bf124cada",
"sha256:33d1ae9d4079e05ac4cc1ef9e20c648f5afabf1a92adfaf2ccf509c50b85717f",
"sha256:33ff26d0f6cc3ca8de13d14fde1ff8efe1456b53e3f0273e63cc8b3c84a063d8",
"sha256:38da2db80cc505a611938d8624801158e409928b136c8916cd2e203970dde4dc",
"sha256:3b155caf3760408d1cb903b21e6a97ad4e2bdad43cbc265e3ce0afb8e0057e73",
"sha256:3b946bbcd5a8231383450b195cfb58cb01cbe7f8949f5758566b881df4b33baf",
"sha256:3baf5f126f30781b5e93dbefcc8271cb2491647f8283f20ac54d12161dff080e",
"sha256:4b14d5e09c656de5038a3f9bfe5228f53439282abcab87317c9f7f1acb280352",
"sha256:51b236e764840a6df0661b67e50697aaa0e7d4124ca95e5058fa3d7cbc240b7c",
"sha256:63ffd21aa133ff48c4dff7adcc46b7ec8b565491bfc371212122dd999812ea1c",
"sha256:6a43c7823cd7427b4ed763aa7fb63901ca8288591323b58c9cd6ec31ad910f3c",
"sha256:755e89e32376c850f826c425ece2c35a4fc266c081490eb0a841e7c1cb0d3bda",
"sha256:7a726d742816cb3a8973c8c9a97539c734b3a309345236cd533c4883dda05b8d",
"sha256:7c7c0d0827e853315c9bbd43c1162c006dd808dbbe297db7ae66cd17b07830f0",
"sha256:7ed681b0f8e8bcbbffa58ba26fcf5dbc8f79e7997595bf071ed5430d8c08d6f3",
"sha256:7ee5c9bb51695f80878faaa5598040dd6c9e172ddcf490382e8aedb8ec3fec8d",
"sha256:8361be1c2c073919500b6601220a6f2f98ea0b6d2fec5014c1d9cfa23dd07038",
"sha256:8ae125d1134bf236acba8b83e74c603d1b30e207266121e76484562bc816344c",
"sha256:9817733f0d3ea91bea80de0f79ef971ae94f81ca52f9b66500c6a2fea8e4b4f8",
"sha256:98b85dd86514d889a2e3dd22ab3c18c9d0019e696478391d86708b805f4ea0fa",
"sha256:9ccb092c9ede70b2517a57382a601619d20981f56f440eae7e4d7eaafd1d1d09",
"sha256:9d58885215094ab4a86a6aef044e42994a2bd76a446dc59b352622655ba6621b",
"sha256:b643cb30821e7570c0aaf54feaf0bfb630b79059f85741843e9dc23f33aaca2c",
"sha256:bc7c85a150501286f8b56bd8ed3aa4093f4b88fb68c0843d21ff9656f0009d6a",
"sha256:beeb129cacea34490ffd4d6153af70509aa3cda20fdda2ea1a2be870dfec8d52",
"sha256:c31b75ae466c053a98bf26843563b3b3517b8f37da4d47b1c582fdc703112bc3",
"sha256:c4e4881fa9e9667afcc742f0c244d9364d197490fbc91d12ac3b5de0bf2df146",
"sha256:c5b15ed7644ae4bee0ecf74fee95808dcc34ba6ace87e8dfbf5cb0dc20eab45a",
"sha256:d12d076582507ea460ea2a89a8c85cb558f83406c8a41dd641d7be9a32e1274f",
"sha256:d248cd4a92065a4d4543b8331660121b31c4148dd00a691bfb7a5cdc7483cfa4",
"sha256:d47dd659a4ee952e90dc56c97d78132573dc5c7b09d61b416a9deef4ebe01a0c",
"sha256:d4a5a5879a939cb84959d86869132b00176197ca561c664fc21478c1eee60d75",
"sha256:da9b41d4539eefd408c46725fb76ecba3a50a3367cafb7dea5f250d0653c1040",
"sha256:db61a79c07331e88b9a9974815c075fbd812bc9dbc4dc44b366b5368a2936063",
"sha256:ddb726cb861c3117a553f940372a495fe1078249ff5f8a5478c0576c7be12050",
"sha256:ded59300d6330be27bc6cf0b74b89ada58069ced87c48eaf9344e5e84b0072f7",
"sha256:e2617759031dae1bf183c16cef8fcfb3de7617f394c813fa5e8e46e9b82d4222",
"sha256:e5cdbb5cafcedea04924568d990e20ce7f1945a1dd54b560f879ee2d57226912",
"sha256:ec8e767f13be637d056f7e07e61d089e555f719b387a7070154ad80a0ff31801",
"sha256:ef382417db92ba23dfb5864a3fc9be27ea4894e86620d342a116b243ade5d35d",
"sha256:f2cba5c6db29ce991029b5e4ac51eb36774458f0a3b8d3137241b32d1bb91f06",
"sha256:f5b4198d85a3755d27e64c52f8c95d6333119e49fd001ae5798dac872c95e0f8",
"sha256:ffeeb38ee4a80a30a6877c5c4c359e5498eec095878f1581453202bfacc8fbc2"
"sha256:0339dc3237c0d31c3b574f19c57985fcbe494280153bbcad33f2cdf469f4ac3e",
"sha256:09643fb0df8e29f7417adc3f40aaf379d071ee8f0350ab290517c7004f05360b",
"sha256:0bd7e628f6c3ec4e7d2d24ec0e50aae4e5ae95ea644e849d92ae4805650b4c4e",
"sha256:0cf557827be7eca1c38a2480484d706693e7bb1929e129785fe59ec155a59de6",
"sha256:0f8318ed0f3c376cfad8d3520f496946977abde080439d6689d7799791457454",
"sha256:1b7fb13850ecb29b62a447ac3516c777b0e7a09ecb0f4bb6718a8654c87dfc80",
"sha256:22c308bc508372576ffa3d2dbc4824bb70d28eeb4fcd79d4d1aed663a06630d0",
"sha256:3004765bca3acd9e015794e5c2f0c9a05587f5e698127ff95e9cfba0d3f29339",
"sha256:3a209d512d157379cc9ab697cbdbb4cfd18daa3e7eebaa84c3d20b6af0037384",
"sha256:436313d129db7cf5b4ac355dd2bd3f7c7e5294af077b090b85de75f8458b8616",
"sha256:49567ec91fc5e0b15356da07a2feabb421d62f52a9fff4b1ec40e9e19772f5f8",
"sha256:4dd34a935de268a133e4741827ae951283a28c0125ddcdbcbba41c4b98f2dfef",
"sha256:570c21a29493b350f591a4b04c158ce1601e8d18bdcd21db136fbb135d75efa6",
"sha256:5928b85416a388dd557ddc006425b0c37e8468bd1c3dc118c1a3de42f59e2a54",
"sha256:5d2b9b5e70a21474c105a133ba227c61bc95f2ac3b66861143ce39a5ea4b3f84",
"sha256:617a94ada56bbfe547aa8d1b1a2b8299e2ec1ba14aac1d4b26a9f7d6158e1273",
"sha256:6a034480e9ebd4e83d1aa0453fd78986414b5d237aea89a8fdc35d330aa13bae",
"sha256:6fce673f79a0e017a4dc35e18dc7bb90bf6d307c67a11ad5e61ca8d42b87cbff",
"sha256:78d2c3dde4c0b9be4b02067185136b7ee4681978228ad5ec1278fa74f5ca3e99",
"sha256:7f099da6958ddfa2ed84bddea7515cb248583292e16bb9231d151cd528eab657",
"sha256:80559eaf6c15ce3da10edb7977a1548b393db36cbc6cf417633eca05d84dd1ed",
"sha256:834c2172edff5a08d78e2f53cf5e7164aacabeb66b369f76e7bb367ca4e2d993",
"sha256:861cc85dfbf55a7a768443d90a07e0ac5207704a9f97a8eb753292a7fcbdfcfc",
"sha256:8649371570551d2fd7dee22cfbf0b61f1747cdfb2b7587bb551e4beaaa44cb97",
"sha256:87dc37f16fb5e3a28429e094145bf7c1753e32bb50f662722e378c5851f7fdc6",
"sha256:8a6450da4c7afc4534305b2b7d8650131e130610cea448ff240b6ab73d7eab63",
"sha256:8d3843ca645f62c426c3d272902b9de90558e9886f15ddf5efe757b12dd376f5",
"sha256:8dca3c1706670297851bca1acff9618455122246bdae623be31eca744ade05ec",
"sha256:97a3189e019d27e914ecf5c5247ea9f13261d22c3bb0cfcfd2a9b179bb36f8b1",
"sha256:99f4dd81b2bb8fc67c3da68b1f5ee1650aca06faa585cbc6818dbf67893c6d58",
"sha256:9e872b082b32065ac2834149dc0adc2a2e6d8203080501e1e3c3c77851b466f9",
"sha256:a81dbcf6c6c877986083d00b834ac1e84b375220207a059ad45d12f6e518a4e3",
"sha256:abacd0a738e71b20e224861bc87e819ef46fedba2fb01bc1af83dfd122e9c319",
"sha256:ae82c988954722fa07ec5045c57b6d55bc1a0890defb57cf4a712ced65b26ddd",
"sha256:b0c0d46de5dd97f6c2d1b560bf0fcf0215658097b604f1840365296302a9d1fb",
"sha256:b1991a6d64231a3e5bbe3099fb0dd7c9aeaa4275ad0e0aeff4cb9ef885c62ba2",
"sha256:b2167d116309f564af56f9aa5e75ef710ef871c5f9b313a83050035097b56820",
"sha256:bd5a12239c0006252244f94863f1c518ac256160cd316ea5c47fb1a11b25889a",
"sha256:bdd3f2f285ddcf2e75174248b2406189261a79e7fedee2ceeadc76219b6faa0e",
"sha256:c77f2a9093ccf329dd523a9b2b3c854c20d2a3d968b6def3b820272ca6732242",
"sha256:cb5f152fb14857cbe7f3e8c9a5d98979c4c66319a33cad6e617f0067c9accdc4",
"sha256:cca7c0b7f5881dfe0291ef09ba7bb1582cb92ab0aeffd8afb00c700bf692415a",
"sha256:d2ef6cae70168815ed91388948b5f4fcc69681480a0061114db737f957719f03",
"sha256:d9256d4c60c4bbfec92721b51579c50f9e5062c21c12bec56b55292464873508",
"sha256:e191a63a05851f8bce77bc875e75457f9b01d42843f8bd7feed2fc26bbe60833",
"sha256:e2b50ebc2b6121edf352336d503357321b9d8738bb7a72d06fc56153fd3f4cd8",
"sha256:e3ea04b23b114572b98a88c85379e9e9ae031272ba1fb9b532aa934c621626d4",
"sha256:e4d70c853f0546855f027890b77854508bdb4d6a81242a9d804482e667fff6e6",
"sha256:f29351393eb05e6326f044a7b45ed8e38cb4dcc38570d12791f271399dc41431",
"sha256:f3d07edb912a978915576a776756069dede66d012baa503022d3a0adba1b6afa",
"sha256:fac6343bae03b176e9b58104a9810df3cdccd5cfed19f99adfa807ffbf43cf9b"
],
"markers": "python_version >= '3.7'",
"version": "==7.1.0"
"version": "==7.2.1"
},
"distlib": {
"hashes": [
@@ -344,7 +354,6 @@
"sha256:9dcc4547dbb1cb284accfb15ab5667a0e5d1881cc443e0677b4882a4067a807e",
"sha256:e0a968b5ba15f8a328fdfd7ab1fcb5af4470c28aaf7e55df02a99bc13138e6e8"
],
"index": "pypi",
"markers": "sys_platform == 'linux'",
"version": "==20.1.0"
},
@@ -411,6 +420,21 @@
"markers": "python_version >= '3.7'",
"version": "==3.1.2"
},
"linkify-it-py": {
"hashes": [
"sha256:11e29f00150cddaa8f434153f103c14716e7e097a8fd372d9eb1ed06ed91524d",
"sha256:2b3f168d5ce75e3a425e34b341a6b73e116b5d9ed8dbbbf5dc7456843b7ce2ee"
],
"version": "==1.0.3"
},
"markdown-it-py": {
"hashes": [
"sha256:5a35f8d1870171d9acc47b99612dc146129b631baf04970128b568f190d0cc30",
"sha256:7c9a5e412688bc771c67432cbfebcdd686c93ce6484913dccf06cb5a0bea35a1"
],
"markers": "python_version >= '3.7'",
"version": "==2.2.0"
},
"markupsafe": {
"hashes": [
"sha256:0576fe974b40a400449768941d5d0858cc624e3249dfd1e0c33674e5c7ca7aed",
@@ -474,6 +498,22 @@
],
"version": "==0.6.1"
},
"mdit-py-plugins": {
"hashes": [
"sha256:3278aab2e2b692539082f05e1243f24742194ffd92481f48844f057b51971283",
"sha256:4f1441264ac5cb39fa40a5901921c2acf314ea098d75629750c138f80d552cdf"
],
"markers": "python_version >= '3.7'",
"version": "==0.3.4"
},
"mdurl": {
"hashes": [
"sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8",
"sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba"
],
"markers": "python_version >= '3.7'",
"version": "==0.1.2"
},
"mock": {
"hashes": [
"sha256:c41cfb1e99ba5d341fbcc5308836e7d7c9786d302f995b2c271ce2144dece9eb",
@@ -490,6 +530,17 @@
"markers": "python_version >= '3.5'",
"version": "==1.0.0"
},
"myst-parser": {
"extras": [
"linkify"
],
"hashes": [
"sha256:61b275b85d9f58aa327f370913ae1bec26ebad372cc99f3ab85c8ec3ee8d9fb8",
"sha256:79317f4bb2c13053dd6e64f9da1ba1da6cd9c40c8a430c447a7b146a594c246d"
],
"index": "pypi",
"version": "==0.18.1"
},
"nodeenv": {
"hashes": [
"sha256:27083a7b96a25f2f5e1d8cb4b6317ee8aeda3bdd121394e5ac54e498028a042e",
@@ -635,13 +686,6 @@
"markers": "python_version >= '3.7'",
"version": "==3.2.0"
},
"pytz": {
"hashes": [
"sha256:01a0681c4b9684a28304615eba55d1ab31ae00bf68ec157ec3708a8182dbbcd0",
"sha256:78f4f37d8198e0627c5f1143240bb0206b8691d8d7ac6d78fee88b78733f8c4a"
],
"version": "==2022.7.1"
},
"pyyaml": {
"hashes": [
"sha256:01b45c0191e6d66c470b6cf1b9531a771a83c1c4208272ead47a3ae4f2f603bf",
@@ -693,17 +737,16 @@
"sha256:64299f4909223da747622c030b781c0d7811e359c37124b4bd368fb8c6518baa",
"sha256:98b1b2782e3c6c4904938b84c0eb932721069dfdb9134313beff7c83c2df24bf"
],
"index": "pypi",
"markers": "python_version >= '3.7' and python_version < '4'",
"version": "==2.28.2"
},
"setuptools": {
"hashes": [
"sha256:95f00380ef2ffa41d9bba85d95b27689d923c93dfbafed4aecd7cf988a25e012",
"sha256:bb6d8e508de562768f2027902929f8523932fcd1fb784e6d573d2cafac995a48"
"sha256:e5fd0a713141a4a105412233c63dc4e17ba0090c8e8334594ac790ec97792330",
"sha256:f106dee1b506dee5102cc3f3e9e68137bbad6d47b616be7991714b0c62204251"
],
"markers": "python_version >= '3.7'",
"version": "==67.3.2"
"version": "==67.4.0"
},
"snowballstemmer": {
"hashes": [
@@ -796,7 +839,6 @@
"hashes": [
"sha256:08c22c9c03b28a140fe3ec5064b53a5288279f22e596ca06b0be698d50c93cf2"
],
"index": "pypi",
"markers": "sys_platform == 'linux'",
"version": "==0.10.0"
},
@@ -824,6 +866,14 @@
"index": "pypi",
"version": "==4.5.0"
},
"uc-micro-py": {
"hashes": [
"sha256:316cfb8b6862a0f1d03540f0ae6e7b033ff1fa0ddbe60c12cbe0d4cec846a69f",
"sha256:b7cdf4ea79433043ddfe2c82210208f26f7962c0cfbe3bacb05ee879a7fdb596"
],
"markers": "python_version >= '3.6'",
"version": "==1.0.1"
},
"urllib3": {
"hashes": [
"sha256:076907bf8fd355cde77728471316625a4d2f7e713c125f51953bb5b3eecf4f72",
@@ -834,11 +884,11 @@
},
"virtualenv": {
"hashes": [
"sha256:37a640ba82ed40b226599c522d411e4be5edb339a0c0de030c0dc7b646d61590",
"sha256:54eb59e7352b573aa04d53f80fc9736ed0ad5143af445a1e539aada6eb947dd1"
"sha256:3c22fa5a7c7aa106ced59934d2c20a2ecb7f49b4130b8bf444178a16b880fa45",
"sha256:a8a4b8ca1e28f864b7514a253f98c1d62b64e31e77325ba279248c65fb4fcef4"
],
"markers": "python_version >= '3.7'",
"version": "==20.19.0"
"version": "==20.20.0"
},
"virtualenv-clone": {
"hashes": [
@@ -853,6 +903,7 @@
"sha256:7500c9625927c8ec60f54377d590f67b30c8e70ef4b8894214ac6e4cad233d2a",
"sha256:780a4082c5fbc0fde6a2fcfe5e26e6efc1e8f425730863c04085769781f51eba"
],
"index": "pypi",
"markers": "sys_platform == 'win32'",
"version": "==2.1.2"
},
docs/advanced.rst
+2 -385
View File
@@ -1,157 +1,10 @@
.. _advanced:
Advanced Usage of Pipenv
Other Topics
========================
.. image:: https://farm4.staticflickr.com/3672/33231486560_bff4124c9a_k_d.jpg
This document is current in the process of being broken apart into more granular sections so that we may provide better overall documentation.
This document covers some of Pipenv's more glorious and advanced features.
☤ Caveats
---------
- Dependencies of wheels provided in a ``Pipfile`` will not be captured by ``$ pipenv lock``.
- There are some known issues with using private indexes, related to hashing. We're actively working to solve this problem. You may have great luck with this, however.
- Installation is intended to be as deterministic as possible.
☤ Specifying Package Indexes
----------------------------
Starting in release ``2022.3.23`` all packages are mapped only to a single package index for security reasons.
All unspecified packages are resolved using the default index source; the default package index is PyPI.
For a specific package to be installed from an alternate package index, you must match the name of the index as in the following example::
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"
[[source]]
url = "https://download.pytorch.org/whl/cu113/"
verify_ssl = false
name = "pytorch"
[dev-packages]
[packages]
torch = {version="*", index="pytorch"}
numpy = {version="*"}
You may install a package such as the example ``torch`` from the named index ``pytorch`` using the CLI by running
the following command:
``pipenv install --index=pytorch torch``
Alternatively the index may be specified by full url, and it will be added to the ``Pipfile`` with a generated name
unless it already exists in which case the existing name with be reused when pinning the package index.
.. note::
In prior versions of ``pipenv`` you could specify ``--extra-index-urls`` to the ``pip`` resolver and avoid
specifically matching the expected index by name. That functionality was deprecated in favor of index restricted
packages, which is a simplifying assumption that is more security mindful. The pip documentation has the following
warning around the ``--extra-index-urls`` option:
*Using this option to search for packages which are not in the main repository (such as private packages) is unsafe,
per a security vulnerability called dependency confusion: an attacker can claim the package on the public repository
in a way that will ensure it gets chosen over the private package.*
Should you wish to use an alternative default index other than PyPI: simply do not specify PyPI as one of the
sources in your ``Pipfile``. When PyPI is omitted, then any public packages required either directly or
as sub-dependencies must be mirrored onto your private index or they will not resolve properly. This matches the
standard recommendation of ``pip`` maintainers: "To correctly make a private project installable is to point
--index-url to an index that contains both PyPI and their private projects—which is our recommended best practice."
The above documentation holds true for both ``lock`` resolution and ``sync`` of packages. It was suggested that
once the resolution and the lock file are updated, it is theoretically possible to safely scan multiple indexes
for these packages when running ``pipenv sync`` or ``pipenv install --deploy`` since it will verify the package
hashes match the allowed hashes that were already captured from a safe locking cycle.
To enable this non-default behavior, add ``install_search_all_sources = true`` option
to your ``Pipfile`` in the ``pipenv`` section::
[pipenv]
install_search_all_sources = true
**Note:** The locking cycle will still requires that each package be resolved from a single index. This feature was
requested as a workaround in order to support organizations where not everyone has access to the package sources.
☤ Using a PyPI Mirror
----------------------------
Should you wish to override the default PyPI index URLs with the URL for a PyPI mirror, you can do the following::
$ pipenv install --pypi-mirror <mirror_url>
$ pipenv update --pypi-mirror <mirror_url>
$ pipenv sync --pypi-mirror <mirror_url>
$ pipenv lock --pypi-mirror <mirror_url>
$ pipenv uninstall --pypi-mirror <mirror_url>
Alternatively, setting the ``PIPENV_PYPI_MIRROR`` environment variable is equivalent to passing ``--pypi-mirror <mirror_url>``.
☤ Injecting credentials into Pipfile via environment variables
-----------------------------------------------------------------
Pipenv will expand environment variables (if defined) in your Pipfile. Quite
useful if you need to authenticate to a private PyPI::
[[source]]
url = "https://$USERNAME:${PASSWORD}@mypypi.example.com/simple"
verify_ssl = true
name = "pypi"
Luckily - pipenv will hash your Pipfile *before* expanding environment
variables (and, helpfully, will substitute the environment variables again when
you install from the lock file - so no need to commit any secrets! Woo!)
If your credentials contain special characters, make sure they are URL-encoded as specified in `rfc3986 <https://datatracker.ietf.org/doc/html/rfc3986>`_.
Environment variables may be specified as ``${MY_ENVAR}`` or ``$MY_ENVAR``.
On Windows, ``%MY_ENVAR%`` is supported in addition to ``${MY_ENVAR}`` or ``$MY_ENVAR``.
Environment variables in the URL part of requirement specifiers can also be expanded, where the variable must be in the form of ``${VAR_NAME}``. Neither ``$VAR_NAME`` nor ``%VAR_NAME%`` is acceptable::
[[package]]
requests = {git = "git://${USERNAME}:${PASSWORD}@private.git.com/psf/requests.git", ref = "2.22.0"}
Keep in mind that environment variables are expanded in runtime, leaving the entries in ``Pipfile`` or ``Pipfile.lock`` untouched. This is to avoid the accidental leakage of credentials in the source code.
☤ Injecting credentials through keychain support
------------------------------------------------
Private registries on Google Cloud, Azure and AWS support dynamic credentials using
the keychain implementation. Due to the way the keychain is structured, it might ask
the user for input. Asking the user for input is disabled. This will disable the keychain
support completely, unfortunately.
If you want to work with private registries that use the keychain for authentication, you
can disable the "enforcement of no input".
**Note:** Please be sure that the keychain will really not ask for
input. Otherwise the process will hang forever!::
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"
[[source]]
url = "https://europe-python.pkg.dev/my-project/python/simple"
verify_ssl = true
name = "private-gcp"
[packages]
flask = "*"
private-test-package = {version = "*", index = "private-gcp"}
[pipenv]
disable_pip_input = false
Above example will install ``flask`` and a private package ``private-test-package`` from GCP.
☤ Supplying additional arguments to pip
------------------------------------------------
@@ -167,35 +20,6 @@ Example usage::
pipenv sync --extra-pip-args="--use-feature=truststore --proxy=127.0.0.1"
☤ Specifying Basically Anything
-------------------------------
If you'd like to specify that a specific package only be installed on certain systems,
you can use `PEP 508 specifiers <https://www.python.org/dev/peps/pep-0508/>`_ to accomplish this.
Here's an example ``Pipfile``, which will only install ``pywinusb`` on Windows systems::
[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"
[packages]
requests = "*"
pywinusb = {version = "*", sys_platform = "== 'win32'"}
Voilà!
Here's a more complex example::
[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
[packages]
unittest2 = {version = ">=1.0,<3.0", markers="python_version < '2.7.9' or (python_version >= '3.0' and python_version < '3.4')"}
Magic. Pure, unadulterated magic.
☤ Using pipenv for Deployments
------------------------------
@@ -453,12 +277,6 @@ different products which integrate with Pipenv projects:
- `VS Code <https://code.visualstudio.com/docs/python/environments>`_ (Editor Integration)
- `PyCharm <https://www.jetbrains.com/pycharm/download/>`_ (Editor Integration)
Works in progress:
- `Sublime Text <https://github.com/kennethreitz/pipenv-sublime>`_ (Editor Integration)
- Mysterious upcoming Google Cloud product (Cloud Hosting)
☤ Open a Module in Your Editor
------------------------------
@@ -517,157 +335,6 @@ Pipenv automatically honors both the ``python_full_version`` and ``python_versio
💫✨🍰✨💫
☤ Automatic Loading of ``.env``
-------------------------------
If a ``.env`` file is present in your project, ``$ pipenv shell`` and ``$ pipenv run`` will automatically load it, for you::
$ cat .env
HELLO=WORLD⏎
$ pipenv run python
Loading .env environment variables...
Python 2.7.13 (default, Jul 18 2017, 09:17:00)
[GCC 4.2.1 Compatible Apple LLVM 8.1.0 (clang-802.0.42)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.environ['HELLO']
'WORLD'
Shell like variable expansion is available in ``.env`` files using ``${VARNAME}`` syntax.::
$ cat .env
CONFIG_PATH=${HOME}/.config/foo
$ pipenv run python
Loading .env environment variables...
Python 3.7.6 (default, Dec 19 2019, 22:52:49)
[GCC 9.2.1 20190827 (Red Hat 9.2.1-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.environ['CONFIG_PATH']
'/home/kennethreitz/.config/foo'
This is very useful for keeping production credentials out of your codebase.
We do not recommend committing ``.env`` files into source control!
If your ``.env`` file is located in a different path or has a different name you may set the ``PIPENV_DOTENV_LOCATION`` environment variable::
$ PIPENV_DOTENV_LOCATION=/path/to/.env pipenv shell
To prevent pipenv from loading the ``.env`` file, set the ``PIPENV_DONT_LOAD_ENV`` environment variable::
$ PIPENV_DONT_LOAD_ENV=1 pipenv shell
See `theskumar/python-dotenv <https://github.com/theskumar/python-dotenv>`_ for more information on ``.env`` files.
☤ Custom Script Shortcuts
-------------------------
Pipenv supports creating custom shortcuts in the (optional) ``[scripts]`` section of your Pipfile.
You can then run ``pipenv run <shortcut name>`` in your terminal to run the command in the
context of your pipenv virtual environment even if you have not activated the pipenv shell first.
For example, in your Pipfile:
.. code-block:: toml
[scripts]
printspam = "python -c \"print('I am a silly example, no one would need to do this')\""
And then in your terminal::
$ pipenv run printspam
I am a silly example, no one would need to do this
Commands that expect arguments will also work.
For example:
.. code-block:: toml
[scripts]
echospam = "echo I am really a very silly example"
::
$ pipenv run echospam "indeed"
I am really a very silly example indeed
You can also specify pacakge functions as callables such as: ``<pathed.module>:<func>``. These can also take arguments.
For exaple:
.. code-block:: toml
[scripts]
my_func_with_args = {call = "package.module:func('arg1', 'arg2')"}
my_func_no_args = {call = "package.module:func()"}
::
$ pipenv run my_func_with_args
$ pipenv run my_func_no_args
You can display the names and commands of your shortcuts by running ``pipenv scripts`` in your terminal.
::
$ pipenv scripts
command script
echospam echo I am really a very silly example
.. _configuration-with-environment-variables:
☤ Configuration With Environment Variables
------------------------------------------
Pipenv comes with a handful of options that can be set via shell environment
variables.
To enable boolean options, create the variable in your shell and assign to it a
truthy value (i.e. ``"1"``)::
$ PIPENV_IGNORE_VIRTUALENVS=1
To explicitly disable a boolean option, assign to it a falsey value (i.e. ``"0"``).
.. autoclass:: pipenv.environments.Setting
:members:
If you'd like to set these environment variables on a per-project basis, I recommend utilizing the fantastic `direnv <https://direnv.net>`_ project, in order to do so.
Also note that `pip itself supports environment variables <https://pip.pypa.io/en/stable/user_guide/#environment-variables>`_, if you need additional customization.
For example::
$ PIP_INSTALL_OPTION="-- -DCMAKE_BUILD_TYPE=Release" pipenv install -e .
☤ Custom Virtual Environment Location
-------------------------------------
Pipenv automatically honors the ``WORKON_HOME`` environment variable, if you
have it set — so you can tell pipenv to store your virtual environments
wherever you want, e.g.::
export WORKON_HOME=~/.venvs
In addition, you can also have Pipenv stick the virtualenv in ``project/.venv`` by setting the ``PIPENV_VENV_IN_PROJECT`` environment variable.
☤ Virtual Environment Name
-------------------------------------
The virtualenv name created by Pipenv may be different from what you were expecting.
Dangerous characters (i.e. ``$`!*@"`` as well as space, line feed, carriage return,
and tab) are converted to underscores. Additionally, the full path to the current
folder is encoded into a "slug value" and appended to ensure the virtualenv name
is unique.
Pipenv supports a arbitrary custom name for the virtual environment set at ``PIPENV_CUSTOM_VENV_NAME``.
The logical place to specify this would be in a user's ``.env`` file in the root of the project, which gets loaded by pipenv when it is invoked.
☤ Testing Projects
------------------
@@ -752,22 +419,7 @@ A 3rd party plugin, `tox-pipenv`_ is also available to use Pipenv natively with
.. _tox-pipenv: https://tox-pipenv.readthedocs.io/en/latest/
.. _Travis-CI: https://travis-ci.org/
☤ Shell Completion
------------------
To enable completion in fish, add this to your configuration::
eval (env _PIPENV_COMPLETE=fish_source pipenv)
Alternatively, with zsh, add this to your configuration::
eval "$(_PIPENV_COMPLETE=zsh_source pipenv)"
Alternatively, with bash, add this to your configuration::
eval "$(_PIPENV_COMPLETE=bash_source pipenv)"
Magic shell completions are now enabled!
✨🍰✨
@@ -788,38 +440,3 @@ interfaces that don't participate in Python-level dependency resolution
at all, use the ``PIP_IGNORE_INSTALLED`` setting::
$ PIP_IGNORE_INSTALLED=1 pipenv install --dev
.. _pipfile-vs-setuppy:
☤ Pipfile vs setup.py
---------------------
There is a subtle but very important distinction to be made between **applications** and **libraries**. This is a very common source of confusion in the Python community.
Libraries provide reusable functionality to other libraries and applications (let's use the umbrella term **projects** here). They are required to work alongside other libraries, all with their own set of sub-dependencies. They define **abstract dependencies**. To avoid version conflicts in sub-dependencies of different libraries within a project, libraries should never ever pin dependency versions. Although they may specify lower or (less frequently) upper bounds, if they rely on some specific feature/fix/bug. Library dependencies are specified via ``install_requires`` in ``setup.py``.
Libraries are ultimately meant to be used in some **application**. Applications are different in that they usually are not depended on by other projects. They are meant to be deployed into some specific environment and only then should the exact versions of all their dependencies and sub-dependencies be made concrete. To make this process easier is currently the main goal of Pipenv.
To summarize:
- For libraries, define **abstract dependencies** via ``install_requires`` in ``setup.py``. The decision of which version exactly to be installed and where to obtain that dependency is not yours to make!
- For applications, define **dependencies and where to get them** in the ``Pipfile`` and use this file to update the set of **concrete dependencies** in ``Pipfile.lock``. This file defines a specific idempotent environment that is known to work for your project. The ``Pipfile.lock`` is your source of truth. The ``Pipfile`` is a convenience for you to create that lock-file, in that it allows you to still remain somewhat vague about the exact version of a dependency to be used. Pipenv is there to help you define a working conflict-free set of specific dependency-versions, which would otherwise be a very tedious task.
- Of course, ``Pipfile`` and Pipenv are still useful for library developers, as they can be used to define a development or test environment.
- And, of course, there are projects for which the distinction between library and application isn't that clear. In that case, use ``install_requires`` alongside Pipenv and ``Pipfile``.
You can also do this::
$ pipenv install -e .
This will tell Pipenv to lock all your ``setup.py``–declared dependencies.
☤ Changing Pipenv's Cache Location
----------------------------------
You can force Pipenv to use a different cache location by setting the environment variable ``PIPENV_CACHE_DIR`` to the location you wish. This is useful in the same situations that you would change ``PIP_CACHE_DIR`` to a different directory.
☤ Changing Default Python Versions
----------------------------------
By default, Pipenv will initialize a project using whatever version of python the system has as default. Besides starting a project with the ``--python`` flag, you can also use ``PIPENV_DEFAULT_PYTHON_VERSION`` to specify what version to use when starting a project when ``--python`` isn't used.
docs/basics.rst
-543
View File
@@ -1,543 +0,0 @@
.. _basic:
Basic Usage of Pipenv
=====================
.. image:: https://farm4.staticflickr.com/3931/33173826122_b7ee8f1a26_k_d.jpg
This document covers some of Pipenv's more basic features.
☤ Example Pipfile & Pipfile.lock
--------------------------------
Pipfiles contain information for the dependencies of the project, and supersedes
the requirements.txt file used in most Python projects. You should add a Pipfile in the
Git repository. The only thing required for users who clone the repository would be
installing Pipenv in the machine and typing ``pipenv install``. Pipenv is a reference
implementation for using Pipfile.
.. _example_files:
Here is a simple example of a ``Pipfile`` and the resulting ``Pipfile.lock``.
Example Pipfile
///////////////
::
[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"
[packages]
requests = "*"
[dev-packages]
pytest = "*"
Example Pipfile.lock
////////////////////
::
{
"_meta": {
"hash": {
"sha256": "8d14434df45e0ef884d6c3f6e8048ba72335637a8631cc44792f52fd20b6f97a"
},
"host-environment-markers": {
"implementation_name": "cpython",
"implementation_version": "3.6.1",
"os_name": "posix",
"platform_machine": "x86_64",
"platform_python_implementation": "CPython",
"platform_release": "16.7.0",
"platform_system": "Darwin",
"platform_version": "Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu-3789.70.16~2/RELEASE_X86_64",
"python_full_version": "3.6.1",
"python_version": "3.6",
"sys_platform": "darwin"
},
"pipfile-spec": 5,
"requires": {},
"sources": [
{
"name": "pypi",
"url": "https://pypi.python.org/simple",
"verify_ssl": true
}
]
},
"default": {
"certifi": {
"hashes": [
"sha256:54a07c09c586b0e4c619f02a5e94e36619da8e2b053e20f594348c0611803704",
"sha256:40523d2efb60523e113b44602298f0960e900388cf3bb6043f645cf57ea9e3f5"
],
"version": "==2017.7.27.1"
},
"chardet": {
"hashes": [
"sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691",
"sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae"
],
"version": "==3.0.4"
},
"idna": {
"hashes": [
"sha256:8c7309c718f94b3a625cb648ace320157ad16ff131ae0af362c9f21b80ef6ec4",
"sha256:2c6a5de3089009e3da7c5dde64a141dbc8551d5b7f6cf4ed7c2568d0cc520a8f"
],
"version": "==2.6"
},
"requests": {
"hashes": [
"sha256:6a1b267aa90cac58ac3a765d067950e7dbbf75b1da07e895d1f594193a40a38b",
"sha256:9c443e7324ba5b85070c4a818ade28bfabedf16ea10206da1132edaa6dda237e"
],
"version": "==2.18.4"
},
"urllib3": {
"hashes": [
"sha256:06330f386d6e4b195fbfc736b297f58c5a892e4440e54d294d7004e3a9bbea1b",
"sha256:cc44da8e1145637334317feebd728bd869a35285b93cbb4cca2577da7e62db4f"
],
"version": "==1.22"
}
},
"develop": {
"py": {
"hashes": [
"sha256:2ccb79b01769d99115aa600d7eed99f524bf752bba8f041dc1c184853514655a",
"sha256:0f2d585d22050e90c7d293b6451c83db097df77871974d90efd5a30dc12fcde3"
],
"version": "==1.4.34"
},
"pytest": {
"hashes": [
"sha256:b84f554f8ddc23add65c411bf112b2d88e2489fd45f753b1cae5936358bdf314",
"sha256:f46e49e0340a532764991c498244a60e3a37d7424a532b3ff1a6a7653f1a403a"
],
"version": "==3.2.2"
}
}
}
☤ General Recommendations & Version Control
-------------------------------------------
- Generally, keep both ``Pipfile`` and ``Pipfile.lock`` in version control.
- Do not keep ``Pipfile.lock`` in version control if multiple versions of Python are being targeted.
- Specify your target Python version in your ``Pipfile``'s ``[requires]`` section. Ideally, you should only have one target Python version, as this is a deployment tool. ``python_version`` should be in the format ``X.Y`` (or ``X``) and ``python_full_version`` should be in ``X.Y.Z`` format.
- ``pipenv install`` is fully compatible with ``pip install`` syntax, for which the full documentation can be found `here <https://pip.pypa.io/en/stable/user_guide/#installing-packages>`__.
- Note that the ``Pipfile`` uses the `TOML Spec <https://github.com/toml-lang/toml#user-content-spec>`_.
☤ Example Pipenv Workflow
-------------------------
Clone / create project repository::
$ cd myproject
Install from Pipfile, if there is one::
$ pipenv install
Or, add a package to your new project::
$ pipenv install <package>
This will create a ``Pipfile`` if one doesn't exist. If one does exist, it will automatically be edited with the new package you provided.
Next, activate the Pipenv shell::
$ pipenv shell
$ python --version
This will spawn a new shell subprocess, which can be deactivated by using ``exit``.
.. _initialization:
☤ Example Pipenv Upgrade Workflow
---------------------------------
- Find out what's changed upstream: ``$ pipenv update --outdated``.
- Upgrade packages, two options:
a. Want to upgrade everything? Just do ``$ pipenv update``.
b. Want to upgrade packages one-at-a-time? ``$ pipenv update <pkg>`` for each outdated package.
☤ Importing from requirements.txt
---------------------------------
If you only have a ``requirements.txt`` file available when running ``pipenv install``,
pipenv will automatically import the contents of this file and create a ``Pipfile`` for you.
You can also specify ``$ pipenv install -r path/to/requirements.txt`` to import a requirements file.
If your requirements file has version numbers pinned, you'll likely want to edit the new ``Pipfile``
to remove those, and let ``pipenv`` keep track of pinning. If you want to keep the pinned versions
in your ``Pipfile.lock`` for now, run ``pipenv lock --keep-outdated``. Make sure to
`upgrade <#initialization>`_ soon!
.. _specifying_versions:
☤ Specifying Versions of a Package
----------------------------------
You can specify versions of a package using the `Semantic Versioning scheme <https://semver.org/>`_
(i.e. ``major.minor.micro``).
For example, to install requests you can use: ::
$ pipenv install requests~=1.2
Pipenv will install version ``1.2`` and any minor update, but not ``2.0``.
This will update your ``Pipfile`` to reflect this requirement, automatically.
In general, Pipenv uses the same specifier format as pip. However, note that according to `PEP 440`_ , you can't use versions containing a hyphen or a plus sign.
.. _`PEP 440`: https://www.python.org/dev/peps/pep-0440/
To make inclusive or exclusive version comparisons you can use: ::
$ pipenv install "requests>=1.4" # will install a version equal or larger than 1.4.0
$ pipenv install "requests<=2.13" # will install a version equal or lower than 2.13.0
$ pipenv install "requests>2.19" # will install 2.19.1 but not 2.19.0
.. note:: The use of double quotes around the package and version specification (i.e. ``"requests>2.19"``) is highly recommended
to avoid issues with `Input and output redirection <https://robots.thoughtbot.com/input-output-redirection-in-the-shell>`_
in Unix-based operating systems.
The use of ``~=`` is preferred over the ``==`` identifier as the latter prevents pipenv from updating the packages: ::
$ pipenv install "requests~=2.2" # locks the major version of the package (this is equivalent to using >=2.2, ==2.*)
To avoid installing a specific version you can use the ``!=`` identifier.
For an in depth explanation of the valid identifiers and more complex use cases check `the relevant section of PEP-440`_.
.. _`the relevant section of PEP-440`: https://www.python.org/dev/peps/pep-0440/#version-specifiers
☤ Specifying Versions of Python
-------------------------------
To create a new virtualenv, using a specific version of Python you have installed (and
on your ``PATH``), use the ``--python VERSION`` flag, like so:
Use Python 3::
$ pipenv --python 3
Use Python3.6::
$ pipenv --python 3.6
Use Python 2.7.14::
$ pipenv --python 2.7.14
When given a Python version, like this, Pipenv will automatically scan your system for a Python that matches that given version.
If a ``Pipfile`` hasn't been created yet, one will be created for you, that looks like this::
[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
[dev-packages]
[packages]
[requires]
python_version = "3.6"
.. note:: The inclusion of ``[requires] python_version = "3.6"`` specifies that your application requires this version
of Python, and will be used automatically when running ``pipenv install`` against this ``Pipfile`` in the future
(e.g. on other machines). If this is not true, feel free to simply remove this section.
If you don't specify a Python version on the command–line, either the ``[requires]`` ``python_full_version`` or ``python_version`` will be selected
automatically, falling back to whatever your system's default ``python`` installation is, at time of execution.
☤ Editable Dependencies (e.g. ``-e .`` )
----------------------------------------
You can tell Pipenv to install a path as editable — often this is useful for
the current working directory when working on packages::
$ pipenv install --dev -e .
$ cat Pipfile
...
[dev-packages]
"e1839a8" = {path = ".", editable = true}
...
.. note:: All sub-dependencies will get added to the ``Pipfile.lock`` as well. Sub-dependencies are **not** added to the
``Pipfile.lock`` if you leave the ``-e`` option out.
☤ Specifying Package Categories
-------------------------------
Originally pipenv supported only two package groups: ``packages`` and ``dev-packages`` in the ``Pipfile`` which mapped to ``default`` and ``develop`` in the ``Pipfile.lock``. Support for additional named categories has been added such that arbitrary named groups can utilized across the available pipenv commands.
.. note:: The name will be the same between ``Pipfile`` and lock file, however to support the legacy naming convention it is not possible to have an additional group named ``default`` or ``develop`` in the ``Pipfile``.
By default ``pipenv lock`` will lock all known package categorises; to specify locking only specific groups use the ``--categories`` argument.
The command should process the package groups in the order specified.
Example usages::
# single category
pipenv install six --categories prereq
# multiple categories
pipenv sync --categories="prereq packages"
# lock and uninstall examples
pipenv lock --categories="prereq dev-packages"
pipenv uninstall six --categories prereq
.. note:: The ``packages``/``default`` specifiers are used to constrain all other categories just as they have done for ``dev-packages``/``develop`` category. However this is the only way constraints are applied -- the presence of other named groups do not constraint each other, which means it is possible to define conflicting package versions across groups. This may be desired in some use cases where users only are installing groups specific to their system platform.
.. _environment_management:
☤ Environment Management with Pipenv
------------------------------------
The three primary commands you'll use in managing your pipenv environment are
``$ pipenv install``, ``$ pipenv uninstall``, and ``$ pipenv lock``.
.. _pipenv_install:
$ pipenv install
////////////////
``$ pipenv install`` is used for installing packages into the pipenv virtual environment
and updating your Pipfile.
Along with the basic install command, which takes the form::
$ pipenv install [package names]
The user can provide these additional parameters:
- ``--python`` — Performs the installation in a virtualenv using the provided Python interpreter.
.. warning:: None of the above commands should be used together. They are also
**destructive** and will delete your current virtualenv before replacing
it with an appropriately versioned one.
- ``--dev`` — Install both ``develop`` and ``default`` packages from ``Pipfile``.
- ``--system`` — Use the system ``pip`` command rather than the one from your virtualenv.
- ``--deploy`` — Make sure the packages are properly locked in Pipfile.lock, and abort if the lock file is out-of-date.
- ``--ignore-pipfile`` — Ignore the ``Pipfile`` and install from the ``Pipfile.lock``.
- ``--skip-lock`` — Ignore the ``Pipfile.lock`` and install from the ``Pipfile``. In addition, do not write out a ``Pipfile.lock`` reflecting changes to the ``Pipfile``.
.. _pipenv_uninstall:
$ pipenv uninstall
//////////////////
``$ pipenv uninstall`` supports all of the parameters in `pipenv install <#pipenv-install>`_,
as well as two additional options, ``--all`` and ``--all-dev``.
- ``--all`` — This parameter will purge all files from the virtual environment,
but leave the Pipfile untouched.
- ``--all-dev`` — This parameter will remove all of the development packages from
the virtual environment, and remove them from the Pipfile.
.. _pipenv_lock:
$ pipenv lock
/////////////
``$ pipenv lock`` is used to create a ``Pipfile.lock``, which declares **all** dependencies (and sub-dependencies) of your project, their latest available versions, and the current hashes for the downloaded files. This ensures repeatable, and most importantly *deterministic*, builds.
☤ About Shell Configuration
---------------------------
Shells are typically misconfigured for subshell use, so ``$ pipenv shell --fancy`` may produce unexpected results. If this is the case, try ``$ pipenv shell``, which uses "compatibility mode", and will attempt to spawn a subshell despite misconfiguration.
A proper shell configuration only sets environment variables like ``PATH`` during a login session, not during every subshell spawn (as they are typically configured to do). In fish, this looks like this::
if status --is-login
set -gx PATH /usr/local/bin $PATH
end
You should do this for your shell too, in your ``~/.profile`` or ``~/.bashrc`` or wherever appropriate.
.. note:: The shell launched in interactive mode. This means that if your shell reads its configuration from a specific file for interactive mode (e.g. bash by default looks for a ``~/.bashrc`` configuration file for interactive mode), then you'll need to modify (or create) this file.
If you experience issues with ``$ pipenv shell``, just check the ``PIPENV_SHELL`` environment variable, which ``$ pipenv shell`` will use if available. For detail, see :ref:`configuration-with-environment-variables`.
☤ A Note about VCS Dependencies
-------------------------------
You can install packages with pipenv from git and other version control systems using URLs formatted according to the following rule::
<vcs_type>+<scheme>://<location>/<user_or_organization>/<repository>@<branch_or_tag>#egg=<package_name>
The only optional section is the ``@<branch_or_tag>`` section. When using git over SSH, you may use the shorthand vcs and scheme alias ``git+git@<location>:<user_or_organization>/<repository>@<branch_or_tag>#egg=<package_name>``. Note that this is translated to ``git+ssh://git@<location>`` when parsed.
Note that it is **strongly recommended** that you install any version-controlled dependencies in editable mode, using ``pipenv install -e``, in order to ensure that dependency resolution can be performed with an up-to-date copy of the repository each time it is performed, and that it includes all known dependencies.
Below is an example usage which installs the git repository located at ``https://github.com/requests/requests.git`` from tag ``v2.20.1`` as package name ``requests``::
$ pipenv install -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests
Creating a Pipfile for this project...
Installing -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests...
[...snipped...]
Adding -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests to Pipfile's [packages]...
[...]
$ cat Pipfile
[packages]
requests = {git = "https://github.com/requests/requests.git", editable = true, ref = "v2.20.1"}
Valid values for ``<vcs_type>`` include ``git``, ``bzr``, ``svn``, and ``hg``. Valid values for ``<scheme>`` include ``http``, ``https``, ``ssh``, and ``file``. In specific cases you also have access to other schemes: ``svn`` may be combined with ``svn`` as a scheme, and ``bzr`` can be combined with ``sftp`` and ``lp``.
You can read more about pip's implementation of VCS support `here <https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support>`__. For more information about other options available when specifying VCS dependencies, please check the `Pipfile spec <https://github.com/pypa/pipfile>`_.
☤ Pipfile.lock Security Features
--------------------------------
``Pipfile.lock`` takes advantage of some great new security improvements in ``pip``.
By default, the ``Pipfile.lock`` will be generated with the sha256 hashes of each downloaded
package. This will allow ``pip`` to guarantee you're installing what you intend to when
on a compromised network, or downloading dependencies from an untrusted PyPI endpoint.
We highly recommend approaching deployments with promoting projects from a development
environment into production. You can use ``pipenv lock`` to compile your dependencies on
your development environment and deploy the compiled ``Pipfile.lock`` to all of your
production environments for reproducible builds.
.. note::
If you'd like a ``requirements.txt`` output of the lockfile, run ``$ pipenv requirements``.
☤ Pipenv and Docker Containers
------------------------------
In general, you should not have Pipenv inside a linux container image, since
it is a build tool. If you want to use it to build, and install the run time
dependencies for your application, you can use a multistage build for creating
a virtual environment with your dependencies. In this approach,
Pipenv in installed in the base layer, it is then used to create the virtual
environment. In a later stage, in a ``runtime`` layer the virtual environment
is copied from the base layer, the layer containing pipenv and other build
dependencies is discarded.
This results in a smaller image, which can still run your application.
Here is an example ``Dockerfile``, which you can use as a starting point for
doing a multistage build for your application::
FROM docker.io/python:3.9 AS builder
RUN pip install --user pipenv
# Tell pipenv to create venv in the current directory
ENV PIPENV_VENV_IN_PROJECT=1
# Pipfile contains requests
ADD Pipfile.lock Pipfile /usr/src/
WORKDIR /usr/src
# NOTE: If you install binary packages required for a python module, you need
# to install them again in the runtime. For example, if you need to install pycurl
# you need to have pycurl build dependencies libcurl4-gnutls-dev and libcurl3-gnutls
# In the runtime container you need only libcurl3-gnutls
# RUN apt install -y libcurl3-gnutls libcurl4-gnutls-dev
RUN /root/.local/bin/pipenv sync
RUN /usr/src/.venv/bin/python -c "import requests; print(requests.__version__)"
FROM docker.io/python:3.9 AS runtime
RUN mkdir -v /usr/src/.venv
COPY --from=builder /usr/src/.venv/ /usr/src/.venv/
RUN /usr/src/.venv/bin/python -c "import requests; print(requests.__version__)"
# HERE GOES ANY CODE YOU NEED TO ADD TO CREATE YOUR APPLICATION'S IMAGE
# For example
# RUN apt install -y libcurl3-gnutls
# RUN adduser --uid 123123 coolio
# ADD run.py /usr/src/
WORKDIR /usr/src/
USER coolio
CMD ["./.venv/bin/python", "-m", "run.py"]
.. Note::
Pipenv is not meant to run as root. However, in the multistage build above
it is done nevertheless. A calculated risk, since the intermediate image
is discarded.
The runtime image later shows that you should create a user and user it to
run your application.
**Once again, you should not run pipenv as root (or Admin on Windows) normally.
This could lead to breakage of your Python installation, or even your complete
OS.**
When you build an image with this example (assuming requests is found in Pipfile), you
will see that ``requests`` is installed in the ``runtime`` image::
$ sudo docker build --no-cache -t oz/123:0.1 .
Sending build context to Docker daemon 1.122MB
Step 1/12 : FROM docker.io/python:3.9 AS builder
---> 81f391f1a7d7
Step 2/12 : RUN pip install --user pipenv
---> Running in b83ed3c28448
... trimmed ...
---> 848743eb8c65
Step 4/12 : ENV PIPENV_VENV_IN_PROJECT=1
---> Running in 814e6f5fec5b
Removing intermediate container 814e6f5fec5b
---> 20167b4a13e1
Step 5/12 : ADD Pipfile.lock Pipfile /usr/src/
---> c7632cb3d5bd
Step 6/12 : WORKDIR /usr/src
---> Running in 1d75c6cfce10
Removing intermediate container 1d75c6cfce10
---> 2dcae54cc2e5
Step 7/12 : RUN /root/.local/bin/pipenv sync
---> Running in 1a00b326b1ee
Creating a virtualenv for this project...
... trimmed ...
✔ Successfully created virtual environment!
Virtualenv location: /usr/src/.venv
Installing dependencies from Pipfile.lock (fe5a22)...
... trimmed ...
Step 8/12 : RUN /usr/src/.venv/bin/python -c "import requests; print(requests.__version__)"
---> Running in 3a66e3ce4a11
2.27.1
Removing intermediate container 3a66e3ce4a11
---> 1db657d0ac17
Step 9/12 : FROM docker.io/python:3.9 AS runtime
... trimmed ...
Step 12/12 : RUN /usr/src/venv/bin/python -c "import requests; print(requests.__version__)"
---> Running in fa39ba4080c5
2.27.1
Removing intermediate container fa39ba4080c5
---> 2b1c90fd414e
Successfully built 2b1c90fd414e
Successfully tagged oz/123:0.1
docs/commands.md
+85
View File
@@ -0,0 +1,85 @@
.. _commands:
# Pipenv Commands
The commands reference for pipenv (incomplete)
## install
``$ pipenv install`` is used for installing packages into the pipenv virtual environment
and updating your Pipfile and Pipfile.lock.
Along with the basic installation command, which takes the form:
$ pipenv install <package_name>
Running the above will install the package `<package_name>` and add it to the default packages section in the `Pipfile.lock`
The user can provide these additional parameters:
--python=<path/to/pyton> — Performs the installation in a virtualenv using the provided Python interpreter.
warning: The above commands should only be used when initially creating the environment.
The user can provide these additional parameters:
--dev — Install both develop and defaul` package categories from Pipfile.
--categories — Install packages to the category groups specified here.
--system — Install packages to the system site-packages rather than into your virtualenv.
--deploy — Verifies the _meta hash of the lock file is up to date with the ``Pipfile``, aborts install if not.
--ignore-pipfile — Install from the Pipfile.lock and completely ignore Pipfile information.
--skip-lock — Ignore the ``Pipfile.lock`` and install from the ``Pipfile``. In addition, do not write out a ``Pipfile.lock`` reflecting changes to the ``Pipfile``. This is not recommended as you loose the security benefits of lock file hash verification.
General Interface Note:
```{note}
It has been confusing to many users of pipenv that running install will completely relock the lock file.
Based on feedback in pipenv issue reports, we are considering changing install to only relock when adding or changing a package.
For now, to install lock file versions (without modification of the lock file) use: pipenv sync
To modify only specific packages and their subdependencies use: pipenv update <package_name>
```
## sync
``$ pipenv sync`` installs dependencies from the ``Pipfile.lock`` without any alteration to the lockfile.
The user can provide these additional parameters:
--categories — Install packages from the category groups specified here.
## uninstall
``$ pipenv uninstall`` supports all of the parameters in `pipenv install <#pipenv-install>`_,
as well as two additional options, ``--all`` and ``--all-dev``.
- ``--all`` — This parameter will purge all files from the virtual environment,
but leave the Pipfile untouched.
- ``--all-dev`` — This parameter will remove all of the development packages from
the virtual environment, and remove them from the Pipfile.
## lock
``$ pipenv lock`` is used to update all dependencies of ``Pipfile.lock`` to their latest resolved versions based on your ``Pipfile`` specification.
## update
``$ pipenv update <package>`` will update the lock of specified dependency and sub-dependencies only and install the updates.
## upgrade
``$ pipenv upgarde <package>`` will update the lock of specified dependency and sub-dependencies only, but does not modify the environment.
## run
``run`` will run a given command from the virtualenv, with any arguments forwarded (e.g. ``$ pipenv run python`` or ``$ pipenv run pip freeze``).
## shell
``shell`` will spawn a shell with the virtualenv activated. This shell can be deactivated by using ``exit``.
## graph
``graph`` will show you a dependency graph of your installed dependencies where each root node is a specifier from the ``Pipfile``.
## check
``check`` checks for security vulnerabilities and asserts that [PEP 508](https://www.python.org/dev/peps/pep-0508/) requirements are being met by the project's lock file or current environment.
docs/conf.py
+17
View File
@@ -46,12 +46,29 @@ extensions = [
"sphinx.ext.todo",
"sphinx.ext.coverage",
"sphinx.ext.viewcode",
"myst_parser",
"sphinx_click",
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
myst_enable_extensions = [
"amsmath",
"colon_fence",
"deflist",
"dollarmath",
"fieldlist",
"html_admonition",
"html_image",
"linkify",
"replacements",
"smartquotes",
"strikethrough",
"substitution",
"tasklist",
]
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
docs/configuration.md
+34
View File
@@ -0,0 +1,34 @@
# Configuration
## Configuration With Environment Variables
Pipenv comes with a handful of options that can be set via shell environment
variables.
To enable boolean options, create the variable in your shell and assign to it a
true value. Allowed values are: `"1", "true", "yes", "on"`
$ PIPENV_IGNORE_VIRTUALENVS=1
To explicitly disable a boolean option, assign to it a false value (i.e. `"0"`).
```{eval-rst}
.. autoclass:: pipenv.environments.Setting
:members:
```
Also note that `pip` supports additional [environment variables](https://pip.pypa.io/en/stable/user_guide/#environment-variables), if you need additional customization.
For example:
$ PIP_INSTALL_OPTION="-- -DCMAKE_BUILD_TYPE=Release" pipenv install -e .
## Changing Cache Location
You can force pipenv to use a different cache location by setting the environment variable `PIPENV_CACHE_DIR` to the location you wish.
This is useful in the same situations that you would change `PIP_CACHE_DIR` to a different directory.
## Changing Default Python Versions
By default, pipenv will initialize a project using whatever version of python the system has as default.
Besides starting a project with the `--python` flag, you can also use `PIPENV_DEFAULT_PYTHON_VERSION` to specify what version to use when starting a project when `--python` isn't used.
docs/credentials.md
+60
View File
@@ -0,0 +1,60 @@
# Credentials
## Injecting credentials into Pipfile via environment variables
Pipenv will expand environment variables (if defined) in your Pipfile. Quite
useful if you need to authenticate to a private PyPI:
[[source]]
url = "https://$USERNAME:${PASSWORD}@mypypi.example.com/simple"
verify_ssl = true
name = "pypi"
Luckily - pipenv will hash your Pipfile *before* expanding environment
variables (and, helpfully, will substitute the environment variables again when
you install from the lock file - so no need to commit any secrets! Woo!)
If your credentials contain special characters, make sure they are URL-encoded as specified in `rfc3986 <https://datatracker.ietf.org/doc/html/rfc3986>`_.
Environment variables may be specified as `${MY_ENVAR}` or `$MY_ENVAR`.
On Windows, `%MY_ENVAR%` is supported in addition to `${MY_ENVAR}` or `$MY_ENVAR`.
Environment variables in the URL part of requirement specifiers can also be expanded, where the variable must be in the form of `${VAR_NAME}`. Neither `$VAR_NAME` nor `%VAR_NAME%` is acceptable:
[[package]]
requests = {git = "git://${USERNAME}:${PASSWORD}@private.git.com/psf/requests.git", ref = "2.22.0"}
Keep in mind that environment variables are expanded in runtime, leaving the entries in `Pipfile` or `Pipfile.lock` untouched. This is to avoid the accidental leakage of credentials in the source code.
## Injecting credentials through keychain support
Private registries on Google Cloud, Azure and AWS support dynamic credentials using
the keychain implementation. Due to the way the keychain is structured, it might ask
the user for input. Asking the user for input is disabled. This will disable the keychain
support completely, unfortunately.
If you want to work with private registries that use the keychain for authentication, you
can disable the "enforcement of no input".
**Note:** Please be sure that the keychain will really not ask for
input. Otherwise, the process will hang forever!:
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"
[[source]]
url = "https://europe-python.pkg.dev/my-project/python/simple"
verify_ssl = true
name = "private-gcp"
[packages]
flask = "*"
private-test-package = {version = "*", index = "private-gcp"}
[pipenv]
disable_pip_input = false
Above example will install `flask` and a private package `private-test-package` from GCP.
docs/docker.md
+113
View File
@@ -0,0 +1,113 @@
# Docker Containers
In general, you should not have Pipenv inside a linux container image, since
it is a build tool. If you want to use it to build, and install the run time
dependencies for your application, you can use a multistage build for creating
a virtual environment with your dependencies.
In this approach, Pipenv in installed in the base layer, and it is used to create the virtual
environment. In a later stage, in a `runtime` layer the virtual environment
is copied from the base layer, the layer containing pipenv and other build
dependencies is discarded.
This results in a smaller image, which can still run your application.
Here is an example `Dockerfile`, which you can use as a starting point for
doing a multistage build for your application:
FROM docker.io/python:3.9 AS builder
RUN pip install --user pipenv
# Tell pipenv to create venv in the current directory
ENV PIPENV_VENV_IN_PROJECT=1
# Pipfile contains requests
ADD Pipfile.lock Pipfile /usr/src/
WORKDIR /usr/src
# NOTE: If you install binary packages required for a python module, you need
# to install them again in the runtime. For example, if you need to install pycurl
# you need to have pycurl build dependencies libcurl4-gnutls-dev and libcurl3-gnutls
# In the runtime container you need only libcurl3-gnutls
# RUN apt install -y libcurl3-gnutls libcurl4-gnutls-dev
RUN /root/.local/bin/pipenv sync
RUN /usr/src/.venv/bin/python -c "import requests; print(requests.__version__)"
FROM docker.io/python:3.9 AS runtime
RUN mkdir -v /usr/src/.venv
COPY --from=builder /usr/src/.venv/ /usr/src/.venv/
RUN /usr/src/.venv/bin/python -c "import requests; print(requests.__version__)"
# HERE GOES ANY CODE YOU NEED TO ADD TO CREATE YOUR APPLICATION'S IMAGE
# For example
# RUN apt install -y libcurl3-gnutls
# RUN adduser --uid 123123 coolio
# ADD run.py /usr/src/
WORKDIR /usr/src/
USER coolio
CMD ["./.venv/bin/python", "-m", "run.py"]
```{note}
Pipenv is not meant to run as root. However, in the multistage build above
it is done nevertheless. A calculated risk, since the intermediate image
is discarded.
The runtime image later shows that you should create a user and user it to
run your application.
**Once again, you should not run pipenv as root (or Admin on Windows) normally.
This could lead to breakage of your Python installation, or even your complete
OS.**
```
When you build an image with this example (assuming requests is found in Pipfile), you
will see that `requests` is installed in the `runtime` image:
$ sudo docker build --no-cache -t oz/123:0.1 .
Sending build context to Docker daemon 1.122MB
Step 1/12 : FROM docker.io/python:3.9 AS builder
---> 81f391f1a7d7
Step 2/12 : RUN pip install --user pipenv
---> Running in b83ed3c28448
... trimmed ...
---> 848743eb8c65
Step 4/12 : ENV PIPENV_VENV_IN_PROJECT=1
---> Running in 814e6f5fec5b
Removing intermediate container 814e6f5fec5b
---> 20167b4a13e1
Step 5/12 : ADD Pipfile.lock Pipfile /usr/src/
---> c7632cb3d5bd
Step 6/12 : WORKDIR /usr/src
---> Running in 1d75c6cfce10
Removing intermediate container 1d75c6cfce10
---> 2dcae54cc2e5
Step 7/12 : RUN /root/.local/bin/pipenv sync
---> Running in 1a00b326b1ee
Creating a virtualenv for this project...
... trimmed ...
✔ Successfully created virtual environment!
Virtualenv location: /usr/src/.venv
Installing dependencies from Pipfile.lock (fe5a22)...
... trimmed ...
Step 8/12 : RUN /usr/src/.venv/bin/python -c "import requests; print(requests.__version__)"
---> Running in 3a66e3ce4a11
2.27.1
Removing intermediate container 3a66e3ce4a11
---> 1db657d0ac17
Step 9/12 : FROM docker.io/python:3.9 AS runtime
... trimmed ...
Step 12/12 : RUN /usr/src/venv/bin/python -c "import requests; print(requests.__version__)"
---> Running in fa39ba4080c5
2.27.1
Removing intermediate container fa39ba4080c5
---> 2b1c90fd414e
Successfully built 2b1c90fd414e
Successfully tagged oz/123:0.1
docs/index.md
+77
View File
@@ -0,0 +1,77 @@
# Pipenv: Python Dev Workflow for Humans
[![pypi version](https://img.shields.io/pypi/v/pipenv.svg)](https://pypi.python.org/pypi/pipenv) [![MIT License](https://img.shields.io/pypi/l/pipenv.svg)](https://pypi.python.org/pypi/pipenv) [![Supported Versions](https://img.shields.io/pypi/pyversions/pipenv.svg)](https://pypi.python.org/pypi/pipenv)
**Pipenv** is a Python virtualenv management tool that supports a multitude of systems and nicely bridges the gaps between pip, pyenv and virtualenv.
*Linux, macOS, and Windows are all first-class citizens in pipenv.*
It automatically creates and manages a virtualenv for your projects, as well as adds/removes packages from your `Pipfile` as you install/uninstall packages. It also generates the ever-important `Pipfile.lock`, which is used to produce deterministic builds.
Pipenv is primarily meant to provide users and developers of applications with an easy method to setup a working environment.
The problems that Pipenv seeks to solve are multi-faceted:
- You no longer need to use `pip` and `virtualenv` separately. They work together.
- Managing a `requirements.txt` file with package hashes can be problematic. Pipenv uses `Pipfile` and `Pipfile.lock` to separate abstract dependency declarations from the last tested combination.
- Hashes are documented in the lock file, always. Security considerations are put first.
- Strongly encourage the use of the latest versions of dependencies to minimize security risks [arising from outdated components](https://www.owasp.org/index.php/Top_10-2017_A9-Using_Components_with_Known_Vulnerabilities).
- Gives you insight into your dependency graph (e.g. `$ pipenv graph`).
- Streamline development workflow by supporting local customizations with `.env` files.
## Install Pipenv Today!
The recommended way to install pipenv on most platforms is to install from pypi using `pip`:
$ pip install --user pipenv
More detailed installation instructions can be found in the :ref:`installing-pipenv` chapter.
✨🍰✨
## Pipenv Features
- Enables truly *deterministic builds*, while easily specifying *only what you want*.
- Generates and checks file hashes for locked dependencies when installing from `Pipfile.lock`.
- Automatically install required Python version when `pyenv` is available.
- Automatically finds your project home, recursively, by looking for a `Pipfile`.
- Automatically generates a `Pipfile`, if one doesn't exist.
- Automatically creates a virtualenv in a standard customizable location.
- Automatically adds/removes packages to a `Pipfile` when they are installed or uninstalled.
- Automatically loads `.env` files to support customization and overrides.
## Pipenv Documentation
```{toctree}
---
caption: Pipenv Documentation
maxdepth: 2
---
installation
pipfile
cli
commands
configuration
virtualenv
workflows
specifiers
indexes
credentials
shell
docker
scripts
advanced
diagnose
changelog
```
## Contribution Guides
```{toctree}
---
caption: Contributing to Pipenv
maxdepth: 2
---
dev/contributing
```
docs/index.rst
-106
View File
@@ -1,106 +0,0 @@
.. pipenv documentation master file, created by
sphinx-quickstart on Mon Jan 30 13:28:36 2017.
You can adapt this file completely to your liking, but it should at least
contain the root ``toctree`` directive.
Pipenv: Python Dev Workflow for Humans
======================================
.. image:: https://img.shields.io/pypi/v/pipenv.svg
:target: https://pypi.python.org/pypi/pipenv
.. image:: https://img.shields.io/pypi/l/pipenv.svg
:target: https://pypi.python.org/pypi/pipenv
.. image:: https://img.shields.io/pypi/pyversions/pipenv.svg
:target: https://pypi.python.org/pypi/pipenv
---------------
**Pipenv** is a tool that aims to bring the best of all packaging worlds (bundler, composer, npm, cargo, yarn, etc.) to the Python world. *Windows is a first-class citizen, in our world.*
It automatically creates and manages a virtualenv for your projects, as well as adds/removes packages from your ``Pipfile`` as you install/uninstall packages. It also generates the ever-important ``Pipfile.lock``, which is used to produce deterministic builds.
Pipenv is primarily meant to provide users and developers of applications with an easy method to setup a working environment. For the distinction between libraries and applications and the usage of ``setup.py`` vs ``Pipfile`` to define dependencies, see :ref:`pipfile-vs-setuppy`.
.. image:: https://gist.githubusercontent.com/jlusk/855d611bbcfa2b159839db73d07f6ce9/raw/7f5743401809f7e630ee8ff458faa980e19924a0/pipenv.gif
:height: 341px
:width: 654px
:scale: 100 %
:alt: a short animation of pipenv at work
The problems that Pipenv seeks to solve are multi-faceted:
- You no longer need to use ``pip`` and ``virtualenv`` separately. They work together.
- Managing a ``requirements.txt`` file `can be problematic <https://kennethreitz.org/essays/2016/02/25/a-better-pip-workflow>`__, so Pipenv uses ``Pipfile`` and ``Pipfile.lock`` to separate abstract dependency declarations from the last tested combination.
- Hashes are used everywhere, always. Security. Automatically expose security vulnerabilities.
- Strongly encourage the use of the latest versions of dependencies to minimize security risks `arising from outdated components <https://www.owasp.org/index.php/Top_10-2017_A9-Using_Components_with_Known_Vulnerabilities>`_.
- Give you insight into your dependency graph (e.g. ``$ pipenv graph``).
- Streamline development workflow by loading ``.env`` files.
You can quickly play with Pipenv right in your browser:
.. image:: https://cdn.rawgit.com/rootnroll/library/assets/try.svg
:target: https://rootnroll.com/d/pipenv/
:alt: Try in browser
Install Pipenv Today!
---------------------
The recommended way to install pipenv on most platforms is to install from pypi using ``pip``::
$ pip install --user pipenv
Or, if you're using Fedora 28::
$ sudo dnf install pipenv
More detailed installation instructions can be found in the :ref:`installing-pipenv` chapter.
✨🍰✨
.. toctree::
Pipenv Features
-----------------
- Enables truly *deterministic builds*, while easily specifying *only what you want*.
- Generates and checks file hashes for locked dependencies when installing from ``Pipfile.lock``.
- Automatically install required Python version when ``pyenv`` is available.
- Automatically finds your project home, recursively, by looking for a ``Pipfile``.
- Automatically generates a ``Pipfile``, if one doesn't exist.
- Automatically creates a virtualenv in a standard customizable location.
- Automatically adds/removes packages to a ``Pipfile`` when they are installed or uninstalled.
- Automatically loads ``.env`` files to support customization and overrides.
.. include:: quickstart.rst
Further Documentation Guides
----------------------------
.. toctree::
:maxdepth: 2
install
basics
advanced
cli
diagnose
changelog
Contribution Guides
-------------------
.. toctree::
:maxdepth: 2
dev/contributing
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
docs/indexes.md
+82
View File
@@ -0,0 +1,82 @@
# Specifying Package Indexes
The default python package index that is standard for use is [pypi.org](https://pypi.org).
Sometimes there is a need to work with alternative or additional package indexes.
## Index Restricted Packages
Starting in release `2022.3.23` all packages are mapped only to a single package index for security reasons.
All unspecified packages are resolved using the default index source; the default package index is PyPI.
For a specific package to be installed from an alternate package index, you must match the name of the index as in the following example:
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"
[[source]]
url = "https://download.pytorch.org/whl/cu113/"
verify_ssl = false
name = "pytorch"
[dev-packages]
[packages]
torch = {version="*", index="pytorch"}
numpy = {version="*"}
You may install a package such as the example `torch` from the named index `pytorch` using the CLI by running
the following command:
`pipenv install torch --index=pytorch`
Alternatively the index may be specified by full url, and it will be added to the `Pipfile` with a generated name
unless it already exists in which case the existing name with be reused when pinning the package index.
```{note}
In prior versions of `pipenv` you could specify `--extra-index-urls` to the `pip` resolver and avoid
specifically matching the expected index by name. That functionality was deprecated in favor of index restricted
packages, which is a simplifying assumption that is more security mindful. The pip documentation has the following
warning around the `--extra-index-urls` option:
Using this option to search for packages which are not in the main repository (such as private packages) is unsafe,
per a security vulnerability called dependency confusion: an attacker can claim the package on the public repository
in a way that will ensure it gets chosen over the private package.*
```
Should you wish to use an alternative default index other than PyPI: simply do not specify PyPI as one of the
sources in your `Pipfile`. When PyPI is omitted, then any public packages required either directly or
as sub-dependencies must be mirrored onto your private index or they will not resolve properly. This matches the
standard recommendation of `pip` maintainers: "To correctly make a private project installable is to point
--index-url to an index that contains both PyPI and their private projects—which is our recommended best practice."
The above documentation holds true for both `lock` resolution and `sync` of packages. It was suggested that
once the resolution and the lock file are updated, it is theoretically possible to safely scan multiple indexes
for these packages when running `pipenv sync` or `pipenv install --deploy` since it will verify the package
hashes match the allowed hashes that were already captured from a safe locking cycle.
To enable this non-default behavior, add `install_search_all_sources = true` option
to your `Pipfile` in the `pipenv` section::
[pipenv]
install_search_all_sources = true
**Note:** The locking cycle will still require that each package be resolved from a single index. This feature was
requested as a workaround in order to support organizations where not everyone has access to the package sources.
## Using a PyPI Mirror
Should you have access to a mirror of PyPI packages and wish to substitute the default pypi.org index URL with your PyPI mirror,
you may supply the `--pypi-mirror <mirror_url>` argument to select commands:
$ pipenv install --pypi-mirror <mirror_url>
$ pipenv update --pypi-mirror <mirror_url>
$ pipenv sync --pypi-mirror <mirror_url>
$ pipenv lock --pypi-mirror <mirror_url>
$ pipenv uninstall --pypi-mirror <mirror_url>
Note that setting the `PIPENV_PYPI_MIRROR` environment variable is equivalent to passing `--pypi-mirror <mirror_url>`.
docs/install.rst
-257
View File
@@ -1,257 +0,0 @@
.. _virtualenvironments-ref:
=============================
Pipenv & Virtual Environments
=============================
.. image:: https://farm3.staticflickr.com/2943/33485660921_dfc0494739_k_d.jpg
This tutorial walks you through installing and using Python packages.
It will show you how to install and use the necessary tools and make strong
recommendations on best practices. Keep in mind that Python is used for a great
many different purposes, and precisely how you want to manage your dependencies
may change based on how you decide to publish your software. The guidance
presented here is most directly applicable to the development and deployment of
network services (including web applications), but is also very well suited to
managing development and testing environments for any kind of project.
.. Note:: This guide is written for Python 3, however, these instructions
should work fine on Python 2.7—if you are still using it, for some reason.
☤ Make sure you've got Python & pip
===================================
Before you go any further, make sure you have Python and that it's available
from your command line. You can check this by simply running::
$ python --version
You should get some output like ``3.10.8``. If you do not have Python, please
install the latest 3.x version from `python.org`_ or refer to the
`Installing Python`_ section of *The Hitchhiker's Guide to Python*.
.. Note:: If you're newcomer and you get an error like this:
.. code-block:: pycon
>>> python
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'python' is not defined
It's because this command is intended to be run in a *shell* (also called
a *terminal* or *console*). See the Python for Beginners
`getting started tutorial`_ for an introduction to using your operating
system's shell and interacting with Python.
Additionally, you'll need to make sure you have pip available. You can
check this by running::
$ pip --version
pip 22.3.1
If you installed Python from source, with an installer from `python.org`_, via `Homebrew`_ or via `Linuxbrew`_ you should already have pip. If you're on Linux and installed
using your OS package manager, you may have to `install pip <https://pip.pypa.io/en/stable/installing/>`_ separately.
If you plan to install Pipenv using Homebrew or Linuxbrew you can skip this step. The
Homebrew/Linuxbrew installer takes care of pip for you.
.. _getting started tutorial: https://opentechschool.github.io/python-beginners/en/getting_started.html#what-is-python-exactly
.. _python.org: https://python.org
.. _Homebrew: https://brew.sh
.. _Linuxbrew: https://linuxbrew.sh/
.. _Installing Python: http://docs.python-guide.org/en/latest/starting/installation/
.. _installing-pipenv:
☤ Installing Pipenv
===================
It is recommended that users on most platforms should install pipenv from pypi.org using ``pip install pipenv``.
☤ Isolated Installation of Pipenv with Pipx
-------------------------------------------
`Pipx`_ is a tool to help you install and run end-user applications written in Python. It installs applications
into an isolated and clean environment on their own. To install pipx, just run::
$ pip install --user pipx
Once you have ``pipx`` ready on your system, continue to install Pipenv::
$ pipx install pipenv
.. _Pipx: https://pypa.github.io/pipx/
☤ Pragmatic Installation of Pipenv
----------------------------------
If you have a working installation of pip, and maintain certain "tool-chain" type Python modules as global utilities in your user environment, pip `user installs <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_ allow for installation into your home directory. Note that due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow like virtualenv, pipenv, tox, and similar software.
To install::
$ pip install --user pipenv
.. Note:: This does a `user installation`_ to prevent breaking any system-wide
packages. If ``pipenv`` isn't available in your shell after installation,
you'll need to add the `user base`_'s binary directory to your ``PATH``.
On Linux and macOS you can find the user base binary directory by running
``python -m site --user-base`` and adding ``bin`` to the end. For example,
this will typically print ``~/.local`` (with ``~`` expanded to the
absolute path to your home directory) so you'll need to add
``~/.local/bin`` to your ``PATH``. You can set your ``PATH`` permanently by
`modifying ~/.profile`_.
On Windows you can find the user base binary directory by running
``python -m site --user-site`` and replacing ``site-packages`` with
``Scripts``. For example, this could return
``C:\Users\Username\AppData\Roaming\Python36\site-packages`` so you would
need to set your ``PATH`` to include
``C:\Users\Username\AppData\Roaming\Python36\Scripts``. You can set your
user ``PATH`` permanently in the `Control Panel`_. You may need to log
out for the ``PATH`` changes to take effect.
For more information, see the `user installs documentation <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_.
.. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE
.. _user installation: https://pip.pypa.io/en/stable/user_guide/#user-installs
.. _modifying ~/.profile: https://stackoverflow.com/a/14638025
.. _Control Panel: https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx
To upgrade pipenv at any time::
$ pip install --user --upgrade pipenv
☤ Crude Installation of Pipenv
------------------------------
If you don't even have pip installed, you can use this crude installation method, which will bootstrap your whole system::
$ curl https://raw.githubusercontent.com/pypa/pipenv/master/get-pipenv.py | python
☤ Homebrew Installation of Pipenv(Discouraged)
----------------------------------------------
`Homebrew`_ is a popular open-source package management system for macOS. For Linux users, `Linuxbrew`_ is a Linux port of that.
Installing pipenv via Homebrew or Linuxbrew will keep pipenv and all of its dependencies in
an isolated virtual environment so it doesn't interfere with the rest of your
Python installation.
Once you have installed Homebrew or Linuxbrew simply run::
$ brew install pipenv
To upgrade pipenv at any time::
$ brew upgrade pipenv
.. Note::
Homebrew installation is discouraged because each time the Homebrew Python is upgraded, which Pipenv depends on,
users have to re-install Pipenv, and perhaps all virtual environments managed by it.
☤ Installing packages for your project
======================================
Pipenv manages dependencies on a per-project basis. To install packages,
change into your project's directory (or just an empty directory for this
tutorial) and run::
$ cd myproject
$ pipenv install requests
.. Note::
Pipenv is designed to be used by non-privileged OS users. It is not meant
to install or handle packages for the whole OS. Running Pipenv as ``root``
or with ``sudo`` (or ``Admin`` on Windows) is highly discouraged and might
lead to unintend breakage of your OS.
Pipenv will install the excellent `Requests`_ library and create a ``Pipfile``
for you in your project's directory. The ``Pipfile`` is used to track which
dependencies your project needs in case you need to re-install them, such as
when you share your project with others. You should get output similar to this
(although the exact paths shown will vary)::
pipenv install requests
Creating a virtualenv for this project...
Pipfile: /home/user/myproject/Pipfile
sing /home/user/.local/share/virtualenvs/pipenv-Cv0J3wbi/bin/python3.9 (3.9.9) to create virtualenv...
Creating virtual environment...created virtual environment CPython3.9.9.final.0-64 in 1142ms
creator CPython3Posix(dest=/home/user/.local/share/virtualenvs/myproject-R3jRVewK, clear=False, no_vcs_ignore=False, global=False)
seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/home/user/.local/share/virtualenv)
added seed packages: pip==21.3.1, setuptools==60.2.0, wheel==0.37.1
activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
✔ Successfully created virtual environment!
Virtualenv location: /home/user/.local/share/virtualenvs/pms-R3jRVewK
Creating a Pipfile for this project...
Installing requests...
Adding requests to Pipfile's [packages]...
Installation Succeeded
Pipfile.lock not found, creating...
Locking [dev-packages] dependencies...
Locking [packages] dependencies...
Building requirements...
Resolving dependencies...
✔ Success!
Updated Pipfile.lock (fe5a22)!
Installing dependencies from Pipfile.lock (fe5a22)...
🐍 ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ 0/0 — 00:00:00
.. _Requests: https://python-requests.org
☤ Using installed packages
==========================
Now that Requests is installed you can create a simple ``main.py`` file to
use it:
.. code-block:: python
import requests
response = requests.get('https://httpbin.org/ip')
print('Your IP is {0}'.format(response.json()['origin']))
Then you can run this script using ``pipenv run``::
$ pipenv run python main.py
You should get output similar to this:
.. code-block:: text
Your IP is 8.8.8.8
Using ``$ pipenv run`` ensures that your installed packages are available to
your script. It's also possible to spawn a new shell that ensures all commands
have access to your installed packages with ``$ pipenv shell``.
☤ Virtualenv mapping caveat
===========================
- Pipenv automatically maps projects to their specific virtualenvs.
- By default, the virtualenv is stored globally with the name of the project’s root directory plus the hash of the full path to the project's root (e.g., ``my_project-a3de50``).
- Should you change your project's path, you break such a default mapping and pipenv will no longer be able to find and to use the project's virtualenv.
- Customize this behavior with ``PIPENV_CUSTOM_VENV_NAME`` environment variable.
- You might also prefer to set ``PIPENV_VENV_IN_PROJECT=1`` in your .env or .bashrc/.zshrc (or other shell configuration file) for creating the virtualenv inside your project's directory.
☤ Next steps
============
Congratulations, you now know how to get started with pipenv, for additional details refer to the basic and advanced documentation. ✨ 🍰 ✨
docs/installation.md
+166
View File
@@ -0,0 +1,166 @@
# Pipenv Installation
Note: This guide is written for Python 3.7+
## Make sure you have python
Before you go any further, make sure you have Python and that it's available
from your command line. You can check this by simply running:
$ python --version
You should get some output like `3.10.8`. If you do not have Python, please
install the latest 3.x version from [python.org](https://python.org)
Additionally, you will want to make sure you have pip available.
Check this by running:
$ pip --version
pip 22.3.1
If you installed Python from source, with an installer from [python.org], via `Homebrew`_ you likely already have pip.
If you're on Linux and installed using your OS package manager, you may have to [install pip](https://pip.pypa.io/en/stable/installing/) manually.
* [python.org](https://python.org)
* [Installing Python](https://wiki.python.org/moin/BeginnersGuide/Download)
* [pip](https://pypi.org/project/pip/)
## Installing Pipenv
It is recommended that users on most platforms should install pipenv from pypi.org using `pip install pipenv --user`.
### Preferred Installation of Pipenv
If you have a working installation of pip, and maintain certain "tool-chain" type Python modules as global utilities in your user environment, pip `user installs <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_ allow for installation into your home directory. Note that due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow like virtualenv, pipenv, tox, and similar software.
To install:
$ pip install pipenv --user
```{note}
This does a `user installation`_ to prevent breaking any system-wide
packages. If `pipenv` isn't available in your shell after installation,
you'll need to add the user site-packages binary directory to your `PATH`.
On Linux and macOS you can find the user base binary directory by running
`python -m site --user-base` and adding `bin` to the end. For example,
this will typically print `~/.local` (with `~` expanded to the
absolute path to your home directory) so you'll need to add
`~/.local/bin` to your `PATH`. You can set your `PATH` permanently by
`modifying ~/.profile`_.
On Windows you can find the user base binary directory by running
`python -m site --user-site` and replacing `site-packages` with
`Scripts`. For example, this could return
`C:\Users\Username\AppData\Roaming\Python37\site-packages` so you would
need to set your `PATH` to include
`C:\Users\Username\AppData\Roaming\Python37\Scripts`. You can set your
user `PATH` permanently in the `Control Panel`_. You may need to log
out for the `PATH` changes to take effect.
For more information, see the `user installs documentation <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_.
```
.. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE
.. _user installation: https://pip.pypa.io/en/stable/user_guide/#user-installs
.. _modifying ~/.profile: https://stackoverflow.com/a/14638025
To upgrade pipenv at any time:
$ pip install --user --upgrade pipenv
### Homebrew Installation of Pipenv
* [Homebrew](https://brew.sh) is a popular open-source package management system for macOS. For Linux users, `Linuxbrew`_ is a Linux port of that.
Once you have installed Homebrew or Linuxbrew simply run:
$ brew install pipenv
To upgrade pipenv at any time:
$ brew upgrade pipenv
```{note}
Homebrew installation is discouraged because it works better to install pipenv using pip on macOS
```
### Installing packages for your project
Pipenv manages dependencies on a per-project basis. To install packages,
change into your project's directory (or just an empty directory for this
tutorial) and run:
$ cd myproject
$ pipenv install requests
```{note}
Pipenv is designed to be used by non-privileged OS users. It is not meant
to install or handle packages for the whole OS. Running Pipenv as `root`
or with `sudo` (or `Admin` on Windows) is highly discouraged and might
lead to unintend breakage of your OS.
```
Pipenv will install the `requests` library and create a `Pipfile`
for you in your project's directory. The `Pipfile` is used to track which
dependencies your project needs in case you need to re-install them, such as
when you share your project with others.
You should get output similar to this:
Creating a virtualenv for this project...
Pipfile: C:\Users\matte\Projects\pipenv-triage\example\Pipfile
Using C:/Users/matte/AppData/Local/Programs/Python/Python311/python.exe (3.11.2) to create virtualenv...
[ ] Creating virtual environment...created virtual environment CPython3.11.2.final.0-64 in 488ms
creator CPython3Windows(dest=C:\Users\matte\.virtualenvs\example-7V6BFyzL, clear=False, no_vcs_ignore=False, global=False)
seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=C:\Users\matte\AppData\Local\pypa\virtualenv)
added seed packages: pip==23.0, setuptools==67.1.0, wheel==0.38.4
activators BashActivator,BatchActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
Successfully created virtual environment!
Virtualenv location: C:\Users\matte\.virtualenvs\example-7V6BFyzL
Installing requests...
Resolving requests...
Installing...
Adding requests to Pipfile's [packages] ...
Installation Succeeded
Installing dependencies from Pipfile.lock (3b5a71)...
To activate this project's virtualenv, run pipenv shell.
Alternatively, run a command inside the virtualenv with pipenv run.
## Using installed packages
Now that `requests` is installed you can create a simple `main.py` file to use it:
```
import requests
response = requests.get('https://httpbin.org/ip')
print('Your IP is {0}'.format(response.json()['origin']))
```
Then you can run this script using `pipenv run`
$ pipenv run python main.py
You should get output similar to this:
Your IP is 8.8.8.8
Using `$ pipenv run` ensures that your installed packages are available to
your script by activating the virtualenv. It is also possible to spawn a new shell
that ensures all commands have access to your installed packages with `$ pipenv shell`.
## Virtualenv mapping caveat
- Pipenv automatically maps projects to their specific virtualenvs.
- By default, the virtualenv is stored globally with the name of the project’s root directory plus the hash of the full path to the project's root (e.g., `my_project-a3de50`).
- Should you change your project's path, you break such a default mapping and pipenv will no longer be able to find and to use the project's virtualenv.
- Customize this behavior with `PIPENV_CUSTOM_VENV_NAME` environment variable.
- You might also prefer to set `PIPENV_VENV_IN_PROJECT=1` in your .env or .bashrc/.zshrc (or other shell configuration file) for creating the virtualenv inside your project's directory.
docs/pipfile.md
+265
View File
@@ -0,0 +1,265 @@
# Pipfile & Pipfile.lock
`Pipfile` contains the specification for the project top-level requirements and any desired specifiers.
This file is managed by the developers invoking pipenv commands.
The `Pipfile` uses inline tables and the [TOML Spec](https://github.com/toml-lang/toml#user-content-spec>).
`Pipfile.lock` replaces the `requirements.txt` file used in most Python projects and adds
security benefits of tracking the packages hashes that were last locked.
This file is managed automatically through locking actions.
You should add both `Pipfile` and `Pipfile.lock` to the project's source control.
## Example Pipfile
Here is a simple example of a `Pipfile` and the resulting `Pipfile.lock`.
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"
[packages]
Django = "==4.*"
waitress = {version = "*", markers="sys_platform == 'win32'"}
gunicorn = {version = "*", markers="sys_platform == 'linux'"}
[dev-packages]
pytest-cov = "==3.*"
## Example Pipfile.lock
{
"_meta": {
"hash": {
"sha256": "d09f41c21ecfb3b019ace66b61ea1174f99e8b0da0d39e70a5c1cf2363d8b88d"
},
"pipfile-spec": 6,
"requires": {},
"sources": [
{
"name": "pypi",
"url": "https://pypi.org/simple",
"verify_ssl": true
}
]
},
"default": {
"asgiref": {
"hashes": [
"sha256:71e68008da809b957b7ee4b43dbccff33d1b23519fb8344e33f049897077afac",
"sha256:9567dfe7bd8d3c8c892227827c41cce860b368104c3431da67a0c5a65a949506"
],
"markers": "python_version >= '3.7'",
"version": "==3.6.0"
},
"django": {
"hashes": [
"sha256:44f714b81c5f190d9d2ddad01a532fe502fa01c4cb8faf1d081f4264ed15dcd8",
"sha256:f2f431e75adc40039ace496ad3b9f17227022e8b11566f4b363da44c7e44761e"
],
"index": "pypi",
"version": "==4.1.7"
},
"gunicorn": {
"hashes": [
"sha256:9dcc4547dbb1cb284accfb15ab5667a0e5d1881cc443e0677b4882a4067a807e",
"sha256:e0a968b5ba15f8a328fdfd7ab1fcb5af4470c28aaf7e55df02a99bc13138e6e8"
],
"index": "pypi",
"markers": "sys_platform == 'linux'",
"version": "==20.1.0"
},
"setuptools": {
"hashes": [
"sha256:95f00380ef2ffa41d9bba85d95b27689d923c93dfbafed4aecd7cf988a25e012",
"sha256:bb6d8e508de562768f2027902929f8523932fcd1fb784e6d573d2cafac995a48"
],
"markers": "python_version >= '3.7'",
"version": "==67.3.2"
},
"sqlparse": {
"hashes": [
"sha256:0323c0ec29cd52bceabc1b4d9d579e311f3e4961b98d174201d5622a23b85e34",
"sha256:69ca804846bb114d2ec380e4360a8a340db83f0ccf3afceeb1404df028f57268"
],
"markers": "python_version >= '3.5'",
"version": "==0.4.3"
},
"waitress": {
"hashes": [
"sha256:7500c9625927c8ec60f54377d590f67b30c8e70ef4b8894214ac6e4cad233d2a",
"sha256:780a4082c5fbc0fde6a2fcfe5e26e6efc1e8f425730863c04085769781f51eba"
],
"markers": "sys_platform == 'win32'",
"version": "==2.1.2"
}
},
"develop": {
"attrs": {
"hashes": [
"sha256:29e95c7f6778868dbd49170f98f8818f78f3dc5e0e37c0b1f474e3561b240836",
"sha256:c9227bfc2f01993c03f68db37d1d15c9690188323c067c641f1a35ca58185f99"
],
"markers": "python_version >= '3.6'",
"version": "==22.2.0"
},
"coverage": {
"extras": [
"toml"
],
"hashes": [
"sha256:04481245ef966fbd24ae9b9e537ce899ae584d521dfbe78f89cad003c38ca2ab",
"sha256:0c45948f613d5d18c9ec5eaa203ce06a653334cf1bd47c783a12d0dd4fd9c851",
"sha256:10188fe543560ec4874f974b5305cd1a8bdcfa885ee00ea3a03733464c4ca265",
"sha256:218fe982371ac7387304153ecd51205f14e9d731b34fb0568181abaf7b443ba0",
"sha256:29571503c37f2ef2138a306d23e7270687c0efb9cab4bd8038d609b5c2393a3a",
"sha256:2a60d6513781e87047c3e630b33b4d1e89f39836dac6e069ffee28c4786715f5",
"sha256:2bf1d5f2084c3932b56b962a683074a3692bce7cabd3aa023c987a2a8e7612f6",
"sha256:3164d31078fa9efe406e198aecd2a02d32a62fecbdef74f76dad6a46c7e48311",
"sha256:32df215215f3af2c1617a55dbdfb403b772d463d54d219985ac7cd3bf124cada",
"sha256:33d1ae9d4079e05ac4cc1ef9e20c648f5afabf1a92adfaf2ccf509c50b85717f",
"sha256:33ff26d0f6cc3ca8de13d14fde1ff8efe1456b53e3f0273e63cc8b3c84a063d8",
"sha256:38da2db80cc505a611938d8624801158e409928b136c8916cd2e203970dde4dc",
"sha256:3b155caf3760408d1cb903b21e6a97ad4e2bdad43cbc265e3ce0afb8e0057e73",
"sha256:3b946bbcd5a8231383450b195cfb58cb01cbe7f8949f5758566b881df4b33baf",
"sha256:3baf5f126f30781b5e93dbefcc8271cb2491647f8283f20ac54d12161dff080e",
"sha256:4b14d5e09c656de5038a3f9bfe5228f53439282abcab87317c9f7f1acb280352",
"sha256:51b236e764840a6df0661b67e50697aaa0e7d4124ca95e5058fa3d7cbc240b7c",
"sha256:63ffd21aa133ff48c4dff7adcc46b7ec8b565491bfc371212122dd999812ea1c",
"sha256:6a43c7823cd7427b4ed763aa7fb63901ca8288591323b58c9cd6ec31ad910f3c",
"sha256:755e89e32376c850f826c425ece2c35a4fc266c081490eb0a841e7c1cb0d3bda",
"sha256:7a726d742816cb3a8973c8c9a97539c734b3a309345236cd533c4883dda05b8d",
"sha256:7c7c0d0827e853315c9bbd43c1162c006dd808dbbe297db7ae66cd17b07830f0",
"sha256:7ed681b0f8e8bcbbffa58ba26fcf5dbc8f79e7997595bf071ed5430d8c08d6f3",
"sha256:7ee5c9bb51695f80878faaa5598040dd6c9e172ddcf490382e8aedb8ec3fec8d",
"sha256:8361be1c2c073919500b6601220a6f2f98ea0b6d2fec5014c1d9cfa23dd07038",
"sha256:8ae125d1134bf236acba8b83e74c603d1b30e207266121e76484562bc816344c",
"sha256:9817733f0d3ea91bea80de0f79ef971ae94f81ca52f9b66500c6a2fea8e4b4f8",
"sha256:98b85dd86514d889a2e3dd22ab3c18c9d0019e696478391d86708b805f4ea0fa",
"sha256:9ccb092c9ede70b2517a57382a601619d20981f56f440eae7e4d7eaafd1d1d09",
"sha256:9d58885215094ab4a86a6aef044e42994a2bd76a446dc59b352622655ba6621b",
"sha256:b643cb30821e7570c0aaf54feaf0bfb630b79059f85741843e9dc23f33aaca2c",
"sha256:bc7c85a150501286f8b56bd8ed3aa4093f4b88fb68c0843d21ff9656f0009d6a",
"sha256:beeb129cacea34490ffd4d6153af70509aa3cda20fdda2ea1a2be870dfec8d52",
"sha256:c31b75ae466c053a98bf26843563b3b3517b8f37da4d47b1c582fdc703112bc3",
"sha256:c4e4881fa9e9667afcc742f0c244d9364d197490fbc91d12ac3b5de0bf2df146",
"sha256:c5b15ed7644ae4bee0ecf74fee95808dcc34ba6ace87e8dfbf5cb0dc20eab45a",
"sha256:d12d076582507ea460ea2a89a8c85cb558f83406c8a41dd641d7be9a32e1274f",
"sha256:d248cd4a92065a4d4543b8331660121b31c4148dd00a691bfb7a5cdc7483cfa4",
"sha256:d47dd659a4ee952e90dc56c97d78132573dc5c7b09d61b416a9deef4ebe01a0c",
"sha256:d4a5a5879a939cb84959d86869132b00176197ca561c664fc21478c1eee60d75",
"sha256:da9b41d4539eefd408c46725fb76ecba3a50a3367cafb7dea5f250d0653c1040",
"sha256:db61a79c07331e88b9a9974815c075fbd812bc9dbc4dc44b366b5368a2936063",
"sha256:ddb726cb861c3117a553f940372a495fe1078249ff5f8a5478c0576c7be12050",
"sha256:ded59300d6330be27bc6cf0b74b89ada58069ced87c48eaf9344e5e84b0072f7",
"sha256:e2617759031dae1bf183c16cef8fcfb3de7617f394c813fa5e8e46e9b82d4222",
"sha256:e5cdbb5cafcedea04924568d990e20ce7f1945a1dd54b560f879ee2d57226912",
"sha256:ec8e767f13be637d056f7e07e61d089e555f719b387a7070154ad80a0ff31801",
"sha256:ef382417db92ba23dfb5864a3fc9be27ea4894e86620d342a116b243ade5d35d",
"sha256:f2cba5c6db29ce991029b5e4ac51eb36774458f0a3b8d3137241b32d1bb91f06",
"sha256:f5b4198d85a3755d27e64c52f8c95d6333119e49fd001ae5798dac872c95e0f8",
"sha256:ffeeb38ee4a80a30a6877c5c4c359e5498eec095878f1581453202bfacc8fbc2"
],
"markers": "python_version >= '3.7'",
"version": "==7.1.0"
},
"iniconfig": {
"hashes": [
"sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3",
"sha256:b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374"
],
"markers": "python_version >= '3.7'",
"version": "==2.0.0"
},
"packaging": {
"hashes": [
"sha256:714ac14496c3e68c99c29b00845f7a2b85f3bb6f1078fd9f72fd20f0570002b2",
"sha256:b6ad297f8907de0fa2fe1ccbd26fdaf387f5f47c7275fedf8cce89f99446cf97"
],
"markers": "python_version >= '3.7'",
"version": "==23.0"
},
"pluggy": {
"hashes": [
"sha256:4224373bacce55f955a878bf9cfa763c1e360858e330072059e10bad68531159",
"sha256:74134bbf457f031a36d68416e1509f34bd5ccc019f0bcc952c7b909d06b37bd3"
],
"markers": "python_version >= '3.6'",
"version": "==1.0.0"
},
"pytest": {
"hashes": [
"sha256:c7c6ca206e93355074ae32f7403e8ea12163b1163c976fee7d4d84027c162be5",
"sha256:d45e0952f3727241918b8fd0f376f5ff6b301cc0777c6f9a556935c92d8a7d42"
],
"markers": "python_version >= '3.7'",
"version": "==7.2.1"
},
"pytest-cov": {
"hashes": [
"sha256:578d5d15ac4a25e5f961c938b85a05b09fdaae9deef3bb6de9a6e766622ca7a6",
"sha256:e7f0f5b1617d2210a2cabc266dfe2f4c75a8d32fb89eafb7ad9d06f6d076d470"
],
"index": "pypi",
"version": "==3.0.0"
}
}
}
## Importing from requirements.txt
For projects utilizing a `requirements.txt` pipenv can import the contents of this file and create a
`Pipfile` and `Pipfile.lock` for you:
$ pipenv install -r path/to/requirements.txt
If your requirements file has version numbers pinned, you'll likely want to edit the new `Pipfile`
to only keep track of top level dependencies and let `pipenv` keep track of pinning sub-dependencies in the lock file.
## Pipfile.lock Security Features
`Pipfile.lock` leverages the security of package hash validation in `pip`.
The `Pipfile.lock` is generated with the sha256 hashes of each downloaded package.
This guarantees you're installing the same exact packages on any network as the one
where the lock file was last updated, even on untrusted networks.
We recommend designing CI/CD deployments whereby the build does not alter the lock file as a side effect.
In other words, you can use `pipenv lock` or `pipenv upgrade` to adjust your lockfile through local development,
the PR process and approve those lock changes before deploying to production that version of the lockfile.
In other words avoid having your CI issue `lock`, `update`, `upgrade` `uninstall` or `install` commands that will relock.
Note: It is counterintuitive that `pipenv install` re-locks and `pipenv sync` or `pipenv install --deploy` does not.
Based on feedback, we may change this behavior of `pipenv install` to not re-lock in the future but be mindful of this when designing CI pipelines today.
```{admonition} Generate requirements.txt output from lock file
$ pipenv requirements
```
## Package Category Groups
Pipenv supports arbitrarily named package categories in the Pipfile/Pipfile.lock for organizing dependencies into different groups.
Traditionally there were only two package groups, and they were named different between the `Pipfile` and `Pipfile.lock`:
* `packages` in the `Pipfile` corresponds to `default` group in the lockfile.
* `dev-packages` in the `Pipfile` corresponds to `develop` group in the lockfile.
The default/packages group is what you interact with when specifying no particular categories,
whereas the develop/dev-packages group is typically what you interact with when specifying the `--dev` or `-d` flag.
Beginning in `pipenv==2022.10.9` support for named package categories was generalized such that any
non-reserved keywords may be used to create named package groups other than the original groups.
All named categories (other than the special default/develop) will use the category name consistently between the `Pipfile` and `Pipfile.lock`
## General Notes and Recommendations
- Keep both `Pipfile` and `Pipfile.lock` in version control.
- `pipenv install` adds specifiers to `Pipfile` and rebuilds the lock file based on the Pipfile specs, by utilizing the internal resolver of `pip`.
- Not all the required sub-dependencies need be specified in `Pipfile`, instead only add specifiers that make sense for the stability of your project.
Example: `requests` requires `cryptography` but (for reasons) you want to ensure `cryptography` is pinned to a particular version set.
- Consider specifying your target Python version in your `Pipfile`'s `[requires]` section.
For this use either `python_version` in the format `X.Y` (or `X`) or `python_full_version` in `X.Y.Z` format.
- Considering making use of named package categories to further isolate dependency install groups for large monoliths.
docs/quickstart.rst
-34
View File
@@ -1,34 +0,0 @@
Basic Commands and Concepts
///////////////////////////
Pipenv uses a set of commands to manage your Project's dependencies and custom scripts.
It replaces the use of ``Makefile``, direct calls to ``pip`` and ``python -m venv`` or ``virtualenv``.
to create virtual environments and install packages in them.
Pipenv uses two files to do this: ``Pipfile`` and ``Pipfile.lock`` (which will look familiar if you
are used to packages manager like ``yarn`` or ``npm``).
The main commands are:
- ``install`` -
Will create a virtual env and install dependencies (if it does not exist already)
The dependencies will be installed inside.
- ``install package==0.2`` -
Will add the package in version 0.2 to the virtual environment and
to ``Pipfile`` and ``Pipfile.lock``
- ``uninstall`` - Will remove the dependency
- ``lock`` - Regenerate ``Pipfile.lock`` and updates the dependencies inside it.
These are intended to replace ``$ pip install`` usage, as well as manual virtualenv management.
Other Commands
//////////////
- ``graph`` will show you a dependency graph of your installed dependencies.
- ``shell`` will spawn a shell with the virtualenv activated. This shell can be deactivated by using ``exit``.
- ``run`` will run a given command from the virtualenv, with any arguments forwarded (e.g. ``$ pipenv run python`` or ``$ pipenv run pip freeze``).
- ``check`` checks for security vulnerabilities and asserts that `PEP 508 <https://www.python.org/dev/peps/pep-0508/>`_ requirements are being met by the current environment.
docs/requirements.txt
+19 -23
View File
@@ -1,27 +1,23 @@
alabaster==0.7.10
Babel==2.6.0
alabaster==0.7.13
Babel==2.12.1
certifi==2022.12.7
chardet==3.0.4
click==7.0
docutils==0.14
first==2.0.1
idna==2.7
imagesize==1.1.0
Jinja2==2.10
MarkupSafe==1.1.0
pbr==5.1.1
click==8.0.3
docutils==0.17.1
idna==3.4
imagesize==1.4.1
Jinja2==3.1.2
MarkupSafe==2.1.2
myst-parser[linkify]==0.18.1
-e .
Pygments==2.11.2
pythonz-bd==1.11.4
pytz==2018.5
requests==2.20.1
resumable-urlretrieve==0.1.5
six==1.11.0
snowballstemmer==1.2.1
Pygments==2.14.0
pytz==2022.7.1
requests==2.28.2
snowballstemmer==2.2.0
Sphinx==4.5.0
sphinx-click==3.1.0
sphinxcontrib-spelling==4.2.1
sphinxcontrib-websupport==1.1.0
urllib3==1.24.1
virtualenv==16.1.0
virtualenv-clone==0.4.0
sphinx-click==4.4.0
sphinxcontrib-spelling==7.7.0
sphinxcontrib-websupport==1.2.4
urllib3==1.26.14
virtualenv==20.20.0
virtualenv-clone==0.5.7
docs/scripts.md
+51
View File
@@ -0,0 +1,51 @@
# Custom Script Shortcuts
It is possible to create custom shortcuts in the optional `[scripts]` section of your Pipfile.
You can then run `pipenv run <shortcut name>` in your terminal to run the command in the
context of your pipenv virtual environment even if you have not activated the pipenv shell first.
For example, in your Pipfile:
```{code-block}
[scripts]
printspam = "python -c \"print('I am a silly example, no one would need to do this')\""
---
toml
```
And then in your terminal:
$ pipenv run printspam
I am a silly example, no one would need to do this
Commands that expect arguments will also work.
```{code-block}
[scripts]
echospam = "echo I am really a very silly example"
---
toml
```
Invoke script:
$ pipenv run echospam "indeed"
I am really a very silly example indeed
You can also specify pacakge functions as callables such as: `<pathed.module>:<func>`. These can also take arguments.
For example:
[scripts]
my_func_with_args = {call = "package.module:func('arg1', 'arg2')"}
my_func_no_args = {call = "package.module:func()"}
To run the script:
$ pipenv run my_func_with_args
$ pipenv run my_func_no_args
You can display the names and commands of your shortcuts by running `pipenv scripts` in your terminal.
$ pipenv scripts
command script
echospam echo I am really a very silly example
docs/shell.md
+76
View File
@@ -0,0 +1,76 @@
# Environment and Shell Configuration
## Automatic Loading of .env
If a `.env` file is present in your project, `$ pipenv shell` and `$ pipenv run` will automatically load it, for you:
$ cat .env
HELLO=WORLD⏎
$ pipenv run python
Loading .env environment variables...
Python 2.7.13 (default, Jul 18 2017, 09:17:00)
[GCC 4.2.1 Compatible Apple LLVM 8.1.0 (clang-802.0.42)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.environ['HELLO']
'WORLD'
Variable expansion is available in `.env` files using `${VARNAME}` syntax:
$ cat .env
CONFIG_PATH=${HOME}/.config/foo
$ pipenv run python
Loading .env environment variables...
Python 3.7.6 (default, Dec 19 2019, 22:52:49)
[GCC 9.2.1 20190827 (Red Hat 9.2.1-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.environ['CONFIG_PATH']
'/home/kennethreitz/.config/foo'
This is very useful for keeping production credentials out of your codebase.
We do not recommend committing `.env` files into source control!
If your `.env` file is located in a different path or has a different name you may set the `PIPENV_DOTENV_LOCATION` environment variable:
$ PIPENV_DOTENV_LOCATION=/path/to/.env pipenv shell
To prevent pipenv from loading the `.env` file, set the `PIPENV_DONT_LOAD_ENV` environment variable:
$ PIPENV_DONT_LOAD_ENV=1 pipenv shell
See [theskumar/python-dotenv](https://github.com/theskumar/python-dotenv>) for more information on `.env` files.
## Shell Completion
To enable completion in fish, add this to your configuration:
eval (env _PIPENV_COMPLETE=fish_source pipenv)
Alternatively, with zsh, add this to your configuration:
eval "$(_PIPENV_COMPLETE=zsh_source pipenv)"
Alternatively, with bash, add this to your configuration:
eval "$(_PIPENV_COMPLETE=bash_source pipenv)"
Shell completions are now enabled!
## Shell Notes (stale)
Shells are typically misconfigured for subshell use, so `$ pipenv shell --fancy` may produce unexpected results. If this is the case, try `$ pipenv shell`, which uses "compatibility mode", and will attempt to spawn a subshell despite misconfiguration.
A proper shell configuration only sets environment variables like `PATH` during a login session, not during every subshell spawn (as they are typically configured to do). In fish, this looks like this:
if status --is-login
set -gx PATH /usr/local/bin $PATH
end
You should do this for your shell too, in your `~/.profile` or `~/.bashrc` or wherever appropriate.
The shell launched in interactive mode. This means that if your shell reads its configuration from a specific file for interactive mode (e.g. bash by default looks for a `~/.bashrc` configuration file for interactive mode), then you'll need to modify (or create) this file.
docs/specifiers.md
+183
View File
@@ -0,0 +1,183 @@
# Specifiers
## Specifying Versions of a Package
You can specify versions of a package using the [Semantic Versioning scheme](https://semver.org/)
(i.e. `major.minor.micro`).
For example, to install requests you can use:
$ pipenv install requests~=1.2
Pipenv will install version `1.2` and any minor update, but not `2.0`.
This will update your `Pipfile` to reflect this requirement, automatically.
In general, Pipenv uses the same specifier format as pip. However, note that according to [PEP 440](https://www.python.org/dev/peps/pep-0440/),
you can't use versions containing a hyphen or a plus sign.
To make inclusive or exclusive version comparisons you can use:
$ pipenv install "requests>=1.4" # will install a version equal or larger than 1.4.0
$ pipenv install "requests<=2.13" # will install a version equal or lower than 2.13.0
$ pipenv install "requests>2.19" # will install 2.19.1 but not 2.19.0
```{note}
The use of double quotes around the package and version specification (i.e. `"requests>2.19"`) is highly recommended
to avoid issues with `Input and output redirection <https://robots.thoughtbot.com/input-output-redirection-in-the-shell>`_
in Unix-based operating systems.
```
The use of `~=` is preferred over the `==` identifier as the latter prevents pipenv from updating the packages:
$ pipenv install "requests~=2.2" # locks the major version of the package (this is equivalent to using >=2.2, ==2.*)
To avoid installing a specific version you can use the `!=` identifier.
For an in depth explanation of the valid identifiers and more complex use cases check
the [relevant section of PEP-440]( https://www.python.org/dev/peps/pep-0440/#version-specifiers).
## Specifying Versions of Python
To create a new virtualenv, using a specific version of Python you have installed (and
on your `PATH`), use the `--python VERSION` flag, like so:
Use Python 3
$ pipenv --python 3
Use Python3.11
$ pipenv --python 3.11
When given a Python version, like this, Pipenv will automatically scan your system for a Python that matches that given version.
If a `Pipfile` hasn't been created yet, one will be created for you, that looks like this:
[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"
[dev-packages]
[packages]
[requires]
python_version = "3.11"
```{note}
The inclusion of `[requires] python_version = "3.11"` specifies that your application requires this version
of Python, and will be used automatically when running `pipenv install` against this `Pipfile` in the future
(e.g. on other machines). If this is not true, feel free to simply remove this section.
```
If you don't specify a Python version on the command–line, either the `[requires]` `python_full_version` or `python_version` will be selected
automatically, falling back to whatever your system's default `python` installation is, at time of execution.
## Editable Dependencies ( -e . )
You can tell Pipenv to install a path as editable — often this is useful for
the current working directory when working on packages:
$ pipenv install --dev -e .
$ cat Pipfile
...
[dev-packages]
"e1839a8" = {path = ".", editable = true}
...
```{note}
All sub-dependencies will get added to the `Pipfile.lock` as well. Sub-dependencies are **not** added to the
`Pipfile.lock` if you leave the `-e` option out.
```
## VCS Dependencies
VCS dependencies from git and other version control systems using URLs formatted according to the following rule:
<vcs_type>+<scheme>://<location>/<user_or_organization>/<repository>@<branch_or_tag>#egg=<package_name>
The only optional section is the `@<branch_or_tag>` section. When using git over SSH, you may use the shorthand vcs and scheme alias `git+git@<location>:<user_or_organization>/<repository>@<branch_or_tag>#egg=<package_name>`. Note that this is translated to `git+ssh://git@<location>` when parsed.
Note that it is **strongly recommended** that you install any version-controlled dependencies in editable mode, using `pipenv install -e`, in order to ensure that dependency resolution can be performed with an up-to-date copy of the repository each time it is performed, and that it includes all known dependencies.
Below is an example usage which installs the git repository located at `https://github.com/requests/requests.git` from tag `v2.20.1` as package name `requests`:
$ pipenv install -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests
Creating a Pipfile for this project...
Installing -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests...
[...snipped...]
Adding -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests to Pipfile's [packages]...
[...]
$ cat Pipfile
[packages]
requests = {git = "https://github.com/requests/requests.git", editable = true, ref = "v2.20.1"}
Valid values for `<vcs_type>` include `git`, `bzr`, `svn`, and `hg`. Valid values for `<scheme>` include `http`, `https`, `ssh`, and `file`. In specific cases you also have access to other schemes: `svn` may be combined with `svn` as a scheme, and `bzr` can be combined with `sftp` and `lp`.
You can read more about pip's implementation of VCS support `here <https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support>`__. For more information about other options available when specifying VCS dependencies, please check the `Pipfile spec <https://github.com/pypa/pipfile>`_.
## Specifying Package Categories
Originally pipenv supported only two package groups: `packages` and `dev-packages` in the `Pipfile` which mapped to `default` and `develop` in the `Pipfile.lock`. Support for additional named categories has been added such that arbitrary named groups can utilized across the available pipenv commands.
```{note}
The name will be the same between `Pipfile` and lock file, however to support the legacy naming convention it is not possible to have an additional group named `default` or `develop` in the `Pipfile`.
```
By default `pipenv lock` will lock all known package categorises; to specify locking only specific groups use the `--categories` argument.
The command should process the package groups in the order specified.
Example usages:
# single category
pipenv install six --categories prereq
# multiple categories
pipenv sync --categories="prereq packages"
# lock and uninstall examples
pipenv lock --categories="prereq dev-packages"
pipenv uninstall six --categories prereq
```{note}
The `packages`/`default` specifiers are used to constrain all other categories just as they have done
for `dev-packages`/`develop` category. However this is the only way constraints are applied --
the presence of other named groups do not constraint each other,
which means it is possible to define conflicting package versions across groups.
This may be desired in some use cases where users only are installing groups specific to their system platform.
```
## Specifying Basically Anything
If you'd like to specify that a specific package only be installed on certain systems,
you can use [PEP 508 specifiers](https://www.python.org/dev/peps/pep-0508/) to accomplish this.
Here's an example `Pipfile`, which will only install `pywinusb` on Windows systems::
[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"
[packages]
requests = "*"
pywinusb = {version = "*", sys_platform = "== 'win32'"}
Here's a more complex example::
[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
[packages]
unittest2 = {version = ">=1.0,<3.0", markers="python_version < '2.7.9' or (python_version >= '3.0' and python_version < '3.4')"}
Markers provide a ton of flexibility when specifying package requirements.
docs/virtualenv.md
+23
View File
@@ -0,0 +1,23 @@
# virtualenv
## Custom Virtual Environment Location
Pipenv automatically honors the `WORKON_HOME` environment variable, if you
have it set — so you can tell pipenv to store your virtual environments
wherever you want, e.g.:
export WORKON_HOME=~/.venvs
In addition, you can also have Pipenv stick the virtualenv in `project/.venv` by setting the `PIPENV_VENV_IN_PROJECT` environment variable.
## Virtual Environment Name
The virtualenv name created by Pipenv may be different from what you were expecting.
Dangerous characters (i.e. `$`!*@"` as well as space, line feed, carriage return,
and tab) are converted to underscores. Additionally, the full path to the current
folder is encoded into a "slug value" and appended to ensure the virtualenv name
is unique.
Pipenv supports a arbitrary custom name for the virtual environment set at `PIPENV_CUSTOM_VENV_NAME`.
The logical place to specify this would be in a user's `.env` file in the root of the project, which gets loaded by pipenv when it is invoked.
docs/workflows.md
+43
View File
@@ -0,0 +1,43 @@
# Pipenv Workflows
Clone / create project repository::
$ cd myproject
Install from `Pipfile.lock`, if there is one::
$ pipenv sync
Add a package to your project, recalibrating entire lock file using the Pipfile specifiers::
$ pipenv install <package>
- Note: This will create a `Pipfile` if one doesn't exist. If one does exist, it will automatically be edited with the new package you provided, the lock file updated and the new dependencies installed.
- `pipenv install` is fully compatible with `pip install` package specifiers, for which the full documentation can be found `here <https://pip.pypa.io/en/stable/user_guide/#installing-packages>`__.
- Additional arguments may be supplied to `pip` by supplying `pipenv` with `--extra-pip-args`.
Update everything (equivalent to `pipenv lock && pipenv sync`::
$ pipenv update
Update and install just the relevant package and its sub-dependencies::
$ pipenv update <package>
Update in the Pipfile/lockfile just the relevant package and its sub-dependencies::
$ pipenv upgrade <package>
Find out what's changed upstream::
$ pipenv update --outdated
Determine the virtualenv PATH::
$ pipenv --venv
Activate the Pipenv shell::
$ pipenv shell
- Note: This will spawn a new shell subprocess, which can be deactivated by using `exit`.
pipenv/environments.py
-1
View File
@@ -107,7 +107,6 @@ class Setting:
"""
def __init__(self) -> None:
self.USING_DEFAULT_PYTHON = True
"""Use the default Python"""
pipenv/installers.py
-1
View File
@@ -11,7 +11,6 @@ from pipenv.vendor import attr
@attr.s
class Version:
major = attr.ib()
minor = attr.ib()
patch = attr.ib()
pipenv/project.py
-1
View File
@@ -487,7 +487,6 @@ class Project:
@property
def pipfile_location(self) -> str:
from pipenv.utils.pipfile import find_pipfile
if self.s.PIPENV_PIPFILE: