:vocab: developer-facing .. _authoring-export-validate: ===================== Export and validation ===================== .. py:currentmodule:: pme :py:func:`export_menus` writes menus as PME's JSON document. The validation functions check a document against the bundled JSON Schema v2 and PME's UID rules, without changing or running it. .. list-table:: :header-rows: 1 :widths: 40 60 * - Function - Purpose * - :py:func:`export_menus` - Exports menus as a JSON document, optionally to a file. * - :py:func:`validate_json` - Validates a JSON string. Returns :py:class:`~pme.validation.ValidationResult`. * - :py:func:`pme.validation.validate` - Validates already-parsed JSON data. * - :py:func:`pme.validation.validate_file` - Validates a UTF-8 JSON file. * - :py:func:`validate_uid` - Checks the format of a menu UID. Described in :ref:`authoring-execution`. Export ====== .. py:function:: export_menus(pm_uids=None, *, include_referenced_menus=True, export_tags=True, filepath=None) Export menus as PME's JSON document. The exporter and file writer are those of the **Export Menus** dialog. The selected menu, Select Mode and the list filters are neither read nor changed. :param pm_uids: UIDs of the menus to export, as a non-string iterable. ``None`` exports every menu. :type pm_uids: iterable of str or None :param bool include_referenced_menus: Also export the menus that the named menus refer to. See :ref:`authoring-export-closure`. No effect when ``pm_uids`` is ``None``. :param bool export_tags: Include tag names, tag UIDs and the tag registry. :param filepath: File to write the JSON text to. ``.json`` is appended when the path does not end in ``.json`` (case-sensitive). An existing file is replaced. :type filepath: str or None :returns: The result described below. :rtype: dict :raises TypeError: ``pm_uids`` is a string, bytes or not iterable; ``include_referenced_menus`` or ``export_tags`` is not a bool; or ``filepath`` is not a non-empty string. :raises ValueError: ``pm_uids`` is empty, a UID in it is rejected, or the data cannot be exported. See *Errors*. :raises RuntimeError: Called off Blender's main thread (``"Menu export requires Blender's main thread"``), while PME runs its startup scripts (``"Menu export requires PME to finish loading"``), or while :py:data:`preferences` is ``None`` (``"PME preferences are unavailable"``). :raises KeyError: :py:data:`ADDON_ID` is not in ``bpy.context.preferences.addons``, as for :py:data:`preferences`. :raises OSError: The file cannot be written, for example ``FileNotFoundError`` when its directory does not exist. .. rubric:: Result .. list-table:: :header-rows: 1 :widths: 22 16 62 * - Key - Type - Value * - ``data`` - dict - The document. See :ref:`authoring-export-document`. * - ``text`` - str - The exact JSON text of ``data``, as written to the file. * - ``pm_uids`` - list[str] - UIDs of the exported menus, in document order. * - ``warnings`` - list[str] - Problems that did not stop the export. See *Warnings*. * - ``filepath`` - str or None - The path of the written file, including an appended ``.json``. ``None`` when ``filepath`` was not given. .. rubric:: Errors Every error is a ``ValueError``. The ``pm_uids`` checks run in the given order and name the first UID that fails. .. list-table:: :header-rows: 1 :widths: 50 50 * - Message - Cause * - ``pm_uids must name at least one menu; pass None to export all`` - ``pm_uids`` is empty. * - ``Menu UID is invalid: `` - Not a menu UID in the format :py:func:`validate_uid` accepts. The UID is shown with ``repr()``. * - ``Menu UID is listed more than once in pm_uids: `` - The UID appears twice in ``pm_uids``. * - ``Menu UID is missing: `` - No saved menu has the UID. * - ``Menu UID is ambiguous: saved menus share `` - Several saved menus have the UID. * - ``PME: Context Router logic export failed for menu '': refers to , which is outside the exported menu set`` - A Context Router's target menu is not exported. ```` is ``branch '