Fix bug where cmd.powershell fails to return

[twangboy]

What does this PR do?

Fixes a bug where some powershell commands would take hours to complete due to the extreme depth setting for ConvertTo-JSON. Reverted to the Windows default (2) and added the option to pass a different value.

Added additional notes to the documentation explaining the purpose of the cmd.powershell function as the name is misleading. Made recommendations to use cmd.run with shell=powershell instead unless they need the data output to be a dictionary.

What issues does this PR fix or reference?

#31509

Previous Behavior

Basic powershell commands such as dir take exponentially longer times to complete as the depth value for ConvertTo-JSON increases. Anything above 4 is painful. It was hard-coded to 32.

New Behavior

Changed the depth value to use Windows defaults (2) with the option to pass a different value.

Tests written?

No

[terminalmage]

We should make it explicit that the depth parameter is new to 2016.3.4.

[terminalmage]

Oops, sorry, accidentally clicked to close and comment instead of just to comment.

[twangboy]

@terminalmage Added .. versionadded:: 2016.3.4 to the depth option

[terminalmage]

This doesn't look accurate. This is executing a cmd.run, which most certainly does not return a dictionary. There is a difference between a dictionary, which is a data structure, and a string of JSON, whichis not. JSON looks like a Python dictionary, but it is not a dictionary. Please change this back to what it was originally, or at least clarify and say "return the output in JSON format".

[terminalmage]

Disregard, I wrongly thought that we were returning the result of the run() command.

[terminalmage]

Again, wrong. Not a dictionary. It would be accurate to say "A JSON-formatted string of data returned by the powershell command."

[terminalmage]

Disregard, I wrongly thought that we were returning the result of the run() command.

[damon-atkins]

Could you make depth a kwargs please.
Effectively it is any way, as no one is going to call it with all the parameters to eventual reach it to set the depth. I need to open a generic item for this against all public functions.

[terminalmage]

@damon-atkins that should not be necessary. It can be called on the Salt using depth=8 and Salt's CLI client will format the function call correctly.

[damon-atkins]

It creates a support issue with the order of the parameters, as you can not control how user base will use it. If you expect to always call it with depth=8 then it should be a kwargs Why create a maintenance overhead. e.g.
A shell script with

#!/bin/bash
# do some CI/CD
salt windows cmd.powershell 'mycmd'  None  None  None  powershell  None  False  None  False  None  'info'  True   60   True  False  'test'  True  'abc'
# do more stuff

use_vt is marked experimental, let say SaltStack decide its no good and should be removed.
The param can not be removed because it would upset the order of the params, as its not the last param, its the 3rd last one. Current method locks you in.

If most of them were kwargs, then it could be ignored, or you could provide a warning for it when its set.

I have started an issue for it.

[terminalmage]

I believe that the arg=value usage is the recommended usage anyway. At least that's how I remember it being from when I started using salt, and it's how I've always used it.

@thatch45 thoughts? I personally think that if you're going to be worried about argument order, then why not make everything with a default value a kwarg, everywhere in Salt?

[thatch45]

It is better this way, having it be an explicit argument like this makes it detectable by salt and the state system which makes it easier for our automated argument forwarding to better report on it.

[twangboy]

@terminalmage What else do I need to do on this one?

[terminalmage]

@twangboy Looks like there are still a couple docstring edits that need to be made, see my comments from last week here.

The rest of the PR looks good.

[twangboy]

@terminalmage The last thing the function does is run json.loads on the result which I believe is a Python dictionary (line 2801).

[terminalmage]

You're right, I misread and thought that the result of the run() was being returned. Sorry!