💾 io#

Reading and writing pack files: functions, advancements, JSON and cached models.

deprecated#

write_function_tag(path: str, functions: list[~typing.Any] | None = None, prepend: bool = False, max_level: int | None = None, condition: ~collections.abc.Callable[[list[~typing.Any]], bool] = <function <lambda>>) → TagFile | None[source]#

write_function_tag is deprecated, prefer using write_tag or tags argument of write_function instead

dicts#

super_merge_dict(
dict1: JsonDict,
dict2: JsonDict,
) → JsonDict[source]#

Merge two dictionaries recursively without modifying them, dict2 winning and lists merged without duplicates.

>>> super_merge_dict({"a": 1}, {"b": 2})
{'a': 1, 'b': 2}
>>> super_merge_dict({"a": 1}, {"a": 99})
{'a': 99}
>>> super_merge_dict({"nested": {"x": 1, "y": 2}}, {"nested": {"y": 99, "z": 3}})
{'nested': {'x': 1, 'y': 99, 'z': 3}}
>>> super_merge_dict({"tags": ["a", "b"]}, {"tags": ["b", "c"]})
{'tags': ['a', 'b', 'c']}
>>> result = super_merge_dict({"items": [{"id": 1}]}, {"items": [{"id": 2}]})
>>> result["items"]
[{'id': 1}, {'id': 2}]

files#

set_json_encoder(
obj: JsonFileT,
max_level: int | None = None,
indent: str | int = '\t',
) → JsonFileT[source]#

Set the encoder of the given object to json_dump

Parameters:
  • obj – The object to set the encoder for

  • max_level – The maximum level of the JSON dump, or None for default behavior

  • indent – The indentation character (default: ‘ ‘)

Returns:

The object with the encoder set

Return type:

JsonFile

texture_mcmeta(
source_path: str,
) → Texture[source]#

Create a Texture object with mcmeta if found

Parameters:

source_path – The path to the texture (ex: “assets/textures/texture_name.png”)

Returns:

The texture object

Return type:

Texture

functions#

McFunction = McFunction[source]#

Commands, as a string. Annotating a variable with it is what colours the commands inside it.

A TextMate grammar matches one place at a time and cannot tell that content reaches a write_* call further down, so the author states the intent instead. notes: str = """...""" stays plain Python.

write_tag(path: str, tag_type: ~beet.library.base.NamespaceProxy[~typing.Any] | ~beet.library.base.NamespaceContainer[~typing.Any], values: list[~typing.Any] | None = None, prepend: bool = False, max_level: int | None = None, condition: ~collections.abc.Callable[[list[~typing.Any]], bool] = <function <lambda>>) → TagFile | None[source]#

Write a function tag at the given path.

Parameters:
  • path – The path to the function tag, ex: “namespace:something” for ‘data/namespace/tags/function/something.json’

  • tag_type – The tag type to write to (ex: ctx.data.function_tags)

  • values – The values to add to the tag

  • prepend – If the values should be prepended instead of appended

  • max_level – The maximum level of the JSON dump, None for default behavior (default: None)

  • condition – Whether to write the new values, given the existing ones (default: always write)

Returns:

The written tag, or None if the condition was not met

Return type:

TagFile | None

read_function(path: str) → str[source]#

Read the content of a function at the given path.

Parameters:

path – The path to the function (ex: “namespace:folder/function_name”)

Returns:

The content of the function, or an empty string if the function does not exist

Return type:

str

write_function(
path: str,
content: str,
overwrite: bool = False,
prepend: bool = False,
tags: list[str] | None = None,
condition: Callable[[str], bool] | None = None,
) → Function | None[source]#

Write the content to the function at the given path.

Parameters:
  • path – The path to the function (ex: “namespace:folder/function_name”)

  • content – The content to write

  • overwrite – If the file should be overwritten (default: Append the content)

  • prepend – Prepend the content instead of appending it (ignored if overwrite is True)

  • tags – The function tags to add to the function, ex: [“namespace:something”] for ‘data/namespace/tags/function/something.json’

  • condition – Whether to write, given the existing content (default: None, always write)

Returns:

The written function, or None if the condition was not met

Return type:

Function | None

write_versioned_function(
path: str,
content: str,
overwrite: bool = False,
prepend: bool = False,
tags: list[str] | None = None,
condition: Callable[[str], bool] | None = None,
) → Function | None[source]#

Write the content to a versioned function at the given path.

Parameters:
  • path – The path to the function (ex: “folder/function_name”)

  • content – The content to write

  • overwrite – If the file should be overwritten (default: Append the content)

  • prepend – Prepend the content instead of appending it (ignored if overwrite is True)

  • tags – The function tags to add to the function, ex: [“namespace:something”] for ‘data/namespace/tags/function/something.json’

  • condition – Whether to write, given the existing content (default: None, always write)

write_load_file(
content: str,
overwrite: bool = False,
prepend: bool = False,
tags: list[str] | None = None,
condition: Callable[[str], bool] | None = None,
) → Function | None[source]#

Write the content to the load file

Parameters:
  • content – The content to write

  • overwrite – If the file should be overwritten (default: Append the content)

  • prepend – Prepend the content instead of appending it (ignored if overwrite is True)

  • tags – The function tags to add to the function, ex: [“namespace:something”] for ‘data/namespace/tags/function/something.json’

  • condition – Whether to write, given the existing content (default: None, always write)

write_unload_file(
content: str,
overwrite: bool = False,
prepend: bool = False,
tags: list[str] | None = None,
condition: Callable[[str], bool] | None = None,
) → Function | None[source]#

Write the content to the unload file

Parameters:
  • content – The content to write

  • overwrite – If the file should be overwritten (default: Append the content)

  • prepend – Prepend the content instead of appending it (ignored if overwrite is True)

  • tags – The function tags to add to the function, ex: [“namespace:something”] for ‘data/namespace/tags/function/something.json’

  • condition – Whether to write, given the existing content (default: None, always write)

write_tick_file(
content: str,
overwrite: bool = False,
prepend: bool = False,
tags: list[str] | None = None,
condition: Callable[[str], bool] | None = None,
) → Function | None[source]#

Write the content to the tick file

Parameters:
  • content – The content to write

  • overwrite – If the file should be overwritten (default: Append the content)

  • prepend – Prepend the content instead of appending it (ignored if overwrite is True)

  • tags – The function tags to add to the function, ex: [“namespace:something”] for ‘data/namespace/tags/function/something.json’

  • condition – Whether to write, given the existing content (default: None, always write)

write_scheduled_function(duration: int | str, content: str, unit: str = 't', path: str | None = None, overwrite: bool = False, prepend: bool = False, condition: ~collections.abc.Callable[[str], bool] = <function <lambda>>) → Function | None[source]#

Write a self-rescheduling function and schedule it on load.

Parameters:
  • duration – Delay before re-execution. If it’s a digit-only string, it is converted to int.

  • content – Function content to execute.

  • unit – Time unit used only when duration is int (default: “t”).

  • path – Target function path. Defaults to “{project_id}:v{project_version}/scheduled/{duration}”.

  • overwrite – If True, overwrite target files instead of appending.

  • prepend – If True, prepend content instead of appending (ignored when overwrite is True).

  • condition – Whether to write the new content, given the existing one (default: always write)

json_resources#

Writing JSON pack resources by path, merged into whatever another plugin already wrote there.

write_json_resource(registry: ~collections.abc.MutableMapping[str, T], file_type: type[T], path: str, data: T | ~stouputils.typing.aliases.JsonDict, overwrite: bool = False, max_level: int = -1, condition: ~collections.abc.Callable[[~stouputils.typing.aliases.JsonDict], bool] = <function <lambda>>) → T | None[source]#

Write a JSON resource of any registry, merging it into the existing one with super_merge_dict.

Parameters:
  • registry – Where it goes (ex: Mem.ctx.data.item_modifiers)

  • file_type – Its beet class (ex: ItemModifier)

  • path – Its resource location (ex: “namespace:folder/name”), with or without “.json”

  • overwrite – Replace the existing resource instead of merging into it

  • max_level – Maximum depth of the JSON dump, -1 for the default

  • condition – Receives the existing data and decides whether to write at all

Returns:

The written resource, or None when the condition refused it

write_advancement(path: str, advancement: ~beet.library.data_pack.Advancement | ~stouputils.typing.aliases.JsonDict, overwrite: bool = False, max_level: int = -1, condition: ~collections.abc.Callable[[~stouputils.typing.aliases.JsonDict], bool] = <function <lambda>>) → Advancement | None[source]#

Write an advancement (ex: “namespace:folder/name”), see write_json_resource for the options.

write_predicate(path: str, predicate: ~beet.library.data_pack.Predicate | ~stouputils.typing.aliases.JsonDict, overwrite: bool = False, max_level: int = -1, condition: ~collections.abc.Callable[[~stouputils.typing.aliases.JsonDict], bool] = <function <lambda>>) → Predicate | None[source]#

Write a predicate (ex: “namespace:is_sneaking”), see write_json_resource for the options.

write_enchantment(path: str, enchantment: ~beet.library.data_pack.Enchantment | ~stouputils.typing.aliases.JsonDict, overwrite: bool = False, max_level: int = -1, condition: ~collections.abc.Callable[[~stouputils.typing.aliases.JsonDict], bool] = <function <lambda>>) → Enchantment | None[source]#

Write an enchantment (ex: “namespace:lifesteal”), see write_json_resource for the options.

