[Feature]: Refactor `src/pynwb/__init__.py` to ease readability and maintainance

[oruebel]

What would you like to see added to PyNWB?

src/pynwb/__init__.py currently works as intended, but it's structure is rather complex, which makes the package entrypoint harder to understand and maintain than necessary. At the moment, it combines several distinct responsibilities, including:

• public API re-exports
• version loading
• namespace/type-map bootstrap and caching
• resource/cache/submodule helpers
• backend selection
• NWBHDF5IO implementation
• convenience read helpers
• import-time module side effects

I propose to refactor src/pynwb/__init__.pyby moving the implementation of different features to dedicated modules, such that __init__.py can serve primarily as a thin public API facade rather than also containing these implementation details.

Is your feature request related to a problem?

The main issue is maintainability and clarity. Because several unrelated concerns are defined in src/pynwb/__init__.py, it is harder to:

• understand the package import flow
• reason about import-time side effects
• isolate bootstrap logic from public API concerns
• avoid circular-import and import-order risks
• make future changes confidently

This is especially relevant because pynwb is used both as a public import surface and as an internal dependency point in multiple modules.

What solution would you like?

I would propose an incremental refactor that keeps the external API stable while moving implementation details out of src/pynwb/__init__.py into internal modules organized by responsibility.

A possible split would be:

• move type-map / namespace logic into something like pynwb/_typemap.py, including:

  • get_type_map
  • get_manager
  • load_namespaces
  • available_namespaces
  • register_class
  • register_map
  • get_class
  • load_type_config
  • get_loaded_type_config
  • unload_type_config

• move bootstrap / cache / resource helpers into something like pynwb/_bootstrap.py or pynwb/_resources.py, including:

  • resource discovery
  • cache path handling
  • cache clearing
  • submodule initialization
  • core namespace loading
  • helpers such as __get_resources, __git_cmd, __clone_submodules, clear_cache_dir, and __load_core_namespace

• move read utility functionality into a dedicated io utility pynwb/io_utils.py including:

  • get_nwbfile_version
  • _get_backend
  • NWBHDF5IO
  • read_nwb

The goal would be for src/pynwb/__init__.py to remain as a compatibility facade that re-exports the existing public symbols. This would preserve the current public import surface from pynwb as well as existing import-time behavior in the first pass such that this would not require a breaking change. This would make the package entrypoint easier to follow without introducing intended user-facing behavior changes.

Subsequent refinements should then include, updating the internal imports to use the new internal modules directly instead of importing through pynwb.

This refactor would also simplify follow-up issues to investigate possible clean-up to deprecate or remove functionality as needed, however, that would be a separate issue.

Alternative considered: leaving the file as-is and only adding comments or section headers. That would help readability a bit, but it would not address the underlying coupling between unrelated responsibilities.

Do you have any interest in helping implement the feature?

Yes.

Code of Conduct

• I agree to follow this project's Code of Conduct
• Have you checked the Contributing document?
• Have you ensured this change was not already requested?