Skip to content

dependence.upgrade

upgrade 

upgrade(
    requirements: collections.abc.Iterable[str],
    *,
    ignore_update: collections.abc.Iterable[str] = (),
    all_extra_name: str = "",
    include_pointers: tuple[str, ...] = (),
    exclude_pointers: tuple[str, ...] = (),
    exclude: collections.abc.Iterable[str] = (),
    exclude_recursive: collections.abc.Iterable[str] = (),
    depth: int | None = None,
    echo: bool = False
) -> None

This function obtains a list of dependencies for the specified requirements using dependence.update.get_frozen_requirements(), upgrades all of these dependencies in the current environment, then updates version specifiers for all requirements/dependencies in any or the requirements which are project config files to align with the newly installed package versions (using dependence.update.update()).

Parameters:

  • requirements (collections.abc.Iterable[str]) –

    One or more requirement specifiers (for example: "requirement-name[extra-a,extra-b]" or ".[extra-a, extra-b]) and/or paths to a setup.py, setup.cfg, pyproject.toml, tox.ini or requirements.txt file.

  • ignore_update (collections.abc.Iterable[str], default: () ) –

    One or more project names to ignore (leave as-is) when updating a dependency's requirement specifier in the provided pyproject.toml/setup.cfg/requirements.txt/tox.ini file(s). Note that this does not prevent the package from being upgraded—for that you need to pass the package name in exclude or exclude_recursive.

  • all_extra_name (str, default: '' ) –

    If provided, an extra which consolidates the requirements for all other extras will be added/updated to pyproject.toml or setup.cfg (this argument is ignored for requirements.txt and tox.ini files).

  • include_pointers (tuple[str, ...], default: () ) –

    A tuple of JSON pointers indicating elements to include (defaults to all elements). This applies only to TOML files (including pyproject.toml), and is ignored for all other file types.

  • exclude_pointers (tuple[str, ...], default: () ) –

    A tuple of JSON pointers indicating elements to exclude (defaults to no exclusions). This applies only to TOML files (including pyproject.toml), and is ignored for all other file types.

  • exclude (collections.abc.Iterable[str], default: () ) –

    One or more distributions to exclude when upgrading packages.

  • exclude_recursive (collections.abc.Iterable[str], default: () ) –

    One or more distributions to exclude when upgrading packages. Recursive dependency discovery is also halted for these distributions, unlike those passed to exclude.

  • depth (int | None, default: None ) –

    The maximum recursion depth to traverse when discovering dependencies. If None (the default), all dependencies are discovered.

Source code in src/dependence/upgrade.py 
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def upgrade(
    requirements: Iterable[str],
    *,
    ignore_update: Iterable[str] = (),
    all_extra_name: str = "",
    include_pointers: tuple[str, ...] = (),
    exclude_pointers: tuple[str, ...] = (),
    exclude: Iterable[str] = (),
    exclude_recursive: Iterable[str] = (),
    depth: int | None = None,
    echo: bool = False,
) -> None:
    """
    This function obtains a list of dependencies for the specified
    `requirements` using `dependence.update.get_frozen_requirements()`,
    upgrades all of these dependencies in the current environment,
    then updates version specifiers for all requirements/dependencies
    in any or the `requirements` which are project config files
    to align with the newly installed package versions (using
    `dependence.update.update()`).

    Parameters:
        requirements: One or more requirement specifiers (for example:
            "requirement-name[extra-a,extra-b]" or ".[extra-a, extra-b]) and/or
            paths to a setup.py, setup.cfg, pyproject.toml, tox.ini or
            requirements.txt file.
        ignore_update: One or more project names to ignore (leave as-is)
            when updating a dependency's requirement specifier in the
            provided pyproject.toml/setup.cfg/requirements.txt/tox.ini
            file(s). Note that this does not prevent the package from being
            upgraded—for that you need to pass the package name in
            `exclude` or `exclude_recursive`.
        all_extra_name: If provided, an extra which consolidates
            the requirements for all other extras will be added/updated to
            pyproject.toml or setup.cfg (this argument is ignored for
            requirements.txt and tox.ini files).
        include_pointers: A tuple of JSON pointers indicating elements to
            include (defaults to all elements). This applies only to TOML
            files (including pyproject.toml), and is ignored for all other
            file types.
        exclude_pointers: A tuple of JSON pointers indicating elements to
            exclude (defaults to no exclusions). This applies only to TOML
            files (including pyproject.toml), and is ignored for all other
            file types.
        exclude: One or more distributions to exclude when upgrading packages.
        exclude_recursive: One or more distributions to exclude when
            upgrading packages. Recursive dependency discovery is also
            halted for these distributions, unlike those passed to `exclude`.
        depth: The maximum recursion depth to traverse when discovering
            dependencies. If `None` (the default), all dependencies are
            discovered.
    """
    frozen_requirements: tuple[str, ...] = get_frozen_requirements(
        requirements,
        exclude=exclude,
        exclude_recursive=exclude_recursive,
        keep_version_specifier="*",
        no_version="*",
        depth=depth,
        include_pointers=include_pointers,
        exclude_pointers=exclude_pointers,
    )
    if frozen_requirements:
        command: tuple[str, ...]
        uv: str | None = shutil.which("uv")
        shell: bool = False
        if uv:
            if is_aliased("uv"):
                shell = True
                uv = "uv"
            command = (
                uv,
                "pip",
                "install",
                "--python",
                sys.executable,
                "--upgrade",
                *frozen_requirements,
            )
        else:
            # If `uv` is not available, use `pip`
            if is_aliased("pip"):
                shell = True
                command = (
                    "pip",
                    "install",
                    "--python",
                    sys.executable,
                )
            else:
                command = (
                    sys.executable,
                    "-m",
                    "pip",
                    "install",
                )
            command = (
                *command,
                "--upgrade",
                *frozen_requirements,
            )
        check_output(command, shell=shell, echo=echo)
    configuration_files: tuple[str, ...] = tuple(
        chain(
            *map(iter_configuration_files, requirements)  # type: ignore
        )
    )
    if configuration_files:
        update(
            configuration_files,
            ignore=ignore_update,
            all_extra_name=all_extra_name,
            include_pointers=include_pointers,
            exclude_pointers=exclude_pointers,
        )