Reference
Common types
json4humans.protocol
This modules provides the JSONModule protocol as well as some related helpers.
LexerType = Literal['auto', 'basic', 'contextual', 'dynamic', 'complete_dynamic']
module-attribute
Lark supported lexer types
JSONEncoder
JSONModule
Bases: Protocol
Protocol for JSON modules implemnentation.
Each implementation must be defined as module implementing this protocol.
transformer: Transformer
class-attribute
The default tranformer instance
dump(obj, out, *, cls=None, indent=None)
Serialize obj to a file-like object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj |
Any
|
The object to serialize as JSON. |
required |
cls |
type[JSONEncoder] | None
|
An encoder class to use. Will use the default module encoder if |
None
|
indent |
str | int | None
|
Indentation to use, either an integer defining the number of spaces or a string representing the indentation characters to be used as indentation. |
None
|
out |
TextIO | Path
|
A file-like object or path to a file to serialize to JSON into. |
required |
dumps(obj, *, cls=None, indent=None)
Serialize obj to a string.
The parameters have the same meaning as dump()
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj |
Any
|
The object to serialize as JSON. |
required |
cls |
type[JSONEncoder] | None
|
An encoder class to use. Will use the default module encoder if |
None
|
indent |
str | int | None
|
Indentation to use, either an integer defining the number of spaces or a string representing the indentation characters to be used as indentation. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
The serialized object as a JSON string representation. |
load(file)
loads(src)
Loads data from a string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
src |
str
|
Some JSON data as string. |
required |
implement(grammar, transformer, encoder, lexer='auto')
A JSON module attributes factory.
Only provide the grammar, the transformer, the encoder class (and a few optional parameters) and this factory will create all the missing helpers and boiler plate to implement JSONModule in the caller module.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
grammar |
str
|
the base name of the grammar (will use the Lark grammar of the same name) |
required |
transformer |
Transformer
|
the instanciated tranformer for this grammar |
required |
encoder |
type[JSONEncoder]
|
the default encoder class used on serialization |
required |
lexer |
LexerType
|
optionaly specify a lexer implementation for Lark |
'auto'
|
json4humans.types
This modules contains all shared and reausable types supporting style preservation.
Most of the time you won't have to instanciate them manually.
Member = tuple[Key, Value]
module-attribute
A Key-Value pair in an Object
Value = Object | Array | String | Number | Literal | bool | None
module-attribute
A type alias matching the JSON Value.
WSC = WhiteSpace | Comment
module-attribute
A whitespace or a comment
BlockStyleComment
Bases: Comment
Stores a block-style comment (ie. starting with /* and ending with */)
Comment
Container
HashStyleComment
Bases: Comment
Stores a hash-style comment (ie. starting with # and ending at the end of the current line)
HexInteger
JSONType
Base class for parsed types with style and metadata preservation.
LineStyleComment
Bases: Comment
Stores a line-style comment (ie. starting with // and ending at the end of the current line)
Literal
Number
Bases: JSONType
Base class for all Number types and representations.
prefixed: bool
class-attribute
Is the number prefixed by an explicit sign
Object
Bases: OrderedDict, Container
A JSON Object with order and style preservation
Quote
WhiteSpace
json4humans.wsc
This module handles whitespaces and comments
WSCTransformer
encode_wsc(wsc)
parse(wsc)
json4humans.style
This modules provides some helpers to handle style preservation.
JSONEncoderBoundMethod: TypeAlias = Callable[[T], str]
module-attribute
A JSON encoder bound type method
JSONEncoderMethod: TypeAlias = Callable[[Encoder, T], str]
module-attribute
A JSON encoder type method
StylePreservingTransformer
Supported formats
json4humans.json
This module implements the JSONModule protocol for JSON.
While JSON is natively supported by Python standard library, the builtin module doesn't provide style preservation.
This one do by returning style preserving types storing whitespaces.
JSONEncoder
JSONTransformer
json4humans.jsonc
This module provides supprot for the JSONC file format
This is a format introduced by github/Microsoft in VSCode. This is basically standard JSON with both line and block comments supports as well as optionnal trailing coma support.
JSONCTransformer
Bases: StylePreservingTransformer
A Transformer for JSONC aka. JSON with Comments
json4humans.json5
This module implements the JSON module protocol for JSON5.
The JSON5 Data Interchange Format (JSON5) is a superset of JSON that aims to alleviate some of the limitations of JSON by expanding its syntax to include some productions from ECMAScript 5.1.
See: specifications