python bindings: add exception hierarchy

Replace the connect_err/discover_err globals and %exception shims with
a proper exception hierarchy in libnvme/_exceptions.py:

  NvmeError (base, .errno + .message)
  ├── ConnectError
  ├── DisconnectError
  ├── DiscoverError
  └── NotConnectedError (.errno is always 0)

Exceptions are imported into the nvme module namespace at init time
via %init %{} and re-exported via %pythoncode so callers can use
nvme.ConnectError etc. directly.

raise_nvme(cls, err) sets the exception from C; raise_not_connected()
handles the no-errno case. SWIG_fail cannot be used inside %extend
function bodies (they are extracted into SWIGINTERN helpers where the
fail: label is absent), so minimal %exception blocks propagate any
pending exception set by the helper back into the wrapper.

Also rename supported_log_pages() to get_supported_log_pages(), which
now raises NvmeError on failure instead of returning None.

Update discover-loop.py and README.md to match the new API.

Signed-off-by: Martin Belanger <[email protected]>
Assisted-by: Claude Sonnet 4.6 <[email protected]>

Author: Martin Belanger

libnvme/examples/discover-loop.py

@@ -23,24 +23,24 @@ def discover(ctx, host, ctrl, iteration):
 
     try:
         ctrl.connect(host)
-    except Exception as e:
+    except nvme.ConnectError as e:
         print(f'Failed to connect: {e}')
         return
 
     print(f'{ctrl.name} connected to {ctrl.subsystem}')
 
-    slp = ctrl.supported_log_pages()
     try:
+        slp = ctrl.get_supported_log_pages()
         dlp_supp_opts = slp[nvme.NVME_LOG_LID_DISCOVERY] >> 16
-    except (TypeError, IndexError):
+    except (nvme.NvmeError, IndexError, TypeError):
         dlp_supp_opts = 0
 
     print(f"LID {nvme.NVME_LOG_LID_DISCOVERY}h (Discovery), supports: {disc_supp_str(dlp_supp_opts)}")
 
     try:
         lsp = nvme.NVMF_LOG_DISC_LSP_PLEO if dlp_supp_opts & nvme.NVMF_LOG_DISC_LID_PLEOS else 0
         disc_log = ctrl.discover(lsp=lsp)
-    except Exception as e:
+    except nvme.DiscoverError as e:
         print(f'Failed to discover: {e}')
         return
 
@@ -52,7 +52,7 @@ def discover(ctx, host, ctrl, iteration):
             continue
         print(f'{iteration}: {dlpe["subtype"]} {dlpe["subnqn"]}')
         with nvme.Ctrl(ctx, subsysnqn=dlpe['subnqn'], transport=dlpe['trtype'], traddr=dlpe['traddr'], trsvcid=dlpe['trsvcid']) as new_ctrl:
-            discover(host, new_ctrl, iteration + 1)
+            discover(ctx, host, new_ctrl, iteration + 1)
 
 ctx = nvme.GlobalCtx()
 host = nvme.Host(ctx)

libnvme/libnvme/README.md

