ni / ni/nimi-python

Consider redefining __module__ when re-exporting types in __init__.py

Open
#1,433 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
128
Forks
110
Avg merge
5d 14h
Merged PRs (30d)
10

Description

Description of issue

In __init__.py, we re-export the types contained in the module like:

from niscope.errors import DriverWarning  # noqa: F401
from niscope.errors import Error  # noqa: F401
from niscope.session import Session  # noqa: F401

from niscope.waveform_info import WaveformInfo  # noqa: F401

from niscope.waveform_info import struct_niScope_wfmInfo  # noqa: F401

This puts the types at package level, which is good. It allows users to do:

>>> import niscope
>>> niscope.Session

..even though Session is defined in session module. But repr() still includes the module:

>>> import niscope
>>> niscope.Session
<class 'niscope.session.Session'>
>>> niscope.WaveformInfo
<class 'niscope.waveform_info.WaveformInfo'>
>>> import nidigital
>>> nidigital.HistoryRAMCycleInformation
<class 'nidigital.history_ram_cycle_information.HistoryRAMCycleInformation'>

We should consider redefining __module__. Advantages of doing so (Copied from here):

  1. We tell clients to from nigitial import HistoryRAMCycleInformation, guaranteeing that this will work (up until we make an API breaking change). It logically follows the __module__ for that type would be nidigital.
  2. We would avoid exposing an implementation detail. If we moved where the class was defined are we sure we aren't going to break someone? Someone JSON-ifying the data, or pickling it? Setting __module__ to nidgitial means we can move the class as much as we want without worrying about exposing implementation details.
  3. This has the added bonus of "using" the class so no more suppressing F401 in __init__.py.
  4. Lastly, the new way leads to shorter strings.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing generated/niscope/niscope/init.py and the re-exported types in the linked modules, then compare the shown repr() behavior for niscope and nidigital. Determine whether package-level types should report the package as their module, with the decision covering repr(), pickling, and future relocation of the implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.