BUG: Failed to import apstools.devices.labjack.

[prjemian]

CI workflow did not fail for this Sphinx build error:

2024-01-02T11:32:16.7588835Z Running Sphinx v5.3.0
2024-01-02T11:32:19.0105200Z making output directory... done
2024-01-02T11:32:19.0293808Z [autosummary] generating autosummary for: api/_callbacks.rst, api/_devices.rst, api/_filewriters.rst, api/_plans.rst, api/_utils.rst, api/index.rst, api/synApps/__common.rst, api/synApps/_asyn.rst, api/synApps/_busy.rst, api/synApps/_calcout.rst, ..., examples/index.rst, examples/pl_excel_scan.ipynb, examples/pl_lineup.ipynb, examples/pl_nscan.ipynb, examples/pl_run_command_list.rst, examples/pl_tuneaxis.ipynb, index.rst, install.rst, license.rst, overview.rst
2024-01-02T11:32:19.3964658Z Failed to import apstools.devices.labjack.
2024-01-02T11:32:19.3971379Z Possible hints:
2024-01-02T11:32:19.3972515Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.3973850Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.3975077Z Failed to import apstools.devices.linkam_controllers.
2024-01-02T11:32:19.3975975Z Possible hints:
2024-01-02T11:32:19.3976878Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.3978317Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.3979393Z Failed to import apstools.devices.measComp_tc32_support.
2024-01-02T11:32:19.3980301Z Possible hints:
2024-01-02T11:32:19.3981338Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.3982753Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.3983877Z Failed to import apstools.devices.measComp_usb_ctr_support.
2024-01-02T11:32:19.3984833Z Possible hints:
2024-01-02T11:32:19.3985646Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.3986922Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.3988054Z Failed to import apstools.devices.motor_mixins.
2024-01-02T11:32:19.3988778Z Possible hints:
2024-01-02T11:32:19.3989628Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.3991043Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.3992118Z Failed to import apstools.devices.preamp_base.
2024-01-02T11:32:19.3993969Z Possible hints:
2024-01-02T11:32:19.3994974Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.3996122Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.3997265Z Failed to import apstools.devices.ptc10_controller.
2024-01-02T11:32:19.3997880Z Possible hints:
2024-01-02T11:32:19.3998359Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.3999155Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.3999797Z Failed to import apstools.devices.scaler_support.
2024-01-02T11:32:19.4000263Z Possible hints:
2024-01-02T11:32:19.4000871Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.4001597Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.4002188Z Failed to import apstools.devices.shutters.
2024-01-02T11:32:19.4002667Z Possible hints:
2024-01-02T11:32:19.4003185Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.4004143Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.4004876Z Failed to import apstools.devices.simulated_controllers.
2024-01-02T11:32:19.4005376Z Possible hints:
2024-01-02T11:32:19.4006039Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.4007173Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.4008279Z Failed to import apstools.devices.srs570_preamplifier.
2024-01-02T11:32:19.4009024Z Possible hints:
2024-01-02T11:32:19.4009807Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.4010508Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.4011129Z Failed to import apstools.devices.struck3820.
2024-01-02T11:32:19.4011661Z Possible hints:
2024-01-02T11:32:19.4012120Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.4012839Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.4013539Z Failed to import apstools.devices.synth_pseudo_voigt.
2024-01-02T11:32:19.4014210Z Possible hints:
2024-01-02T11:32:19.4014716Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.4015491Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.4016037Z Failed to import apstools.devices.xia_pf4.
2024-01-02T11:32:19.4016490Z Possible hints:
2024-01-02T11:32:19.4017035Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.4017713Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.4018319Z Failed to import apstools.devices.xia_slit.
2024-01-02T11:32:19.4018832Z Possible hints:
2024-01-02T11:32:19.4019304Z * AttributeError: module 'apstools' has no attribute 'devices'
2024-01-02T11:32:19.4020000Z * TypeError: unsupported operand type(s) for |: 'config' and 'normal'
2024-01-02T11:32:19.4023723Z myst v1.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
2024-01-02T11:32:19.5321073Z building [mo]: targets for 0 po files that are out of date
2024-01-02T11:32:19.5340744Z building [html]: targets for 47 source files that are out of date
2024-01-02T11:32:19.5356406Z updating environment: [new config] 47 added, 0 changed, 0 removed
2024-01-02T11:32:19.5357426Z reading sources... [  2%] api/_callbacks
...

