feat: --requirements-file option #748

amol- · 2025-12-17T18:09:14Z

Intent

Allow users to specify a custom requirements file.

Closes #747

Type of Change

Bug Fix
New Feature
Breaking Change

Approach

added a --requirements-file/-r option to force a specific requirements file.

Internally force_generate has been removed. Now a requirements file can be specified, when the requirements file is None it means one should be generated, thus replacing the force_generate option.

To retain compatibility with current commands, the command line options have not been changed, --force-generate still exists. It just sets the requirements file to None

Automated Tests

test_requirements_override tests for support in overriding requirements.

Directions for Reviewers

Checklist

I have updated CHANGELOG.md to cover notable changes.
I have updated all related GitHub issues to reflect their current state.

github-actions · 2025-12-17T18:09:48Z

PR Preview Action v1.6.3
Preview removed because the pull request was closed.
2025-12-18 15:43 UTC

github-actions · 2025-12-17T18:20:20Z

☂️ Python Coverage

current status: ✅

Overall Coverage

Lines	Covered	Coverage	Threshold	Status
5235	3970	76%	0%	🟢

New Files

No new covered files...

Modified Files

File	Coverage	Status
rsconnect/actions.py	47%	🟢
rsconnect/environment.py	88%	🟢
rsconnect/main.py	68%	🟢
rsconnect/subprocesses/inspect_environment.py	87%	🟢
TOTAL	72%	🟢

updated for commit: a5e85fb by action🐍

amol- · 2025-12-18T10:46:58Z

rsconnect/actions.py

-        python,
+        requirements_file="requirements.txt" if not force_generate else None,
+        python=python,
    )


This is only used by vetiver-python package, which writes an application from scratch and deploys it using rsconnect. We can take for granted the requirements file is always "requirements.txt" here as it's driven by vetiver-python

amol- · 2025-12-18T10:48:24Z