@@ -3,6 +3,84 @@
 
 We use [SWIG](http://www.swig.org/) to generate Python bindings for libnvme.
 
+## Classes
+
+Five classes are exposed, matching the NVMe topology:
+
+| Class | Description |
+|---|---|
+| `nvme.GlobalCtx` | Root context. Manages the NVMe device tree and logging. Create one instance per process. |
+| `nvme.Host` | Represents the local host: NQN, host ID, optional symbolic name (symname). |
+| `nvme.Subsystem` | An NVMe subsystem discovered under a host. |
+| `nvme.Ctrl` | An NVMe controller (physical or fabrics). Constructed from a configuration dict. |
+| `nvme.Namespace` | A namespace under a controller. |
+
+All five classes support the context manager protocol (`with` statement) for automatic cleanup.
+
+Topology can be traversed with iterators: `ctx.hosts()`, `host.subsystems()`,
+`subsystem.controllers()`, `ctrl.namespaces()`.
+
+### Ctrl configuration dict
+
+`nvme.Ctrl(ctx, cfg)` accepts a flat dict. Common keys:
+
+| Key | Description |
+|---|---|
+| `subsysnqn` | Subsystem NQN (required) |
+| `transport` | Transport type: `pcie`, `tcp`, `rdma`, `fc`, `loop`, `apple-nvme` (required) |
+| `traddr` | Target address |
+| `trsvcid` | Target service ID (port) |
+| `host_iface` | Local network interface to use |
+| `hostnqn` | Override the host NQN |
+| `hostid` | Override the host ID |
+| `hdr_digest` | Enable header digests (`bool`) |
+| `data_digest` | Enable data digests (`bool`) |
+| `persistent` | Keep the connection alive after the object is released (`bool`) |
+
+### Key Ctrl methods and properties
+
+| Name | Type | Description |
+|---|---|---|
+| `connected` | property | `True` if the controller is currently connected |
+| `registration_supported` | property | `True` if the target supports explicit host registration |
+| `name` | property | Kernel device name (e.g. `nvme0`), or `None` if not connected |
+| `transport`, `traddr`, `trsvcid` | properties | Connection parameters |
+| `connect(host)` | method | Establish the kernel connection |
+| `disconnect()` | method | Tear down the connection |
+| `discover()` | method | Retrieve the discovery log page (discovery controllers only) |
+| `get_supported_log_pages()` | method | Fetch the Supported Log Pages log |
+| `rescan()` | method | Rescan the controller and refresh its namespace list |
+| `registration_control(tas)` | method | Register / deregister / update with the DIM service |
+
+## Exceptions
+
+All libnvme errors are reported through a small exception hierarchy:
+
+```
+NvmeError                  base class — carries .errno (int) and .message (str)
+├── ConnectError            raised by ctrl.connect()
+├── DisconnectError         raised by ctrl.disconnect()
+├── DiscoverError           raised by ctrl.discover()
+└── NotConnectedError       raised when an operation requires a connected controller
+                            (.errno is always 0)
+```
+
+Import them directly from the `nvme` module:
+
+```python
+from libnvme import nvme
+
+try:
+    ctrl.connect(host)
+except nvme.ConnectError as e:
+    print(f"errno={e.errno}, message={e.message}")
+except nvme.NotConnectedError:
+    print("not connected")
+```
+
+`NvmeError` is also raised by `get_supported_log_pages()` and
+`registration_control()` on failure.
+
 ## How to use
 
 ```python
@@ -19,59 +97,75 @@ def disc_supp_str(dlp_supp_opts):
     }
     return [txt for msk, txt in bitmap.items() if dlp_supp_opts & msk]
 
-ctx = nvme.global_ctx()     # This is a singleton
-ctx.log_level('debug')      # Optional: extra debug info
+ctx = nvme.GlobalCtx()
+ctx.log_level('debug')  # Optional: extra debug info
 
-host = nvme.host(ctx)       # This "may be" a singleton.
-subsysnqn  = [string]       # e.g. nvme.NVME_DISC_SUBSYS_NAME, ...
-transport  = [string]       # One of: 'tcp', 'rdma', 'fc', 'loop'.
-traddr     = [IPv4 or IPv6] # e.g. '192.168.10.10', 'fd2e:853b:3cad:e135:506a:65ee:29f2:1b18', ...
-trsvcid    = [string]		# e.g. '8009', '4420', ...
-host_iface = [interface]    # e.g. 'eth1', ens256', ...
-ctrl = nvme.ctrl(ctx, subsysnqn=subsysnqn, transport=transport, traddr=traddr, trsvcid=trsvcid, host_iface=host_iface)
+host = nvme.Host(ctx)
+
+ctrl = nvme.Ctrl(ctx, {
+    'subsysnqn':  '...',    # e.g. nvme.NVME_DISC_SUBSYS_NAME
+    'transport':  '...',    # One of: 'tcp', 'rdma', 'fc', 'loop'
+    'traddr':     '...',    # e.g. '192.168.10.10'
+    'trsvcid':    '...',    # e.g. '8009', '4420'
+    'host_iface': '...',    # e.g. 'eth1', 'ens256'
+    'hdr_digest': True,     # Enable header digests
+    'data_digest': False,   # Disable data digests
+})
 
 try:
-    cfg = {
-        'hdr_digest': True,   # Enable header digests
-        'data_digest': False, # Disable data digests       
-    }
-    ctrl.connect(host, cfg)
+    ctrl.connect(host)
     print(f"connected to {ctrl.name} subsys {ctrl.subsystem.name}")
-except Exception as e:
+except nvme.ConnectError as e:
     sys.exit(f'Failed to connect: {e}')
 
-supported_log_pages = ctrl.supported_log_pages()
 try:
-    # Get the supported options for the Get Discovery Log Page command
-    dlp_supp_opts = supported_log_pages[nvme.NVME_LOG_LID_DISCOVERY] >> 16
-except (TypeError, IndexError):
+    slp = ctrl.get_supported_log_pages()
+    dlp_supp_opts = slp[nvme.NVME_LOG_LID_DISCOVERY] >> 16
+except (nvme.NvmeError, IndexError, TypeError):
     dlp_supp_opts = 0
 
 print(f"LID {nvme.NVME_LOG_LID_DISCOVERY:02x}h (Discovery), supports: {disc_supp_str(dlp_supp_opts)}")
+
 try:
     lsp = nvme.NVMF_LOG_DISC_LSP_PLEO if dlp_supp_opts & nvme.NVMF_LOG_DISC_LID_PLEOS else 0
     log_pages = ctrl.discover(lsp=lsp)
     print(pprint.pformat(log_pages))
-except Exception as e:
+except nvme.DiscoverError as e:
     sys.exit(f'Failed to retrieve log pages: {e}')
 
 try:
     ctrl.disconnect()
-except Exception as e:
+except nvme.DisconnectError as e:
     sys.exit(f'Failed to disconnect: {e}')
-
-ctrl = None
-host = None
-ctx = None
 ```
 
-## Testing PyPI package
+## Installation
 
-Use the following command to test installing the package from TestPyPI before publishing to the official PyPI registry.
+The package is available from most Linux distribution repositories and on PyPI.
+
+**From your distribution (recommended):**
 
 ```bash
-pip install \
-  --index-url https://test.pypi.org/simple/ \
-  --extra-index-url https://pypi.org/simple/ \
-  libnvme==[libnvme-version]
+# Debian / Ubuntu
+apt-get install python3-libnvme
+
+# Fedora
+dnf install python3-libnvme
+
+# openSUSE
+zypper install python3-libnvme
 ```
+
+**From PyPI:**
+
+```bash
+pip install libnvme
+```
+
+> **Note:** The PyPI package is a source distribution — it builds libnvme and
+> the Python bindings directly on your machine. Build dependencies (a C
+> compiler, Meson, Ninja, SWIG, and the libnvme C dependencies) must be
+> present. If any are missing, `pip install` will fail. Installing from your
+> distribution package manager is generally easier and avoids this requirement.
+
+See [PUBLISHING.md](PUBLISHING.md) for instructions on testing and publishing new releases.

libnvme/libnvme/_exceptions.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# This file is part of libnvme.
+# Copyright (c) 2026, Dell Technologies Inc. or its subsidiaries.
+# Authors: Martin Belanger <[email protected]>
+
+
+class NvmeError(Exception):
+    """Base class for all libnvme errors.
+
+    Attributes:
+        errno:   OS error number (negative values are stored as-is).
+        message: Human-readable description from libnvme_errno_to_string().
+    """
+    def __init__(self, errno, message):
+        self.errno = errno
+        self.message = message
+        super().__init__(f"[Errno {errno}] {message}")
+
+
+class ConnectError(NvmeError):
+    """Raised when a controller connection attempt fails."""
+
+
+class DisconnectError(NvmeError):
+    """Raised when a controller disconnect attempt fails."""
+
+
+class DiscoverError(NvmeError):
+    """Raised when a discovery log retrieval fails."""
+
+
+class NotConnectedError(NvmeError):
+    """Raised when an operation requires a connected controller but none exists."""
+    def __init__(self, message="Not connected"):
+        super().__init__(0, message)

libnvme/libnvme/meson.build

@@ -60,19 +60,22 @@ if want_python
         },
     )
 