[prjemian]

Is the root cause on lines such as these?

apstools/apstools/devices/labjack.py

Line 393 in d47c55a

analog_outputs = DCpt(make_analog_outputs(2), kind=(Kind.config | Kind.normal))

where: kind=(Kind.config | Kind.normal)

---

note the number of occurrences:

(bluesky_2024_1) prjemian@arf:~/.../BCDA-APS/apstools$ git grep config | grep normal
apstools/devices/labjack.py:    analog_outputs = DCpt(make_analog_outputs(2), kind=(Kind.config | Kind.normal))
apstools/devices/labjack.py:    analog_inputs = DCpt(make_analog_inputs(12), kind=(Kind.config | Kind.normal))
apstools/devices/labjack.py:    digital_ios = DCpt(make_digital_ios(16), kind=(Kind.config | Kind.normal))
apstools/devices/labjack.py:    analog_inputs = DCpt(make_analog_inputs(14), kind=(Kind.config | Kind.normal))
apstools/devices/labjack.py:    digital_ios = DCpt(make_digital_ios(23), kind=(Kind.config | Kind.normal))
apstools/devices/labjack.py:    analog_inputs = DCpt(make_analog_inputs(14), kind=(Kind.config | Kind.normal))
apstools/devices/labjack.py:    digital_ios = DCpt(make_digital_ios(23), kind=(Kind.config | Kind.normal))
apstools/devices/labjack.py:    analog_inputs = DCpt(make_analog_inputs(8), kind=(Kind.config | Kind.normal))
apstools/devices/labjack.py:    digital_ios = DCpt(make_digital_ios(20), kind=(Kind.config | Kind.normal))

[prjemian]

A suggested workaround is in one of the example notebooks (docs/source/examples/de_0_adsim_hdf5_basic.ipynb):

    "**Note**: Here, we assign the `kind` attribute by number `3`, a shorthand which is interpreted by ophyd as `ophyd.Kind.config | ophyd.Kind.normal`."
    "adsimdet.hdf1.kind = 3  # config | normal"

[prjemian]

One more Sphinx problem:

/home/prjemian/Documents/projects/BCDA-APS/apstools/apstools/devices/labjack.py:docstring of apstools.devices.labjack:22: ERROR: Unknown directive type "see".

[prjemian]

This error is odd now, given this ophyd source code usage:

ophyd/mca.py:    preset_real_time = Cpt(EpicsSignal, ".PRTM", kind=Kind.config | Kind.normal)
ophyd/tests/test_kind.py:    # Notice that it tacks 'config' on when you set the kind to 'normal'.
ophyd/tests/test_kind.py:    assert (Kind.normal | Kind.config) == B(name="b", kind=Kind.normal).kind
ophyd/tests/test_kind.py:    assert b.a_default.kind == (Kind.normal | Kind.config)
ophyd/tests/test_kind.py:    # kind value with Kind.config if said vlaue includes Kind.normal.

[prjemian]

Note, the problem now is with Sphinx:

In [1]: from ophyd import Kind

In [2]: Kind.config
Out[2]: <Kind.config: 2>

In [3]: Kind.normal
Out[3]: <Kind.normal: 1>

In [4]: Kind.config or Kind.normal
Out[4]: <Kind.config: 2>

In [5]: Kind.config + Kind.normal
Out[5]: 3

In [6]: f"{Kind.config or Kind.normal=}"
Out[6]: 'Kind.config or Kind.normal=<Kind.config: 2>'

In [7]: Kind.config | Kind.normal
Out[7]: <Kind.normal|config: 3>

[prjemian]

This alternative form does not raise a TypeError in Sphinx: 3 -- Make a symbol for it.