lesscpy - Python LESS Compiler

Common errors

• lesscpy.lessc.errors.LesscpySyntaxError: Syntax Error: Unexpected '@' at line X, col Y

  cause The LESS code contains syntax not supported by `lesscpy`, likely a newer LESS feature or a subtle deviation from `lesscpy`'s parsing capabilities.
  fix Review the LESS code for advanced features. Try to simplify the LESS or adapt it to `lesscpy`'s known capabilities. If possible, test the problematic LESS snippet against an official LESS compiler to confirm its validity.

• FileNotFoundError: [Errno 2] No such file or directory: 'path/to/imported/file.less'

  cause An `@import` directive within your LESS file refers to a file that `lesscpy` cannot locate. This is often due to incorrect relative paths or the file not being in `lesscpy`'s expected search path.
  fix Verify that all `@import` paths are correct and relative to the main LESS file being compiled. If compiling LESS from a string that has `@import`s, ensure the imported files are accessible in the current working directory or `lesscpy` might need configuration (though this is less common for simple string compilation).

• UnicodeDecodeError: 'charmap' codec can't decode byte 0x81 in position X: character maps to <undefined>

  cause `lesscpy` attempted to read a LESS file or input string with an incorrect character encoding, often defaulting to a system-specific encoding instead of UTF-8.
  fix When reading LESS files, explicitly specify the encoding, e.g., `with open('file.less', 'r', encoding='utf-8') as f: lesscpy.compile(f, ...)`.

Warnings

• gotcha Due to lack of active development since 2018, `lesscpy` may not fully support newer LESS features (e.g., modern CSS Grid functions, advanced color functions, or recent syntax improvements).
  Fix: For projects requiring the latest LESS features, consider using the official Node.js LESS compiler or a more actively maintained alternative. For existing `lesscpy` projects, limit LESS usage to features available prior to 2018.
• gotcha File system operations and path resolution within LESS files (e.g., `@import` directives) can be sensitive to the current working directory or system encoding, potentially leading to `FileNotFoundError` or `UnicodeDecodeError`.
  Fix: Ensure all paths in `@import` directives are correct and relative to the input LESS file. Explicitly handle file I/O with UTF-8 encoding (e.g., `open('file.less', 'r', encoding='utf-8')`).

Install

• pip install lesscpy Install latest version

Imports

• compile

  from lesscpy import compile

  This is the main function to compile LESS code. It's also commonly accessed as `lesscpy.compile` after a general `import lesscpy`.

Quickstart

This quickstart demonstrates how to compile a LESS string into minified CSS using the `lesscpy.compile` function, which accepts a file-like object (like `StringIO`) as input.

from io import StringIO
import lesscpy

# Example LESS code as a string
less_code = """
@primary-color: #3498db;
@spacing: 10px;

.container {
  max-width: 960px;
  margin: 0 auto;
  padding: @spacing;

  h1 {
    color: @primary-color;
    margin-bottom: @spacing * 2;
  }

  p {
    line-height: 1.6;
  }
}

.button {
  background-color: @primary-color;
  color: white;
  padding: @spacing @spacing * 2;
  border: none;
  cursor: pointer;

  &:hover {
    opacity: 0.9;
  }
}
"""

# Compile the LESS code from a StringIO object
# lesscpy.compile expects a file-like object or a filename string.
# The 'minify' argument is common for output control.
css_output = lesscpy.compile(StringIO(less_code), minify=True)

print("--- Compiled and Minified CSS ---")
print(css_output)