cliasi v0.3.0 #1

2025-12-05T20:06:39+01:00

Qrashi commented

2025-12-05 20:06:39 +01:00

(Migrated from github.com)

This adds documentation, support for multiline text and catching logging.Logger output.

copilot-pull-request-reviewer[bot] (Migrated from github.com) reviewed

2025-12-05 20:11:15 +01:00

copilot-pull-request-reviewer[bot] (Migrated from github.com) left a comment

Pull request overview

This PR introduces version 0.3.0 of cliasi, adding comprehensive documentation, multiline text support, and Python logging integration. The changes modernize the build system, improve output formatting, and provide better integration with standard Python logging.

Key Changes

Added Sphinx documentation with guides and API reference
Implemented multiline text wrapping and alignment for messages
Integrated Python's logging module with custom handler and global exception hook
Refactored API (renamed update_prefix to set_prefix, changed verbosity model to use logging levels)

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
tests/test_cliasi.py	Updated tests to use custom stream capture fixture and added tests for multiline, exception hooks, and logger installation
src/cliasi/logging_handler.py	New module providing CLILoggingHandler, install_logger, and install_exception_hook functions
src/cliasi/cliasi.py	Added multiline text wrapping, thread-safe printing, stderr routing for errors, and updated verbosity to use logging levels
src/cliasi/constants.py	Minor formatting improvement to UNICORN list comprehension
src/cliasi/init.py	Added version fallback handling and auto-installation of logger/exception hook
src/cliasi/about.py	Removed (now generated by setuptools_scm)
setup.py	Removed (migrated to pyproject.toml)
pyproject.toml	Updated to use setuptools_scm for versioning and added dev/docs dependencies
examples.py	Updated to use new `set_prefix` method and demonstrate multiline support
docs/*	Added complete Sphinx documentation structure with guides, API reference, and configuration
.readthedocs.yaml	Added Read the Docs configuration
.github/workflows/docs.yml	Added GitHub Actions workflow for building and deploying documentation
README.md	Added installation instructions and documentation link

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

## Pull request overview This PR introduces version 0.3.0 of cliasi, adding comprehensive documentation, multiline text support, and Python logging integration. The changes modernize the build system, improve output formatting, and provide better integration with standard Python logging. ### Key Changes - Added Sphinx documentation with guides and API reference - Implemented multiline text wrapping and alignment for messages - Integrated Python's logging module with custom handler and global exception hook - Refactored API (renamed `update_prefix` to `set_prefix`, changed verbosity model to use logging levels) ### Reviewed changes Copilot reviewed 20 out of 20 changed files in this pull request and generated 16 comments. <details> <summary>Show a summary per file</summary> | File | Description | | ---- | ----------- | | tests/test_cliasi.py | Updated tests to use custom stream capture fixture and added tests for multiline, exception hooks, and logger installation | | src/cliasi/logging_handler.py | New module providing CLILoggingHandler, install_logger, and install_exception_hook functions | | src/cliasi/cliasi.py | Added multiline text wrapping, thread-safe printing, stderr routing for errors, and updated verbosity to use logging levels | | src/cliasi/constants.py | Minor formatting improvement to UNICORN list comprehension | | src/cliasi/__init__.py | Added version fallback handling and auto-installation of logger/exception hook | | src/cliasi/__about__.py | Removed (now generated by setuptools_scm) | | setup.py | Removed (migrated to pyproject.toml) | | pyproject.toml | Updated to use setuptools_scm for versioning and added dev/docs dependencies | | examples.py | Updated to use new `set_prefix` method and demonstrate multiline support | | docs/* | Added complete Sphinx documentation structure with guides, API reference, and configuration | | .readthedocs.yaml | Added Read the Docs configuration | | .github/workflows/docs.yml | Added GitHub Actions workflow for building and deploying documentation | | README.md | Added installation instructions and documentation link | </details> --- 💡 <a href="/IgnyteX-Labs/cliasi/new/main/.github/instructions?filename=*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

docs/source/advanced.rst

					
				@ -0,0 +1,113 @@

				Advanced usage

Typo: 'CRTL-C' should be 'CTRL-C' (Control-C).

    cli.animate_message_blocking("Saving.. [CTRL-C] to stop", time=3)
    # You cant do anything else while the animation is running
    # Useful if you save something to a file at the end of a program
    # User can CTRL-C while this is running

Typo: 'CRTL-C' should be 'CTRL-C' (Control-C). ```suggestion cli.animate_message_blocking("Saving.. [CTRL-C] to stop", time=3) # You cant do anything else while the animation is running # Useful if you save something to a file at the end of a program # User can CTRL-C while this is running ```

Typo: 'CRTL-C' should be 'CTRL-C' (Control-C).

    cli.animate_message_blocking("Saving.. [CTRL-C] to stop", time=3)
    # You cant do anything else while the animation is running
    # Useful if you save something to a file at the end of a program
    # User can CTRL-C while this is running

Typo: 'CRTL-C' should be 'CTRL-C' (Control-C). ```suggestion cli.animate_message_blocking("Saving.. [CTRL-C] to stop", time=3) # You cant do anything else while the animation is running # Useful if you save something to a file at the end of a program # User can CTRL-C while this is running ```

docs/source/conf.py

					
				@ -0,0 +1,73 @@

				import os

The import references 'singlejson' but should import from 'cliasi' to match the actual package name.

            from cliasi import __version__ as release  # type: ignore

The import references 'singlejson' but should import from 'cliasi' to match the actual package name. ```suggestion from cliasi import __version__ as release # type: ignore ```

docs/source/getting_started.rst

					
				@ -0,0 +1,78 @@

				Getting started

Typo: 'verbostiy' should be 'verbosity'.

    # Debug messages are hidden by default as default verbosity level is INFO

Typo: 'verbostiy' should be 'verbosity'. ```suggestion # Debug messages are hidden by default as default verbosity level is INFO ```

The text 'messagesfinish' appears to be missing a space or has incorrect wording. It should likely be 'messages finish' or be reworded for clarity.

When ``messages_stay_in_one_line`` is set to ``True``, all subsequent messages finish

The text 'messagesfinish' appears to be missing a space or has incorrect wording. It should likely be 'messages finish' or be reworded for clarity. ```suggestion When ``messages_stay_in_one_line`` is set to ``True``, all subsequent messages finish ```

The documentation uses HTML <br> tags in RST format. In reStructuredText, line breaks should be handled differently (e.g., using blank lines or | for explicit line breaks).


This is disabled by default so enable it using ``cli.messages_stay_in_one_line = True``. or pass ``Cliasi(prefix="CLI", messages_stay_in_one_line=True)`` when creating a new instance.

Cliasi instances
-----------------
You can also create your own instance to customize its behavior.

This is especially helpful when giving over control to other parts of your application.

The documentation uses HTML `<br>` tags in RST format. In reStructuredText, line breaks should be handled differently (e.g., using blank lines or `|` for explicit line breaks). ```suggestion This is disabled by default so enable it using ``cli.messages_stay_in_one_line = True``. or pass ``Cliasi(prefix="CLI", messages_stay_in_one_line=True)`` when creating a new instance. Cliasi instances ----------------- You can also create your own instance to customize its behavior. This is especially helpful when giving over control to other parts of your application. ```

The documentation uses HTML <br> tags in RST format. In reStructuredText, line breaks should be handled differently (e.g., using blank lines or | for explicit line breaks).


This is disabled by default so enable it using ``cli.messages_stay_in_one_line = True``. or pass ``Cliasi(prefix="CLI", messages_stay_in_one_line=True)`` when creating a new instance.

Cliasi instances
-----------------
You can also create your own instance to customize its behavior.

This is especially helpful when giving over control to other parts of your application.

The documentation uses HTML `<br>` tags in RST format. In reStructuredText, line breaks should be handled differently (e.g., using blank lines or `|` for explicit line breaks). ```suggestion This is disabled by default so enable it using ``cli.messages_stay_in_one_line = True``. or pass ``Cliasi(prefix="CLI", messages_stay_in_one_line=True)`` when creating a new instance. Cliasi instances ----------------- You can also create your own instance to customize its behavior. This is especially helpful when giving over control to other parts of your application. ```

docs/source/index.rst

					
				@ -0,0 +1,45 @@

				.. cliasi documentation master file, created by f.rader

The comment references 'singlejson' but should reference 'cliasi' to match the actual project name.

.. cliasi documentation master file, created by

The comment references 'singlejson' but should reference 'cliasi' to match the actual project name. ```suggestion .. cliasi documentation master file, created by ```

docs/source/set_up_development_environment.rst

					
				@ -0,0 +1,35 @@

				Set up the development environment

The git clone command is incomplete - it's missing the repository URL. It should be something like git clone https://github.com/IgnyteX-Labs/cliasi.git.

       git clone https://github.com/IgnyteX-Labs/cliasi.git

The git clone command is incomplete - it's missing the repository URL. It should be something like `git clone https://github.com/IgnyteX-Labs/cliasi.git`. ```suggestion git clone https://github.com/IgnyteX-Labs/cliasi.git ```

src/cliasi/__init__.py

					
				@ -7,0 +14,4 @@

				        from importlib.metadata import version as _pkg_version

				        __version__ = _pkg_version("singlejson")

				    except Exception:

				        # Last resort for local source trees without SCM metadata

The package name 'singlejson' is incorrect. This should be 'cliasi' to match the actual package name.

        __version__ = _pkg_version("cliasi")

The package name 'singlejson' is incorrect. This should be 'cliasi' to match the actual package name. ```suggestion __version__ = _pkg_version("cliasi") ```

src/cliasi/cliasi.py

					
				@ -93,2 +127,3 @@

				    def message(self, message: str, verbosity: int = 0, override_messages_stay_in_one_line: Optional[bool] = None):

				        lines = []

The prefix is being constructed with DIM color removed from the assignment (compared to the old implementation on line 62). However, the DIM color is still applied when printing in the __print method (line 147). Consider documenting why DIM was moved from prefix storage to print-time application to make this clearer for future maintainers.

        """
        # Note: The DIM color is intentionally NOT applied here.
        # The DIM color is applied at print time in the __print method,
        # so that the prefix is stored unformatted and formatting is handled consistently during output.

The prefix is being constructed with DIM color removed from the assignment (compared to the old implementation on line 62). However, the DIM color is still applied when printing in the `__print` method (line 147). Consider documenting why DIM was moved from prefix storage to print-time application to make this clearer for future maintainers. ```suggestion """ # Note: The DIM color is intentionally NOT applied here. # The DIM color is applied at print time in the __print method, # so that the prefix is stored unformatted and formatting is handled consistently during output. ```

src/cliasi/cliasi.py

					
				@ -202,2 +286,4 @@

				    @staticmethod

				    def newline() -> None:

				        """

				        Print a newline.

The return type documentation says "None" but the function actually returns a str (user input). The return type should be documented correctly.

        :return: The user input as a string.

The return type documentation says "None" but the function actually returns a `str` (user input). The return type should be documented correctly. ```suggestion :return: The user input as a string. ```

src/cliasi/cliasi.py

					
				@ -388,17 +479,19 @@ class Cliasi:

				                     self.__format_progressbar_to_screen_width(message, "#", progress, show_percent),

				                     override_messages_stay_in_one_line)

The progress parameter is incorrectly assigned logging.INFO as its default value instead of 0. This will cause type errors when the progress bar tries to use this value as an integer.

    def progressbar_download(self, message: str, verbosity: int = logging.INFO, progress: int = 0,

The `progress` parameter is incorrectly assigned `logging.INFO` as its default value instead of `0`. This will cause type errors when the progress bar tries to use this value as an integer. ```suggestion def progressbar_download(self, message: str, verbosity: int = logging.INFO, progress: int = 0, ```

src/cliasi/logging_handler.py

					
				@ -0,0 +1,139 @@

				"""

The docstring states "existing StreamHandlers from the root logger will be removed" but this is only true when replace_root_handlers=True. The documentation should clarify that StreamHandlers are only removed when this parameter is True.

    :param replace_root_handlers: If True, existing StreamHandlers will be removed from the root logger so that only cliasi will print to the console. If False, existing StreamHandlers are left unchanged.

The docstring states "existing StreamHandlers from the root logger will be removed" but this is only true when `replace_root_handlers=True`. The documentation should clarify that StreamHandlers are only removed when this parameter is True. ```suggestion :param replace_root_handlers: If True, existing StreamHandlers will be removed from the root logger so that only cliasi will print to the console. If False, existing StreamHandlers are left unchanged. ```

The variable name exec_text is misleading - it should be exc_text (short for exception text) since it stores exception information, not execution text.

                exc_text = ""
                if record.exc_info:
                    # Unpack exc_info tuple explicitly to satisfy static analysis and clarity
                    exc_type, exc_value, exc_tb = record.exc_info
                    exc_text = "".join(traceback.format_exception(exc_type, exc_value, exc_tb))
                # pass verbosity so Cliasi can filter
                self.cli.fail(msg + exc_text, verbosity=level)

The variable name `exec_text` is misleading - it should be `exc_text` (short for exception text) since it stores exception information, not execution text. ```suggestion exc_text = "" if record.exc_info: # Unpack exc_info tuple explicitly to satisfy static analysis and clarity exc_type, exc_value, exc_tb = record.exc_info exc_text = "".join(traceback.format_exception(exc_type, exc_value, exc_tb)) # pass verbosity so Cliasi can filter self.cli.fail(msg + exc_text, verbosity=level) ```

src/cliasi/logging_handler.py

					
				@ -0,0 +76,4 @@

				    if replace_root_handlers:

				        for h in list(root.handlers):

				            if isinstance(h, logging.StreamHandler):

				                root.removeHandler(h)

The logic removes StreamHandlers twice - once unconditionally (lines 70-72) and again when replace_root_handlers=True (lines 74-77). The first removal should only happen when replace_root_handlers=True. This causes StreamHandlers to always be removed regardless of the parameter value.

The logic removes StreamHandlers twice - once unconditionally (lines 70-72) and again when `replace_root_handlers=True` (lines 74-77). The first removal should only happen when `replace_root_handlers=True`. This causes StreamHandlers to always be removed regardless of the parameter value.

Sign in to join this conversation.

No reviewers