1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
Changelog
=========
All notable changes to ``tiered-debug`` will be documented in this file.
The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,
and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
[1.4.0] - 2025-10-07
--------------------
Changes
~~~~~~~
A bit of a reversion from 1.3.1 with regards to default logger kwargs, but with a better approach.
- Updated version to 1.4.0 for release.
- Configure ``log``, ``lv1``, ``lv2``, ``lv3``, ``lv4``, and ``lv5`` methods in ``_base.py`` to use default ``None`` value for ``exc_info``, ``stack_info``, ``stacklevel``, and ``extra``. If ``None`` is provided, the logging module will apply its own defaults (``exc_info=False``, ``stack_info=False``, ``extra={}``, and then set ``stacklevel`` to the `effective` stack level).
- Pruned unused import in ``docs/conf.py``.
- Updated ``debug.py`` to use ``Literal[1, 2, 3, 4, 5]`` for ``begin`` and ``end`` parameters in ``begin_end`` decorator in order to match the typing in ``_base.py``. This cleans up MyPy and other linter warnings.
- Updated ``test_base.py`` tests ``test_log_with_default_stacklevel`` and ``test_log_levels`` to collect the logger name from the fixture rather than hardcoding an expected value.
All tests passing. Tested pre-release in a sample project and everything looks good.
[1.3.1] - 2025-10-03
--------------------
Changes
~~~~~~~
- Updated version to 1.3.1 for patch release.
- Updated ``log``, ``lv1``, ``lv2``, ``lv3``, ``lv4``, and ``lv5`` methods in ``_base.py`` to use proper default values for ``exc_info`` (``False``), ``stack_info`` (``False``), and ``stacklevel`` (``1``) instead of ``None``.
- Corrected tests ``test_log_with_default_stacklevel`` and ``test_log_levels`` to verify that the record logger name matches the logger name assigned in the fixture, rather than a hardcoded expected value.
- Corrected ``test_add_handler`` and ``test_log_with_default_stacklevel`` in ``test_base.py`` to add ``caplog.set_level(logging.DEBUG)`` for proper DEBUG log capture. Kudos to @schoekek for identifying the issue and supplying the fix in #6. The nice thing is that it's not a code change, but an update to how testing is done.
- Discovered that ReadTheDocs builds were failing due to conditional resulting in ``html_theme`` being set to ``None`` when building on ReadTheDocs. Updated ``docs/conf.py`` to always set ``html_theme`` to ``sphinx_rtd_theme``, at least for now.
All tests passing.
[1.3.0] - 2025-04-21
--------------------
Added
~~~~~
- Added ``exc_info``, ``stack_info``, and ``extra`` keyword arguments to ``log``, ``lv1``, ``lv2``, ``lv3``, ``lv4``, and ``lv5`` methods in ``TieredDebug``, following Python ``logging`` module specifications.
- ``log`` method now ensures ``extra`` is an empty dictionary if ``None`` is provided.
- Standardized all docstrings in ``_base.py`` to Google-style format with line length limits (code and docstrings: soft 80, hard 88; Args/Returns/Raises definitions: soft 72, hard 80; Examples: soft 68, hard 76).
- Added doctests to ``_base.py`` for key methods to demonstrate usage and validate behavior.
- Standardized all docstrings in ``debug.py`` to Google-style format with line length limits (code and docstrings: soft 80, hard 88; Args/Returns/Raises definitions: soft 72, hard 80; Examples: soft 68, hard 76).
- Added doctests to ``debug.py`` with line length limits (soft 68, hard 76) for decorator and global instance.
- Standardized module docstring in ``__init__.py`` to Google-style format with doctests and line length limits (code and docstrings: soft 80, hard 88; Args/Returns/Raises definitions: soft 72, hard 80; Examples: soft 68, hard 76).
- Updated ``docs/conf.py`` for tiered-debug with Google-style docstring, doctests, direct metadata imports enabled by module installation, and line length limits (code and docstrings: soft 80, hard 88; Args/Returns/Raises definitions: soft 72, hard 80; Examples: soft 68, hard 76).
- Updated ``.readthedocs.yaml`` to configure ReadTheDocs build with module installation, Sphinx configuration, and dependency installation via ``docs/requirements.txt``.
- Added ``docs/requirements.txt`` with Sphinx dependencies for ReadTheDocs documentation builds.
- Enhanced tests in ``test_base.py`` to cover ``exc_info``, ``stack_info``, and ``extra`` parameters in ``TieredDebug`` logging methods, including edge cases and performance.
- Added ``__version__``, ``__author__``, and ``__copyright__`` to ``__all__`` in ``__init__.py`` to export metadata.
- Added ``W0622`` to pylint disable in ``docs/conf.py`` to suppress redefined built-in warnings for ``copyright``.
- Fixed ``test_log_with_extra`` and ``test_log_all_parameters_combined`` in ``test_base.py`` to check log record attributes for ``extra`` metadata due to ``pytest.ini`` log format.
- Fixed ``test_log_with_stack_info`` and ``test_log_all_parameters_combined`` in ``test_base.py`` to check for correct stack trace prefix across Python 3.8-3.13.
- Updated ``test_log_with_invalid_extra_type`` in ``test_base.py`` to expect TypeError for invalid ``extra`` types, aligning with ``_base.py`` validation.
- Renamed ``stklvl`` to ``stacklevel`` and reordered keyword arguments (``exc_info``, ``stack_info``, ``stacklevel``, ``extra``) in ``_base.py`` methods to match ``logging.Logger.debug``.
- Updated ``debug.py`` to use ``stacklevel`` and enhanced ``begin_end`` decorator to accept ``stacklevel`` and ``extra``, defaulting to updating only ``stacklevel``.
- Updated ``test_base.py`` to use ``stacklevel``, reordered keyword arguments, and added tests for ``*args`` message formatting support in ``_base.py`` methods.
- Fixed ``test_select_frame_getter_non_cpython`` in ``test_base.py`` to correctly call ``inspect.currentframe()`` without arguments.
- Updated ``debug.py`` to restore ``begin`` and ``end`` arguments for ``begin_end`` decorator, retaining ``stacklevel`` and ``extra``.
- Updated ``test_debug.py`` to test ``begin``, ``end``, ``stacklevel``, and ``extra`` in ``begin_end`` decorator, restoring original test structure.
- Corrected ``test_debug.py`` to ensure all tests pass, as updated by user.
- Updated ``index.rst`` to highlight ``stacklevel`` and ``extra`` and clarify ``debug.py``’s role.
- Updated ``usage.rst`` to include ``stacklevel``, ``extra``, ``*args``, correct ``set_level``, align log output with ``pytest.ini``, and enhance Elasticsearch handler example.
- Updated ``usage.rst`` formatters to include ``extra`` fields (``%(context)s``, ``%(module)s``) in log output for ``TieredDebug``, ``debug.py``, Elasticsearch, and pytest examples.
- Re-rendered ``usage.rst`` Python code blocks to fit within a 90-character hard limit to avoid side-scrolling.
- Corrected spacing in ``usage.rst`` bash code block to improve visibility in rendered documentation, as updated by user.
[1.2.1] - 2025-04-17
--------------------
Added
~~~~~
- Unit tests for ``debug.py`` in ``test_debug.py``.
Changed
~~~~~~~
- Fixed unit tests in ``test_base.py`` where setting the log level for caplog was required.
[1.2.0] - 2025-04-17
--------------------
Added
~~~~~
- Instance-level logger (``self._logger``) in ``TieredDebug`` for flexible configuration.
- ``add_handler`` method to attach handlers at ``logging.DEBUG`` level, with info message for duplicates.
- Cached ``_select_frame_getter`` to use ``sys._getframe`` in CPython and ``inspect.currentframe`` elsewhere.
- Sphinx autodoc docstrings for all classes and methods.
- Support for custom logger names via ``logger_name`` parameter in ``TieredDebug.__init__``.
Changed
~~~~~~~
- Removed environment variable support (``TIERED_DEBUG_LEVEL``, ``TIERED_STACK_LEVEL``).
- Updated ``check_val`` to handle ``TypeError`` and ``ValueError`` with specific error logging.
- Improved error handling and validation throughout ``TieredDebug``.
[1.1.0] - 2025-04-15
--------------------
Added
~~~~~
- Initial ``TieredDebug`` class with tiered logging levels (1-5).
- ``begin_end`` decorator in ``debug.py`` for logging function call boundaries.
- Environment variable support for setting debug and stack levels.
- Basic unit tests in ``test_base.py``.
[1.0.0] - 2025-03-31
--------------------
Added
~~~~~
- Initial release of ``tiered_debug`` module.
- ``TieredDebug`` class with module-level logger.
- Support for debug levels 1-5 and stack levels 1-9.
- ``debug.py`` sample module with global ``debug`` instance.
|
