extension.yml
The extension.yml
document contains metadata pertaining to a Universal Extension. This document must be included in the Universal Extension zip archive at the root level (along with extension.py
).
extension: name: extension1 version: "0.1.0" api_level: "1.4.0" requires_python: ">=3.6" python_extra_paths: "${extension_zip}/lib:${extension_zip}/test/lib" zip_safe: true owner: name: John Doe organization: Stonebranch, Inc. comments: | These comments will appear in the Controller in the Universal Template 'Extension Comments' field. The 'Extension Comments' field can be viewed from the Meta Data section, the List, or the Show Details.
The file contains three sections: extension, owner, and comments.
extension
The extension section contains attributes that pertain to extension management and operation. Some fields are optional.
name
The name
attribute is required. It is used to identify the extension within the UAC system and therefore, must be unique within that system.
version
The version
attribute is required. This attribute is used in the generation of dependency package file names for a given extension.
api_level
The api_level
attribute is required. This attribute is used to specify the Universal Extension API level required by the extension. There are two important things controlled by the api_level
.
- The Universal Controller will only run a Universal Extension task on an agent that supports the
api_level
specified by extension. - The agents running the extension will only "activate" the functionality associated with the specified API level - regardless of the API level supported by the agent. Therefore, the
api_level
is the upper bounds of API support that will be available to the extension.
The extension developer should consider the target API level carefully. Specifying the latest API level will make the most functionality available to the extension. However, it will also restrict the extension to only running on the latest agents.
In general, an extension should not specify an API level higher than what is required by the extension. Doing so only servers to restrict the range of agent versions it can run on.
requires_python
The requires_python
attribute is optional. This attribute allows the extension to specify the versions of Python it can work with. The syntax and semantics are a subset of PEP 440 version specifiers. Its value consists of one or more version specifier clauses delimited by commas. A specifier clause consists of a comparison operator and a version number. if not specified, a default value of >=2.7
will be used. Valid comparison operators are as follows:
Operator | Meaning |
---|---|
== | Equal to |
!= | Not equal to |
< | Less than to |
<= | Less than or equal to |
> | Greater than |
>= | Greater than or equal to |
A single version specifier consists of one of the above operators, followed by a version which must use one of these formats.
Major | Minor | Patch | Note | ||
---|---|---|---|---|---|
Number | Equivalent to Number. 0. 0 | ||||
Number | . | Number | Equivalent to Number. Number. 0 | ||
Number | . | Number | . | Number | |
Number | . | * | |||
Number | * | Equivalent to Number.* | |||
Number | . | Number | . | * | |
Number | . | Number | * | Equivalent to Number. Number.* |
The wildcard *
is used in place of the minor number to mean that any version with a matching major number matches the specifier; or in place of the patch number to mean that any version with a matching major and minor number matches the specifier.
For example:
!=2*,!=3.9.* | No 2 version, and no 3.9 version | <2,>=3,<3.9,>=4 | Less than 2.0.0, and greater or equal to 3.0.0, and less than 3.9.0 and greater or equal to 4.0.0 | !=2*,!=3.* | No 2 version, and no 3 version |
==2.7.*,>=3.5 | Any 2.7 version, and greater than or equal to 3.5.0 | >=2.7.0,<=2.8 | Greater than or equal to 2.7.0, and less than or equal to 2.8.0 | ==3.11.2 | Equal to 3.11.2 |
>=3.6 | Greater than or equal to 3.6.0 | ==2.8.* | Any 2.8 version | >3.6.* | Greater than any 3.6 version |
The comparison algorithm is as follows: given Python versions A and B,
- If A.major > B.major, A > B
If A.major < B.major, A < B
If either A.minor or B.minor is a wildcard, A == B
If A.minor > B.minor, A > B
If A.minor < B.minor, A < B
If either A.patch or B.patch is a wildcard, A == B
If A.patch > B.patch, A > B
If A.patch < B.patch, A < B
A == B
python_extra_paths
The python_extra_paths
attribute is optional. This attribute provides a means for the extension developer to specify additional paths that will be included in the Python runtime environment in which the extension runs. Since it is impossible for the extension developer to know the path to the deployed extension at runtime, a special token is provided that will resolve to the deployed extension path at runtime: ${extension_zip}
.
At runtime, ${extension_zip}
will be replaced with the file system path to the deployed extension. For example, if an extension archive included a directory for test modules:
├── extension.py ├── extension.yml └── test └── test1.py └── test2.py └── test3.py
The following python_extra_paths
value would setup pathing in the runtime environment allowing the extension code to access the test
package:
python_extra_paths: ${extension_zip}/test
zip_safe
The zip_safe
attribute is optional. It specifies whether the extension should be run directly from the zip archive or extracted to the file system in a private cache and run from there. The default value is true.
This attribute was introduced in Universal Extension API level 1.4.0. In order for zip_safe: false
to have any impact, the extension must specify a Universal Extension API level >= 1.4.0 via the api_level
attribute in extension.yml
.
If an extension requires "dependency packages" (introduced in Universal Extension API 1.4.0), the extension must specify zip_safe: false
.
owner
This section pertains to the owner of the extension (the extension developer or developer's organization).
name
The name
attribute is optional. Specifies the Universal Extension owner's name. This field is displayed in the Metadata section of an extensions Universal Template in the Universal Controller. It is for informational purposes only.
organization
The organization
attribute is optional. Specifies the Universal Extension developer's organization. This field is displayed in the Metadata section of an extensions Universal Template in the Universal Controller. It is for informational purposes only.
comments
The comments
section is optional. This attribute allows the extension developer to provide information about the extension. This field is displayed in the Metadata section of an extensions Universal Template in the Universal Controller. It is for informational purposes only.