Being more explicit with documenting public API

[fridex]

Description of issue or feature request:

As a result of discussion in https://github.com/theupdateframework/python-tuf/pull/2234, opening this issue to make consensus on eventually declaring public API directly in Python sources.

Current behavior:

Developers can explore API provided by python-tuf using RTD pages. As per PEP-8 standard, __all__ could be considered to declare public API. Note by doing so, this also affects start imports.

Expected behavior:

Identify possible use-cases for declaring public API in Python sources.

[jku]

I'll leave some comments for ngclient since I think that's the easy case:

• I'm pretty happy with what is in tuf/ngclient/__init__.py: that really defines the public ngclient API. Defining __all__ sounds good to me -- but not sure if it changes anything from default? Maybe defining __all__ even if it is same as default is good practice? :shrug:
• in hindsight, all of the sub modules could have been internal (so updater.py could be _updater.py or _internal/updater.py)
  • If we did that, probably the only required addition to __init__.py might be a import TargetFile (because the updater API exposes it so makes sense to make it available)
  • This would be an API change but likely not a problematic one

I think the ngclient changes sound reasonable (not strictly necessary but result would likely be better software)

[fridex]

See also https://github.com/theupdateframework/python-tuf/pull/2234#issuecomment-1365761814