rsconnect/subprocesses/inspect_environment.py

    """

-    if force_generate:
+    if requirements_file is None:


This is the main change in terms of logic.

Externally we preserved the --force-generate command line option to retain backward compatibility, but internally the force_generate argument is now replaced by the None value passed as the the requirements_file

amol- · 2025-12-18T10:50:03Z

rsconnect/subprocesses/inspect_environment.py

+            dest="requirements_file",
+            default="requirements.txt",
+            help="Requirements file name (relative to the directory). Use 'none' to capture via pip freeze.",
+        )


inspect_environment subprocess (the one that runs inside the application environment) now accepts a requirements file argument.

As the argument is passed via command line (thus strings) we use the "none" value to signal the None python value for the requirements_file argument.

I'm not sure if this help is the right place or not, but we should be explicit that "requirements file" here could be both a requirements.txt or requirements.txt.lock file.

I suspect most of our users will read requirements file and think only of requirements.txt, and not think a lock file is even possible (let alone the thing this is possibly most useful for!)

This is the internal inspect_environment.py script we run in a subprocess to inspect the application. It is not exposed to the user. I only changed it to use argparse for the purpose of making more clear (instead of previous positional arguments), but the user never sees this help nor the command

Ok, maybe I missed this elsewhere, do we document this distinction / combination of concepts anywhere? Here isn't the right place, but I want to make sure we communicate to our users that --requirements-file requirements.txt.lock is a thing since IMO that's not actually obvious from the name of the argument alone.

Can you elaborate?
I mean, if you explicitly use --requirements-file X then X could be named anything you want and doesn't even have to be a lockfile, it can be anything listing python dependencies.
So not sure I get what you mean by "we communicate to our users that --requirements-file requirements.txt.lock is a thing"

I tried to improve a bit the "help=X" messages in #750
Feel free to comment on that PR with a better help message if you feel there is space for improvement

amol- · 2025-12-18T10:51:05Z

rsconnect/environment.py

+        click.secho(
+            "    Warning: The requirements file '%s' is outside of the deployment directory.\n" % requirements_file,
+            fg="red",
+        )


Given that the user can now provide a requirements file, the used requirements file might be "../../../something.txt", we want to make sure the user has clear that's not meant to happen.

amol- · 2025-12-18T10:57:20Z

tests/testdata/stock-api-fastapi/main.py

 # -*- coding: utf-8 -*-
 import os
-from datetime import date
+from datetime import date  # noqa: F401


This is just to get rid of an already existing lint error

amol- · 2025-12-18T11:12:30Z

rsconnect/main.py

+        if requirements_file and "jupyter" not in engines:
+            raise RSConnectException(
+                "--requirements-file is only supported for Quarto content using the Jupyter engine."
+            )


My understanding is that quarto has 3 possible values:

jupyter → Python notebooks; needs a Python environment

markdown → plain/markdown docs rendered by Quarto, no Python dependencies

knitr → explicitly rejected by validate_quarto_engines

So we only support the requirements_file option when the engine is Jupyter

jonkeane · 2025-12-18T14:38:10Z

rsconnect/subprocesses/inspect_environment.py


    :param: dirname Directory name
-    :param: force_generate Force the generation of an environment
+    :param: requirements_file The requirements file to read. If None, generate using pip freeze.


Thoughts on if we could incorporate the spirit of #680 into this change too? pip freeze has never been satisfying to most of our users.

You mean making the requirements file a required part of the project?
I think that's a bit out of scope here as it would involve changing the logic of --force-generate option.

I haven't touched the behavior of this function, the pip_freeze was already there, so it's not different from the past behavior. We can definitely enforce the requirements file in a separate PR as you were doing, happy to pick up that work in the context of that PR if you can't move it forward

happy to pick up that work in the context of that PR if you can't move it forward

Thank you, I would very much appreciate that!

toph-allen

Considering the internal logic of the changes in this PR, this generally looks fine to me, and if merging it is required for the demo you plan to give today, go ahead and merge.

I think I'm missing some context about the motivation of this change that I'd like to learn. Before this change, rsconnect-python would use a requirements.txt file if one existed in the current directory, right? So, is this change motivated by a desire to allow different names and directory structures? Or is there something else I'm unaware of?

toph-allen · 2025-12-18T15:20:19Z

rsconnect/environment.py

            "    Warning: Capturing the environment using 'pip freeze'.\n"
-            "             Consider creating a requirements.txt file instead.",
+            "             Consider creating a %s file instead." % requirements_file,


My initial impulse was that if a user explicitly passes in a requirements file path and we can't find a file there, we should emit an error, not a warning.

But I realize we don't have any way to know whether the path we have is one that was explicitly provided or the default from the user, so I guess I'm just noting my weird feeling here.

--requirements-file option

07afaa4

amol- self-assigned this Dec 17, 2025

amol- added 2 commits December 17, 2025 19:12

format

f439cb4

lint and format

aa947e5

amol- added 2 commits December 18, 2025 11:17

Address test on windows

dce2fa3

Fix actions.py:deploy_app

4e2e5eb

amol- marked this pull request as ready for review December 18, 2025 10:45

amol- commented Dec 18, 2025

View reviewed changes

Remove accidental support for 'none' value in command line

9b3577b

amol- commented Dec 18, 2025

View reviewed changes

amol- requested a review from toph-allen December 18, 2025 11:57

Add CHANGELOG entry

a5e85fb

jonkeane reviewed Dec 18, 2025

View reviewed changes

toph-allen approved these changes Dec 18, 2025

View reviewed changes

amol- merged commit 844bb49 into main Dec 18, 2025
44 of 45 checks passed

amol- deleted the requirements-filename branch December 18, 2025 15:43

This was referenced Dec 18, 2025

feat: basic support for uv.lock #750

Merged

bug: allow requirements.txt to not exist #751

Merged

feat: --requirements-file option #748

feat: --requirements-file option #748

Uh oh!

Conversation

amol- commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Intent

Type of Change

Approach

Automated Tests

Directions for Reviewers

Checklist

Uh oh!

github-actions bot commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

☂️ Python Coverage

Overall Coverage

New Files

Modified Files

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amol- Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

toph-allen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

amol- commented Dec 17, 2025 •

edited

Loading

github-actions bot commented Dec 17, 2025 •

edited

Loading

github-actions bot commented Dec 17, 2025 •

edited

Loading

amol- Dec 18, 2025 •

edited

Loading