API Reference¶

Welcome to the API reference for Spytula. This section provides detailed information about the classes, methods, and attributes available in the Spytula library.

SpytulaBuilder¶

The SpytulaBuilder class is the main class in Spytula that allows you to construct JSON and YAML data structures.

Bases: DataFormattingMixin

Parameters:

Name	Type	Description	Default
`root`	`str`	The root key for the output JSON.	`None`

add_node ¶

add_node(node_list)

Add a new node to the given list.

Parameters:

Name	Type	Description	Default
`node_list`	`List[Dict[str, Any]]`	The list to which the node will be added.	required

Example

with builder.add_node(ingredient_list) as ingredient_builder:
    ingredient_builder.attribute("name", "Ramen Noodles")

attribute ¶

attribute(key, value)

Add a new attribute to the JSON.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key for the new attribute in the JSON.	required
`value`	`Any`	The value of the new attribute.	required

Example

builder.attribute("name", "Ramen Noodles")

attributes ¶

attributes(obj, keys)

Add multiple new attributes to the JSON.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object from which the attributes' values will be retrieved.	required
`keys`	`List[str]`	A list of the keys for the new attributes in the JSON.	required

Example

ramen = {'name': 'Tonkotsu Ramen', 'type': 'Pork-based'}
builder.attributes(ramen, ['name', 'type'])

each ¶

each(key, items)

Iterate over a list of items and create a nested context for each item.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key for the new list in the JSON.	required
`items`	`List[Dict[str, Any]]`	The list of items to iterate over.	required

Returns:

Type	Description
`List[Tuple[SpytulaBuilder, Dict[str, Any]]]`	List[Tuple[SpytulaBuilder, Dict[str, Any]]]: A list of tuples containing the SpytulaBuilder instance and the current item.

Example

ingredients = [
    {'name': 'Noodles', 'type': 'Main'},
    {'name': 'Pork', 'type': 'Protein'},
    {'name': 'Eggs', 'type': 'Topping'},
    {'name': 'Miso', 'type': 'Flavoring'},
]

for ingredient_builder, ingredient in builder.each('ingredients', ingredients):
    ingredient_builder.attribute('name', ingredient['name'])
    ingredient_builder.attribute('type', ingredient['type'])

merge ¶

merge(data)

Merge given dictionary into the JSON data.

Parameters:

Name	Type	Description	Default
`data`	`Dict[str, Any]`	Dictionary to merge.	required

Example

extra_info = {'rating': 4.5, 'spiciness': 'Medium'}
builder.merge(extra_info)

node ¶

node(key)

Create a new node to be added to the JSON.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key for the new node in the JSON.	required

Example

with builder.node("ingredients") as ingredient_builder:
    ingredient_builder.attribute("name", "Ramen Noodles")

nodes ¶

nodes(key)

Create a new list of nodes to be added to the JSON.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key for the new list in the JSON.	required

Example

ingredients = [
    {'name': 'Noodles', 'type': 'Main'},
    {'name': 'Pork', 'type': 'Protein'},
    {'name': 'Eggs', 'type': 'Topping'},
    {'name': 'Miso', 'type': 'Flavoring'},
]

with builder.nodes('ingredients') as add_ingredient:
    for ingredient in ingredients:
        with add_ingredient() as ingredient_builder:
            ingredient_builder.attribute('name', ingredient['name'])
            ingredient_builder.attribute('type', ingredient['type'].upper())

partial ¶

partial(other_builder)

Merge given SpytulaBuilder instance into the current instance.

Parameters:

Name	Type	Description	Default
`other_builder`	`SpytulaBuilder`	SpytulaBuilder instance to merge.	required

Example

other_builder = SpytulaBuilder()
other_builder.attribute('type', 'Ramen')
builder.partial(other_builder)

root ¶

root(key)

Set the root key for the output JSON.

Parameters:

Name	Type	Description	Default
`key`	`str`	The root key for the output JSON.	required

Example

builder = SpytulaBuilder()
builder.root("ramen")

to_json ¶

to_json(*args, **kwargs)

Convert the data to a JSON-formatted string.

Parameters:

Name	Type	Description	Default
`*args`		Additional positional arguments to pass to json.dumps.	`()`
`**kwargs`		Additional keyword arguments to pass to json.dumps.	`{}`

Returns:

Name	Type	Description
`str`	`str`	A JSON-formatted string representing the data.

Example

json_data = builder.to_json(indent=2)
print(json_data)

to_yaml ¶

to_yaml(*args, **kwargs)

Convert the data to a YAML-formatted string.

Parameters:

Name	Type	Description	Default
`*args`		Additional positional arguments to pass to yaml.dump.	`()`
`**kwargs`		Additional keyword arguments to pass to yaml.dump.	`{}`

Returns:

Name	Type	Description
`str`	`str`	A YAML-formatted string representing the data.

Example

yaml_data = builder.to_yaml()
print(yaml_data)

when ¶

when(key, value, condition)

Add a new attribute to the JSON when the condition is met.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key for the new attribute in the JSON.	required
`value`	`Any`	The value of the new attribute.	required
`condition`	`bool or callable`	Condition to be met. Can be a boolean or a lambda function that takes a value and returns a boolean.	required

Example

builder.when('has_noodles', True, True)