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:
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
¶
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.
catalog
¶
Every library that can be installed, in the order of their names.
Returns:
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
¶
Whether a library is installed, at the version this xnano reads.
Parameters:
-
name(AssetName) –The name of the library, such as
'melodies'.
Raises:
-
ValueError–No library has that name.
Source code in xnano/ai/assets/__init__.py
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.gzdownload, to install without the network;Nonedownloads 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 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:
-
ValueError–No library has that name.
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