AcademySoftwareFoundation / AcademySoftwareFoundation/OpenTimelineIO

Python docstrings without *args, **kwargs

Open
#870 2 comments 0 reactions 0 assignees View on GitHub
bug documentation help wanted
Dominant language
C++
Stars
2k
Forks
351
Avg merge
1d 12h
Merged PRs (30d)
1

Description

## Bug Report

In the python docstrings, as noted in the discussion for this PR:
https://github.com/PixarAnimationStudios/OpenTimelineIO/pull/789

`*args, **kwargs` is visible rather than the specific arguments to the functions. This makes it significantly more difficult to use the documentation as a _discovery_ mechanism for understanding the API, a common practice in the python community.

For example:
``` python
| before(...)
| before(*args, **kwargs)
```

Applies to the time predicates: `before`, `begins`, etc.

## To Reproduce

```python
import opentimelineio as otio
help(otio.opentime.TimeRange.before)
```

## Expected Behavior

The arguments should appear in the signature, for example:

```python
| end_time_exclusive(...)
| end_time_exclusive(self: opentimelineio._opentime.TimeRange) -> opentimelineio._open
time.RationalTime
```

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the discussion in pull request 789 and reproduce the issue with help(otio.opentime.TimeRange.before). Inspect the Python-facing definitions for the TimeRange predicates, including before and begins. Done means help() displays the specific argument signatures instead of *args and **kwargs.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.