lastversion.py

This is the main module of lastversion package. To use it, import it and invoke any function documented here. For example:

from lastversion import lastversion
lastversion.has_update(repo='mautic/mautic', current_version='1.2.3')

build_changelog_bullets(res, repo_arg)

Build changelog bullets for a release dict using upstream notes and OpenAI.

Parameters:

Name	Type	Description	Default
res	dict	Release metadata containing upstream notes.	required
repo_arg	str	Repository identifier used for the release lookup.	required

Returns:

Type	Description
Optional[List[str]]	Optional[List[str]]: Generated changelog bullets, or None when notes are unavailable or generation fails.

Source code in src/lastversion/lastversion.py

def build_changelog_bullets(res: dict, repo_arg: str) -> Optional[List[str]]:
    """Build changelog bullets for a release dict using upstream notes and OpenAI.

    Args:
        res (dict): Release metadata containing upstream notes.
        repo_arg (str): Repository identifier used for the release lookup.

    Returns:
        Optional[List[str]]: Generated changelog bullets, or None when notes
            are unavailable or generation fails.
    """
    try:
        raw_notes = res.get("body") or res.get("description")
    except AttributeError:
        raw_notes = None

    if not raw_notes:
        return None

    try:
        context = {
            "repo": res.get("from"),
            "tag": res.get("tag_name"),
            "version": str(res.get("version")),
            "source": res.get("source"),
        }
        return generate_changelog(raw_notes, context)
    except Exception:
        log.error("Failed to build changelog bullets", exc_info=True)
        return None

check_version(value)

Given a version string, raises argparse.ArgumentTypeError if it does not contain any version. In lastversion CLI app, this is used as argument parser helper for --newer-than (-gt) option.

Parameters:

Name	Type	Description	Default
value	str	Free-format string which is meant to contain a user-supplied version	required

Raises:

Type	Description
ArgumentTypeError	Exception in a case version was not found in the input string

Returns:

Name	Type	Description
Version	Version	Parsed version object

Source code in src/lastversion/lastversion.py

def check_version(value) -> Version:
    """Given a version string, raises argparse.ArgumentTypeError if it does not contain any version.
    In lastversion CLI app, this is used as argument parser helper for --newer-than (-gt) option.

    Args:
        value (str): Free-format string which is meant to contain a user-supplied version

    Raises:
        argparse.ArgumentTypeError: Exception in a case version was not found in the input string

    Returns:
        Version: Parsed version object

    """
    value = parse_version(value)
    if not value:
        raise argparse.ArgumentTypeError("%s is an invalid version value" % value)
    return value

clear_cache(repo=None)

Clear the HTTP cache for lastversion.

This function is useful for webhook handlers that need to invalidate cache when a new release is published.

Parameters:

Name	Type	Description	Default
repo	str	Optional repository identifier (e.g., "owner/repo"). If provided, attempts to clear cache for that repo only. If None, clears the entire cache.	None

Returns:

Name	Type	Description
int	int	Number of cache entries cleared (or 1 for full cache clear)

Example

In a webhook handler for GitHub release events:

from lastversion import clear_cache, latest

def handle_github_webhook(payload): repo = payload.get("repository", {}).get("full_name") clear_cache(repo) # Optionally fetch fresh version version = latest(repo, output_format='json') return version

Source code in src/lastversion/lastversion.py

def clear_cache(repo=None) -> int:
    """Clear the HTTP cache for lastversion.

    This function is useful for webhook handlers that need to invalidate
    cache when a new release is published.

    Args:
        repo (str): Optional repository identifier (e.g., "owner/repo").
                    If provided, attempts to clear cache for that repo only.
                    If None, clears the entire cache.

    Returns:
        int: Number of cache entries cleared (or 1 for full cache clear)

    Example:
        # In a webhook handler for GitHub release events:
        from lastversion import clear_cache, latest

        def handle_github_webhook(payload):
            repo = payload.get("repository", {}).get("full_name")
            clear_cache(repo)
            # Optionally fetch fresh version
            version = latest(repo, output_format='json')
            return version
    """
    from lastversion.repo_holders.base import BaseProjectHolder

    return BaseProjectHolder.clear_cache(repo)

expand_spec_macros(value, macros)

Expand %{macro} / %macro references using macros defined in the spec.

Unknown macros are left as-is. Nested definitions are resolved with a bounded number of passes so self-referencing macros cannot loop forever.

Source code in src/lastversion/lastversion.py

