Archive

A Smarter Extension’s archive: the zip file that an administrator installs.

An archive holds a pyproject.toml (the ExtensionManifest) and the Python package that it names, at the archive’s root:

weather-1.0.0.zip
├── pyproject.toml
├── README.md            (optional)
└── weather/
    ├── __init__.py      (its module docstring is the extension's documentation)
    ├── tools.py
    ├── lifecycle.py     (optional install, upgrade and uninstall hooks)
    ├── manifests/       (optional SAM manifests, applied on install, deleted on uninstall)
    ├── static/          (optional assets: icons, images, css, js)
    └── docs/            (optional extra documentation pages, .rst or .md)

An archive whose files are all in one top-level directory, as GitHub’s source archives are, is accepted too: the directory is ignored.

ExtensionArchive validates an archive without importing any of its code: it rejects paths that would escape the extraction directory, links, and archives that are too large, and it reads the package’s docstring by parsing, not importing, __init__.py.

class smarter.apps.llmtool.extension.archive.ExtensionArchive(data)[source]

Bases: object

A validated extension archive.

Parameters:

data (bytes) – The bytes of the zip file.

Raises:

Example usage:

archive = ExtensionArchive(uploaded_file.read())
archive.manifest.slug, archive.manifest.version, archive.sha256
archive.extract_to(Path("/tmp/weather"))
__init__(data)[source]
property docstring: str[source]

its documentation, in reStructuredText.

It is read by parsing __init__.py, without importing it.

Type:

The module docstring of the extension’s package

extract_to(target)[source]

Extract the archive’s files into a directory.

Parameters:

target (Path) – The directory, which is created if necessary.

Return type:

None

property manifest: ExtensionManifest[source]

The archive’s parsed pyproject.toml.

property names: list[str]

The paths of the archive’s files, relative to its root, sorted.

package_files(directory)[source]

Return the paths, relative to <package>/<directory>/, of the files in one of the package’s directories.

Parameters:

directory (str) – e.g. static or docs.

Return type:

list[str]

read(path)[source]

Return the contents of one of the archive’s files.

Parameters:

path (str) – The file’s path, relative to the archive’s root.

Raises:

KeyError – If there is no such file.

Return type:

bytes

read_text(path)[source]

Return a text file’s contents, or None if there is no such file or it is not UTF-8.

Return type:

str | None

property sha256: str[source]

The hex sha256 of the archive’s bytes.

smarter.apps.llmtool.extension.archive.build_archive(source)[source]

Build an extension archive from an extension’s source directory.

The archive holds the pyproject.toml, the package it names, and a README, LICENSE or CHANGELOG if there is one. Caches, version control and virtual environments are left out. The same source always gives the same bytes.

Parameters:

source (Path) – The directory that holds pyproject.toml.

Return type:

bytes

Returns:

The archive’s bytes.

Raises: