beresta 2.1.0__py3-none-any.whl

beresta/__init__.py

@@ -0,0 +1,42 @@
+"""
+Берёста — быстрая DOM-библиотека XML на C++17 для Python (через ctypes).
+
+    import beresta
+
+    with beresta.parse("<shop><item code='A1'>Чай</item></shop>") as document:
+        item = document.root.first_child
+        print(item.get_attribute("code"), item.text)
+        print(beresta.XPath("count(//item)").number(document))
+
+Без зависимостей: нужен только сам Python и динамическая библиотека,
+которую сборка кладёт в beresta/_native/<os>-<arch>/.
+
+Beresta is a fast XML DOM library in C++17 for Python (through ctypes).
+
+No dependencies: only Python itself and the native library,
+which the build puts into beresta/_native/<os>-<arch>/.
+"""
+
+from ._factory import new_document, parse, parse_file
+from ._loader import platform_name
+from ._native import LIB as _LIB
+from .document import Document
+from .element import Element
+from .errors import BerestaError
+from .flags import NodeType, ParseFlags, WriteFlags
+from .languages import language, languages, set_language
+from .node import Node
+from .schema import Diagnostic, Schema
+from .xpath import XPath
+
+__all__ = [
+    "BerestaError", "Diagnostic", "Document", "Element", "Node", "NodeType",
+    "ParseFlags", "Schema", "WriteFlags", "XPath",
+    "language", "languages", "new_document", "parse", "parse_file", "platform_name",
+    "set_language", "version",
+]
+
+
+def version() -> str:
+    """Версия нативной библиотеки, например "2.1.0". / The native library version, for example "2.1.0"."""
+    return _LIB.beresta_version().decode("ascii")

beresta/_diagnostics.py

@@ -0,0 +1,45 @@
+"""
+Нарушения схемы и чтение их нативного списка. Общее для проверки
+готового дерева (Schema.validate) и потоковой проверки байтов и файлов
+(Schema.validate_bytes / validate_file) — одна функция вместо трёх копий.
+
+Schema violations and reading their native list. Common for the validation of
+a ready tree (Schema.validate) and the streaming validation of bytes and files
+(Schema.validate_bytes / validate_file) — one function instead of three copies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+from ._native import LIB
+from .errors import take_text
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """Одно нарушение: текст с путём к элементу и место в исходнике (0 — неизвестно).
+    One violation: the text with the element path and the place in the source (0 — unknown)."""
+
+    message: str
+    line: int
+    column: int
+
+
+def take_diagnostics(diagnostics) -> List[Diagnostic]:
+    """Список нарушений из нативного дескриптора; дескриптор освобождается в finally.
+    The list of violations from a native handle; the handle is freed in finally."""
+    try:
+        return [_diagnostic_at(diagnostics, index)
+                for index in range(LIB.beresta_diagnostics_count(diagnostics))]
+    finally:
+        LIB.beresta_diagnostics_free(diagnostics)
+
+
+def _diagnostic_at(diagnostics, index: int) -> Diagnostic:
+    """Чтение одного нарушения из нативного списка. / Reads one violation from the native list."""
+    message = take_text(LIB.beresta_diagnostics_message(diagnostics, index))
+    line = LIB.beresta_diagnostics_line(diagnostics, index)
+    column = LIB.beresta_diagnostics_column(diagnostics, index)
+    return Diagnostic(message, line, column)

beresta/_document_content.py

@@ -0,0 +1,45 @@
+"""Примесь документа: корень, поиск по ID, копия, запись в файл.
+Document mixin: the root, lookup by ID, a copy, writing to a file."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ._native import LIB, encode, out_handle
+from ._wrapping import wrap_node
+from .errors import check
+from .flags import WriteFlags
+
+
+class DocumentContentMixin:
+    """Операции уровня документа. / Document-level operations."""
+
+    @property
+    def raw_handle(self) -> int:
+        """Дескриптор без проверки закрытия (нужен фабрике обёрток).
+        The handle without the closed check (needed by the wrapper factory)."""
+        return self._pointer
+
+    @property
+    def root(self):
+        """Корневой элемент или None. / The root element or None."""
+        return wrap_node(LIB.beresta_document_root(self.handle), self)
+
+    def element_by_id(self, identifier: str):
+        """Элемент с атрибутом типа ID (по DTD) или xml:id.
+        An element with an ID-typed attribute (by DTD) or xml:id."""
+        return wrap_node(LIB.beresta_document_element_by_id(self.handle, encode(identifier)), self)
+
+    def clone(self):
+        """Независимая глубокая копия документа. / An independent deep copy of the document."""
+        from .document import Document
+
+        result = out_handle()
+        check(LIB.beresta_document_clone(self.handle, result))
+        return Document(result.value)
+
+    def save(self, path, flags: WriteFlags = WriteFlags.DEFAULT, encoding: Optional[str] = None) -> None:
+        """Запись в файл; encoding=None — UTF-8, иначе, например, "windows-1251".
+        Writing to a file; encoding=None means UTF-8, otherwise, for example, "windows-1251"."""
+        check(LIB.beresta_document_save(self.handle, encode(os.fspath(path)), int(flags), encode(encoding)))

