Skip to content

xnano.ai.assets

xnano.ai.assets

xnano.ai.assets

Libraries of examples that the task models can use, which you install when you want them.

Every model works without them, from the few examples built into xnano. An installed library gives a model many more to choose from, and it shows the model the ones closest to each request: ArtModel reads 'art-references', ComponentModel reads 'component-examples' and MusicModel reads 'melodies'.

Install one from the command line, the way spaCy downloads a language model:

python -m xnano.ai.assets install art-references

or from Python with install. python -m xnano.ai.assets list shows each library and whether it is installed. A library is saved under directory, the user data directory of xnano (or the directory in XNANO_DATA_DIRECTORY when it is set), so every program on the computer finds it.

Examples:

from xnano.ai import assets

assert [asset.name for asset in assets.catalog()] == [
    'art-references',
    'component-examples',
    'melodies',
]
if not assets.is_installed('melodies'):
    print('install it with: python -m xnano.ai.assets install melodies')

Classes:

  • Asset –

    A library of examples in the catalog: what it is, and the download that installs it.

Functions:

  • catalog –

    Every library that can be installed, in the order of their names.

  • directory –

    The directory the libraries are installed in.

  • is_installed –

    Whether a library is installed, at the version this xnano reads.

  • path –

    The directory a library is installed in.

  • install –

    Download a library and install it, so the models that read it find it.

  • remove –

    Remove an installed library, every version of it.

Attributes:

  • AssetName –

    The name of a library of examples: 'art-references', 'component-examples' or 'melodies'.

AssetName module-attribute

AssetName = Literal['art-references', 'component-examples', 'melodies']

The name of a library of examples: 'art-references', 'component-examples' or 'melodies'.

Asset dataclass

Asset(name: AssetName, description: str, version: str, size_bytes: int, sha256: str)

A library of examples in the catalog: what it is, and the download that installs it.

Get them from catalog; install one by its name.

Attributes:

  • name (AssetName) –

    The name to install it by, such as 'art-references'.

  • description (str) –

    What it holds and which model reads it.

  • version (str) –

    The version of the library that this xnano reads.

  • size_bytes (int) –

    The size of the download, in bytes.

  • sha256 (str) –

    The checksum the download must have.

  • url (str) –

    Where the download is published.

url property

url: str

Where the download is published.

catalog

catalog() -> tuple[Asset, ...]

Every library that can be installed, in the order of their names.

Returns:

Source code in xnano/ai/assets/__init__.py
def catalog() -> tuple[Asset, ...]:
    """
    Every library that can be installed, in the order of their names.

    Returns:
        The [`Asset`][xnano.ai.assets.Asset] of each library.
    """
    return _CATALOG

directory

directory() -> Path

The directory the libraries are installed in.

It is XNANO_DATA_DIRECTORY when that is set, and otherwise the user data directory of xnano: ~/Library/Application Support/xnano on macOS, %LOCALAPPDATA%\\xnano on Windows, and $XDG_DATA_HOME/xnano (or ~/.local/share/xnano) elsewhere. Each library is in assets/<name>/<version> inside it. The directory is not created until something is installed.

Returns:

  • Path –

    The path of the directory.

Source code in xnano/ai/assets/__init__.py
def directory() -> pathlib.Path:
    r"""
    The directory the libraries are installed in.

    It is ``XNANO_DATA_DIRECTORY`` when that is set, and otherwise the user data directory of
    xnano: ``~/Library/Application Support/xnano`` on macOS, ``%LOCALAPPDATA%\\xnano`` on
    Windows, and ``$XDG_DATA_HOME/xnano`` (or ``~/.local/share/xnano``) elsewhere. Each library
    is in ``assets/<name>/<version>`` inside it. The directory is not created until something
    is installed.

    Returns:
        The path of the directory.
    """
    configured = os.environ.get('XNANO_DATA_DIRECTORY')
    if configured:
        return pathlib.Path(configured).expanduser()
    home = pathlib.Path.home()
    if sys.platform == 'darwin':
        return home / 'Library' / 'Application Support' / 'xnano'
    if sys.platform == 'win32':
        local = os.environ.get('LOCALAPPDATA')
        return (pathlib.Path(local) if local else home / 'AppData' / 'Local') / 'xnano'
    data_home = os.environ.get('XDG_DATA_HOME')
    return (pathlib.Path(data_home) if data_home else home / '.local' / 'share') / 'xnano'

is_installed

is_installed(name: AssetName) -> bool

Whether a library is installed, at the version this xnano reads.

Parameters:

  • name (AssetName) –

    The name of the library, such as 'melodies'.

Raises:

