check if NCBITaxa() db exists

[EDohmen]

I'm trying to package a toolkit on PyPI that should be installable with pip (and uv) and some tools in it use NCBITaxa from ete3.

What is the best way to make sure a local NCBITaxa db exists? I searched for it, but just found old (ete2) discussions about it or the hint that this is not possible at all.

Best way would be to build the db directly after installation of ete3, which is not possible with a pyproject.toml file as far as I can see. Is there a way from ete3 to trigger this behaviour during installation from PyPI (or in ete4, but ete4 is not available on PyPI yet, correct)?

Even if I call a separate script/function to check/build/update NCBITaxa db before a GUI script is run, I'm missing how the code block should look like to check if NCBITaxa() will trigger a complete new build of the db, to make sure there's a warning if the db needs to be built and this will take a while before the actual GUI tool is launched.

Any hints and ideas or workarounds would be very much appreciated.

My example code to explain what I'm looking for:

from ete3 import NCBITaxa
import warnings


class NCBITAXDBWarning(UserWarning):
    # Warning for NCBI Taxonomy Database updates/builds
    pass


def check_NCBI_taxDB():
    # Check if NCBI Taxonomy Database exists
    if not ncbi_taxDB_exists:  # TODO: how to implement this?
        warnings.warn(
            "Building NCBI Taxonomy Database. This may take a while.", NCBITAXDBWarning
        )
        update_NCBI_taxDB()
    else:
        # takes the existing db or provides functionality to update it
        ncbi = NCBITaxa()


def update_NCBI_taxDB():
    ncbi = NCBITaxa()
    ncbi.update_taxonomy_database()

[EDohmen]

For reference for others with the same issue and in case someone can say anything about the implications/caveats of my workaround:
I searched the source code of ete3 and ete4 manually and found a workaround utilising the existing ete3.ncbi_taxonomy.ncbiquery.is_taxadb_up_to_date() function, which seems to check the existence of the file or a valid sqlite3 db, respectively, without triggering a NCBITaxa db build if it's non-existent (returns a bool).

Can anyone tell me if I can use that function like this or am I likely running into troubles at some point (which might be the reason why this is "hidden" and not documented anywhere for direct usage)?
Also, ete3 and ete4 seem to handle the path and db location differently, is there anything to be aware of in the ete3 version leading to problems with virtenvs or --user installations on multi-user nodes or on different platforms?

With the below solution in a module, I can just call for different tools the check_NCBI_taxDB() before calling the cli/gui tool and provide additionally (e.g. as an executable in the pyproject.toml file referring to the update_NCBI_taxDB() function) a way to manually update the db when necessary:

from ete3 import NCBITaxa
from ete3.ncbi_taxonomy.ncbiquery import is_taxadb_up_to_date
import warnings


class NCBITAXDBWarning(UserWarning):
    """
    Warning raised when NCBI Taxonomy Database is newly built or updated
    """

    pass


def check_NCBI_taxDB() -> NCBITaxa:
    if not is_taxadb_up_to_date():
        warnings.warn(
            "No valid NCBI Taxonomy Database found. Building NCBI Taxonomy "
            "Database. This might take a while...",
            NCBITAXDBWarning,
        )

    ncbi = NCBITaxa()
    return ncbi


def update_NCBI_taxDB():
    warnings.warn("Updating NCBI Taxonomy Database...", NCBITAXDBWarning)
    ncbi = NCBITaxa()
    ncbi.update_taxonomy_database()

[EDohmen]

Unfortunately, this does not work. If the database file does not exist at all, this raises a sqlite3.OperationalError, since the db = sqlite3.connect(dbfile) happens outside of the try...except block of the is_taxadb_up_to_date function. So the except clause from the is_taxadb_up_to_date function would be needed to be be wrapped around the is_taxadb_up_to_date function again in the above code.

Is there any reason, why the sqlite3.connect is not called within the try...except block like the below example?

def is_taxadb_up_to_date(dbfile=DEFAULT_TAXADB) -> bool:  # added type hint for return type
    """Return True if a valid and up-to-date taxa.sqlite database exists.

    If `dbfile` is not specified, DEFAULT_TAXADB is assumed.
    """

    try:
        db = sqlite3.connect(dbfile)  # shouldn't this be here, so the sqlite3.OperationalError can be caught and the function returns False if no database file was found?
        version = db.execute('SELECT version FROM stats;').fetchone()[0]
    except (sqlite3.OperationalError, ValueError, IndexError, TypeError):
        version = None

    db.close()

    return version == DB_VERSION