Help and documentation 'list of unicodes' inconsistent
Affects | Status | Importance | Assigned to | Milestone | |
---|---|---|---|---|---|
MAAS |
Fix Released
|
High
|
Mike Pontillo | ||
1.9 |
Won't Fix
|
High
|
Mike Pontillo | ||
2.0 |
Won't Fix
|
High
|
Mike Pontillo |
Bug Description
Documentation and help text refers to 'list of unicodes' for some params but what that means is undefined and inconsistent.
In tags= it can be either comma separated, or multiple params:
:param tags: List of tags the returned machine must have.
:type tags: list of unicodes
:param not_tags: List of tags the acquired machine must not have.
:type tags: List of unicodes.
$ maas $MAAS nodes acquire tags=a,b verbose=true dry_run=true
{"tags": ["No such tag(s): 'a', 'b'."]}
$ maas $MAAS nodes acquire tags=a tags=b verbose=true dry_run=true
{"tags": ["No such tag(s): 'a', 'b'."]}
Both correctly interpret as two tags, 'a' and 'b'.
But for networks/
:param networks: List of networks (defined in MAAS) to which the
machine must be attached. ...
:type networks: list of unicodes
:param not_networks: List of networks (defined in MAAS) to which the
machine must not be attached. ...
:type not_networks: list of unicodes
$ maas $MAAS nodes acquire networks=space:1 verbose=true dry_run=true
No available node matches constraints: networks=
$ maas $MAAS nodes acquire networks=
{"networks": ["No matching subnets found."]}
This is maas attempting to say the param couldn't be parsed, in a confusing manner.
$ maas $MAAS nodes acquire networks=space:1 networks=space:0 verbose=true dry_run=true
No available node matches constraints: networks=
This is maas understanding the constraint correctly.
Also, 'unicode' would generally be treated as a maas-noun in english, so no 's' for the plural.
Related branches
- Mike Pontillo (community): Approve
-
Diff: 178 lines (+122/-34)1 file modifiedsrc/maasserver/api/machines.py (+122/-34)
Changed in maas: | |
assignee: | nobody → Mike Pontillo (mpontillo) |
no longer affects: | maas/2.1 |
Changed in maas: | |
milestone: | none → 2.1.1 |
status: | New → In Progress |
importance: | Undecided → High |
Changed in maas: | |
status: | In Progress → Fix Committed |
Changed in maas: | |
status: | Fix Committed → Fix Released |
I agree; this is very confusing.
I was thinking of changing the documentation to read more like:
:param arch: Architecture of the returned machine (e.g. 'i386/generic',
'amd64', 'armhf/highbank', etc.). If multiple architectures are
specified, the machine to acquire may match any of the given
architectures. To request multiple architectures, this parameter
must be repeated in the request with each value.
:type arch: unicode (accepts multiple)
...
:param tags: The tag name(s) the machine to acquire must be tagged
with. If multiple tag names are specified, the machine must be
tagged with all of them. To request multiple tags, this parameter
must be repeated in the request with each value.
:type tags: unicode (accepts multiple)
I already have a bug open to address documentation problems with constraints, so I might fix this under that one.