gscrib.formatters

G-code syntax and number formatting utilities.

This module provides utilities for formatting G-code output, including commands, parameters, comments, and numbers. It defines standard interfaces and implementations for consistent G-code generation.

class gscrib.formatters.BaseFormatter

Bases: ABC

Abstract base class for G-code formatting.

Defines the interface that all G-code formatters must implement.

abstractmethod command(command, params=None, comment=None)

Format a G-code command with optional parameters.

Parameters:

  • command (str) – The G-code command

  • params (dict | None) – Command parameters

  • comment (str | None) – Comment to append to the statement

Returns:

Formatted command statement string

Return type:

str

abstractmethod comment(text)

Format text as a G-code comment.

Parameters:

text (str) – Text to be formatted as a comment

Returns:

Formatted comment string

Return type:

str

abstractmethod line(statement)

Format a single G-code statement for output.

Parameters:

statement (str) – The G-code statement to format

Returns:

Formatted statement with proper line endings

Return type:

str

abstractmethod number(number)

Format a number with specified decimal places.

Parameters:

number (Number) – The number to format

Returns:

Formatted number string

Return type:

str

abstractmethod parameters(params)

Format G-code statement parameters.

Parameters:

params – Statement parameters

Returns:

Formatted parameters string

Return type:

str

abstractmethod set_axis_label(axis, label)

Set a custom label for an axis.

Parameters:

  • axis (Axis | str) – The axis to relabel

  • label (str) – The new label for the axis

Return type:

None

abstractmethod set_comment_symbols(value)

Set the comment symbols for G-code comments.

Parameters:

value (str) – Comment symbols to use

Return type:

None

abstractmethod set_decimal_places(value)

Set the maximum decimal places for number formatting.

Parameters:

value (int) – Number of decimal places

Return type:

None

abstractmethod set_line_endings(line_endings)

Set the line ending style.

Parameters:

line_endings (str) – Line ending style

Return type:

None

class gscrib.formatters.DefaultFormatter

Bases: BaseFormatter

Formats G-code output.

command(command, params=None, comment=None)

Format a G-code command with optional parameters.

Parameters:

  • command (str) – The G-code command (e.g., G0, G1, M104)

  • params (dict | None) – Dictionary of parameters and their values

  • comment (str | None) – Comment to append to the statement

Returns:

Formatted command statement string

Return type:

str

comment(text)

Format text as a G-code comment.

Parameters:

text (str) – Text to be formatted as a comment

Returns:

Formatted comment string

Return type:

str

line(statement)

Format a single G-code statement for output.

Parameters:

statement (str) – The G-code statement to format

Returns:

Formatted statement with proper line endings

Return type:

str

number(number)

Format a number with specified decimal places.

Parameters:

number (Number) – The number to format

Returns:

Formatted number string

Raises:

  • ValueError – If value is not finite

  • TypeError – If value is a complex number

  • typeguard.TypeCheckError – If value is not a number

Return type:

str

parameters(params)

Format G-code statement parameters.

Parameters:

params (dict) – Statement parameters

Returns:

Formatted parameters string

Return type:

str

set_axis_label(axis, label)

Set a custom label for an axis.

Parameters:

  • axis (Axis | str) – The axis to relabel (‘x’, ‘y’, or ‘z’)

  • label (str) – The new label for the axis

Raises:

ValueError – If axis is invalid or label is empty

set_comment_symbols(value)

Set the comment symbols for G-code comments.

Parameters:

value (str) – Comment symbols to use (non-empty string)

Raises:

ValueError – If value is empty or not a string

Return type:

None

set_decimal_places(value)

Set the maximum number of decimal places for number formatting.

Parameters:

value (int) – Number of decimal places (non-negative integer)

Raises:

ValueError – If value is negative

Return type:

None

set_line_endings(line_endings)

Set the line ending style.

Parameters:

line_endings (str) – Line ending style (‘os’ or custom string)