rsconnect-python 1.30.0__py3-none-any.whl

rsconnect/utils_package.py

@@ -0,0 +1,261 @@
+"""
+Utility functions related to packages and versions.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple, cast
+
+from typing import Literal
+
+import semver
+
+from .environment import Environment
+from .log import logger
+from .models import AppMode, AppModes
+
+ComparisonOperator = Literal[">=", "<=", ">", "<", "==", "!="]
+
+
+class VersionInfo(NamedTuple):
+    operator: ComparisonOperator
+    version: str
+
+
+class PackageInfo(NamedTuple):
+    name: str
+    specs: list[VersionInfo]
+
+
+def compare_semvers(version1: str, version2: str) -> Literal[-1, 0, 1]:
+    """
+    Compare semver-like version numbers. This should be used for comparing Connect
+    versions, but not Python package versions.
+
+    This is a wrapper for semver.VersionInfo.compare(), but it can handle some version
+    strings that are not strictly valid semver strings. Specifically, it can handle
+    strings like "2024.01.0", which have a leading '0' in a version part. The leading
+    zero in "01" makes it an invalid semver string.
+
+    Note that semvers always have three parts, so "0.12" is not a valid semver. This
+    function can be safely used for comparing Connect version numbers, but not for
+    comparing Python package numbers, because the latter may not have exactly three
+    parts.
+
+    This function is better for comparing Connect version numbers than
+    compare_package_versions(), because the latter doesn't handle the prerelease and
+    build components of the version string. For "2024.01.0-dev+20-abcd", the prerelease
+    and build components are "dev" and "20-abcd", respectively.
+
+    :return: -1 if version1 < version2, 0 if version1 == version2, or 1 if version1 >
+        version2.
+    """
+
+    version1 = _remove_leading_zeros(version1)
+    version2 = _remove_leading_zeros(version2)
+
+    return semver.VersionInfo.parse(version1).compare(version2)  # type: ignore
+
+
+def _remove_leading_zeros(version: str) -> str:
+    """
+    Given a version string like "2024.01.0-dev+20-abcd", remove any leading zeros in a
+    version part, so that the result is "2024.1.0-dev+20-abcd".
+    """
+    parts = version.split(".")
+    parts = [re.sub(r"^0+(\d)", "\\1", x) for x in parts]
+    return ".".join(parts)
+
+
+def compare_package_versions(version1: str, version2: str) -> Literal[-1, 0, 1]:
+    """
+    Compare two package versions. This function is similar to compare_semvers(), but it
+    can accept version numbers with any number of parts (instead of exactly three). It
+    is used to compare package versions, which may not be valid semver strings.
+    """
+    parts1 = [int(x) for x in version1.split(".")]
+    parts2 = [int(x) for x in version2.split(".")]
+
+    max_length = max(len(parts1), len(parts2))
+    parts1 += [0] * (max_length - len(parts1))
+    parts2 += [0] * (max_length - len(parts2))
+
+    for part1, part2 in zip(parts1, parts2):
+        if part1 > part2:
+            return 1
+        elif part1 < part2:
+            return -1
+
+    return 0
+
+
+def parse_requirements_txt(requirements_txt: str) -> list[PackageInfo]:
+    """
+    Given a string of requirements (like the contents of a requirements.txt file), find
+    the version of the package that is installed. This is done by finding the line that
+    starts with the package name, and then extracting the version from that line.
+
+    :param requirements_txt: The contents of a requirements.txt file.
+    :param package: The name of the package to find.
+
+    :return: A list of PackageInfo objects.
+    """
+    # Note that this parser is not perfect. If we want to perfectly parse a
+    # requirements.txt file, we could use the requirements-parser package, but that
+    # would introduce another dependency.
+
+    package_info: list[PackageInfo] = []
+
+    for line in requirements_txt.split("\n"):
+        # Skip blank lines or comment lines
+        if re.match(r"^\s*$", line) or re.match(r"^\s*#", line):
+            continue
+
+        pkg_match = re.match(r"^([A-Z0-9][A-Z0-9][A-Z0-9._-]*[A-Z0-9])(.*)", line, flags=re.IGNORECASE)
+        if pkg_match is None:
+            continue
+
+        # If the line is "foo>=1.0", this is "foo".
+        pkg_name = cast(str, pkg_match.group(1))
+
+        # If the line is "foo>=1.0", this is ">=1.0".
+        pkg_version_string = cast(str, pkg_match.group(2)).strip()
+        # Remove comment from version string, if present.
+        pkg_version_string = re.sub(r"#.*$", "", pkg_version_string).strip()
+        pkg_version_specs = _parse_version_specs(pkg_version_string)
+
+        package_info.append(PackageInfo(name=pkg_name, specs=pkg_version_specs))
+
+    return package_info
+
+
+def _parse_version_specs(version_specs: str) -> list[VersionInfo]:
+    """
+    Parse a version spec string like ">=1.0,<=2.0" into a list of tuples like [(">=",
+    "1.0"), ("<=", "2.0")]. If there is a semicolon, as in "==1.0;
+    python_version<'3.8'", then the semicolon and everything after it is ignored.
+    If it finds a spec string that it is unable to parse, it will ignore that string.
+    """
+
+    version_specs = version_specs.split(";")[0].strip()
+    if version_specs.strip() == "":
+        return []
+    version_spec_strings = [x.strip() for x in version_specs.split(",")]
+
+    version_infos: list[VersionInfo] = []
+    for version_spec_string in version_spec_strings:
+        spec = _parse_version_spec(version_spec_string)
+        if spec is not None:
+            version_infos.append(spec)
+
+    return version_infos
+
+
+def _parse_version_spec(version_spec: str) -> VersionInfo | None:
+    """
+    Parse a version spec string like ">=1.0" into a tuple like (">=", "1.0"). If it is
+    unable to parse the string, return None.
+
+    For the purposes for which this function is used, it makes sense to return None if
+    the spec can't be parsed, instead of raising an exception. For our use cases, we do
+    not want to interrupt the flow of the program if we encounter malformed input.
+    """
+    for op in (">=", "<=", ">", "<", "==", "!="):
+        if version_spec.startswith(op):
+            return VersionInfo(op, version_spec[len(op) :].strip())  # type: ignore
+    return None
+
+
+def find_package_info(package: str, requirements: list[PackageInfo]) -> PackageInfo | None:
+    """
+    Given a package name and a list of PackageInfo objects, find the PackageInfo object
+    that corresponds to the package name. If the package is not found, return None.
+    """
+    for pkg_info in requirements:
+        if pkg_info.name == package:
+            return pkg_info
+    return None
+
+
+def replace_requirement(package_name: str, replacement: str, requirements_txt: str) -> str:
+    """
+    Given a requirements.txt file and a package name, replace the line of
+    requirements.txt for that package, with the replacement string, and return the
+    modified requirements.txt.
+
+    Note that package_name is a regular expression, so if the target package name
+    contains a ".", it should be escaped, as in "foo\\.bar".
+    """
+    lines = requirements_txt.split("\n")
+    new_lines: list[str] = []
+
+    for line in lines:
+        new_line = re.sub(f"^{package_name}([^a-zA-Z0-9._-].*?)?$", replacement, line)
+        new_lines.append(new_line)
+
+    return "\n".join(new_lines)
+
+
+def fix_starlette_requirements(
+    environment: Environment,
+    app_mode: AppMode,
+    connect_version_string: str,
+) -> Environment:
+    """
+    Ensure that the starlette version in an Environment is compatible with the Connect
+    server.
+
+    If the app mode is PYTHON_SHINY and the Connect server version is less than
+    2024.01.0, then make sure the starlette version is less than 0.35.0, due to an
+    incompatibility with between older Connect<2024.01.0 and starlette>=0.35.0.
+
+    After all users are on Connect 2024.01.0 or later, this function can be removed.
+
+    For more information, see https://github.com/posit-dev/py-shiny/issues/1114
+
+    :return: Either a modified environment (if changes were needed), or the original
+    environment.
+    """
+    if not (app_mode == AppModes.PYTHON_SHINY and compare_semvers(connect_version_string, "2024.01.0") == -1):
+        return environment
+
+    requirements_txt = environment.contents
+
+    reqs = parse_requirements_txt(requirements_txt)
+    starlette_req = find_package_info("starlette", reqs)
+
+    # If didn't ask for specific version of starlette, add starlette<0.35.0.
+    # If pinned version is <0.35.0, do nothing.
+    # If pinned version is >=0.35.0, change the version and emit warning
+    # If more complex version spec (that doesn't use ==), do nothing.
+
+    if starlette_req is None:
+        # starlette is not listed in requirements.
+        # Add starlette<0.35.0 to requirements.
+        requirements_txt = requirements_txt.rstrip("\n") + "\nstarlette<0.35.0\n"
+        environment = environment._replace(contents=requirements_txt)
+
+    elif len(starlette_req.specs) == 0:
+        # starlette is in requirements, but without a version specification.
+        # Replace it with starlette<0.35.0.
+        requirements_txt = replace_requirement("starlette", "starlette<0.35.0", requirements_txt)
+        environment = environment._replace(contents=requirements_txt)
+
+    elif len(starlette_req.specs) == 1 and starlette_req.specs[0].operator == "==":
+        if compare_semvers(starlette_req.specs[0].version, "0.35.0") >= 0:
+            # starlette is in requirements.txt, but with a version spec that is
+            # not compatible with this version of Connect.
+            logger.warning(
+                "Starlette version is 0.35.0 or greater, but this version of Connect "
+                "requires starlette<0.35.0. Setting to <0.35.0."
+            )
+            requirements_txt = replace_requirement("starlette", "starlette<0.35.0", requirements_txt)
+            environment = environment._replace(contents=requirements_txt)
+    else:
+        # If more complex version spec (e.g., it uses something other than == or
+        # has multiple specs), do nothing, because this is an advanced user that
+        # is doing something complicated.
+        pass
+
+    return environment

rsconnect/validation.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import click
+
+from rsconnect.exception import RSConnectException
+
+
+def get_parameter_source_name_from_ctx(
+    var_or_param_name: str,
+    ctx: Optional[click.Context],
+) -> str:
+    if ctx:
+        varName = var_or_param_name.replace("-", "_")
+        source = ctx.get_parameter_source(varName)
+        if source and source.name:
+            return source.name
+    return "<source unknown>"
+
+
+def _get_present_options(
+    options: dict[str, Optional[Any]],
+    ctx: Optional[click.Context],
+) -> list[str]:
+    result: list[str] = []
+    for k, v in options.items():
+        if v:
+            parts = k.split("--")
+            if ctx and len(parts) == 2:
+                sourceName = get_parameter_source_name_from_ctx(parts[1], ctx)
+                result.append(f"{k} (from {sourceName})")
+            else:
+                result.append(f"{k}")
+    return result
+
+
+def validate_connection_options(
+    ctx: Optional[click.Context],
+    url: Optional[str],
+    api_key: Optional[str],
+    insecure: bool,
+    cacert: Optional[str],
+    account_name: Optional[str],
+    token: Optional[str],
+    secret: Optional[str],
+    name: Optional[str] = None,
+    snowflake_connection_name: Optional[str] = None,
+    has_default_server: bool = False,
+):
+    """
+    Validates provided Connect or shinyapps.io connection options and returns which target to use given the provided
+    options.
+
+    rsconnect deploy api --name localhost ./python-bottle-py3
+    should fail w/
+    -s/--server or CONNECT_SERVER
+    -T/--token or SHINYAPPS_TOKEN or RSCLOUD_TOKEN
+    -S/--secret or SHINYAPPS_SECRET or RSCLOUD_SECRET
+    -A/--account or SHINYAPPS_ACCOUNT
+
+    FAILURE if not any of:
+    -n/--name
+    -s/--server or CONNECT_SERVER
+    -T/--token or SHINYAPPS_TOKEN or RSCLOUD_TOKEN
+    -S/--secret or SHINYAPPS_SECRET or RSCLOUD_SECRET
+    -A/--account or SHINYAPPS_ACCOUNT
+    --snowflake-connection-name
+
+    FAILURE if any of:
+    -k/--api-key or CONNECT_API_KEY
+    -i/--insecure or CONNECT_INSECURE
+    -c/--cacert or CONNECT_CA_CERTIFICATE
+    AND any of:
+    -T/--token or SHINYAPPS_TOKEN
+    -S/--secret or SHINYAPPS_SECRET
+    -A/--account or SHINYAPPS_ACCOUNT
+
+    FAILURE if any of following are specified, without the rest:
+    -T/--token or SHINYAPPS_TOKEN
+    -S/--secret or SHINYAPPS_SECRET
+    -A/--account or SHINYAPPS_ACCOUNT
+
+
+    FAILURE if -s/--server or CONNECT_SERVER include "snowflakecomputing.app"
+    and not
+    --snowflake-connection-name
+    """
+    connect_options = {"-k/--api-key": api_key, "-i/--insecure": insecure, "-c/--cacert": cacert}
+    shinyapps_options = {"-T/--token": token, "-S/--secret": secret, "-A/--account": account_name}
+    spcs_options = {"--snowflake-connection-name": snowflake_connection_name}
+    options_mutually_exclusive_with_name = {"-s/--server": url, **shinyapps_options}
+    present_options_mutually_exclusive_with_name = _get_present_options(options_mutually_exclusive_with_name, ctx)
+
+    if name and present_options_mutually_exclusive_with_name:
+        name_source = get_parameter_source_name_from_ctx("name", ctx)
+        raise RSConnectException(
+            f"-n/--name (from {name_source}) cannot be specified in conjunction with options \
+{', '.join(present_options_mutually_exclusive_with_name)}. See command help for further details."
+        )
+
+    if not name and not url and not any(shinyapps_options.values()) and not has_default_server:
+        raise RSConnectException(
+            "You must specify one of -n/--name OR -s/--server OR -T/--token, -S/--secret, \
+either via command options or environment variables. See command help for further details."
+        )
+
+    present_connect_options = _get_present_options(connect_options, ctx)
+    present_shinyapps_options = _get_present_options(shinyapps_options, ctx)
+    present_spcs_options = _get_present_options(spcs_options, ctx)
+
+    if present_connect_options and present_shinyapps_options:
+        raise RSConnectException(
+            f"Connect options ({', '.join(present_connect_options)}) may not be passed \
+alongside shinyapps.io options ({', '.join(present_shinyapps_options)}). \
+See command help for further details."
+        )
+
+    if snowflake_connection_name and not url:
+        raise RSConnectException(
+            "--snowflake-connection-name requires -s/--server to be specified. \
+See command help for further details."
+        )
+
+    if present_shinyapps_options and present_spcs_options:
+        raise RSConnectException(
+            f"Shinyapps.io options ({', '.join(present_shinyapps_options)}) may not be passed \
+alongside SPCS options ({', '.join(present_spcs_options)}). \
+    See command help for further details."
+        )
+
+    if present_shinyapps_options:
+        if len(present_shinyapps_options) != len(shinyapps_options):
+            raise RSConnectException(
+                "-A/--account, -T/--token, and -S/--secret must all be provided \
+for shinyapps.io. See command help for further details."
+            )
+
+
+class PythonVersionParamType(click.ParamType):
+    name = "python-version"
+
+    def convert(self, value: str, param: Optional[click.Parameter], ctx: Optional[click.Context]):
+        try:
+            parts = list(map(int, value.split(".")))
+            if len(parts) == 3:
+                return value
+            elif len(parts) == 2:
+                return value + ".0"
+            else:
+                raise ValueError
+        except (AttributeError, ValueError):
+            self.fail(f"{value!r} is not a valid python version; expected 3.x or 3.x.y", param, ctx)
+
+
+PYTHON_VERSION = PythonVersionParamType()

rsconnect/version_check.py

@@ -0,0 +1,154 @@
+"""Background version update check against PyPI.
+
+Checked only on deploy commands. The latest known version is cached on disk and
+refreshed at most once per :data:`_CACHE_TTL_SECONDS` in a background thread, so a
+warm cache adds no network traffic and no latency and prints on every exit path
+(including fast failures). Only a cold cache -- the first run, or an ephemeral
+environment where the cache never persists -- waits briefly on the fetch so it can
+still warn.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from http.client import HTTPSConnection
+from os.path import join
+from typing import Optional, Tuple
+
+from packaging.version import Version
+
+from . import VERSION
+from .metadata import config_dirname, makedirs
+
+RSCONNECT_DISABLE_VERSION_CHECK = "RSCONNECT_DISABLE_VERSION_CHECK"
+_PYPI_HOST = "pypi.org"
+_PYPI_PATH = "/pypi/rsconnect-python/json"
+_PYPI_TIMEOUT_SECONDS = 2
+_CACHE_TTL_SECONDS = 24 * 60 * 60  # Re-check PyPI at most once a day.
+_CACHE_FILENAME = "version_check.json"
+
+
+def _is_check_disabled() -> bool:
+    value = os.environ.get(RSCONNECT_DISABLE_VERSION_CHECK, "").strip().lower()
+    return value in ("1", "true", "yes")
+
+
+def _is_dev_version(version_str: str) -> bool:
+    try:
+        return Version(version_str).is_devrelease
+    except Exception:
+        return True
+
+
+def _cache_path() -> str:
+    return join(config_dirname(), _CACHE_FILENAME)
+
+
+def _read_cache() -> Tuple[bool, Optional[str]]:
+    """Return ``(is_fresh, latest)``.
+
+    ``latest`` is the last known PyPI version recorded in the cache (or None when
+    the cache is missing/unreadable or the last fetch failed). It is returned
+    regardless of freshness so even a stale value can drive the upgrade hint while
+    a refresh runs in the background. ``is_fresh`` is True only when the entry is
+    within the TTL, signalling that no background refresh is needed.
+    """
+    try:
+        with open(_cache_path()) as f:
+            data = json.load(f)
+        latest = data.get("latest")
+        latest = latest if isinstance(latest, str) else None
+        is_fresh = time.time() - float(data["checked_at"]) <= _CACHE_TTL_SECONDS
+        return (is_fresh, latest)
+    except Exception:
+        return (False, None)
+
+
+def _write_cache(latest: Optional[str]) -> None:
+    """Persist the latest known version (or None) with the current timestamp.
+
+    A None value is still cached so repeated failures don't re-hit PyPI on every
+    deploy until the TTL expires.
+    """
+    try:
+        path = _cache_path()
+        makedirs(path)
+        with open(path, "w") as f:
+            json.dump({"checked_at": time.time(), "latest": latest}, f)
+    except Exception:
+        pass
+
+
+def _fetch_latest_version() -> Optional[str]:
+    conn = None
+    try:
+        conn = HTTPSConnection(_PYPI_HOST, timeout=_PYPI_TIMEOUT_SECONDS)
+        conn.request("GET", _PYPI_PATH, headers={"Accept": "application/json"})
+        response = conn.getresponse()
+        if response.status != 200:
+            return None
+        data = json.loads(response.read())
+        return data.get("info", {}).get("version")
+    except Exception:
+        return None
+    finally:
+        if conn is not None:
+            conn.close()
+
+
+def _update_message(latest: Optional[str]) -> Optional[str]:
+    """Return an upgrade warning if ``latest`` is newer than the running version."""
+    try:
+        if latest is not None and Version(latest) > Version(VERSION):
+            return (
+                f"A new version of rsconnect-python is available: {latest} "
+                f"(you have {VERSION}).\n"
+                f"Upgrade with: pip install --upgrade rsconnect-python"
+            )
+    except Exception:
+        pass
+    return None
+
+
+class BackgroundVersionCheck:
+    """Resolves the latest available version, using a cache and a background fetch."""
+
+    def __init__(self) -> None:
+        self._thread: Optional[threading.Thread] = None
+        self._latest: Optional[str] = None
+
+    def start(self) -> None:
+        if _is_check_disabled() or _is_dev_version(VERSION):
+            return
+        is_fresh, latest = _read_cache()
+        # Seed the hint from the cached value (even a stale one is good enough to
+        # suggest an upgrade), so a warm cache prints instantly on every exit path
+        # -- including commands that fail fast.
+        self._latest = latest
+        if not is_fresh:
+            # Refresh in the background so the fetch overlaps the command's own
+            # work. A warm or stale cache never waits on this; only a cold cache
+            # waits briefly at exit -- see get_warning_message.
+            self._thread = threading.Thread(target=self._run, daemon=True)
+            self._thread.start()
+
+    def _run(self) -> None:
+        latest = _fetch_latest_version()
+        _write_cache(latest)
+        # Adopt a successful result so a cold-cache run can warn this time, but
+        # never overwrite a usable cached value with a failed (None) refresh.
+        if latest is not None:
+            self._latest = latest
+
+    def get_warning_message(self) -> Optional[str]:
+        # With no cached value yet (a cold cache: first run, or an ephemeral
+        # environment where the cache never persists), give the in-flight fetch a
+        # bounded chance to finish so this run can still warn. The bound is the
+        # fetch's own time budget -- a slower network just means no hint this run.
+        # A warm or stale cache already has a value here and never waits.
+        if self._latest is None and self._thread is not None:
+            self._thread.join(timeout=_PYPI_TIMEOUT_SECONDS)
+        return _update_message(self._latest)