beresta/_element_attributes.py

@@ -0,0 +1,49 @@
+"""Примесь: атрибуты элемента. / Mixin: element attributes."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+from ._native import LIB, encode
+from .errors import check, take_text
+
+
+class ElementAttributesMixin:
+    """Чтение, запись и перебор атрибутов (порядок — как в документе).
+    Reading, writing and iterating attributes (in document order)."""
+
+    def get_attribute(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """Значение атрибута или default, если атрибута нет.
+        The attribute value or default if there is no such attribute."""
+        value = take_text(LIB.beresta_element_get_attribute(self.handle, encode(name)))
+        if value is None:
+            return default
+        return value
+
+    def set_attribute(self, name: str, value: str) -> None:
+        check(LIB.beresta_element_set_attribute(self.handle, encode(name), encode(value)))
+
+    def has_attribute(self, name: str) -> bool:
+        result = LIB.beresta_element_has_attribute(self.handle, encode(name))
+        if result < 0:
+            check(LIB.beresta_last_error_code())
+        return result == 1
+
+    def remove_attribute(self, name: str) -> bool:
+        """True — атрибут был и удалён, False — его не было.
+        True means the attribute existed and was removed, False means it did not exist."""
+        result = LIB.beresta_element_remove_attribute(self.handle, encode(name))
+        if result < 0:
+            check(LIB.beresta_last_error_code())
+        return result == 1
+
+    @property
+    def attributes(self) -> Dict[str, str]:
+        """Снимок всех атрибутов: {имя: значение} в порядке документа.
+        A snapshot of all attributes: {name: value} in document order."""
+        result = {}
+        handle = self.handle
+        for index in range(LIB.beresta_element_attribute_count(handle)):
+            name = take_text(LIB.beresta_element_attribute_name(handle, index))
+            result[name] = take_text(LIB.beresta_element_attribute_value(handle, index))
+        return result

beresta/_factory.py

@@ -0,0 +1,53 @@
+"""Создание документов: разбор текста, байтов и файлов, документ с нуля.
+Creating documents: parsing text, bytes and files, a document from scratch."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional, Union
+
+from ._native import LIB, encode, out_handle
+from .document import Document
+from .errors import check
+from .flags import ParseFlags
+
+
+def _schema_handle(schema) -> Optional[int]:
+    """Дескриптор схемы или NULL, если проверка по схеме не нужна.
+    The schema handle or NULL if no schema validation is needed."""
+    if schema is None:
+        return None
+    return schema.handle
+
+
+def parse(source: Union[str, bytes], flags: ParseFlags = ParseFlags.DEFAULT, schema=None) -> Document:
+    """
+    Разбор XML. str кодируется в UTF-8; bytes передаются как есть —
+    кодировку (UTF-16, windows-1251, ...) библиотека определит сама.
+
+    Parses XML. str is encoded to UTF-8; bytes are passed as is —
+    the library detects the encoding (UTF-16, windows-1251, ...) itself.
+    """
+    data = source
+    if isinstance(source, str):
+        data = source.encode("utf-8")
+    result = out_handle()
+    check(LIB.beresta_document_parse(data, len(data), int(flags), _schema_handle(schema), result))
+    return Document(result.value)
+
+
+def parse_file(path, flags: ParseFlags = ParseFlags.DEFAULT, schema=None) -> Document:
+    """Разбор файла (ParseFlags.FILE_RESOURCES разрешает внешние DTD рядом с ним).
+    Parses a file (ParseFlags.FILE_RESOURCES allows external DTDs next to it)."""
+    result = out_handle()
+    status = LIB.beresta_document_parse_file(encode(os.fspath(path)), int(flags), _schema_handle(schema), result)
+    check(status)
+    return Document(result.value)
+
+
+def new_document(root_name: Optional[str] = None) -> Document:
+    """Новый документ; root_name=None — без корневого элемента.
+    A new document; root_name=None means without a root element."""
+    result = out_handle()
+    check(LIB.beresta_document_create(encode(root_name), result))
+    return Document(result.value)

