almet/dangerzone

Fork 0

mirror of https://github.com/freedomofpress/dangerzone.git synced 2025-05-08 22:41:50 +02:00

Alex Pyrgiotis 5ec1809809

WIP: More polishing

2025-05-07 15:33:22 +03:00

7.9 KiB

Raw Blame History

Using the Inventory Asset Management Tool

Overview
Config Spec
- General Structure
- Fields Description
Running the Script
- lock
- sync
- list
- Common Arguments

Overview

The dev_scripts/inventory.py tool is a Python script designed to manage assets from GitHub releases. It expects a configuration file (in TOML format) that contains a list of assets and some parameters. Using this config file, it can query GitHub for release information, compute checksums for assets, update a lock file (JSON format) and sync assets as described in the lock file.

If you come from a Python background, think of it like "Poetry, but for GitHub assets".

Config Spec

Before you begin working with the script, you must create a configuration file in one of the following locations of your project:

inventory.toml: This is a config file written specifically for this tool.
pyproject.toml: This is a config file written for a Python project. The inventory tool expects a [tool.inventory] section in this file.

General Structure

Each asset is defined as an entry under the [asset] section. For example:

[asset.example]
repo = "owner/repo"
version = ">=1.0.1"
platform."darwin/arm64"  = "asset-macos"
platform."linux/amd64"   = "asset-linux"
platform.all             = "asset-universal"
executable = true
destination = "./downloads/asset"
extract = false

If you are using pyproject.toml as a config file, then you need to prepend tool.inventory to the section name, e.g., [tool.inventory.asset.example].

Fields Description

The table below lists the configuration fields supported for each asset entry along with their possible values.

Field	Required	Description	Possible Values
`repo`	yes	The GitHub repository identifier in the format `"owner/repo"`.	Any valid GitHub repository string (e.g., `"octocat/Hello-World"`).
`version`	yes	A semantic versioning (semver) expression specifying the release version constraint for the asset.	Any valid semver expression, such as `">=1.0.1"`, `"==2.0.0"` (options).
`platform.<platform>`	yes	Define the asset filename for specific platforms. Assets may have different filenames per platform. A fallback `platform.all` key can be used for platform-agnostic assets.	Keys like `platform."windows/amd64"`, `platform."linux/amd64"`, `platform."darwin/arm64"`; Fallback Key: `platform.all`. The value is the filename as a string. Templates with `{version}` are allowed. Use `"!tarball"` or `"!zipball"` to get the GitHub-generated source archives.
`executable`	no	Indicates whether the downloaded asset should be marked as executable.	`true` or `false` (default).
`destination`	yes	The local path where the asset should be saved after download. If the asset is a file, the destination will be its filename. Else, it will be the directory where the contents will be extracted in	Any valid file path string (e.g., `"downloads/asset.exe"`).
`extract`	no	Instructions for file extraction from the downloaded asset.	`false` (default) for no extraction; a list of glob strings to extract matching files; or a table with keys (see below).
`extract.globs`	no	a list of glob strings to match specific files from an archive	Any valid glob such as `.exe`, `bin/*/asset` (options). Will extract all files in the archive if omitted.
`extract.flatten`	no	copy the files to the destination root	`true` or `false` (default)

Running the Script

The inventory script supports three commands:

lock
sync
list

The following sections assume you invoke the script with poetry run.

lock

The lock command updates the lock file based on the configuration defined in pyproject.toml / inventory.toml. For each asset, it reads its details, queries GitHub to find the appropriate release and asset URL, computes a checksum if the asset is available locally, uses caching for fetching and hashing, renders filenames that contain the {version} template string, and supports assets that are platform-agnostic using platform.all.

Example:

./dev_scripts/inventory.py lock
Processing 'asset1'
Processing 'asset2'
Lock file 'inventory.lock' updated.

sync

The sync command synchronizes (downloads or copies) assets as specified in the lock file for the given platform (or the current platform if none is provided). It downloads assets into a cache, verifies them against an expected hash, copies them to the destination, marks files as executable if required, and extracts files based on the provided extraction criteria.

Examples:

Sync all assets for the current platform:

./dev_scripts/inventory.py sync
Syncing 'asset1'
Syncing 'asset2'
Synced 2 assets.

Sync all assets for the provided platform:

./dev_scripts/inventory.py sync -p darwin/amd64
Syncing 'asset3'
Synced 1 assets.

Sync only specific assets:

./dev_scripts/inventory.py sync asset1
Syncing 'asset1'
Synced 1 assets.

list

The list command lists all assets defined for a specific platform, or the current one, if not specified. The list output contains the name of the asset, its version, and its download URL.