dependence.update

_Version dataclass

Instances of this class can be be passed as self in a call to packaging.version.Version.__str__, and thereby can facilitate operations to mimic mutability for the aforementioned class.

Source code in src/dependence/update.py

@dataclass
class _Version:
    """
    Instances of this class can be be passed as `self` in a call
    to `packaging.version.Version.__str__`, and thereby can facilitate
    operations to mimic mutability for the aforementioned class.
    """

    epoch: int
    release: tuple[int, ...]
    pre: Any
    post: Any
    dev: Any
    local: Any

_update_requirement_specifiers

_update_requirement_specifiers(
    requirement: packaging.requirements.Requirement,
    installed_version_string: str,
) -> None

This function updates specifier version numbers for a requirement to match the installed version of the package

Source code in src/dependence/update.py

def _update_requirement_specifiers(
    requirement: Requirement, installed_version_string: str
) -> None:
    """
    This function updates specifier version numbers for a requirement
    to match the installed version of the package
    """
    installed_version: Version = parse_version(installed_version_string)
    specifier: Specifier
    updated_specifier_strings: list[str] = []
    for specifier in requirement.specifier:  # type: ignore
        # Only update requirement to match our installed version
        # if the requirement is *inclusive*
        if ("=" in specifier.operator) and ("!" not in specifier.operator):
            specifier_version: Version = parse_version(specifier.version)
            if installed_version.release is None:
                raise ValueError(installed_version)
            if specifier_version.release is None:
                updated_specifier_strings.append(f"{specifier.operator}")
            else:
                greater_or_equal_specificity: bool = len(
                    specifier_version.release
                ) >= len(installed_version.release)
                specifier_version_data: _Version = _Version(
                    epoch=installed_version.epoch,
                    # Truncate the updated version requirement at the same
                    # level of specificity as the old
                    release=installed_version.release[
                        : len(specifier_version.release)
                    ],
                    pre=(
                        installed_version.pre
                        if greater_or_equal_specificity
                        else None
                    ),
                    post=(
                        installed_version.post
                        if greater_or_equal_specificity
                        else None
                    ),
                    dev=(
                        installed_version.dev
                        if greater_or_equal_specificity
                        else None
                    ),
                    local=(
                        installed_version.local
                        if greater_or_equal_specificity
                        else None
                    ),
                )
                version_string: str = Version.__str__(
                    specifier_version_data  # type: ignore
                )
                updated_specifier_strings.append(
                    f"{specifier.operator}{version_string}"
                )
        else:
            updated_specifier_strings.append(str(specifier))
    requirement.specifier = SpecifierSet(",".join(updated_specifier_strings))

_get_updated_requirement_string

_get_updated_requirement_string(
    requirement_string: str, ignore: set[str]
) -> str

This function updates version numbers in a requirement string to match those installed in the current environment

Source code in src/dependence/update.py

def _get_updated_requirement_string(
    requirement_string: str, ignore: set[str]
) -> str:
    """
    This function updates version numbers in a requirement string to match
    those installed in the current environment
    """
    # Skip empty requirement strings
    if not is_requirement_string(requirement_string):
        return requirement_string
    requirement: Requirement = Requirement(requirement_string)
    name: str = normalize_name(requirement.name)
    if name in ignore:
        return requirement_string
    try:
        distribution: Distribution = get_installed_distributions()[name]
        _update_requirement_specifiers(requirement, distribution.version)
    except KeyError:
        # If the requirement isn't installed, we can't update the version
        pass
    return str(requirement)

_get_updated_requirements_txt

_get_updated_requirements_txt(
    data: str, ignore: collections.abc.Iterable[str] = ()
) -> str

Return the contents of a requirements.txt file, updated to reflect the currently installed project versions, excluding those specified in ignore.

Parameters:

• data (str): The contents of a requirements.txt file
• ignore ([str]): One or more project names to leave as-is

Source code in src/dependence/update.py

