feat: Add LogLevel enum with QUIET alias support #806

Granine · 2025-11-09T21:22:49Z

What does this add?

This PR adds support for "QUIET" as a valid string alias for the logging_setting parameter, complementing the existing LogLevel.QUIET enum. This improves developer experience by matching industry conventions (like git --quiet, pip --quiet) while maintaining full backward compatibility.

Problem: Users expected logging_setting="QUIET" to work based on industry conventions, but only "NONE" was accepted as a string, causing confusion.

Solution: Added "QUIET" to the allowable string values, mapping to the same log level as "NONE". Both the enum (LogLevel.QUIET) and string ("QUIET") now work seamlessly.

Type of changes

Please check the type of change your PR introduces:

Background context

The LogLevel enum was introduced to provide IDE autocomplete support and better developer experience. However, only the enum LogLevel.QUIET worked, not the string "QUIET". This created an inconsistency where users familiar with Unix tools (--quiet flag) couldn't use the string form they expected.

This PR resolves issue #805 by adding string "QUIET" support alongside the enum.

Checklist for Author

Code Quality

Code follows the project's style guidelines (run ruff check . and ruff format .)
Code is commented, particularly in hard-to-understand areas

Testing

Tests added/updated and pass locally (pytest tests)
Test coverage maintained (24 new tests, 51/51 pass, 100% success rate)

Documentation

Documentation updated if needed (docstrings enhanced with examples)

Git & PR Management

PR title clearly describes the change

Breaking Changes

Breaking changes are documented (N/A - no breaking changes)
Migration guide provided in documentation (N/A - backward compatible)

Final Product

Usage Examples

All of these methods now work to suppress logs:

import railtracks as rt

# Method 1: Enum QUIET (recommended - IDE autocomplete)
with rt.Session(logging_setting=rt.LogLevel.QUIET):
    result = await rt.call(agent, "Hello")

# Method 2: String "QUIET" (NEW! - matches Unix conventions)
with rt.Session(logging_setting="QUIET"):
    result = await rt.call(agent, "Hello")

# Method 3: Enum NONE (existing)
with rt.Session(logging_setting=rt.LogLevel.NONE):
    result = await rt.call(agent, "Hello")

# Method 4: String "NONE" (existing)
with rt.Session(logging_setting="NONE"):
    result = await rt.call(agent, "Hello")

What Changed

Component	Before	After
String `"QUIET"`	❌ ValueError	✅ Accepted
Enum `LogLevel.QUIET`	✅ Works	✅ Works
Backward compatibility	✅ All strings work	✅ All strings work
Type hints	`Literal["DEBUG", "INFO", ..., "NONE"]`	`Literal["DEBUG", "INFO", ..., "NONE", "QUIET"]`

- Add LogLevel enum with DEBUG, INFO, WARNING, ERROR, CRITICAL, NONE, QUIET - QUIET is an enum alias for NONE (both resolve to 'NONE' value) - Add string 'QUIET' as valid logging_setting value (alias for 'NONE') - Update type hints to include 'QUIET' in AllowableLogLevels - Update Session and LogLevel docstrings with examples - Add 24 comprehensive tests in test_loglevel.py - Fix 4 broken tests in test_session.py (invalid log levels) - Maintain backward compatibility with string values - Improve developer experience with IDE autocomplete Benefits: - IDE autocomplete support via LogLevel.XXX constants - Matches industry conventions (git --quiet, pip --quiet) - Type safety while maintaining string backward compatibility - Clear self-documenting API

- Remove unused imports and variables - Fix comparison operators (use 'is' for True/None checks) - Format code with ruff - All tests still pass (51/51)

- Fix whitespace and line breaks in docstrings - Format AllowableLogLevels type hint for readability - Consistent quote style in string comparisons

After team discussion, decided to stick with NONE only. Changes: - Removed LogLevel.QUIET enum value - Removed 'QUIET' from AllowableLogLevels type hint - Removed 'QUIET' from str_to_log_level mapping - Updated Session docstring to remove QUIET references - Removed 5 QUIET-related tests (19 tests remain, down from 24) - Tests now validate that 'QUIET' is invalid All tests pass: 46/46 (27 session + 19 loglevel)

soulFood5632

Some minor comments around docstring and where some of the tests live.

