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

5881-Full conversion from rst to md (#5909)

Browse Source 
* add the files from rst -> md
This commit is contained in:
Thiago Gariani
2023-09-05 22:19:27 -03:00
committed by GitHub
parent c844fe1752
commit 9b2e0d41a8
16 changed files with 4185 additions and 2794 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+1875
View File
File diff suppressed because it is too large Load Diff
CHANGELOG.rst
-2375
View File
File diff suppressed because it is too large Load Diff
docs/advanced.rst → docs/advanced.md
+76 -127
View File
@@ -1,80 +1,66 @@
.. _advanced:
Other Topics
========================
# Other topics
This document is current in the process of being broken apart into more granular sections so that we may provide better overall documentation.
## ☤ Supplying additional arguments to pip
☤ Supplying additional arguments to pip
------------------------------------------------
There may be cases where you wish to supply additional arguments to pip to be used during the install phase. For example, you may want to enable the pip feature for using [system certificate stores](https://pip.pypa.io/en/latest/topics/https-certificates/#using-system-certificate-stores)
There may be cases where you wish to supply additional arguments to pip to be used during the install phase.
For example, you may want to enable the pip feature for using
`system certificate stores <https://pip.pypa.io/en/latest/topics/https-certificates/#using-system-certificate-stores>`_
In this case you can supply these additional arguments to ``pipenv sync`` or ``pipenv install`` by passing additional
argument ``--extra-pip-args="--use-feature=truststore"``. It is possible to supply multiple arguments in the ``--extra-pip-args``.
Example usage::
In this case you can supply these additional arguments to `pipenv sync` or `pipenv install` by passing additional
argument `--extra-pip-args="--use-feature=truststore"`. It is possible to supply multiple arguments in the `--extra-pip-args`. Example usage:
pipenv sync --extra-pip-args="--use-feature=truststore --proxy=127.0.0.1"
## ☤ Using pipenv for Deployments
You may want to use `pipenv` as part of a deployment process.
☤ Using pipenv for Deployments
------------------------------
You may want to use ``pipenv`` as part of a deployment process.
You can enforce that your ``Pipfile.lock`` is up to date using the ``--deploy`` flag::
You can enforce that your `Pipfile.lock` is up to date using the `--deploy` flag:
$ pipenv install --deploy
This will fail a build if the ``Pipfile.lock`` is out–of–date, instead of generating a new one.
This will fail a build if the `Pipfile.lock` is out–of–date, instead of generating a new one.
Or you can install packages exactly as specified in ``Pipfile.lock`` using the ``sync`` command::
Or you can install packages exactly as specified in `Pipfile.lock` using the `sync` command:
$ pipenv sync
.. note::
Note
``pipenv install --ignore-pipfile`` is nearly equivalent to ``pipenv sync``, but ``pipenv sync`` will *never* attempt to re-lock your dependencies as it is considered an atomic operation. ``pipenv install`` by default does attempt to re-lock unless using the ``--deploy`` flag.
You may only wish to verify your ``Pipfile.lock`` is up-to-date with dependencies specified in the ``Pipfile``, without installing::
You may only wish to verify your `Pipfile.lock` is up-to-date with dependencies specified in the `Pipfile`, without installing:
$ pipenv verify
The command will perform a verification, and return an exit code ``1`` when dependency locking is needed. This may be useful for cases when the ``Pipfile.lock`` file is subject to version control, so this command can be used within your CI/CD pipelines.
The command will perform a verification, and return an exit code `1` when dependency locking is needed. This may be useful for cases when the `Pipfile.lock` file is subject to version control, so this command can be used within your CI/CD pipelines.
Deploying System Dependencies
/////////////////////////////
### Deploying System Dependencies
You can tell Pipenv to install a Pipfile's contents into its parent system with the ``--system`` flag::
You can tell Pipenv to install a Pipfile's contents into its parent system with the `--system` flag:
$ pipenv install --system
This is useful for managing the system Python, and deployment infrastructure (e.g. Heroku does this).
☤ Pipenv and Other Python Distributions
---------------------------------------
## ☤ Pipenv and Other Python Distributions
To use Pipenv with a third-party Python distribution (e.g. Anaconda), you simply provide the path to the Python binary::
To use Pipenv with a third-party Python distribution (e.g. Anaconda), you simply provide the path to the Python binary:
$ pipenv install --python=/path/to/python
Anaconda uses Conda to manage packages. To reuse Conda–installed Python packages, use the ``--site-packages`` flag::
Anaconda uses Conda to manage packages. To reuse Conda–installed Python packages, use the `--site-packages` flag:
$ pipenv --python=/path/to/python --site-packages
☤ Generating a ``requirements.txt``
-----------------------------------
## ☤ Generating a `requirements.txt`
Sometimes, you would want to generate a requirements file based on your current
environment, for example to include tooling that only supports requirements.txt.
You can convert a ``Pipfile.lock`` into a ``requirements.txt``
You can convert a `Pipfile.lock` into a `requirements.txt`
file very easily.
Let's take this ``Pipfile``::
Let's take this `Pipfile`:
[[source]]
name = "pypi"
@@ -87,7 +73,7 @@ Let's take this ``Pipfile``::
[dev-packages]
pytest = {version="==3.2.3"}
Which generates a ``Pipfile.lock`` upon completion of running ``pipenv lock``` similar to::
Which generates a `Pipfile.lock` upon completion of running ``pipenv lock``` similar to:
{
"_meta": {
@@ -105,7 +91,7 @@ Which generates a ``Pipfile.lock`` upon completion of running ``pipenv lock``` s
]
},
"default": {
... snipped ...
... snipped ...
"requests": {
"hashes": [
"sha256:6a1b267aa90cac58ac3a765d067950e7dbbf75b1da07e895d1f594193a40a38b",
@@ -114,7 +100,7 @@ Which generates a ``Pipfile.lock`` upon completion of running ``pipenv lock``` s
"index": "pypi",
"version": "==2.18.4"
},
... snipped ...
... snipped ...
},
"develop": {
... snipped ...
@@ -129,7 +115,7 @@ Which generates a ``Pipfile.lock`` upon completion of running ``pipenv lock``` s
... snipped ...
}
Given the ``Pipfile.lock`` exists, you may generate a set of requirements out of it with the default dependencies::
Given the `Pipfile.lock` exists, you may generate a set of requirements out of it with the default dependencies:
$ pipenv requirements
-i https://pypi.org/simple
@@ -139,10 +125,10 @@ Given the ``Pipfile.lock`` exists, you may generate a set of requirements out of
requests==2.18.4
urllib3==1.22
As with other commands, passing ``--dev`` will include both the default and
development dependencies::
As with other commands, passing `--dev` will include both the default and
development dependencies:
$ pipenv requirements --dev
$ pipenv requirements --dev
-i https://pypi.org/simple
colorama==0.4.5 ; sys_platform == 'win32'
py==1.11.0 ; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'
@@ -154,9 +140,7 @@ development dependencies::
requests==2.18.4
urllib3==1.22
If you wish to generate a requirements file with only the
development requirements you can do that too, using the ``--dev-only``
flag::
If you wish to generate a requirements file with only the development requirements you can do that too, using the `--dev-only` flag:
$ pipenv requirements --dev-only
-i https://pypi.org/simple
@@ -165,11 +149,11 @@ flag::
pytest==3.2.3
setuptools==65.4.1 ; python_version >= '3.7'
Adding the ``--hash`` flag adds package hashes to the output for extra security.
Adding the ``--exclude-markers`` flag excludes the markers from the output.
Adding the `--hash` flag adds package hashes to the output for extra security.
Adding the `--exclude-markers` flag excludes the markers from the output.
The locked requirements are written to stdout, with shell output redirection
used to write them to a file::
used to write them to a file:
$ pipenv requirements > requirements.txt
$ pipenv requirements --dev-only > dev-requirements.txt
@@ -189,7 +173,7 @@ used to write them to a file::
If you have multiple categories in your Pipfile and wish to generate
a requirements file for only some categories, you can do that too,
using the ``--categories`` option::
using the `--categories` option:
$ pipenv requirements --categories="tests" > requirements-tests.txt
$ pipenv requirements --categories="docs" > requirements-docs.txt
@@ -208,19 +192,17 @@ It can be used to specify multiple categories also.
$ pipenv requirements --categories="tests,docs"
☤ Detection of Security Vulnerabilities
---------------------------------------
## ☤ Detection of Security Vulnerabilities
Pipenv includes the `safety <https://github.com/pyupio/safety>`_ package, and will use it to scan your dependency graph
for known security vulnerabilities!
Pipenv includes the [safety](https://github.com/pyupio/safety) package, and will use it to scan your dependency graph for known security vulnerabilities!
By default ``pipenv check`` will scan the Pipfile.lock default packages group and use this as the input to the safety command.
To scan other package categories pass the specific ``--categories`` you want to check against.
To have ``pipenv check`` scan the virtualenv packages for what is installed and use this as the input to the safety command,
run``pipenv check --use-installed``.
Note: ``--use-installed`` was the default behavior in ``pipenv<=2023.2.4``
By default `pipenv check` will scan the Pipfile.lock default packages group and use this as the input to the safety command.
To scan other package categories pass the specific `--categories` you want to check against.
To have `pipenv check` scan the virtualenv packages for what is installed and use this as the input to the safety command,
run`pipenv check --use-installed`.
Note: `--use-installed` was the default behavior in `pipenv<=2023.2.4`.
Example::
Example:
$ pipenv install wheel==0.37.1
$ cat Pipfile.lock
@@ -250,38 +232,28 @@ Example::
Scan was completed. 1 vulnerability was found.
...
Note
.. note::
Each month, [PyUp.io](https://pyup.io>)updates the `safety` database of insecure Python packages and [makes it available to the open source community for free](https://pyup.io/safety/). Each time you run `pipenv check` to show you vulnerable dependencies,
Pipenv makes an API call to retrieve and use those results.
Each month, `PyUp.io <https://pyup.io>`_ updates the ``safety`` database of
insecure Python packages and `makes it available to the open source
community for free <https://pyup.io/safety/>`__. Each time
you run ``pipenv check`` to show you vulnerable dependencies,
Pipenv makes an API call to retrieve and use those results.
For more up-to-date vulnerability data, you may also use your own safety API key by setting the environment variable `PIPENV_PYUP_API_KEY`.
For more up-to-date vulnerability data, you may also use your own safety
API key by setting the environment variable ``PIPENV_PYUP_API_KEY``.
## ☤ Community Integrations
There are a range of community-maintained plugins and extensions available for a range of editors and IDEs, as well as different products which integrate with Pipenv projects:
☤ Community Integrations
------------------------
- [Heroku](https://heroku.com/python) (Cloud Hosting)
- [Platform.sh](https://platform.sh/hosting/python)(Cloud Hosting)
- [PyUp](https://pyup.io) (Security Notification)
- [Emacs](https://github.com/pwalsh/pipenv.el) (Editor Integration)
- [Fish Shell](https://github.com/fisherman/pipenv) (Automatic `$ pipenv shell`!)
- [VS Code](https://code.visualstudio.com/docs/python/environments) (Editor Integration)
- [PyCharm](https://www.jetbrains.com/pycharm/download/) (Editor Integration)
There are a range of community-maintained plugins and extensions available for a range of editors and IDEs, as well as
different products which integrate with Pipenv projects:
## ☤ Open a Module in Your Editor
- `Heroku <https://heroku.com/python>`_ (Cloud Hosting)
- `Platform.sh <https://platform.sh/hosting/python>`_ (Cloud Hosting)
- `PyUp <https://pyup.io>`_ (Security Notification)
- `Emacs <https://github.com/pwalsh/pipenv.el>`_ (Editor Integration)
- `Fish Shell <https://github.com/fisherman/pipenv>`_ (Automatic ``$ pipenv shell``!)
- `VS Code <https://code.visualstudio.com/docs/python/environments>`_ (Editor Integration)
- `PyCharm <https://www.jetbrains.com/pycharm/download/>`_ (Editor Integration)
☤ Open a Module in Your Editor
------------------------------
Pipenv allows you to open any Python module that is installed (including ones in your codebase), with the ``$ pipenv open`` command::
Pipenv allows you to open any Python module that is installed (including ones in your codebase), with the `$ pipenv open` command:
$ pipenv install -e git+https://github.com/kennethreitz/background.git#egg=background
Installing -e git+https://github.com/kennethreitz/background.git#egg=background...
@@ -293,14 +265,11 @@ Pipenv allows you to open any Python module that is installed (including ones in
This allows you to easily read the code you're consuming, instead of looking it up on GitHub.
.. note:: The standard ``EDITOR`` environment variable is used for this. If you're using VS Code, for example, you'll want to ``export EDITOR=code`` (if you're on macOS you will want to `install the command <https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line>`_ on to your ``PATH`` first).
Note
☤ Automatic Python Installation
-------------------------------
The standard `EDITOR` environment variable is used for this. If you're using VS Code, for example, you'll want to `export EDITOR=code` (if you're on macOS you will want to [install the command](https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line) on to your `PATH` first).
If you have `pyenv <https://github.com/pyenv/pyenv#simple-python-version-management-pyenv>`_ installed and configured, Pipenv will automatically ask you if you want to install a required version of Python if you don't already have it available.
This is a very fancy feature, and we're very proud of it::
This is a very fancy feature, and we're very proud of it:
$ cat Pipfile
[[source]]
@@ -332,19 +301,17 @@ This is a very fancy feature, and we're very proud of it::
To activate this project's virtualenv, run the following:
$ pipenv shell
Pipenv automatically honors both the ``python_full_version`` and ``python_version`` `PEP 508 <https://www.python.org/dev/peps/pep-0508/>`_ specifiers.
Pipenv automatically honors both the `python_full_version` and `python_version` [PEP 508](https://www.python.org/dev/peps/pep-0508/) specifiers.
💫✨🍰✨💫
☤ Testing Projects
------------------
## ☤ Testing Projects
Pipenv is being used in projects like `Requests`_ for declaring development dependencies and running the test suite.
Pipenv is being used in projects like [Requests](https://github.com/psf/requests) for declaring development dependencies and running the test suite.
Tox Automation Project
//////////////////////
### Tox Automation Project
Here's an example ``tox.ini`` for both local and external testing::
Here's an example `tox.ini` for both local and external testing:
[tox]
envlist = py37, py38, py39, py310, py311, pypy3, ruff
@@ -362,45 +329,27 @@ Here's an example ``tox.ini`` for both local and external testing::
pipenv run ruff --version
pipenv run ruff .
Pipenv will automatically use the virtualenv provided by ``tox``. If ``pipenv install --dev`` installs e.g. ``pytest``, then installed command ``pytest`` will be present in given virtualenv and can be called directly by ``pytest tests`` instead of ``pipenv run pytest tests``.
Pipenv will automatically use the virtualenv provided by `tox`. If `pipenv install --dev` installs e.g. `pytest`, then installed command `pytest` will be present in given virtualenv and can be called directly by `pytest tests` instead of `pipenv run pytest tests`.
You might also want to add ``--ignore-pipfile`` to ``pipenv install``, as to
not accidentally modify the lock-file on each test run. This causes Pipenv
to ignore changes to the ``Pipfile`` and (more importantly) prevents it from
adding the current environment to ``Pipfile.lock``. This might be important as
the current environment (i.e. the virtualenv provisioned by tox) will usually
contain the current project (which may or may not be desired) and additional
dependencies from ``tox``'s ``deps`` directive. The initial provisioning may
alternatively be disabled by adding ``skip_install = True`` to tox.ini.
This method requires you to be explicit about updating the lock-file, which is
probably a good idea in any case.
A 3rd party plugin, `tox-pipenv`_ is also available to use Pipenv natively with tox.
.. _Requests: https://github.com/psf/requests
.. _tox: https://tox.readthedocs.io/en/latest/
.. _tox-pipenv: https://tox-pipenv.readthedocs.io/en/latest/
.. _Travis-CI: https://travis-ci.org/
You might also want to add `--ignore-pipfile` to `pipenv install`, as to not accidentally modify the lock-file on each test run. This causes Pipenv
to ignore changes to the `Pipfile` and (more importantly) prevents it from adding the current environment to `Pipfile.lock`. This might be important as the current environment (i.e. the virtualenv provisioned by tox) will usually
contain the current project (which may or may not be desired) and additional dependencies from `tox`'s `deps` directive. The initial provisioning may
alternatively be disabled by adding `skip_install = True` to tox.ini.
This method requires you to be explicit about updating the lock-file, which is probably a good idea in any case.
A 3rd party plugin, [tox-pipenv](https://tox-pipenv.readthedocs.io/en/latest/) is also available to use Pipenv natively with tox.
✨🍰✨
☤ Working with Platform-Provided Python Components
--------------------------------------------------
## ☤ Working with Platform-Provided Python Components
It's reasonably common for platform specific Python bindings for
operating system interfaces to only be available through the system
package manager, and hence unavailable for installation into virtual
environments with ``pip``. In these cases, the virtual environment can
be created with access to the system ``site-packages`` directory::
It's reasonably common for platform specific Python bindings for operating system interfaces to only be available through the system package manager, and hence unavailable for installation into virtual
environments with `pip`. In these cases, the virtual environment can be created with access to the system `site-packages` directory:
$ pipenv --site-packages
To ensure that all ``pip``-installable components actually are installed
into the virtual environment and system packages are only used for
interfaces that don't participate in Python-level dependency resolution
at all, use the ``PIP_IGNORE_INSTALLED`` setting::
To ensure that all `pip`-installable components actually are installed into the virtual environment and system packages are only used for 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
docs/changelog.md
+1875
View File
File diff suppressed because it is too large Load Diff
docs/changelog.rst
-4
View File
@@ -1,4 +0,0 @@
Release and Version History
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: ../CHANGELOG.rst
docs/cli.md
+147
View File
@@ -0,0 +1,147 @@
# Pipenv CLI Reference
## pipenv
```bash
pipenv [OPTIONS] COMMAND [ARGS]...
```
## check
Checks for PyUp Safety security vulnerabilities and against PEP 508 markers provided in Pipfile.
```bash
pipenv check [OPTIONS]
```
## clean
Uninstalls all packages not specified in Pipfile.lock.
```bash
pipenv clean [OPTIONS]
```
## graph
Displays currently–installed dependency graph information.
```bash
pipenv graph [OPTIONS]
```
## install
Installs provided packages and adds them to Pipfile, or (if no packages are given), installs all packages from Pipfile.
```bash
pipenv install [OPTIONS] [PACKAGES]...
```
Environment Variables
PIP_INDEX_URL
```bash
Provide a default for -i
```
## lock
Generates Pipfile.lock.
```bash
pipenv lock [OPTIONS]
```
## open
View a given module in your editor.
This uses the EDITOR environment variable. You can temporarily override it, for example:
EDITOR=atom pipenv open requests
```bash
pipenv open [OPTIONS] MODULE
```
## requirements
Generate a requirements.txt from Pipfile.lock.
```bash
pipenv requirements [OPTIONS]
```
## run
Spawns a command installed into the virtualenv.
```bash
pipenv run [OPTIONS] COMMAND [ARGS]...
```
## shell
Spawns a shell within the virtualenv.
```bash
pipenv shell [OPTIONS] [SHELL_ARGS]...
```
## sync
Installs all packages specified in Pipfile.lock.
```bash
pipenv sync [OPTIONS]
```
## uninstall
Un-installs a provided package and removes it from Pipfile.
```bash
pipenv uninstall [OPTIONS] [PACKAGES]...
```
## update
Runs lock when no packages are specified, or upgrade, and then sync.
```bash
pipenv update [OPTIONS] [PACKAGES]...
```
Environment Variables
PIP_INDEX_URL
```bash
Provide a default for -i
```
## upgrade
Resolves provided packages and adds them to Pipfile, or (if no packages are given), merges results to Pipfile.lock
```bash
pipenv upgrade [OPTIONS] [PACKAGES]...
```
Environment Variables
PIP_INDEX_URL
```bash
Provide a default for -i
```
## verify
Verify the hash in Pipfile.lock is up-to-date.
```bash
pipenv verify [OPTIONS]
```
docs/cli.rst
-8
View File
@@ -1,8 +0,0 @@
.. _cli:
Pipenv CLI Reference
======================================
.. click:: pipenv:cli
:prog: pipenv
:show-nested:
docs/conf.py
+2 -2
View File
@@ -72,8 +72,8 @@ myst_enable_extensions = [
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = ".rst"
source_suffix = [".rst", ".md"]
# source_suffix = ".rst"
# The master toctree document.
master_doc = "index"
docs/dev/contributing.rst → docs/dev/contributing.md
+111 -151
View File
@@ -1,10 +1,9 @@
Contributing to Pipenv
======================
# Contributing to Pipenv
If you're reading this, you're probably interested in contributing to Pipenv.
Thank you very much! Open source projects live-and-die based on the support
they receive from others, and the fact that you're even considering
contributing to the Pipenv project is *very* generous of you.
contributing to the Pipenv project is _very_ generous of you.
This document lays out guidelines and advice for contributing to this project.
If you're thinking of contributing, please start by reading this document and
@@ -14,28 +13,19 @@ The guide is split into sections based on the type of contribution you're
thinking of making, with a section that covers general guidelines for all
contributors.
## General Guidelines
General Guidelines
------------------
### Be Cordial
Be Cordial
~~~~~~~~~~
**Be cordial or be on your way**. *—Kenneth Reitz*
.. _be cordial or be on your way: https://kennethreitz.org/essays/2013/01/27/be-cordial-or-be-on-your-way
> **Be cordial or be on your way**. _—Kenneth Reitz_
Pipenv has one very important rule governing all forms of contribution,
including reporting bugs or requesting features. This golden rule is
"`be cordial or be on your way`_"
including reporting bugs or requesting features. This golden rule is [be cordial or be on your way](https://kennethreitz.org/essays/2013/01/27/be-cordial-or-be-on-your-way)
**All contributions are welcome**, as long as
everyone involved is treated with respect.
.. _early-feedback:
Get Early Feedback
~~~~~~~~~~~~~~~~~~
### Get Early Feedback
If you are contributing, do not feel the need to sit on your contribution until
it is perfectly polished and complete. It helps everyone involved for you to
@@ -44,8 +34,7 @@ version of your contribution for feedback in no way prejudices your chances of
getting that contribution accepted, and can save you from putting a lot of work
into a contribution that is not suitable for the project.
Contribution Suitability
~~~~~~~~~~~~~~~~~~~~~~~~
### Contribution Suitability
Our project maintainers have the last word on whether or not a contribution is
suitable for Pipenv. All contributions will be considered carefully, but from
@@ -56,68 +45,51 @@ If your contribution is rejected, don't despair! As long as you followed these
guidelines, you will have a much better chance of getting your next
contribution accepted.
## Questions
Questions
---------
The GitHub issue tracker is for *bug reports* and *feature requests*. Please do
The GitHub issue tracker is for _bug reports_ and _feature requests_. Please do
not use it to ask questions about how to use Pipenv. These questions should
instead be directed to `Stack Overflow`_. Make sure that your question is tagged
with the ``pipenv`` tag when asking it on Stack Overflow, to ensure that it is
instead be directed to [Stack Overflow](https://stackoverflow.com/). Make sure that your question is tagged
with the `pipenv` tag when asking it on Stack Overflow, to ensure that it is
answered promptly and accurately.
.. _Stack Overflow: https://stackoverflow.com/
## Code Contributions
Code Contributions
------------------
Steps for Submitting Code
~~~~~~~~~~~~~~~~~~~~~~~~~
### Steps for Submitting Code
When contributing code, you'll want to follow this checklist:
#. Fork the repository on GitHub.
#. Set up your :ref:`dev-setup`
#. Run the tests (:ref:`run-the-tests`) to confirm they all pass on your system.
If they don't, you'll need to investigate why they fail. If you're unable
to diagnose this yourself, raise it as a bug report by following the guidelines
in this document: :ref:`bug-reports`.
#. Write tests that demonstrate your bug or feature. Ensure that they fail.
#. Make your change.
#. Run the entire test suite again, confirming that all tests pass *including
the ones you just added*.
#. Send a GitHub Pull Request to the main repository's ``main`` branch.
GitHub Pull Requests are the expected method of code collaboration on this
project.
1. Fork the repository on GitHub.
2. Set up your [development environment](#development-setup)
3. Run the tests from [here](#run-the-tests) to confirm they all pass on your system. If they don't, you'll need to investigate why they fail. If you're unable to diagnose this yourself, raise it as a bug report by following the guidelines
in this [document](#bug-reports).
4. Write tests that demonstrate your bug or feature. Ensure that they fail.
5. Make your change.
6. Run the entire test suite again, confirming that all tests pass _including the ones you just added_.
7. Send a GitHub Pull Request to the main repository's `main` branch. GitHub Pull Requests are the expected method of code collaboration on this project.
The following sub-sections go into more detail on some of the points above.
.. _dev-setup:
### Development Setup
Development Setup
~~~~~~~~~~~~~~~~~
The repository version of Pipenv must be installed over other global versions to
resolve conflicts with the ``pipenv`` folder being implicitly added to ``sys.path``.
See `pypa/pipenv#2557`_ for more details.
.. _pypa/pipenv#2557: https://github.com/pypa/pipenv/issues/2557
The repository version of Pipenv must be installed over other global versions to resolve conflicts with the `pipenv` folder being implicitly added to `sys.path`.
See [pypa/pipenv#2557](https://github.com/pypa/pipenv/issues/2557) for more details.
Pipenv now uses pre-commit hooks similar to Pip in order to apply linting and
code formatting automatically! The build now also checks that these linting rules
have been applied to the code before running the tests.
The build will fail when linting changes are detected so be sure to sync dev requirements
and install the pre-commit hooks locally::
and install the pre-commit hooks locally:
```bash
$ pipenv install --dev
# This will configure running the pre-commit checks at start of each commit
$ pre-commit install
# Should you want to check the pre-commit configuration against all configured project files
$ pre-commit run --all-files --verbose
```
Code Review
~~~~~~~~~~~
### Code Review
Contributions will not be merged until they have been code reviewed. You should
implement any code review feedback unless you strongly object to it. In the
@@ -125,98 +97,88 @@ event that you object to the code review feedback, you should make your case
clearly and calmly. If, after doing so, the feedback is judged to still apply,
you must either apply the feedback or withdraw your contribution.
Package Index
~~~~~~~~~~~~~
### Package Index
To speed up testing, tests that rely on a package index for locking and
installing use a local server that contains vendored packages in the
``tests/pypi`` directory. Each vendored package should have it's own folder
`tests/pypi` directory. Each vendored package should have it's own folder
containing the necessary releases. When adding a release for a package, it is
easiest to use either the ``.tar.gz`` or universal wheels (ex: ``py2.py3-none``). If
a ``.tar.gz`` or universal wheel is not available, add wheels for all available
easiest to use either the `.tar.gz` or universal wheels (ex: `py2.py3-none`). If
a `.tar.gz` or universal wheel is not available, add wheels for all available
architectures and platforms.
Documentation Contributions
---------------------------
## Documentation Contributions
Documentation improvements are always welcome! The documentation files live in
the ``docs/`` directory of the codebase. They're written in
`reStructuredText`_, and use `Sphinx`_ to generate the full suite of
the `docs/` directory of the codebase. They're written in
[MarkDown](https://www.markdownguide.org/), and use [Sphinx](http://sphinx-doc.org/index.html) to generate the full suite of
documentation.
When contributing documentation, please do your best to follow the style of the
documentation files. This means a soft-limit of 79 characters wide in your text
files and a semi-formal, yet friendly and approachable, prose style.
When presenting Python code, use single-quoted strings (``'hello'`` instead of
``"hello"``).
When presenting Python code, use single-quoted strings (`'hello'` instead of
`"hello"`).
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org/index.html
## Bug Reports
.. _bug-reports:
Bug Reports
-----------
Bug reports are hugely important! They are recorded as `GitHub issues`_. Please
Bug reports are hugely important! They are recorded as [GitHub issues](https://github.com/pypa/pipenv/issues). Please
be aware of the following things when filing bug reports:
.. _GitHub issues: https://github.com/pypa/pipenv/issues
1. Avoid raising duplicate issues. *Please* use the GitHub issue search feature
1. Avoid raising duplicate issues. _Please_ use the GitHub issue search feature
to check whether your bug report or feature request has been mentioned in
the past. Duplicate bug reports and feature requests are a huge maintenance
burden on the limited resources of the project. If it is clear from your
report that you would have struggled to find the original, that's okay, but
if searching for a selection of words in your issue title would have found
the duplicate then the issue will likely be closed extremely abruptly.
2. When filing bug reports about exceptions or tracebacks, please include the
*complete* traceback. Partial tracebacks, or just the exception text, are
_complete_ traceback. Partial tracebacks, or just the exception text, are
not helpful. Issues that do not contain complete tracebacks may be closed
without warning.
3. Make sure you provide a suitable amount of information to work with. This
means you should provide:
- Guidance on **how to reproduce the issue**. Ideally, this should be a
*small* code sample that can be run immediately by the maintainers.
Failing that, let us know what you're doing, how often it happens, what
environment you're using, etc. Be thorough: it prevents us needing to ask
further questions.
- Tell us **what you expected to happen**. When we run your example code,
what are we expecting to happen? What does "success" look like for your
code?
- Tell us **what actually happens**. It's not helpful for you to say "it
doesn't work" or "it fails". Tell us *how* it fails: do you get an
exception? A hang? The packages installed seem incorrect?
How was the actual result different from your expected result?
- Tell us **what version of Pipenv you're using**, and
**how you installed it**. Different versions of Pipenv behave
differently and have different bugs, and some distributors of Pipenv
ship patches on top of the code we supply.
- Guidance on **how to reproduce the issue**. Ideally, this should be a
_small_ code sample that can be run immediately by the maintainers.
Failing that, let us know what you're doing, how often it happens, what
environment you're using, etc. Be thorough: it prevents us needing to ask
further questions.
If you do not provide all of these things, it will take us much longer to
fix your problem. If we ask you to clarify these and you never respond, we
will close your issue without fixing it.
- Tell us **what you expected to happen**. When we run your example code,
what are we expecting to happen? What does "success" look like for your
code?
.. _run-the-tests:
- Tell us **what actually happens**. It's not helpful for you to say "it
doesn't work" or "it fails". Tell us _how_ it fails: do you get an
exception? A hang? The packages installed seem incorrect?
How was the actual result different from your expected result?
Run the tests
-------------
- Tell us **what version of Pipenv you're using**, and
**how you installed it**. Different versions of Pipenv behave
differently and have different bugs, and some distributors of Pipenv
ship patches on top of the code we supply.
Tests are written in ``pytest`` style and can be run very simply:
If you do not provide all of these things, it will take us much longer to
fix your problem. If we ask you to clarify these and you never respond, we
will close your issue without fixing it.
.. code-block:: bash
## Run the tests
pytest
Tests are written in `pytest` style and can be run very simply:
```bash
pytest
```
However many tests depend on running a private pypi server on localhost:8080.
This can be accomplished by using either the ``run-tests.sh`` or ``run-tests.bat`` scripts
which will start the ``pypiserver`` process ahead of invoking pytest.
This can be accomplished by using either the `run-tests.sh` or `run-tests.bat` scripts
which will start the `pypiserver` process ahead of invoking pytest.
You may also manually perform this step and then invoke pytest as you would normally. Example::
You may also manually perform this step and then invoke pytest as you would normally. Example:
# Linux or MacOS
pipenv run pypi-server run -v --host=0.0.0.0 --port=8080 --hash-algo=sha256 --disable-fallback ./tests/pypi/ ./tests/fixtures &
@@ -224,60 +186,59 @@ You may also manually perform this step and then invoke pytest as you would norm
# Windows
cmd /c start pipenv run pypi-server run -v --host=0.0.0.0 --port=8080 --hash-algo=sha256 --disable-fallback ./tests/pypi/ ./tests/fixtures
This will run all Pipenv tests, which can take awhile. To run a subset of the
tests, the standard pytest filters are available, such as:
- provide a directory or file: ``pytest tests/unit`` or ``pytest tests/unit/test_cmdparse.py``
- provide a keyword expression: ``pytest -k test_lock_editable_vcs_without_install``
- provide a nodeid: ``pytest tests/unit/test_cmdparse.py::test_parse``
- provide a test marker: ``pytest -m lock``
- provide a directory or file: `pytest tests/unit` or `pytest tests/unit/test_cmdparse.py`
- provide a keyword expression: `pytest -k test_lock_editable_vcs_without_install`
- provide a nodeid: `pytest tests/unit/test_cmdparse.py::test_parse`
- provide a test marker: `pytest -m lock`
There are a few other ways of running the tests:
1. test scripts
The scripts for bash or windows: ``run-tests.sh`` and ``run-tests.bat``
The scripts for bash or windows: `run-tests.sh` and `run-tests.bat`
Note that, you override the default Python Pipenv will use with
PIPENV_PYTHON and the Python binary name with PYTHON in case it
is not called ``python`` on your system or in case you have many.
is not called `python` on your system or in case you have many.
Here is an example how you can override both variables (you can
override just one too)::
override just one too):
$ PYTHON=python3.8 PIPENV_PYTHON=python3.9 run-tests.sh
$ PYTHON=python3.8 PIPENV_PYTHON=python3.9 run-tests.sh
You can also do::
You can also do:
$ PYTHON=/opt/python/python3.10/python3 run-tests.sh
$ PYTHON=/opt/python/python3.10/python3 run-tests.sh
If you need to change how pytest is invoked, see how to run the
test suite manually. The ``run-tests.sh`` script does the same
test suite manually. The `run-tests.sh` script does the same
steps the Github CI workflow does, and as such it is recommended
you run it before you open a PR. Taking this second approach,
will allow you, for example, to run a single test case, or
``fail fast`` if you need it.
`fail fast` if you need it.
2. Manually
This repeats the steps of the scripts above:
.. code-block:: console
```console
$ git clone https://github.com/pypa/pipenv.git
$ cd pipenv
$ git submodule sync && git submodule update --init --recursive
$ pipenv install --dev
$ pipenv run pytest [--any optional arguments to pytest]
```
$ git clone https://github.com/pypa/pipenv.git
$ cd pipenv
$ git submodule sync && git submodule update --init --recursive
$ pipenv install --dev
$ pipenv run pytest [--any optional arguments to pytest]
The second options assumes you already have ``pipenv`` on your system.
The second options assumes you already have `pipenv` on your system.
And simply repeats all the steps in the script above.
Preferably, you should be running your tests in a Linux container
(or FreeBSD Jail or even VM). This will guarantee that you don't break
stuff, and that the tests run in a pristine environment.
Consider doing something like this::
Consider doing something like this:
$ docker run --rm -v $(pwd):/usr/src -it python:3.7 bash
# inside the container
@@ -285,17 +246,16 @@ Consider doing something like this::
# su debian && cd /usr/src/
# bash run-tests.sh
3. Using the Makefile:
The Makefile automates all the task as in the script. However, it allows
one more fine grained control on every step. For example::
one more fine grained control on every step. For example:
$ make ramdisk # create a ram disk to preserve your SSDs life
$ make ramdisk-virtualenv
$ make test suite="-m not cli" # run all tests but cli
or ::
or
$ make tests parallel="" suite="tests/integration/test_cli.py::test_pipenv_check"
@@ -303,23 +263,23 @@ It is important that your environment is setup correctly, and
this may take some work, for example, on a specific Mac installation, the following
steps may be needed:
.. code-block:: bash
```bash
# Make sure the tests can access github
if [ "$SSH_AGENT_PID" = "" ]
then
eval ``ssh-agent``
ssh-add
fi
# Make sure the tests can access github
if [ "$SSH_AGENT_PID" = "" ]
then
eval ``ssh-agent``
ssh-add
fi
# Use unix like utilities, installed with brew,
# e.g. brew install coreutils
for d in /usr/local/opt/*/libexec/gnubin /usr/local/opt/python/libexec/bin
do
[[ ":$PATH:" != *":$d:"* ]] && PATH="$d:${PATH}"
done
# Use unix like utilities, installed with brew,
# e.g. brew install coreutils
for d in /usr/local/opt/*/libexec/gnubin /usr/local/opt/python/libexec/bin
do
[[ ":$PATH:" != *":$d:"* ]] && PATH="$d:${PATH}"
done
export PATH
export PATH
# PIP_FIND_LINKS currently breaks test_uninstall.py
# PIP_FIND_LINKS currently breaks test_uninstall.py
unset PIP_FIND_LINKS
```
docs/diagnose.md
+97
View File
@@ -0,0 +1,97 @@
# Frequently Encountered PiPenv Problems
Pipenv is constantly being improved by volunteers, but is still a very young
project with limited resources, and has some quirks that needs to be dealt
with. We need everyone’s help (including yours!).
Here are some common questions people have using Pipenv. Please take a look
below and see if they resolve your problem.
Note
**Make sure you’re running the newest Pipenv version first!**
## ☤ Your dependencies could not be resolved
Make sure your dependencies actually _do_ resolve. If you’re confident they
are, you may need to clear your resolver cache. Run the following command::
pipenv lock --clear
and try again.
If this does not work, try manually deleting the whole cache directory. It is
usually one of the following locations:
- `~/Library/Caches/pipenv` (macOS)
- `%LOCALAPPDATA%\pipenv\pipenv\Cache` (Windows)
- `~/.cache/pipenv` (other operating systems)
Pipenv does not install pre-releases (i.e. a version with an alpha/beta/etc.
suffix, such as _1.0b1_) by default. You will need to pass the `--pre` flag
in your command, or set
[pipenv]
allow_prereleases = true
in your Pipfile.
## ☤ No module named <module name>
This is usually a result of mixing Pipenv with system packages. We _strongly_
recommend installing Pipenv in an isolated environment. Uninstall all existing
Pipenv installations, and see [installing pipenv](./installation.md/#installing-pipenv) to choose one of the recommended way to install Pipenv instead.
## ☤ My pyenv-installed Python is not found
Make sure you have `PYENV_ROOT` set correctly. Pipenv only supports CPython
distributions, with version name like `3.6.4` or similar.
## ☤ Pipenv does not respect pyenv’s global and local Python versions
Pipenv by default uses the Python it is installed against to create the
virtualenv. You can set the `--python` option to `$(pyenv which python)` to use your current pyenv interpreter. See [specifying versions](./specifiers.md) for more information.
## ☤ ValueError: unknown locale: UTF-8
macOS has a bug in its locale detection that prevents us from detecting your
shell encoding correctly. This can also be an issue on other systems if the
locale variables do not specify an encoding.
The workaround is to set the following two environment variables to a standard
localization format:
- `LC_ALL`
- `LANG`
```bash
export LC_ALL='en_US.UTF-8'
export LANG='en_US.UTF-8'
```
For Zsh, the file to edit is `~/.zshrc`.
Note
You can change both the `en_US` and `UTF-8` part to the language/locale and encoding you use.
## ☤ /bin/pip: No such file or directory
This may be related to your locale setting. See [here](#☤-valueerror-unknown-locale-utf-8) for a possible solution.
## ☤ Pipenv does not respect dependencies in setup.py
No, it does not, intentionally. Pipfile and setup.py serve different purposes, and should not consider each other by default. See :ref:`pipfile-vs-setuppy` for more information.
## ☤ Using `pipenv run` in Supervisor program
When you configure a supervisor program's `command` with `pipenv run ...`, you need to set locale environment variables properly to make it work.
Add this line under `[supervisord]` section in `/etc/supervisor/supervisord.conf`::
[supervisord]
environment=LC_ALL='en_US.UTF-8',LANG='en_US.UTF-8'
## ☤ An exception is raised during `Locking dependencies...`
Run `pipenv lock --clear` and try again. The lock sequence caches results to speed up subsequent runs. The cache may contain faulty results if a bug causes the format to corrupt, even after the bug is fixed. `--clear` flushes the cache, and therefore removes the bad results.
docs/diagnose.rst
-123
View File
@@ -1,123 +0,0 @@
.. _diagnose:
Frequently Encountered Pipenv Problems
======================================
Pipenv is constantly being improved by volunteers, but is still a very young
project with limited resources, and has some quirks that needs to be dealt
with. We need everyone’s help (including yours!).
Here are some common questions people have using Pipenv. Please take a look
below and see if they resolve your problem.
.. Note:: **Make sure you’re running the newest Pipenv version first!**
☤ Your dependencies could not be resolved
-----------------------------------------
Make sure your dependencies actually *do* resolve. If you’re confident they
are, you may need to clear your resolver cache. Run the following command::
pipenv lock --clear
and try again.
If this does not work, try manually deleting the whole cache directory. It is
usually one of the following locations:
* ``~/Library/Caches/pipenv`` (macOS)
* ``%LOCALAPPDATA%\pipenv\pipenv\Cache`` (Windows)
* ``~/.cache/pipenv`` (other operating systems)
Pipenv does not install pre-releases (i.e. a version with an alpha/beta/etc.
suffix, such as *1.0b1*) by default. You will need to pass the ``--pre`` flag
in your command, or set
::
[pipenv]
allow_prereleases = true
in your Pipfile.
☤ No module named <module name>
---------------------------------
This is usually a result of mixing Pipenv with system packages. We *strongly*
recommend installing Pipenv in an isolated environment. Uninstall all existing
Pipenv installations, and see :ref:`installing-pipenv` to choose one of the
recommended way to install Pipenv instead.
☤ My pyenv-installed Python is not found
----------------------------------------
Make sure you have ``PYENV_ROOT`` set correctly. Pipenv only supports CPython
distributions, with version name like ``3.6.4`` or similar.
☤ Pipenv does not respect pyenv’s global and local Python versions
------------------------------------------------------------------
Pipenv by default uses the Python it is installed against to create the
virtualenv. You can set the ``--python`` option to ``$(pyenv which python)``
to use your current pyenv interpreter. See :ref:`specifying_versions` for more
information.
.. _unknown-local-diagnose:
☤ ValueError: unknown locale: UTF-8
-----------------------------------
macOS has a bug in its locale detection that prevents us from detecting your
shell encoding correctly. This can also be an issue on other systems if the
locale variables do not specify an encoding.
The workaround is to set the following two environment variables to a standard
localization format:
* ``LC_ALL``
* ``LANG``
For Bash, for example, you can add the following to your ``~/.bash_profile``:
.. code-block:: bash
export LC_ALL='en_US.UTF-8'
export LANG='en_US.UTF-8'
For Zsh, the file to edit is ``~/.zshrc``.
.. Note:: You can change both the ``en_US`` and ``UTF-8`` part to the
language/locale and encoding you use.
☤ /bin/pip: No such file or directory
-------------------------------------
This may be related to your locale setting. See :ref:`unknown-local-diagnose`
for a possible solution.
☤ Pipenv does not respect dependencies in setup.py
--------------------------------------------------
No, it does not, intentionally. Pipfile and setup.py serve different purposes,
and should not consider each other by default. See :ref:`pipfile-vs-setuppy`
for more information.
☤ Using ``pipenv run`` in Supervisor program
---------------------------------------------
When you configure a supervisor program's ``command`` with ``pipenv run ...``, you
need to set locale environment variables properly to make it work.
Add this line under ``[supervisord]`` section in ``/etc/supervisor/supervisord.conf``::
[supervisord]
environment=LC_ALL='en_US.UTF-8',LANG='en_US.UTF-8'
☤ An exception is raised during ``Locking dependencies...``
-----------------------------------------------------------
Run ``pipenv lock --clear`` and try again. The lock sequence caches results
to speed up subsequent runs. The cache may contain faulty results if a bug
causes the format to corrupt, even after the bug is fixed. ``--clear`` flushes
the cache, and therefore removes the bad results.
docs/requirements.txt
+1 -1
View File
@@ -19,5 +19,5 @@ sphinx-click==4.4.0
sphinxcontrib-spelling==7.7.0
sphinxcontrib-websupport==1.2.4
urllib3==1.26.14
virtualenv==20.20.0
virtualenv>=20.20.0
virtualenv-clone==0.5.7
pipenv/vendor/click/LICENSE.rst → pipenv/vendor/click/LICENSE.md
Vendored
View File
pipenv/vendor/markupsafe/LICENSE.rst → pipenv/vendor/markupsafe/LICENSE.md
Vendored
View File
tests/fixtures/fake-package/README.md
Vendored
+1
View File
@@ -0,0 +1 @@
# fake_package: A fake python package.
tests/fixtures/fake-package/README.rst
Vendored
-3
View File
@@ -1,3 +0,0 @@
===============================================================================
fake_package: A fake python package.
===============================================================================