def _get_updated_requirements_txt(
    data: str, ignore: Iterable[str] = ()
) -> str:
    """
    Return the contents of a *requirements.txt* file, updated to reflect the
    currently installed project versions, excluding those specified in
    `ignore`.

    Parameters:

    - data (str): The contents of a *requirements.txt* file
    - ignore ([str]): One or more project names to leave as-is
    """
    ignore_set: set[str] = _normalize_ignore_argument(ignore)

    def get_updated_requirement_string(requirement: str) -> str:
        return _get_updated_requirement_string(requirement, ignore=ignore_set)

    return "\n".join(map(get_updated_requirement_string, data.split("\n")))

_get_updated_setup_cfg

_get_updated_setup_cfg(
    data: str,
    ignore: collections.abc.Iterable[str] = (),
    all_extra_name: str = "",
) -> str

Return the contents of a setup.cfg file, updated to reflect the currently installed project versions, excluding those specified in ignore.

Parameters:

• data (str): The contents of a setup.cfg file
• ignore ([str]): One or more project names to leave as-is
• all_extra_name (str): An (optional) extra name which will consolidate requirements from all other extras

Source code in src/dependence/update.py

def _get_updated_setup_cfg(
    data: str, ignore: Iterable[str] = (), all_extra_name: str = ""
) -> str:
    """
    Return the contents of a *setup.cfg* file, updated to reflect the
    currently installed project versions, excluding those specified in
    `ignore`.

    Parameters:

    - data (str): The contents of a *setup.cfg* file
    - ignore ([str]): One or more project names to leave as-is
    - all_extra_name (str): An (optional) extra name which will
      consolidate requirements from all other extras
    """
    ignore_set: set[str] = _normalize_ignore_argument(ignore)

    def get_updated_requirement_string(requirement: str) -> str:
        return _get_updated_requirement_string(requirement, ignore=ignore_set)

    # Parse
    parser: ConfigParser = ConfigParser()
    parser.read_string(data)
    # Update
    if ("options" in parser) and ("install_requires" in parser["options"]):
        parser["options"]["install_requires"] = "\n".join(
            map(  # type: ignore
                get_updated_requirement_string,
                parser["options"]["install_requires"].split("\n"),
            )
        )
    if "options.extras_require" in parser:
        extras_require: SectionProxy = parser["options.extras_require"]
        all_extra_requirements: list[str] = []
        extra_name: str
        extra_requirements_string: str
        extra_requirements: list[str]
        for extra_name, extra_requirements_string in extras_require.items():
            if extra_name != all_extra_name:
                extra_requirements = list(
                    map(
                        get_updated_requirement_string,
                        extra_requirements_string.split("\n"),
                    )
                )
                if all_extra_name:
                    all_extra_requirements += extra_requirements
                extras_require[extra_name] = "\n".join(extra_requirements)
        # If a name was specified for an all-encompasing extra,
        # we de-duplicate and update or create that extra
        if all_extra_name:
            # We pre-pend an empty requirement string in order to]
            # force new-line creation at the beginning of the extra
            extras_require[all_extra_name] = "\n".join(
                iter_distinct(["", *all_extra_requirements])
            )
    # Return as a string
    setup_cfg: str
    setup_cfg_io: IO[str]
    with StringIO() as setup_cfg_io:
        parser.write(setup_cfg_io)
        setup_cfg_io.seek(0)
        setup_cfg = re.sub(r"[ ]+(\n|$)", r"\1", setup_cfg_io.read()).strip()
        return f"{setup_cfg}\n"

_get_updated_tox_ini

_get_updated_tox_ini(
    data: str, ignore: collections.abc.Iterable[str] = ()
) -> str

Return the contents of a tox.ini file, updated to reflect the currently installed project versions, excluding those specified in ignore.

Parameters:

• data (str): The contents of a tox.ini file
• ignore ([str]): One or more project names to leave as-is

Source code in src/dependence/update.py

