libtmux(feat[logging]): add NullHandler, lifecycle logging, clean up unused imports

why: Complete logging standards conformance per AGENTS.md conventions.
what:
- __init__.py: Add NullHandler to prevent "No handler found" warnings
- session.py: Add INFO logging for kill(), rename_session(), new_window()
  with structured extra (tmux_subcommand, tmux_session, tmux_target)
- pane.py: Add INFO logging for kill() and split() with structured extra
- neo.py: Add guarded DEBUG logging for fetch_objs() before/after query
- Remove unused logger imports from test/retry.py, test/environment.py,
  test/temporary.py, test/random.py, _internal/constants.py
- tests/test/test_random.py: Remove test_logger, test_logger_configured,
  and logger import; fix test_imports_coverage assertion

Author: tony

src/libtmux/__init__.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import logging
+
 from .__about__ import (
     __author__,
     __copyright__,
@@ -17,6 +19,8 @@
 from .session import Session
 from .window import Window
 
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
 __all__ = (
     "Pane",
     "Server",

src/libtmux/_internal/constants.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import io
-import logging
 import typing as t
 from dataclasses import dataclass, field
 
@@ -19,8 +18,6 @@
 TerminalFeatures = dict[str, list[str]]
 HookArray: TypeAlias = "dict[str, SparseArray[str]]"
 
-logger = logging.getLogger(__name__)
-
 
 @dataclass(repr=False)
 class ServerOptions(

src/libtmux/neo.py

@@ -5,6 +5,7 @@
 import dataclasses
 import functools
 import logging
+import shlex
 import typing as t
 from collections.abc import Iterable
 
@@ -305,12 +306,33 @@ def fetch_objs(
 
     tmux_cmds.append(f"-F{format_string}")
 
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(
+            "tmux list queried",
+            extra={
+                "tmux_subcommand": list_cmd,
+                "tmux_cmd": shlex.join([str(x) for x in tmux_cmds]),
+            },
+        )
+
     proc = tmux_cmd(*tmux_cmds)  # output
 
     if proc.stderr:
         raise exc.LibTmuxException(proc.stderr)
 
-    return [parse_output(line) for line in proc.stdout]
+    outputs = [parse_output(line) for line in proc.stdout]
+
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(
+            "tmux list parsed",
+            extra={
+                "tmux_subcommand": list_cmd,
+                "tmux_cmd": shlex.join([str(x) for x in tmux_cmds]),
+                "tmux_stdout_len": len(proc.stdout),
+            },
+        )
+
+    return outputs
 
 
 def fetch_obj(

src/libtmux/pane.py

@@ -567,6 +567,15 @@ def kill(
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
 
+        logger.info(
+            "pane killed",
+            extra={
+                "tmux_subcommand": "kill-pane",
+                "tmux_pane": self.pane_id,
+                "tmux_target": self.pane_id,
+            },
+        )
+
     """
     Commands ("climber"-helpers)
 
@@ -769,7 +778,20 @@ def split(
             zip(["pane_id"], pane_output.split(FORMAT_SEPARATOR), strict=False),
         )
 
-        return self.from_pane_id(server=self.server, pane_id=pane_formatters["pane_id"])
+        pane = self.from_pane_id(server=self.server, pane_id=pane_formatters["pane_id"])
+
+        logger.info(
+            "pane created",
+            extra={
+                "tmux_subcommand": "split-window",
+                "tmux_session": self.session.session_name,
+                "tmux_window": self.window.window_name,
+                "tmux_pane": pane.pane_id,
+                "tmux_target": target,
+            },
+        )
+
+        return pane
 
     """
     Commands (helpers)

src/libtmux/session.py

@@ -395,6 +395,15 @@ def kill(
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
 
+        logger.info(
+            "session killed",
+            extra={
+                "tmux_subcommand": "kill-session",
+                "tmux_session": self.session_name,
+                "tmux_target": self.session_id,
+            },
+        )
+
     def switch_client(self) -> Session:
         """Switch client to session.
 
@@ -430,6 +439,15 @@ def rename_session(self, new_name: str) -> Session:
 
         self.refresh()
 
+        logger.info(
+            "session renamed",
+            extra={
+                "tmux_subcommand": "rename-session",
+                "tmux_session": new_name,
+                "tmux_target": self.session_id,
+            },
+        )
+
         return self
 
     def new_window(
@@ -561,11 +579,23 @@ def new_window(
             zip(["window_id"], window_output.split(FORMAT_SEPARATOR), strict=False),
         )
 
-        return Window.from_window_id(
+        window = Window.from_window_id(
             server=self.server,
             window_id=window_formatters["window_id"],
         )
 
+        logger.info(
+            "window created",
+            extra={
+                "tmux_subcommand": "new-window",
+                "tmux_session": self.session_name,
+                "tmux_window": window_name,
+                "tmux_target": target,
+            },
+        )
+
+        return window
+
     def kill_window(self, target_window: str | None = None) -> None:
         """Close a tmux window, and all panes inside it, ``$ tmux kill-window``.
 

src/libtmux/test/environment.py

@@ -2,12 +2,9 @@
 
 from __future__ import annotations
 
-import logging
 import os
 import typing as t
 
-logger = logging.getLogger(__name__)
-
 if t.TYPE_CHECKING:
     import sys
     import types

src/libtmux/test/random.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations  # pragma: no cover
 
-import logging
 import random
 import typing as t  # pragma: no cover
 
@@ -22,9 +21,6 @@
         pass  # pragma: no cover
 
 
-logger = logging.getLogger(__name__)
-
-
 class RandomStrSequence:
     """Factory to generate random string."""
 

src/libtmux/test/retry.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import logging
 import time
 import typing as t
 
@@ -12,8 +11,6 @@
     RETRY_TIMEOUT_SECONDS,
 )
 
-logger = logging.getLogger(__name__)
-
 if t.TYPE_CHECKING:
     import sys
     from collections.abc import Callable

src/libtmux/test/temporary.py

@@ -3,13 +3,10 @@
 from __future__ import annotations
 
 import contextlib
-import logging
 import typing as t
 
 from libtmux.test.random import get_test_session_name, get_test_window_name
 
-logger = logging.getLogger(__name__)
-
 if t.TYPE_CHECKING:
     import sys
     from collections.abc import Generator

tests/test/test_random.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import logging
 import string
 import sys
 import typing as t
@@ -14,7 +13,6 @@
     RandomStrSequence,
     get_test_session_name,
     get_test_window_name,
-    logger,
     namer,
 )
 
@@ -25,12 +23,6 @@
     from libtmux.session import Session
 
 
-def test_logger() -> None:
-    """Test that the logger is properly configured."""
-    assert isinstance(logger, logging.Logger)
-    assert logger.name == "libtmux.test.random"
-
-
 def test_random_str_sequence_default() -> None:
     """Test RandomStrSequence with default characters."""
     rng = RandomStrSequence()
@@ -295,20 +287,6 @@ def test_random_str_sequence_insufficient_characters() -> None:
         next(rng)
 
 
-def test_logger_configured(caplog: pytest.LogCaptureFixture) -> None:
-    """Test that the logger in random.py is properly configured."""
-    # Verify the logger is set up with the correct name
-    assert logger.name == "libtmux.test.random"
-
-    # Test that the logger functions properly
-    with caplog.at_level(logging.DEBUG):
-        logger.debug("Test debug message")
-        logger.info("Test info message")
-
-        assert "Test debug message" in caplog.text
-        assert "Test info message" in caplog.text
-
-
 def test_next_method_directly() -> None:
     """Test directly calling __next__ method on RandomStrSequence."""
     rng = RandomStrSequence()
@@ -424,7 +402,6 @@ def test_imports_coverage() -> None:
     # This test simply ensures the imports are covered
     from libtmux.test import random
 
-    assert hasattr(random, "logging")
     assert hasattr(random, "random")
     assert hasattr(random, "t")
     assert hasattr(random, "TEST_SESSION_PREFIX")