# Colored changelog

## [2.3.2] - 2026-03-27

### Added
- Added `tests_pytest/` suite with pytest-based tests for foreground, background, styles, exceptions, hex color matching, and convert functionality.

### Fixed
- Fixed mypy type error in `hexadecimal.py`: changed `color` parameter type from `str | int` to `str` in `Hex.find()`, as the method requires string input for `len()` and indexing operations.
- Fixed mypy type errors in `attributes.py`: added missing return type annotation (`-> None`) to `MetaStyle.__getattr__()` and replaced bare `dict` with `dict[str, str]` for `_STYLES` and `_COLORS` class attributes.
- Fixed `ValueError` in `Colored.enabled()` when `FORCE_COLOR` environment variable contains a non-integer value (e.g. `FORCE_COLOR=yes`): invalid values are now treated as enabled.
- Fixed `Controls.nav()` ignoring `column=0` due to falsy check: changed `if column:` to `if column is not None:` so cursor position at column 0 (start of line) works correctly.
- Fixed `ValueError` crash in `Hex.find()` when passing an invalid hex string (e.g. `#FF`, `#AABBCCDD`): added format validation that raises `InvalidHexColor` for strings that are not 4 or 7 characters long starting with `#`.
- Fixed RGB values out of range in `Utilities.is_percentage()`: values are now clamped to [0, 255] to always produce valid ANSI escape sequences without breaking existing code.
- Fixed incorrect return type annotation `-> None` on `__getattr__` in `MetaStyle`, `MetaFore`, and `MetaBack` metaclasses: changed to `-> NoReturn` since these methods always raise an exception and never return.
- Fixed `Utilities.set_colorterm()` losing the default `truecolor` value when `$COLORTERM` is not set in the environment: changed fallback from `''` to `self.colorterm` to preserve the initialized default.
- Renamed misleading `Hex.cube()` method to `Hex.square()` to correctly reflect its calculation (`x*x`), which is the intended least squares fit operation.

## [2.3.1] - 2025-07-28

### Changed
- Refactor: Optimized Windows Terminal Mode initialization: Moved `Colored.enable_windows_terminal_mode()` call from `Colored.__init__` to module-level execution. This ensures the Windows virtual terminal processing is enabled only once when the `colored` module is imported, instead of on every `Colored` object instantiation. This change improves performance by avoiding redundant API calls and checks.
- Refactor: Reduce `Colored` instance attributes: Removed redundant instance attributes (`_ESC`, `_END`, `_STYLES`, etc.) from the `Colored` class's `__init__` method. These constants are now accessed directly from the `Library` module, reducing memory footprint per instance and improving adherence to Pylint's `R0902` warning.

### Fixed
- Resolved static analysis warnings in `enable_windows_terminal_mode()`: Modified `enable_windows_terminal_mode()` to ensure consistent return statements and handle all possible execution paths explicitly. This addresses `mypy`'s "Missing return statement" error and `pylint`'s "inconsistent-return-statements" warning by making all return paths explicit and robustly handling potential `ctypes` related exceptions. The return type hint was also updated to `Optional[bool]`.
- Resolved type hinting and tuple unpacking warnings in `Utilities.is_percentage()`: Modified the `Utilities.is_percentage()` method to explicitly return a fixed-length `tuple[int, int, int]`. This addresses `mypy`'s "Incompatible return value type" error and `pylint`'s "unbalanced-tuple-unpacking" warning by ensuring consistent and statically verifiable return types.
- Refined type validation and error handling in `Controls.nav()`: Eliminated the redundant `_is_str_object` static method. Integrated string type validation directly into the `nav()` method. Replaced `AttributeError` with `TypeError` for improved semantic clarity when handling invalid argument types.
- Ensured `test_hex_1.py` correctly uses nearest ANSI codes for hex color representation, preventing `InvalidHexColor` exceptions during gradient and random color tests.

## [2.3.0] - 2025-02-07

### Added
- New `convert` function to convert between ANSI and HEX color formats.
- Tests for the `convert` module.

### Changed
- Updated `convert_percentages(percent: str)` to return an integer.
- Improved code quality with enhanced type annotations and docstrings.

### Fixed
- Removed duplicated HEX color codes.
- Updated utilities to raise `InvalidHexColor` exception instead of `InvalidColor`.