rsconnect_python-1.30.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.3
+Name: rsconnect_python
+Version: 1.30.0
+Summary: The Posit Connect command-line interface.
+Author: Posit, PBC
+Author-email: Posit, PBC <rsconnect@posit.co>
+License: # MIT License
+         
+         Copyright (c) 2025 Posit Software, PBC
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Requires-Dist: typing-extensions>=4.8.0
+Requires-Dist: pip>=10.0.0
+Requires-Dist: uv>=0.9.0
+Requires-Dist: semver>=2.0.0,<4.0.0
+Requires-Dist: pyjwt>=2.4.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: packaging>=20.0
+Requires-Dist: toml>=0.10 ; python_full_version < '3.11'
+Requires-Dist: keyring>=23.0.0 ; extra == 'keyring'
+Requires-Dist: snowflake-cli ; extra == 'snowflake'
+Requires-Python: >=3.8
+Project-URL: Repository, http://github.com/posit-dev/rsconnect-python
+Project-URL: Documentation, https://docs.posit.co/rsconnect-python
+Provides-Extra: keyring
+Provides-Extra: snowflake
+Description-Content-Type: text/markdown
+
+# [rsconnect-python](https://docs.posit.co/rsconnect-python)
+
+The [Posit Connect](https://docs.posit.co/connect/) command-line interface.
+
+## Installation
+
+### uv
+
+```bash
+uv tool install rsconnect-python
+```
+
+### pipx
+
+```bash
+pipx install rsconnect-python
+```
+
+### into your project
+
+```bash
+python -m pip install rsconnect-python
+```
+
+## Usage
+
+[Get an API key from your Posit Connect server](https://docs.posit.co/connect/user/api-keys/) with at least publisher privileges:
+
+Store your credentials:
+
+```bash
+rsconnect add --server https://connect.example.com --api-key <YOUR-CONNECT-API-KEY> --name production
+```
+
+Deploy your application:
+
+```bash
+rsconnect deploy shiny app.py --title "my shiny app"
+```
+
+[Read more about publisher and admin capabilities on the docs site.](https://docs.posit.co/rsconnect-python)
+
+## Contributing
+
+[Contributing docs](./CONTRIBUTING.md)