Is it file.copy_ or file.copy ?

[James Pearson]

Something that has puzzled me for a while, the salt.states.file documentation at <https://docs.saltproject.io/en/3006/ref/states/all/salt.states.file.html#salt.states.file.copy_> has the copy state as 'file.copy_' - but this doesn't work - you have to use 'file.copy' - and even the given example has the comment: Use 'copy', not 'copy_'

So why does the documentation give the state as 'salt.states.file.copy_ ' ?

Is this a documentation error - or is there some reason for this - i.e. is there some significance of the trailing underscore ?

Thanks

James Pearson

[Dafydd Jones (techneg.it)]

The reasoning is described here as

Sometimes one wishes to use a function name that would shadow a python built-in. A common example would be set(). To support this, append an underscore to the function definition, def set_():, and use the __func_alias__ feature to provide an alias to the function.

__func_alias__ is a dictionary where each key is the name of a function in the module, and each value is a string representing the alias for that function. When calling an aliased function from a different execution module, state module, or from the cli, the alias name should be used.

The documentation is generated from the code, hence the copy_, but the documentation generation process is not sophisticated enough to handle function aliases which are, I guess, handled by the Salt loader.

HTH

Dafydd 

--
You received this message because you are subscribed to the Google Groups "Salt-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to salt-users+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/salt-users/95a2ede8-c788-4f47-b073-739bbae65f26n%40googlegroups.com.

[Evgeni Daskalov]

That’s a peculiarity about the way the Salt documentation was written and I agree, it could have been clearer in this respect.

Salt is Python-based and in the Python language some function names are given a trailing underscore to avoid conflicts with Python’s reserved keywords. That way the copy_ function is guaranteed uniqueness within the Python codebase for the Salt framework.

For the general user, those functions are exposed as “states” and their naming convention / syntax simplified to make it more user-friendly.

So the documentation shows how this function is named in the Python module but Salt will call this function as file.copy when writing states.

Hope this explanation helps.

Kind Regards,

Evgeni

[evgeni....@gmail.com]

That’s a peculiarity about the way the Salt documentation was written and I agree, it could have been clearer in this respect.

 

Salt is Python-based and in the Python language some function names are given a trailing underscore to avoid conflicts with Python’s reserved keywords. That way the copy_ function is guaranteed uniqueness within the Python codebase for the Salt framework.

 

For the general user, those functions are exposed as “states” and their naming convention / syntax simplified to make it more user-friendly.

 

So the documentation shows how this function is named in the Python module but Salt will call this function as file.copy when writing states.

 

Hope this explanation helps.

 

Kind Regards,

Evgeni

 

 

 

--

[James Pearson]

Thanks for the explanation - but it's a shame that whatever generates the documentation can't 'strip' the trailing underscore in cases like this - or, at least, include some better info in the description of the file.copy state - currently, there is only a comment in the given example, but no context on why 'file.copy' needs to be used and not 'file.copy_' ...

James Pearson