Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs and add deprecation warning for lock -r #5069

Merged
merged 3 commits into from
Apr 30, 2022
Merged

Update docs and add deprecation warning for lock -r #5069

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
89267ae
Update docs and add deprecation warning for lock -r
ImreC Apr 22, 2022
5946a7c
Fix linting errors
ImreC Apr 22, 2022
16aca8d
Update deprecation message
ImreC Apr 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 14 additions & 43 deletions docs/advanced.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,9 +231,10 @@ Anaconda uses Conda to manage packages. To reuse Conda–installed Python packag
☤ 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`` and ``Pipfile.lock`` into a ``requirements.txt``
file very easily, and get all the benefits of extras and other goodies we have
included.
file very easily.

Let's take this ``Pipfile``::

Expand All @@ -249,7 +250,8 @@ Let's take this ``Pipfile``::

And generate a set of requirements out of it with only the default dependencies::

$ pipenv lock -r
$ pipenv requirements
-i https://pypi.org/simple
chardet==3.0.4
requests==2.18.4
certifi==2017.7.27.1
Expand All @@ -259,7 +261,8 @@ And generate a set of requirements out of it with only the default dependencies:
As with other commands, passing ``--dev`` will include both the default and
development dependencies::

$ pipenv lock -r --dev
$ pipenv requirements --dev
-i https://pypi.org/simple
chardet==3.0.4
requests==2.18.4
certifi==2017.7.27.1
Expand All @@ -272,59 +275,27 @@ If you wish to generate a requirements file with only the
development requirements you can do that too, using the ``--dev-only``
flag::

$ pipenv lock -r --dev-only
$ pipenv requirements --dev-only
-i https://pypi.org/simple
py==1.4.34
pytest==3.2.3

Sometimes, you would want to generate a requirements file based on your current
environment. However, using pipenv lock -r will still do the locking process which
could update package versions. To keep the packages as is, use the ``--keep-outdated``
flag::

$ pipenv lock -r --keep-outdated
chardet==3.0.4
requests==2.18.4
certifi==2017.7.27.1
idna==2.6
urllib3==1.22

Note that using this approach, packages newly added to the Pipfile will still be
included in requirements.txt. If you really want to use Pipfile.lock and
Pipfile.lock only, you can generate the requirements using::

$ pipenv requirements
chardet==3.0.4
requests==2.18.4
certifi==2017.7.27.1
idna==2.6
urllib3==1.22

This will bypass the locking process completely. As with other commands,
passing ``--dev`` will include both the default and development dependencies.
Passing ``--dev-only`` will include only development dependencies and ``--hash`` will
add package hashes to the output for extra security.
Adding the ``--hash`` flag will add package hashes to the output for extra security.

The locked requirements are written to stdout, with shell output redirection
used to write them to a file::

$ pipenv lock -r > requirements.txt
$ pipenv lock -r --dev-only > dev-requirements.txt
$ pipenv requirements --dev > all-requirements.txt
$ pipenv requirements > requirements.txt
$ pipenv requirements --dev-only > dev-requirements.txt
$ cat requirements.txt
-i https://pypi.org/simple
chardet==3.0.4
requests==2.18.4
certifi==2017.7.27.1
idna==2.6
urllib3==1.22
$ cat dev-requirements.txt
py==1.4.34
pytest==3.2.3
$ cat all-requirements.txt
chardet==3.0.4
requests==2.18.4
certifi==2017.7.27.1
idna==2.6
urllib3==1.22
-i https://pypi.org/simple
py==1.4.34
pytest==3.2.3

Expand Down
9 changes: 9 additions & 0 deletions pipenv/cli/command.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,6 +323,15 @@ def lock(ctx, state, **kwargs):
dev_only = state.lockoptions.dev_only
pre = state.installstate.pre
if emit_requirements:
echo(
crayons.yellow(
"""
Warning: The lock flags -r/--requirements, along with it's options (--keep-outdated, --dev, --dev-only)
Copy link
Member

@matteius matteius Apr 22, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you cannot deprecate --keep-outdated because it is used to change the behavior of locking and thus install as well. I think the --dev or --dev-only may also be used similarly .. isn't --dev how you specify to only install the development requirements? I am not sure about --dev-only actually.

Otherwise I think this is the right direction to head in.

Unrelated, can you also have a look at this PR: #5071

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh one more thing, we are trying to not add any more crayons usage -- use click coloring instead. @oz123 will thank you. I have a recent example of doing just that: https://github.com/pypa/pipenv/pull/5046/files#diff-ef852c4ac364f946819f765a6bc26f04f1b0968f31fc512949a60fa2ab0685e8R903-R910

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does requirements subcommand updates the packages? Is the default keep-outdated or update?
This should be clarified in the deperecation message.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated the message. It indeed was very confusing. Apologies. Please check if it is okay now @matteius @oz123

will be deprecated in a future version of pipenv in favor of the new requirements command.
For more info see https://pipenv.pypa.io/en/latest/advanced/#generating-a-requirements-txt
"""
)
)
# Emit requirements file header (unless turned off with --no-header)
if state.lockoptions.emit_requirements_header:
header_options = ["--requirements"]
Expand Down