Make user-visible types public to support type hints

[bkeryan]

The task subobject types (AIChannel, Timing, etc.) are defined in internal modules contained in the private nidaqmx._task_modules package. When users write helper functions that accept channel objects or other task subobjects, they must refer to these internal modules. We should make these modules public and/or add public aliases for their types.

@StSav012 brought this up in https://github.com/ni/nidaqmx-python/pull/458

[bkeryan]

I think we should turn task.py into a package, merge it with _task_modules, make most of the submodules private, and add aliases to reexport types from the subpackages.

Something like this:

nidaqmx/
  task/
    __init__.py - defines Task; reexports ExportSignals, InStream, OutStream, Timing, Triggers
    channels/
      __init__.py - reexports Channel, AIChannel, AOChannel, etc.
      _channel.py - defines Channel
      _ai_channel.py - defines AIChannel
      ...
    collections
      __init__.py - reexports ChannelCollection, AIChannelCollection, AOChannelCollection, etc.
      _channel_collection.py - defines ChannelCollection
      _ai_channel_collection.py - defines AIChannelCollection
      ...
    _export_signals.py - defines ExportSignals
    _in_stream.py - defines InStream
    _out_stream.py - defines OutStream
    _timing.py - defines Timing
    _triggers.py - defines Triggers
    triggering/
      __init_.py - reexports triggering classes
      _arm_start_trigger.py - defines ArmStartTrigger
      ...

The public types would be:

nidaqmx.task.Task
nidaqmx.task.ExportSignals
nidaqmx.task.InStream
nidaqmx.task.OutStream
nidaqmx.task.Timing
nidaqmx.task.Triggers
nidaqmx.task.channels.Channel, AIChannel, etc.
nidaqmx.task.collections.ChannelCollection, AIChannelCollection, etc.
nidaqmx.task.triggering.ArmStartTrigger, HandshakeTrigger, etc.

[charitylxy]

Completed refactoring work for task and its submodules, documentation is updated accordingly. Closing this issue.

[bkeryan]

Some of the types in nidaqmx.system are not public yet. Also, the docs refer to nonexistent modules like nidaqmx.system.collections and nidaqmx.system.device_collection: https://nidaqmx-python.readthedocs.io/en/latest/collections.html

(This is really nidaqmx.system._collections, which is private.)

[charitylxy]

@bkeryan The things needed to update are:

1. nidaqmx.system.collections: making the submodules in collections private and update docs
2. nidaqmx.system.storage: upadate docs
3. nidaqmx.system.watchdog: making _watchdog_modules public and its submodules private and update docs

Anything else i miss out?

[bkeryan]

nidaqmx.system.collections: making the submodules in collections private and update docs

Also make nidaqmx.system.collections itself public & add aliases for the collection types.

nidaqmx.system.storage: upadate docs

nidaqmx.system.storage and nidaqmx.system.storage.persisted_channel are both public, so the only thing that is entirely wrong here is the docs.

However, it's confusing that you can import PersistedChannel from either nidaqmx.system.storage and nidaqmx.system.storage.persisted_channel. That fails "There should be one-- and preferably only one --obvious way to do it." from the Zen of Python.

It would make sense to shorten nidaqmx.system.storage.persisted_channel.PersistedChannel -> nidaqmx.system.storage.PersistedChannel for consistency with the other subpackages like collections, channels, etc. and keep the old submodules around as deprecated compatibility shims.

nidaqmx/system/storage/
   __init__.py: Exports PersistedChannel, PersistedTask, PersistedScale
   _persisted_channel.py, etc.: Defines PersistedChannel, etc.
   persisted_channel.py, etc.: Announces a DeprecationWarning and re-exports PersistedChannel or whatever.

nidaqmx.system.watchdog: making _watchdog_modules public and its submodules private and update docs

I think you should turn watchdog into a package like you did with task.

nidaqmx/system/watchdog/
   __init__.py: Exports WatchdogTask, ExpirationState, ExpirationStateCollection
   _watchdog_task.py: Renamed version of watchdog.py
   _expiration_state.py
   _expiration_state_collection.py

(Or you can rename watchdog.py to watchdog/__init__.py if that's easier.)