def _get_updated_tox_ini(data: str, ignore: Iterable[str] = ()) -> str:
    """
    Return the contents of a **tox.ini** file, updated to reflect the
    currently installed project versions, excluding those specified in
    `ignore`.

    Parameters:

    - data (str): The contents of a **tox.ini** file
    - ignore ([str]): One or more project names to leave as-is
    """
    ignore_set: set[str] = _normalize_ignore_argument(ignore)

    def get_updated_requirement_string(requirement: str) -> str:
        prefix: str | None = None
        if ":" in requirement:
            prefix, requirement = requirement.split(":", maxsplit=1)
        requirement = _get_updated_requirement_string(
            requirement, ignore=ignore_set
        )
        if prefix is not None:
            requirement = f"{prefix}: {requirement.lstrip()}"
        return requirement

    # Parse
    parser: ConfigParser = ConfigParser()
    parser.read_string(data)

    def update_section_options(section_name: str, option_name: str) -> None:
        if parser.has_option(section_name, option_name):
            parser.set(
                section_name,
                option_name,
                "\n".join(
                    map(
                        get_updated_requirement_string,
                        parser.get(section_name, option_name).split("\n"),
                    )
                ),
            )

    def update_section(section_name: str) -> None:
        update_section_options(section_name, "deps")
        if section_name == "tox":
            update_section_options(section_name, "requires")

    # Update
    list(map(update_section, parser.sections()))
    # Return as a string
    tox_ini: str
    tox_ini_io: IO[str]
    with StringIO() as tox_ini_io:
        parser.write(tox_ini_io)
        tox_ini_io.seek(0)
        tox_ini = re.sub(r"[ ]+(\n|$)", r"\1", tox_ini_io.read()).strip()
        return f"{tox_ini}\n"

_get_updated_pyproject_toml

_get_updated_pyproject_toml(
    data: str,
    ignore: collections.abc.Iterable[str] = (),
    all_extra_name: str = "",
    include_pointers: tuple[str, ...] = (),
    exclude_pointers: tuple[str, ...] = (),
) -> str

Return the contents of a pyproject.toml file, updated to reflect the currently installed project versions, excluding those specified in ignore.

Parameters:

• data (str) –

  The contents of a pyproject.toml file

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

  One or more project names to leave as-is

• all_extra_name (str, default: '' ) –

  An (optional) extra name which will consolidate requirements from all other extras

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

  A tuple of JSON pointers indicating elements to include (defaults to all elements).

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

  A tuple of JSON pointers indicating elements to exclude (defaults to no exclusions).

Returns:

• str –

  The contents of the updated pyproject.toml file.

Source code in src/dependence/update.py

def _get_updated_pyproject_toml(
    data: str,
    ignore: Iterable[str] = (),
    all_extra_name: str = "",
    include_pointers: tuple[str, ...] = (),
    exclude_pointers: tuple[str, ...] = (),
) -> str:
    """
    Return the contents of a *pyproject.toml* file, updated to reflect the
    currently installed project versions, excluding those specified in
    `ignore`.

    Parameters:
        data: The contents of a *pyproject.toml* file
        ignore: One or more project names to leave as-is
        all_extra_name: An (optional) extra name which will
            consolidate requirements from all other extras
        include_pointers: A tuple of JSON pointers indicating elements to
            include (defaults to all elements).
        exclude_pointers: A tuple of JSON pointers indicating elements to
            exclude (defaults to no exclusions).

    Returns:
        The contents of the updated pyproject.toml file.
    """
    # Parse pyproject.toml
    original_pyproject: dict[str, Any] = tomli.loads(data)
    updated_pyproject: dict[str, Any] = deepcopy(original_pyproject)
    # Find and update requirements
    _update_document_requirements(
        updated_pyproject,
        ignore=ignore,
        include_pointers=include_pointers,
        exclude_pointers=exclude_pointers,
    )
    # Update consolidated optional requirements
    project_optional_dependencies: dict[str, list[str]] = (
        updated_pyproject.get("project", {}).get("optional-dependencies", {})
    )
    # Update an extra indicated to encompass all other extras
    if project_optional_dependencies and all_extra_name:
        key: str
        dependencies: list[str]
        project_optional_dependencies[all_extra_name] = list(
            iter_distinct(
                chain(
                    *(
                        dependencies
                        for key, dependencies in (
                            project_optional_dependencies.items()
                        )
                        if key != all_extra_name
                    )
                )
            )
        )
    # Only dump the data if something was updated
    if original_pyproject != updated_pyproject:
        return tomli_w.dumps(updated_pyproject)
    return data