def expand_spec_macros(value, macros):
    """Expand %{macro} / %macro references using macros defined in the spec.

    Unknown macros are left as-is. Nested definitions are resolved with a
    bounded number of passes so self-referencing macros cannot loop forever.
    """
    for _ in range(10):
        expanded = _SPEC_MACRO_REF_RE.sub(lambda m: macros.get(m.group(1) or m.group(2), m.group(0)), value)
        if expanded == value:
            break
        value = expanded
    return value

find_preferred_url(spec_urls)

Given a list of URLs of a project, return preferred one that might lead to version info. Basically returns the first URL that matches a handler by matching its primary domain.

Source code in src/lastversion/lastversion.py

def find_preferred_url(spec_urls):
    """
    Given a list of URLs of a project, return preferred one that might lead to version info.
    Basically returns the first URL that matches a handler by matching its primary domain.
    """
    # TODO: use rpmspec --parse if failed to get lastversion_repo inside spec (includes macro)
    for url in spec_urls:
        # parse URL and get domain
        parsed = urlparse(url)
        hostname = parsed.hostname
        # enumerate holders, and see if any of them can handle this domain
        for holder in HolderFactory.HOLDERS.values():
            if holder.DEFAULT_HOSTNAME and holder.DEFAULT_HOSTNAME == hostname:
                return url
    return spec_urls[0] if spec_urls else None

get_repo_data_from_spec(rpmspec_filename)

Extract repo data and CLI args from a spec file.

The project (repo) is specified inside the .spec file GitHub repo is resolved via %{upstream_github} + %{name}/%{upstream_name} No upstream_github global means that the spec was not prepared for lastversion Optional: use of spec_tag macros if the source is from GitHub. In edge cases we check new version via GitHub, but prepared sources are elsewhere

Parameters:

Name	Type	Description	Default
rpmspec_filename	str	Path to the RPM spec file.	required

Returns:

Name	Type	Description
dict	dict	Repository metadata and CLI options parsed from the spec file.

Source code in src/lastversion/lastversion.py

def get_repo_data_from_spec(rpmspec_filename: str) -> dict:
    """Extract repo data and CLI args from a spec file.

    The project (repo) is specified inside the .spec file
    GitHub repo is resolved via %{upstream_github} + %{name}/%{upstream_name}
    No upstream_github global means that the spec was not prepared for lastversion
    Optional: use of spec_tag macros if the source is from GitHub. In edge cases we check
    new version via GitHub, but prepared sources are elsewhere

    Args:
        rpmspec_filename (str): Path to the RPM spec file.

    Returns:
        dict: Repository metadata and CLI options parsed from the spec file.
    """
    repo_data = {}
    with open(rpmspec_filename) as f:
        name = None
        upstream_github = None
        upstream_name = None
        current_version = None
        spec_repo = None
        spec_urls = []
        current_commit = None
        macros = {}
        for line in f.readlines():
            macro_def = _SPEC_MACRO_DEF_RE.match(line)
            if macro_def:
                macros[macro_def.group(1)] = macro_def.group(2)
            if line.startswith("%global lastversion_repo"):
                spec_repo = shlex.split(line)[2].strip()
            elif line.startswith("%global upstream_github"):
                upstream_github = shlex.split(line)[2].strip()
            elif line.startswith("%global upstream_name"):
                upstream_name = shlex.split(line)[2].strip()
            elif line.startswith("%global commit "):
                # Commit-based release (snapshots)
                current_commit = shlex.split(line)[2].strip()
                repo_data["commit_based"] = True
            elif line.startswith("Name:"):
                name = line.split("Name:")[1].strip()
                macros["name"] = name
            elif line.startswith("URL:"):
                # append to spec_urls
                spec_urls.append(line.split("URL:")[1].strip())
            elif line.startswith("Source0:"):
                source0 = line.split("Source0:")[1].strip()
                # noinspection HttpUrlsUsage
                if source0.startswith("https://") or source0.startswith("http://"):  # NOSONAR
                    spec_urls.append(source0)
            elif line.startswith("%global upstream_version "):
                current_version = shlex.split(line)[2].strip()
                # influences %spec_tag to use %upstream_version instead of %version
                repo_data["module_of"] = True
            elif line.startswith("Version:") and not current_version:
                current_version = line.split("Version:")[1].strip()
                macros.setdefault("version", current_version)
            elif line.startswith("%global lastversion_only"):
                repo_data["only"] = shlex.split(line)[2].strip()
            elif line.startswith("%global lastversion_having_asset"):
                repo_data["having_asset"] = shlex.split(line)[2].strip()
            elif line.startswith("%global lastversion_major"):
                repo_data["major"] = shlex.split(line)[2].strip()
            elif line.startswith("%global lastversion_formal"):
                value = shlex.split(line)[2].strip()
                low = value.lower()
                if low in ["1", "true", "yes", "on"]:
                    repo_data["formal"] = True
                elif low in ["0", "false", "no", "off"]:
                    repo_data["formal"] = False
                else:
                    # Any non-empty string defaults to True for safety
                    repo_data["formal"] = bool(value)
            elif line.startswith("%global lastversion_sem"):
                # Semver constraint: major, minor, or patch
                value = shlex.split(line)[2].strip().lower()
                if value in ["major", "minor", "patch"]:
                    repo_data["sem"] = value

        # Store current commit for comparison
        if current_commit:
            repo_data["current_commit"] = current_commit

        if not current_version:
            log.critical("Did not find neither Version: nor %upstream_version in the spec file")
            sys.exit(1)
        try:
            if current_version != "x":
                repo_data["current_version"] = Version(current_version)
        except InvalidVersion:
            log.critical(
                "Failed to parse current version in %s. Tried %s",
                rpmspec_filename,
                current_version,
            )
            sys.exit(1)
        if upstream_name:
            repo_data["name"] = upstream_name
            repo_data["spec_name"] = "%{upstream_name}"
        else:
            repo_data["name"] = name
            repo_data["spec_name"] = "%{name}"

        if upstream_github:
            repo = f"{upstream_github}/{repo_data['name']}"
            log.info("Discovered GitHub repo %s from .spec file", repo)
        elif spec_repo:
            repo = spec_repo
            log.info("Discovered explicit repo %s from .spec file", repo)
        else:
            # Expand spec-defined macros (e.g. URL: https://github.com/%{gitowner}/%{name}),
            # and prefer URLs that fully resolved over ones still holding unknown macros
            spec_urls = [expand_spec_macros(url, macros) for url in spec_urls]
            resolved_urls = [url for url in spec_urls if not re.search(r"%\{|%[A-Za-z_]", url)]
            repo = find_preferred_url(resolved_urls or spec_urls)

        if not repo:
            log.critical(
                "Failed to determine repo from %s. Please prepare your spec file using instructions: "
                "https://lastversion.getpagespeed.com/spec-preparing.html",
                rpmspec_filename,
            )
            sys.exit(1)

        repo_data["repo"] = repo
        return repo_data

