diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 07438c7fad..587dece403 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -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) ============================ diff --git a/Pipfile b/Pipfile index f148374499..f1c2263cc6 100644 --- a/Pipfile +++ b/Pipfile @@ -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" diff --git a/Pipfile.lock b/Pipfile.lock index 7ff8e123ca..72e3b73094 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -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" }, diff --git a/docs/advanced.rst b/docs/advanced.rst index e4f49d5735..8551697586 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -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 - - $ pipenv update --pypi-mirror - - $ pipenv sync --pypi-mirror - - $ pipenv lock --pypi-mirror - - $ pipenv uninstall --pypi-mirror - -Alternatively, setting the ``PIPENV_PYPI_MIRROR`` environment variable is equivalent to passing ``--pypi-mirror ``. - -☤ 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 `_. - -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 `_ 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 `_ (Editor Integration) - `PyCharm `_ (Editor Integration) -Works in progress: - -- `Sublime Text `_ (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 `_ 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 `` 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: ``:``. 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 `_ project, in order to do so. - -Also note that `pip itself supports 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. diff --git a/docs/basics.rst b/docs/basics.rst deleted file mode 100644 index b634b76025..0000000000 --- a/docs/basics.rst +++ /dev/null @@ -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 `__. -- Note that the ``Pipfile`` uses the `TOML 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 - -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 `` 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 `_ -(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 `_ - 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:: - - +:////@#egg= - -The only optional section is the ``@`` section. When using git over SSH, you may use the shorthand vcs and scheme alias ``git+git@:/@#egg=``. Note that this is translated to ``git+ssh://git@`` 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 ```` include ``git``, ``bzr``, ``svn``, and ``hg``. Valid values for ```` 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 `__. For more information about other options available when specifying VCS dependencies, please check the `Pipfile spec `_. - - -☤ 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 diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000000..0eafd60265 --- /dev/null +++ b/docs/commands.md @@ -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 + +Running the above will install the package `` and add it to the default packages section in the `Pipfile.lock` + +The user can provide these additional parameters: + + --python= — 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 +``` + +## 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 `` will update the lock of specified dependency and sub-dependencies only and install the updates. + + +## upgrade + +``$ pipenv upgarde `` 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. diff --git a/docs/conf.py b/docs/conf.py index 6f4cddf9e9..a03988b063 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,12 +46,29 @@ "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: # diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000000..b5c1602085 --- /dev/null +++ b/docs/configuration.md @@ -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. diff --git a/docs/credentials.md b/docs/credentials.md new file mode 100644 index 0000000000..44f4ace26c --- /dev/null +++ b/docs/credentials.md @@ -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 `_. + +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. diff --git a/docs/docker.md b/docs/docker.md new file mode 100644 index 0000000000..bee4798a2c --- /dev/null +++ b/docs/docker.md @@ -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 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..b2a2fd3c79 --- /dev/null +++ b/docs/index.md @@ -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 +``` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index b3db3d5da4..0000000000 --- a/docs/index.rst +++ /dev/null @@ -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 `__, 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 `_. -- 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` diff --git a/docs/indexes.md b/docs/indexes.md new file mode 100644 index 0000000000..99ad039b61 --- /dev/null +++ b/docs/indexes.md @@ -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 ` argument to select commands: + + $ pipenv install --pypi-mirror + + $ pipenv update --pypi-mirror + + $ pipenv sync --pypi-mirror + + $ pipenv lock --pypi-mirror + + $ pipenv uninstall --pypi-mirror + +Note that setting the `PIPENV_PYPI_MIRROR` environment variable is equivalent to passing `--pypi-mirror `. diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 8a50629902..0000000000 --- a/docs/install.rst +++ /dev/null @@ -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 "", line 1, in - 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 `_ 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 `_ 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 `_. - - -.. _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. ✨ 🍰 ✨ diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000000..89b7b9385a --- /dev/null +++ b/docs/installation.md @@ -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 `_ 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 `_. +``` + +.. _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. diff --git a/docs/pipfile.md b/docs/pipfile.md new file mode 100644 index 0000000000..b17a59c3e3 --- /dev/null +++ b/docs/pipfile.md @@ -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. diff --git a/docs/quickstart.rst b/docs/quickstart.rst deleted file mode 100644 index 29a9aff681..0000000000 --- a/docs/quickstart.rst +++ /dev/null @@ -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 `_ requirements are being met by the current environment. diff --git a/docs/requirements.txt b/docs/requirements.txt index 2d000c10a1..25d201062f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -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 diff --git a/docs/scripts.md b/docs/scripts.md new file mode 100644 index 0000000000..06fe0c5777 --- /dev/null +++ b/docs/scripts.md @@ -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 ` 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: `:`. 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 diff --git a/docs/shell.md b/docs/shell.md new file mode 100644 index 0000000000..4f5dcebccd --- /dev/null +++ b/docs/shell.md @@ -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. diff --git a/docs/specifiers.md b/docs/specifiers.md new file mode 100644 index 0000000000..758dc72cba --- /dev/null +++ b/docs/specifiers.md @@ -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 `_ + 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: + + +:////@#egg= + +The only optional section is the `@` section. When using git over SSH, you may use the shorthand vcs and scheme alias `git+git@:/@#egg=`. Note that this is translated to `git+ssh://git@` 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 `` include `git`, `bzr`, `svn`, and `hg`. Valid values for `` 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 `__. For more information about other options available when specifying VCS dependencies, please check the `Pipfile spec `_. + + +## 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. diff --git a/docs/virtualenv.md b/docs/virtualenv.md new file mode 100644 index 0000000000..a925beb374 --- /dev/null +++ b/docs/virtualenv.md @@ -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. diff --git a/docs/workflows.md b/docs/workflows.md new file mode 100644 index 0000000000..471d763517 --- /dev/null +++ b/docs/workflows.md @@ -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 + +- 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 `__. +- 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 + +Update in the Pipfile/lockfile just the relevant package and its sub-dependencies:: + + $ pipenv upgrade + +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`. diff --git a/pipenv/environments.py b/pipenv/environments.py index 3a0b1b6c93..6fb39a6ed9 100644 --- a/pipenv/environments.py +++ b/pipenv/environments.py @@ -107,7 +107,6 @@ class Setting: """ def __init__(self) -> None: - self.USING_DEFAULT_PYTHON = True """Use the default Python""" diff --git a/pipenv/installers.py b/pipenv/installers.py index 2e49da9602..52c2293ec2 100644 --- a/pipenv/installers.py +++ b/pipenv/installers.py @@ -11,7 +11,6 @@ @attr.s class Version: - major = attr.ib() minor = attr.ib() patch = attr.ib() diff --git a/pipenv/project.py b/pipenv/project.py index 802c144e20..3e7e8f532d 100644 --- a/pipenv/project.py +++ b/pipenv/project.py @@ -487,7 +487,6 @@ def register_proper_name(self, name: str) -> None: @property def pipfile_location(self) -> str: - from pipenv.utils.pipfile import find_pipfile if self.s.PIPENV_PIPFILE: