| Name | mazette JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | GitHub asset management with lock files and extensive configuration |
| upload_time | 2025-08-07 10:12:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
assets
github
packaging
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Mazette
The `mazette` 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 install assets as described in the lock file.
If you come from a Python background, think of it like "Poetry, but for GitHub
assets".
## Table of Contents
- [Installation](#installation)
- [Configuration](#configuration)
- [Examples](#examples)
- [`repo`](#repo)
- [`version`](#version)
- [`platform.<platform>`](#platformplatform)
- [`executable`](#executable)
- [`destination`](#destination)
- [`extract`](#extract)
- [`extract.globs`](#extractglobs)
- [`extract.flatten`](#extractflatten)
- [Commands](#commands)
- [`lock`](#lock)
- [`install`](#install)
- [`list`](#list)
- [Common Arguments](#common-arguments)
- [License](#license)
---
## Installation
```
python -m pip install mazette
```
Alternatively, you can run it directly with
[`uvx`](https://docs.astral.sh/uv/guides/tools/#running-tools):
```
uvx mazette --help
```
## Configuration
Before you begin working with the script, you must create a configuration file
in one of the following locations of your project:
* `mazette.toml`: This is a config file written specifically for this tool.
* `pyproject.toml`: This is a config file written for a Python project. The
mazette tool expects a `[tool.mazette]` section in this file.
### Examples
Each asset is defined as an entry under the `[asset]` section. For example:
```toml
[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.mazette` to the section name, e.g., `[tool.mazette.asset.example]`.
### `repo`
**Type:** `string`
The GitHub repository identifier in the format `"owner/repo"`.
### `version`
**Type:** `string`
A semantic versioning (semver) expression specifying the release version
constraint for the asset, such as `">=1.0.1"`, `"==2.0.0"`
([options](https://python-semver.readthedocs.io/en/latest/usage/compare-versions-through-expression.html)).
### `platform.<platform>`
**Type:** `string`
The filename of an asset for a specific platform, since assets may have
different filenames per platform.
Allowed argument names:
* Strings like `platform."windows/amd64"`, `platform."linux/amd64"`,
`platform."darwin/arm64"`.
* `platform.all`, for platform-agnostic assets, i.e., assets that should be
installed regardless of the platform type.
Allowed values:
* Strings like `asset-linux-amd64`, `foo-0.1.0.zip`
* Template strings like `foo-{version}.zip`, where `{version}` will be replaced
during install time with the version of the asset (minus the leading `v`)
* Special strings `"!tarball"` or `"!zipball"`, to get the GitHub-generated
source archives for a release.
### `executable`
**Type:** `boolean`
**Default:** `false`
Indicates whether the downloaded asset should be marked as executable.
### `destination`
**Type:** `string`
The local path where the asset should be installed. 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.
### `extract`
**Type:** `boolean | list of strings | dict`
**Default:** `false`
Extraction options for zip/tar files. By default no extraction will take place.
If set to `true`, then the contents of the archive will be extracted to the
destination. If a list of globs is provided, only the matching filenames in the
archive will be extracted.
See [`extract.globs`](#extractglobs) and [`extract.flatten`](#extractflatten)
for more info.
### `extract.globs`
**Type:** `list of strings`
**Default:** `["*"]`
A list of glob strings to match specific files from an archive. Accepted values
are any valid glob such as `*.exe`, `bin/**/asset`
([options](https://docs.python.org/3/library/fnmatch.html)). Will extract all
files in the archive if omitted.
### `extract.flatten`
**Type:** `boolean`
**Default:** `false`
Indicates whether the contents of the archive should be copied to the
destination root. By default the file hierarchy in the archive is preserved.
## Commands
The mazette script supports three commands:
- `lock`
- `install`
- `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` / `mazette.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:
```
./mazette.py lock
Processing 'asset1'
Processing 'asset2'
Lock file 'mazette.lock' updated.
```
### `install`
The `install` command installs (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:
Install all assets for the current platform:
```
./mazette.py install
Installing 'asset1'
Installing 'asset2'
Installed 2 assets.
```
Install all assets for the provided platform:
```
./mazette.py install -p darwin/amd64
Installing 'asset3'
Installed 1 assets.
```
Install only specific assets:
```
./mazette.py install asset1
Installing 'asset1'
Installed 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.
Example:
```
./mazette.py list
asset1 0.0.1 https://github.com/owner/repo/releases/download/v0.0.1/asset1
asset2 1.2.3 https://github.com/owner/other/releases/download/v0.0.1/asset2
```
Pass `-vv` to get full details for each asset entry.
### Common Arguments
Each command supports the following optional arguments:
- `-p, --platform`:
Specify the platform for which the assets should be processed. Examples
include: `windows/amd64`, `linux/amd64`, `darwin/amd64`, `darwin/arm64`.
If not provided, the current platform is auto-detected.
- `-v, --verbose`:
Enable verbose logging. Use `-v` for INFO level or `-vv` (or more) for DEBUG
level messaging.
- `-C, --directory`:
Specify the working directory for the script. Defaults to the current working
directory if not provided.
## License
The mazette tool is licensed under either of:
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in assets by you, as defined in the Apache-2.0 license, shall be
dually licensed as above, without any additional terms or conditions.
Raw data
{
"_id": null,
"home_page": null,
"name": "mazette",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "assets, github, packaging",
"author": null,
"author_email": "Freedom of the Press Foundation <info@freedom.press>",
"download_url": "https://files.pythonhosted.org/packages/c8/b6/225a28aba60475e4030e84055df3449872f27c4cb8e0f2622c34ef15b630/mazette-0.2.1.tar.gz",
"platform": null,
"description": "# Mazette\n\nThe `mazette` tool is a Python script designed to manage assets from GitHub\nreleases. It expects a configuration file (in TOML format) that contains a list\nof assets and some parameters. Using this config file, it can query GitHub for\nrelease information, compute checksums for assets, update a lock file (JSON\nformat) and install assets as described in the lock file.\n\nIf you come from a Python background, think of it like \"Poetry, but for GitHub\nassets\".\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n - [Examples](#examples)\n - [`repo`](#repo)\n - [`version`](#version)\n - [`platform.<platform>`](#platformplatform)\n - [`executable`](#executable)\n - [`destination`](#destination)\n - [`extract`](#extract)\n - [`extract.globs`](#extractglobs)\n - [`extract.flatten`](#extractflatten)\n- [Commands](#commands)\n - [`lock`](#lock)\n - [`install`](#install)\n - [`list`](#list)\n - [Common Arguments](#common-arguments)\n- [License](#license)\n\n---\n\n## Installation\n\n```\npython -m pip install mazette\n```\n\nAlternatively, you can run it directly with\n[`uvx`](https://docs.astral.sh/uv/guides/tools/#running-tools):\n\n```\nuvx mazette --help\n```\n\n## Configuration\n\nBefore you begin working with the script, you must create a configuration file\nin one of the following locations of your project:\n* `mazette.toml`: This is a config file written specifically for this tool.\n* `pyproject.toml`: This is a config file written for a Python project. The\n mazette tool expects a `[tool.mazette]` section in this file.\n\n### Examples\n\nEach asset is defined as an entry under the `[asset]` section. For example:\n\n```toml\n[asset.example]\nrepo = \"owner/repo\"\nversion = \">=1.0.1\"\nplatform.\"darwin/arm64\" = \"asset-macos\"\nplatform.\"linux/amd64\" = \"asset-linux\"\nplatform.all = \"asset-universal\"\nexecutable = true\ndestination = \"./downloads/asset\"\nextract = false\n```\n\nIf you are using `pyproject.toml` as a config file, then you need to prepend\n`tool.mazette` to the section name, e.g., `[tool.mazette.asset.example]`.\n\n### `repo`\n\n**Type:** `string`\n\nThe GitHub repository identifier in the format `\"owner/repo\"`.\n\n### `version`\n\n**Type:** `string`\n\nA semantic versioning (semver) expression specifying the release version\nconstraint for the asset, such as `\">=1.0.1\"`, `\"==2.0.0\"`\n([options](https://python-semver.readthedocs.io/en/latest/usage/compare-versions-through-expression.html)).\n\n### `platform.<platform>`\n\n**Type:** `string`\n\nThe filename of an asset for a specific platform, since assets may have\ndifferent filenames per platform.\n\nAllowed argument names:\n* Strings like `platform.\"windows/amd64\"`, `platform.\"linux/amd64\"`,\n `platform.\"darwin/arm64\"`.\n* `platform.all`, for platform-agnostic assets, i.e., assets that should be\n installed regardless of the platform type.\n\nAllowed values:\n* Strings like `asset-linux-amd64`, `foo-0.1.0.zip`\n* Template strings like `foo-{version}.zip`, where `{version}` will be replaced\n during install time with the version of the asset (minus the leading `v`)\n* Special strings `\"!tarball\"` or `\"!zipball\"`, to get the GitHub-generated\n source archives for a release.\n\n### `executable`\n\n**Type:** `boolean`\n\n**Default:** `false`\n\nIndicates whether the downloaded asset should be marked as executable.\n\n### `destination`\n\n**Type:** `string`\n\nThe local path where the asset should be installed. If the asset is a file, the\ndestination will be its filename. Else, it will be the directory where the\ncontents will be extracted in.\n\n### `extract`\n\n**Type:** `boolean | list of strings | dict`\n\n**Default:** `false`\n\nExtraction options for zip/tar files. By default no extraction will take place.\nIf set to `true`, then the contents of the archive will be extracted to the\ndestination. If a list of globs is provided, only the matching filenames in the\narchive will be extracted.\n\nSee [`extract.globs`](#extractglobs) and [`extract.flatten`](#extractflatten)\nfor more info.\n\n### `extract.globs`\n\n**Type:** `list of strings`\n\n**Default:** `[\"*\"]`\n\nA list of glob strings to match specific files from an archive. Accepted values\nare any valid glob such as `*.exe`, `bin/**/asset`\n([options](https://docs.python.org/3/library/fnmatch.html)). Will extract all\nfiles in the archive if omitted.\n\n### `extract.flatten`\n\n**Type:** `boolean`\n\n**Default:** `false`\n\nIndicates whether the contents of the archive should be copied to the\ndestination root. By default the file hierarchy in the archive is preserved.\n\n## Commands\n\nThe mazette script supports three commands:\n- `lock`\n- `install`\n- `list`\n\nThe following sections assume you invoke the script with `poetry run`.\n\n### `lock`\n\nThe `lock` command updates the lock file based on the configuration defined in\n`pyproject.toml` / `mazette.toml`. For each asset, it reads its details,\nqueries GitHub to find the appropriate release and asset URL, computes a\nchecksum if the asset is available locally, uses caching for fetching and\nhashing, renders filenames that contain the `{version}` template string, and\nsupports assets that are platform-agnostic using `platform.all`.\n\nExample:\n\n```\n./mazette.py lock\nProcessing 'asset1'\nProcessing 'asset2'\nLock file 'mazette.lock' updated.\n```\n\n### `install`\n\nThe `install` command installs (downloads or copies) assets as specified in the\nlock file for the given platform (or the current platform if none is provided).\nIt downloads assets into a cache, verifies them against an expected hash, copies\nthem to the destination, marks files as executable if required, and extracts\nfiles based on the provided extraction criteria.\n\nExamples:\n\nInstall all assets for the current platform:\n\n```\n./mazette.py install\nInstalling 'asset1'\nInstalling 'asset2'\nInstalled 2 assets.\n```\n\nInstall all assets for the provided platform:\n\n```\n./mazette.py install -p darwin/amd64\nInstalling 'asset3'\nInstalled 1 assets.\n```\n\nInstall only specific assets:\n\n```\n./mazette.py install asset1\nInstalling 'asset1'\nInstalled 1 assets.\n```\n\n### `list`\n\nThe `list` command lists all assets defined for a specific platform, or the\ncurrent one, if not specified. The list output contains the name of the asset,\nits version, and its download URL.\n\nExample:\n\n```\n./mazette.py list\nasset1 0.0.1 https://github.com/owner/repo/releases/download/v0.0.1/asset1\nasset2 1.2.3 https://github.com/owner/other/releases/download/v0.0.1/asset2\n```\n\nPass `-vv` to get full details for each asset entry.\n\n### Common Arguments\n\nEach command supports the following optional arguments:\n\n- `-p, --platform`:\n Specify the platform for which the assets should be processed. Examples\n include: `windows/amd64`, `linux/amd64`, `darwin/amd64`, `darwin/arm64`.\n If not provided, the current platform is auto-detected.\n\n- `-v, --verbose`:\n Enable verbose logging. Use `-v` for INFO level or `-vv` (or more) for DEBUG\n level messaging.\n\n- `-C, --directory`:\n Specify the working directory for the script. Defaults to the current working\n directory if not provided.\n\n## License\n\nThe mazette tool is licensed under either of:\n\n* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)\n* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)\n\nat your option.\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in assets by you, as defined in the Apache-2.0 license, shall be\ndually licensed as above, without any additional terms or conditions.\n",
"bugtrack_url": null,
"license": null,
"summary": "GitHub asset management with lock files and extensive configuration",
"version": "0.2.1",
"project_urls": {
"Repository": "https://github.com/freedomofpress/mazette"
},
"split_keywords": [
"assets",
" github",
" packaging"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e58e245255a25cb73f770af5d7f863f0492d96dc3fc4c3ff0a209e7abe2bf234",
"md5": "810274dc24432cdd72802b29756666fb",
"sha256": "b87f166cad936075ea3eec87f031b95a8ef71cafc7764cfb5937e914b86f503a"
},
"downloads": -1,
"filename": "mazette-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "810274dc24432cdd72802b29756666fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17510,
"upload_time": "2025-08-07T10:12:51",
"upload_time_iso_8601": "2025-08-07T10:12:51.831261Z",
"url": "https://files.pythonhosted.org/packages/e5/8e/245255a25cb73f770af5d7f863f0492d96dc3fc4c3ff0a209e7abe2bf234/mazette-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c8b6225a28aba60475e4030e84055df3449872f27c4cb8e0f2622c34ef15b630",
"md5": "351f4fe61bb3bbb6b51e24d5ff290c14",
"sha256": "2e710e007f72413cefb9847dc16eadbc81130261b60f21e7e4c89567cd2f1c0f"
},
"downloads": -1,
"filename": "mazette-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "351f4fe61bb3bbb6b51e24d5ff290c14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 30032,
"upload_time": "2025-08-07T10:12:53",
"upload_time_iso_8601": "2025-08-07T10:12:53.775865Z",
"url": "https://files.pythonhosted.org/packages/c8/b6/225a28aba60475e4030e84055df3449872f27c4cb8e0f2622c34ef15b630/mazette-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 10:12:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "freedomofpress",
"github_project": "mazette",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mazette"
}
