### Install Python on Linux using Apt

Source: https://github.com/fhpythonutils/colourswatch/blob/master/README.md

Installs a specific version of Python on Debian-based Linux distributions using the apt package manager. Replace '3.x' with the desired Python version.

```bash
sudo apt install python3.x
```

--------------------------------

### Install Python on Windows using Chocolatey

Source: https://github.com/fhpythonutils/colourswatch/blob/master/README.md

Installs Python on Windows using the Chocolatey package manager. Ensure Chocolatey is installed and configured on your system before running this command.

```powershell
choco install python
```

--------------------------------

### Install Python on MacOS using Homebrew

Source: https://github.com/fhpythonutils/colourswatch/blob/master/README.md

Installs a specific version of Python on macOS using the Homebrew package manager. Replace '3.x' with the desired Python version.

```bash
brew install python@3.x
```

--------------------------------

### Install Python on Linux using Dnf

Source: https://github.com/fhpythonutils/colourswatch/blob/master/README.md

Installs a specific version of Python on Fedora-based Linux distributions using the dnf package manager. Replace '3.x' with the desired Python version.

```bash
sudo dnf install python3.x
```

--------------------------------

### Run Python Modules and Files on Windows

Source: https://github.com/fhpythonutils/colourswatch/blob/master/README.md

Commands to execute Python modules or files on Windows using the 'py' launcher. This assumes Python is installed and registered with the 'py' launcher.

```bash
py -3.x -m [module]
[module]
py -3.x [file]
./[file]
```

--------------------------------

### Colour Conversion Methods (Python)

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/colourswatch.md

Provides methods to convert a Colour object to various color formats like RGB, CMYK, HSL, HSV, and LAB. It also includes methods to get the color as different tuple representations (float, hex, RGB255).

```python
    def colorToTuple(self) -> tuple[float, ...]: ...

    def convertedColourToHexTuple(self, uppercase: bool = False) -> tuple[str, ...]: ...

    def convertedColourToTuple(self) -> tuple[float, ...]: ...

    def getRGB255(self) -> tuple[int, ...]: ...

    def getRGB255Hex(self, uppercase: bool = False) -> tuple[str, ...]: ...

    def toCMYK(self) -> CMYKColor: ...

    def toHSL(self) -> HSLColor: ...

    def toHSV(self) -> HSVColor: ...

    def toLAB(self) -> LabColor: ...

    def toRGB(self) -> sRGBColor: ...

```

--------------------------------

### Get Converted Colour Values as Tuple

Source: https://context7.com/fhpythonutils/colourswatch/llms.txt

Retrieves the current colour's value as a tuple. This function is typically called after converting the colour to a specific format like RGB using `fromRGB()` or similar methods. The output is a tuple representing the colour components.

```python
print(f"RGB: {colour.convertedColourToTuple()}")  # After calling toRGB()
print(f"Original colour tuple: {colour.colorToTuple()}")
```

--------------------------------

### Build Project Artifacts and Documentation

Source: https://github.com/fhpythonutils/colourswatch/blob/master/README.md

Automated build process using FHMake (or equivalent commands) for generating documentation, updating requirements, and building library artifacts. This sequence approximates the functionality of `fhmake`.

```sh
handsdown  --cleanup -o documentation/reference
poetry export -f requirements.txt --output requirements.txt
poetry export -f requirements.txt --with dev --output requirements_optional.txt
poetry build
```

--------------------------------

### Clone Project Repository using Git

Source: https://github.com/fhpythonutils/colourswatch/blob/master/README.md

Clones the ColourSwatch project repository from GitHub using the Git command-line interface. This downloads the entire project history and files to your local machine.

```bash
git clone https://github.com/FHPythonUtils/ColourSwatch
```

--------------------------------

### GimpGplPalette Class Initialization

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/gimpgplpal.md

Initializes a GimpGplPalette object. It can optionally load palette data from a file path, file-like object, or bytes stream upon instantiation.

```python
class GimpGplPalette:
    def __init__(self, file: BytesIO | str | Path | None = None) -> None: ...
```

--------------------------------

### Open Colour Palette Files with Python

Source: https://context7.com/fhpythonutils/colourswatch/llms.txt

Demonstrates how to use the `openColourSwatch()` function to read various colour palette file formats into `ColourSwatch` objects. It handles different formats like GPL, YAML, JSON, and ASE, showing how to access palette names, colour counts, and individual colour details.

```python
from colourswatch.io import openColourSwatch

# Open a GIMP palette file
palette = openColourSwatch("my_palette.gpl")
print(f"Palette: {palette.name}")
print(f"Number of colours: {len(palette.colours)}")

# Access individual colours
for colour in palette.colours:
    print(f"  {colour.name}: RGB{colour.getRGB255()}")

# Open different format examples
yaml_palette = openColourSwatch("theme.yaml")
json_palette = openColourSwatch("colors.json")
png_palette = openColourSwatch("swatches.png")

# Adobe Swatch Exchange files return a list of swatches
ase_swatches = openColourSwatch("design.ase")
for swatch in ase_swatches:
    print(f"Swatch: {swatch.name} with {len(swatch.colours)} colours")
```

--------------------------------

### Batch Convert Palette Files using I/O Functions

Source: https://context7.com/fhpythonutils/colourswatch/llms.txt

Converts entire directories of palette files between supported formats using `openColourSwatch` and `saveColourSwatch`. Handles various input formats and outputs to a specified directory. Requires `pathlib`. Errors during conversion are caught and reported.

```python
from pathlib import Path
from colourswatch.io import openColourSwatch, saveColourSwatch

# Convert all GPL files in a directory to JSON
source_dir = Path("./palettes")
output_dir = Path("./json_palettes")
output_dir.mkdir(exist_ok=True)

for gpl_file in source_dir.glob("*.gpl"):
    try:
        palette = openColourSwatch(gpl_file)
        output_path = output_dir / f"{gpl_file.stem}.json"
        saveColourSwatch(output_path, palette)
        print(f"Converted: {gpl_file.name} -> {output_path.name}")
    except Exception as e:
        print(f"Error converting {gpl_file.name}: {e}")

# Convert multiple formats to a single target format
formats_to_convert = ["*.yaml", "*.toml", "*.colors", "*.pal"]
for pattern in formats_to_convert:
    for file in source_dir.glob(pattern):
        palette = openColourSwatch(file)
        saveColourSwatch(output_dir / f"{file.stem}.gpl", palette)
```

--------------------------------

### Create ColourSwatch Objects Programmatically in Python

Source: https://context7.com/fhpythonutils/colourswatch/llms.txt

Shows how to programmatically create `ColourSwatch` and `Colour` objects in Python, allowing for detailed control over palette metadata and colour definitions across different colour spaces. The created swatches can then be saved to various file formats.

```python
from colourswatch.colourswatch import ColourSwatch, Colour
from colourswatch.io import saveColourSwatch
from colormath.color_objects import sRGBColor, CMYKColor, LabColor

# Create colours using different colour spaces
colours = [
    Colour("Primary Red", sRGBColor(1.0, 0.0, 0.0)),
    Colour("Forest Green", sRGBColor(0.13, 0.55, 0.13)),
    Colour("Ocean Blue", sRGBColor(0.0, 0.47, 0.75)),
    Colour("Warm Yellow", sRGBColor(255, 215, 0, is_upscaled=True)),  # Using 0-255 values
    Colour("Print Cyan", CMYKColor(1.0, 0.0, 0.0, 0.0)),  # CMYK colour
    Colour("Lab Purple", LabColor(50.0, 60.0, -40.0)),    # Lab colour
]

# Create the swatch with metadata
swatch = ColourSwatch(
    name="Brand Colours",
    colours=colours,
    author="Design Team",
    description="Official brand colour palette",
    swatchId="brand-2024",
    swatchCopyright="Copyright 2024"
)

# Save to multiple formats
saveColourSwatch("brand_colours.gpl", swatch)
saveColourSwatch("brand_colours.json", swatch)
saveColourSwatch("brand_colours.png", swatch)
```

--------------------------------

### GimpGplPalette Load from File

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/gimpgplpal.md

Loads palette data from a specified file, which can be a file name string, a path object, or a file-like object.

```python
def load(self, file: BytesIO | str | Path) -> None: ...
```

--------------------------------

### Run Python Modules and Files on Linux/MacOS

Source: https://github.com/fhpythonutils/colourswatch/blob/master/README.md

Commands to execute Python modules or files on Linux and macOS. Ensure the desired Python version (e.g., python3.x) is in your PATH.

```bash
python3.x -m [module]
[module]
python3.x [file]
./[file]
```

--------------------------------

### Open TXT Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .TXT file. This function takes a file path and returns a ColourSwatch object, useful for plain text colour swatch files.

