Skip to content

API reference#

Parse: Sled to Python dict#

from_sled #

Python
from_sled(text: str) -> dict[str, Entity]

Parse the input text into a Python dict.

The input text should be a valid Sled document. Otherwise, raises an InvalidSledError.

Serialize: Python object to Sled#

to_sled #

Python
to_sled(obj: object, *, indent: str = DEFAULT_INDENT, use_top_level_braces: bool = DEFAULT_USE_TOP_LEVEL_BRACES, line_separator: LineSeparator = DEFAULT_LINE_SEPARATOR, always_quote: bool = DEFAULT_ALWAYS_QUOTE, break_on_line_separator: bool = DEFAULT_BREAK_ON_LINE_SEPARATOR, ascii_only: bool = DEFAULT_ASCII_ONLY, quote_mark: QuoteMarkType = DEFAULT_QUOTE_MARK, hex_upper_case: bool = DEFAULT_HEX_UPPER_CASE, hex_horizontal_separator: HexHorizontalSeparator = DEFAULT_HEX_HORIZONTAL_SEPARATOR, hex_bytes_per_separator: int = DEFAULT_HEX_BYTES_PER_SEPARATOR, hex_line_length: int = DEFAULT_HEX_LINE_LENGTH, decimal_mark: DecimalMarkType = DEFAULT_DECIMAL_MARK, exponent_prefix: ExponentPrefixType = DEFAULT_EXPONENT_PREFIX, use_thousands_separator: bool = DEFAULT_USE_THOUSANDS_SEPARATOR) -> str

Serializes the input obj as a (top level) Sled document.

The input obj must be a dataclass or a Mapping where: - every key must be serialized as a Sled string - every value must either be an Entity instance or have a to_sled_serializable() method that returns an Entity instance

If the input obj is both a Mapping and a dataclass, it will be serialized as a Mapping.

This function has the same configuration options and defaults as SledSerializer. For details, the SledSerializer documentation below.

Example:

Python
data = {
    "name": "John Doe",
    "age": 50,
    "children": ["Jack", "Jill"],
}
sled_output = to_sled(data)

Sled output:

Text Only
name = "John Doe"
age = 50
children = [
  Jack
  Jill
]

SledSerializer #

Converts Python objects to Sled.

Example:

Python
data = {
    "name": "John Doe",
    "age": 50,
    "children": ["Jack", "Jill"],
}
sled_serializer = SledSerializer()
sled_output = sled_serializer.to_sled(data)

Sled output:

Text Only
name = "John Doe"
age = 50
children = [
  Jack
  Jill
]

__init__ #

Python
__init__(*, indent: str = DEFAULT_INDENT, use_top_level_braces: bool = DEFAULT_USE_TOP_LEVEL_BRACES, line_separator: LineSeparator = DEFAULT_LINE_SEPARATOR, always_quote: bool = DEFAULT_ALWAYS_QUOTE, ascii_only: bool = DEFAULT_ASCII_ONLY, break_on_line_separator: bool = DEFAULT_BREAK_ON_LINE_SEPARATOR, quote_mark: QuoteMarkType = DEFAULT_QUOTE_MARK, hex_upper_case: bool = DEFAULT_HEX_UPPER_CASE, hex_horizontal_separator: HexHorizontalSeparator = DEFAULT_HEX_HORIZONTAL_SEPARATOR, hex_bytes_per_separator: int = DEFAULT_HEX_BYTES_PER_SEPARATOR, hex_line_length: int = DEFAULT_HEX_LINE_LENGTH, decimal_mark: DecimalMarkType = DEFAULT_DECIMAL_MARK, exponent_prefix: ExponentPrefixType = DEFAULT_EXPONENT_PREFIX, use_thousands_separator: bool = DEFAULT_USE_THOUSANDS_SEPARATOR) -> None
PARAMETER DESCRIPTION
indent #

The incremental indent added for each layer of nesting. Can only contain spaces and tabs.

TYPE: str DEFAULT: DEFAULT_INDENT

