yubikey-manager

yubikey-manager copied to clipboard

• YubiKey Manager (ykman) version: 5.0.0
• How was it installed?: pip install yubikey-manager (latest from PyPI)
• Operating system and version: Ubuntu Linux 18.04.6 LTS Bionic (and higher)
• YubiKey model and version: YubiKey 5 NFC (5.4.3)
• Bug description summary: Python API docs not available

Steps to reproduce

1. Go to Developer.yubico.com
2. Find the yubikey-manager documentation
3. There are not Python API docs, only a chapter with examples

Expected result

For a good developer experience it would be helpful to have a complete API documentation.

Actual results and logs

As a developer, I have to consult the source code, as an alternative, to understand how the Python package can be used.

Other info

Potential role model: Click documentation

For me the examples don't even work:

>>> from ykman.device import connect_to_device
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: cannot import name 'connect_to_device' from 'ykman.device' (/home/dmarinus/.cache/pypoetry/virtualenvs/aws-credential-process-XniAX0gx-py3.10/lib/python3.10/site-packages/ykman/device.py)

In the meantime I'm using this:

def ykman_main(*args):
    """
    Helper function for ykman (yubikey manager)
    """
    stdout = io.StringIO()
    stderr = io.StringIO()
    with contextlib.redirect_stderr(stderr):
        with contextlib.redirect_stdout(stdout):
            try:
                ykman._cli.__main__.cli.main(args=args)
            except SystemExit:
                pass
    return stdout.getvalue().splitlines(), stderr.getvalue().splitlines()

Because the end-user documentation is at least clear to me.

Please include this as an API and I think you'd help a lot of people.

See also: https://github.com/Yubico/yubikey-manager/pull/425

@dmarinuswoodwing I opened #532 as a dedicated issue for the non-working examples.

API documentation is available at https://developers.yubico.com/yubikey-manager/API_Documentation/

There is certainly still room for improvement, but it's a lot better than it used to be!