## [2.2.5] - 2025-01-27

### Added
- Added `py.typed` marker file to the package, declaring that `colored` supports PEP 561 static type checking. Type checkers such as mypy and pyright will now recognize inline type annotations from the package without extra configuration.
- Added `__all__` declaration to `__init__.py` to explicitly define the public API surface, improving IDE auto-completion and star-import behavior (#33).

### Changed
- Updated `flit_core` build dependency to the latest supported version.
- Updated copyright year.
- Removed unused `setuptools` dependency from the build configuration.

## [2.2.4] - 2023-12-15

### Fixed
- Fixed `cprint()` incorrectly applying default foreground white `(255, 255, 255)` and background black `(0, 0, 0)` when `fore_256`/`back_256` and the RGB parameters were all omitted. Default values for `fore_256`, `back_256`, `fore_rgb`, and `back_rgb` were changed from eager color constants to `None`, so colors are only applied when explicitly provided (#20).

## [2.2.3] - 2023-07-07

### Fixed
- Fixed a typo in the Windows virtual terminal processing code: `windll.kernel32.SetsConsoleMode` was corrected to `windll.kernel32.SetConsoleMode`. The misspelled function name caused a silent failure when enabling ANSI color support on Windows terminals (#29).

## [2.2.2] - 2023-06-26

### Added
- Added `set_colorterm()` utility method that reads the `$COLORTERM` environment variable (typically set to `truecolor` or `24bit` by modern terminals) and stores it in the library configuration. This allows callers to detect whether the current terminal supports 24-bit RGB color output.

### Changed
- Moved RGB percentage conversion logic from `Colored` into the dedicated `Utilities` class, improving separation of concerns.
- Expanded the valid input range for RGB percentage strings (e.g. `'100%'`) to correctly map to the full 0–255 integer range by refactoring the conversion calculation.

## [2.2.1] - 2023-06-25

### Changed
- Renamed `InvalidNavigation` exception to `InvalidControl` to better reflect the broader scope of the `Controls` module, which handles cursor movement, screen clearing, and other terminal control sequences — not just navigation.

## [2.2.0] - 2023-06-24

### Added
- Added support for CSI (Control Sequence Introducer) terminal control sequences: cursor movement, screen/line clearing, scroll up/down, and cursor save/restore, exposed through the new `Controls` class.
- Added SGR (Select Graphic Rendition) underline color parameter, allowing a separate RGB color to be set for underlined text independently of the foreground color.
- Introduced 24-bit RGB color support via `fore_rgb()` and `back_rgb()` functions and the `Colored.foreground()`/`Colored.background()` methods, producing `\x1b[38;2;R;G;Bm` and `\x1b[48;2;R;G;Bm` escape sequences.
- Added `stylize_interactive()` function that wraps styled text with `\x01`/`\x02` markers, making escape sequences invisible to readline for correct cursor positioning in interactive prompts (e.g. custom shell prompts).

### Changed
- Updated `cprint()` to accept RGB color tuples in addition to 256-color names/codes.

### Fixed
- Corrected style name typo: `underlined` was renamed to `underline` in the SGR style definitions to match standard terminal terminology.

## [2.1.1] - 2023-06-20

### Changed
- Restored backward compatibility with the 1.x API following the breaking changes in 2.0.0 and 2.1.0:
  - Reintroduced `fg()`, `bg()`, and `attr()` as public functions (to be deprecated in a future release).
  - Made the `fore`, `back`, and `style` module-level instances importable directly, e.g.:
    ```python
    from colored.foreground import fore
    from colored.background import back
    from colored.attributes import style
    ```

## [2.1.0] - 2023-06-20

### Added
- Introduced `cprint()` as a high-level convenience function that combines foreground color, background color, text formatting, and automatic reset in a single call, replacing the lower-level `show_colour()`.

### Changed
- Replaced `show_colour()` with `cprint()` throughout the library. `show_colour()` is no longer part of the public API.
- Standardized parameter default values across `Colored`, `Fore`, `Back`, and `Style` classes to reduce boilerplate in common use cases.

## [2.0.0] - 2023-06-19

### Added
- Launched official documentation site at https://dslackw.gitlab.io/colored with user guide and API reference.
- Added `italic` and `strikeout` text style attributes (#22).
- Introduced `show_colour()` as a convenience function for styled printing (later superseded by `cprint()` in 2.1.0).

### Changed
- Full rewrite with type hints throughout the codebase.
- Renamed classes to follow Python naming conventions:
  - `fore` → `Fore`
  - `back` → `Back`
  - `style` → `Style`
- Renamed primary functions:
  - `fg()` → `fore()`
  - `bg()` → `back()`
  - `attr()` → `style()`
- Made all class color/style attributes case-insensitive via metaclass `__getattr__` — `Fore.red`, `Fore.RED`, and `Fore.Red` are all equivalent.

## [1.4.4] - 2022-11-09

### Changed
- Modernized the codebase by replacing `%`-style and `.format()`-style string formatting with f-strings throughout.
- Dropped Python 2 support. The minimum supported version is now Python 3.
- Replaced direct use of `ctypes.windll` with the properly typed `ctypes.wintypes` Windows types for virtual terminal processing, improving robustness on Windows (#25).

## [1.4.3] - 2021-10-23

### Changed
- Improved the color-enabling mechanism: colors are now disabled when output is not a TTY (e.g. when piped to a file or another process), and re-enabled with the `set_tty_aware(False)` call. This prevents raw ANSI escape codes from appearing in redirected output (#18).

## [1.4.2] - 2019-12-09

### Changed
- Updated `setup.py` to resolve Python 3 packaging issues (missing `packages` discovery and incorrect classifiers).

## [1.4.1] - 2019-10-28

### Fixed
- Resolved `io.UnsupportedOperation: fileno` error raised when checking `sys.stdout.isatty()` in environments where stdout is replaced with a non-file object (e.g. during testing or when stdout is redirected to a `StringIO` buffer) (#14).

## [1.4.0] - 2019-10-02

### Added
- Ensured `colored/` package data files are included in source distributions by updating `MANIFEST.in`.
- Migrated packaging from legacy `setup.py`-only to `setup.cfg` declarative format.
- Improved HEX color lookup: the `Hex.find()` method now performs a nearest-color search using a least-squares RGB distance calculation when an exact match is not found in the color table.
- Added support for ANSI colors in Windows Command Prompt and PowerShell by enabling virtual terminal processing via `SetConsoleMode` at import time.
- Added TTY awareness: by default, color codes are suppressed when output is not connected to a terminal, preventing escape sequences from appearing in piped or redirected output. Use `set_tty_aware(False)` to override.

## [1.3.93] - 2018-07-06

### Fixed
- Corrected a typo in `MANIFEST.in` that caused the file to be ignored by setuptools, preventing source distributions from including the correct data files.

## [1.3.92] - 2018-07-02

### Fixed
- Updated `CHANGELOG`, `LICENSE`, and `MANIFEST.in` to meet PyPI packaging requirements, resolving upload and display issues on the package index (#12).
- Adjusted `setup.py` classifiers and metadata to match the corrected license and changelog format.

## [1.3.8] - 2018-06-26

### Fixed
- Resolved `pip install colored` failures caused by a missing or malformed `MANIFEST.in`, which prevented the source distribution from being built correctly (#12).

## [1.3.7] - 2018-06-26

### Fixed
- Corrected a license identifier typo in `setup.py` (`MIT License` → `MIT`) that caused the package to fail PyPI validation.
- Fixed related `pip install` failures stemming from the invalid metadata (#12).

## [1.3.6] - 2018-06-24

### Fixed
- Fixed the `license` field in `setup.py` to use the correct SPDX identifier, resolving a PyPI upload error.

## [1.3.5] - 2018-06-24

### Changed
- Migrated the project repository from GitHub to GitLab.
- Switched the project license from BSD to MIT.

## [1.3.4] - 2017-05-07

### Added
- Added `stylize_interactive()` function that wraps styled strings with `\x01` and `\x02` non-printing markers. This makes the escape sequences transparent to readline's line-length calculation, preventing display glitches in interactive prompts such as custom Python REPLs or shell prompt strings (#6).

## [1.3.3] - 2016-11-19

### Added
- Made HEX color lookup case-insensitive: `#FF0000`, `#ff0000`, and `#Ff0000` are now treated identically (#2).
- Added `stylize(text, style)` convenience function that applies a style string to text and appends an automatic reset, reducing boilerplate for the common case (#3).

## [1.3.2] - 2016-11-02

### Changed
- Merged the separate foreground and background color name dictionaries into a single shared color library, eliminating duplicate entries and ensuring consistent color naming across `fore` and `back`.

## [1.3.1] - 2016-09-20

### Added
- Added `RED_3B` color entry to the color library to fill a gap in the named 256-color palette.

### Fixed
- Fixed Python 3 compatibility in `print` statements used in the test suite.

## [1.3.0] - 2016-09-20

### Changed
- Refactored `fore`, `back`, and `style` classes to use `vars()` for dynamic attribute lookup, replacing hard-coded `if/elif` chains and simplifying the addition of new color names.

## [1.2.2] - 2016-05-18

### Changed
- Updated license headers in all source files.
- Fixed typo in color name: `dark_sea_sreen_X` corrected to `dark_sea_green_X` (thanks to Clifford Ireland).

## [1.2.1] - 2015-06-06

### Changed
- Fixed Python 3 installation by correcting the `packages` declaration in `setup.py`.
- Added MIT license header to each source file.

## [1.2.0] - 2015-06-06

### Changed
- Restored informative `KeyError` messages in exceptions so that invalid color names report the offending key.
- Fixed a duplicate key in the foreground color dictionary that caused one color to silently override another.
- Cleaned up module imports to remove circular dependencies.
- Improved the test suite to cover more color and style combinations.

## [1.1.5] - 2015-02-25

### Changed
- Applied PEP 8 formatting across the codebase: consistent indentation, whitespace, and naming conventions.

## [1.1.4] - 2014-08-01

### Changed
- Added the generated `egg-info` directory to the repository to simplify local development installs via `pip install -e .`.

## [1.1.3] - 2014-07-11

### Changed
- Fixed version string to correctly reflect `1.1.3`.
- Resolved a module naming conflict between `attr.py` and `colored.py` that caused an `ImportError` on some Python installations.

## [1.1.2] - 2014-07-11

### Added
- Introduced `fore`, `back`, and `style` classes as the primary API for accessing color and style codes as attributes (e.g. `fore.red`, `back.blue`, `style.bold`).

## [1.1.1] - 2014-07-10

### Added
- Added support for HEX color input: `Hex.find()` converts a `#RRGGBB` string to the nearest 256-color ANSI code.
- Added `HEX_COLORS` lookup table mapping ANSI color codes to their corresponding HEX values.

## [1.1.0] - 2014-07-09

### Added
- Added `colors_list.txt` listing all 256 named color entries for reference.
- Extended test suite with additional color coverage tests.

### Changed
- Improved Python 3 compatibility by replacing `print` statements with `print()` function calls and fixing string handling.

## [1.0.9] - 2014-07-09

### Changed
- Removed numeric keys from the color dictionary to enforce name-only lookups and avoid ambiguity between color names and ANSI code integers.
- Fixed `KeyError` exceptions that occurred when looking up colors not present in the dictionary.

## [1.0.8] - 2014-07-08

### Changed
- Introduced `fg()`, `bg()`, and `attr()` as shorthand aliases for accessing foreground color, background color, and text style codes respectively.

## [1.0.7] - 2014-07-08

### Changed
- Consolidated the previously separate foreground and background color dictionaries into a single shared dictionary, reducing duplication.

## [1.0.6] - 2014-07-07

### Changed
- Integrated the 16 standard ANSI colors into the full 256-color lookup table, unifying the color API.
- Introduced the class and attribute-based structure (`fore`, `back`, `style`) as the foundation for the public API.

## [1.0.5] - 2014-07-05

### Added
- Added `test_3.py` covering style attribute tests.

## [1.0.4] - 2014-07-04

### Added
- Added `test_2.py` covering background color escape sequence tests.

## [1.0.3] - 2014-07-03

### Changed
- Removed the `screenshots` directory from the repository to reduce repository size.

## [1.0.2] - 2014-07-02

### Added
- Added support for the full 256-color ANSI palette for both foreground (`\x1b[38;5;Nm`) and background (`\x1b[48;5;Nm`) colors.

## [1.0.1] - 2014-07-02

### Added
- Added initial test suite (`test_1.py`) covering basic foreground and background color output.

## [1.0.0] - 2014-07-02

### Added
- Initial release of the `colored` library: a simple Python library for applying ANSI color and text formatting in terminal output, with named color support for 256-color terminals.