get_repo_data_from_yml(repo)

Get repo data from YAML file.

Source code in src/lastversion/lastversion.py

def get_repo_data_from_yml(repo):
    """Get repo data from YAML file."""
    with open(repo) as fpi:
        repo_data = yaml.safe_load(fpi)
        if "repo" in repo_data:
            if "nginx-extras" in repo:
                repo_data["module_of"] = "nginx"
            name = os.path.splitext(os.path.basename(repo))[0]
            if "module_of" in repo_data:
                name = f'{repo_data["module_of"]}-module-{name}'
            repo_data["name"] = name
    return repo_data

get_rpm_packager()

Get RPM packager name from ~/.rpmmacros

Source code in src/lastversion/lastversion.py

def get_rpm_packager():
    """Get RPM packager name from ~/.rpmmacros"""
    try:
        rpmmacros = expanduser("~") + "/.rpmmacros"
        with open(rpmmacros) as f:
            for ln in f.readlines():
                if ln.startswith("%packager"):
                    return ln.split("%packager")[1].strip()
    except IOError:
        log.warning("~/.rpmmacros does not exist. Changelog will not be generated")
    return None

has_update(repo, current_version, pre_ok=False, at=None)

Given an existing version for a repo, checks if there is an update.

Parameters:

Name	Type	Description	Default
repo	str	Repository specifier in any form.	required
current_version	str	A version you want to check update for.	required
pre_ok	bool	Specifies whether pre-releases can be accepted as a newer version.	False
at	str	Specifies repo hosting more precisely, only useful if repo argument was specified as one word.	None

Returns:

Name	Type	Description
Version	Union[Version, bool]	Newer version as an object, if found. Otherwise, False

Source code in src/lastversion/lastversion.py

