Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 4 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

- Reads deployment settings from `[tool.posit.connect]` in `pyproject.toml` and generates it in quickstart projects. The legacy `[tool.rsconnect]` name remains supported with a deprecation warning.

### Changed

- Selects Python dependencies consistently for deploy and write-manifest: explicit and configured sources take precedence, followed by `uv.lock`, static `pyproject.toml` dependencies, and `requirements.txt`. Lockfiles are validated offline; generated requirements overwrite `requirements.txt`, with a warning when an existing file is replaced.

### Removed

- **Breaking:** Removes support for running the CLI on Python 3.8–3.10. Installing on those versions resolves to 1.33.2, the last compatible release. Content can still target those versions [#972](https://github.com/posit-dev/rsconnect-python/pull/972).
Expand Down
53 changes: 33 additions & 20 deletions docs/deploying.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,8 @@ rsconnect deploy notebook my-notebook.ipynb data.csv

#### Package Dependencies

If a `requirements.txt` file exists in the same directory as the notebook file, it will
be included in the bundle. It must specify the package dependencies needed to execute
the notebook. Posit Connect will reconstruct the Python environment using the
specified package list.
Dependency sources are selected using the same rules as for Python applications;
see [Python dependency sources](#python-dependency-sources).

With `--force-generate`, rsconnect-python determines package dependencies from the
selected Python environment. It checks `--python`, `VIRTUAL_ENV`, a non-base
Expand Down Expand Up @@ -99,10 +97,8 @@ Install `nbconvert` in the selected Python environment to render static notebook
You can create a `manifest.json` file for a Jupyter Notebook, then use that manifest
in a later deployment. Use the `write-manifest` command to do this.

The `write-manifest` command will also create a `requirements.txt` file, if it does
not already exist or the `--force-generate` option is specified. It will contain the
package dependencies from the selected Python environment, or from an alternative
Python executable specified in the `--python` option.
When dependencies are generated, `write-manifest` writes a separate requirements
file alongside the manifest. See [Python dependency sources](#python-dependency-sources).

Here is an example of the `write-manifest` command:

Expand Down Expand Up @@ -201,10 +197,8 @@ Any directory that appears to be a Python virtual environment (by containing

#### Package Dependencies

If a `requirements.txt` file exists in the API/application directory, it will be
included in the bundle. It must specify the package dependencies needed to execute
the API or application. Posit Connect will reconstruct the Python environment using
the specified package list.
Dependency sources are selected using the same rules as for notebooks; see
[Python dependency sources](#python-dependency-sources).

With `--force-generate`, rsconnect-python determines package dependencies from the
selected Python environment. Use `--python` to select an interpreter explicitly:
Expand Down Expand Up @@ -291,10 +285,8 @@ RENV_PATHS_LOCKFILE=/path/to/renv.lock rsconnect deploy api my-api/
You can create a `manifest.json` file for an API or application, then use that
manifest in a later deployment. Use the `write-manifest` command to do this.

The `write-manifest` command will also create a `requirements.txt` file, if it does
not already exist or the `--force-generate` option is specified. It will contain
the package dependencies from the selected Python environment, or from an alternative
Python executable specified in the `--python` option.
When dependencies are generated, `write-manifest` writes a separate requirements
file alongside the manifest. See [Python dependency sources](#python-dependency-sources).

Here is an example of the `write-manifest` command:

Expand Down Expand Up @@ -394,10 +386,31 @@ rsconnect deploy pyproject my_app/
```

The directory passed to `deploy pyproject` must contain `pyproject.toml`.
Dependencies follow the same resolution rules as the other deploy commands:
`[project.dependencies]` from `pyproject.toml` provides the dependency
snapshot, and `uv.lock` or `requirements.txt` may be supplied via
`--requirements-file` when a pinned environment is needed.
Dependencies follow the same resolution rules as the other deploy commands.

### Python dependency sources

Python deployment and manifest commands choose a dependency source in this order:
`--requirements-file`, `requirements_file` in `[tool.posit.connect]` (or the
legacy `[tool.rsconnect]` table), then `uv.lock`, `pyproject.toml`, and
`requirements.txt`. Automatic selection uses `pyproject.toml` only when
`[project].dependencies` is explicitly declared as a static list; an empty list
is valid. A selected source must be valid and readable: rsconnect-python will
not fall back to another source if it fails.

A selected `uv.lock` must be current with its companion `pyproject.toml`.
rsconnect-python validates and exports it offline without updating it. If the
lock is stale, run `uv lock` before retrying. If offline validation cannot
complete, ensure uv can find a Python interpreter compatible with the project's
`requires-python` (for example, run `uv python install <version>` while online)
and prepare the lock and uv cache before retrying.

Use `--force-generate` to snapshot the selected Python environment instead of
using a dependency source. It cannot be combined with `--requirements-file`.
When dependencies come from anything other than an unchanged requirements
file (`uv.lock`, `pyproject.toml`, or `--force-generate`), `write-manifest`
writes them to `requirements.txt`, **overwriting any existing file** at that
path. rsconnect-python prints a warning before it overwrites the file.

### Options for All Types of Deployments

Expand Down
20 changes: 20 additions & 0 deletions rsconnect/bundle.py
Original file line number Diff line number Diff line change
Expand Up @@ -2539,6 +2539,14 @@ def write_nodejs_manifest_json(
write_manifest_json(manifest_path, manifest)


_GENERATED_SOURCE_DESCRIPTIONS = {
"pip_freeze": "snapshotted from the Python environment (--force-generate)",
"uv_lock": "exported from uv.lock",
"pyproject_toml": "generated from pyproject.toml [project].dependencies",
"derived_file": "normalized from the selected requirements file",
}


def write_environment_file(
environment: Environment,
directory: str,
Expand All @@ -2552,6 +2560,18 @@ def write_environment_file(
:param directory: the directory where the file should be written.
"""
environment_file_path = join(directory, environment.filename)
if environment.source != "file" and os.path.islink(environment_file_path):
raise RSConnectException(f"Cannot overwrite symlink at generated requirements path {environment_file_path}.")
if environment.source != "file":
description = _GENERATED_SOURCE_DESCRIPTIONS.get(environment.source, environment.source)
if exists(environment_file_path):
warn_user(
f"Overwriting {environment_file_path} with requirements {description}. "
"The previous contents of this file will be lost. To deploy an existing requirements file "
"unchanged, pass it with --requirements-file."
)
else:
logger.info(f"Writing {environment_file_path} with requirements {description}.")
# Write bytes so that the file matches the manifest checksum on all platforms.
# Text mode changes line endings and encoding on Windows.
with open(environment_file_path, "wb") as f:
Expand Down
16 changes: 16 additions & 0 deletions rsconnect/environment.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@
from .exception import RSConnectException
from .subprocesses.inspect_environment import EnvironmentData, MakeEnvironmentData as _MakeEnvironmentData

GENERATED_REQUIREMENTS_HEADER = "# Generated by rsconnect-python; overwritten on each manifest write.\n"


class PackageInstaller(StrEnum):
PIP = "pip"
Expand Down Expand Up @@ -151,6 +153,20 @@ def create_python_environment(
)
environment.python_version_requirement = python_version_requirement

if environment.source == "file" and requirements_file is not None:
source_path = pathlib.Path(directory) / requirements_file
try:
with source_path.open("r", encoding="utf-8", newline="") as source:
unchanged = source.read() == environment.contents
except (OSError, UnicodeError) as err:
raise RSConnectException(f"Cannot read requirements source {requirements_file}: {err}") from err
if not unchanged:
environment.source = "derived_file"

if environment.source != "file":
environment.filename = "requirements.txt"
environment.contents = GENERATED_REQUIREMENTS_HEADER + environment.contents

if environment.source == "pip_freeze":
mismatch = pyproject.local_python_mismatch(python_version_requirement, environment.python)
if mismatch:
Expand Down
6 changes: 6 additions & 0 deletions rsconnect/log.py
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,11 @@ def set_in_feedback(self, value: bool):
self._in_feedback = value
self._have_feedback_output = False

def end_feedback_line(self) -> None:
if self._in_feedback and not self._have_feedback_output:
click.echo(err=self._quiet)
self._have_feedback_output = True

def set_quiet(self, value: bool):
self._quiet = value

Expand Down Expand Up @@ -187,6 +192,7 @@ def warn_user(message: str, fg: str = "yellow") -> None:
In quiet mode the warning is routed to stderr so that stdout stays
reserved for the content URL.
"""
logger.end_feedback_line()
click.secho(message, fg=fg, err=logger.quiet)


Expand Down
Loading
Loading