model_cache#

MODEL_CACHE_NAME: str = 'stewbeet_model_encoder'[source]#

Name of the beet cache holding serialized models.

MODEL_CACHE_MAX_AGE: timedelta = datetime.timedelta(days=7)[source]#

Entries untouched for longer than this are dropped at the start of a build.

MODEL_CACHE_MIN_SIZE: int = 8192[source]#

Contents whose marshalled size is below this are serialized directly instead of cached.

Caching costs a directory lookup, a file read and a timestamp update, which together run to roughly 0.2ms per entry; serializing runs at roughly 55ms per megabyte. Below a few kilobytes the cache is therefore slower than simply doing the work, and on a pack with thousands of tiny json files that overhead adds up to more than it saves.

EXACT_JSON_TYPES: frozenset[type] = frozenset({<class 'NoneType'>, <class 'bool'>, <class 'float'>, <class 'int'>, <class 'str'>})[source]#

Types marshal accepts as-is, checked by identity since it rejects every subclass.

to_plain_builtin(value: Any) → Any[source]#

Rebuild a value out of dict, list, str, int, float, bool and None so marshal serializes it.

marshal rejects subclasses: a single Resource, a str but not exactly one, would make its model uncacheable. Values with the same plain form serialize to the same json text, so normalizing is safe, tuples becoming lists. marshal back-references repeated objects, so the key also depends on which values are the same object. Anything else is returned untouched, letting marshal reject it.

>>> to_plain_builtin({"a": (1, 2), "b": [None, True]})
{'a': [1, 2], 'b': [None, True]}
>>> class MyStr(str): pass
>>> plain = to_plain_builtin({"model": MyStr("ns:item/x")})
>>> plain, type(plain["model"]) is str
({'model': 'ns:item/x'}, True)
class ModelSerializationCache(directory: Path)[source]#

Bases: object

Content-addressed, cross-build cache of serialized models.

Serializing models dominates build time on packs that generate many variants of the same geometry: the elements array is by far the biggest part of a model file, and packs with camouflages / powered states / zoom levels emit the same geometry hundreds of times.

Entries are keyed on a hash of the model content itself, not on where it came from. That is what makes the cache safe to keep between builds: any change that alters a generated model: editing the source geometry, changing how models are built, upgrading StewBeet: changes the hash and misses the cache. There is no invalidation rule to keep in sync, and no way to serve a model that was generated by code that no longer exists.

The hash covers the encoder settings and the versions of everything involved in producing the text (Python, marshal, stouputils), since those decide the formatting rather than the content. marshal is used to turn the model into bytes because it is a C serializer for exactly these primitive types and runs several times faster than json.dumps; its output is stable within a given interpreter version, which is why that version is part of the key.

directory[source]#

Directory holding one file per cached model.

hits[source]#

Number of models served from the cache during this build.

misses[source]#

Number of models serialized during this build.

evict_old_entries() → None[source]#

Delete entries that were not used recently, so the cache cannot grow without bound.

compute_key(
data: JsonDict,
max_level: int,
indent: str,
) → str | None[source]#

Hash a model into a cache key.

Parameters:
  • data – The model content.

  • max_level – The depth of indentation the model will be serialized with.

  • indent – The indentation character.

Returns:

The key, or None when the content should not be cached at all: either it holds

values marshal cannot serialize, or it is too small to be worth caching.

Return type:

str | None

encode(
data: JsonDict,
max_level: int = 4,
indent: str = '\t',
) → str[source]#

Serialize a model, reusing the stored text when this exact model was serialized before.

Parameters:
  • data – The model content to serialize.

  • max_level – The depth of indentation to stop at (see stouputils.json_dump).

  • indent – The indentation character.

Returns:

The serialized model, byte-for-byte identical to stp.json_dump(data, max_level).

Return type:

str

active_model_cache: ModelSerializationCache | None = None[source]#

Cache installed for the current build by the item_models plugin. None disables caching.

Deliberately not upper-cased: it is rebound on every build rather than being a constant.

setup_model_cache(
ctx: Context,
) → ModelSerializationCache[source]#

Create the model serialization cache for this build and make it the active one.

Parameters:

ctx – The beet context, used for its cache directory.

Returns:

The cache that was installed.

Return type:

ModelSerializationCache

set_model_encoder(
obj: JsonFileT,
max_level: int = 4,
indent: str = '\t',
) → JsonFileT[source]#

Set the encoder of the given model to the cached serializer.

Falls back to plain json_dump when no cache is active, so models can still be encoded outside of a build (tests, direct library use).

Parameters:
  • obj – The model to set the encoder for.

  • max_level – The maximum level of the JSON dump.

  • indent – The indentation character (default: ‘t’)

Returns:

The object with the encoder set

Return type:

JsonFile