def has_update(repo, current_version, pre_ok=False, at=None) -> Union[Version, bool]:
    """Given an existing version for a repo, checks if there is an update.

    Args:
        repo (str): Repository specifier in any form.
        current_version (str): A version you want to check update for.
        pre_ok (bool): Specifies whether pre-releases can be accepted as a newer version.
        at (str): Specifies repo hosting more precisely, only useful if repo argument was
                  specified as one word.

    Returns:
        Version: Newer version as an object, if found. Otherwise, False

    """
    latest_version = latest(repo, output_format="version", pre_ok=pre_ok, at=at)
    if latest_version and latest_version > Version(current_version):
        return latest_version
    return False

install_app_image(url, install_name)

Install an AppImage from a URL to ~/Applications/<install_name>

Parameters:

Name	Type	Description	Default
url	str	URL where AppImage file is hosted	required
install_name	str	Short name that the AppImage will be renamed to	required

Source code in src/lastversion/lastversion.py

def install_app_image(url, install_name):
    """Install an AppImage from a URL to `~/Applications/<install_name>`

    Args:
        url (str): URL where AppImage file is hosted
        install_name (str): Short name that the AppImage will be renamed to
    """
    if not install_name.endswith(".AppImage"):
        install_name += ".AppImage"
    app_file_name = install_standalone_binary(url, install_name)
    extract_appimage_desktop_file(app_file_name)

install_debs(_res, debs, args)

Install deb packages using apt.

Parameters:

Name	Type	Description	Default
_res	dict	Release metadata, unused but kept for API consistency with install_rpms.	required
debs	List[str]	Debian package URLs to download and install.	required
args	Namespace	Parsed CLI arguments.	required

Source code in src/lastversion/lastversion.py

def install_debs(_res: dict, debs: List[str], args: argparse.Namespace) -> None:
    """Install deb packages using apt.

    Args:
        _res (dict): Release metadata, unused but kept for API consistency with install_rpms.
        debs (List[str]): Debian package URLs to download and install.
        args (argparse.Namespace): Parsed CLI arguments.
    """
    try:
        import subprocess

        # Download debs first, then install with apt
        local_debs = []
        for deb_url in debs:
            local_file = download_file(deb_url)
            local_debs.append(local_file)

        params = ["apt", "install"]
        params.extend(local_debs)
        if args.assumeyes:
            params.append("-y")
        subprocess.call(params)
    except OSError:
        log.critical("Failed to launch apt for package install!")
        sys.exit(1)

install_release(res, args)

Install latest release.

Prefers native package formats (RPM/deb) over AppImages for better integration with package managers and architecture compatibility.

Source code in src/lastversion/lastversion.py

def install_release(res, args):
    """Install latest release.

    Prefers native package formats (RPM/deb) over AppImages for better
    integration with package managers and architecture compatibility.
    """
    # Prefer RPMs on RPM-based distros
    rpms = [asset for asset in res["assets"] if asset.endswith(".rpm")]
    if rpms:
        return install_rpms(res, rpms, args)

    # Prefer debs on Debian-based distros
    debs = [asset for asset in res["assets"] if asset.endswith(".deb")]
    if debs:
        return install_debs(res, debs, args)

    # Fall back to AppImages (cross-distro)
    app_images = [asset for asset in res["assets"] if asset.endswith(".AppImage")]
    if app_images:
        return install_app_image(app_images[0], install_name=res.get("install_name", args.repo))

    # static files are those without an extension
    static_binaries = [asset for asset in res["assets"] if "." not in asset.rsplit("/", 1)[-1]]
    if static_binaries:
        return install_standalone_binary(static_binaries[0], install_name=res.get("install_name", args.repo))

    log.error("No installable assets found to install")
    sys.exit(1)

install_rpms(res, rpms, args)

Install RPMs using package manager

Source code in src/lastversion/lastversion.py

def install_rpms(res, rpms, args):
    """Install RPMs using package manager"""
    # prevents downloading large packages if we already have newest installed
    # consult RPM database  for current version
    installed_version = rpm_installed_version(args.repo)
    if installed_version is False:
        log.warning(
            "Please install lastversion using YUM or DNF so it can check current "
            "program version. This is helpful to prevent unnecessary downloads"
        )
    if installed_version and Version(installed_version) >= Version(res["version"]):
        log.warning("Newest version %s is already installed", installed_version)
        sys.exit(0)
    # pass RPM URLs directly to package management program
    try:
        import subprocess

        params = ["yum", "install"]
        params.extend(rpms)
        if args.assumeyes:
            params.append("-y")
        subprocess.call(params)
    except OSError:
        log.critical("Failed to launch package manager. Only YUM/DNF is supported!")
        sys.exit(1)

install_standalone_binary(url, install_name)