```python
def openSwatch_TXT(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### Open SOC Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .SOC file. The function accepts a file path and returns a ColourSwatch object, handling the .SOC file format.

```python
def openSwatch_SOC(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### openSwatch_GPL

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a GPL (GIMP Palette) file and returns it as a ColourSwatch object. This function is used for loading GIMP-compatible palette files.

```APIDOC
## openSwatch_GPL

### Description
Opens a GPL (GIMP Palette) file and returns it as a ColourSwatch object. Used for loading GIMP-compatible palette files.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the GPL color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object representing the GIMP palette.

#### Response Example
N/A
```

--------------------------------

### Open SKP Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .SKP file. This function takes a file path and returns a ColourSwatch object, designed for the .SKP file format.

```python
def openSwatch_SKP(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### Open XML Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .XML file. It takes a file path and returns a ColourSwatch object, allowing import from XML-based colour swatch definitions.

```python
def openSwatch_XML(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### Run Project Tests using Tox

Source: https://github.com/fhpythonutils/colourswatch/blob/master/README.md

Executes project tests across multiple Python versions (3.8-3.11) using the tox testing framework. This provides a comprehensive test suite across different environments.

```bash
tox
```

--------------------------------

### ColourSwatch Class Initialization (Python)

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/colourswatch.md

Defines the ColourSwatch class for representing a collection of colours. Includes the constructor and methods for outputting a PIL palette.

```python
class ColourSwatch:
    def __init__(
        self,
        name: str,
        colours: list[Colour] | None = None,
        swatchId: str | None = None,
        description: str | None = None,
        swatchCopyright: str | None = None,
        author: str | None = None,
    ) -> None: ...

    def toPILPalette(self) -> ...: ...

```

--------------------------------

### Colour Space Conversions in Python with ColourSwatch

Source: https://context7.com/fhpythonutils/colourswatch/llms.txt

Demonstrates the colour space conversion capabilities of the `Colour` class in the ColourSwatch library, utilizing the `colormath` library. It shows how to convert a colour to various standard colour spaces like RGB, CMYK, HSV, HSL, and LAB, and how to retrieve RGB values in different formats (tuple, hex).

```python
from colourswatch.io import openColourSwatch

palette = openColourSwatch("palette.gpl")
colour = palette.colours[0]

# Convert to different colour spaces
rgb = colour.toRGB()      # Returns sRGBColor
cmyk = colour.toCMYK()    # Returns CMYKColor
hsv = colour.toHSV()      # Returns HSVColor
hsl = colour.toHSL()      # Returns HSLColor
lab = colour.toLAB()      # Returns LabColor

# Get RGB values in different formats
rgb_tuple = colour.getRGB255()              # (255, 128, 64) - integer 0-255
rgb_hex = colour.getRGB255Hex()             # ('ff', '80', '40') - lowercase hex
rgb_hex_upper = colour.getRGB255Hex(uppercase=True)  # ('FF', '80', '40')
```

--------------------------------

### POST /saveSwatch_GPL

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Save a colour swatch as .GPL format. This endpoint takes a file path and a ColourSwatch object to save the swatch.

```APIDOC
## POST /saveSwatch_GPL

### Description
Save a colour swatch as .GPL format.

### Method
POST

### Endpoint
/saveSwatch_GPL

### Parameters
#### Request Body
- **file** (str | Path) - Required - The file path to save the swatch.
- **colourSwatch** (ColourSwatch) - Required - The ColourSwatch object to save.
```

--------------------------------

### Open YAML Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .YAML file. This function accepts a file path and returns a ColourSwatch object, supporting colour data in YAML format.

```python
def openSwatch_YAML(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### extNotRecognised

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Outputs the file extension not recognized error. This function is used when an unsupported file extension is encountered.

```APIDOC
## extNotRecognised

### Description
Outputs the file extension not recognised error.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **file** (str | Path) - Required - The file path for which the extension was not recognized.

### Request Example
N/A

### Response
#### Success Response (200)
- **str**: An error message string indicating the unrecognized file extension.

#### Response Example
```
"Error: File extension not recognized."
```
```

--------------------------------

### Open PNG Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .png file. This function takes a file path as input and returns a ColourSwatch object, specifically designed for PNG image formats.

```python
def openSwatch_PNG(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### openSwatch_TXT

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a plain text file containing color swatch data and returns it as a ColourSwatch object. This function is for simple text-based color palette formats.

```APIDOC
## openSwatch_TXT

### Description
Opens a plain text file containing color swatch data and returns it as a ColourSwatch object. For simple text-based color palette formats.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the TXT color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object parsed from the TXT file.

#### Response Example
N/A
```

--------------------------------

### Run Project Tests using Poetry

Source: https://github.com/fhpythonutils/colourswatch/blob/master/README.md

Executes project tests using the pytest framework, managed by Poetry. This ensures tests are run within the project's defined virtual environment.

```bash
poetry run pytest
```

--------------------------------

### openSwatch_PSPPAL

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a PSPPAL (PaintShop Pro Palette) file and returns it as a ColourSwatch object. This function handles PaintShop Pro's palette format.

```APIDOC
## openSwatch_PSPPAL

### Description
Opens a PSPPAL (PaintShop Pro Palette) file and returns it as a ColourSwatch object. Handles PaintShop Pro's palette format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the PSPPAL color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object representing the PaintShop Pro palette.

#### Response Example
N/A
```

--------------------------------

### Open Image Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from an image file (e.g., .jpg, .webp). It accepts a file path and returns a ColourSwatch object. This function is useful for extracting colour palettes from images.

```python
def openSwatch_IMAGE(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### openSwatch_SOC

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens an SOC (sK1 Project) color swatch file and returns it as a ColourSwatch object. This function is specific to the SOC file format.

```APIDOC
## openSwatch_SOC

### Description
Opens an SOC (sK1 Project) color swatch file and returns it as a ColourSwatch object. Specific to the SOC file format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the SOC color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object representing the SOC swatch.

#### Response Example
N/A
```

--------------------------------

### Open TOML Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .TOML file. The function accepts a file path and returns a ColourSwatch object, supporting colour data stored in TOML format.

```python
def openSwatch_TOML(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### Work with GIMP GPL Palette Files Directly

Source: https://context7.com/fhpythonutils/colourswatch/llms.txt

Provides direct access to GIMP palette file internals using the `GimpGplPalette` class. Allows loading, accessing properties like name and columns, modifying colours and names, and saving changes or creating new palettes. No external dependencies beyond the library itself.

```python
from colourswatch.gimpgplpal import GimpGplPalette

# Load a GIMP palette
gpl = GimpGplPalette("palette.gpl")

# Access palette properties
print(f"Name: {gpl.name}")
print(f"Columns: {gpl.columns}")
print(f"File: {gpl.fileName}")

# Access colours directly (as RGB tuples 0-255)
for i, color in enumerate(gpl.colors):
    name = gpl.colorNames[i] or f"colour{i}"
    print(f"{name}: RGB({color[0]}, {color[1]}, {color[2]})")

# Modify the palette
gpl.name = "My Modified Palette"
gpl.columns = 8
gpl.colors.append((128, 64, 192))
gpl.colorNames.append("New Purple")

# Save changes
gpl.save("modified_palette.gpl")

# Create a new palette from scratch
new_gpl = GimpGplPalette()
new_gpl.name = "Custom Palette"
new_gpl.columns = 4
new_gpl.colors = [(255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 255, 0)]
new_gpl.colorNames = ["Red", "Green", "Blue", "Yellow"]
new_gpl.save("custom.gpl")
```

--------------------------------

### Open PaintShopPro PAL Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a PaintShopPro .PAL file. It accepts a file path and returns a ColourSwatch object, supporting a specific proprietary colour format.

```python
def openSwatch_PSPPAL(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### openSwatch_SKP

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens an SKP (Sketch) color swatch file and returns it as a ColourSwatch object. This function is specific to the SKP file format.

```APIDOC
## openSwatch_SKP

### Description
Opens an SKP (Sketch) color swatch file and returns it as a ColourSwatch object. Specific to the SKP file format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the SKP color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object representing the SKP swatch.

#### Response Example
N/A
```

--------------------------------

### Read GIMP Palette (.GPL) Files in Python

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

The openSwatch_GPL function handles the parsing of GIMP Palette (.gpl) files. It takes a file path as input and returns a ColourSwatch object, enabling the import of color palettes created or used in GIMP.

```python
def openSwatch_GPL(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### Open SPL Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .SPL file. This function takes a file path and returns a ColourSwatch object, specifically for the .SPL file format.

```python
def openSwatch_SPL(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### Open SVG Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .svg file. It takes a file path as input and returns a ColourSwatch object, enabling the import of colour data from SVG files.

```python
def openSwatch_SVG(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### Colour Class Initialization and Representation (Python)

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/colourswatch.md

Defines the Colour class for representing individual colors. Includes constructor, equality check, and string representation methods.

```python
class Colour:
    def __init__(
        self,
        name: str,
        colour: ColorBase | None = None,
        nameNull: bool = False,
        alpha: float = 1.0,
    ) -> None: ...

    def __eq__(self, other: Colour) -> bool: ...

    def __repr__(self) -> str: ...

```

--------------------------------

### openSwatch_CDPAL

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a CorelDraw .PAL color swatch file and returns it as a ColourSwatch object. This function handles CorelDraw's palette format.

```APIDOC
## openSwatch_CDPAL

### Description
Opens a CorelDraw .PAL color swatch file and returns it as a ColourSwatch object. Handles CorelDraw's palette format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the CorelDraw .PAL color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object representing the CorelDraw palette.

#### Response Example
N/A
```

--------------------------------

### Open JSON Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .JSON file. The function takes a file path and returns a ColourSwatch object, enabling the import of colour data stored in JSON format.

```python
def openSwatch_JSON(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### GimpGplPalette Save to File

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/gimpgplpal.md

Saves the current GIMP GPL palette data to a specified file path or file-like object.

```python
def save(self, file: BytesIO | str | Path) -> None: ...
```

--------------------------------

### openSwatch_ASE

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens an ASE (Adobe Swatch Exchange) file and returns a list of ColourSwatch objects. This function is used for loading Adobe-compatible swatch files.

```APIDOC
## openSwatch_ASE

### Description
Opens an ASE (Adobe Swatch Exchange) file and returns a list of ColourSwatch objects. Used for loading Adobe-compatible swatch files.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the ASE color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **list[ColourSwatch]**: A list of ColourSwatch objects extracted from the ASE file.

#### Response Example
N/A
```

--------------------------------

### Open HPL Colour Swatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a colour swatch from a .HPL file. It takes a file path as input and returns a ColourSwatch object. This function is part of the colourswatch I/O utilities.

```python
def openSwatch_HPL(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### openSwatch_YAML

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a YAML file containing color swatch data and returns it as a ColourSwatch object. This function is used for loading swatches stored in YAML format.

```APIDOC
## openSwatch_YAML

### Description
Opens a YAML file containing color swatch data and returns it as a ColourSwatch object. Used for loading swatches stored in YAML format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the YAML color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object parsed from the YAML file.

#### Response Example
N/A
```

--------------------------------

### openSwatch_ACBL

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens an ACBL color swatch file and returns it as a ColourSwatch object. This is specific to the ACBL file format.

```APIDOC
## openSwatch_ACBL

### Description
Opens an ACBL color swatch file and returns it as a ColourSwatch object. Specific to the ACBL file format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the ACBL color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object representing the ACBL swatch.

#### Response Example
N/A
```

--------------------------------

### openColourSwatch

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens and parses a color swatch file, returning a ColourSwatch object or a list of such objects. This function supports various swatch file formats.

```APIDOC
## openColourSwatch

### Description
Opens and parses a color swatch file, returning a ColourSwatch object or a list of such objects. Supports various swatch file formats.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch | list[ColourSwatch]**: A ColourSwatch object or a list of ColourSwatch objects.

#### Response Example
N/A

#### Error Handling
- **FileExistsError**: Raised if the specified file does not exist.
- **ValueError**: Raised for invalid file content or format.
```

--------------------------------

### POST /saveSwatch_TXT

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Save a colour swatch as .TXT format. This endpoint takes a file path and a ColourSwatch object to save the swatch.

```APIDOC
## POST /saveSwatch_TXT

### Description
Save a colour swatch as .TXT format.

### Method
POST

### Endpoint
/saveSwatch_TXT

### Parameters
#### Request Body
- **file** (str | Path) - Required - The file path to save the swatch.
- **colourSwatch** (ColourSwatch) - Required - The ColourSwatch object to save.
```

--------------------------------

### openSwatch_XML

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens an XML file containing color swatch data and returns it as a ColourSwatch object. This function is used for loading swatches stored in XML format.

```APIDOC
## openSwatch_XML

### Description
Opens an XML file containing color swatch data and returns it as a ColourSwatch object. Used for loading swatches stored in XML format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the XML color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object parsed from the XML file.

#### Response Example
N/A
```

--------------------------------

### openSwatch_HPL

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens an HPL (HPL Path) color swatch file and returns it as a ColourSwatch object. This function is specific to the HPL file format.

```APIDOC
## openSwatch_HPL

### Description
Opens an HPL (HPL Path) color swatch file and returns it as a ColourSwatch object. Specific to the HPL file format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the HPL color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object representing the HPL swatch.

#### Response Example
N/A
```

--------------------------------

### Prettify XML Output

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Returns a pretty-printed XML string for a given Element. It allows customization of indentation and doctype. This is useful for generating human-readable XML output.

```python
def prettify(
    elem: Element,
    indent: str = "\t",
    doctype: str = '<?xml version="1.0" encoding="utf-8"?>',
) -> str: ...
```

--------------------------------

### POST /saveSwatch_SKP

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Save a colour swatch as .SKP format. This endpoint takes a file path and a ColourSwatch object to save the swatch.

```APIDOC
## POST /saveSwatch_SKP

### Description
Save a colour swatch as .SKP format.

### Method
POST

### Endpoint
/saveSwatch_SKP

### Parameters
#### Request Body
- **file** (str | Path) - Required - The file path to save the swatch.
- **colourSwatch** (ColourSwatch) - Required - The ColourSwatch object to save.
```

--------------------------------

### Open and Parse Color Swatch Files in Python

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

The openColourSwatch function serves as a general-purpose entry point for opening various color swatch files. It can return either a single ColourSwatch object or a list of them, depending on the file format. The function handles file path input and includes error handling for file existence and value errors.

```python
def openColourSwatch(file: str | Path) -> ColourSwatch | list[ColourSwatch]: ...
```

--------------------------------

### POST /saveSwatch_YAML

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Save a colour swatch as .YAML format. This endpoint takes a file path and a ColourSwatch object to save the swatch.

```APIDOC
## POST /saveSwatch_YAML

### Description
Save a colour swatch as .YAML format.

### Method
POST

### Endpoint
/saveSwatch_YAML

### Parameters
#### Request Body
- **file** (str | Path) - Required - The file path to save the swatch.
- **colourSwatch** (ColourSwatch) - Required - The ColourSwatch object to save.
```

--------------------------------

### POST /saveSwatch_XML

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Save a colour swatch as .XML format. This endpoint takes a file path and a ColourSwatch object to save the swatch.

```APIDOC
## POST /saveSwatch_XML

### Description
Save a colour swatch as .XML format.

### Method
POST

### Endpoint
/saveSwatch_XML

### Parameters
#### Request Body
- **file** (str | Path) - Required - The file path to save the swatch.
- **colourSwatch** (ColourSwatch) - Required - The ColourSwatch object to save.
```

--------------------------------

### Load Color Swatch Data from File in Python

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

The getSwatchFromfile function reads color data from a specified file and constructs a ColourSwatch object. It takes a file path and a list of Colour objects as input, returning the populated ColourSwatch. This is a core function for loading color palettes from external sources.

```python
def getSwatchFromfile(file: str | Path, colours: list[Colour]) -> ColourSwatch: ...
```

--------------------------------

### Save Colour Swatch as .TXT

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Saves a ColourSwatch object to a plain text (.TXT) file. This function takes a file path and a ColourSwatch object as input and is located in the io.py module.

```python
def saveSwatch_TXT(file: str | Path, colourSwatch: ColourSwatch) -> None: ...
```

--------------------------------

### Save Colour Swatch as .GPL

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Exports a ColourSwatch object to a .GPL (GIMP Palette) file. The function accepts a file path and the ColourSwatch data. It is part of the io.py module.

```python
def saveSwatch_GPL(file: str | Path, colourSwatch: ColourSwatch) -> None: ...
```

--------------------------------

### openSwatch_TOML

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a TOML file containing color swatch data and returns it as a ColourSwatch object. This function is used for loading swatches stored in TOML format.

```APIDOC
## openSwatch_TOML

### Description
Opens a TOML file containing color swatch data and returns it as a ColourSwatch object. Used for loading swatches stored in TOML format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the TOML color swatch file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object parsed from the TOML file.

#### Response Example
N/A
```

--------------------------------

### Save Colour Swatch as .SOC

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Exports a ColourSwatch object to a .SOC file. This function requires a file path and the ColourSwatch data and is implemented in the io.py module.

```python
def saveSwatch_SOC(file: str | Path, colourSwatch: ColourSwatch) -> None: ...
```

--------------------------------

### POST /saveSwatch_SOC

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Save a colour swatch as .SOC format. This endpoint takes a file path and a ColourSwatch object to save the swatch.

```APIDOC
## POST /saveSwatch_SOC

### Description
Save a colour swatch as .SOC format.

### Method
POST

### Endpoint
/saveSwatch_SOC

### Parameters
#### Request Body
- **file** (str | Path) - Required - The file path to save the swatch.
- **colourSwatch** (ColourSwatch) - Required - The ColourSwatch object to save.
```

--------------------------------

### prettify

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Formats a color swatch or a list of colors for pretty printing. This function is useful for displaying color data in a human-readable format.

```APIDOC
## prettify

### Description
Formats a color swatch or a list of colors for pretty printing. Useful for displaying color data in a human-readable format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **colourSwatchOrColours** (ColourSwatch | list[Colour]) - Required - The color swatch or list of colors to format.

### Request Example
N/A

### Response
#### Success Response (200)
- **str**: A string representation of the formatted colors.

#### Response Example
N/A
```

--------------------------------

### Read .ACBL Files in Python

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

The openSwatch_ACBL function parses color swatch files with the .ACBL extension. It accepts a file path and returns a ColourSwatch object, enabling the integration of color data from this particular file format.

```python
def openSwatch_ACBL(file: str | Path) -> ColourSwatch: ...
```

--------------------------------

### Save Colour Swatch as .YAML

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Serializes a ColourSwatch object into a .YAML file. This function accepts a file path and a ColourSwatch object, and is implemented in the io.py module.

```python
def saveSwatch_YAML(file: str | Path, colourSwatch: ColourSwatch) -> None: ...
```

--------------------------------

### openSwatch_PNG

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens a PNG image file and extracts color swatches from it. This function is specialized for PNG image format.

```APIDOC
## openSwatch_PNG

### Description
Opens a PNG image file and extracts color swatches from it. Specialized for PNG image format.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the PNG image file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object derived from the PNG image.

#### Response Example
N/A
```

--------------------------------

### Save Colour Swatch as Image File

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Saves a ColourSwatch object as an image file, supporting formats like .png, .jpg, and .webp. It requires a file path and a ColourSwatch object. This functionality is provided by the io.py module.

```python
def saveSwatch_IMAGE(file: str | Path, colourSwatch: ColourSwatch) -> None: ...
```

--------------------------------

### GimpGplPalette Equality Comparison

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/gimpgplpal.md

Compares the current GimpGplPalette object with another GimpGplPalette object for equality. Returns a boolean indicating if the palettes are identical.

```python
def __eq__(self, other: GimpGplPalette) -> bool: ...
```

--------------------------------

### Save Colour Swatch as ASE

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Saves a colour swatch to a file in the .ase (Adobe Swatch Exchange) format. It requires a file path and a ColourSwatch object, returning NoReturn.

```python
def saveSwatch_ASE(file: str | Path, colourSwatch: ColourSwatch) -> NoReturn: ...
```

--------------------------------

### POST /saveSwatch_IMAGE

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Save a colour swatch as an image file (.png, .jpg, .webp). This endpoint takes a file path and a ColourSwatch object to save the swatch.

```APIDOC
## POST /saveSwatch_IMAGE

### Description
Save a colour swatch as .png, .jpg, .webp.

### Method
POST

### Endpoint
/saveSwatch_IMAGE

### Parameters
#### Request Body
- **file** (str | Path) - Required - The file path to save the swatch.
- **colourSwatch** (ColourSwatch) - Required - The ColourSwatch object to save.
```

--------------------------------

### Read Adobe Swatch Exchange (.ASE) Files in Python

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

The openSwatch_ASE function is specifically designed to parse Adobe Swatch Exchange (.ase) files. It reads the contents of an .ase file and returns a list of ColourSwatch objects, allowing for the import of color palettes from Adobe applications.

```python
def openSwatch_ASE(file: str | Path) -> list[ColourSwatch]: ...
```

--------------------------------

### Save Colour Swatch as .TOML

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Serializes a ColourSwatch object into a .TOML file. The function requires a file path and the ColourSwatch object. It is implemented in the io.py module.

```python
def saveSwatch_TOML(file: str | Path, colourSwatch: ColourSwatch) -> None: ...
```

--------------------------------

### Save Colour Palette Files with Python

Source: https://context7.com/fhpythonutils/colourswatch/llms.txt

Illustrates the use of the `saveColourSwatch()` function to export `ColourSwatch` objects into various supported file formats. This function automatically handles colour conversions, enabling easy export to formats like YAML, JSON, PNG, and SVG.

```python
from colourswatch.io import openColourSwatch, saveColourSwatch

# Open a palette and convert to different formats
palette = openColourSwatch("source.gpl")

# Save to various formats
saveColourSwatch("output.yaml", palette)      # YAML format
saveColourSwatch("output.json", palette)      # JSON format
saveColourSwatch("output.colors", palette)    # KDE KOffice format
saveColourSwatch("output.soc", palette)       # LibreOffice format
saveColourSwatch("output.xml", palette)       # Scribus format
saveColourSwatch("output.pal", palette)       # CorelDraw/PaintShopPro format
saveColourSwatch("output.png", palette)       # Image palette (16x16 px per colour)
saveColourSwatch("output.svg", palette)       # SVG visual palette
```

--------------------------------

### POST /saveSwatch_TOML

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Save a colour swatch as .TOML format. This endpoint takes a file path and a ColourSwatch object to save the swatch.

```APIDOC
## POST /saveSwatch_TOML

### Description
Save a colour swatch as .TOML format.

### Method
POST

### Endpoint
/saveSwatch_TOML

### Parameters
#### Request Body
- **file** (str | Path) - Required - The file path to save the swatch.
- **colourSwatch** (ColourSwatch) - Required - The ColourSwatch object to save.
```

--------------------------------

### Save Colour Swatch to File

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Saves a colour swatch or a list of colour swatches to a specified file. It handles different colour swatch objects and can raise a ValueError for invalid inputs.

```python
def saveColourSwatch(
    file: str | Path, colourSwatch: ColourSwatch | list[ColourSwatch]
) -> None: ...
```

--------------------------------

### POST /saveSwatch_PSPPAL

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Save a colour swatch as PaintShopPro .PAL format. This endpoint takes a file path and a ColourSwatch object to save the swatch.

```APIDOC
## POST /saveSwatch_PSPPAL

### Description
Save a colour swatch as PaintShopPro .PAL.

### Method
POST

### Endpoint
/saveSwatch_PSPPAL

### Parameters
#### Request Body
- **file** (str | Path) - Required - The file path to save the swatch.
- **colourSwatch** (ColourSwatch) - Required - The ColourSwatch object to save.
```

--------------------------------

### openSwatch_IMAGE

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/io.md

Opens an image file and extracts color swatches from it. This function allows for generating color palettes from image data.

```APIDOC
## openSwatch_IMAGE

### Description
Opens an image file and extracts color swatches from it. Allows for generating color palettes from image data.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **file** (str | Path) - Required - The path to the image file.

### Request Example
N/A

### Response
#### Success Response (200)
- **ColourSwatch**: A ColourSwatch object derived from the image.

#### Response Example
N/A
```

--------------------------------

### ColourSwatch Class Methods

Source: https://github.com/fhpythonutils/colourswatch/blob/master/documentation/reference/colourswatch/colourswatch.md

Details on the methods available for the ColourSwatch class, used to represent a collection of colors.

```APIDOC
## ColourSwatch Class Methods

### Description
Represents a collection of colors, forming a color swatch.

### Methods

#### `ColourSwatch.__init__`
*   **Description**: Initializes a ColourSwatch object.
*   **Signature**: `__init__(self, name: str, colours: list[Colour] | None = None, swatchId: str | None = None, description: str | None = None, swatchCopyright: str | None = None, author: str | None = None) -> None`

#### `ColourSwatch.__eq__`
*   **Description**: Compares two ColourSwatch objects for equality.
*   **Signature**: `__eq__(self, other: ColourSwatch) -> bool`

#### `ColourSwatch.__repr__`
*   **Description**: Returns a string representation of the ColourSwatch object.
*   **Signature**: `__repr__(self) -> str`

#### `ColourSwatch.__str__`
*   **Description**: Returns a user-friendly string representation of the ColourSwatch object.
*   **Signature**: `__str__(self) -> str`

#### `ColourSwatch.toPILPalette`
*   **Description**: Converts the ColourSwatch to a PIL compatible palette.
*   **Signature**: `toPILPalette(self) -> list[tuple[int, int, int]]`
```