[BUG] zypperpkg add_lock and remove_lock examples do not work

[oeuftete]

Description

The current examples for the zypperpkg add_lock and remove_lock methods include a non-working example.

salt/salt/modules/zypperpkg.py

Line 1894 in 0f58560

salt '*' pkg.remove_lock pkgs='["foo", "bar"]'

salt/salt/modules/zypperpkg.py

Line 1927 in 0f58560

salt '*' pkg.add_lock pkgs='["foo", "bar"]'

Steps to Reproduce the behavior

salt-call pkg.add_lock pkgs='["foo", "bar"]'
salt-call pkg.remove_lock pkgs='["foo", "bar"]'

Errors from `add_lock` (similar for `remove_lock`)

a6ec4f481e57:/ # salt-call pkg.add_lock pkgs='["foo", "bar"]'

Passed invalid arguments: add_lock() missing 1 required positional argument: 'packages'.

Usage:

    Add a package lock. Specify packages to lock by exact name.

    CLI Example:

    .. code-block:: bash

        salt '*' pkg.add_lock <package name>
        salt '*' pkg.add_lock <package1>,<package2>,<package3>
        salt '*' pkg.add_lock pkgs='["foo", "bar"]'
    
a6ec4f481e57:/ # salt-call pkg.add_lock packages='["foo", "bar"]'
[ERROR   ] An un-handled exception was caught by salt's global exception handler:
AttributeError: 'list' object has no attribute 'split'
Traceback (most recent call last):
  File "/usr/bin/salt-call", line 11, in <module>
    sys.exit(salt_call())
  File "/usr/lib/python3.6/site-packages/salt/scripts.py", line 472, in salt_call
    client.run()
  File "/usr/lib/python3.6/site-packages/salt/cli/call.py", line 58, in run
    caller.run()
  File "/usr/lib/python3.6/site-packages/salt/cli/caller.py", line 121, in run
    ret = self.call()
  File "/usr/lib/python3.6/site-packages/salt/cli/caller.py", line 229, in call
    self.opts, data, func, args, kwargs
  File "/usr/lib/python3.6/site-packages/salt/executors/direct_call.py", line 12, in execute
    return func(*args, **kwargs)
  File "/usr/lib/python3.6/site-packages/salt/modules/zypperpkg.py", line 1932, in add_lock
    packages = list(__salt__["pkg_resource.parse_targets"](packages)[0].keys())
  File "/usr/lib/python3.6/site-packages/salt/modules/pkg_resource.py", line 174, in parse_targets
    packed = dict([(_normalize_name(x), version) for x in name.split(",")])
AttributeError: 'list' object has no attribute 'split'
Traceback (most recent call last):
  File "/usr/bin/salt-call", line 11, in <module>
    sys.exit(salt_call())
  File "/usr/lib/python3.6/site-packages/salt/scripts.py", line 472, in salt_call
    client.run()
  File "/usr/lib/python3.6/site-packages/salt/cli/call.py", line 58, in run
    caller.run()
  File "/usr/lib/python3.6/site-packages/salt/cli/caller.py", line 121, in run
    ret = self.call()
  File "/usr/lib/python3.6/site-packages/salt/cli/caller.py", line 229, in call
    self.opts, data, func, args, kwargs
  File "/usr/lib/python3.6/site-packages/salt/executors/direct_call.py", line 12, in execute
    return func(*args, **kwargs)
  File "/usr/lib/python3.6/site-packages/salt/modules/zypperpkg.py", line 1932, in add_lock
    packages = list(__salt__["pkg_resource.parse_targets"](packages)[0].keys())
  File "/usr/lib/python3.6/site-packages/salt/modules/pkg_resource.py", line 174, in parse_targets
    packed = dict([(_normalize_name(x), version) for x in name.split(",")])
AttributeError: 'list' object has no attribute 'split'

Expected behavior

All documented examples should work.

Versions Report

salt --versions-report

(Provided by running salt --versions-report. Please also mention any differences in master/minion versions.)

Installed with bootstrap-salt.sh -X -x python3 git master.

Salt Version:
           Salt: 3000-n/a-a8d3c06
 
Dependency Versions:
           cffi: Not Installed
       cherrypy: Not Installed
       dateutil: Not Installed
      docker-py: Not Installed
          gitdb: Not Installed
      gitpython: Not Installed
         Jinja2: 2.11.2
        libgit2: Not Installed
       M2Crypto: Not Installed
           Mako: Not Installed
   msgpack-pure: Not Installed
 msgpack-python: 0.6.2
   mysql-python: Not Installed
      pycparser: Not Installed
       pycrypto: Not Installed
   pycryptodome: 3.9.7
         pygit2: Not Installed
         Python: 3.6.10 (default, Jan 16 2020, 09:12:04) [GCC]
   python-gnupg: Not Installed
         PyYAML: 5.3.1
          PyZMQ: 19.0.0
          smmap: Not Installed
        timelib: Not Installed
        Tornado: 4.5.3
            ZMQ: 4.3.2
 
System Versions:
           dist:   
         locale: UTF-8
        machine: x86_64
        release: 5.3.0-46-generic
         system: Linux
        version: Not Installed

Additional context

Note that this is also a problem in the published SuSE packages. In their latest packages, these two methods are flagged as deprecated for their provided hold/unhold methods (#50773), which are not currently part of released Open.

[sagetherage]

@saltstack/docs-working-group and thank you @oeuftete for the PR draft!

[ScriptAutomate]

This looks like the documentation problem, with working examples being included in #50773, will be resolved once the PR is merged. I have included further guidance in that PR about including .. deprecated:: directives in the docstrings of the functions being deprecated.

@sagetherage Though this ticket no longer needs docs assistance/review (but should be left open in order to be auto-closed by #50773), I have opened a new ticket here related to needing to extend deprecation docs as follow-up: #58208

[sagetherage]

@waynew looks like the draft PR that is open may need some help with writing tests, so adding you here to help with that to see we can get this issue across the finish line for Magnesium Release cycle. Thank you!!

[waynew]

@oeuftete If you'd like, we can take a look at tests during the Test Clinic tomorrow afternoon (2PM Central Time)

[sagetherage]

De-scoping from the Magnesium release since the port to master PR still needs a test case written. That could change, but for now I am de-scoping.

[ScriptAutomate]

#56935 will resolve this issue once it is merged.