Install a standalone binary from a URL to ~/Applications/<install_name>

Parameters:

Name	Type	Description	Default
url	str	URL where the binary file is hosted	required
install_name	str	Filename that the binary will be renamed to	required

Source code in src/lastversion/lastversion.py

def install_standalone_binary(url, install_name):
    """Install a standalone binary from a URL to `~/Applications/<install_name>`

    Args:
        url (str): URL where the binary file is hosted
        install_name (str): Filename that the binary will be renamed to
    """
    home_dir = os.path.expanduser("~")
    apps_dir = os.path.join(home_dir, "Applications")
    app_file_name = os.path.join(apps_dir, install_name)

    Path(apps_dir).mkdir(exist_ok=True, parents=True)
    download_file(url, app_file_name)
    os.chmod(app_file_name, 0o755)  # skipcq: BAN-B103
    return app_file_name

latest(repo, output_format='version', pre_ok=False, assets_filter=None, short_urls=False, major=None, only=None, at=None, having_asset=None, exclude=None, even=False, formal=False, changelog=False, cache_ttl=None, skip_release_cache=False)

Find the latest release version for a project.

Parameters:

Name	Type	Description	Default
major	str	Only consider versions which are "descendants" of this major version string	None
short_urls	bool	Whether we should try to return shorter URLs for release data	False
assets_filter	Union[str, Pattern]	Regular expression for filtering assets for the latest release	None
only	str	Only consider tags with this text. Useful for repos with multiple projects. The argument supports negation and regular expressions. To indicate a regex, start it with tilde sign, to negate the expression, start it with exclamation point. See Examples.	None
repo	str	Repository specifier in any form.	required
output_format	str	Affects the return format. Possible values version, json, dict, assets, source, tag.	'version'
pre_ok	bool	Specifies whether pre-releases can be accepted as a newer version.	False
at	str	Specifies repo hosting more precisely, only useful if repo argument was specified as one word.	None
having_asset	Union[str, bool]	Only consider releases with the given asset. Pass True for any asset	None
exclude	str	Only consider releases NOT containing this text/regular expression.	None
even	bool	Consider as stable only releases with even minor component, e.g. 1.2.3	False
formal	bool	Consider as stable only releases with formal tags set up in Web UI	False
changelog	bool	Populate release["changelog"] using upstream notes (if True)	False
cache_ttl	int	Optional TTL override for release data cache (seconds). Only used when release cache is enabled in config.	None
skip_release_cache	bool	Skip the release data cache entirely (both read and write). Useful when you need fresh data from the source.	False

Examples:

Find the latest version of Mautic, it is OK to consider betas.

>>> latest("mautic/mautic", output_format='version', pre_ok=True)
<Version('4.4.4')>

Consider only tags without letters:

>>> latest("openssl/openssl", output_format='version', only=r'!~\w')
<Version('3.0.7')>

Returns:

Type	Description
Any	Union[Version, dict, str, None]: Release data in the requested format, or None when no matching release is found.

Source code in src/lastversion/lastversion.py

