From 0b6222bccfb5ca234eb1095e9796cd69517d4ed6 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 18 Feb 2023 00:35:19 -0500 Subject: [PATCH 01/32] Begin reviewing the basics docs. --- docs/basics.rst | 221 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 161 insertions(+), 60 deletions(-) diff --git a/docs/basics.rst b/docs/basics.rst index b634b76025..a4457abc5d 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -5,16 +5,17 @@ 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. +This document covers the most basic features of Pipenv. -☤ Example Pipfile & Pipfile.lock +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. +``Pipfile`` contains the top level specifiers for the requirements of the project dependencies. + +``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. + +You should add both ``Pipfile`` and ``Pipfile.lock`` to the project's source control. .. _example_files: @@ -26,16 +27,17 @@ Example Pipfile :: [[source]] - url = "https://pypi.python.org/simple" + url = "https://pypi.org/simple" verify_ssl = true name = "pypi" [packages] - requests = "*" - + Django = "==4.*" + waitress = {version = "*", markers="sys_platform == 'win32'"} + gunicorn = {version = "*", markers="sys_platform == 'linux'"} [dev-packages] - pytest = "*" + pytest-cov = "==3.*" Example Pipfile.lock @@ -46,94 +48,193 @@ Example Pipfile.lock { "_meta": { "hash": { - "sha256": "8d14434df45e0ef884d6c3f6e8048ba72335637a8631cc44792f52fd20b6f97a" + "sha256": "d09f41c21ecfb3b019ace66b61ea1174f99e8b0da0d39e70a5c1cf2363d8b88d" }, - "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, + "pipfile-spec": 6, "requires": {}, "sources": [ { "name": "pypi", - "url": "https://pypi.python.org/simple", + "url": "https://pypi.org/simple", "verify_ssl": true } ] }, "default": { - "certifi": { + "asgiref": { "hashes": [ - "sha256:54a07c09c586b0e4c619f02a5e94e36619da8e2b053e20f594348c0611803704", - "sha256:40523d2efb60523e113b44602298f0960e900388cf3bb6043f645cf57ea9e3f5" + "sha256:71e68008da809b957b7ee4b43dbccff33d1b23519fb8344e33f049897077afac", + "sha256:9567dfe7bd8d3c8c892227827c41cce860b368104c3431da67a0c5a65a949506" ], - "version": "==2017.7.27.1" + "markers": "python_version >= '3.7'", + "version": "==3.6.0" }, - "chardet": { + "django": { "hashes": [ - "sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691", - "sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae" + "sha256:44f714b81c5f190d9d2ddad01a532fe502fa01c4cb8faf1d081f4264ed15dcd8", + "sha256:f2f431e75adc40039ace496ad3b9f17227022e8b11566f4b363da44c7e44761e" ], - "version": "==3.0.4" + "index": "pypi", + "version": "==4.1.7" }, - "idna": { + "gunicorn": { "hashes": [ - "sha256:8c7309c718f94b3a625cb648ace320157ad16ff131ae0af362c9f21b80ef6ec4", - "sha256:2c6a5de3089009e3da7c5dde64a141dbc8551d5b7f6cf4ed7c2568d0cc520a8f" + "sha256:9dcc4547dbb1cb284accfb15ab5667a0e5d1881cc443e0677b4882a4067a807e", + "sha256:e0a968b5ba15f8a328fdfd7ab1fcb5af4470c28aaf7e55df02a99bc13138e6e8" ], - "version": "==2.6" + "index": "pypi", + "markers": "sys_platform == 'linux'", + "version": "==20.1.0" }, - "requests": { + "setuptools": { "hashes": [ - "sha256:6a1b267aa90cac58ac3a765d067950e7dbbf75b1da07e895d1f594193a40a38b", - "sha256:9c443e7324ba5b85070c4a818ade28bfabedf16ea10206da1132edaa6dda237e" + "sha256:95f00380ef2ffa41d9bba85d95b27689d923c93dfbafed4aecd7cf988a25e012", + "sha256:bb6d8e508de562768f2027902929f8523932fcd1fb784e6d573d2cafac995a48" ], - "version": "==2.18.4" + "markers": "python_version >= '3.7'", + "version": "==67.3.2" }, - "urllib3": { + "sqlparse": { "hashes": [ - "sha256:06330f386d6e4b195fbfc736b297f58c5a892e4440e54d294d7004e3a9bbea1b", - "sha256:cc44da8e1145637334317feebd728bd869a35285b93cbb4cca2577da7e62db4f" + "sha256:0323c0ec29cd52bceabc1b4d9d579e311f3e4961b98d174201d5622a23b85e34", + "sha256:69ca804846bb114d2ec380e4360a8a340db83f0ccf3afceeb1404df028f57268" ], - "version": "==1.22" + "markers": "python_version >= '3.5'", + "version": "==0.4.3" + }, + "waitress": { + "hashes": [ + "sha256:7500c9625927c8ec60f54377d590f67b30c8e70ef4b8894214ac6e4cad233d2a", + "sha256:780a4082c5fbc0fde6a2fcfe5e26e6efc1e8f425730863c04085769781f51eba" + ], + "markers": "sys_platform == 'win32'", + "version": "==2.1.2" } }, "develop": { - "py": { + "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:2ccb79b01769d99115aa600d7eed99f524bf752bba8f041dc1c184853514655a", - "sha256:0f2d585d22050e90c7d293b6451c83db097df77871974d90efd5a30dc12fcde3" + "sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3", + "sha256:b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374" ], - "version": "==1.4.34" + "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:b84f554f8ddc23add65c411bf112b2d88e2489fd45f753b1cae5936358bdf314", - "sha256:f46e49e0340a532764991c498244a60e3a37d7424a532b3ff1a6a7653f1a403a" + "sha256:c7c6ca206e93355074ae32f7403e8ea12163b1163c976fee7d4d84027c162be5", + "sha256:d45e0952f3727241918b8fd0f376f5ff6b301cc0777c6f9a556935c92d8a7d42" + ], + "markers": "python_version >= '3.7'", + "version": "==7.2.1" + }, + "pytest-cov": { + "hashes": [ + "sha256:578d5d15ac4a25e5f961c938b85a05b09fdaae9deef3bb6de9a6e766622ca7a6", + "sha256:e7f0f5b1617d2210a2cabc266dfe2f4c75a8d32fb89eafb7ad9d06f6d076d470" ], - "version": "==3.2.2" + "index": "pypi", + "version": "==3.0.0" } } } -☤ 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. +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 Pip's internal resolver. +- Not all of 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 or version set. +- Specify your target Python version in your ``Pipfile``'s ``[requires]`` section. +Use either ``python_version`` in the format ``X.Y`` (or ``X``) or ``python_full_version`` 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 `_. +- The ``Pipfile`` uses the `TOML Spec `_. From 1c3329ca19beb658380d8dade32a67f54d842bdb Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sun, 19 Feb 2023 03:02:06 -0500 Subject: [PATCH 02/32] Check in delta --- docs/basics.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/basics.rst b/docs/basics.rst index a4457abc5d..17f544573c 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -247,13 +247,13 @@ Clone / create project repository:: Install from Pipfile, if there is one:: - $ pipenv install + $ pipenv sync 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. +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. Next, activate the Pipenv shell:: From dc619e2257abfd3d69eecf5f96bb3427de9e5cc3 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 25 Feb 2023 21:57:15 -0500 Subject: [PATCH 03/32] More doc revisions. --- docs/basics.rst | 102 ++++++++++++++++++++++++++---------------------- 1 file changed, 56 insertions(+), 46 deletions(-) diff --git a/docs/basics.rst b/docs/basics.rst index 17f544573c..827f626b18 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -7,13 +7,16 @@ Basic Usage of Pipenv This document covers the most basic features of Pipenv. -Example Pipfile & Pipfile.lock +Pipfile & Pipfile.lock -------------------------------- -``Pipfile`` contains the top level specifiers for the requirements of the project dependencies. +``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 `_. ``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. @@ -228,66 +231,74 @@ 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 Pip's internal resolver. +- ``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 of 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 or version set. -- Specify your target Python version in your ``Pipfile``'s ``[requires]`` section. -Use either ``python_version`` in the format ``X.Y`` (or ``X``) or ``python_full_version`` in ``X.Y.Z`` format. -- ``pipenv install`` is fully compatible with ``pip install`` syntax, for which the full documentation can be found `here `__. -- The ``Pipfile`` uses the `TOML Spec `_. +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. +- ``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``. +- Considering making use of named package categories to further isolate dependency install groups for large monoliths. - -☤ Example Pipenv Workflow +☤ Example Pipenv Workflows ------------------------- Clone / create project repository:: $ cd myproject -Install from Pipfile, if there is one:: +Install from ``Pipfile.lock``, if there is one:: $ pipenv sync -Or, add a package to your new project:: +Add a package to your project, recalibrating entire lock file using the Pipfile specifiers:: $ 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, the lock file updated and the new dependencies installed. +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. -Next, activate the Pipenv shell:: +Update everything (equivalent to ``pipenv lock && pipenv sync``:: - $ pipenv shell - $ python --version + $ pipenv update -This will spawn a new shell subprocess, which can be deactivated by using ``exit``. +Update and install just the relevant package and its sub-dependencies:: -.. _initialization: + $ pipenv update -☤ Example Pipenv Upgrade Workflow ---------------------------------- +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``. -- 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. +For projects utilizing a ``requirements.txt`` pipenv can import the contents of this file and create a +``Pipfile`` and `Pipfile.lock`` for you:: -You can also specify ``$ pipenv install -r path/to/requirements.txt`` to import a requirements file. + $ 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 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! +to only keep track of top level dependencies and let ``pipenv`` keep track of pinning sub-dependencies in the lock file. .. _specifying_versions: -☤ Specifying Versions of a Package +Specifying Versions of a Package ---------------------------------- You can specify versions of a package using the `Semantic Versioning scheme `_ @@ -415,9 +426,6 @@ Example usages:: ☤ 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 @@ -439,8 +447,8 @@ The user can provide these additional parameters: 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. + - ``--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`` — 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``. @@ -486,7 +494,7 @@ If you experience issues with ``$ pipenv shell``, just check the ``PIPENV_SHELL` ☤ A Note about VCS Dependencies ------------------------------- -You can install packages with pipenv from git and other version control systems using URLs formatted according to the following rule:: +VCS dependencies from git and other version control systems using URLs formatted according to the following rule:: +:////@#egg= @@ -515,15 +523,17 @@ You can read more about pip's implementation of VCS support `here Date: Sat, 25 Feb 2023 22:35:24 -0500 Subject: [PATCH 04/32] Split apart basics docs. --- docs/basics.rst | 654 ------------------------- docs/commands.rst | 50 ++ docs/docker.rst | 113 +++++ docs/index.rst | 9 +- docs/{install.rst => installation.rst} | 46 +- docs/pipfile.rst | 254 ++++++++++ docs/shell.rst | 15 + docs/specifiers.rst | 146 ++++++ docs/workflows.rst | 45 ++ 9 files changed, 636 insertions(+), 696 deletions(-) delete mode 100644 docs/basics.rst create mode 100644 docs/commands.rst create mode 100644 docs/docker.rst rename docs/{install.rst => installation.rst} (86%) create mode 100644 docs/pipfile.rst create mode 100644 docs/shell.rst create mode 100644 docs/specifiers.rst create mode 100644 docs/workflows.rst diff --git a/docs/basics.rst b/docs/basics.rst deleted file mode 100644 index 827f626b18..0000000000 --- a/docs/basics.rst +++ /dev/null @@ -1,654 +0,0 @@ -.. _basic: - -Basic Usage of Pipenv -===================== - -.. image:: https://farm4.staticflickr.com/3931/33173826122_b7ee8f1a26_k_d.jpg - -This document covers the most basic features of Pipenv. - -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 `_. - -``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_files: - -Here is a simple example of a ``Pipfile`` and the resulting ``Pipfile.lock``. - -Example Pipfile -/////////////// - -:: - - [[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" - } - } - } - - -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 of 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. -- ``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``. -- Considering making use of named package categories to further isolate dependency install groups for large monoliths. - - -☤ Example 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. - -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``. - - -☤ 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. - -.. _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 ------------------------------------- - -.. _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`` — 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`` — 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 -------------------------------- - -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 `_. - - -☤ 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. - -.. 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.rst b/docs/commands.rst new file mode 100644 index 0000000000..df51fe06b6 --- /dev/null +++ b/docs/commands.rst @@ -0,0 +1,50 @@ +.. _commands: + +# Pipenv Commands + +The commands reference for pipenv (incomplete) + +## 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`` — 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`` — 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. + + diff --git a/docs/docker.rst b/docs/docker.rst new file mode 100644 index 0000000000..dce4892e5b --- /dev/null +++ b/docs/docker.rst @@ -0,0 +1,113 @@ +.. _docker: + +# 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/index.rst b/docs/index.rst index b3db3d5da4..d6a8388a99 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -84,8 +84,13 @@ Further Documentation Guides .. toctree:: :maxdepth: 2 - install - basics + installation + workflows + pipfile + commands + specifiers + shell + docker advanced cli diagnose diff --git a/docs/install.rst b/docs/installation.rst similarity index 86% rename from docs/install.rst rename to docs/installation.rst index 8a50629902..29f2cb2478 100644 --- a/docs/install.rst +++ b/docs/installation.rst @@ -1,10 +1,6 @@ -.. _virtualenvironments-ref: +.. _installation: -============================= -Pipenv & Virtual Environments -============================= - -.. image:: https://farm3.staticflickr.com/2943/33485660921_dfc0494739_k_d.jpg +# Pipenv Installation This tutorial walks you through installing and using Python packages. @@ -16,12 +12,10 @@ 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. +.. Note:: This guide is written for Python 3.7+ -☤ Make sure you've got Python & pip -=================================== +## Make sure you have 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:: @@ -70,22 +64,7 @@ Homebrew/Linuxbrew installer takes care of pip for you. ☤ 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/ +It is recommended that users on most platforms should install pipenv from pypi.org using ``pip install pipenv --user``. ☤ Pragmatic Installation of Pipenv @@ -95,7 +74,7 @@ If you have a working installation of pip, and maintain certain "tool-chain" typ To install:: - $ pip install --user pipenv + $ 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, @@ -131,13 +110,6 @@ 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) ---------------------------------------------- @@ -249,9 +221,3 @@ have access to your installed packages with ``$ pipenv shell``. - 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/pipfile.rst b/docs/pipfile.rst new file mode 100644 index 0000000000..3e24cbc9ea --- /dev/null +++ b/docs/pipfile.rst @@ -0,0 +1,254 @@ +.. _pipfile: + +# 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 `_. + +``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_files: + +Here is a simple example of a ``Pipfile`` and the resulting ``Pipfile.lock``. + +## Example Pipfile:: + + [[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. + +.. note:: + + If you'd like a ``requirements.txt`` output of the lockfile, run ``$ pipenv requirements``. + + +## 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 of 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/shell.rst b/docs/shell.rst new file mode 100644 index 0000000000..0b308e73de --- /dev/null +++ b/docs/shell.rst @@ -0,0 +1,15 @@ +# 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`. diff --git a/docs/specifiers.rst b/docs/specifiers.rst new file mode 100644 index 0000000000..1f63df31a6 --- /dev/null +++ b/docs/specifiers.rst @@ -0,0 +1,146 @@ +.. _specifiers: + +## 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.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.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. + + +## 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. diff --git a/docs/workflows.rst b/docs/workflows.rst new file mode 100644 index 0000000000..9b8d490bdf --- /dev/null +++ b/docs/workflows.rst @@ -0,0 +1,45 @@ +.. _workflows: + +# 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``. From 685e34892a555cbe0c43f3b116f53df69ed51688 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 25 Feb 2023 23:07:42 -0500 Subject: [PATCH 05/32] Refactor based on building docs --- Pipfile | 1 + Pipfile.lock | 515 ++++++++++++++++++++++++++---------------- docs/commands.rst | 50 ---- docs/conf.py | 19 ++ docs/docker.rst | 113 --------- docs/installation.rst | 223 ------------------ docs/pipfile.rst | 254 --------------------- docs/quickstart.rst | 34 --- docs/shell.rst | 15 -- docs/specifiers.rst | 146 ------------ 10 files changed, 342 insertions(+), 1028 deletions(-) delete mode 100644 docs/commands.rst delete mode 100644 docs/docker.rst delete mode 100644 docs/installation.rst delete mode 100644 docs/pipfile.rst delete mode 100644 docs/quickstart.rst delete mode 100644 docs/shell.rst delete mode 100644 docs/specifiers.rst diff --git a/Pipfile b/Pipfile index 78d413b275..e4e1503841 100644 --- a/Pipfile +++ b/Pipfile @@ -21,6 +21,7 @@ gunicorn = {version = "*", markers="sys_platform == 'linux'"} parse = "*" importlib-metadata = {version = "*", markers="python_version < '3.8'"} colorama= {version = "*", markers="sys_platform == 'win32'"} +myst-parser = "*" [packages] diff --git a/Pipfile.lock b/Pipfile.lock index 9e9aad580e..a94bafa55f 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "48857cc762ed1cb9fe4ec09aaf5d90931deb1e6875a09f7a09bf6fc5f438b402" + "sha256": "54bb9b3f0185e90e259131a3037b83616f16530ae9bebc331da17f6b5eefdf0f" }, "pipfile-spec": 6, "requires": {}, @@ -17,10 +17,11 @@ "develop": { "alabaster": { "hashes": [ - "sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359", - "sha256:a661d72d58e6ea8a57f7a86e37d86716863ee5e92788398526d58b26a4e4dc02" + "sha256:1ee19aca801bbabb5ba3f5f258e4422dfa86f82f3e9cefb0859b283cdd7f62a3", + "sha256:a27a4a084d5e690e16e01e03ad2b2e552c61a65469419b907243193de1a84ae2" ], - "version": "==0.7.12" + "markers": "python_version >= '3.6'", + "version": "==0.7.13" }, "arpeggio": { "hashes": [ @@ -54,29 +55,42 @@ }, "beautifulsoup4": { "hashes": [ - "sha256:58d5c3d29f5a36ffeb94f02f0d786cd53014cf9b3b3951d42e0080d8a9498d30", - "sha256:ad9aa55b65ef2808eb405f46cf74df7fcb7044d5cbc26487f96eb2ef2e436693" + "sha256:0e79446b10b3ecb499c1556f7e228a53e64a2bfcebd455f370d8927cb5b59e39", + "sha256:bc4bdda6717de5a2987436fb8d72f45dc90dd856bdfd512a1314ce90349a0106" ], "markers": "python_full_version >= '3.6.0'", - "version": "==4.11.1" + "version": "==4.11.2" }, "black": { "hashes": [ - "sha256:0b945a5a1e5a5321f884de0061d5a8585d947c9b608e37b6d26ceee4dfdf4b62", - "sha256:4db1d8027ce7ae53f0ccf02b0be0b8808fefb291d6cb1543420f4165d96d364c", - "sha256:5fb7641d442ede92538bc70fa0201f884753a7d0f62f26c722b7b00301b95902", - "sha256:63330069d8ec909cf4e2c4d43a7f00aeb03335430ef9fec6cd2328e6ebde8a77", - "sha256:793c9176beb2adf295f6b863d9a4dc953fe2ac359ca3da108d71d14cb2c09e52", - "sha256:85dede655442f5e246e7abd667fe07e14916897ba52f3640b5489bf11f7dbf67", - "sha256:88288a645402106b8eb9f50d7340ae741e16240bb01c2eed8466549153daa96e", - "sha256:88ec25a64063945b4591b6378bead544c5d3260de1c93ad96f3ad2d76ddd76fd", - "sha256:8dff6f0157e47fbbeada046fca144b6557d3be2fb2602d668881cd179f04a352", - "sha256:ca658b69260a18bf7aa0b0a6562dbbd304a737487d1318998aaca5a75901fd2c", - "sha256:ddbf9da228726d46f45c29024263e160d41030a415097254817d65127012d1a2", - "sha256:e88e4b633d64b9e7adc4a6b922f52bb204af9f90d7b1e3317e6490f2b598b1ea" + "sha256:0052dba51dec07ed029ed61b18183942043e00008ec65d5028814afaab9a22fd", + "sha256:0680d4380db3719ebcfb2613f34e86c8e6d15ffeabcf8ec59355c5e7b85bb555", + "sha256:121ca7f10b4a01fd99951234abdbd97728e1240be89fde18480ffac16503d481", + "sha256:162e37d49e93bd6eb6f1afc3e17a3d23a823042530c37c3c42eeeaf026f38468", + "sha256:2a951cc83ab535d248c89f300eccbd625e80ab880fbcfb5ac8afb5f01a258ac9", + "sha256:2bf649fda611c8550ca9d7592b69f0637218c2369b7744694c5e4902873b2f3a", + "sha256:382998821f58e5c8238d3166c492139573325287820963d2f7de4d518bd76958", + "sha256:49f7b39e30f326a34b5c9a4213213a6b221d7ae9d58ec70df1c4a307cf2a1580", + "sha256:57c18c5165c1dbe291d5306e53fb3988122890e57bd9b3dcb75f967f13411a26", + "sha256:7a0f701d314cfa0896b9001df70a530eb2472babb76086344e688829efd97d32", + "sha256:8178318cb74f98bc571eef19068f6ab5613b3e59d4f47771582f04e175570ed8", + "sha256:8b70eb40a78dfac24842458476135f9b99ab952dd3f2dab738c1881a9b38b753", + "sha256:9880d7d419bb7e709b37e28deb5e68a49227713b623c72b2b931028ea65f619b", + "sha256:9afd3f493666a0cd8f8df9a0200c6359ac53940cbde049dcb1a7eb6ee2dd7074", + "sha256:a29650759a6a0944e7cca036674655c2f0f63806ddecc45ed40b7b8aa314b651", + "sha256:a436e7881d33acaf2536c46a454bb964a50eff59b21b51c6ccf5a40601fbef24", + "sha256:a59db0a2094d2259c554676403fa2fac3473ccf1354c1c63eccf7ae65aac8ab6", + "sha256:a8471939da5e824b891b25751955be52ee7f8a30a916d570a5ba8e0f2eb2ecad", + "sha256:b0bd97bea8903f5a2ba7219257a44e3f1f9d00073d6cc1add68f0beec69692ac", + "sha256:b6a92a41ee34b883b359998f0c8e6eb8e99803aa8bf3123bf2b2e6fec505a221", + "sha256:bb460c8561c8c1bec7824ecbc3ce085eb50005883a6203dcfb0122e95797ee06", + "sha256:bfffba28dc52a58f04492181392ee380e95262af14ee01d4bc7bb1b1c6ca8d27", + "sha256:c1c476bc7b7d021321e7d93dc2cbd78ce103b84d5a4cf97ed535fbc0d6660648", + "sha256:c91dfc2c2a4e50df0026f88d2215e166616e0c80e86004d0003ece0488db2739", + "sha256:e6663f91b6feca5d06f2ccd49a10f254f9298cc1f7f49c46e498a0771b507104" ], "markers": "python_version >= '3.7'", - "version": "==23.1a1" + "version": "==23.1.0" }, "bs4": { "hashes": [ @@ -102,11 +116,97 @@ }, "charset-normalizer": { "hashes": [ - "sha256:5a3d016c7c547f69d6f81fb0db9449ce888b418b5b9952cc5e6e66843e9dd845", - "sha256:83e9a75d1911279afd89352c68b45348559d1fc0506b054b346651b5e7fee29f" + "sha256:00d3ffdaafe92a5dc603cb9bd5111aaa36dfa187c8285c543be562e61b755f6b", + "sha256:024e606be3ed92216e2b6952ed859d86b4cfa52cd5bc5f050e7dc28f9b43ec42", + "sha256:0298eafff88c99982a4cf66ba2efa1128e4ddaca0b05eec4c456bbc7db691d8d", + "sha256:02a51034802cbf38db3f89c66fb5d2ec57e6fe7ef2f4a44d070a593c3688667b", + "sha256:083c8d17153ecb403e5e1eb76a7ef4babfc2c48d58899c98fcaa04833e7a2f9a", + "sha256:0a11e971ed097d24c534c037d298ad32c6ce81a45736d31e0ff0ad37ab437d59", + "sha256:0bf2dae5291758b6f84cf923bfaa285632816007db0330002fa1de38bfcb7154", + "sha256:0c0a590235ccd933d9892c627dec5bc7511ce6ad6c1011fdf5b11363022746c1", + "sha256:0f438ae3532723fb6ead77e7c604be7c8374094ef4ee2c5e03a3a17f1fca256c", + "sha256:109487860ef6a328f3eec66f2bf78b0b72400280d8f8ea05f69c51644ba6521a", + "sha256:11b53acf2411c3b09e6af37e4b9005cba376c872503c8f28218c7243582df45d", + "sha256:12db3b2c533c23ab812c2b25934f60383361f8a376ae272665f8e48b88e8e1c6", + "sha256:14e76c0f23218b8f46c4d87018ca2e441535aed3632ca134b10239dfb6dadd6b", + "sha256:16a8663d6e281208d78806dbe14ee9903715361cf81f6d4309944e4d1e59ac5b", + "sha256:292d5e8ba896bbfd6334b096e34bffb56161c81408d6d036a7dfa6929cff8783", + "sha256:2c03cc56021a4bd59be889c2b9257dae13bf55041a3372d3295416f86b295fb5", + "sha256:2e396d70bc4ef5325b72b593a72c8979999aa52fb8bcf03f701c1b03e1166918", + "sha256:2edb64ee7bf1ed524a1da60cdcd2e1f6e2b4f66ef7c077680739f1641f62f555", + "sha256:31a9ddf4718d10ae04d9b18801bd776693487cbb57d74cc3458a7673f6f34639", + "sha256:356541bf4381fa35856dafa6a965916e54bed415ad8a24ee6de6e37deccf2786", + "sha256:358a7c4cb8ba9b46c453b1dd8d9e431452d5249072e4f56cfda3149f6ab1405e", + "sha256:37f8febc8ec50c14f3ec9637505f28e58d4f66752207ea177c1d67df25da5aed", + "sha256:39049da0ffb96c8cbb65cbf5c5f3ca3168990adf3551bd1dee10c48fce8ae820", + "sha256:39cf9ed17fe3b1bc81f33c9ceb6ce67683ee7526e65fde1447c772afc54a1bb8", + "sha256:3ae1de54a77dc0d6d5fcf623290af4266412a7c4be0b1ff7444394f03f5c54e3", + "sha256:3b590df687e3c5ee0deef9fc8c547d81986d9a1b56073d82de008744452d6541", + "sha256:3e45867f1f2ab0711d60c6c71746ac53537f1684baa699f4f668d4c6f6ce8e14", + "sha256:3fc1c4a2ffd64890aebdb3f97e1278b0cc72579a08ca4de8cd2c04799a3a22be", + "sha256:4457ea6774b5611f4bed5eaa5df55f70abde42364d498c5134b7ef4c6958e20e", + "sha256:44ba614de5361b3e5278e1241fda3dc1838deed864b50a10d7ce92983797fa76", + "sha256:4a8fcf28c05c1f6d7e177a9a46a1c52798bfe2ad80681d275b10dcf317deaf0b", + "sha256:4b0d02d7102dd0f997580b51edc4cebcf2ab6397a7edf89f1c73b586c614272c", + "sha256:502218f52498a36d6bf5ea77081844017bf7982cdbe521ad85e64cabee1b608b", + "sha256:503e65837c71b875ecdd733877d852adbc465bd82c768a067badd953bf1bc5a3", + "sha256:5995f0164fa7df59db4746112fec3f49c461dd6b31b841873443bdb077c13cfc", + "sha256:59e5686dd847347e55dffcc191a96622f016bc0ad89105e24c14e0d6305acbc6", + "sha256:601f36512f9e28f029d9481bdaf8e89e5148ac5d89cffd3b05cd533eeb423b59", + "sha256:608862a7bf6957f2333fc54ab4399e405baad0163dc9f8d99cb236816db169d4", + "sha256:62595ab75873d50d57323a91dd03e6966eb79c41fa834b7a1661ed043b2d404d", + "sha256:70990b9c51340e4044cfc394a81f614f3f90d41397104d226f21e66de668730d", + "sha256:71140351489970dfe5e60fc621ada3e0f41104a5eddaca47a7acb3c1b851d6d3", + "sha256:72966d1b297c741541ca8cf1223ff262a6febe52481af742036a0b296e35fa5a", + "sha256:74292fc76c905c0ef095fe11e188a32ebd03bc38f3f3e9bcb85e4e6db177b7ea", + "sha256:761e8904c07ad053d285670f36dd94e1b6ab7f16ce62b9805c475b7aa1cffde6", + "sha256:772b87914ff1152b92a197ef4ea40efe27a378606c39446ded52c8f80f79702e", + "sha256:79909e27e8e4fcc9db4addea88aa63f6423ebb171db091fb4373e3312cb6d603", + "sha256:7e189e2e1d3ed2f4aebabd2d5b0f931e883676e51c7624826e0a4e5fe8a0bf24", + "sha256:7eb33a30d75562222b64f569c642ff3dc6689e09adda43a082208397f016c39a", + "sha256:81d6741ab457d14fdedc215516665050f3822d3e56508921cc7239f8c8e66a58", + "sha256:8499ca8f4502af841f68135133d8258f7b32a53a1d594aa98cc52013fff55678", + "sha256:84c3990934bae40ea69a82034912ffe5a62c60bbf6ec5bc9691419641d7d5c9a", + "sha256:87701167f2a5c930b403e9756fab1d31d4d4da52856143b609e30a1ce7160f3c", + "sha256:88600c72ef7587fe1708fd242b385b6ed4b8904976d5da0893e31df8b3480cb6", + "sha256:8ac7b6a045b814cf0c47f3623d21ebd88b3e8cf216a14790b455ea7ff0135d18", + "sha256:8b8af03d2e37866d023ad0ddea594edefc31e827fee64f8de5611a1dbc373174", + "sha256:8c7fe7afa480e3e82eed58e0ca89f751cd14d767638e2550c77a92a9e749c317", + "sha256:8eade758719add78ec36dc13201483f8e9b5d940329285edcd5f70c0a9edbd7f", + "sha256:911d8a40b2bef5b8bbae2e36a0b103f142ac53557ab421dc16ac4aafee6f53dc", + "sha256:93ad6d87ac18e2a90b0fe89df7c65263b9a99a0eb98f0a3d2e079f12a0735837", + "sha256:95dea361dd73757c6f1c0a1480ac499952c16ac83f7f5f4f84f0658a01b8ef41", + "sha256:9ab77acb98eba3fd2a85cd160851816bfce6871d944d885febf012713f06659c", + "sha256:9cb3032517f1627cc012dbc80a8ec976ae76d93ea2b5feaa9d2a5b8882597579", + "sha256:9cf4e8ad252f7c38dd1f676b46514f92dc0ebeb0db5552f5f403509705e24753", + "sha256:9d9153257a3f70d5f69edf2325357251ed20f772b12e593f3b3377b5f78e7ef8", + "sha256:a152f5f33d64a6be73f1d30c9cc82dfc73cec6477ec268e7c6e4c7d23c2d2291", + "sha256:a16418ecf1329f71df119e8a65f3aa68004a3f9383821edcb20f0702934d8087", + "sha256:a60332922359f920193b1d4826953c507a877b523b2395ad7bc716ddd386d866", + "sha256:a8d0fc946c784ff7f7c3742310cc8a57c5c6dc31631269876a88b809dbeff3d3", + "sha256:ab5de034a886f616a5668aa5d098af2b5385ed70142090e2a31bcbd0af0fdb3d", + "sha256:c22d3fe05ce11d3671297dc8973267daa0f938b93ec716e12e0f6dee81591dc1", + "sha256:c2ac1b08635a8cd4e0cbeaf6f5e922085908d48eb05d44c5ae9eabab148512ca", + "sha256:c512accbd6ff0270939b9ac214b84fb5ada5f0409c44298361b2f5e13f9aed9e", + "sha256:c75ffc45f25324e68ab238cb4b5c0a38cd1c3d7f1fb1f72b5541de469e2247db", + "sha256:c95a03c79bbe30eec3ec2b7f076074f4281526724c8685a42872974ef4d36b72", + "sha256:cadaeaba78750d58d3cc6ac4d1fd867da6fc73c88156b7a3212a3cd4819d679d", + "sha256:cd6056167405314a4dc3c173943f11249fa0f1b204f8b51ed4bde1a9cd1834dc", + "sha256:db72b07027db150f468fbada4d85b3b2729a3db39178abf5c543b784c1254539", + "sha256:df2c707231459e8a4028eabcd3cfc827befd635b3ef72eada84ab13b52e1574d", + "sha256:e62164b50f84e20601c1ff8eb55620d2ad25fb81b59e3cd776a1902527a788af", + "sha256:e696f0dd336161fca9adbb846875d40752e6eba585843c768935ba5c9960722b", + "sha256:eaa379fcd227ca235d04152ca6704c7cb55564116f8bc52545ff357628e10602", + "sha256:ebea339af930f8ca5d7a699b921106c6e29c617fe9606fa7baa043c1cdae326f", + "sha256:f4c39b0e3eac288fedc2b43055cfc2ca7a60362d0e5e87a637beac5d801ef478", + "sha256:f5057856d21e7586765171eac8b9fc3f7d44ef39425f85dbcccb13b3ebea806c", + "sha256:f6f45710b4459401609ebebdbcfb34515da4fc2aa886f95107f556ac69a9147e", + "sha256:f97e83fa6c25693c7a35de154681fcc257c1c41b38beb0304b9c4d2d9e164479", + "sha256:f9d0c5c045a3ca9bedfc35dca8526798eb91a07aa7a2c0fee134c6c6f321cbd7", + "sha256:ff6f3db31555657f3163b15a6b7c6938d08df7adbfc9dd13d9d19edad678f1e8" ], "markers": "python_full_version >= '3.6.0'", - "version": "==2.1.1" + "version": "==3.0.1" }, "click": { "hashes": [ @@ -135,60 +235,60 @@ "toml" ], "hashes": [ - "sha256:04691b8e832a900ed15f5bcccc2008fc2d1c8e7411251fd7d1422a84e1d72841", - "sha256:1a613d60be1a02c7a5184ea5c4227f48c08e0635608b9c17ae2b17efef8f2501", - "sha256:1d732b5dcafed67d81c5b5a0c404c31a61e13148946a3b910a340f72fdd1ec95", - "sha256:2b31f7f246dbff339b3b76ee81329e3eca5022ce270c831c65e841dbbb40115f", - "sha256:312fd77258bf1044ef4faa82091f2e88216e4b62dcf1a461d3e917144c8b09b7", - "sha256:321316a7b979892a13c148a9d37852b5a76f26717e4b911b606a649394629532", - "sha256:36c1a1b6d38ebf8a4335f65226ec36b5d6fd67743fdcbad5c52bdcd46c4f5842", - "sha256:38f281bb9bdd4269c451fed9451203512dadefd64676f14ed1e82c77eb5644fc", - "sha256:3a2d81c95d3b02638ee6ae647edc79769fd29bf5e9e5b6b0c29040579f33c260", - "sha256:3d40ad86a348c79c614e2b90566267dd6d45f2e6b4d2bfb794d78ea4a4b60b63", - "sha256:3d72e3d20b03e63bd27b1c4d6b754cd93eca82ecc5dd77b99262d5f64862ca35", - "sha256:3fbb59f84c8549113dcdce7c6d16c5731fe53651d0b46c0a25a5ebc7bb655869", - "sha256:405d8528a0ea07ca516d9007ecad4e1bd10e2eeef27411c6188d78c4e2dfcddc", - "sha256:420f10c852b9a489cf5a764534669a19f49732a0576c76d9489ebf287f81af6d", - "sha256:426895ac9f2938bec193aa998e7a77a3e65d3e46903f348e794b4192b9a5b61e", - "sha256:4438ba539bef21e288092b30ea2fc30e883d9af5b66ebeaf2fd7c25e2f074e39", - "sha256:46db409fc0c3ee5c859b84c7de9cb507166287d588390889fdf06a1afe452e16", - "sha256:483e120ea324c7fced6126bb9bf0535c71e9233d29cbc7e2fc4560311a5f8a32", - "sha256:4d7be755d7544dac2b9814e98366a065d15a16e13847eb1f5473bb714483391e", - "sha256:4e97b21482aa5c21e049e4755c95955ad71fb54c9488969e2f17cf30922aa5f6", - "sha256:5f44ba7c07e0aa4a7a2723b426c254e952da82a33d65b4a52afae4bef74a4203", - "sha256:62e5b942378d5f0b87caace567a70dc634ddd4d219a236fa221dc97d2fc412c8", - "sha256:7c669be1b01e4b2bf23aa49e987d9bedde0234a7da374a9b77ca5416d7c57002", - "sha256:7d47d666e17e57ef65fefc87229fde262bd5c9039ae8424bc53aa2d8f07dc178", - "sha256:7e184aa18f921b612ea08666c25dd92a71241c8ed40917f2824219c92289b8c7", - "sha256:80583c536e7e010e301002088919d4ea90566d1789ee02551574fdf3faa275ae", - "sha256:8217f73faf08623acb25fb2affd5d20cbcd8185213db308e46a37e6fd6a56a49", - "sha256:87d95eea58fb71f69b4f1c761099a19e0e9cb27d45dc1cc7042523128ee56337", - "sha256:8bd466135fb07f693dbdd999a5569ffbc0590e9c64df859243162f0ebee950c8", - "sha256:8e133ca2f8141b415ff396ba789bdeffdea8ff9a5c7fc9996ccf591d7d40ee93", - "sha256:8e6c0ca447b557a32642f22d0987be37950eda51c4f19fc788cebc99426284b6", - "sha256:9de96025ce25b9f4e744fbe558a003e673004af255da9b1f6ec243720ac5deeb", - "sha256:a27a8dca0dc6f0944ed9fd83c556d862e227a5cd4220e62af5d4c750389938f0", - "sha256:a2d4f68e4fa286fb6b00d58a1e87c79840e289d3f6e5dcb912ad7b0fbd9629fb", - "sha256:a6e1c77ff6f10eab496fbbcdaa7dfae84968928a0aadc43ce3c3453cec29bd79", - "sha256:a7b018811a0e1d3869d8d0600849953acd355a3a29c6bee0fbd24d7772bcc0a2", - "sha256:a99b2f2dd1236e8d9dc35974a3dc298a408cdfd512b0bb2451798cff1ce63408", - "sha256:ac1033942851bf01f28c76318155ea92d6648aecb924cab81fa23781d095e9ab", - "sha256:b6936cd38757dd323fefc157823e46436610328f0feb1419a412316f24b77f36", - "sha256:b6eab230b18458707b5c501548e997e42934b1c189fb4d1b78bf5aacc1c6a137", - "sha256:bcb57d175ff0cb4ff97fc547c74c1cb8d4c9612003f6d267ee78dad8f23d8b30", - "sha256:c1f02d016b9b6b5ad21949a21646714bfa7b32d6041a30f97674f05d6d6996e3", - "sha256:c40aaf7930680e0e5f3bd6d3d3dc97a7897f53bdce925545c4b241e0c5c3ca6a", - "sha256:c5e1874c601128cf54c1d4b471e915658a334fbc56d7b3c324ddc7511597ea82", - "sha256:c8805673b1953313adfc487d5323b4c87864e77057944a0888c98dd2f7a6052f", - "sha256:da458bdc9b0bcd9b8ca85bc73148631b18cc8ba03c47f29f4c017809990351aa", - "sha256:dcb708ab06f3f4dfc99e9f84821c9120e5f12113b90fad132311a2cb97525379", - "sha256:dfafc350f43fd7dc67df18c940c3b7ed208ebb797abe9fb3047f0c65be8e4c0f", - "sha256:e8931af864bd599c6af626575a02103ae626f57b34e3af5537d40b040d33d2ad", - "sha256:efa9d943189321f67f71070c309aa6f6130fa1ec35c9dfd0da0ed238938ce573", - "sha256:fd22ee7bff4b5c37bb6385efee1c501b75e29ca40286f037cb91c2182d1348ce" + "sha256:049806ae2df69468c130f04f0fab4212c46b34ba5590296281423bb1ae379df2", + "sha256:08e3dd256b8d3e07bb230896c8c96ec6c5dffbe5a133ba21f8be82b275b900e8", + "sha256:0f03c229f1453b936916f68a47b3dfb5e84e7ad48e160488168a5e35115320c8", + "sha256:171dd3aa71a49274a7e4fc26f5bc167bfae5a4421a668bc074e21a0522a0af4b", + "sha256:1856a8c4aa77eb7ca0d42c996d0ca395ecafae658c1432b9da4528c429f2575c", + "sha256:28563a35ef4a82b5bc5160a01853ce62b9fceee00760e583ffc8acf9e3413753", + "sha256:2c15bd09fd5009f3a79c8b3682b52973df29761030b692043f9834fc780947c4", + "sha256:2c9fffbc39dc4a6277e1525cab06c161d11ee3995bbc97543dc74fcec33e045b", + "sha256:2d7daf3da9c7e0ed742b3e6b4de6cc464552e787b8a6449d16517b31bbdaddf5", + "sha256:32e6a730fd18b2556716039ab93278ccebbefa1af81e6aa0c8dba888cf659e6e", + "sha256:34d7211be69b215ad92298a962b2cd5a4ef4b17c7871d85e15d3d1b6dc8d8c96", + "sha256:358d3bce1468f298b19a3e35183bdb13c06cdda029643537a0cc37e55e74e8f1", + "sha256:3713a8ec18781fda408f0e853bf8c85963e2d3327c99a82a22e5c91baffcb934", + "sha256:40785553d68c61e61100262b73f665024fd2bb3c6f0f8e2cd5b13e10e4df027b", + "sha256:4655ecd813f4ba44857af3e9cffd133ab409774e9d2a7d8fdaf4fdfd2941b789", + "sha256:465ea431c3b78a87e32d7d9ea6d081a1003c43a442982375cf2c247a19971961", + "sha256:4b8fd32f85b256fc096deeb4872aeb8137474da0c0351236f93cbedc359353d6", + "sha256:4c1153a6156715db9d6ae8283480ae67fb67452aa693a56d7dae9ffe8f7a80da", + "sha256:577a8bc40c01ad88bb9ab1b3a1814f2f860ff5c5099827da2a3cafc5522dadea", + "sha256:59a427f8a005aa7254074719441acb25ac2c2f60c1f1026d43f846d4254c1c2f", + "sha256:5e29a64e9586194ea271048bc80c83cdd4587830110d1e07b109e6ff435e5dbc", + "sha256:74cd60fa00f46f28bd40048d6ca26bd58e9bee61d2b0eb4ec18cea13493c003f", + "sha256:7efa21611ffc91156e6f053997285c6fe88cfef3fb7533692d0692d2cb30c846", + "sha256:7f992b32286c86c38f07a8b5c3fc88384199e82434040a729ec06b067ee0d52c", + "sha256:875b03d92ac939fbfa8ae74a35b2c468fc4f070f613d5b1692f9980099a3a210", + "sha256:88ae5929f0ef668b582fd7cad09b5e7277f50f912183cf969b36e82a1c26e49a", + "sha256:8d5302eb84c61e758c9d68b8a2f93a398b272073a046d07da83d77b0edc8d76b", + "sha256:90e7a4cbbb7b1916937d380beb1315b12957b8e895d7d9fb032e2038ac367525", + "sha256:9240a0335365c29c968131bdf624bb25a8a653a9c0d8c5dbfcabf80b59c1973c", + "sha256:932048364ff9c39030c6ba360c31bf4500036d4e15c02a2afc5a76e7623140d4", + "sha256:93db11da6e728587e943dff8ae1b739002311f035831b6ecdb15e308224a4247", + "sha256:971b49dbf713044c3e5f6451b39f65615d4d1c1d9a19948fa0f41b0245a98765", + "sha256:9cc9c41aa5af16d845b53287051340c363dd03b7ef408e45eec3af52be77810d", + "sha256:9dbb21561b0e04acabe62d2c274f02df0d715e8769485353ddf3cf84727e31ce", + "sha256:a6ceeab5fca62bca072eba6865a12d881f281c74231d2990f8a398226e1a5d96", + "sha256:ad12c74c6ce53a027f5a5ecbac9be20758a41c85425c1bbab7078441794b04ee", + "sha256:b09dd7bef59448c66e6b490cc3f3c25c14bc85d4e3c193b81a6204be8dd355de", + "sha256:bd67df6b48db18c10790635060858e2ea4109601e84a1e9bfdd92e898dc7dc79", + "sha256:bf9e02bc3dee792b9d145af30db8686f328e781bd212fdef499db5e9e4dd8377", + "sha256:bfa065307667f1c6e1f4c3e13f415b0925e34e56441f5fda2c84110a4a1d8bda", + "sha256:c160e34e388277f10c50dc2c7b5e78abe6d07357d9fe7fcb2f3c156713fd647e", + "sha256:c243b25051440386179591a8d5a5caff4484f92c980fb6e061b9559da7cc3f64", + "sha256:c3c4beddee01c8125a75cde3b71be273995e2e9ec08fbc260dd206b46bb99969", + "sha256:cd38140b56538855d3d5722c6d1b752b35237e7ea3f360047ce57f3fade82d98", + "sha256:d7f2a7df523791e6a63b40360afa6792a11869651307031160dc10802df9a252", + "sha256:da32526326e8da0effb452dc32a21ffad282c485a85a02aeff2393156f69c1c3", + "sha256:dc4f9a89c82faf6254d646180b2e3aa4daf5ff75bdb2c296b9f6a6cf547e26a7", + "sha256:f0557289260125a6c453ad5673ba79e5b6841d9a20c9e101f758bfbedf928a77", + "sha256:f332d61fbff353e2ef0f3130a166f499c3fad3a196e7f7ae72076d41a6bfb259", + "sha256:f3ff4205aff999164834792a3949f82435bc7c7655c849226d5836c3242d7451", + "sha256:ffa637a2d5883298449a5434b699b22ef98dd8e2ef8a1d9e60fa9cfe79813411" ], "markers": "python_version >= '3.7'", - "version": "==7.0.2" + "version": "==7.2.0" }, "distlib": { "hashes": [ @@ -205,14 +305,6 @@ "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'", "version": "==0.17.1" }, - "exceptiongroup": { - "hashes": [ - "sha256:327cbda3da756e2de031a3107b81ab7b3770a602c4d16ca618298c526f4bec1e", - "sha256:bcb67d800a4497e1b404c2dd44fca47d3b7a5e5433dbab67f96c1a685cdfdf23" - ], - "markers": "python_version < '3.11'", - "version": "==1.1.0" - }, "execnet": { "hashes": [ "sha256:8f694f3ba9cc92cab508b152dcfe322153975c29bda272e2fd7f3f00f36e47c5", @@ -256,11 +348,11 @@ }, "identify": { "hashes": [ - "sha256:14b7076b29c99b1b0b8b08e96d448c7b877a9b07683cd8cfda2ea06af85ffa1c", - "sha256:e7db36b772b188099616aaf2accbee122949d1c6a1bac4f38196720d6f9f06db" + "sha256:89e144fa560cc4cffb6ef2ab5e9fb18ed9f9b3cb054384bab4b95c12f6c309fe", + "sha256:93aac7ecf2f6abf879b8f29a8002d3c6de7086b8c28d88e1ad15045a15ab63f9" ], "markers": "python_version >= '3.7'", - "version": "==2.5.11" + "version": "==2.5.18" }, "idna": { "hashes": [ @@ -295,17 +387,19 @@ }, "iniconfig": { "hashes": [ - "sha256:011e24c64b7f47f6ebd835bb12a743f2fbe9a26d4cecaa7f53bc4f35ee9da8b3", - "sha256:bc3af051d7d14b2ee5ef9969666def0cd1a000e121eaea580d4a313df4b37f32" + "sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3", + "sha256:b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374" ], - "version": "==1.1.1" + "markers": "python_version >= '3.7'", + "version": "==2.0.0" }, "invoke": { "hashes": [ - "sha256:41b428342d466a82135d5ab37119685a989713742be46e42a3a399d685579314", - "sha256:d9694a865764dd3fd91f25f7e9a97fb41666e822bbb00e670091e3f43933574d" + "sha256:7ab5dd9cd76b787d560a78b1a9810d252367ab595985c50612702be21d671dd7", + "sha256:a860582bcf7a4b336fe18ef53937f0f28cec1c0053ffa767c2fcf7ba0b850f59" ], - "version": "==1.7.3" + "markers": "python_version >= '3.6'", + "version": "==2.0.0" }, "jinja2": { "hashes": [ @@ -315,51 +409,69 @@ "markers": "python_version >= '3.7'", "version": "==3.1.2" }, + "markdown-it-py": { + "hashes": [ + "sha256:5a35f8d1870171d9acc47b99612dc146129b631baf04970128b568f190d0cc30", + "sha256:7c9a5e412688bc771c67432cbfebcdd686c93ce6484913dccf06cb5a0bea35a1" + ], + "markers": "python_version >= '3.7'", + "version": "==2.2.0" + }, "markupsafe": { "hashes": [ - "sha256:0212a68688482dc52b2d45013df70d169f542b7394fc744c02a57374a4207003", - "sha256:089cf3dbf0cd6c100f02945abeb18484bd1ee57a079aefd52cffd17fba910b88", - "sha256:10c1bfff05d95783da83491be968e8fe789263689c02724e0c691933c52994f5", - "sha256:33b74d289bd2f5e527beadcaa3f401e0df0a89927c1559c8566c066fa4248ab7", - "sha256:3799351e2336dc91ea70b034983ee71cf2f9533cdff7c14c90ea126bfd95d65a", - "sha256:3ce11ee3f23f79dbd06fb3d63e2f6af7b12db1d46932fe7bd8afa259a5996603", - "sha256:421be9fbf0ffe9ffd7a378aafebbf6f4602d564d34be190fc19a193232fd12b1", - "sha256:43093fb83d8343aac0b1baa75516da6092f58f41200907ef92448ecab8825135", - "sha256:46d00d6cfecdde84d40e572d63735ef81423ad31184100411e6e3388d405e247", - "sha256:4a33dea2b688b3190ee12bd7cfa29d39c9ed176bda40bfa11099a3ce5d3a7ac6", - "sha256:4b9fe39a2ccc108a4accc2676e77da025ce383c108593d65cc909add5c3bd601", - "sha256:56442863ed2b06d19c37f94d999035e15ee982988920e12a5b4ba29b62ad1f77", - "sha256:671cd1187ed5e62818414afe79ed29da836dde67166a9fac6d435873c44fdd02", - "sha256:694deca8d702d5db21ec83983ce0bb4b26a578e71fbdbd4fdcd387daa90e4d5e", - "sha256:6a074d34ee7a5ce3effbc526b7083ec9731bb3cbf921bbe1d3005d4d2bdb3a63", - "sha256:6d0072fea50feec76a4c418096652f2c3238eaa014b2f94aeb1d56a66b41403f", - "sha256:6fbf47b5d3728c6aea2abb0589b5d30459e369baa772e0f37a0320185e87c980", - "sha256:7f91197cc9e48f989d12e4e6fbc46495c446636dfc81b9ccf50bb0ec74b91d4b", - "sha256:86b1f75c4e7c2ac2ccdaec2b9022845dbb81880ca318bb7a0a01fbf7813e3812", - "sha256:8dc1c72a69aa7e082593c4a203dcf94ddb74bb5c8a731e4e1eb68d031e8498ff", - "sha256:8e3dcf21f367459434c18e71b2a9532d96547aef8a871872a5bd69a715c15f96", - "sha256:8e576a51ad59e4bfaac456023a78f6b5e6e7651dcd383bcc3e18d06f9b55d6d1", - "sha256:96e37a3dc86e80bf81758c152fe66dbf60ed5eca3d26305edf01892257049925", - "sha256:97a68e6ada378df82bc9f16b800ab77cbf4b2fada0081794318520138c088e4a", - "sha256:99a2a507ed3ac881b975a2976d59f38c19386d128e7a9a18b7df6fff1fd4c1d6", - "sha256:a49907dd8420c5685cfa064a1335b6754b74541bbb3706c259c02ed65b644b3e", - "sha256:b09bf97215625a311f669476f44b8b318b075847b49316d3e28c08e41a7a573f", - "sha256:b7bd98b796e2b6553da7225aeb61f447f80a1ca64f41d83612e6139ca5213aa4", - "sha256:b87db4360013327109564f0e591bd2a3b318547bcef31b468a92ee504d07ae4f", - "sha256:bcb3ed405ed3222f9904899563d6fc492ff75cce56cba05e32eff40e6acbeaa3", - "sha256:d4306c36ca495956b6d568d276ac11fdd9c30a36f1b6eb928070dc5360b22e1c", - "sha256:d5ee4f386140395a2c818d149221149c54849dfcfcb9f1debfe07a8b8bd63f9a", - "sha256:dda30ba7e87fbbb7eab1ec9f58678558fd9a6b8b853530e176eabd064da81417", - "sha256:e04e26803c9c3851c931eac40c695602c6295b8d432cbe78609649ad9bd2da8a", - "sha256:e1c0b87e09fa55a220f058d1d49d3fb8df88fbfab58558f1198e08c1e1de842a", - "sha256:e72591e9ecd94d7feb70c1cbd7be7b3ebea3f548870aa91e2732960fa4d57a37", - "sha256:e8c843bbcda3a2f1e3c2ab25913c80a3c5376cd00c6e8c4a86a89a28c8dc5452", - "sha256:efc1913fd2ca4f334418481c7e595c00aad186563bbc1ec76067848c7ca0a933", - "sha256:f121a1420d4e173a5d96e47e9a0c0dcff965afdf1626d28de1460815f7c4ee7a", - "sha256:fc7b548b17d238737688817ab67deebb30e8073c95749d55538ed473130ec0c7" + "sha256:0576fe974b40a400449768941d5d0858cc624e3249dfd1e0c33674e5c7ca7aed", + "sha256:085fd3201e7b12809f9e6e9bc1e5c96a368c8523fad5afb02afe3c051ae4afcc", + "sha256:090376d812fb6ac5f171e5938e82e7f2d7adc2b629101cec0db8b267815c85e2", + "sha256:0b462104ba25f1ac006fdab8b6a01ebbfbce9ed37fd37fd4acd70c67c973e460", + "sha256:137678c63c977754abe9086a3ec011e8fd985ab90631145dfb9294ad09c102a7", + "sha256:1bea30e9bf331f3fef67e0a3877b2288593c98a21ccb2cf29b74c581a4eb3af0", + "sha256:22152d00bf4a9c7c83960521fc558f55a1adbc0631fbb00a9471e097b19d72e1", + "sha256:22731d79ed2eb25059ae3df1dfc9cb1546691cc41f4e3130fe6bfbc3ecbbecfa", + "sha256:2298c859cfc5463f1b64bd55cb3e602528db6fa0f3cfd568d3605c50678f8f03", + "sha256:28057e985dace2f478e042eaa15606c7efccb700797660629da387eb289b9323", + "sha256:2e7821bffe00aa6bd07a23913b7f4e01328c3d5cc0b40b36c0bd81d362faeb65", + "sha256:2ec4f2d48ae59bbb9d1f9d7efb9236ab81429a764dedca114f5fdabbc3788013", + "sha256:340bea174e9761308703ae988e982005aedf427de816d1afe98147668cc03036", + "sha256:40627dcf047dadb22cd25ea7ecfe9cbf3bbbad0482ee5920b582f3809c97654f", + "sha256:40dfd3fefbef579ee058f139733ac336312663c6706d1163b82b3003fb1925c4", + "sha256:4cf06cdc1dda95223e9d2d3c58d3b178aa5dacb35ee7e3bbac10e4e1faacb419", + "sha256:50c42830a633fa0cf9e7d27664637532791bfc31c731a87b202d2d8ac40c3ea2", + "sha256:55f44b440d491028addb3b88f72207d71eeebfb7b5dbf0643f7c023ae1fba619", + "sha256:608e7073dfa9e38a85d38474c082d4281f4ce276ac0010224eaba11e929dd53a", + "sha256:63ba06c9941e46fa389d389644e2d8225e0e3e5ebcc4ff1ea8506dce646f8c8a", + "sha256:65608c35bfb8a76763f37036547f7adfd09270fbdbf96608be2bead319728fcd", + "sha256:665a36ae6f8f20a4676b53224e33d456a6f5a72657d9c83c2aa00765072f31f7", + "sha256:6d6607f98fcf17e534162f0709aaad3ab7a96032723d8ac8750ffe17ae5a0666", + "sha256:7313ce6a199651c4ed9d7e4cfb4aa56fe923b1adf9af3b420ee14e6d9a73df65", + "sha256:7668b52e102d0ed87cb082380a7e2e1e78737ddecdde129acadb0eccc5423859", + "sha256:7df70907e00c970c60b9ef2938d894a9381f38e6b9db73c5be35e59d92e06625", + "sha256:7e007132af78ea9df29495dbf7b5824cb71648d7133cf7848a2a5dd00d36f9ff", + "sha256:835fb5e38fd89328e9c81067fd642b3593c33e1e17e2fdbf77f5676abb14a156", + "sha256:8bca7e26c1dd751236cfb0c6c72d4ad61d986e9a41bbf76cb445f69488b2a2bd", + "sha256:8db032bf0ce9022a8e41a22598eefc802314e81b879ae093f36ce9ddf39ab1ba", + "sha256:99625a92da8229df6d44335e6fcc558a5037dd0a760e11d84be2260e6f37002f", + "sha256:9cad97ab29dfc3f0249b483412c85c8ef4766d96cdf9dcf5a1e3caa3f3661cf1", + "sha256:a4abaec6ca3ad8660690236d11bfe28dfd707778e2442b45addd2f086d6ef094", + "sha256:a6e40afa7f45939ca356f348c8e23048e02cb109ced1eb8420961b2f40fb373a", + "sha256:a6f2fcca746e8d5910e18782f976489939d54a91f9411c32051b4aab2bd7c513", + "sha256:a806db027852538d2ad7555b203300173dd1b77ba116de92da9afbc3a3be3eed", + "sha256:abcabc8c2b26036d62d4c746381a6f7cf60aafcc653198ad678306986b09450d", + "sha256:b8526c6d437855442cdd3d87eede9c425c4445ea011ca38d937db299382e6fa3", + "sha256:bb06feb762bade6bf3c8b844462274db0c76acc95c52abe8dbed28ae3d44a147", + "sha256:c0a33bc9f02c2b17c3ea382f91b4db0e6cde90b63b296422a939886a7a80de1c", + "sha256:c4a549890a45f57f1ebf99c067a4ad0cb423a05544accaf2b065246827ed9603", + "sha256:ca244fa73f50a800cf8c3ebf7fd93149ec37f5cb9596aa8873ae2c1d23498601", + "sha256:cf877ab4ed6e302ec1d04952ca358b381a882fbd9d1b07cccbfd61783561f98a", + "sha256:d9d971ec1e79906046aa3ca266de79eac42f1dbf3612a05dc9368125952bd1a1", + "sha256:da25303d91526aac3672ee6d49a2f3db2d9502a4a60b55519feb1a4c7714e07d", + "sha256:e55e40ff0cc8cc5c07996915ad367fa47da6b3fc091fdadca7f5403239c5fec3", + "sha256:f03a532d7dee1bed20bc4884194a16160a2de9ffc6354b3878ec9682bb623c54", + "sha256:f1cd098434e83e656abf198f103a8207a8187c0fc110306691a2e94a78d0abb2", + "sha256:f2bfb563d0211ce16b63c7cb9395d2c682a23187f54c3d79bfec33e6705473c6", + "sha256:f8ffb705ffcf5ddd0e80b65ddf7bed7ee4f5a441ea7d3419e861a12eaf41af58" ], "markers": "python_version >= '3.7'", - "version": "==2.1.1" + "version": "==2.1.2" }, "mccabe": { "hashes": [ @@ -368,20 +480,45 @@ ], "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:335ef0bf9bcd27505c0c1720d4eac2783f18d07d6f45ac49542b57885a1996dd", - "sha256:fd552787228eb2ab8352f270470fa93c9ad8b9cbc565c5558ee3faed8edb3853" + "sha256:c41cfb1e99ba5d341fbcc5308836e7d7c9786d302f995b2c271ce2144dece9eb", + "sha256:e3ea505c03babf7977fd21674a69ad328053d414f05e6433c30d8fa14a534a6b" ], "markers": "python_version >= '3.6'", - "version": "==5.0.0" + "version": "==5.0.1" }, "mypy-extensions": { "hashes": [ - "sha256:090fedd75945a69ae91ce1303b5824f428daf5a028d2f6ab8a299250a846f15d", - "sha256:2d82818f5bb3e369420cb3c4060a7970edba416647068eb4c5343488a6c604a8" + "sha256:4392f6c0eb8a5668a69e23d168ffa70f0be9ccfd32b5cc2d26a34ae5b844552d", + "sha256:75dbf8955dc00442a438fc4d0666508a9a97b6bd41aa2f0ffe9d2f2725af0782" ], - "version": "==0.4.3" + "markers": "python_version >= '3.5'", + "version": "==1.0.0" + }, + "myst-parser": { + "hashes": [ + "sha256:61b275b85d9f58aa327f370913ae1bec26ebad372cc99f3ab85c8ec3ee8d9fb8", + "sha256:79317f4bb2c13053dd6e64f9da1ba1da6cd9c40c8a430c447a7b146a594c246d" + ], + "index": "pypi", + "version": "==0.18.1" }, "nodeenv": { "hashes": [ @@ -393,11 +530,11 @@ }, "packaging": { "hashes": [ - "sha256:2198ec20bd4c017b8f9717e00f0c8714076fc2fd93816750ab48e2c41de2cfd3", - "sha256:957e2148ba0e1a3b282772e791ef1d8083648bc131c8ab0c1feba110ce1146c3" + "sha256:714ac14496c3e68c99c29b00845f7a2b85f3bb6f1078fd9f72fd20f0570002b2", + "sha256:b6ad297f8907de0fa2fe1ccbd26fdaf387f5f47c7275fedf8cce89f99446cf97" ], "markers": "python_version >= '3.7'", - "version": "==22.0" + "version": "==23.0" }, "parse": { "hashes": [ @@ -416,11 +553,11 @@ }, "pathspec": { "hashes": [ - "sha256:3c95343af8b756205e2aba76e843ba9520a24dd84f68c22b9f93251507509dd6", - "sha256:56200de4077d9d0791465aa9095a01d421861e405b5096955051deefd697d6f6" + "sha256:3a66eb970cbac598f9e5ccb5b2cf58930cd8e3ed86d393d541eaf2d8b1705229", + "sha256:64d338d4e0914e91c1792321e6907b5a593f1ab1851de7fc269557a21b30ebbc" ], "markers": "python_version >= '3.7'", - "version": "==0.10.3" + "version": "==0.11.0" }, "pipenv": { "editable": true, @@ -432,11 +569,11 @@ }, "platformdirs": { "hashes": [ - "sha256:83c8f6d04389165de7c9b6f0c682439697887bca0aa2f1c87ef1826be3584490", - "sha256:e1fea1fe471b9ff8332e229df3cb7de4f53eeea4998d3b6bfff542115e998bd2" + "sha256:8a1228abb1ef82d788f74139988b137e78692984ec7b08eaa6c65f1723af28f9", + "sha256:b1d5eb14f221506f50d6604a561f4c5786d9e80355219694a1b244bcd96f4567" ], "markers": "python_version >= '3.7'", - "version": "==2.6.2" + "version": "==3.0.0" }, "pluggy": { "hashes": [ @@ -498,11 +635,11 @@ }, "pytest": { "hashes": [ - "sha256:892f933d339f068883b6fd5a459f03d85bfcb355e4981e146d2c7616c21fef71", - "sha256:c4014eb40e10f11f355ad4e3c2fb2c6c6d1919c73f3b5a433de4708202cade59" + "sha256:c7c6ca206e93355074ae32f7403e8ea12163b1163c976fee7d4d84027c162be5", + "sha256:d45e0952f3727241918b8fd0f376f5ff6b301cc0777c6f9a556935c92d8a7d42" ], "markers": "python_version >= '3.7'", - "version": "==7.2.0" + "version": "==7.2.1" }, "pytest-cov": { "hashes": [ @@ -522,18 +659,18 @@ }, "pytest-xdist": { "hashes": [ - "sha256:40fdb8f3544921c5dfcd486ac080ce22870e71d82ced6d2e78fa97c2addd480c", - "sha256:70a76f191d8a1d2d6be69fc440cdf85f3e4c03c08b520fd5dc5d338d6cf07d89" + "sha256:336098e3bbd8193276867cc87db8b22903c3927665dff9d1ac8684c02f597b68", + "sha256:fa10f95a2564cd91652f2d132725183c3b590d9fdcdec09d3677386ecf4c1ce9" ], "markers": "python_version >= '3.7'", - "version": "==3.1.0" + "version": "==3.2.0" }, "pytz": { "hashes": [ - "sha256:7ccfae7b4b2c067464a6733c6261673fdb8fd1be905460396b97a073e9fa683a", - "sha256:93007def75ae22f7cd991c84e02d434876818661f8df9ad5df9e950ff4e52cfd" + "sha256:01a0681c4b9684a28304615eba55d1ab31ae00bf68ec157ec3708a8182dbbcd0", + "sha256:78f4f37d8198e0627c5f1143240bb0206b8691d8d7ac6d78fee88b78733f8c4a" ], - "version": "==2022.7" + "version": "==2022.7.1" }, "pyyaml": { "hashes": [ @@ -583,19 +720,19 @@ }, "requests": { "hashes": [ - "sha256:7c5599b102feddaa661c826c56ab4fee28bfd17f5abca1ebbe3e7f19d7c97983", - "sha256:8fefa2a1a1365bf5520aac41836fbee479da67864514bdb821f31ce07ce65349" + "sha256:64299f4909223da747622c030b781c0d7811e359c37124b4bd368fb8c6518baa", + "sha256:98b1b2782e3c6c4904938b84c0eb932721069dfdb9134313beff7c83c2df24bf" ], "markers": "python_version >= '3.7' and python_version < '4'", - "version": "==2.28.1" + "version": "==2.28.2" }, "setuptools": { "hashes": [ - "sha256:57f6f22bde4e042978bcd50176fdb381d7c21a9efa4041202288d3737a0c6a54", - "sha256:a7620757bf984b58deaf32fc8a4577a9bbc0850cf92c20e1ce41c38c19e5fb75" + "sha256:e5fd0a713141a4a105412233c63dc4e17ba0090c8e8334594ac790ec97792330", + "sha256:f106dee1b506dee5102cc3f3e9e68137bbad6d47b616be7991714b0c62204251" ], "markers": "python_version >= '3.7'", - "version": "==65.6.3" + "version": "==67.4.0" }, "snowballstemmer": { "hashes": [ @@ -606,11 +743,11 @@ }, "soupsieve": { "hashes": [ - "sha256:3b2503d3c7084a42b1ebd08116e5f81aadfaea95863628c80a3b774a11b7c759", - "sha256:fc53893b3da2c33de295667a0e19f078c14bf86544af307354de5fcf12a3f30d" + "sha256:49e5368c2cda80ee7e84da9dbe3e110b70a4575f196efb74e51b94549d921955", + "sha256:e28dba9ca6c7c00173e34e4ba57448f0688bb681b7c5e8bf4971daafc093d69a" ], - "markers": "python_version >= '3.6'", - "version": "==2.3.2.post1" + "markers": "python_version >= '3.7'", + "version": "==2.4" }, "sphinx": { "hashes": [ @@ -630,11 +767,11 @@ }, "sphinxcontrib-applehelp": { "hashes": [ - "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a", - "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58" + "sha256:29d341f67fb0f6f586b23ad80e072c8e6ad0b48417db2bde114a4c9746feb228", + "sha256:828f867945bbe39817c210a1abfd1bc4895c8b73fcaade56d45357a348a07d7e" ], - "markers": "python_version >= '3.5'", - "version": "==1.0.2" + "markers": "python_version >= '3.8'", + "version": "==1.0.4" }, "sphinxcontrib-devhelp": { "hashes": [ @@ -646,11 +783,11 @@ }, "sphinxcontrib-htmlhelp": { "hashes": [ - "sha256:d412243dfb797ae3ec2b59eca0e52dac12e75a241bf0e4eb861e450d06c6ed07", - "sha256:f5f8bb2d0d629f398bf47d0d69c07bc13b65f75a81ad9e2f71a63d4b7a2f6db2" + "sha256:0cbdd302815330058422b98a113195c9249825d681e18f11e8b1f78a2f11efff", + "sha256:c38cb46dccf316c79de6e5515e1770414b797162b23cd3d06e67020e1d2a6903" ], - "markers": "python_version >= '3.6'", - "version": "==2.0.0" + "markers": "python_version >= '3.8'", + "version": "==2.0.1" }, "sphinxcontrib-jsmath": { "hashes": [ @@ -692,14 +829,6 @@ "markers": "sys_platform == 'linux'", "version": "==0.10.0" }, - "tomli": { - "hashes": [ - "sha256:939de3e7a6161af0c887ef91b7d41a53e7c5a1ca976325f429cb46ea9bc30ecc", - "sha256:de526c12914f0c550d15924c62d72abc48d6fe7364aa87328337a31007fe8a4f" - ], - "markers": "python_version < '3.11'", - "version": "==2.0.1" - }, "towncrier": { "hashes": [ "sha256:9767a899a4d6856950f3598acd9e8f08da2663c49fdcda5ea0f9e6ba2afc8eea", @@ -710,27 +839,27 @@ }, "typing-extensions": { "hashes": [ - "sha256:1511434bb92bf8dd198c12b1cc812e800d4181cfcb867674e0f8279cc93087aa", - "sha256:16fa4864408f655d35ec496218b85f79b3437c829e93320c7c9215ccfd92489e" + "sha256:5cb5f4a79139d699607b3ef622a1dedafa84e115ab0024e0d9c044a9479ca7cb", + "sha256:fb33085c39dd998ac16d1431ebc293a8b3eedd00fd4a32de0ff79002c19511b4" ], "index": "pypi", - "version": "==4.4.0" + "version": "==4.5.0" }, "urllib3": { "hashes": [ - "sha256:47cc05d99aaa09c9e72ed5809b60e7ba354e64b59c9c173ac3018642d8bb41fc", - "sha256:c083dd0dce68dbfbe1129d5271cb90f9447dea7d52097c6e0126120c521ddea8" + "sha256:076907bf8fd355cde77728471316625a4d2f7e713c125f51953bb5b3eecf4f72", + "sha256:75edcdc2f7d85b137124a6c3c9fc3933cdeaa12ecb9a6a959f22797a0feca7e1" ], "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'", - "version": "==1.26.13" + "version": "==1.26.14" }, "virtualenv": { "hashes": [ - "sha256:ce3b1684d6e1a20a3e5ed36795a97dfc6af29bc3970ca8dab93e11ac6094b3c4", - "sha256:f8b927684efc6f1cc206c9db297a570ab9ad0e51c16fa9e45487d36d1905c058" + "sha256:37a640ba82ed40b226599c522d411e4be5edb339a0c0de030c0dc7b646d61590", + "sha256:54eb59e7352b573aa04d53f80fc9736ed0ad5143af445a1e539aada6eb947dd1" ], - "markers": "python_version >= '3.6'", - "version": "==20.17.1" + "markers": "python_version >= '3.7'", + "version": "==20.19.0" }, "virtualenv-clone": { "hashes": [ diff --git a/docs/commands.rst b/docs/commands.rst deleted file mode 100644 index df51fe06b6..0000000000 --- a/docs/commands.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _commands: - -# Pipenv Commands - -The commands reference for pipenv (incomplete) - -## 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`` — 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`` — 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. - - diff --git a/docs/conf.py b/docs/conf.py index 6f4cddf9e9..065f1942fb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,12 +46,31 @@ "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", + "attrs_inline", + "colon_fence", + "deflist", + "dollarmath", + "fieldlist", + "html_admonition", + "html_image", + "inv_link", + "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/docker.rst b/docs/docker.rst deleted file mode 100644 index dce4892e5b..0000000000 --- a/docs/docker.rst +++ /dev/null @@ -1,113 +0,0 @@ -.. _docker: - -# 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/installation.rst b/docs/installation.rst deleted file mode 100644 index 29f2cb2478..0000000000 --- a/docs/installation.rst +++ /dev/null @@ -1,223 +0,0 @@ -.. _installation: - -# Pipenv Installation - -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.7+ - - -## Make sure you have 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 --user``. - - -☤ 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 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 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 - - - -☤ 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. diff --git a/docs/pipfile.rst b/docs/pipfile.rst deleted file mode 100644 index 3e24cbc9ea..0000000000 --- a/docs/pipfile.rst +++ /dev/null @@ -1,254 +0,0 @@ -.. _pipfile: - -# 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 `_. - -``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_files: - -Here is a simple example of a ``Pipfile`` and the resulting ``Pipfile.lock``. - -## Example Pipfile:: - - [[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. - -.. note:: - - If you'd like a ``requirements.txt`` output of the lockfile, run ``$ pipenv requirements``. - - -## 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 of 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/shell.rst b/docs/shell.rst deleted file mode 100644 index 0b308e73de..0000000000 --- a/docs/shell.rst +++ /dev/null @@ -1,15 +0,0 @@ -# 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`. diff --git a/docs/specifiers.rst b/docs/specifiers.rst deleted file mode 100644 index 1f63df31a6..0000000000 --- a/docs/specifiers.rst +++ /dev/null @@ -1,146 +0,0 @@ -.. _specifiers: - -## 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.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.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. - - -## 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. From 937bcca0f6c3c067d3e3d406a79fd0070b9bd3c2 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 25 Feb 2023 23:08:13 -0500 Subject: [PATCH 06/32] add the files back as markdown. --- docs/commands.md | 48 +++++++++ docs/docker.md | 113 ++++++++++++++++++++ docs/installation.md | 223 ++++++++++++++++++++++++++++++++++++++ docs/pipfile.md | 249 +++++++++++++++++++++++++++++++++++++++++++ docs/quickstart.md | 34 ++++++ docs/shell.md | 15 +++ docs/specifiers.md | 149 ++++++++++++++++++++++++++ 7 files changed, 831 insertions(+) create mode 100644 docs/commands.md create mode 100644 docs/docker.md create mode 100644 docs/installation.md create mode 100644 docs/pipfile.md create mode 100644 docs/quickstart.md create mode 100644 docs/shell.md create mode 100644 docs/specifiers.md diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000000..9c95ca7233 --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,48 @@ +.. _commands: + +# Pipenv Commands + +The commands reference for pipenv (incomplete) + +## 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`` — 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`` — 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. diff --git a/docs/docker.md b/docs/docker.md new file mode 100644 index 0000000000..dce4892e5b --- /dev/null +++ b/docs/docker.md @@ -0,0 +1,113 @@ +.. _docker: + +# 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/installation.md b/docs/installation.md new file mode 100644 index 0000000000..29f2cb2478 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,223 @@ +.. _installation: + +# Pipenv Installation + +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.7+ + + +## Make sure you have 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 --user``. + + +☤ 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 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 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 + + + +☤ 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. diff --git a/docs/pipfile.md b/docs/pipfile.md new file mode 100644 index 0000000000..b15514c584 --- /dev/null +++ b/docs/pipfile.md @@ -0,0 +1,249 @@ +# 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 +``` + +## 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 of 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.md b/docs/quickstart.md new file mode 100644 index 0000000000..29a9aff681 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,34 @@ +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/shell.md b/docs/shell.md new file mode 100644 index 0000000000..0b308e73de --- /dev/null +++ b/docs/shell.md @@ -0,0 +1,15 @@ +# 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`. diff --git a/docs/specifiers.md b/docs/specifiers.md new file mode 100644 index 0000000000..72a40e6a45 --- /dev/null +++ b/docs/specifiers.md @@ -0,0 +1,149 @@ +.. _specifiers: + +# Specifiers + + +## 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.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.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. + + +## 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. From de7a43864c83cc76fcf176bc7817bf71b969bbb3 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 25 Feb 2023 23:12:17 -0500 Subject: [PATCH 07/32] more conversions to markdown. --- docs/specifiers.md | 47 ++++++++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/docs/specifiers.md b/docs/specifiers.md index 72a40e6a45..4d96dc091d 100644 --- a/docs/specifiers.md +++ b/docs/specifiers.md @@ -1,11 +1,9 @@ -.. _specifiers: - # Specifiers ## Specifying Versions of a Package -You can specify versions of a package using the `Semantic Versioning scheme `_ +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: :: @@ -16,9 +14,8 @@ 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/ +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: :: @@ -26,9 +23,11 @@ To make inclusive or exclusive version comparisons you can use: :: $ 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 +```{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: :: @@ -36,9 +35,8 @@ The use of ``~=`` is preferred over the ``==`` identifier as the latter prevents 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 +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 @@ -70,9 +68,11 @@ If a ``Pipfile`` hasn't been created yet, one will be created for you, that look [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. +```{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. @@ -90,10 +90,10 @@ the current working directory when working on packages:: [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. - +```{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 @@ -127,7 +127,9 @@ You can read more about pip's implementation of VCS support `here Date: Sat, 25 Feb 2023 23:17:37 -0500 Subject: [PATCH 08/32] more conversions to markdown. --- docs/docker.md | 10 ++++------ docs/specifiers.md | 30 +++++++++++++++--------------- 2 files changed, 19 insertions(+), 21 deletions(-) diff --git a/docs/docker.md b/docs/docker.md index dce4892e5b..4dc16274fd 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,5 +1,3 @@ -.. _docker: - # Pipenv and Docker Containers In general, you should not have Pipenv inside a linux container image, since @@ -12,7 +10,7 @@ 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:: +doing a multistage build for your application: FROM docker.io/python:3.9 AS builder @@ -57,8 +55,7 @@ doing a multistage build for your application:: CMD ["./.venv/bin/python", "-m", "run.py"] -.. Note:: - +```{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. @@ -67,9 +64,10 @@ doing a multistage build for 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:: +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 diff --git a/docs/specifiers.md b/docs/specifiers.md index 4d96dc091d..5dc1b75a9e 100644 --- a/docs/specifiers.md +++ b/docs/specifiers.md @@ -6,7 +6,7 @@ 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: :: +For example, to install requests you can use: $ pipenv install requests~=1.2 @@ -17,7 +17,7 @@ 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: :: +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 @@ -29,13 +29,13 @@ To make inclusive or exclusive version comparisons you can use: :: in Unix-based operating systems. ``` -The use of ``~=`` is preferred over the ``==`` identifier as the latter prevents pipenv from updating the packages: :: +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 +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 @@ -43,18 +43,18 @@ the [relevant section of PEP-440]( https://www.python.org/dev/peps/pep-0440/#ver 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:: +Use Python 3 $ pipenv --python 3 -Use Python3.11:: +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:: +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" @@ -81,7 +81,7 @@ automatically, falling back to whatever your system's default ``python`` install ## 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:: +the current working directory when working on packages: $ pipenv install --dev -e . @@ -97,7 +97,7 @@ All sub-dependencies will get added to the ``Pipfile.lock`` as well. Sub-depende ## VCS Dependencies -VCS dependencies from git and other version control systems using URLs formatted according to the following rule:: +VCS dependencies from git and other version control systems using URLs formatted according to the following rule: +:////@#egg= @@ -105,7 +105,7 @@ The only optional section is the ``@`` section. When using git o 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``:: +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... @@ -134,7 +134,7 @@ The name will be the same between ``Pipfile`` and lock file, however to support 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:: +Example usages: # single category pipenv install six --categories prereq @@ -148,9 +148,9 @@ Example usages:: ```{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. + 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. ``` From 5437e26b64a89f3059626aef85ea0b20ad0aff42 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 25 Feb 2023 23:18:32 -0500 Subject: [PATCH 09/32] fix markdown formatting. --- docs/docker.md | 164 ++++++++++++++++++++++++------------------------- 1 file changed, 82 insertions(+), 82 deletions(-) diff --git a/docs/docker.md b/docs/docker.md index 4dc16274fd..7ea4a57f28 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -12,48 +12,48 @@ 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"] + 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 @@ -69,43 +69,43 @@ doing a multistage build for your application: 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 + $ 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 From 41937212d156d2bdebba741fe98be88aea039cda Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 25 Feb 2023 23:37:13 -0500 Subject: [PATCH 10/32] convert index to markdown. --- docs/{index.rst => index.md} | 86 ++++++++++++++---------------------- docs/quickstart.md | 10 ++--- 2 files changed, 38 insertions(+), 58 deletions(-) rename docs/{index.rst => index.md} (72%) diff --git a/docs/index.rst b/docs/index.md similarity index 72% rename from docs/index.rst rename to docs/index.md index d6a8388a99..e39893008f 100644 --- a/docs/index.rst +++ b/docs/index.md @@ -1,21 +1,9 @@ -.. 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 +![pypi version](https://img.shields.io/pypi/v/pipenv.svg)(https://pypi.python.org/pypi/pipenv) -Pipenv: Python Dev Workflow for Humans -====================================== +![MIT License](https://img.shields.io/pypi/l/pipenv.svg)(https://pypi.python.org/pypi/pipenv) -.. 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 - ---------------- +![Supported Versions](https://img.shields.io/pypi/pyversions/pipenv.svg)(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.* @@ -45,26 +33,17 @@ You can quickly play with Pipenv right in your browser: :alt: Try in browser -Install Pipenv Today! ---------------------- +## Install Pipenv Today! -The recommended way to install pipenv on most platforms is to install from pypi using ``pip``:: +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 ------------------ +## 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``. @@ -78,34 +57,35 @@ Pipenv Features .. include:: quickstart.rst -Further Documentation Guides +Pipenv Documentation ---------------------------- -.. toctree:: - :maxdepth: 2 - - installation - workflows - pipfile - commands - specifiers - shell - docker - advanced - cli - diagnose - changelog +```{toctree} +--- +caption: Pipenv Documentation +maxdepth: 2 +--- +installation +quickstart +workflows +pipfile +commands +specifiers +shell +docker +advanced +cli +diagnose +changelog +``` Contribution Guides ------------------- -.. toctree:: - :maxdepth: 2 - - dev/contributing - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` +```{toctree} +--- +caption: Contributing to Pipenv +maxdepth: 2 +--- +dev/contributing +``` diff --git a/docs/quickstart.md b/docs/quickstart.md index 29a9aff681..0c38745a0f 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,5 +1,6 @@ -Basic Commands and Concepts -/////////////////////////// +# Quickstart + +## 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``. @@ -25,10 +26,9 @@ The main commands are: These are intended to replace ``$ pip install`` usage, as well as manual virtualenv management. -Other Commands -////////////// +## 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. +- ``check`` checks for security vulnerabilities and asserts that [PEP 508](https://www.python.org/dev/peps/pep-0508/) requirements are being met by the current environment. From 0c7d410d7a36dc5f957c9ded82b6b8a5a16bf5ac Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 25 Feb 2023 23:58:08 -0500 Subject: [PATCH 11/32] More docs review --- docs/docker.md | 38 ++++++++++++++++++++------------------ docs/index.md | 40 +++++++++++----------------------------- docs/installation.md | 28 ++++++++++------------------ 3 files changed, 41 insertions(+), 65 deletions(-) diff --git a/docs/docker.md b/docs/docker.md index 7ea4a57f28..947a5c8236 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -3,56 +3,58 @@ 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 +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} diff --git a/docs/index.md b/docs/index.md index e39893008f..627e0360b1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,36 +1,21 @@ # Pipenv: Python Dev Workflow for Humans -![pypi version](https://img.shields.io/pypi/v/pipenv.svg)(https://pypi.python.org/pypi/pipenv) +[![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) -![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 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.* +**Pipenv** is a Python virtualenv management tool that supports a multitude of systems and nicely bridges the gaps between pip, pyenv and virtualenv. +*Linux, Mac OS, 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. 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 +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 `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 +- 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! @@ -55,10 +40,8 @@ More detailed installation instructions can be found in the :ref:`installing-pip - Automatically loads ``.env`` files to support customization and overrides. -.. include:: quickstart.rst -Pipenv Documentation ----------------------------- +## Pipenv Documentation ```{toctree} --- @@ -79,8 +62,7 @@ diagnose changelog ``` -Contribution Guides -------------------- +## Contribution Guides ```{toctree} --- diff --git a/docs/installation.md b/docs/installation.md index 29f2cb2478..1cd41c1437 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,5 +1,3 @@ -.. _installation: - # Pipenv Installation This tutorial walks you through installing and using Python packages. @@ -12,13 +10,13 @@ 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.7+ +Note: This guide is written for Python 3.7+ ## Make sure you have 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:: +from your command line. You can check this by simply running: $ python --version @@ -26,7 +24,8 @@ 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: + +Note: If you're newcomer and you get an error like this: .. code-block:: pycon @@ -59,16 +58,13 @@ Homebrew/Linuxbrew installer takes care of pip for you. .. _Installing Python: http://docs.python-guide.org/en/latest/starting/installation/ -.. _installing-pipenv: -☤ Installing Pipenv -=================== +## Installing Pipenv It is recommended that users on most platforms should install pipenv from pypi.org using ``pip install pipenv --user``. -☤ Pragmatic Installation of Pipenv ----------------------------------- +### 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. @@ -111,8 +107,7 @@ To upgrade pipenv at any time:: -☤ Homebrew Installation of Pipenv(Discouraged) ----------------------------------------------- +### 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 @@ -132,8 +127,7 @@ To upgrade pipenv at any time:: users have to re-install Pipenv, and perhaps all virtual environments managed by it. -☤ Installing packages for your project -====================================== +### 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 @@ -184,8 +178,7 @@ when you share your project with others. You should get output similar to this .. _Requests: https://python-requests.org -☤ Using installed packages -========================== +## Using installed packages Now that Requests is installed you can create a simple ``main.py`` file to use it: @@ -213,8 +206,7 @@ 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 -=========================== +## 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``). From 75ac533b989ed42ef5758645c83c906f5a07f75b Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sun, 26 Feb 2023 00:20:53 -0500 Subject: [PATCH 12/32] More markdown and doc revisions. --- docs/commands.md | 5 +- docs/index.md | 2 +- docs/installation.md | 161 ++++++++++++++++--------------------------- docs/pipfile.md | 2 +- docs/shell.md | 4 +- 5 files changed, 63 insertions(+), 111 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 9c95ca7233..5e23cda099 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -9,7 +9,7 @@ The commands reference for pipenv (incomplete) ``$ 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:: +Along with the basic installation command, which takes the form:: $ pipenv install [package names] @@ -27,7 +27,6 @@ The user can provide these additional parameters: - ``--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 @@ -41,8 +40,6 @@ as well as two additional options, ``--all`` and ``--all-dev``. 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. diff --git a/docs/index.md b/docs/index.md index 627e0360b1..ee1c42c266 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,7 @@ [![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, Mac OS, and Windows are all first-class citizens in pipenv.* +*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. diff --git a/docs/installation.md b/docs/installation.md index 1cd41c1437..279532c906 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,19 +1,9 @@ # Pipenv Installation -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.7+ -## Make sure you have python & pip +## 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: @@ -21,41 +11,20 @@ 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 +install the latest 3.x version from [python.org](https://python.org) - >>> 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:: +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`_ 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 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. -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/ +* [python.org](https://python.org) +* [Installing Python](https://wiki.python.org/moin/BeginnersGuide/Download) +* [pip](https://pypi.org/project/pip/) @@ -68,13 +37,14 @@ It is recommended that users on most platforms should install pipenv from pypi.o 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:: +To install: $ pip install pipenv --user -.. Note:: This does a `user installation`_ to prevent breaking any system-wide +```{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``. + 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, @@ -86,124 +56,109 @@ To install:: 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 + ``C:\Users\Username\AppData\Roaming\Python37\site-packages`` so you would need to set your ``PATH`` to include - ``C:\Users\Username\AppData\Roaming\Python36\Scripts``. You can set your + ``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 -.. _Control Panel: https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx -To upgrade pipenv at any time:: +To upgrade pipenv at any time: $ pip install --user --upgrade pipenv ### 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. +* [Homebrew](https://brew.sh) 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:: +Once you have installed Homebrew or Linuxbrew simply run: $ brew install pipenv -To upgrade pipenv at any time:: +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. - +```{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:: +tutorial) and run: $ cd myproject $ pipenv install requests -.. Note:: - +```{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`` +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 -(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 +when you share your project with others. -Now that Requests is installed you can create a simple ``main.py`` file to -use it: +You should get output similar to this: -.. code-block:: python + 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. - import requests +## Using installed packages - response = requests.get('https://httpbin.org/ip') +Now that ``requests`` is installed you can create a simple ``main.py`` file to use it: - print('Your IP is {0}'.format(response.json()['origin'])) +``` +import requests -Then you can run this script using ``pipenv run``:: +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``. +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 diff --git a/docs/pipfile.md b/docs/pipfile.md index b15514c584..3e5b9bf33e 100644 --- a/docs/pipfile.md +++ b/docs/pipfile.md @@ -242,7 +242,7 @@ Based on feedback, we may change this behavior of ``pipenv install`` to not re-l - 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 of the required sub-dependencies need be specified in ``Pipfile``, instead only add specifiers that make sense for the stability of your project. +- 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. diff --git a/docs/shell.md b/docs/shell.md index 0b308e73de..a30058a16d 100644 --- a/docs/shell.md +++ b/docs/shell.md @@ -2,7 +2,7 @@ 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:: +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 @@ -10,6 +10,6 @@ A proper shell configuration only sets environment variables like ``PATH`` durin 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. +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`. From 1ee7df2e190e197c6faa144fe7d3122a20cf42fe Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sun, 26 Feb 2023 00:24:14 -0500 Subject: [PATCH 13/32] Fix docs. --- docs/conf.py | 2 -- docs/{workflows.rst => workflows.md} | 2 -- 2 files changed, 4 deletions(-) rename docs/{workflows.rst => workflows.md} (98%) diff --git a/docs/conf.py b/docs/conf.py index 065f1942fb..a03988b063 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,14 +55,12 @@ myst_enable_extensions = [ "amsmath", - "attrs_inline", "colon_fence", "deflist", "dollarmath", "fieldlist", "html_admonition", "html_image", - "inv_link", "linkify", "replacements", "smartquotes", diff --git a/docs/workflows.rst b/docs/workflows.md similarity index 98% rename from docs/workflows.rst rename to docs/workflows.md index 9b8d490bdf..53976ce939 100644 --- a/docs/workflows.rst +++ b/docs/workflows.md @@ -1,5 +1,3 @@ -.. _workflows: - # Pipenv Workflows Clone / create project repository:: From 8e386c37c4c80832e5be743fee84a8720c8d812b Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Wed, 1 Mar 2023 08:29:40 -0500 Subject: [PATCH 14/32] Update doc build requirements. --- docs/requirements.txt | 42 +++++++++++++++++++----------------------- 1 file changed, 19 insertions(+), 23 deletions(-) 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 From fc9c76a7916d3ac0cd10962bd7d2ea777ddb4993 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Wed, 1 Mar 2023 08:34:34 -0500 Subject: [PATCH 15/32] fix lint --- docs/installation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 279532c906..1d2dd64a09 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -19,7 +19,7 @@ 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 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) @@ -114,7 +114,7 @@ tutorial) and run: 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. +when you share your project with others. You should get output similar to this: @@ -126,7 +126,7 @@ You should get output similar to this: 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... @@ -157,7 +157,7 @@ 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 +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``. From 36023f6737ec22019ec0ae31d2502c336dfc6adf Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Thu, 2 Mar 2023 22:44:49 -0500 Subject: [PATCH 16/32] Fix build with update/upgrade command. --- Pipfile | 1 + Pipfile.lock | 13 +++++++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/Pipfile b/Pipfile index 8b25c2a84a..f1c2263cc6 100644 --- a/Pipfile +++ b/Pipfile @@ -27,6 +27,7 @@ exceptiongroup = "==1.1.0" tomli = "*" [packages] +pytz = "*" [scripts] tests = "bash ./run-tests.sh" diff --git a/Pipfile.lock b/Pipfile.lock index c52d2e789b..72e3b73094 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "54ce6300ead30838070d586211801fe8ce14f9963d19053bb3d976e8fe184773" + "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": [ From 7d63d5f41224fd2295b870098c42b9b1218157c4 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Fri, 3 Mar 2023 23:59:56 -0500 Subject: [PATCH 17/32] remove useless quickstart and update the commands section. --- docs/commands.md | 37 +++++++++++++++++++++++++++++++++---- docs/index.md | 1 - docs/quickstart.md | 34 ---------------------------------- 3 files changed, 33 insertions(+), 39 deletions(-) delete mode 100644 docs/quickstart.md diff --git a/docs/commands.md b/docs/commands.md index 5e23cda099..b7582a546c 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -4,7 +4,7 @@ The commands reference for pipenv (incomplete) -## pipenv install +## install ``$ pipenv install`` is used for installing packages into the pipenv virtual environment and updating your Pipfile. @@ -28,7 +28,7 @@ The user can provide these additional parameters: - ``--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 +## uninstall ``$ pipenv uninstall`` supports all of the parameters in `pipenv install <#pipenv-install>`_, as well as two additional options, ``--all`` and ``--all-dev``. @@ -40,6 +40,35 @@ as well as two additional options, ``--all`` and ``--all-dev``. the virtual environment, and remove them from the Pipfile. -## pipenv lock +## sync +``$ pipenv sync`` installs dependencies from the ``Pipfile.lock`` without any alteration to the lockfile. + + +## lock + +``$ pipenv lock`` is used to update a ``Pipfile.lock``, which declares **all** dependencies of your project, their latest resolved versions based on your ``Pipfile`` specifiers, and the current hashes for the downloaded files. This ensures repeatable and deterministic builds. + +## 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. -``$ 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. diff --git a/docs/index.md b/docs/index.md index ee1c42c266..03fafbec10 100644 --- a/docs/index.md +++ b/docs/index.md @@ -49,7 +49,6 @@ caption: Pipenv Documentation maxdepth: 2 --- installation -quickstart workflows pipfile commands diff --git a/docs/quickstart.md b/docs/quickstart.md deleted file mode 100644 index 0c38745a0f..0000000000 --- a/docs/quickstart.md +++ /dev/null @@ -1,34 +0,0 @@ -# Quickstart - -## Basic Commands and Concepts - -Pipenv uses a set of commands to manage your Project's dependencies and custom scripts. -It replaces the use of ``Makefile``, direct calls to ``pip`` and ``python -m venv`` or ``virtualenv``. -to create virtual environments and install packages in them. -Pipenv uses two files to do this: ``Pipfile`` and ``Pipfile.lock`` (which will look familiar if you -are used to packages manager like ``yarn`` or ``npm``). - -The main commands are: - -- ``install`` - - - Will create a virtual env and install dependencies (if it does not exist already) - The dependencies will be installed inside. - -- ``install package==0.2`` - - - Will add the package in version 0.2 to the virtual environment and - to ``Pipfile`` and ``Pipfile.lock`` - -- ``uninstall`` - Will remove the dependency - -- ``lock`` - Regenerate ``Pipfile.lock`` and updates the dependencies inside it. - -These are intended to replace ``$ pip install`` usage, as well as manual virtualenv management. - -## Other Commands - -- ``graph`` will show you a dependency graph of your installed dependencies. -- ``shell`` will spawn a shell with the virtualenv activated. This shell can be deactivated by using ``exit``. -- ``run`` will run a given command from the virtualenv, with any arguments forwarded (e.g. ``$ pipenv run python`` or ``$ pipenv run pip freeze``). -- ``check`` checks for security vulnerabilities and asserts that [PEP 508](https://www.python.org/dev/peps/pep-0508/) requirements are being met by the current environment. From 88f5a6d6e2afc95af94092f2910475919bea77ad Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 4 Mar 2023 00:00:32 -0500 Subject: [PATCH 18/32] Fix lint --- docs/commands.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/commands.md b/docs/commands.md index b7582a546c..ee1540aefd 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -71,4 +71,3 @@ as well as two additional options, ``--all`` and ``--all-dev``. ## 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. - From ed3bad1aa4fee4a4243f3d17f718b3b24c562c24 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 4 Mar 2023 00:02:05 -0500 Subject: [PATCH 19/32] change ordering of table of contents. --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 03fafbec10..3f59d36057 100644 --- a/docs/index.md +++ b/docs/index.md @@ -49,9 +49,9 @@ caption: Pipenv Documentation maxdepth: 2 --- installation -workflows pipfile commands +workflows specifiers shell docker From 3c68c396e620f242ea1c13c7641525328cab55b2 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 4 Mar 2023 00:09:08 -0500 Subject: [PATCH 20/32] fix changelog duplicate headings. --- CHANGELOG.rst | 42 ------------------------------------------ 1 file changed, 42 deletions(-) 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) ============================ From 54494b538daad20ea01de43b1c0f4ebc157d1bc2 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 4 Mar 2023 00:20:47 -0500 Subject: [PATCH 21/32] Start splitting advanced topics. --- docs/advanced.rst | 147 +------------------------------------------- docs/credentials.md | 60 ++++++++++++++++++ docs/dev/indexes.md | 81 ++++++++++++++++++++++++ docs/index.md | 2 + 4 files changed, 144 insertions(+), 146 deletions(-) create mode 100644 docs/credentials.md create mode 100644 docs/dev/indexes.md diff --git a/docs/advanced.rst b/docs/advanced.rst index e4f49d5735..d69c313261 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -5,153 +5,8 @@ Advanced Usage of Pipenv .. image:: https://farm4.staticflickr.com/3672/33231486560_bff4124c9a_k_d.jpg -This document covers some of Pipenv's more glorious and advanced features. +This document is current in the process of being broken apart into more granular sections so that we may provide better overall documentation. -☤ 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 ------------------------------------------------ diff --git a/docs/credentials.md b/docs/credentials.md new file mode 100644 index 0000000000..61e975f108 --- /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/dev/indexes.md b/docs/dev/indexes.md new file mode 100644 index 0000000000..0d231a3a65 --- /dev/null +++ b/docs/dev/indexes.md @@ -0,0 +1,81 @@ +# 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 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 ``. diff --git a/docs/index.md b/docs/index.md index 3f59d36057..7051fc1440 100644 --- a/docs/index.md +++ b/docs/index.md @@ -55,6 +55,8 @@ workflows specifiers shell docker +indexes +credentials advanced cli diagnose From 67cef81ca09dbb3b0ba82ebceb7a1e65abcd5594 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 4 Mar 2023 00:23:02 -0500 Subject: [PATCH 22/32] minor nits --- docs/docker.md | 2 +- docs/installation.md | 8 ++------ 2 files changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/docker.md b/docs/docker.md index 947a5c8236..3367996da6 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,4 +1,4 @@ -# Pipenv and Docker Containers +# 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 diff --git a/docs/installation.md b/docs/installation.md index 1d2dd64a09..cf337fba08 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -33,7 +33,7 @@ If you're on Linux and installed using your OS package manager, you may have to It is recommended that users on most platforms should install pipenv from pypi.org using ``pip install pipenv --user``. -### Pragmatic Installation of Pipenv +### 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. @@ -76,13 +76,9 @@ To upgrade pipenv at any time: -### Homebrew Installation of Pipenv(Discouraged) +### 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. -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 From 4995e90b31bfe49e879ed47604ff186d1d6e3adb Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 4 Mar 2023 00:29:49 -0500 Subject: [PATCH 23/32] Move some sections from advanced to shell. --- docs/advanced.rst | 66 ---------------------------------------------- docs/shell.md | 67 ++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 64 insertions(+), 69 deletions(-) diff --git a/docs/advanced.rst b/docs/advanced.rst index d69c313261..e1cf9bbb1e 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -308,12 +308,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 ------------------------------ @@ -372,51 +366,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 ------------------------- @@ -607,22 +556,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! ✨🍰✨ diff --git a/docs/shell.md b/docs/shell.md index a30058a16d..044fef2821 100644 --- a/docs/shell.md +++ b/docs/shell.md @@ -1,4 +1,67 @@ -# About Shell Configuration +# 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. @@ -11,5 +74,3 @@ A proper shell configuration only sets environment variables like ``PATH`` durin 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. - -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`. From 175c6abbbd15bc8a5d0d29eb6d182402787dfb19 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 4 Mar 2023 00:35:39 -0500 Subject: [PATCH 24/32] remove this section as its stale and kind of off topic. --- docs/advanced.rst | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/docs/advanced.rst b/docs/advanced.rst index e1cf9bbb1e..e05844d470 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -579,29 +579,6 @@ 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 ---------------------------------- From 0f14cdd2dd62559c3ef2076ab06f4526ca4ca375 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 4 Mar 2023 00:40:57 -0500 Subject: [PATCH 25/32] move scripts out into its own section. --- docs/advanced.rst | 54 ----------------------------------------------- docs/index.md | 1 + docs/scripts.md | 51 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 52 insertions(+), 54 deletions(-) create mode 100644 docs/scripts.md diff --git a/docs/advanced.rst b/docs/advanced.rst index e05844d470..dbd5f33f98 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -366,60 +366,6 @@ Pipenv automatically honors both the ``python_full_version`` and ``python_versio 💫✨🍰✨💫 -☤ 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 diff --git a/docs/index.md b/docs/index.md index 7051fc1440..45aab4bf93 100644 --- a/docs/index.md +++ b/docs/index.md @@ -57,6 +57,7 @@ shell docker indexes credentials +scripts advanced cli diagnose diff --git a/docs/scripts.md b/docs/scripts.md new file mode 100644 index 0000000000..1877b69fd7 --- /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 From 90fd7f5fbbab5a235769f6a41d2b258a8404719e Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 4 Mar 2023 00:53:23 -0500 Subject: [PATCH 26/32] Wrap up revisions1 --- docs/advanced.rst | 96 +------------------------------------------ docs/configuration.md | 34 +++++++++++++++ docs/specifiers.md | 27 ++++++++++++ docs/virtualenv.md | 23 +++++++++++ 4 files changed, 85 insertions(+), 95 deletions(-) create mode 100644 docs/configuration.md create mode 100644 docs/virtualenv.md diff --git a/docs/advanced.rst b/docs/advanced.rst index dbd5f33f98..a1d3a1ab4b 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -1,10 +1,8 @@ .. _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. @@ -22,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 ------------------------------ @@ -366,58 +335,6 @@ Pipenv automatically honors both the ``python_full_version`` and ``python_versio 💫✨🍰✨💫 -.. _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 ------------------ @@ -524,14 +441,3 @@ at all, use the ``PIP_IGNORE_INSTALLED`` setting:: $ PIP_IGNORE_INSTALLED=1 pipenv install --dev - - -☤ 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/configuration.md b/docs/configuration.md new file mode 100644 index 0000000000..eacdae1d78 --- /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/specifiers.md b/docs/specifiers.md index 5dc1b75a9e..9805331909 100644 --- a/docs/specifiers.md +++ b/docs/specifiers.md @@ -154,3 +154,30 @@ Example usages: 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..908146f82d --- /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. From 5159fe017c9cbb7b6b989550b1901e9e67856d3f Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 4 Mar 2023 00:57:32 -0500 Subject: [PATCH 27/32] fix lint --- docs/advanced.rst | 1 - docs/configuration.md | 6 +++--- docs/dev/indexes.md | 2 +- docs/index.md | 2 ++ 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/advanced.rst b/docs/advanced.rst index a1d3a1ab4b..8551697586 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -440,4 +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 - diff --git a/docs/configuration.md b/docs/configuration.md index eacdae1d78..e8275e40dd 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -12,7 +12,7 @@ true value. Allowed values are: ``"1", "true", "yes", "on"`` To explicitly disable a boolean option, assign to it a false value (i.e. ``"0"``). -```{eval-rst} +```{eval-rst} .. autoclass:: pipenv.environments.Setting :members: ``` @@ -25,10 +25,10 @@ For example: ## 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. +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. +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/dev/indexes.md b/docs/dev/indexes.md index 0d231a3a65..41cc55feff 100644 --- a/docs/dev/indexes.md +++ b/docs/dev/indexes.md @@ -1,6 +1,6 @@ # Specifying Package Indexes -The default python package index that is standard for use is [pypi.org](https://pypi.org). +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 diff --git a/docs/index.md b/docs/index.md index 45aab4bf93..a22ba62354 100644 --- a/docs/index.md +++ b/docs/index.md @@ -54,10 +54,12 @@ commands workflows specifiers shell +virtualenv docker indexes credentials scripts +configuration advanced cli diagnose From 840b72688710863ee671a8dca13465bfe18c0474 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Thu, 9 Mar 2023 05:35:08 -0500 Subject: [PATCH 28/32] address PR feedback and other nits. --- docs/commands.md | 46 +++++++++++++++++++++------------- docs/configuration.md | 12 ++++----- docs/credentials.md | 10 ++++---- docs/dev/indexes.md | 31 ++++++++++++----------- docs/docker.md | 8 +++--- docs/index.md | 24 +++++++++--------- docs/installation.md | 50 ++++++++++++++++++------------------- docs/pipfile.md | 58 +++++++++++++++++++++++++++---------------- docs/scripts.md | 8 +++--- docs/shell.md | 22 ++++++++-------- docs/specifiers.md | 50 ++++++++++++++++++------------------- docs/virtualenv.md | 10 ++++---- docs/workflows.md | 12 ++++----- 13 files changed, 185 insertions(+), 156 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index ee1540aefd..0eafd60265 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -7,26 +7,42 @@ The commands reference for pipenv (incomplete) ## install ``$ pipenv install`` is used for installing packages into the pipenv virtual environment -and updating your Pipfile. +and updating your Pipfile and Pipfile.lock. -Along with the basic installation command, which takes the form:: +Along with the basic installation command, which takes the form: - $ pipenv install [package names] + $ 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. + --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: - .. 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 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 +``` - - ``--dev`` — Install both ``develop`` and ``default`` packages from ``Pipfile``. - - ``--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`` — 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``. +## 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 @@ -40,13 +56,9 @@ as well as two additional options, ``--all`` and ``--all-dev``. the virtual environment, and remove them from the Pipfile. -## sync -``$ pipenv sync`` installs dependencies from the ``Pipfile.lock`` without any alteration to the lockfile. - - ## lock -``$ pipenv lock`` is used to update a ``Pipfile.lock``, which declares **all** dependencies of your project, their latest resolved versions based on your ``Pipfile`` specifiers, and the current hashes for the downloaded files. This ensures repeatable and deterministic builds. +``$ pipenv lock`` is used to update all dependencies of ``Pipfile.lock`` to their latest resolved versions based on your ``Pipfile`` specification. ## update diff --git a/docs/configuration.md b/docs/configuration.md index e8275e40dd..b5c1602085 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -6,18 +6,18 @@ 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"`` +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"``). +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. +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: @@ -25,10 +25,10 @@ For example: ## 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. +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. +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 index 61e975f108..44f4ace26c 100644 --- a/docs/credentials.md +++ b/docs/credentials.md @@ -16,16 +16,16 @@ 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``. +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``. +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: +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. +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 @@ -57,4 +57,4 @@ input. Otherwise, the process will hang forever!: [pipenv] disable_pip_input = false -Above example will install ``flask`` and a private package ``private-test-package`` from GCP. +Above example will install `flask` and a private package `private-test-package` from GCP. diff --git a/docs/dev/indexes.md b/docs/dev/indexes.md index 41cc55feff..6db49af6fe 100644 --- a/docs/dev/indexes.md +++ b/docs/dev/indexes.md @@ -5,7 +5,7 @@ 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. +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: @@ -26,19 +26,19 @@ For a specific package to be installed from an alternate package index, you must 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 +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`` +`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 +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 + 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: + 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 @@ -46,27 +46,28 @@ unless it already exists in which case the existing name with be reused when pin ``` 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 +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 +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 +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 +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:: +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 +**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 wish to override the default PyPI index URLs with the URL for a PyPI mirror, you can do the following: +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 @@ -78,4 +79,4 @@ Should you wish to override the default PyPI index URLs with the URL for a PyPI $ pipenv uninstall --pypi-mirror -Alternatively, setting the ``PIPENV_PYPI_MIRROR`` environment variable is equivalent to passing ``--pypi-mirror ``. +Note that setting the `PIPENV_PYPI_MIRROR` environment variable is equivalent to passing `--pypi-mirror `. diff --git a/docs/docker.md b/docs/docker.md index 3367996da6..bee4798a2c 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -5,13 +5,13 @@ 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 +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 +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 @@ -69,7 +69,7 @@ doing a multistage build for your application: ``` 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: +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 diff --git a/docs/index.md b/docs/index.md index a22ba62354..c89ef99fed 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,23 +4,23 @@ **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. +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. +- 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. +- 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``: +The recommended way to install pipenv on most platforms is to install from pypi using `pip`: $ pip install --user pipenv @@ -31,13 +31,13 @@ More detailed installation instructions can be found in the :ref:`installing-pip ## 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. +- 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. +- Automatically adds/removes packages to a `Pipfile` when they are installed or uninstalled. +- Automatically loads `.env` files to support customization and overrides. diff --git a/docs/installation.md b/docs/installation.md index cf337fba08..89b7b9385a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -10,7 +10,7 @@ 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 +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. @@ -30,7 +30,7 @@ If you're on Linux and installed using your OS package manager, you may have to ## Installing Pipenv -It is recommended that users on most platforms should install pipenv from pypi.org using ``pip install pipenv --user``. +It is recommended that users on most platforms should install pipenv from pypi.org using `pip install pipenv --user`. ### Preferred Installation of Pipenv @@ -43,24 +43,24 @@ To install: ```{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``. + 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 + `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 + `~/.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. + `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 `_. ``` @@ -102,13 +102,13 @@ tutorial) and run: ```{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 + 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 +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. @@ -136,7 +136,7 @@ You should get output similar to this: ## Using installed packages -Now that ``requests`` is installed you can create a simple ``main.py`` file to use it: +Now that `requests` is installed you can create a simple `main.py` file to use it: ``` import requests @@ -144,7 +144,7 @@ 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`` +Then you can run this script using `pipenv run` $ pipenv run python main.py @@ -152,15 +152,15 @@ 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 +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``. +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``). +- 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. +- 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 index 3e5b9bf33e..b79d18b5c9 100644 --- a/docs/pipfile.md +++ b/docs/pipfile.md @@ -1,18 +1,18 @@ # Pipfile & Pipfile.lock -``Pipfile`` contains the specification for the project top-level requirements and any desired specifiers. +`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>). +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 +`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. +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``. +Here is a simple example of a `Pipfile` and the resulting `Pipfile.lock`. [[source]] url = "https://pypi.org/simple" @@ -211,39 +211,55 @@ Here is a simple example of a ``Pipfile`` and the resulting ``Pipfile.lock``. ## 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: +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. +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. +`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, +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. +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. +- 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/scripts.md b/docs/scripts.md index 1877b69fd7..06fe0c5777 100644 --- a/docs/scripts.md +++ b/docs/scripts.md @@ -1,8 +1,8 @@ # Custom Script Shortcuts -It is possible to create custom shortcuts in the optional ``[scripts]`` section of your Pipfile. +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 +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: @@ -32,7 +32,7 @@ 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. +You can also specify pacakge functions as callables such as: `:`. These can also take arguments. For example: [scripts] @@ -44,7 +44,7 @@ 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. +You can display the names and commands of your shortcuts by running `pipenv scripts` in your terminal. $ pipenv scripts command script diff --git a/docs/shell.md b/docs/shell.md index 044fef2821..4f5dcebccd 100644 --- a/docs/shell.md +++ b/docs/shell.md @@ -1,9 +1,9 @@ # Environment and Shell Configuration -## Automatic Loading of ``.env`` +## Automatic Loading of .env -If a ``.env`` file is present in your project, ``$ pipenv shell`` and ``$ pipenv run`` will automatically load it, for you: +If a `.env` file is present in your project, `$ pipenv shell` and `$ pipenv run` will automatically load it, for you: $ cat .env HELLO=WORLD⏎ @@ -17,7 +17,7 @@ If a ``.env`` file is present in your project, ``$ pipenv shell`` and ``$ pipenv >>> os.environ['HELLO'] 'WORLD' -Variable expansion is available in ``.env`` files using ``${VARNAME}`` syntax: +Variable expansion is available in `.env` files using `${VARNAME}` syntax: $ cat .env CONFIG_PATH=${HOME}/.config/foo @@ -33,17 +33,17 @@ Variable expansion is available in ``.env`` files using ``${VARNAME}`` syntax: This is very useful for keeping production credentials out of your codebase. -We do not recommend committing ``.env`` files into source control! +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: +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: +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. +See [theskumar/python-dotenv](https://github.com/theskumar/python-dotenv>) for more information on `.env` files. ## Shell Completion @@ -63,14 +63,14 @@ 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. +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: +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. +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. +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 index 9805331909..758dc72cba 100644 --- a/docs/specifiers.md +++ b/docs/specifiers.md @@ -4,15 +4,15 @@ ## 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``). +(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``. +Pipenv will install version `1.2` and any minor update, but not `2.0`. -This will update your ``Pipfile`` to reflect this requirement, automatically. +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. @@ -24,16 +24,16 @@ To make inclusive or exclusive version comparisons you can use: $ 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 + 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: +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. +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). @@ -41,7 +41,7 @@ the [relevant section of PEP-440]( https://www.python.org/dev/peps/pep-0440/#ver ## 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: +on your `PATH`), use the `--python VERSION` flag, like so: Use Python 3 @@ -54,7 +54,7 @@ Use Python3.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: +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" @@ -69,16 +69,16 @@ If a ``Pipfile`` hasn't been created yet, one will be created for you, that look 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 + 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. +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 .`` ) +## 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: @@ -91,8 +91,8 @@ the current working directory when working on 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. +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 @@ -101,11 +101,11 @@ VCS dependencies from git and other version control systems using URLs formatted +:////@#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. +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. +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``: +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... @@ -118,20 +118,20 @@ Below is an example usage which installs the git repository located at ``https:/ [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``. +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. +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``. +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. +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: @@ -148,8 +148,8 @@ Example usages: ```{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 `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. @@ -160,7 +160,7 @@ Example usages: 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:: +Here's an example `Pipfile`, which will only install `pywinusb` on Windows systems:: [[source]] url = "https://pypi.python.org/simple" diff --git a/docs/virtualenv.md b/docs/virtualenv.md index 908146f82d..a925beb374 100644 --- a/docs/virtualenv.md +++ b/docs/virtualenv.md @@ -2,22 +2,22 @@ ## Custom Virtual Environment Location -Pipenv automatically honors the ``WORKON_HOME`` environment variable, if you +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. +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, +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``. +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. +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 index 53976ce939..471d763517 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -4,7 +4,7 @@ Clone / create project repository:: $ cd myproject -Install from ``Pipfile.lock``, if there is one:: +Install from `Pipfile.lock`, if there is one:: $ pipenv sync @@ -12,11 +12,11 @@ Add a package to your project, recalibrating entire lock file using the Pipfile $ 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``. +- 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``:: +Update everything (equivalent to `pipenv lock && pipenv sync`:: $ pipenv update @@ -40,4 +40,4 @@ Activate the Pipenv shell:: $ pipenv shell -- Note: This will spawn a new shell subprocess, which can be deactivated by using ``exit``. +- Note: This will spawn a new shell subprocess, which can be deactivated by using `exit`. From a3e7ca5b73f794e8e1bb6f453734d08bc64c97f5 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Thu, 9 Mar 2023 05:35:12 -0500 Subject: [PATCH 29/32] fix lint --- docs/dev/indexes.md | 2 +- docs/pipfile.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dev/indexes.md b/docs/dev/indexes.md index 6db49af6fe..99ad039b61 100644 --- a/docs/dev/indexes.md +++ b/docs/dev/indexes.md @@ -66,7 +66,7 @@ requested as a workaround in order to support organizations where not everyone h ## 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, +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 diff --git a/docs/pipfile.md b/docs/pipfile.md index b79d18b5c9..077831d7d3 100644 --- a/docs/pipfile.md +++ b/docs/pipfile.md @@ -247,10 +247,10 @@ Traditionally there were only two package groups, and they were named different * `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, +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 +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` From 05be6dbfbcb25fe7abce23aa7588d707ff49083f Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Mon, 13 Mar 2023 03:58:15 -0400 Subject: [PATCH 30/32] Try improving ordering of table of contents, fix issue with indexes.md file location. --- docs/index.md | 10 +++++----- docs/{dev => }/indexes.md | 0 2 files changed, 5 insertions(+), 5 deletions(-) rename docs/{dev => }/indexes.md (100%) diff --git a/docs/index.md b/docs/index.md index c89ef99fed..b2a2fd3c79 100644 --- a/docs/index.md +++ b/docs/index.md @@ -50,18 +50,18 @@ maxdepth: 2 --- installation pipfile +cli commands +configuration +virtualenv workflows specifiers -shell -virtualenv -docker indexes credentials +shell +docker scripts -configuration advanced -cli diagnose changelog ``` diff --git a/docs/dev/indexes.md b/docs/indexes.md similarity index 100% rename from docs/dev/indexes.md rename to docs/indexes.md From 305a8ecdaa6c97f07d784ed052f678bcf384c776 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Mon, 13 Mar 2023 07:38:27 -0400 Subject: [PATCH 31/32] fix lint --- pipenv/environments.py | 1 - pipenv/installers.py | 1 - pipenv/project.py | 1 - 3 files changed, 3 deletions(-) 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: From 4181ea85793022fb8fccead5f4cda628c330d57e Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Sat, 18 Mar 2023 00:52:39 -0400 Subject: [PATCH 32/32] PR feedback. --- docs/pipfile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pipfile.md b/docs/pipfile.md index 077831d7d3..b17a59c3e3 100644 --- a/docs/pipfile.md +++ b/docs/pipfile.md @@ -4,7 +4,7 @@ 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 +`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.