use_top_level_braces #

If True, encloses the top level key-value pairs in an outermost pair of curly braces, like a map (i.e. the Sled document as a whole is a Sled map). Otherwise, the top level key-value pairs are left unenclosed.

TYPE: bool DEFAULT: DEFAULT_USE_TOP_LEVEL_BRACES

line_separator #

The str with which to separate adjacent lines.

TYPE: LineSeparator DEFAULT: DEFAULT_LINE_SEPARATOR

always_quote #

If True, always serialize each str as a quote (never identity, even where the content of a str is such that it could be serialized as an identity). Otherwise, serialize as an identity where possible. Does NOT apply to segments inside any concat emitted; each segment within the concat must always be a quote. NOTE: If break_on_line_separator, each str containing the line_separator will be serialized as a concat.

TYPE: bool DEFAULT: DEFAULT_ALWAYS_QUOTE

ascii_only #

If True, escape all non-ASCII symbols in each str, so that the serialization output contains only ASCII characters. Otherwise, escape only disallowed characters.

TYPE: bool DEFAULT: DEFAULT_ASCII_ONLY

break_on_line_separator #

If True, each str containing the line_separator will be serialized as a concat, with segments based on each occurrence of the line_separator. Otherwise, never use concat.

TYPE: bool DEFAULT: DEFAULT_BREAK_ON_LINE_SEPARATOR

quote_mark #

Symbol with which to enclose each quote.

TYPE: QuoteMarkType DEFAULT: DEFAULT_QUOTE_MARK

hex_upper_case #

If True, the hexadecimal letters 'A' thru 'F' will be in upper case. Otherwise, they will be in lower case.

TYPE: bool DEFAULT: DEFAULT_HEX_UPPER_CASE

hex_horizontal_separator #

Character (if any) with which to separate adjacent groups of hexadecimal characters.

TYPE: HexHorizontalSeparator DEFAULT: DEFAULT_HEX_HORIZONTAL_SEPARATOR

hex_bytes_per_separator #

Defines the length of each group of hexadecimal characters by the number of bytes that they represent. Two hexadecimal characters represent a byte, so the number of hexadecimal characters per group is twice this number. Positive values count from the right, negative from the left. If 0, hexadecimal characters will not be grouped.

TYPE: int DEFAULT: DEFAULT_HEX_BYTES_PER_SEPARATOR

hex_line_length #

Max number of characters per line in hex content, excluding any indentation. If 0, hex content will not be split into multiple lines.

TYPE: int DEFAULT: DEFAULT_HEX_LINE_LENGTH

decimal_mark #

Symbol to use for separating the integer part and fractional part of each float. Can be either the period (.) or the comma (,).

TYPE: DecimalMarkType DEFAULT: DEFAULT_DECIMAL_MARK

exponent_prefix #

Character with which to prefix the exponent (if any) in each float. Can be either upper (E) or lower (e) case.

TYPE: ExponentPrefixType DEFAULT: DEFAULT_EXPONENT_PREFIX

use_thousands_separator #

If True, separate digits into thousands (groups of 3) using the underscore (_). Otherwise, don't separate digits into groups.

TYPE: bool DEFAULT: DEFAULT_USE_THOUSANDS_SEPARATOR

to_sled #

Python
to_sled(obj: object) -> str

Serializes the input obj as a (top level) Sled document.

The input obj must be a dataclass or a Mapping where: - every key must be serialized as a Sled string - every value must either be an Entity instance or have a to_sled_serializable() method that returns an Entity instance

If the input obj is both a Mapping and a dataclass, it will be serialized as a Mapping.

Mini serialization#

to_sled_mini #

Python
to_sled_mini(obj: object, *, use_top_level_braces: bool = DEFAULT_USE_TOP_LEVEL_BRACES, always_quote: bool = DEFAULT_ALWAYS_QUOTE, ascii_only: bool = DEFAULT_ASCII_ONLY, quote_mark: QuoteMarkType = DEFAULT_QUOTE_MARK, hex_upper_case: bool = DEFAULT_HEX_UPPER_CASE, decimal_mark: DecimalMarkType = DEFAULT_DECIMAL_MARK, exponent_prefix: ExponentPrefixType = DEFAULT_EXPONENT_PREFIX) -> str

