Is there documented good way a plugin should deal with params ?

[fkuep]

Now if go ahead and model "url is set " into this diagram in Readme

I still have three problems:

• I don't understand about ini and env values and their precedence.
• Should we even (as think now) most in the constructor vs the kv.get request (in case consul decides tokens have to be inheaders) ?
• Is there a documented best practise or a does a mock unit test make sense ?
• Also there is terms in which I suppose with_module_ -multi-invocation is handled..

[fkuep]

"Prior art" to this ticket: ansible/proposals#15
This lead to a comment in LookupBase

[bcoca]

I just ported all core lookups that use options to the plugin config system, this should be the standard way of handling options.

The current docs are generic about plugins but I'll follow up with specifics per plugin type, including lookups, but the short of it is:
a) create DOCUMENTATION with the options you want and the various configuration methods available. Declaring the option makes it 'directly settable' in lookup via k=v argument passing lookup('x', <terms>. optionname='value')
b) call set_options() early in your run method
c) use get_option() to get the 'resolved' value you want.

draft ansible/ansible#74495 (feedback welcome)

[fkuep]

I just ported all core lookups that use option
..
current docs are generic about plugins but I'll follow up with specifics per plugin type
..
draft ansible/ansible#74495 (feedback welcome)

@bcoca Thank You veriy much for the effort!
That makes it much easier for a beginner like me to know how to start developing!

• Now I fell more confident in my understanding , that where possible I should not try and fiddle parsing terms myself for options.
• Is there a way (argspec ?) to tell a user that an option does not exsist in a lookup plugin ?
  • or validate options in a standard way ?

You probably saw, that I am trying to deal with legacy code:
ansible-collections/community.general#2126 (comment)

In #7 You can see me discovering (after days of chewing on the code) that:

• certain options must be put inside terms
• others must be put in oprtion= format

And if put inside terms, there is some validation, where I can see an error, when I use a wrong option.
Whereas set_options leads to superfluous options being ignored silently.

So knowing "the way" to input validation for set_option in lookup plugins would greatly help me over that hurdle.

[bcoca]

Is there a way (argspec ?) to tell a user that an option does not exsist in a lookup plugin ?

set_options/set_option does that validation, the DOCUMENTATION is your argspec

certain options must be put inside terms

This should be discontinued, but if you look at core lookups, I kept this for backwards compatibility (in next version I plan to add deprecation message) see ansible/ansible#74108 (PR that migrated all of them to use set_options/get_option).

You can parse this way and use set_option to override the settings for that term (you might want to reset to global at start of term loop).

others must be put in oprtion= format

This should be the standard going forward

[fkuep]

Is there a way (argspec ?) to tell a user that an option does not exsist in a lookup plugin ?

set_options/set_option does that validation, the DOCUMENTATION is your argspec

Well then, for example... :
What should be written into the DOCUMENTATION
in order to abort execution or display a warning, if a user sends the non-exsiting option 'schema' instead of 'scheme' ?

The legacy code does this while parsing the "terms for options".

[bcoca]

use set_optoins/set_option, they do all the validation on required, type and matching existing settings.