Add type hints and/or reST docstrings

[samhaese]

What is the idea?

A lot of the conda modules have no type hinting, incomplete type hinting, no docstrings, or docstrings with varying formats (reST, Google).

What should happen?

We should clean up the types and doc strings of one module or several small modules per PR until the code base has better documentation and type hints.

Type hints should follow mypy guide

Docstrings should follow Sphinx guide

Modules in progress:

(None)

Modules finished:

• conda.cli
  • main_info.py: Type hints and doc strings: conda.cli.main_info #13445
  • main_search.py: Type hints for conda.cli.main_search #13465

Tasks

Beta Give feedback

1. conda.auxlib.* (0 finished, 0 in progress, 10 remaining)
2. conda.base.* (0 finished, 0 in progress, 4 remaining)
3. conda.cli.* (2 finished, 0 in progress, 24 remaining)
4. conda.common.* (0 finished, 0 in progress, 21 remaining)
5. conda.core.* (0 finished, 0 in progress, 12 remaining)
6. conda.gateways.* (0 finished, 0 in progress, 27 remaining)
7. conda.models.* (0 finished, 0 in progress, 10 remaining)
8. conda.notices.* (0 finished, 0 in progress, 6 remaining)
9. conda.plugins.* (0 finished, 0 in progress, 16 remaining)
10. conda.testing.* (0 finished, 0 in progress, 11 remaining)
11. conda.trust.* (0 finished, 0 in progress, 3 remaining)
12. conda.*.py (0 finished, 0 in progress, 15 remaining)

[travishathaway]

Hi @samhaese,

Thanks for creating this. We would be open to any pull request adding more type hinting or consolidating our documentation style. conda.deprecations is a good reference to use.

My advice to you if you want to submit such pull requests is to keep them narrow in scope (e.g. focus on one module at a time or limit lines to changed to around 1,000). This makes the pull requests smaller and easier for us to review. We have also begun to render our API documentation here recently:

• https://docs.conda.io/projects/conda/en/stable/dev-guide/api/conda/index.html

Please make sure that it renders correctly there when making any changes.

Let us know if you need any help on this. We are happy to assist.

[travishathaway]

One more thing:

It would be nice if you could make a check list of the things that you think should be updated on this issue. That way, others could potentially pick up some of this work. We could add our own suggestions to this list too.

[samhaese]

The task list and new layout of the issue has been added to help identify where people can easily contribute. I'll do another pass soon and mark modules completed that don't actually need any additional type hints or doc strings.

Maybe this is a "good first issue"?

[jezdez]

FWIW, since this came up in #13445, we should make use of sphinx-autoapi's ability to use typehints automatically to render return types and not duplicate the information in the source code.

[Nathann03]

Whoops didn't mean to do that

[Nathann03]

I'll be starting to work on this issue if that is fine! First time contributor and ready to help!

[samhaese]

@Nathann03 I've been keeping each pull request to one module at a time so far. As you look through the code, find a module you think you can tackle and submit a PR linking to this issue and I'll add it to the list at the top.