def latest(
    repo,
    output_format="version",
    pre_ok=False,
    assets_filter=None,
    short_urls=False,
    major=None,
    only=None,
    at=None,
    having_asset=None,
    exclude=None,
    even=False,
    formal=False,
    changelog=False,
    cache_ttl=None,
    skip_release_cache=False,
) -> Any:
    r"""Find the latest release version for a project.

    Args:
        major (str): Only consider versions which are "descendants" of this
            major version string
        short_urls (bool): Whether we should try to return shorter URLs for
            release data
        assets_filter (Union[str, Pattern]): Regular expression for filtering
            assets for the latest release
        only (str): Only consider tags with this text. Useful for repos with multiple projects.
                    The argument supports negation and regular expressions. To indicate a regex,
                    start it with tilde sign, to negate the expression, start it with exclamation
                    point. See `Examples`.
        repo (str): Repository specifier in any form.
        output_format (str): Affects the return format. Possible values `version`, `json`, `dict`,
                             `assets`, `source`, `tag`.
        pre_ok (bool): Specifies whether pre-releases can be accepted as a newer version.
        at (str): Specifies repo hosting more precisely, only useful if repo argument was
                  specified as one word.
        having_asset (Union[str, bool]): Only consider releases with the given asset.
                                         Pass `True` for any asset
        exclude (str): Only consider releases NOT containing this text/regular expression.
        even (bool): Consider as stable only releases with even minor component, e.g. 1.2.3
        formal (bool): Consider as stable only releases with formal tags set up in Web UI
        changelog (bool): Populate release["changelog"] using upstream notes (if True)
        cache_ttl (int): Optional TTL override for release data cache (seconds).
                         Only used when release cache is enabled in config.
        skip_release_cache (bool): Skip the release data cache entirely (both read and write).
                                   Useful when you need fresh data from the source.

    Examples:
        Find the latest version of Mautic, it is OK to consider betas.

        >>> latest("mautic/mautic", output_format='version', pre_ok=True)
        <Version('4.4.4')>

        Consider only tags without letters:

        >>> latest("openssl/openssl", output_format='version', only=r'!~\w')
        <Version('3.0.7')>

    Returns:
        Union[Version, dict, str, None]: Release data in the requested format,
            or None when no matching release is found.

    """
    repo_data = {}

    # Parse local project metadata BEFORE consulting the release cache. Some of
    # it (notably `current_version`, read off the spec's Version: tag) is state
    # of the file on disk right now, not of the upstream release, so it must
    # never be served from a cache entry written when the spec said something
    # else -- and it must be re-applied over any cache hit, exactly as the
    # fetch path does with `release.update(repo_data)` further down.
    # noinspection HttpUrlsUsage
    if repo.endswith(".yml") and not repo.startswith(("http://", "https://")):
        repo_data = get_repo_data_from_yml(repo)

    # noinspection HttpUrlsUsage
    if repo.startswith(("http://", "https://")) and repo.endswith("Chart.yaml"):
        at = "helm_chart"

    if repo.endswith(".spec"):
        repo_data = get_repo_data_from_spec(rpmspec_filename=repo)

    # Check release data cache first (when enabled and using json/dict output)
    release_cache = get_release_cache()
    cache_key_params = {
        "pre_ok": pre_ok,
        "major": major,
        "only": only,
        "at": at,
        "having_asset": having_asset,
        "exclude": exclude,
        "even": even,
        "formal": formal,
    }

    def _return_from_cache(cached_data, fmt, is_stale=False):
        """Helper to return cached data in the appropriate format."""
        if cached_data is None:
            return None
        prefix = "stale " if is_stale else ""
        log.info("Using %scached release data for: %s", prefix, repo)
        if is_stale:
            log.warning("Network/API error occurred. Returning stale cached data for: %s", repo)
        if fmt == "version":
            try:
                return Version(cached_data.get("version", ""))
            except InvalidVersion:
                return None
        elif fmt == "tag":
            return cached_data.get("tag_name")
        elif fmt == "dict":
            # Convert version string back to Version object for dict output
            try:
                cached_data["version"] = Version(cached_data.get("version", ""))
            except InvalidVersion:
                pass
            # Re-apply freshly parsed local metadata over the cached release,
            # mirroring `release.update(repo_data)` on the fetch path. Without
            # this, `current_version` stays whatever JSON round-tripped out of
            # the cache -- a plain str, which then blows up comparing against
            # a Version in update_spec().
            cached_data.update(repo_data)
            return cached_data
        else:  # json
            return cached_data

    # Try to get from cache for formats that can use cached data
    if release_cache.enabled and not skip_release_cache and output_format in ["json", "dict", "version", "tag"]:
        cached_release = release_cache.get(repo, **cache_key_params)
        if cached_release:
            result = _return_from_cache(cached_release, output_format, is_stale=False)
            if result is not None:
                return result
            # Fall through to fetch fresh data if cache parsing failed

    # Define network error types that should trigger cache fallback
    network_errors = (
        requests.exceptions.RequestException,  # All requests errors (connection, timeout, etc.)
        ApiCredentialsError,  # Rate limits, auth failures
        ConnectionError,
        TimeoutError,
        OSError,  # Network unreachable, etc.
    )

    try:
        with HolderFactory.get_instance_for_repo(repo_data.get("repo", repo), at=at) as project:
            project.set_only(repo_data.get("only", only))
            project.set_exclude(exclude)
            project.set_having_asset(repo_data.get("having_asset", having_asset))
            project.set_even(even)
            project.set_formal(repo_data.get("formal", formal))
            release = project.get_latest(pre_ok=pre_ok, major=repo_data.get("major", major))

            # bail out, found nothing that looks like a release
            if not release:
                return None

            from_type = f"Located the latest release tag {release['tag_name']} at: {project.get_canonical_link()}"
            if "type" in release:
                from_type = f"{from_type} via {release['type']} mechanism"
            log.info(from_type)

            version = release["version"]
            tag = release["tag_name"]

            # return the release if we've reached far enough:
            if output_format == "version":
                return version

            if output_format in ["json", "dict"]:
                if output_format == "dict":
                    release["version"] = version
                else:
                    release["version"] = str(version)
                # Convert tag_date for both json and dict to ensure cache serialization works
                if "tag_date" in release:
                    release["tag_date"] = str(release["tag_date"])
                release["v_prefix"] = tag.startswith("v")
                version_macro = "upstream_version" if "module_of" in repo_data else "version"
                version_macro = f"%{{{version_macro}}}"
                holder_i = {value: key for key, value in HolderFactory.HOLDERS.items()}
                release["source"] = holder_i[type(project)]
                release["spec_tag"] = tag.replace(str(version), version_macro)
                # spec_tag_no_prefix is the helpful macro that will allow us to know where tarball
                # extracts to (GitHub-specific)
                if release["spec_tag"].startswith(f"v{version_macro}") or re.match(r"^v\d", release["spec_tag"]):
                    release["spec_tag_no_prefix"] = release["spec_tag"].lstrip("v")
                else:
                    release["spec_tag_no_prefix"] = release["spec_tag"]
                release["tag_name"] = tag
                if hasattr(project, "repo_license"):
                    release["license"] = project.repo_license(tag)
                if hasattr(project, "repo_readme"):
                    release["readme"] = project.repo_readme(tag)
                if changelog:
                    text, source = project.collect_release_notes(tag, release)
                    if text:
                        context = {
                            "repo": project.get_canonical_link(),
                            "tag": tag,
                            "version": str(release["version"]),
                            "source": release.get("source"),
                        }
                        try:
                            bullets = generate_changelog(text, context)
                            if bullets:
                                release["changelog"] = bullets
                                release["changelog_source"] = source
                        except Exception:
                            log.error("Failed to generate changelog for %s", tag, exc_info=True)
                release.update(repo_data)
                try:
                    # Get detailed asset info with digests BEFORE get_assets transforms them
                    release["assets_with_digests"] = project.get_assets_with_digests(release, short_urls, assets_filter)
                    # Get asset URLs (this transforms the assets list)
                    release["assets"] = project.get_assets(release, short_urls, assets_filter)
                except NotImplementedError:
                    pass
                release["from"] = project.get_canonical_link()

                if "license" in release and release["license"]:
                    spdx_id = release["license"].get("license", {}).get("spdx_id")
                    rpmspec_licence = rpmspec_licenses[spdx_id] if spdx_id in rpmspec_licenses else None
                    if rpmspec_licence:
                        release["rpmspec_license"] = rpmspec_licence

                release["source_url"] = project.release_download_url(release, short_urls)

                # Store in release cache if enabled (skip if explicitly bypassing cache)
                if release_cache.enabled and not skip_release_cache:
                    release_cache.set(repo, release, ttl=cache_ttl, **cache_key_params)

                return release

            if output_format == "assets":
                return project.get_assets(release, short_urls, assets_filter)

            if output_format == "source":
                return project.release_download_url(release, short_urls)

            if output_format == "tag":
                return tag

    except network_errors as e:
        # Network or API error - try to fall back to stale cached data
        log.warning("Network/API error while fetching release data: %s", e)

        # Try to get stale cache (bypass TTL check)
        if output_format in ["json", "dict", "version", "tag"]:
            # Get any cached data, even if expired (for fallback)
            stale_cache = release_cache.get(repo, ignore_expiry=True, **cache_key_params)
            if stale_cache:
                result = _return_from_cache(stale_cache, output_format, is_stale=True)
                if result is not None:
                    return result

        # No cached data available, re-raise the exception
        raise

    return None

