pz-scripts-data 1.1.0__tar.gz

pz_scripts_data-1.1.0/LICENSE

@@ -0,0 +1,4 @@
+PZ Scripts Data License
+This dataset is provided as fully open-source. You are free to use, modify, repost this dataset and any tools in this projects. Any contribution to it is welcomed.
+
+We are not responsible for what is made with this dataset, whenever it gets updated and breaks anything.

pz_scripts_data-1.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: pz-scripts-data
+Version: 1.1.0
+Summary: Dataset for the Scripts of Project Zomboid.
+Author: SimKDT
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Database
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.12.3
+License-File: LICENSE
+Requires-Dist: pyyaml
+Requires-Dist: jsonschema
+Requires-Dist: pydantic>=2.11
+Dynamic: license-file

pz_scripts_data-1.1.0/README.md

@@ -0,0 +1,41 @@
+# PZ Scripts Data
+Provides information regarding various script blocks and parameters of Project Zomboid [scripts](https://pzwiki.net/wiki/Scripts) system. This dataset is used to provide a [ScriptsDocs](https://pz-wiki-modding.github.io/PZ-API-Docs/).
+
+The translation data is now moved to [pz-translation-data](https://github.com/SirDoggyJvla/pz-translation-data) and are now deprecated. The main data files holding the last updated translation data are kept for tools that may use them, but will be removed in the future.
+
+## Installation
+
+PZ Scripts Data can be installed via PyPI, Git, or in development mode as described below.
+
+<details open>
+<summary>PyPI</summary>
+
+```bash
+pip install pz-scripts-data
+```
+</details>
+
+<details>
+<summary>Git</summary>
+
+```bash
+pip install git+https://github.com/PZ-Wiki-Modding/pz-scripts-data.git
+```
+</details>
+
+<details>
+<summary>Dev</summary>
+
+```bash
+pip install -e .
+```
+</details>
+
+## Schema
+You can find a Pydantic model defining the data format in the [schema.py](src/pz_scripts_data/schema.py) file. A JSON schema file exported from this model is available in the [schemas/blocks.json](schemas/blocks.json) file.
+
+## Contributing
+This dataset is aimed to accept any contributions. See [CONTRIBUTING](CONTRIBUTING.md) for more information on how to contribute to this dataset.
+
+## License
+See [LICENSE](LICENSE) for more information.

pz_scripts_data-1.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "pz-scripts-data"
+description = "Dataset for the Scripts of Project Zomboid."
+requires-python = ">=3.12.3"
+version = "1.1.0"
+license-files = ["LICENSE"]
+authors = [
+    { name = "SimKDT" },
+]
+dependencies = [
+    "pyyaml",
+    "jsonschema",
+    "pydantic>=2.11",
+]
+classifiers = [
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Database",
+    "Operating System :: OS Independent",
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+release = "pz_scripts_data.release:main"
+
+[tool.uv]
+package = true
+
+[tool.setuptools.package-data]
+pz_scripts_data = [
+    "py.typed"
+]

pz_scripts_data-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pz_scripts_data-1.1.0/src/pz_scripts_data/blocks.py

@@ -0,0 +1,65 @@
+from enum import StrEnum
+
+class BlockProperties(StrEnum):
+    VERSION = 'version'
+    REF_DESC = '#desc'
+    REF_FULL = '#ref'
+    DEPRECATED = 'deprecated'
+
+    NAME = 'name'
+    ID = 'ID'
+    SOFT_OVERRIDE = 'softOverride'
+    NO_COMMA = 'noComma'
+    PATTERN = 'pattern'
+
+    DESCRIPTION = 'description'
+    SHORT_DESCRIPTION = 'short_description'
+
+    VARIANT = 'variantOf'
+    VARIANTS = 'variants'
+
+    PARENTS = 'parents'
+    CHILDREN = 'children'
+    NEEDS_CHILDREN = 'needsChildren'
+    PARAMETERS = 'parameters'
+    PROPERTIES = 'properties'
+
+    IS_ROOT = 'isRoot'
+
+class IDProperties(StrEnum):
+    OPTIONAL = 'optional'
+    CAN_HAVE_SPACES = 'canHaveSpace'
+    FORBIDDEN = 'forbidden'
+
+    VALUES = 'values'
+    PARENTS_WITHOUT = 'parentsWithout'
+    AS_TYPE = 'asType'
+
+    TRANSLATION = 'translation'
+
+class ParameterProperties(StrEnum):
+    REF_DESC = '#desc'
+    REF_FULL = '#ref'
+
+    NAME = 'name'
+    DESCRIPTION = 'description'
+
+    TYPE = 'type'
+    DEFAULT = 'default'
+    REQUIRED = 'required'
+    CAN_BE_EMPTY = 'canBeEmpty'
+    MINIMUM = 'minimum'
+    MAXIMUM = 'maximum'
+    VALUES = 'values'
+
+    DEPRECATED = 'deprecated'
+    IS_USELESS = 'isUseless'
+    ALLOW_DUPLICATES = 'allowDuplicates'
+    INCOMPATIBLE_WITH = 'incompatibleWith'
+
+    SEE_ALSO = 'seeAlso'
+
+class PropertyData(StrEnum):
+    NAME = 'name'
+    DESCRIPTION = 'description'
+    PROPERTIES = 'properties'

pz_scripts_data-1.1.0/src/pz_scripts_data/formatBlocks.py

@@ -0,0 +1,279 @@
+import os, json, yaml
+from pathlib import Path
+from typing import TypedDict, Optional, Any
+
+from pz_scripts_data.blocks import BlockProperties, ParameterProperties, IDProperties, PropertyData
+
+
+type ScriptsBlock = dict[str, Any]
+class Item(TypedDict):
+    input: Path
+    output: Path
+    data: Optional[dict[str, ScriptsBlock]]
+
+
+items: list[Item] = [
+    Item(
+        input=Path("data/blocks"),
+        output=Path("out/scriptsBlocks.json"),
+        data=None,
+    ),
+    Item(
+        input=Path("data/roots"),
+        output=Path("out/roots.json"),
+        data=None,
+    ),
+]
+
+
+
+
+
+## PROCESS ITEM
+
+def fetchBlocks(item: Item):
+    # combine all block json files into one
+    blocks: dict[str, ScriptsBlock] = {}
+    for file_path in item['input'].glob("*.yaml"):
+        with open(file_path, 'r', encoding='utf-8') as f:
+            data = yaml.safe_load(f)
+            key = data[ParameterProperties.NAME]
+            if key in blocks:
+                raise ValueError(f"Duplicate block name '{key}' found in '{file_path}'.")
+            blocks[key] = data
+    return blocks
+
+def process_parameters(data: ScriptsBlock) -> ScriptsBlock:
+    # remove unnecessary fields
+    data.pop(BlockProperties.VERSION)
+
+    # replace parameters array into dictionary
+    # where keys are lowercased parameter names
+    parameters_data = data.get(BlockProperties.PARAMETERS, [])
+    parameters_new = {}
+    for param_data in parameters_data:
+        name = param_data[ParameterProperties.NAME]
+        parameters_new[name.lower()] = param_data
+    data[BlockProperties.PARAMETERS] = parameters_new
+
+    # handle properties
+    properties_data = data.get(BlockProperties.PROPERTIES, None)
+    if properties_data is not None:
+        for property_data in properties_data.values():
+            # transform into dictionary too
+            new_properties = {}
+            properties: list = property_data[PropertyData.PROPERTIES]
+            for prop_data in properties:
+                prop_name = prop_data[PropertyData.NAME]
+                new_properties[prop_name] = prop_data
+            property_data[PropertyData.PROPERTIES] = new_properties
+
+    return data
+
+# main
+
+def process(item: Item):
+    blocks = fetchBlocks(item)
+    for key, block in blocks.items():
+        blocks[key] = process_parameters(block)
+
+    return blocks
+
+
+
+## PREPARE
+
+# relationship and hierarchy
+
+def add_source_ref_to_targets(
+        source_name: str, 
+        targets_names: list[str], 
+        items: list[Item],
+        array_type: BlockProperties):
+    """
+    This is used to add source_name to the targets's array_type.
+
+    For example:
+    - source_name -> child_name
+    - targets_names -> child_parents
+    - array_type -> children (of parent)
+    will add source_name in the array stored at key array_type of the targets of targets_names.
+    (child_name --append--> array (key: children) of each parents)
+    """
+    _processed: list[str] = []
+    for item in items:
+        blocks = item['data']
+        assert blocks is not None, "Something went wrong."
+
+        # add children_name ref to every parents
+        for parent_name in targets_names:
+            parent_block = blocks.get(parent_name, None)
+            if parent_block is None:
+                continue
+
+            # init if needed
+            if array_type not in parent_block:
+                parent_block[array_type] = []
+
+            # add name
+            children: list[str] = parent_block[array_type]
+            if source_name not in children:
+                children.append(source_name)
+            _processed.append(parent_name)
+
+    # we make sure they were all properly processed
+    for parent_name in targets_names:
+        if parent_name not in _processed:
+            raise ValueError(f"Parent block '{parent_name}' not found for block '{source_name}'.")
+
+
+def prepare_relationship(block: ScriptsBlock, items: list[Item]):
+    """
+    This will retrieve the parents of this block and add a reference to itself inside the data,
+    of this parent block
+    """
+    # handle parents
+    parents = block.get(BlockProperties.PARENTS, [])
+    if parents:
+        add_source_ref_to_targets(
+            block[BlockProperties.NAME], parents, items,
+            BlockProperties.CHILDREN)
+
+    # handle variants
+    variant = block.get(BlockProperties.VARIANT, None)
+    if variant:
+        add_source_ref_to_targets(
+            block[BlockProperties.NAME], [variant], items,
+            BlockProperties.VARIANTS)
+
+
+# description and reference
+
+def find_block_in_items(block_name: str, items: list[Item]) -> ScriptsBlock | None:
+    for item in items:
+        blocks = item['data']
+        assert blocks is not None, "Something is wrong."
+
+        if block_name in blocks:
+            return blocks[block_name]
+    return None
+
+
+def copy_block_ref(block: ScriptsBlock, items: list[Item]) -> ScriptsBlock:
+    """
+    #desc copies the description of the source block
+    #ref copies every key values of that source block into the block (if not already present)
+    """
+    # copy #desc
+    if BlockProperties.REF_DESC in block:
+        desc_source_key: str = block[BlockProperties.REF_DESC]
+        desc_source = find_block_in_items(desc_source_key, items)
+
+        if desc_source is not None:
+            block[BlockProperties.DESCRIPTION] = desc_source[BlockProperties.DESCRIPTION]
+
+            # copy the short description if available too
+            if BlockProperties.SHORT_DESCRIPTION in desc_source:
+                block[BlockProperties.SHORT_DESCRIPTION] = desc_source[BlockProperties.SHORT_DESCRIPTION]
+
+    # copy #ref
+    if BlockProperties.REF_FULL in block:
+        ref_source_key: str = block[BlockProperties.REF_FULL]
+        ref_source = find_block_in_items(ref_source_key, items)
+        if ref_source is not None:
+            # we copy every key-value from the ref_block
+            # that doesn't already exist in the block
+            for key, value in ref_source.items():
+                if key not in block:
+                    block[key] = value
+
+    return block
+
+
+# parameters
+
+def get_source_parameter(ref_key: str, items: list[Item]) -> dict:
+    """
+    This will return the source parameter data from the ref_key.
+    The ref_key is in the format "BlockName/ParameterName"
+    """
+    # find the source block and parameter
+    path = ref_key.split('/')
+    assert len(path) == 2, f"Invalid #ref format for '{ref_key}'. Needs to be in format 'BlockName/ParameterName'."
+    origin_block = path[0]
+    origin_param = path[1].lower()
+
+    origin_block_data = find_block_in_items(origin_block, items)
+
+    # make sure the source block and parameter exist
+    if origin_block_data is None:
+        raise ValueError(f"Source block '{origin_block}' not found for parameter '{origin_param}'.")
+    if BlockProperties.PARAMETERS not in origin_block_data:
+        raise ValueError(f"Source block '{origin_block}' has no parameters for parameter '{origin_param}'.")
+    if origin_param not in origin_block_data[BlockProperties.PARAMETERS]:
+        raise ValueError(f"Source block '{origin_block}' has no parameter '{origin_param}'.")
+
+    return origin_block_data[BlockProperties.PARAMETERS][origin_param]
+
+def copy_parameters_ref(parameters: dict[str, dict], items: list[Item]):
+    for param_key, param_data in parameters.items():
+        if ParameterProperties.REF_FULL in param_data:
+            ref_key = param_data[ParameterProperties.REF_FULL]
+            
+            source_param_data = get_source_parameter(ref_key, items)
+            assert source_param_data is not None, f"Source parameter '{ref_key}' not found for parameter '{param_key}'."
+
+            # copy every key-value from the source parameter data
+            # that doesn't already exist in the parameter data
+            for key, value in source_param_data.items():
+                if key not in param_data:
+                    param_data[key] = value
+
+        if ParameterProperties.REF_DESC in param_data:
+            desc_key = param_data[ParameterProperties.REF_DESC]
+
+            source_param_data = get_source_parameter(desc_key, items)
+            assert source_param_data is not None, f"Source parameter '{desc_key}' not found for parameter '{param_key}'."
+
+            # make sure the source parameter has a description
+            if ParameterProperties.DESCRIPTION not in source_param_data:
+                raise ValueError(f"Parameter '{param_key}' has #desc but source has no description.")
+
+            # only copy the description
+            param_data[ParameterProperties.DESCRIPTION] = source_param_data[ParameterProperties.DESCRIPTION]
+
+
+# main
+
+def prepare(item: Item, items: list[Item]):
+    blocks = item['data']
+    assert blocks is not None, "Something went wrong."
+
+    for block in blocks.values():
+        prepare_relationship(block, items)
+        copy_block_ref(block, items)
+
+        parameters = block.get(BlockProperties.PARAMETERS, {})
+        copy_parameters_ref(parameters, items)
+
+
+    return blocks
+
+
+
+
+
+
+def main():
+    for item in items:
+        item['data'] = process(item)
+    for item in items:
+        item['data'] = prepare(item, items)
+    for item in items:
+        output_file = item['output']
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_file, 'w', encoding='utf-8') as f:
+            json.dump(item['data'], f, indent=2, ensure_ascii=False, sort_keys=True)
+
+if __name__ == "__main__":
+    main()

pz_scripts_data-1.1.0/src/pz_scripts_data/release.py

@@ -0,0 +1,150 @@
+import json
+import datetime
+import argparse
+import subprocess
+from pathlib import Path
+
+def assert_release_number(version: str) -> tuple[int, int, int]:
+    splitted = version.split('.')
+    if len(splitted) != 3:
+        raise ValueError("Invalid build version format. Expected format: 'major.minor.patch'")
+    try:
+        major, minor, patch = [int(x) for x in splitted]
+    except ValueError:
+        raise ValueError("Invalid build version format. Expected format: 'major.minor.patch' with integers")
+    except Exception as e:
+        raise ValueError(f"Error parsing build version: {e}")
+    return major, minor, patch
+
+def assert_release_with_version(version: str) -> tuple[int, int, int, int]:
+    splitted = version.split('.')
+    if len(splitted) != 4:
+        raise ValueError("Invalid release version format. Expected format: 'major.minor.patch.version'")
+    try:
+        major, minor, patch, release_version = [int(x) for x in splitted]
+    except ValueError:
+        raise ValueError("Invalid release version format. Expected format: 'major.minor.patch.version' with integers")
+    except Exception as e:
+        raise ValueError(f"Error parsing release version: {e}")
+    return major, minor, patch, release_version
+
+def main():
+    parser = argparse.ArgumentParser(description="Release a dataset build")
+    parser.add_argument("--set-stable", type=str, 
+                        help="Move the stable to the provided build version")
+    parser.add_argument("--set-latest-build", type=str, 
+                        help="Update the latest build version in the manifest")
+    parser.add_argument("--set-latest-release", type=str, 
+                        help="Update the latest release version in the manifest")
+    parser.add_argument("--build", type=str, 
+                        help="Specify the new build version")
+    parser.add_argument("--dry-run", action="store_true", 
+                        help="Perform a dry run without making any changes")
+    args = parser.parse_args()
+
+    # retrieve manifest file
+    WORKSPACE = Path(__file__).parent.parent.parent
+    MANIFEST_FILE = WORKSPACE / "manifest.json"
+    assert MANIFEST_FILE.exists(), f"Manifest file not found at {MANIFEST_FILE}"
+
+    # retrieve the latest manifest data
+    MANIFEST_DATA = json.loads(MANIFEST_FILE.read_text())
+    latest_build = MANIFEST_DATA['latest_build']
+    major, minor, patch = assert_release_number(latest_build)
+
+    # handle set-latest-build argument
+    set_latest_build = args.set_latest_build
+    set_latest_release = args.set_latest_release
+    set_stable = args.set_stable
+    dry_run = args.dry_run
+
+    pushed_new_release = None
+    if set_latest_build is not None:
+        print(f"Setting latest build to {set_latest_build}")
+        splitted = set_latest_build.split('.')
+        if len(splitted) != 3:
+            raise ValueError("Invalid build version format. Expected format: 'major.minor.patch'")
+        assert_release_number(set_latest_build)
+
+        # set new version in the manifest
+        MANIFEST_DATA['latest_build'] = set_latest_build
+
+    # set new stable
+    elif set_stable:
+        print(f"Setting stable to {set_stable}")
+        assert_release_with_version(set_stable)
+        MANIFEST_DATA['stable'] = set_stable
+
+    # handle set-latest-release argument
+    elif set_latest_release is not None:
+        print(f"Setting latest release to {set_latest_release}")
+        assert_release_with_version(set_latest_release)
+
+        # get associated release
+        releases = MANIFEST_DATA['releases']
+        if set_latest_release not in releases.keys():
+            raise ValueError(f"Release version {set_latest_release} not found in manifest")
+        MANIFEST_DATA['latest_release'] = set_latest_release
+
+    # no args, push a new release
+    else:
+        print("Pushing a new release")
+        current_date = datetime.datetime.now().isoformat()
+        releases = MANIFEST_DATA['releases']
+        build = args.build if args.build is not None else f"{major}.{minor}.{patch}"
+        version = 0
+        if build not in releases.keys():
+            releases[build] = {
+                'date': current_date,
+                'version': version,
+            }
+        else:
+            existing_build = releases[build]
+            existing_build['date'] = current_date
+            existing_build['version'] += 1
+            version = existing_build['version']
+        pushed_new_release = f"{build}.{version}"
+
+    # write latest changes
+    if not dry_run:
+        MANIFEST_FILE.write_text(json.dumps(MANIFEST_DATA, indent=4))
+
+    # commit latest manifest changes
+    try:
+        if not dry_run:
+            subprocess.run(["git", "add", str(MANIFEST_FILE)], check=True)
+            message = "manifest"
+            if pushed_new_release is not None:
+                message += f": {pushed_new_release}"
+            elif set_stable is not None:
+                message += f": New stable {set_stable}"
+            elif set_latest_release is not None:
+                message += f": New latest release {set_latest_release}"
+            elif set_latest_build is not None:
+                message += f": New latest build {set_latest_build}"
+            subprocess.run(["git", "commit", "-m", message], check=True)
+    except Exception as e:
+        print(f"Error committing changes: {e}")
+
+    # that one we don't ignore, since that could been connection issues
+    if not dry_run:
+        subprocess.run(["git", "push"], check=True)
+
+    # if set as stable is active
+    # move stable tag
+    if set_stable is not None:
+        if not dry_run:
+            subprocess.run(["git", "tag", "-fa", "stable", "-m", "Moved stable tag"], check=True)
+            subprocess.run(["git", "push", "-f", "--tags"], check=True)
+        print(f"Moved stable tag")
+
+    if pushed_new_release is not None:
+        if not dry_run:
+            subprocess.run(["git", "tag", "-fa", pushed_new_release, "-m", "New release"], check=True)
+            subprocess.run(["git", "push", "-f", "--tags"], check=True)
+        print(f"Pushed new release: {pushed_new_release}")
+
+
+
+if __name__ == "__main__":
+    main()

pz_scripts_data-1.1.0/src/pz_scripts_data/schema.py

@@ -0,0 +1,500 @@
+"""Pydantic models defining the structure of block definition files.
+
+``BlockDefinition`` is the root model. Its JSON Schema is exported to
+``schemas/blocks.json`` by running ``python -m pz_scripts_data.schema``.
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
+from pydantic_core import core_schema
+
+DEFAULT_OUTPUT = Path(__file__).resolve().parents[2] / "schemas" / "blocks.json"
+
+ScalarType = Literal["string", "float", "boolean", "integer"]
+
+
+class SchemaModel(BaseModel):
+    """Base model. Unknown keys are rejected and no value may be null."""
+
+    model_config = ConfigDict(extra="forbid", strict=True, validate_by_name=True)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_null(cls, data: Any) -> Any:
+        if isinstance(data, dict) and any(value is None for value in data.values()):
+            raise ValueError("null is not allowed; omit the key instead")
+        return data
+
+
+class BlockReference(SchemaModel):
+    """If the parameter is of type 'block', this can be used to provide a description of the expected format of the block."""
+
+    name: str = Field(description="The name of the block type that this parameter references to.")
+    full_type: bool = Field(
+        True,
+        alias="fullType",
+        description="Indicates whether the parameter's value can match the module and block name, for example 'module.block'.",
+    )
+    no_auto_import: bool = Field(
+        False,
+        alias="noAutoImport",
+        description="Indicates whenever this parameter can automatically check its own parent block module when fullType is set to true. If false, this means that the module won't be automatically imported.",
+    )
+
+
+class TranslationDefinition(SchemaModel):
+    """If the parameter is of type 'translation', this can be used to provide a description of the expected format of the translation. For script blocks, this is associated to the ID of the block."""
+
+    key_pattern: str = Field(
+        alias="keyPattern",
+        description="A regex pattern that the translation key in the source must match. The '{value}' placeholder is replaced by the ID of the block or value of the parameter. '{module}' is replaced by the module of the block.",
+    )
+    source_file: str = Field(
+        alias="sourceFile",
+        description="The source file where the translation key is defined (without the .json extension).",
+    )
+
+
+class BlockID(SchemaModel):
+    """Defines the ID properties for this block type. If not specified, the block type does not have an ID."""
+
+    parents_without: list[str] | None = Field(
+        None,
+        alias="parentsWithout",
+        description="A list of block names that cannot be parents if this block has an ID.",
+    )
+    values: list[str] | None = Field(
+        None,
+        description="A list of allowed ID values for this block. If not given, any value is allowed.",
+    )
+    as_type: bool | None = Field(
+        None,
+        alias="asType",
+        description="Specifies if the ID of the block should count as the block type. For example, components have specific definitions based on their ID. This means a script block needs to be defined with the name 'component <componentID>' as well as 'component' to cover all component types available with the 'values' attribute.",
+    )
+    optional: list[str] | None = Field(
+        None,
+        description="A list of ID values that are optional for this block type.",
+    )
+    can_have_space: bool | None = Field(
+        None,
+        alias="canHaveSpace",
+        description="Indicates whether the ID of the block can contain spaces. If false or not specified, the ID cannot contain spaces.",
+    )
+    forbidden: list[str] | None = Field(
+        None,
+        description="A list of forbidden ID values for this block. If not provided, no values are forbidden.",
+    )
+    translation: TranslationDefinition | None = None
+
+
+class BlockDeprecation(SchemaModel):
+    """Indicates whether the block type is deprecated."""
+
+    replaced_by: str | None = Field(
+        None,
+        alias="replacedBy",
+        description="The name of the block type that replaces this deprecated block type.",
+    )
+    description: str | None = Field(
+        None,
+        description="A brief description of why the block type is deprecated and any additional information about the deprecation.",
+    )
+
+
+class _ArrayBase(SchemaModel):
+    separator: str = Field(description="Specifies the separator used to split the string into array items.")
+    min_items: float | None = Field(
+        None,
+        alias="min",
+        description="The minimum number of items required in the array.",
+    )
+    max_items: float | None = Field(
+        None,
+        alias="max",
+        description="The maximum number of items allowed in the array.",
+    )
+    soft_override: bool | None = Field(
+        None,
+        alias="softOverride",
+        description="If true, a soft override of this property will add its content to the previously already existing array. Thus adding the old entries is not necessary and should be avoided to prevent duplicates.",
+    )
+
+
+class ScalarArrayDefinition(_ArrayBase):
+    item_type: ScalarType = Field(alias="type", description="Specifies the data type of the items in the array.")
+
+
+class BlockArrayDefinition(_ArrayBase):
+    item_type: Literal["block"] = Field(alias="type", description="Specifies the data type of the items in the array.")
+    block: BlockReference = Field(description="The block type of the items in the array.")
+
+
+ArrayDefinition = ScalarArrayDefinition | BlockArrayDefinition
+
+
+class _ObjectBase(SchemaModel):
+    key_value_separator: str = Field(
+        alias="keyValueSeparator",
+        description="Specifies the separator used to split the key and the value in the key-value pairs. The parameter 'pairsSeparator' is used to split the pairs from each others.",
+    )
+    pairs_separator: str = Field(
+        alias="pairsSeparator",
+        description="Specifies the separator used to split the pairs from each others. The parameter 'keyValueSeparator' is used to split the keys and values.",
+    )
+    soft_override: bool | None = Field(
+        None,
+        alias="softOverride",
+        description="If true, a soft override of this property will add its content to the previously already existing array. Thus adding the old entries is not necessary and should be avoided to prevent duplicates.",
+    )
+
+
+class ScalarKeyScalarValueObject(_ObjectBase):
+    key_type: ScalarType = Field(alias="keyType", description="Specifies the data type of the keys in the object.")
+    value_type: ScalarType = Field(alias="valueType", description="Specifies the data type of the values in the object.")
+
+
+class BlockKeyBlockValueObject(_ObjectBase):
+    key_type: Literal["block"] = Field(alias="keyType", description="Specifies the data type of the keys in the object.")
+    key_block: BlockReference = Field(alias="keyBlock", description="The block type of the keys in the object.")
+    value_type: Literal["block"] = Field(alias="valueType", description="Specifies the data type of the values in the object.")
+    value_block: BlockReference = Field(alias="valueBlock", description="The block type of the values in the object.")
+
+
+class BlockKeyScalarValueObject(_ObjectBase):
+    key_type: Literal["block"] = Field(alias="keyType", description="Specifies the data type of the keys in the object.")
+    key_block: BlockReference = Field(alias="keyBlock", description="The block type of the keys in the object.")
+    value_type: ScalarType = Field(alias="valueType", description="Specifies the data type of the values in the object.")
+
+
+class ScalarKeyBlockValueObject(_ObjectBase):
+    key_type: ScalarType = Field(alias="keyType", description="Specifies the data type of the keys in the object.")
+    value_type: Literal["block"] = Field(alias="valueType", description="Specifies the data type of the values in the object.")
+    value_block: BlockReference = Field(alias="valueBlock", description="The block type of the values in the object.")
+
+
+ObjectDefinition = (
+    ScalarKeyScalarValueObject
+    | BlockKeyBlockValueObject
+    | BlockKeyScalarValueObject
+    | ScalarKeyBlockValueObject
+)
+
+
+class CallbackParameter(SchemaModel):
+    name: str = Field(description="The name of the parameter.")
+    param_type: str = Field(alias="type", description="The type of the parameter.")
+    is_java: bool = Field(
+        False,
+        alias="isJava",
+        description="Indicates whether the parameter is a Java object.",
+    )
+
+
+class CallbackDefinition(SchemaModel):
+    """Indicates whether the parameter is a callback function."""
+
+    parameters: list[CallbackParameter] = Field(description="A list of parameters that the callback function takes.")
+    returns: str | None = Field(None, description="The return type of the callback function.")
+
+
+class ArrayParameterType(SchemaModel):
+    main: Literal["array"] = Field(description="The main data type of the parameter.")
+    array: ArrayDefinition = Field(
+        description="If the parameter is of type 'array', this can be used to provide a description of the expected format of the array.",
+    )
+
+
+class ObjectParameterType(SchemaModel):
+    main: Literal["object"] = Field(description="The main data type of the parameter.")
+    object_: ObjectDefinition = Field(
+        alias="object",
+        description="If the parameter is of type 'object', this can be used to provide a description of the expected format of the object.",
+    )
+
+
+class BlockParameterType(SchemaModel):
+    main: Literal["block"] = Field(description="The main data type of the parameter.")
+    block: BlockReference = Field(
+        description="If the parameter is of type 'block', this can be used to provide a description of the expected format of the block.",
+    )
+
+
+class CallbackParameterType(SchemaModel):
+    main: Literal["callback"] = Field(description="The main data type of the parameter.")
+    callback: CallbackDefinition = Field(description="Indicates whether the parameter is a callback function.")
+
+
+class TranslationParameterType(SchemaModel):
+    main: Literal["translation"] = Field(description="The main data type of the parameter.")
+    translation: TranslationDefinition = Field(
+        description="If the parameter is of type 'translation', this can be used to provide a description of the expected format of the translation.",
+    )
+
+
+class ScalarParameterType(SchemaModel):
+    main: ScalarType = Field(description="The main data type of the parameter.")
+
+
+ParameterType = (
+    ArrayParameterType
+    | ObjectParameterType
+    | BlockParameterType
+    | CallbackParameterType
+    | TranslationParameterType
+    | ScalarParameterType
+)
+
+
+class ParameterDeprecation(SchemaModel):
+    """Indicates whether the parameter is deprecated."""
+
+    replaced_by: str | None = Field(
+        None,
+        alias="replacedBy",
+        description="The name of the parameter that replaces this deprecated parameter.",
+    )
+    description: str | None = Field(
+        None,
+        description="A brief description of why the parameter is deprecated and any additional information about the deprecation.",
+    )
+    version: str | None = Field(None, description="The version(s) in which the parameter is deprecated.")
+
+
+class ParameterNeed(SchemaModel):
+    """A condition on another parameter that must be met for this parameter to be valid."""
+
+    name: str | None = Field(None, description="The name of the parameter that this condition depends on.")
+    values: list[str | float | bool] | None = Field(
+        None,
+        description="The values of the dependent parameter that must be met for this parameter to be valid.",
+    )
+    value_to_type: dict[str, str] | None = Field(
+        None,
+        alias="valueToType",
+        description="A mapping of values of the dependent parameter to the expected type of this parameter. For example, if the dependent parameter is 'type' and it has a value 'integer', then this parameter should be of type 'float'. The key is the value of the dependent parameter, and the value is the expected type of this parameter when the dependent parameter has that value.",
+        examples=[{"integer": "float", "double": "float", "boolean": "boolean", "string": "string"}],
+    )
+    minimum: float | None = Field(
+        None,
+        description="The minimum value for this parameter when the dependent parameter has a specific value. Requires the target parameter to be of type 'float' or 'integer'.",
+    )
+    maximum: float | None = Field(
+        None,
+        description="The maximum value for this parameter when the dependent parameter has a specific value. Requires the target parameter to be of type 'float' or 'integer'.",
+    )
+    children: list[str] | None = Field(
+        None,
+        description="A list of child blocks that must be present for this parameter to be valid.",
+    )
+    parents: list[str] | None = Field(
+        None,
+        description="A list of parent blocks that must be present for this parameter to be valid.",
+    )
+
+
+class ParameterDefinition(SchemaModel):
+    """A parameter available for a block type."""
+
+    name: str | None = Field(None, description="The name of the parameter.")
+    any_name: bool | None = Field(
+        None,
+        alias="anyName",
+        description="A parameter with `anyName` can have any name.",
+    )
+    ref: str | None = Field(None, alias="#ref", description="A reference to another block parameter.")
+    ref_desc: str | None = Field(
+        None,
+        alias="#desc",
+        description="A reference to the description of another block parameter. This allows sharing the same description between multiple parameters without using #ref, which would also share other properties.",
+    )
+    description: str | None = Field(None, description="A brief description of what the parameter does.")
+    allowed_duplicate: bool | None = Field(
+        None,
+        alias="allowedDuplicate",
+        description="Indicates whether the parameter can be duplicated.",
+    )
+    can_be_empty: bool | None = Field(
+        None,
+        alias="canBeEmpty",
+        description="Indicates whether the parameter can be empty.",
+    )
+    item_types: list[str] | None = Field(
+        None,
+        alias="itemTypes",
+        description="DEPRECATED: Specifies the type of item the parameter is associated with (e.g., 'vehicle', 'item', etc.). Only for item scripts.",
+    )
+    parents_only: list[str] | None = Field(
+        None,
+        alias="parentsOnly",
+        description="DEPRECATED: A list of parent block types for which this parameter is applicable.",
+    )
+    required: bool | None = Field(None, description="Indicates whether the parameter is required.")
+    default_value: str | float | bool | list[Any] | dict[str, Any] | None = Field(
+        None,
+        alias="default",
+        description="The default value for the parameter if not specified.",
+    )
+    minimum: float | None = Field(
+        None,
+        description="The minimum value for the parameter if it is a number. Needs type.main to be 'float' or 'integer' to be applicable.",
+    )
+    maximum: float | None = Field(
+        None,
+        description="The maximum value for the parameter if it is a number. Needs type.main to be 'float' or 'integer' to be applicable.",
+    )
+    data_type: ParameterType | None = Field(
+        None,
+        alias="type",
+        description="The data type of the parameter.",
+    )
+    values: list[str | float] | None = Field(None, description="A list of allowed values for the parameter.")
+    deprecated: ParameterDeprecation | None = None
+    needs: list[ParameterNeed] | None = Field(
+        None,
+        description="A list of conditions of other parameters that must be met for this parameter to be valid.",
+    )
+    incompatible_with: list[str] | None = Field(
+        None,
+        alias="incompatibleWith",
+        description="List of other parameters which are incompatible with this one.",
+    )
+    is_useless: bool = Field(
+        False,
+        alias="isUseless",
+        description="Indicates whether the parameter is considered useless or not. This can be used to flag parameters that have no effect in the game. Not to be confused with deprecated which indicates a parameter that previously worked but no longer does.",
+    )
+    see_also: list[str] | None = Field(
+        None,
+        alias="seeAlso",
+        description="A list of other parameters that are related to this one.",
+    )
+
+
+class BlockDefinition(SchemaModel):
+    """Schema of a block definition file."""
+
+    model_config = ConfigDict(
+        title="Blocks Folder General Schema",
+        json_schema_extra=lambda schema: schema.update(
+            allOf=[
+                {
+                    "if": {"required": ["isRoot"], "properties": {"isRoot": {"const": True}}},
+                    "then": {"required": ["pattern"]},
+                }
+            ]
+        ),
+    )
+
+    version: float | str | None = None
+    ref_desc: str | None = Field(
+        None,
+        alias="#desc",
+        description="A reference to the description of another block type. This allows sharing the same description between multiple block types without using #ref, which would also share other properties.",
+    )
+    ref: str | None = Field(
+        None,
+        alias="#ref",
+        description="A reference to another block type. This allows sharing the same properties between multiple block types.",
+    )
+    variant_of: str | None = Field(
+        None,
+        alias="variantOf",
+        description="Indicates whether this block type is a variant of another block type. The value corresponds to the block type it is a variant of.",
+    )
+    name: str = Field(description="The name of the block type.")
+    any_name: bool | None = Field(
+        None,
+        alias="anyName",
+        description="A block with `anyName` can have any name. This requires strict placement in parent blocks to correctly validate the block parameters.",
+    )
+    short_description: str | None = Field(
+        None,
+        alias="shortDescription",
+        description="A brief description of the block type, used for quick reference in completion items.",
+    )
+    description: str | None = Field(None, description="A brief description of the block type.")
+    block_id: BlockID | None = Field(None, alias="ID")
+    parents: list[str] | None = Field(None, description="A list of valid parent block types.")
+    needs_children: list[str] | None = Field(
+        None,
+        alias="needsChildren",
+        description="A list of required child block types.",
+    )
+    soft_override: bool | None = Field(
+        None,
+        alias="softOverride",
+        description="Indicates whether the block can be soft overridden in scripts.",
+    )
+    is_root: bool | None = Field(
+        None,
+        alias="isRoot",
+        description="Indicates whether the block is a root document.",
+    )
+    pattern: list[str] | None = Field(
+        None,
+        description="A list of regex patterns that can be used to match this root file. Required when 'isRoot' is true.",
+    )
+    no_comma: bool | None = Field(
+        None,
+        alias="noComma",
+        description="Indicates whether the block parameters should not be followed by a comma.",
+    )
+    deprecated: BlockDeprecation | None = None
+    parameters: list[ParameterDefinition] | None = Field(
+        None,
+        description="A list of parameters available for this block type.",
+    )
+    properties: dict[str, Any] | None = Field(
+        None,
+        description="Custom additional properties for the block type.",
+    )
+
+    @model_validator(mode="after")
+    def _root_requires_pattern(self) -> Self:
+        if self.is_root is True and self.pattern is None:
+            raise ValueError("'pattern' is required when 'isRoot' is true")
+        return self
+
+
+class _BlocksJsonSchemaGenerator(GenerateJsonSchema):
+    """Draft-07 output without null members, titles or `default: null` entries, matching the hand-written schema."""
+
+    schema_dialect = "http://json-schema.org/draft-07/schema#"
+
+    def field_title_should_be_set(self, schema: Any) -> bool:
+        return False
+
+    def model_schema(self, schema: core_schema.ModelSchema) -> JsonSchemaValue:
+        json_schema = super().model_schema(schema)
+        if schema["cls"] is not BlockDefinition:
+            json_schema.pop("title", None)
+        return json_schema
+
+    def nullable_schema(self, schema: core_schema.NullableSchema) -> JsonSchemaValue:
+        return self.generate_inner(schema["schema"])
+
+    def default_schema(self, schema: core_schema.WithDefaultSchema) -> JsonSchemaValue:
+        if schema.get("default") is None:
+            return self.generate_inner(schema["schema"])
+        return super().default_schema(schema)
+
+
+def build_json_schema() -> dict[str, Any]:
+    return BlockDefinition.model_json_schema(by_alias=True, schema_generator=_BlocksJsonSchemaGenerator)
+
+
+def main(argv: list[str]) -> int:
+    output = Path(argv[0]) if argv else DEFAULT_OUTPUT
+    output.write_text(json.dumps(build_json_schema(), indent=2) + "\n", encoding="utf-8")
+    print(f"Wrote {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

pz_scripts_data-1.1.0/src/pz_scripts_data/sortItemParameters.py

@@ -0,0 +1,42 @@
+import json
+
+INPUT_FILE = "out/scriptsBlocks.json"
+OUTPUT_FILE = "out/itemParameters.json"
+
+
+
+def get_itemtype_needs(param_data: dict) -> list[str] | None:
+    # skip if no needs
+    if 'needs' not in param_data:
+        return None
+    # skip if no need for ItemType
+    for need in param_data['needs']:
+        if need.get('name', None) == 'ItemType':
+            return need.get('values', None)
+    return None
+
+
+# load item ItemTypes available
+with open(INPUT_FILE, 'r', encoding='utf-8') as f:
+    blocks = json.load(f)
+
+item_block = blocks['item']
+itemtypes = item_block['parameters']['itemtype']['values']
+
+# initialize dictionary of ItemTypes
+type_2_params = {}
+for itemtype in itemtypes:
+    type_2_params[itemtype] = []
+
+
+# for each parameter, check if it has a need for ItemType
+# if so, it means it specifically is only valid those ItemTypes
+for param_key, param_data in item_block['parameters'].items():
+    itemtypes = get_itemtype_needs(param_data)
+    if itemtypes is not None:
+        for itemtype in itemtypes:
+            type_2_params[itemtype].append(param_data['name'])
+
+
+with open(OUTPUT_FILE, 'w', encoding='utf-8') as f:
+    json.dump(type_2_params, f, indent=4)

pz_scripts_data-1.1.0/src/pz_scripts_data/validateBlocks.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""
+Validate YAML block files against the blocks.json schema.
+
+Usage:
+    python validateBlocks.py                     # Validate all YAML files in data/blocks/
+    python validateBlocks.py <file_path>         # Validate a specific file
+    python validateBlocks.py <directory_path>    # Validate all YAML files in a directory
+    python validateBlocks.py --help              # Show this help message
+"""
+
+import json, yaml, sys, os
+from pathlib import Path
+from jsonschema import Draft7Validator
+from typing import List, Tuple
+
+# Default paths
+DEFAULT_BLOCKS_DIR = "data/blocks"
+DEFAULT_SCHEMA_PATH = "schemas/blocks.json"
+
+def load_schema(schema_path: str) -> dict:
+    """Load the JSON schema from file."""
+    with open(schema_path, 'r') as f:
+        return json.load(f)
+
+def load_yaml_file(file_path: str) -> dict:
+    """Load a YAML file and return its contents."""
+    with open(file_path, 'r') as f:
+        return yaml.safe_load(f)
+
+def validate_file(file_path: str, schema: dict) -> Tuple[bool, List[str]]:
+    """
+    Validate a single YAML file against the schema.
+    
+    Returns:
+        Tuple of (is_valid, error_messages)
+    """
+    errors = []
+    try:
+        data = load_yaml_file(file_path)
+        
+        # Handle empty files
+        if data is None:
+            return True, []
+        
+        # Validate against schema
+        validator = Draft7Validator(schema)
+        validation_errors = list(validator.iter_errors(data))
+        
+        if validation_errors:
+            for error in validation_errors:
+                path = ".".join(str(p) for p in error.absolute_path) or "root"
+                errors.append(f"  {path}: {error.message}")
+            return False, errors
+        
+        return True, []
+        
+    except yaml.YAMLError as e:
+        return False, [f"  YAML Parse Error: {str(e)}"]
+    except Exception as e:
+        return False, [f"  Error: {str(e)}"]
+
+def get_yaml_files(path: str) -> List[str]:
+    """Get all YAML files from a path (file or directory)."""
+    path_obj = Path(path)
+    
+    if path_obj.is_file():
+        if path_obj.suffix.lower() in ['.yaml', '.yml']:
+            return [str(path_obj)]
+        return []
+    elif path_obj.is_dir():
+        return sorted([str(f) for f in path_obj.glob("*.yaml")] + 
+                     [str(f) for f in path_obj.glob("*.yml")])
+    
+    return []
+
+def main():
+    """Main validation function."""
+    # Parse arguments
+    if len(sys.argv) > 1:
+        if sys.argv[1] in ['--help', '-h', 'help']:
+            print(__doc__)
+            return 0
+        target_path = sys.argv[1]
+    else:
+        target_path = DEFAULT_BLOCKS_DIR
+    
+    # Check if project root is correct
+    if not os.path.exists(DEFAULT_SCHEMA_PATH):
+        print(f"Error: Schema not found at {DEFAULT_SCHEMA_PATH}")
+        print("Please run this script from the project root directory.")
+        return 1
+    
+    # Load schema
+    try:
+        schema = load_schema(DEFAULT_SCHEMA_PATH)
+    except Exception as e:
+        print(f"Error loading schema: {e}")
+        return 1
+    
+    # Get files to validate
+    if not os.path.exists(target_path):
+        print(f"Error: Path not found: {target_path}")
+        return 1
+    
+    yaml_files = get_yaml_files(target_path)
+    
+    if not yaml_files:
+        print(f"No YAML files found in {target_path}")
+        return 1
+    
+    # Validate files
+    print(f"Validating {len(yaml_files)} file(s)...\n")
+    
+    valid_count = 0
+    invalid_count = 0
+    
+    for file_path in yaml_files:
+        is_valid, errors = validate_file(file_path, schema)
+        
+        if is_valid:
+            print(f"✓ {file_path}")
+            valid_count += 1
+        else:
+            print(f"✗ {file_path}")
+            for error in errors:
+                print(error)
+            print()
+            invalid_count += 1
+    
+    # Summary
+    print("\n" + "="*60)
+    print(f"Results: {valid_count} valid, {invalid_count} invalid")
+    print("="*60)
+    
+    return 0 if invalid_count == 0 else 1
+
+if __name__ == "__main__":
+    sys.exit(main())

pz_scripts_data-1.1.0/src/pz_scripts_data.egg-info/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: pz-scripts-data
+Version: 1.1.0
+Summary: Dataset for the Scripts of Project Zomboid.
+Author: SimKDT
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Database
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.12.3
+License-File: LICENSE
+Requires-Dist: pyyaml
+Requires-Dist: jsonschema
+Requires-Dist: pydantic>=2.11
+Dynamic: license-file

pz_scripts_data-1.1.0/src/pz_scripts_data.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/pz_scripts_data/blocks.py
+src/pz_scripts_data/formatBlocks.py
+src/pz_scripts_data/py.typed
+src/pz_scripts_data/release.py
+src/pz_scripts_data/schema.py
+src/pz_scripts_data/sortItemParameters.py
+src/pz_scripts_data/validateBlocks.py
+src/pz_scripts_data.egg-info/PKG-INFO
+src/pz_scripts_data.egg-info/SOURCES.txt
+src/pz_scripts_data.egg-info/dependency_links.txt
+src/pz_scripts_data.egg-info/entry_points.txt
+src/pz_scripts_data.egg-info/requires.txt
+src/pz_scripts_data.egg-info/top_level.txt

pz_scripts_data-1.1.0/src/pz_scripts_data.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pz_scripts_data-1.1.0/src/pz_scripts_data.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+release = pz_scripts_data.release:main

pz_scripts_data-1.1.0/src/pz_scripts_data.egg-info/requires.txt

@@ -0,0 +1,3 @@
+pyyaml
+jsonschema
+pydantic>=2.11

pz_scripts_data-1.1.0/src/pz_scripts_data.egg-info/top_level.txt

@@ -0,0 +1 @@
+pz_scripts_data