beresta/_loader.py

@@ -0,0 +1,110 @@
+"""
+Поиск и загрузка динамической библиотеки «Берёсты» через ctypes.
+
+Порядок поиска (первый найденный файл побеждает):
+  1. переменная окружения BERESTA_LIBRARY — явный путь к файлу;
+  2. папка пакета _native/<os>-<arch>/ — туда бинарник кладут
+     CMake (-DBERESTA_BUILD_PYTHON=ON) и Makefile (make PYTHON=1);
+  3. системный поиск (ctypes.util.find_library) — библиотека,
+     установленная в систему (/usr/lib, PATH и т.п.).
+
+Имена ОС и архитектуры совпадают с именами в CMake, Makefile и
+Java-обёртке: windows/linux/macos и x86_64/aarch64/x86.
+
+Finding and loading the Beresta shared library through ctypes.
+Lookup order (the first file found wins):
+1. the BERESTA_LIBRARY environment variable — an explicit file path;
+2. the package folder _native/<os>-<arch>/ — the binary is put there by
+CMake (-DBERESTA_BUILD_PYTHON=ON) and the Makefile (make PYTHON=1);
+3. the system lookup (ctypes.util.find_library) — a library
+installed in the system (/usr/lib, PATH and so on).
+The OS and architecture names match CMake, the Makefile and the
+Java wrapper: windows/linux/macos and x86_64/aarch64/x86.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import os
+import platform
+import struct
+import sys
+from pathlib import Path
+
+# Каноническое имя файла библиотеки на каждой ОС
+# The canonical library file name on each OS
+_LIBRARY_FILES = {
+    "windows": "beresta.dll",
+    "linux": "libberesta.so",
+    "macos": "libberesta.dylib",
+}
+
+# Разные системы называют одну архитектуру по-разному
+# Different systems name the same architecture differently
+_ARCH_ALIASES = {
+    "amd64": "x86_64", "x86_64": "x86_64", "x64": "x86_64",
+    "arm64": "aarch64", "aarch64": "aarch64",
+    "i386": "x86", "i686": "x86", "x86": "x86",
+}
+
+
+def platform_name() -> str:
+    """Имя платформы вида windows-x86_64 (имя папки в _native).
+    The platform name like windows-x86_64 (the folder name in _native)."""
+    if sys.platform.startswith("win"):
+        system = "windows"
+    elif sys.platform == "darwin":
+        system = "macos"
+    else:
+        system = sys.platform.rstrip("0123456789")
+    machine = platform.machine().lower()
+    arch = _ARCH_ALIASES.get(machine, machine)
+    # 32-битный Python на 64-битном процессоре загрузит только 32-битную библиотеку
+    # A 32-bit Python on a 64-bit processor can load only a 32-bit library
+    if arch == "x86_64" and struct.calcsize("P") == 4:
+        arch = "x86"
+    return system + "-" + arch
+
+
+def library_file_name() -> str:
+    """Имя файла библиотеки для текущей ОС. / The library file name for the current OS."""
+    system = platform_name().split("-")[0]
+    return _LIBRARY_FILES.get(system, "libberesta.so")
+
+
+def _candidates() -> list:
+    """Кандидаты в порядке приоритета (несуществующие отбрасываются позже).
+    Candidates in priority order (missing ones are dropped later)."""
+    result = []
+    explicit = os.environ.get("BERESTA_LIBRARY")
+    if explicit:
+        result.append(explicit)
+    bundled = Path(__file__).resolve().parent / "_native" / platform_name() / library_file_name()
+    result.append(str(bundled))
+    system_wide = ctypes.util.find_library("beresta")
+    if system_wide:
+        result.append(system_wide)
+    return result
+
+
+def load_library() -> ctypes.CDLL:
+    """Загрузка библиотеки; понятная ошибка, если бинарник не найден.
+    Loads the library; a clear error if the binary is not found."""
+    tried = []
+    for candidate in _candidates():
+        if os.path.isabs(candidate) and not os.path.exists(candidate):
+            tried.append(candidate)
+            continue
+        return ctypes.CDLL(candidate)
+    # Библиотека ещё не загружена, каталога сообщений нет — текст на двух языках
+    # The library is not loaded yet, so there is no message catalog — the text is bilingual
+    raise OSError(
+        "Берёста: динамическая библиотека не найдена для платформы "
+        + platform_name() + ". Соберите её с флагом PYTHON=1 (make) или "
+        + "-DBERESTA_BUILD_PYTHON=ON (CMake) либо задайте BERESTA_LIBRARY. "
+        + "Проверенные пути: " + ", ".join(tried)
+        + " / Beresta: the native library was not found for the platform "
+        + platform_name() + ". Build it with PYTHON=1 (make) or "
+        + "-DBERESTA_BUILD_PYTHON=ON (CMake), or set BERESTA_LIBRARY. "
+        + "Paths tried: " + ", ".join(tried))

beresta/_native.py

@@ -0,0 +1,42 @@
+"""
+Единственный экземпляр загруженной библиотеки (паттерн Singleton на уровне
+модуля: Python импортирует модуль ровно один раз, поэтому библиотека
+загружается и связывается с сигнатурами тоже один раз).
+
+The single instance of the loaded library (the Singleton pattern at module
+level: Python imports a module exactly once, so the library is also
+loaded and bound to the signatures once).
+"""
+
+from __future__ import annotations
+
+from ctypes import c_void_p
+from typing import Optional
+
+from ._loader import load_library
+from ._signatures import bind_signatures
+
+
+def _initialize():
+    """Загрузка библиотеки и назначение сигнатур всем функциям.
+    Loads the library and assigns signatures to all functions."""
+    library = load_library()
+    bind_signatures(library)
+    return library
+
+
+LIB = _initialize()
+
+
+def encode(text: Optional[str]) -> Optional[bytes]:
+    """Строка Python -> байты UTF-8 для параметра const char* (None -> NULL).
+    A Python string -> UTF-8 bytes for a const char* parameter (None -> NULL)."""
+    if text is None:
+        return None
+    return str(text).encode("utf-8")
+
+
+def out_handle() -> c_void_p:
+    """Пустая ячейка для выходного параметра вида beresta_document* out.
+    An empty cell for an output parameter like beresta_document* out."""
+    return c_void_p()

beresta/_node_children.py

@@ -0,0 +1,44 @@
+"""Примесь: доступ к детям как к последовательности Python. / Mixin: access to children as a Python sequence."""
+
+from __future__ import annotations
+
+from typing import Iterator
+
+from ._native import LIB
+from ._wrapping import wrap_node
+from .errors import check
+
+
+class NodeChildrenMixin:
+    """len(node), node[i], for child in node: ..."""
+
+    @property
+    def child_count(self) -> int:
+        count = LIB.beresta_node_child_count(self.handle)
+        if count < 0:
+            check(LIB.beresta_last_error_code())
+        return count
+
+    @property
+    def children(self) -> list:
+        """Список детей (снимок: последующие изменения дерева в нём не видны).
+        The list of children (a snapshot: later tree changes are not visible in it)."""
+        return list(iter(self))
+
+    def __len__(self) -> int:
+        return self.child_count
+
+    def __getitem__(self, index: int):
+        """Ребёнок по индексу; отрицательный индекс — с конца, как у list.
+        A child by index; a negative index counts from the end, as in list."""
+        if index < 0:
+            index += self.child_count
+        return wrap_node(LIB.beresta_node_child(self.handle, index), self.document)
+
+    def __iter__(self) -> Iterator:
+        """Обход детей через соседей — O(1) на шаг, без лишних списков.
+        Iterates children through siblings — O(1) per step, without extra lists."""
+        child = self.first_child
+        while child is not None:
+            yield child
+            child = child.next_sibling

beresta/_node_content.py

@@ -0,0 +1,46 @@
+"""Примесь: тип, имя, текст и сериализация узла. / Mixin: node type, name, text and serialization."""
+
+from __future__ import annotations
+
+from ._native import LIB, encode
+from .errors import check, take_text
+from .flags import NodeType, WriteFlags
+
+
+class NodeContentMixin:
+    """Свойства содержимого узла. / Node content properties."""
+
+    @property
+    def type(self) -> NodeType:
+        """Тип узла (NodeType); запоминается при первом запросе или фабрикой.
+        The node type (NodeType); remembered on the first request or by the factory."""
+        handle = self.handle
+        if self._kind is None:
+            code = LIB.beresta_node_type(handle)
+            if code < 0:
+                check(LIB.beresta_last_error_code())
+            self._kind = code
+        return NodeType(self._kind)
+
+    @property
+    def name(self) -> str:
+        """Имя по соглашению DOM: тег, цель PI, "#text", "#comment"...
+        The name by the DOM convention: a tag, a PI target, "#text", "#comment"..."""
+        return take_text(LIB.beresta_node_name(self.handle))
+
+    @property
+    def text(self) -> str:
+        """Текстовое содержимое (у элемента — весь текст потомков).
+        The text content (for an element — all text of its descendants)."""
+        return take_text(LIB.beresta_node_text(self.handle))
+
+    @text.setter
+    def text(self, value: str) -> None:
+        """У элемента все дети заменяются одним текстовым узлом.
+        For an element all children are replaced with one text node."""
+        check(LIB.beresta_node_set_text(self.handle, encode(value)))
+
+    def to_xml(self, flags: WriteFlags = WriteFlags.DEFAULT) -> str:
+        """Сериализация узла с потомками (по умолчанию — без лишних пробелов).
+        Serializes the node with its descendants (by default — without extra spaces)."""
+        return take_text(LIB.beresta_node_to_string(self.handle, int(flags)))

beresta/_node_editing.py

@@ -0,0 +1,32 @@
+"""Примесь: добавление новых узлов в конец детей. / Mixin: appending new nodes to the end of the children."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ._native import LIB, encode
+from ._wrapping import wrap_node
+
+
+class NodeEditingMixin:
+    """Каждый метод возвращает созданный узел — удобно строить дерево цепочкой.
+    Each method returns the created node — convenient for building a tree in a chain."""
+
+    def append_element(self, name: str):
+        """Новый элемент; у пустого документа он становится корнем.
+        A new element; in an empty document it becomes the root."""
+        return wrap_node(LIB.beresta_node_append_element(self.handle, encode(name)), self.document)
+
+    def append_text(self, text: str):
+        return wrap_node(LIB.beresta_node_append_text(self.handle, encode(text)), self.document)
+
+    def append_comment(self, text: str):
+        return wrap_node(LIB.beresta_node_append_comment(self.handle, encode(text)), self.document)
+
+    def append_cdata(self, text: str):
+        return wrap_node(LIB.beresta_node_append_cdata(self.handle, encode(text)), self.document)
+
+    def append_pi(self, target: str, data: Optional[str] = None):
+        """Инструкция обработки <?target data?>. / A processing instruction <?target data?>."""
+        pointer = LIB.beresta_node_append_pi(self.handle, encode(target), encode(data))
+        return wrap_node(pointer, self.document)