parse_version(tag)

Parse version to a Version object. Argument may not be a version but a URL or a repo name, in which case return False E.g., used in lastversion repo-name -gt 1.2.3 (and repo-name is passed here as tag)

Source code in src/lastversion/lastversion.py

def parse_version(tag):
    """
    Parse version to a Version object.
    Argument may not be a version but a URL or a repo name, in which case return False
    E.g., used in lastversion repo-name -gt 1.2.3 (and repo-name is passed here as tag)
    """
    # If a URL is passed
    if tag.startswith(("http://", "https://")):
        return False
    # If a repo name is passed, e.g. "mautic/mautic"
    if "/" in tag and " " not in tag:
        return False
    h = TestProjectHolder()
    v = h.sanitize_version(tag, pre_ok=True)
    return v

update_spec_commit(spec_file, commit_info, repo_data)

Update spec file for commit-based (snapshot) releases.

Parameters:

Name	Type	Description	Default
spec_file	str	Path to the spec file.	required
commit_info	dict	Commit metadata with sha, short_sha, date, and message fields.	required
repo_data	dict	Repository metadata parsed from the spec file.	required

Updates

• %global commit
• %global commit_date
• Release: 0.%{snapinfo}%{?dist} (if no releases) or 1.%{snapinfo}%{?dist}