Source code in xnano/ai/assets/__init__.py
def is_installed(name: AssetName) -> bool:
    """
    Whether a library is installed, at the version this xnano reads.

    Args:
        name: The name of the library, such as ``'melodies'``.

    Raises:
        ValueError: No library has that name.
    """
    return (_installed_directory(_asset(name)) / _ENTRIES_FILE).is_file()

path

path(name: AssetName) -> Path

The directory a library is installed in.

Parameters:

  • name (AssetName) –

    The name of the library, such as 'melodies'.

Returns:

  • Path –

    The directory, which holds the library's entries.jsonl.

Raises:

  • ValueError –

    No library has that name.

  • TerminalError –

    The library is not installed. The message says how to install it.

Source code in xnano/ai/assets/__init__.py
def path(name: AssetName) -> pathlib.Path:
    """
    The directory a library is installed in.

    Args:
        name: The name of the library, such as ``'melodies'``.

    Returns:
        The directory, which holds the library's ``entries.jsonl``.

    Raises:
        ValueError: No library has that name.
        TerminalError: The library is not installed. The message says how to install it.
    """
    asset = _asset(name)
    installed = _installed_directory(asset)
    if not (installed / _ENTRIES_FILE).is_file():
        raise TerminalError(
            f'The library {name!r} is not installed. Install it with: python -m '
            f'xnano.ai.assets install {name}, or xnano.ai.assets.install({name!r}).',
            code='ai.asset',
        )
    return installed

install

install(name: AssetName, /, *, archive: str | PathLike[str] | None = None, should_replace: bool = False) -> Path

Download a library and install it, so the models that read it find it.

The download is checked against the checksum in the catalog before anything is installed, and an earlier install of the same version is kept unless should_replace is true. Pass archive to install from a copy of the download on this computer instead, such as one taken to a machine without a network.

Parameters:

  • name (AssetName) –

    The name of the library, such as 'art-references'.

  • archive (str | PathLike[str] | None, default: None ) –

    The path of the library's .tar.gz download, to install without the network; None downloads it.

  • should_replace (bool, default: False ) –

    Whether to install again over a library that is installed.

Returns:

  • Path –

    The directory the library is installed in.

Raises:

  • ValueError –

    No library has that name, or the archive is not this library.

  • TerminalError –

    The download failed, or its checksum is not the one in the catalog. The message says what to do.

Source code in xnano/ai/assets/__init__.py
def install(
    name: AssetName,
    /,
    *,
    archive: str | os.PathLike[str] | None = None,
    should_replace: bool = False,
) -> pathlib.Path:
    """
    Download a library and install it, so the models that read it find it.

    The download is checked against the checksum in the catalog before anything is
    installed, and an earlier install of the same version is kept unless ``should_replace``
    is true. Pass ``archive`` to install from a copy of the download on this computer
    instead, such as one taken to a machine without a network.

    Args:
        name: The name of the library, such as ``'art-references'``.
        archive: The path of the library's ``.tar.gz`` download, to install without the
            network; ``None`` downloads it.
        should_replace: Whether to install again over a library that is installed.

    Returns:
        The directory the library is installed in.

    Raises:
        ValueError: No library has that name, or the archive is not this library.
        TerminalError: The download failed, or its checksum is not the one in the catalog.
            The message says what to do.
    """
    asset = _asset(name)
    destination = _installed_directory(asset)
    if (destination / _ENTRIES_FILE).is_file() and not should_replace:
        return destination
    destination.parent.mkdir(parents=True, exist_ok=True)
    with tempfile.TemporaryDirectory(dir=destination.parent) as working:
        working_path = pathlib.Path(working)
        downloaded = working_path / 'download.tar.gz'
        if archive is None:
            _download(asset, downloaded)
        else:
            shutil.copyfile(archive, downloaded)
        _check_checksum(asset, downloaded, from_archive=archive is not None)
        unpacked = working_path / 'unpacked'
        _unpack(downloaded, unpacked)
        _check_contents(asset, unpacked)
        if destination.exists():
            shutil.rmtree(destination)
        # Moved in one step, so a program never sees half a library.
        unpacked.rename(destination)
    return destination

remove

remove(name: AssetName) -> bool

Remove an installed library, every version of it.

Parameters:

  • name (AssetName) –

    The name of the library, such as 'melodies'.

Returns:

  • bool –

    Whether there was anything to remove.

Raises:

Source code in xnano/ai/assets/__init__.py
def remove(name: AssetName) -> bool:
    """
    Remove an installed library, every version of it.

    Args:
        name: The name of the library, such as ``'melodies'``.

    Returns:
        Whether there was anything to remove.

    Raises:
        ValueError: No library has that name.
    """
    library = directory() / 'assets' / _asset(name).name
    if not library.exists():
        return False
    shutil.rmtree(library)
    return True