Log sys testing, starting to get "serious" about it..

[goodboy]

Another sloppy summary anyone?

---

This pull request introduces significant improvements and refactoring to the logging subsystem in tractor.log. The changes focus on enhancing logger naming behavior, improving sub-logger creation, and updating documentation and type annotations for clarity and maintainability. Additionally, new unit tests have been added to verify the correct logger name handling and module introspection. Below are the most important changes:

Logger Naming and Sub-Logger Improvements:

• Refactored get_logger() to use pkg_name (formerly _root_name) as the primary root logger identifier, deprecating the old parameter and warning users if it is used. The logger now introspects the caller's module when name is not provided, automatically generating sub-logger names based on the module context. This avoids duplication of the root package name in logger names and ensures sub-loggers are correctly nested and filtered. [1] [2] [3]
• Improved sub-logger creation logic to check for and warn about duplicate root package names or module names in the logger hierarchy, and to only create sub-loggers when appropriate.

Type Annotations and Documentation:

• Added or updated type annotations for logging format variables (LOG_FORMAT, DATE_FORMAT, BOLD_PALETTE) and clarified docstrings throughout the logging module, making the codebase more readable and maintainable. [1] [2] [3] [4] [5]
• Updated and expanded documentation in tractor/log.py to describe the enhanced logging system, its concurrency features, and usage patterns.

Testing Enhancements:

• Added a new test file tests/test_log_sys.py with unit tests to verify that root package names are not duplicated in logger names and that implicit module name detection for sub-loggers works as intended. This includes utilities for dynamically loading modules from file paths for testing purposes.

Internal Refactoring:

• Renamed the global root logger from log to _root_log within the logging module to clarify its role and avoid confusion with user-level loggers.
• Improved assertions to ensure that custom logging levels are properly attached as methods to the logger adapter.

---

links dump from getting to the current impl in this patch,

• The lurkerz want hipper logging.. #244
• https://stackoverflow.com/questions/1095543/get-name-of-calling-functions-module-in-python
• https://docs.python.org/3/library/inspect.html#inspect.Traceback
• https://docs.python.org/3/library/inspect.html#inspect.FrameInfo
• https://tutorialreference.com/python/examples/faq/python-how-to-get-details-type-file-line-number-of-exception
• https://stackoverflow.com/questions/15883526/how-is-the-name-variable-in-a-python-module-defined
• https://stackoverflow.com/questions/247770/how-to-retrieve-a-modules-path
• https://docs.python.org/3/library/modulefinder.html#modulefinder-example
• https://pymotw.com/2/inspect/index.html#module-inspect
• https://stackoverflow.com/questions/22232201/how-in-python-find-where-exception-was-raised
• https://docs.python.org/3/library/traceback.html#tracebackexception-objects
• https://docs.python.org/3/library/traceback.html#traceback.extract_tb
• https://docs.python.org/3/library/traceback.html#framesummary-objects
• https://docs.python.org/3/reference/datamodel.html#frame-objects
• https://stackoverflow.com/questions/60691759/add-information-to-every-log-message-in-python-logging/61830838#61830838
• https://stackoverflow.com/questions/7507825/where-is-a-complete-example-of-logging-config-dictconfig/7507842#7507842

[Copilot]

Pull Request Overview

This PR enhances the logging subsystem in the tractor library by adding improved introspection capabilities and type annotations. The changes introduce automatic module name detection for sub-loggers and add comprehensive testing for the logging functionality.

• Adds automatic caller module introspection when creating sub-loggers
• Improves type annotations for better code clarity and tooling support
• Implements comprehensive test coverage for logger creation and module name handling

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
tractor/log.py	Enhanced logging with auto-detection of caller modules, improved type annotations, and refactored parameter handling
tests/test_log_sys.py	New comprehensive test suite covering logger creation, module name detection, and package hierarchy handling

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Using stack() for caller introspection on every logger creation could impact performance in hot paths. Consider caching the introspection result or making this feature opt-in for performance-critical applications.

[Copilot]

This info-level log statement will be emitted every time a logger is created, potentially causing log noise. Consider using a debug level or removing this diagnostic logging in production code.

Suggested change

	log.info(
	log.debug(

[Copilot]

The getmodule() function can return None if the module cannot be determined. The type annotation indicates ModuleType but the subsequent None check suggests this is expected. The type annotation should be ModuleType | None.

Suggested change

	caller_mod: ModuleType = getmodule(caller_fi.frame)
	caller_mod: ModuleType | None = getmodule(caller_fi.frame)

[Copilot]

Accessing callstack[1] without checking the length could raise an IndexError if the call stack is unexpectedly shallow. Add a bounds check or handle the IndexError.

Suggested change

	caller_fi: FrameInfo = callstack[1]
	caller_mod: ModuleType = getmodule(caller_fi.frame)
	if caller_mod:
	# ?how is this `mod.__name__` defined?
	# -> well by how the mod is imported..
	# |_https://stackoverflow.com/a/15883682
	mod_name: str = caller_mod.__name__
	mod_pkg: str = caller_mod.__package__
	log.info(
	f'Generating sub-logger name,\n'
	f'{mod_pkg}.{mod_name}\n'
	)
	# if pkg_name in caller_mod.__package__:
	# from tractor.devx.debug import mk_pdb
	# mk_pdb().set_trace()
	if (
	pkg_name
	# and
	# pkg_name in mod_name
	):
	name = mod_name
	if len(callstack) > 1:
	caller_fi: FrameInfo = callstack[1]
	caller_mod: ModuleType = getmodule(caller_fi.frame)
	if caller_mod:
	# ?how is this `mod.__name__` defined?
	# -> well by how the mod is imported..
	# |_https://stackoverflow.com/a/15883682
	mod_name: str = caller_mod.__name__
	mod_pkg: str = caller_mod.__package__
	log.info(
	f'Generating sub-logger name,\n'
	f'{mod_pkg}.{mod_name}\n'
	)
	# if pkg_name in caller_mod.__package__:
	# from tractor.devx.debug import mk_pdb
	# mk_pdb().set_trace()
	if (
	pkg_name
	# and
	# pkg_name in mod_name
	):
	name = mod_name

[Copilot]

Commented-out debugging code should be removed from production code to keep the codebase clean.

Suggested change

	# if pkg_name in caller_mod.__package__:
	# from tractor.devx.debug import mk_pdb
	# mk_pdb().set_trace()

[Copilot]

Commented-out debugging code should be removed from production code to keep the codebase clean.

Suggested change

	# from tractor.devx.debug import mk_pdb
	# mk_pdb().set_trace()

[Copilot]

Spelling error: 'debuggin' should be 'debugging'.

Suggested change

	# XXX, lowlevel debuggin..
	# XXX, lowlevel debugging..

[Copilot]

Commented-out breakpoint should be removed from test code.

Suggested change

# breakpoint()