soulFood5632 · 2025-11-13T19:53:28Z

packages/railtracks/src/railtracks/utils/logging/config.py

+        NONE: Suppress all logging output
+
+    Examples:
+        Using LogLevel constants (recommended - enables IDE autocomplete):


I would get rid of the (recomonded line becuase lots of tools like vscode have autocomplete for literals as well

soulFood5632 · 2025-11-13T19:57:36Z

packages/railtracks/src/railtracks/utils/config.py

+                f"logging_setting must be one of {list(str_to_log_level.keys())}, got {value}"
            )
-        self._logging_setting: AllowableLogLevels = value
+        self._logging_setting: AllowableLogLevels = str_value


This is a bit of nitpick, but typing wise the self._logging_setting can only be a string so we should be typing this properly here

soulFood5632 · 2025-11-13T19:58:19Z

packages/railtracks/src/railtracks/_session.py

-        logging_setting (AllowableLogLevels, optional): The setting for the level of logging you would like to have. This will override the module-level logging settings for the duration of this session.
+        logging_setting (LogLevel | str, optional): Controls log verbosity. This will override the module-level logging settings for the duration of this session.
+
+            Use LogLevel constants (recommended - enables IDE autocomplete):


same as above, get rid of the line "(recomonded - enables IDE autocomplete)"

soulFood5632 · 2025-11-13T20:01:11Z

packages/railtracks/tests/unit_tests/test_loglevel.py

+# ================ END Edge Cases ===============
+
+
+if __name__ == "__main__":


I would delete this line for consitency sake

soulFood5632 · 2025-11-13T20:02:12Z

packages/railtracks/tests/unit_tests/test_loglevel.py

+# ================ END Documentation Tests ===============
+
+
+# ================= START Integration Tests ===============


I would move this test to either the Session unit tests or integration folder

soulFood5632 · 2025-11-13T20:02:24Z

packages/railtracks/tests/unit_tests/test_loglevel.py

+    assert str(rt.LogLevel.NONE) == "NONE"
+
+
+def test_session_with_none_logging_uses_global_config(mock_session_dependencies):


Granine requested review from Amir-R25 and soulFood5632 as code owners November 9, 2025 21:22

Granine linked an issue Nov 9, 2025 that may be closed by this pull request

[Feature] Add LogLevel Enum Support #805

Open

9 tasks

Granine added 3 commits November 9, 2025 16:26

style: Fix linting issues in test files

27a6e7a

- Remove unused imports and variables - Fix comparison operators (use 'is' for True/None checks) - Format code with ruff - All tests still pass (51/51)

style: Fix code formatting

d36f43f

- Fix whitespace and line breaks in docstrings - Format AllowableLogLevels type hint for readability - Consistent quote style in string comparisons

soulFood5632 requested changes Nov 13, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add LogLevel enum with QUIET alias support #806

feat: Add LogLevel enum with QUIET alias support #806

Uh oh!

Granine commented Nov 9, 2025

Uh oh!

soulFood5632 left a comment

Uh oh!

soulFood5632 Nov 13, 2025

Uh oh!

soulFood5632 Nov 13, 2025

Uh oh!

soulFood5632 Nov 13, 2025

Uh oh!

soulFood5632 Nov 13, 2025

Uh oh!

soulFood5632 Nov 13, 2025

Uh oh!

soulFood5632 Nov 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		# ================ END Edge Cases ===============


		if __name__ == "__main__":

		# ================ END Documentation Tests ===============


		# ================= START Integration Tests ===============

		assert str(rt.LogLevel.NONE) == "NONE"


		def test_session_with_none_logging_uses_global_config(mock_session_dependencies):

feat: Add LogLevel enum with QUIET alias support #806

Are you sure you want to change the base?

feat: Add LogLevel enum with QUIET alias support #806

Uh oh!

Conversation

Granine commented Nov 9, 2025

What does this add?

Type of changes

Background context

Checklist for Author

Code Quality

Testing

Documentation

Git & PR Management

Breaking Changes

Final Product

Usage Examples

What Changed

Uh oh!

soulFood5632 left a comment

Choose a reason for hiding this comment

Uh oh!

soulFood5632 Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

soulFood5632 Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

soulFood5632 Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

soulFood5632 Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

soulFood5632 Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

soulFood5632 Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants