ransacklib 0.1.10__tar.gz

ransacklib-0.1.10/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rajmund H. Hruska
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ransacklib-0.1.10/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: ransacklib
+Version: 0.1.10
+Summary: A modern, extensible language for manipulation with structured data
+Author-email: "Rajmund H. Hruška" <rajmund.hruska@cesnet.cz>
+License-Expression: MIT
+Project-URL: Repository, https://gitlab.cesnet.cz/713/mentat/ransack
+Project-URL: Documentation, https://ransack-125e0a.gitlab-pages.cesnet.cz/index.html
+Project-URL: Issues, https://gitlab.cesnet.cz/713/mentat/ransack/-/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: lark<1.3.0,>=1.2.2
+Requires-Dist: ipranges<0.2,>=0.1.12
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flake8-pytest-style; extra == "dev"
+Requires-Dist: flake8-bugbear; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx_rtd_theme; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Dynamic: license-file
+
+Welcome to ransack
+==================
+
+**ransack** is a modern, extensible language for manipulation with structured data.
+
+Structured data --- like `JSON <https://json.org>`_, `YAML <https://yaml.org/>`_, `TOML <https://toml.io/>`_ and domain-specific formats such as `IDEA <https://idea.cesnet.cz>`_ --- form the backbone of many modern applications. These formats appear in configuration files, security logs, telemetry systems, and beyond.
+
+**ransack** was designed to meet the increasing need for a robust and expressive language to query, filter, and inspect structured data. Whether used in Python code, as part of a log analysis tool, or as a compiler frontend for other systems, **ransack** provides a flexible foundation.
+
+Why ransack?
+------------
+
+ransack is a new implementation and improvement over existing libraries like *Pynspect*, which was widely used in security monitoring systems like `NEMEA <https://nemea.liberouter.org/>`_ and `Mentat <https://mentat.cesnet.cz>`_. Compared to older tools, ransack:
+
+- supports **user-defined variables**
+- enables **multi-argument functions**
+- is **extensible** and **modular**
+- supports **multiple backends** (e.g., Python evaluation, SQL translation)
+- offers a clean internal architecture for future enhancements
+
+Key features
+------------
+
+- a simple and expressive syntax for filters and conditions
+- support for context-aware variables and data scoping
+- predefined functions
+- support for IPv4/IPv6, datetimes, string and list manipulation
+- safe and maintainable implementation using `Lark <https://lark-parser.readthedocs.io/en/stable/>`_ for parsing
+

ransacklib-0.1.10/README.rst

@@ -0,0 +1,29 @@
+Welcome to ransack
+==================
+
+**ransack** is a modern, extensible language for manipulation with structured data.
+
+Structured data --- like `JSON <https://json.org>`_, `YAML <https://yaml.org/>`_, `TOML <https://toml.io/>`_ and domain-specific formats such as `IDEA <https://idea.cesnet.cz>`_ --- form the backbone of many modern applications. These formats appear in configuration files, security logs, telemetry systems, and beyond.
+
+**ransack** was designed to meet the increasing need for a robust and expressive language to query, filter, and inspect structured data. Whether used in Python code, as part of a log analysis tool, or as a compiler frontend for other systems, **ransack** provides a flexible foundation.
+
+Why ransack?
+------------
+
+ransack is a new implementation and improvement over existing libraries like *Pynspect*, which was widely used in security monitoring systems like `NEMEA <https://nemea.liberouter.org/>`_ and `Mentat <https://mentat.cesnet.cz>`_. Compared to older tools, ransack:
+
+- supports **user-defined variables**
+- enables **multi-argument functions**
+- is **extensible** and **modular**
+- supports **multiple backends** (e.g., Python evaluation, SQL translation)
+- offers a clean internal architecture for future enhancements
+
+Key features
+------------
+
+- a simple and expressive syntax for filters and conditions
+- support for context-aware variables and data scoping
+- predefined functions
+- support for IPv4/IPv6, datetimes, string and list manipulation
+- safe and maintainable implementation using `Lark <https://lark-parser.readthedocs.io/en/stable/>`_ for parsing
+

ransacklib-0.1.10/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ransacklib"
+dynamic = ["version"]
+description = "A modern, extensible language for manipulation with structured data"
+license = "MIT"
+readme = "README.rst"
+dependencies = [
+  "lark>=1.2.2,<1.3.0",
+  "ipranges>=0.1.12,<0.2",
+]
+requires-python = ">=3.9"
+authors = [
+  {name = "Rajmund H. Hruška", email = "rajmund.hruska@cesnet.cz"}
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "pytest-cov",
+  "flake8",
+  "flake8-pytest-style",
+  "flake8-bugbear",
+  "sphinx",
+  "sphinx_rtd_theme",
+  "black",
+  "mypy",
+  "isort",
+]
+
+[project.urls]
+Repository = "https://gitlab.cesnet.cz/713/mentat/ransack"
+Documentation = "https://ransack-125e0a.gitlab-pages.cesnet.cz/index.html"
+Issues = "https://gitlab.cesnet.cz/713/mentat/ransack/-/issues"
+
+[tool.setuptools]
+packages = ["ransack"]
+
+[tool.setuptools.dynamic]
+version = {attr = "ransack.__version__"}
+
+[tool.setuptools.package-data]
+ransack = ["py.typed"]
+
+[tool.mypy]
+mypy_path = "$MYPY_CONFIG_FILE_DIR/typings"
+
+[tool.isort]
+profile = "black"

ransacklib-0.1.10/ransack/__init__.py

@@ -0,0 +1,15 @@
+from .exceptions import EvaluationError, ParseError, RansackError, ShapeError
+from .parser import Parser
+from .transformer import Filter, get_values
+
+__version__ = "0.1.10"
+
+__all__ = (
+    "get_values",
+    "Parser",
+    "Filter",
+    "RansackError",
+    "ParseError",
+    "ShapeError",
+    "EvaluationError",
+)

ransacklib-0.1.10/ransack/exceptions.py

@@ -0,0 +1,118 @@
+"""Custom exceptions for Ransack query parsing, evaluation, and shape validation."""
+
+from typing import Any, Optional
+
+
+class RansackError(Exception):
+    """Base exception for all query-related errors."""
+
+
+class PositionInfoMixin:
+    """Mixin class that adds source position metadata to exceptions."""
+
+    def __init__(
+        self,
+        line: int,
+        column: int,
+        context: Optional[str] = None,
+        start_pos: Optional[int] = None,
+        end_pos: Optional[int] = None,
+        end_line: Optional[int] = None,
+        end_column: Optional[int] = None,
+        *args,
+        **kwargs,
+    ):
+        self.line = line
+        self.column = column
+        self.context = context
+        self.start_pos = start_pos
+        self.end_pos = end_pos
+        self.end_line = end_line
+        self.end_column = end_column
+        super().__init__(*args, **kwargs)
+
+
+class ParseError(PositionInfoMixin, RansackError):
+    """Raised when the input query cannot be parsed."""
+
+    def __str__(self):
+        return f"Syntax error at line {self.line}, column {self.column}.\n\n{self.context}"  # noqa
+
+
+class ShapeError(PositionInfoMixin, RansackError):
+    """Raised when a query has an invalid shape or structure."""
+
+    def __init__(self, msg: str, **kwargs):
+        self.msg = msg
+        super().__init__(**kwargs)
+
+    def __str__(self):
+        return f"Error at line {self.line}, column {self.column}.\n\n{self.msg}\n\n{self.context}"  # noqa
+
+
+class EvaluationError(PositionInfoMixin, RansackError):
+    """Raised when a query fails during evaluation."""
+
+    def __init__(self, msg: str, **kwargs):
+        self.msg = msg
+        super().__init__(**kwargs)
+
+    def __str__(self):
+        return f"Error at line {self.line}, column {self.column}.\n\n{self.msg}"
+
+
+class OperatorNotFoundError(RansackError):
+    """Exception raised when an operator is not found for the provided types."""
+
+    def __init__(
+        self,
+        operator: str,
+        types: tuple[type | str, type | str],
+        values: tuple[Any, Any] | None = None,
+    ):
+        """
+        Initialize the exception with operator, operand types, and optional values.
+
+        Args:
+            operator: The operator that was attempted.
+            types: The types of the operands.
+            values: The values of the operands. Defaults to None.
+        """
+        self.operator = operator
+        self.types = types
+        self.values = values
+        message = f"Operator '{operator}' not found for types {types}"
+        if values:
+            message += f" with values {values}"
+        super().__init__(message)
+
+
+def add_caret_to_context(
+    context: str, line: int, column: int, original_data: str, context_start_pos: int
+) -> str:
+    """
+    Inserts a caret (^) under the character at (line, column) relative
+    to the full input. `context` is a slice of the full input string.
+    `line` and `column` are from the parser (1-based).
+    """
+    # Recalculate absolute position
+    lines_up_to_error = original_data.splitlines()[0 : line - 1]
+    absolute_error_pos = (
+        sum(len(lines) + 1 for lines in lines_up_to_error) + column - 1
+    )  # +1 for newline
+
+    caret_pos_in_context = absolute_error_pos - context_start_pos
+
+    # Sanity check
+    if caret_pos_in_context < 0 or caret_pos_in_context > len(context):
+        return context  # fallback, avoid crashing
+
+    # Find line offset in context
+    line_start = context.rfind("\n", 0, caret_pos_in_context) + 1
+    line_end = context.find("\n", caret_pos_in_context)
+    if line_end == -1:
+        line_end = len(context)
+
+    caret_line = " " * (caret_pos_in_context - line_start) + "^"
+
+    return context[:line_end] + "\n" + caret_line + context[line_end:]

ransacklib-0.1.10/ransack/function.py

@@ -0,0 +1,38 @@
+"""
+function.py - Defines built-in functions usable in query expressions.
+
+This module provides a set of predefined utility functions that can be invoked from
+within query expressions. These functions enable common operations such as determining
+the length of a value or obtaining the current time.
+
+Functions:
+    - length(x): Returns the length of a string, list, or IP range/network.
+    - now(): Returns the current UTC datetime.
+
+These functions are registered in the `predefined_functions` dictionary and are
+automatically available during query evaluation.
+
+Example usage in query:
+    length(some_field) > 3 or now() > 2024-01-01T00:00:00Z
+"""
+
+import datetime
+
+from ipranges import IP4, IP6, IP4Net, IP4Range, IP6Net, IP6Range
+
+
+def length(x):
+    if isinstance(x, (list, str, IP4, IP4Net, IP4Range, IP6, IP6Net, IP6Range)):
+        return len(x)
+    raise TypeError(f"Function length is not defined for value {x}")
+
+
+def now():
+    return datetime.datetime.now(datetime.timezone.utc)
+
+
+predefined_functions = {
+    "length": length,
+    "len": length,
+    "now": now,
+}