Undocumented valid argument "tag" in client.instance_create() function and undocumented requirements for client.create_tag() function

[santiago-mooser]

As per the title, there's missing documentation entries for two functions:

• The "tag" parameter in the instance_create() function of the LinodeClient() class
• The user permissions requirements for the tag_create() class

This led to a lot of trial and error on my part when I tried to create a new instance with a new tag in a restricted account.

The docs clearly say that the client.tags() function requires an unrestricted account. However, the entry for client.tag_create() does not, and causes and error when called on by a restricted user.

Example

When trying to create a new tag and apply it to all or any instances:

client = LinodeClient(settings.get("API_key"))
instance = client.instance_create(.....)
client.tag_create(label="random", instances=instance)

This results in a 403 response from the API:

Traceback (most recent call last):
  File "./deploy.py", line 53, in <module>
    main()
  File "./deploy.py", line 31, in main
    tags = client.tag_create(label="random")
  File "/usr/local/lib/python3.7/dist-packages/linode_api4/linode_client.py", line 1408, in tag_create
    result = self.post('/tags', data=params)
  File "/usr/local/lib/python3.7/dist-packages/linode_api4/linode_client.py", line 1185, in post
    return self._api_call(*args, method=self.session.post, **kwargs)
  File "/usr/local/lib/python3.7/dist-packages/linode_api4/linode_client.py", line 1156, in _api_call
    raise ApiError(error_msg, status=response.status_code, json=j)
linode_api4.errors.ApiError: 403: Unauthorized;

counterexample

This is not to say that new instances cannot be tagged: the alternative is to specify the tag when creating a new instance, but this is missing from the documentation.
Here's some example code that has worked for me:

[...]
client = LinodeClient(settings.get("API_key"))
new_linode, new_password = client.linode.instance_create(settings.get("type"), 
                                                    settings.get("region"), 
                                                    tags=['random'], 
                                                    image=deployment_image, 
                                                    authorized_keys=settings.get("ssh").get("key"), 
                                                    label=label, 
                                                    booted=True)

However, this is not documented in the entry for the instance_create() function

Suggestions

1. Add a note to the tag_create() class documentation entry notifying developers of the restriction (similar to how the client.tags() entry does)
2. Add the parameter "tags" to the supported list of arguments in the client.instance_create() documentation and source

Edit: grammar and spelling

[Dorthu]

Thanks for the report. I opened #188 to address the documentation concerns. I'm asking our API team about the current restrictions on creating tags before documenting them, as they seem confusing to me and might warrant an upstream change.

[santiago-mooser]

Thank you!