ni / ni/nidaqmx-python

Docstrings use `Optional[T]` incorrectly

Open
#502 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
592
Forks
199
Avg merge
1d 16h
Merged PRs (30d)
10

Description

Many of this package's docstrings incorrectly conflate Optional[T] with default arguments.
typing.Optional[T] means "either a T or a None", which is orthogonal to whether the parameter has a default argument or not.

Example: https://github.com/ni/nidaqmx-python/blob/master/src/handwritten/task.py

    def __init__(self, new_task_name='', *, grpc_options=None):
        """
        Creates a DAQmx task.

        Args:
            new_task_name (Optional[str]): Specifies the name to assign to
                the task.

                If you use this method in a loop and specify a name for the
                task, you must use the DAQmx Clear Task method within the loop
                after you are finished with the task. Otherwise, NI-DAQmx
                attempts to create multiple tasks with the same name, which
                results in an error.

            grpc_options (Optional[:class:`~nidaqmx.GrpcSessionOptions`]): Specifies
                the gRPC session options.
        """

new_task_name (Optional[str])): ... means that new_task_name has a type of typing.Optional[str], but that is not the case. It has a type of str. If you do not specify an argument for new_task_name, the default argument is used, which also has a type of str.

grpc_options (Optional[:class:~nidaqmx.GrpcSessionOptions]): ... is correct. The default argument has type None, so typing.Optional[GrpcSessionOptions] is needed to accept either a GrpcSessionOptions or a None.

https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html uses the syntax param2 (:obj:int, optional): . I don't know which meaning of "optional" it's using.

The best way to fix this is to add type hints and delete the types from the docstrings.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the docstring example in src/handwritten/task.py and read the linked issue #209 about adding type hints. Audit the package docstrings for cases where Optional describes a default rather than a nullable type, then align the documentation with the actual parameter types. Done means the incorrect Optional annotations are corrected consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.