Serializes the input obj as a minified (top level) Sled document. Produces a serialization output that is more compact but less human-friendly.

This function has the same configuration options and defaults as SledSerializerMini. For details, refer to the SledSerializerMini documentation below.

The input obj must be a Mapping or dataclass that does NOT have a to_sled_serializable() method, or an object with such a method returning such a Mapping or dataclass.

If the input obj is both a Mapping and a dataclass, it will be serialized as a Mapping.

Example:

Python
data = {
    "name": "John Doe",
    "age": 50,
    "children": ["Jack", "Jill"],
}
sled_output = to_sled_mini(data)

Sled output:

Text Only
name="John Doe";age=50;children=[Jack;Jill]

SledSerializerMini #

Converts Python objects to minified Sled. Produces a serialization output that is more compact but less human-friendly.

Example:

Python
data = {
    "name": "John Doe",
    "age": 50,
    "children": ["Jack", "Jill"],
}
sled_serializer = SledSerializer()
sled_output = sled_serializer.to_sled(data)

Sled output:

Text Only
name="John Doe";age=50;children=[Jack;Jill]

__init__ #

Python
__init__(*, use_top_level_braces: bool = DEFAULT_USE_TOP_LEVEL_BRACES, always_quote: bool = DEFAULT_ALWAYS_QUOTE, ascii_only: bool = DEFAULT_ASCII_ONLY, quote_mark: QuoteMarkType = DEFAULT_QUOTE_MARK, hex_upper_case: bool = DEFAULT_HEX_UPPER_CASE, decimal_mark: DecimalMarkType = DEFAULT_DECIMAL_MARK, exponent_prefix: ExponentPrefixType = DEFAULT_EXPONENT_PREFIX) -> None
PARAMETER DESCRIPTION
use_top_level_braces #

If True, encloses the top level key-value pairs in an outermost pair of curly braces, like a map (i.e. the Sled document as a whole is a Sled map). Otherwise, the top level key-value pairs are left unenclosed.

TYPE: bool DEFAULT: DEFAULT_USE_TOP_LEVEL_BRACES

always_quote #

If True, always serialize each str as a quote (never identity, even where the content of a str is such that it could be serialized as an identity). Otherwise, serialize as an identity where possible.

TYPE: bool DEFAULT: DEFAULT_ALWAYS_QUOTE

ascii_only #

If True, escape all non-ASCII symbols in each str, so that the serialization output contains only ASCII characters. Otherwise, escape only disallowed characters.

TYPE: bool DEFAULT: DEFAULT_ASCII_ONLY

quote_mark #

Symbol with which to enclose each quote.

TYPE: QuoteMarkType DEFAULT: DEFAULT_QUOTE_MARK

hex_upper_case #

If True, the hexadecimal letters 'A' thru 'F' will be in upper case. Otherwise, they will be in lower case.

TYPE: bool DEFAULT: DEFAULT_HEX_UPPER_CASE

decimal_mark #

Symbol to use for separating the integer part and fractional part of each float. Can be either the period (.) or the comma (,).

TYPE: DecimalMarkType DEFAULT: DEFAULT_DECIMAL_MARK

exponent_prefix #

Character with which to prefix the exponent (if any) in each float. Can be either upper (E) or lower (e) case.

TYPE: ExponentPrefixType DEFAULT: DEFAULT_EXPONENT_PREFIX

to_sled #

Python
to_sled(obj: object) -> str

Serializes the input obj as a (top level) Sled document.

The input obj must be a dataclass or a Mapping where: - every key must be serialized as a Sled string - every value must either be an Entity instance or have a to_sled_serializable() method that returns an Entity instance

If the input obj is both a Mapping and a dataclass, it will be serialized as a Mapping.