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
) -> 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 
 20
 21
 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
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,
) -> 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,
    )
    command: tuple[str, ...] = (
        sys.executable,
        "-m",
        "pip",
        "install",
        "--upgrade",
        *frozen_requirements,
    )
    check_output(command)
    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,
        )