💾 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
tagsargument of write_function instead
dicts#
- super_merge_dict(
- dict1: JsonDict,
- dict2: JsonDict,
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',
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
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
contentreaches awrite_*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,
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,
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,
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,
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,
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
marshalaccepts 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,boolandNonesomarshalserializes it.marshalrejects subclasses: a singleResource, astrbut 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.marshalback-references repeated objects, so the key also depends on which values are the same object. Anything else is returned untouched, lettingmarshalreject 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:
objectContent-addressed, cross-build cache of serialized models.
Serializing models dominates build time on packs that generate many variants of the same geometry: the
elementsarray 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.marshalis used to turn the model into bytes because it is a C serializer for exactly these primitive types and runs several times faster thanjson.dumps; its output is stable within a given interpreter version, which is why that version is part of the key.- 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,
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
marshalcannot serialize, or it is too small to be worth caching.
- Return type:
str | None
- encode(
- data: JsonDict,
- max_level: int = 4,
- indent: str = '\t',
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,
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:
- set_model_encoder(
- obj: JsonFileT,
- max_level: int = 4,
- indent: str = '\t',
Set the encoder of the given model to the cached serializer.
Falls back to plain
json_dumpwhen 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