_get_updated_toml

_get_updated_toml(
    data: str,
    ignore: collections.abc.Iterable[str] = (),
    include_pointers: tuple[str, ...] = (),
    exclude_pointers: tuple[str, ...] = (),
) -> str

Return the contents of a TOML file, updated to reflect the currently installed project versions, excluding those specified in ignore.

Note: This functions identically to get_updated_pyproject_toml, but does not consolidate optional dependencies.

Parameters:

• data (str) –

  The contents of a TOML file

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

  One or more package names to leave as-is

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

  A tuple of JSON pointers indicating elements to include (defaults to all elements).

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

  A tuple of JSON pointers indicating elements to exclude (defaults to no exclusions).

Returns:

• str –

  The contents of the updated TOML file.

Source code in src/dependence/update.py

def _get_updated_toml(
    data: str,
    ignore: Iterable[str] = (),
    include_pointers: tuple[str, ...] = (),
    exclude_pointers: tuple[str, ...] = (),
) -> str:
    """
    Return the contents of a TOML file, updated to reflect the
    currently installed project versions, excluding those specified in
    `ignore`.

    Note: This functions identically to `get_updated_pyproject_toml`, but
    does not consolidate optional dependencies.

    Parameters:
        data: The contents of a TOML file
        ignore: One or more package names to leave as-is
        include_pointers: A tuple of JSON pointers indicating elements to
            include (defaults to all elements).
        exclude_pointers: A tuple of JSON pointers indicating elements to
            exclude (defaults to no exclusions).

    Returns:
        The contents of the updated TOML file.
    """
    # Parse pyproject.toml
    original_pyproject: dict[str, Any] = tomli.loads(data)
    updated_pyproject: dict[str, Any] = deepcopy(original_pyproject)
    # Find and update requirements
    _update_document_requirements(
        updated_pyproject,
        ignore=ignore,
        include_pointers=include_pointers,
        exclude_pointers=exclude_pointers,
    )
    # Only dump the data if something was updated
    if original_pyproject != updated_pyproject:
        return tomli_w.dumps(updated_pyproject)
    return data

update

update(
    paths: collections.abc.Iterable[str],
    ignore: collections.abc.Iterable[str] = (),
    all_extra_name: str = "",
    include_pointers: tuple[str, ...] = (),
    exclude_pointers: tuple[str, ...] = (),
) -> None

Update requirement versions in the specified files.

Parameters:

• path –

  One or more local paths to a setup.cfg, setup.cfg, and/or requirements.txt files

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

  One or more project names to ignore (leave as-is)

• all_extra_name (str, default: '' ) –

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

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

  A tuple of JSON pointers indicating elements to include (defaults to all elements).

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

  A tuple of JSON pointers indicating elements to exclude (defaults to no exclusions).

Source code in src/dependence/update.py

def update(
    paths: Iterable[str],
    ignore: Iterable[str] = (),
    all_extra_name: str = "",
    include_pointers: tuple[str, ...] = (),
    exclude_pointers: tuple[str, ...] = (),
) -> None:
    """
    Update requirement versions in the specified files.

    Parameters:
        path: One or more local paths to a setup.cfg,
            setup.cfg, and/or requirements.txt files
        ignore: One or more project names to ignore (leave as-is)
        all_extra_name: If provided, an extra which consolidates
            the requirements for all other extras will be added/updated to
            setup.cfg or setup.cfg (this argument is ignored for
            requirements.txt files)
        include_pointers: A tuple of JSON pointers indicating elements to
            include (defaults to all elements).
        exclude_pointers: A tuple of JSON pointers indicating elements to
            exclude (defaults to no exclusions).
    """
    if isinstance(paths, str):
        paths = (paths,)

    def update_(path: str) -> None:
        _update(
            path,
            ignore=ignore,
            all_extra_name=all_extra_name,
            include_pointers=include_pointers,
            exclude_pointers=exclude_pointers,
        )

    deque(map(update_, paths), maxlen=0)