Skip to main content

Configurations

API Reference

carefree-portable 📦️ is designed to hold configurations in one single file - the cfport.json file. This file has an identical structure with the Config class, so you may find that contents in this page are almost the same as the API Reference.

Typical cfpot.json file looks like this:

{
  "type": "auto",
  "info": {
    "workspace": "carefree-portable",
    "allow_existing": true,
    "assets": null,
    "downloads": {
      "python_embeddables": "3.10.11_64-bit"
    },
    "python_requirements": [
      {
        "install_command": "$pip install ."
      }
    ],
    "python_launch_cli": "cfport/cli.py",
    "external_blocks": null
  }
}
  • The type field indicates the target OS platform.
  • The info field contains all the configurations we need to build a portable package.

Below are the detail descriptions of each field in info.

workspace​

[ str, default: "cfport_package" ]

The workspace path, this is where your portable package will be stored.

allow_existing​

[ bool, default: True ]

Indicates whether to allow existing workspace. This is useful when the package process crashes and you want to restart it with caches.

assets​

[ List[str | dict] | None, default: None ]

The list of assets to fetch.

If it is not None, the items in the list will be converted into Asset objects for further processing:

  • str will be converted into Asset(path=asset).
  • dict will be converted into Asset(**asset).

downloads​

Reference

[ Dict[str, str | List[str]], default: {} ]

The dictionary of download configurations.

  • The key should be one of the files' names in the cfport/settings/downloads folder.
  • The value should be one of the keys in the corresponding json file.

Here's an example, which indicates we will download the file associated with the 3.10.11_64-bit key in the python_embeddables.json file:

{
  "python_embeddables": "3.10.11_64-bit"
}

And here's the pseudo code of how we process it:

cfport/executer/blocks/download.py
for k, vs in downloads.items():
    if isinstance(vs, str):
        vs = [vs]
    k_urls_path = SETTINGS_DIR / "downloads" / f"{k}.json"
    with k_urls_path.open("r") as f:
        k_urls = json.load(f)
    for v in vs:
        v_url = k_urls.get(v)
        if isinstance(v_url, dict):
            v_url = v_url.get(platform)
        download(v_url)

python_requirements​

[ List[str | dict], default: [] ]

The list of Python requirements.

The items in the list will be converted into PyRequirement objects for further processing:

  • str will be converted into PyRequirement(package_name=req).
  • dict will be converted into PyRequirement(**req).

huggingface_space_app_file​

[ str | None, default: None ]

The Hugging Face space app file, if any.

python_launch_cli​

[ str | None, default: None ]

The Python launch CLI file. It should relative to the site-packages directory.

python_launch_entry​

[ str | None, default: None ]

The Python launch entry file. It should relative to the workspace.

external_blocks​

[ List[str] | None, default: None ]

The list of external blocks, see Block for more details.

Last updated on