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

Fix formatting in /docs (#5721)

Browse Source
This commit is contained in:
plgruener
2023-06-10 22:03:44 +02:00
committed by GitHub
parent ff879aac72
commit 9a9ee9cfda
7 changed files with 92 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docker.md
+8 -8
View File
@@ -58,14 +58,14 @@ doing a multistage build for your application:
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.**
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
docs/index.md
+1 -1
View File
@@ -24,7 +24,7 @@ The recommended way to install pipenv on most platforms is to install from pypi
$ pip install --user pipenv
More detailed installation instructions can be found in the :ref:`installing-pipenv` chapter.
More detailed installation instructions can be found in the [installing Pipenv](installation) chapter.
✨🍰✨
docs/indexes.md
+6 -7
View File
@@ -35,14 +35,13 @@ Alternatively the index may be specified by full url, and it will be added to th
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:
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.*
> 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
docs/installation.md
+53 -54
View File
@@ -1,85 +1,83 @@
# Pipenv Installation
Note: This guide is written for Python 3.7+
```{note}
This guide is written for Python 3.7+
```
## Make sure you have python
## Make sure you have python and 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
You should get some output like `3.10.8`. If you do not have Python, please
install the latest 3.x version from [python.org](https://python.org)
Additionally, you will want to make sure you have pip available.
Check this by running:
Additionally, make sure you have [pip] available.
Check this by running
$ pip --version
pip 22.3.1
If you installed Python from source, with an installer from [python.org], via `Homebrew`_ you likely already have pip.
If you installed Python from source, with an installer from [python.org] or via [Homebrew], you likely already have pip.
If you're on Linux and installed using your OS package manager, you may have to [install pip](https://pip.pypa.io/en/stable/installing/) manually.
* [python.org](https://python.org)
* [Installing Python](https://wiki.python.org/moin/BeginnersGuide/Download)
* [pip](https://pypi.org/project/pip/)
[python.org]: https://python.org
[pypi.org]: https://pypi.org
[pip]: https://pypi.org/project/pip/
[Homebrew]: https://brew.sh/
## Installing Pipenv
It is recommended that users on most platforms should install pipenv from pypi.org using `pip install pipenv --user`.
### Preferred Installation of Pipenv
If you have a working installation of pip, and maintain certain "tool-chain" type Python modules as global utilities in your user environment, pip `user installs <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_ allow for installation into your home directory. Note that due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow like virtualenv, pipenv, tox, and similar software.
To install:
It is recommended that users on most platforms install pipenv from [pypi.org] using
$ pip install pipenv --user
```{note}
This does a `user installation`_ to prevent breaking any system-wide
packages. If `pipenv` isn't available in your shell after installation,
you'll need to add the user site-packages binary directory to your `PATH`.
On Linux and macOS you can find the user base binary directory by running
`python -m site --user-base` and adding `bin` to the end. For example,
this will typically print `~/.local` (with `~` expanded to the
absolute path to your home directory) so you'll need to add
`~/.local/bin` to your `PATH`. You can set your `PATH` permanently by
`modifying ~/.profile`_.
On Windows you can find the user base binary directory by running
`python -m site --user-site` and replacing `site-packages` with
`Scripts`. For example, this could return
`C:\Users\Username\AppData\Roaming\Python37\site-packages` so you would
need to set your `PATH` to include
`C:\Users\Username\AppData\Roaming\Python37\Scripts`. You can set your
user `PATH` permanently in the `Control Panel`_. You may need to log
out for the `PATH` changes to take effect.
For more information, see the `user installs documentation <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_.
pip [user installations] allow for installation into your home directory to prevent breaking any system-wide packages.
Due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow such as virtualenv, pipenv, tox, and similar software.
```
.. _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
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 appending `bin` to the end. For example,
this will typically print `~/.local` (with `~` expanded to the
absolute path to your home directory), so you'll need to add
`~/.local/bin` to your `PATH`. You can set your `PATH` permanently by
[modifying ~/.profile].
On Windows you can find the user base binary directory by running
`python -m site --user-site` and replacing `site-packages` with
`Scripts`. For example, this could return
`C:\Users\Username\AppData\Roaming\Python37\site-packages`, so you would
need to set your `PATH` to include
`C:\Users\Username\AppData\Roaming\Python37\Scripts`. You can set your
user `PATH` permanently in the [Control Panel](https://learn.microsoft.com/en-us/windows/win32/shell/user-environment-variables).
You may need to log out for the `PATH` changes to take effect.
[user base]: https://docs.python.org/3/library/site.html#site.USER_BASE
[user installations]: https://pip.pypa.io/en/stable/user_guide/#user-installs
[modifying ~/.profile]: https://stackoverflow.com/a/14638025
[Control Panel]: https://learn.microsoft.com/en-us/windows/win32/shell/user-environment-variables
To upgrade pipenv at any time:
$ pip install --user --upgrade pipenv
### Homebrew Installation of Pipenv
* [Homebrew](https://brew.sh) is a popular open-source package management system for macOS. For Linux users, `Linuxbrew`_ is a Linux port of that.
* [Homebrew] is a popular open-source package management system for macOS (or Linux).
Once you have installed Homebrew or Linuxbrew simply run:
Once you have installed Homebrew simply run
$ brew install pipenv
@@ -88,32 +86,33 @@ To upgrade pipenv at any time:
$ brew upgrade pipenv
```{note}
Homebrew installation is discouraged because it works better to install pipenv using pip on macOS
Homebrew installation is discouraged because it works better to install pipenv using pip on macOS.
```
### Installing packages for your project
## Installing packages for your project
Pipenv manages dependencies on a per-project basis. To install packages,
Pipenv manages dependencies on a per-project basis. To install a package,
change into your project's directory (or just an empty directory for this
tutorial) and run:
tutorial) and run
$ cd myproject
$ pipenv install requests
$ pipenv install <package>
```{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 is designed to be used by non-privileged OS users. It is not meant
to install or handle packages for the whole OS. Running Pipenv as `root`
or with `sudo` (or `Admin` on Windows) is highly discouraged and might
lead to unintend breakage of your OS.
```
Pipenv will install the `requests` library and create a `Pipfile`
Pipenv will install the package 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:
For example when installing the `requests` library, you should get output similar to this:
$ pipenv install requests
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...
docs/specifiers.md
+11 -11
View File
@@ -30,9 +30,9 @@ 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
to avoid issues with `Input and output redirection <https://robots.thoughtbot.com/input-output-redirection-in-the-shell>`_
in Unix-based operating systems.
The use of double quotes around the package and version specification (i.e. `"requests>2.19"`) is highly recommended
to avoid issues with [Input and output redirection](https://robots.thoughtbot.com/input-output-redirection-in-the-shell)
in Unix-based operating systems.
```
The use of `~=` is preferred over the `==` identifier as the latter prevents pipenv from updating the packages:
@@ -75,9 +75,9 @@ If a `Pipfile` hasn't been created yet, one will be created for you, that looks
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.
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
@@ -154,11 +154,11 @@ 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.
This may be desired in some use cases where users only are installing groups specific to their system platform.
The `packages`/`default` specifiers are used to constrain all other categories just as they have done
for `dev-packages`/`develop` category. However this is the only way constraints are applied --
the presence of other named groups do not constraint each other,
which means it is possible to define conflicting package versions across groups.
This may be desired in some use cases where users only are installing groups specific to their system platform.
```
## Specifying Basically Anything
docs/virtualenv.md
+3 -3
View File
@@ -2,8 +2,8 @@
## 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
Pipenv automatically honors the `WORKON_HOME` environment variable, if it
is set, so you can tell pipenv to store your virtual environments
wherever you want, e.g.:
export WORKON_HOME=~/.venvs
@@ -13,7 +13,7 @@ In addition, you can also have Pipenv stick the virtualenv in `project/.venv` by
## 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.
docs/workflows.md
+10 -10
View File
@@ -1,42 +1,42 @@
# Pipenv Workflows
Clone / create project repository::
Clone / create project repository:
$ cd myproject
Install from `Pipfile.lock`, if there is one::
Install from `Pipfile.lock`, if there is one:
$ pipenv sync
Add a package to your project, recalibrating entire lock file using the Pipfile specifiers::
Add a package to your project, recalibrating entire lock file using the Pipfile specifiers:
$ pipenv install <package>
- Note: This will create a `Pipfile` if one doesn't exist. If one does exist, it will automatically be edited with the new package you provided, the lock file updated and the new dependencies installed.
- `pipenv install` is fully compatible with `pip install` package specifiers, for which the full documentation can be found `here <https://pip.pypa.io/en/stable/user_guide/#installing-packages>`__.
- `pipenv install` is fully compatible with `pip install` [package specifiers](https://pip.pypa.io/en/stable/user_guide/#installing-packages>).
- Additional arguments may be supplied to `pip` by supplying `pipenv` with `--extra-pip-args`.
Update everything (equivalent to `pipenv lock && pipenv sync`::
Update everything (equivalent to `pipenv lock && pipenv sync`):
$ pipenv update
Update and install just the relevant package and its sub-dependencies::
Update and install just the relevant package and its sub-dependencies:
$ pipenv update <package>
Update in the Pipfile/lockfile just the relevant package and its sub-dependencies::
Update in the Pipfile/lockfile just the relevant package and its sub-dependencies:
$ pipenv upgrade <package>
Find out what's changed upstream::
Find out what's changed upstream:
$ pipenv update --outdated
Determine the virtualenv PATH::
Determine the virtualenv `PATH`:
$ pipenv --venv
Activate the Pipenv shell::
Activate the Pipenv shell:
$ pipenv shell