Source code in src/lastversion/lastversion.py

def update_spec_commit(spec_file: str, commit_info: dict, repo_data: dict) -> None:
    """Update spec file for commit-based (snapshot) releases.

    Args:
        spec_file (str): Path to the spec file.
        commit_info (dict): Commit metadata with sha, short_sha, date, and message fields.
        repo_data (dict): Repository metadata parsed from the spec file.

    Updates:
        - %global commit <sha>
        - %global commit_date <YYYYMMDD>
        - Release: 0.%{snapinfo}%{?dist} (if no releases) or 1.%{snapinfo}%{?dist}
    """
    current_commit = repo_data.get("current_commit")
    if current_commit == commit_info["sha"]:
        log.info("Commit %s is already current in spec file", commit_info["short_sha"])
        sys.exit(2)

    log.info("Updating to commit %s", commit_info["short_sha"])

    # Format commit date as YYYYMMDD
    commit_date = commit_info["date"].strftime("%Y%m%d")

    out = []
    commit_present = False
    commit_date_present = False
    snapinfo_present = False

    with open(spec_file) as f:
        for ln in f.readlines():
            if ln.startswith("%global commit "):
                out.append(f'%global commit {commit_info["sha"]}')
                commit_present = True
            elif ln.startswith("%global commit_date "):
                out.append(f"%global commit_date {commit_date}")
                commit_date_present = True
            elif ln.startswith("%global snapinfo "):
                # Keep existing snapinfo definition
                out.append(ln.rstrip())
                snapinfo_present = True
            elif ln.startswith("Release:"):
                release_tag_regex = r"^Release:(\s+)(\S+)"
                m = re.match(release_tag_regex, ln)
                if m:
                    # Check if there's a formal release version
                    current_version = repo_data.get("current_version")
                    if current_version and str(current_version) != "0":
                        # Post-release snapshot: 1.snapinfo
                        out.append(f"Release:{m.group(1)}1.%{{snapinfo}}%{{?dist}}")
                    else:
                        # Pre-release snapshot: 0.snapinfo
                        out.append(f"Release:{m.group(1)}0.%{{snapinfo}}%{{?dist}}")
                else:
                    out.append(ln.rstrip())
            else:
                out.append(ln.rstrip())

    # Add missing globals at the top
    if not commit_present:
        out.insert(0, f'%global commit {commit_info["sha"]}')

    if not commit_date_present:
        # Insert after %global commit
        for i, line in enumerate(out):
            if line.startswith("%global commit "):
                out.insert(i + 1, f"%global commit_date {commit_date}")
                break

    if not snapinfo_present:
        # Add default snapinfo definition after commit_date
        for i, line in enumerate(out):
            if line.startswith("%global commit_date "):
                out.insert(i + 1, "%global snapinfo %{commit_date}git%{shortcommit}")
                break

    # Add shortcommit if not present
    has_shortcommit = any(line.startswith("%global shortcommit ") for line in out)
    if not has_shortcommit:
        for i, line in enumerate(out):
            if line.startswith("%global commit "):
                out.insert(i + 1, "%global shortcommit %(c=%{commit}; echo ${c:0:7})")
                break

    with open(spec_file, "w") as f:
        f.write("\n".join(out))

    log.info(
        "Updated %s to commit %s (%s)",
        spec_file,
        commit_info["short_sha"],
        commit_info["message"][:50],
    )

RPM changelog generation

When updating a .spec file, you can ask lastversion to generate a concise RPM %changelog entry from upstream release notes:

lastversion path/to/package.spec --changelog

Environment variables:

• OPENAI_API_KEY or LASTVERSION_OPENAI_API_KEY
• LASTVERSION_OPENAI_MODEL (default: gpt-4o-mini)

Behavior:

• Tries conventional changelog files at the tag (e.g., CHANGELOG.md, NEWS) via raw Git first, then falls back to API.
• Produces 1–7 short bullets focusing on user-facing changes, fixes, security, and compatibility.
• Falls back to a single line - upstream release v<version> if upstream notes are unavailable or the API call fails.