beresta/_node_navigation.py

@@ -0,0 +1,32 @@
+"""Примесь: навигация по дереву (родитель, соседи, первый и последний ребёнок).
+Mixin: tree navigation (parent, siblings, first and last child)."""
+
+from __future__ import annotations
+
+from ._native import LIB
+from ._wrapping import wrap_node
+
+
+class NodeNavigationMixin:
+    """Соседи и родитель находятся за O(1): ядро хранит индекс узла у родителя.
+    Siblings and the parent are found in O(1): the core stores the node's index in its parent."""
+
+    @property
+    def parent(self):
+        return wrap_node(LIB.beresta_node_parent(self.handle), self.document)
+
+    @property
+    def first_child(self):
+        return wrap_node(LIB.beresta_node_first_child(self.handle), self.document)
+
+    @property
+    def last_child(self):
+        return wrap_node(LIB.beresta_node_last_child(self.handle), self.document)
+
+    @property
+    def next_sibling(self):
+        return wrap_node(LIB.beresta_node_next_sibling(self.handle), self.document)
+
+    @property
+    def previous_sibling(self):
+        return wrap_node(LIB.beresta_node_previous_sibling(self.handle), self.document)

beresta/_node_structure.py

@@ -0,0 +1,50 @@
+"""Примесь: удаление, копирование и перенос поддерева. / Mixin: removing, copying and moving a subtree."""
+
+from __future__ import annotations
+
+from ._native import LIB, out_handle
+from ._wrapping import transfer_wrappers, wrap_node
+from .errors import check
+
+
+class NodeStructureMixin:
+    """Изменение структуры дерева. / Changing the tree structure."""
+
+    def remove(self) -> None:
+        """
+        Удаление узла с потомками. После вызова этот объект и обёртки
+        потомков недействительны — обращаться к ним нельзя.
+
+        Removes the node with its descendants. After the call this object and the
+        wrappers of its descendants are invalid — they must not be used.
+        """
+        check(LIB.beresta_node_remove(self.handle))
+
+    def copy_to(self, parent):
+        """Глубокая копия в конец детей parent (можно в другой документ).
+        A deep copy appended to the children of parent (another document is allowed)."""
+        result = out_handle()
+        check(LIB.beresta_node_copy_to(self.handle, parent.handle, result))
+        return wrap_node(result.value, parent.document)
+
+    def move_to(self, parent) -> None:
+        """
+        Перенос (без копирования) в конец детей parent, в том числе в другой
+        документ. Этот объект остаётся тем же узлом; после переноса его
+        документ — parent.document, и закрытие прежнего документа узел не
+        затрагивает. Обёртки потомков, полученные раньше, тоже переходят
+        к новому документу. Корень документа и сам документ переносить
+        нельзя (BerestaError HIERARCHY_VIOLATION / INVALID_ARGUMENT).
+
+        Moves the node (without copying) to the end of the children of parent,
+        including into another document. This object stays the same node; after the
+        move its document is parent.document, and closing the former document does
+        not affect the node. The wrappers of descendants obtained earlier move to the
+        new document too. The document root and the document itself cannot be moved
+        (BerestaError HIERARCHY_VIOLATION / INVALID_ARGUMENT).
+        """
+        source = self.document
+        target = parent.document
+        check(LIB.beresta_node_move_to(self.handle, parent.handle))
+        if source is not target:
+            transfer_wrappers(self, source, target)