-    # Little hack to copy file __init__.py to the build directory. 
-    # This is needed to create the proper directory layout to run the tests.
-    # It's a hack because we don't really "configure" file __init__.py and we
-    # could simply install directly from the source tree with:
-    #   python3.install_sources(['__init__.py', ], pure:false, subdir:'libnvme')
-    # However, since we need __init__.py in the build directory to run the tests
-    # we resort to this hack to copy it.
-    configure_file(
-        input:  '__init__.py', 
-        output: '__init__.py',
-        configuration: conf,
-        install_dir: python3.get_install_dir(pure: false, subdir: 'libnvme'),
-    )
+    # Little hack to copy a list of files [__init__.py, etc.] to the build
+    # directory. This is needed to create the proper directory layout to run the
+    # tests. It's a hack because we don't really "configure" files and we could
+    # simply install directly from the source tree with:
+    #   python3.install_sources(files, pure:false, subdir:'libnvme')
+    # However, since we need these files in the build directory to run the tests
+    # we resort to this hack to copy them.
+    files = ['__init__.py', '_exceptions.py']
+    foreach file: files
+        configure_file(
+            input:  file,
+            output: file,
+            configuration: conf,
+            install_dir: python3.get_install_dir(pure: false, subdir: 'libnvme'),
+        )
+    endforeach
 
     # Set the PYTHONPATH so that we can run the 
     # tests directly from the build directory.