{"id":24300094,"url":"https://github.com/sun-lab-nbb/ataraxis-base-utilities","last_synced_at":"2025-09-26T02:31:23.232Z","repository":{"id":246901024,"uuid":"819900844","full_name":"Sun-Lab-NBB/ataraxis-base-utilities","owner":"Sun-Lab-NBB","description":"A Python library that provides shared utility assets used to support most other Sun (NeuroAI) lab projects.","archived":false,"fork":false,"pushed_at":"2025-09-15T03:19:11.000Z","size":201,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-17T09:52:04.274Z","etag":null,"topics":["ataraxis","console","logging","utilities","utility-classes"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sun-Lab-NBB.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-25T12:01:07.000Z","updated_at":"2025-09-15T03:19:02.000Z","dependencies_parsed_at":"2024-07-05T20:28:32.731Z","dependency_job_id":"18ce3c6c-8e08-412b-b823-2e5e6e079840","html_url":"https://github.com/Sun-Lab-NBB/ataraxis-base-utilities","commit_stats":null,"previous_names":["sun-lab-nbb/ataraxis-base-utilities"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/Sun-Lab-NBB/ataraxis-base-utilities","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sun-Lab-NBB%2Fataraxis-base-utilities","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sun-Lab-NBB%2Fataraxis-base-utilities/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sun-Lab-NBB%2Fataraxis-base-utilities/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sun-Lab-NBB%2Fataraxis-base-utilities/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sun-Lab-NBB","download_url":"https://codeload.github.com/Sun-Lab-NBB/ataraxis-base-utilities/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sun-Lab-NBB%2Fataraxis-base-utilities/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275623427,"owners_count":25498335,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-17T02:00:09.119Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ataraxis","console","logging","utilities","utility-classes"],"created_at":"2025-01-16T22:38:41.502Z","updated_at":"2025-09-26T02:31:23.219Z","avatar_url":"https://github.com/Sun-Lab-NBB.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ataraxis-base-utilities\n\nA Python library that provides shared utility assets used to support most other Sun Lab projects.\n\n![PyPI - Version](https://img.shields.io/pypi/v/ataraxis-base-utilities)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ataraxis-base-utilities)\n[![uv](https://tinyurl.com/uvbadge)](https://github.com/astral-sh/uv)\n[![Ruff](https://tinyurl.com/ruffbadge)](https://github.com/astral-sh/ruff)\n![type-checked: mypy](https://img.shields.io/badge/type--checked-mypy-blue?style=flat-square\u0026logo=python)\n![PyPI - License](https://img.shields.io/pypi/l/ataraxis-base-utilities)\n![PyPI - Status](https://img.shields.io/pypi/status/ataraxis-base-utilities)\n![PyPI - Wheel](https://img.shields.io/pypi/wheel/ataraxis-base-utilities)\n\n___\n\n## Detailed Description\n\nThe primary focus of this library is to provide the unified message and error processing framework used across all\nother Sun lab projects instead of the built-in 'print,' 'logging,' and 'raise' assets. In addition to this framework, it\nalso provides functions used to perform common filesystem operations (such as creating directories) and facilitate \nefficient parallel data processing (such as chunking iterables into batches).\n\n___\n\n## Features\n\n- Supports Windows, Linux, and macOS.\n- Provides a unified approach to message and error formatting, printing, and logging through the Console class.\n- Provides a set of common utility functions frequently reused across other Sun lab projects.\n- GPL 3 License.\n\n___\n\n## Table of Contents\n\n- [Dependencies](#dependencies)\n- [Installation](#installation)\n- [Usage](#usage)\n- [API Documentation](#api-documentation)\n- [Developers](#developers)\n- [Versioning](#versioning)\n- [Authors](#authors)\n- [License](#license)\n- [Acknowledgements](#Acknowledgments)\n\n___\n\n## Dependencies\n\nFor users, all library dependencies are installed automatically by all supported installation methods \n(see the [Installation](#installation) section).\n\n***Note!*** Developers should see the [Developers](#developers) section for information on installing additional \ndevelopment dependencies.\n\n___\n\n## Installation\n\n### Source\n\nNote, installation from source is ***highly discouraged*** for anyone who is not an active project developer.\n\n1. Download this repository to the local machine using the preferred method, such as git-cloning. Use one of the stable \n   releases that include precompiled binary and source code distribution (sdist) wheels.\n2. ```cd``` to the root directory of the project.\n3. Run ```python -m pip install .``` to install the project. Alternatively, if using a distribution with precompiled\n   binaries, use ```python -m pip install WHEEL_PATH```, replacing 'WHEEL_PATH' with the path to the wheel file.\n\n### pip\n\nUse the following command to install the library using pip: ```pip install ataraxis-base-utilities```\n\n___\n\n## Usage\n\n### Console\nThe Console class provides a unified [loguru](https://github.com/Delgan/loguru)-based framework for working with \nmessages and errors to display them in the terminal and (optionally) log them to files.\n\n#### Quickstart\nMost class functionality revolves around 2 methods: ```echo()``` and ```error()```. To make adoption as frictionless\nas possible, a preconfigured Console instance is exposed as part of the library initialization via the 'console' global \nvariable:\n```\nfrom ataraxis_base_utilities import console\n\n# All class functionality is disabled by default and must be enabled for the class to behave as expected.\nconsole.enable()\n\n# Use this instead of 'print'!\nconsole.echo(\"This is a better 'print'.\")\n\n# Use this instead of 'raise'!\nconsole.error(\"This is a 'raise' with logging.\")\n```\n\n***Note!*** The preconfigured class does **not** log processed messages and errors to files. To enable file-logging, \nre-initialize the Console class with the appropriate \n[configuration parameters](#overriding-default-console-configuration).\n\n#### Working with Messages\nAll Console’s functionality for working with messages is realized through the **echo()** method. Depending on \nclass configuration, the method can be flexibly used to display the input messages in the terminal and log them to \nfiles. Each message is handed according to its **LogLevel** (urgency level) and the processing Console’s configuration.\n```\nfrom ataraxis_base_utilities import console, LogLevel\nconsole.enable()\n\n# By default, console is configured to NOT print debug messages. Calling echo for a message at 'Debug' level has no \n# effect\nconsole.echo(message='Debug is disabled by default.', level=LogLevel.DEBUG)\n\n# Messages at all levels other than 'Debug' are always printed if the console is enabled.\nconsole.echo(message='Information messages are enabled!', level=LogLevel.INFO)\nconsole.echo(message='Error messages are enabled!', level=LogLevel.ERROR)\n\n# Disabled console does not print any messages.\nconsole.disable()\nconsole.echo(message='Disabled console does not print messages.', level=LogLevel.INFO)\n```\n\n#### Working with Errors\nThe Console class treats errors as a special class of messages, handled through the **error()** method. Error \nmessages are always handled at the **Error** log level and always interrupt the normal runtime flow of the \ncaller program by calling the built-in 'raise' method after logging the message.\n```\nfrom ataraxis_base_utilities import console\n\n# The Console raises error messages even if it is disabled. However, the instance does not log messages to files when\n# disabled.\nconsole.disable()\n\n# Specify the exception to be raised by providing it as an 'error' argument. By default, this argument is\n# set to RuntimeError.\nconsole.error(message=\"Error message\", error=TypeError)\n```\n\n#### Message Formatting\nAll Console methods format input messages to fit the Sun lab’s default width-limit of 120 characters. It is \npossible to directly access and use the formatter through the **format_message()** method:\n```\nfrom ataraxis_base_utilities import console\n\n# This long message does not display well without additional formatting\nmessage = (\n    \"This is a long message that exceeds our default limit of 120 characters. Therefore, it needs to be wrapped to \"\n    \"appear correctly when printed to the terminal (or saved to a log file).\"\n)\nprint(message)\n\n# Prints a line-break for easier difference visualization\nprint()\n\n# This formats the message according to the current (default) Console configuration.\nformatted_message = console.format_message(message)\nprint(formatted_message)\n```\n\n#### Overriding Default Console Configuration\nThe default Console instance exposed via the 'console' variable is used by all other Sun lab projects. Re-initializing \nand overriding the **console** variable overrides the Console configuration used by ***all*** Sun lab \nprojects used by the same process. **Note!** Overriding the default Console configuration is a prerequisite for \nenabling logging messages and errors to files and working with 'Debug' level messages.\n```\nfrom ataraxis_base_utilities import console, Console, LogLevel, LogFormats\nfrom pathlib import Path\nfrom tempfile import TemporaryDirectory\n\n# Overwriting the default 'console' instance replaces the instance used by all other Sun lab projects running in the\n# same process as the overridden 'console'.\nconsole = Console()  # This is equivalent to using the 'default' configuration\n\n# Behaves like the default 'console' instance.\nconsole.enable()\nconsole.echo(\"Not printed by default.\", level=LogLevel.DEBUG)\n\n# Reinitializing the Console allows overriding default runtime parameters. For example, it can be used to enabled\n# handling 'Debug' messages.\nconsole = Console(debug=True)\nconsole.enable()  # Reinitializing the console resets it to the 'disabled' state.\nconsole.echo(\"Debug messages are now enabled!\", level=LogLevel.DEBUG)\n\n# Another important configuration step that requires reinitializing the console is enabling logging messages and errors\n# to files, which is disabled by default.\nwith TemporaryDirectory() as log_directory:\n    console = Console(\n        log_directory=Path(log_directory),\n        log_format=LogFormats.TXT,  # LogFormats enumeration stores all currently supported log file formats.\n        debug=True\n    )\n\n    # Prints and saves the debug message to a log file.\n    console.enable()\n    console.echo(\"Debug messages are now logged to the debug log file!\", level=LogLevel.DEBUG)\n\n    # The message can now be viewed by reading the .txt log file.\n    with console.debug_log_path.open(\"r\") as file:\n        console.echo(file.read())\n```\n\n#### Compatibility with Other Projects:\nThe Console class is built on top of the [loguru](https://github.com/Delgan/loguru) library. As part of its \ninitialization, each Console class automatically resets the handles used by the 'logger' exposed by Loguru. Therefore, \nthe Console class is **incompatible** with any other third-party library that uses Loguru for similar purposes.\n\n### Standalone Methods\nThe standalone methods are a collection of utility functions that either abstract away the boilerplate code for \ncommon data manipulations or provide novel functionality not commonly available through popular Python libraries used \nby other Sun lab projects. Generally, these methods are straightforward to use and do not require detailed explanation.\nSee the API documentation below for details on available standalone methods.\n___\n\n## API Documentation\n\nSee the [API documentation](https://ataraxis-base-utilities-api-docs.netlify.app/) for the detailed description of the \nmethods and classes exposed by components of this library.\n\n___\n\n## Developers\n\nThis section provides installation, dependency, and build-system instructions for project developers.\n\n### Installing the Project\n\n***Note!*** This installation method requires **mamba version 2.0.0 or above**.\n\n1. Download this repository to the local machine using the preferred method, such as git-cloning.\n2. ```cd``` to the root project directory.\n3. Install core Sun lab development dependencies into the 'base' mamba environment via the \n   ```mamba install tox uv tox-uv``` command.\n4. Use the ```tox -e create``` command to create the project-specific development environment followed by \n   ```tox -e install``` command to isntall the project into that environment as a library.\n\n### Additional Dependencies\n\nIn addition to installing the project and all user dependencies, install the following dependencies:\n\n1. [Python](https://www.python.org/downloads/) distributions, one for each version supported by the developed project. \n   Currently, this library supports the three latest stable versions. It is recommended to use a tool like \n   [pyenv](https://github.com/pyenv/pyenv) to install and manage the required versions.\n\n### Development Automation\n\nThis project comes with a fully configured set of automation pipelines implemented using \n[tox](https://tox.wiki/en/latest/user_guide.html). Check the [tox.ini file](tox.ini) for details about the \navailable pipelines and their implementation. Alternatively, call ```tox list``` from the root directory of the project\nto see the list of available tasks.\n\n**Note!** All pull requests for this project have to successfully complete the ```tox``` task before being merged. \nTo expedite the task’s runtime, use the ```tox --parallel``` command to run some tasks in-parallel.\n\n### Automation Troubleshooting\n\nMany packages used in 'tox' automation pipelines (uv, mypy, ruff) and 'tox' itself may experience runtime failures. In \nmost cases, this is related to their caching behavior. If an unintelligible error is encountered with \nany of the automation components, deleting the corresponding .cache (.tox, .ruff_cache, .mypy_cache, etc.) manually  \nor via a CLI command typically solves the issue.\n\n___\n\n## Versioning\n\nThis project uses [semantic versioning](https://semver.org/). For the versions available, see the \n[tags on this repository](https://github.com/Sun-Lab-NBB/ataraxis-base-utilities/tags).\n\n---\n\n## Authors\n\n- Ivan Kondratyev ([Inkaros](https://github.com/Inkaros))\n\n___\n\n## License\n\nThis project is licensed under the GPL3 License: see the [LICENSE](LICENSE) file for details.\n\n___\n\n## Acknowledgments\n\n- All Sun Lab [members](https://neuroai.github.io/sunlab/people) for providing the inspiration and comments during the\n  development of this library.\n- The creators of all other dependencies and projects listed in the [pyproject.toml](pyproject.toml) file.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsun-lab-nbb%2Fataraxis-base-utilities","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsun-lab-nbb%2Fataraxis-base-utilities","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsun-lab-nbb%2Fataraxis-base-utilities/lists"}