{"id":10004,"library":"onigurumacffi","title":"Oniguruma CFFI","description":"Onigurumacffi provides Python cffi bindings for the Oniguruma regex engine. Currently at version 1.5.0, it wraps the Oniguruma C library, offering a performant, multibyte-aware regex engine that operates primarily on bytes, distinct from Python's built-in `re` module. The library bundles the Oniguruma C source, simplifying installation, and requires Python 3.10 or newer. Releases are infrequent, tied to updates in the underlying Oniguruma library or CFFI.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/asottile/onigurumacffi","tags":["regex","cffi","oniguruma","bindings","performance","bytes","pattern-matching"],"install":[{"cmd":"pip install onigurumacffi","lang":"bash","label":"Install Oniguruma CFFI"}],"dependencies":[],"imports":[{"symbol":"OnigurumaRegex","correct":"from onigurumacffi import OnigurumaRegex"},{"symbol":"OnigurumaMatch","correct":"from onigurumacffi import OnigurumaMatch"},{"symbol":"OnigurumaError","correct":"from onigurumacffi import OnigurumaError"}],"quickstart":{"code":"from onigurumacffi import OnigurumaRegex, OnigurumaMatch, OnigurumaError\n\n# Create a regex object. Oniguruma supports various encodings, UTF-8 is common.\n# Patterns are typically bytes for direct Oniguruma interaction.\nregex = OnigurumaRegex(b'^(hello|hi)\\\\s+(world|there)!$', encoding='utf-8')\n\n# Match a string (also bytes)\ntext = b'hello world!'\nmatch: OnigurumaMatch | None = regex.match(text)\n\nif match:\n    print(f\"Match found!\")\n    print(f\"Full match: {match.group(0).decode('utf-8')}\")\n    print(f\"Group 1: {match.group(1).decode('utf-8')}\")\n    print(f\"Group 2: {match.group(2).decode('utf-8')}\")\nelse:\n    print(f\"No match for '{text.decode('utf-8')}'\")\n\n# Example of a search (finding a substring match)\nsearch_text = b'some hello world! text'\nsearch_match: OnigurumaMatch | None = regex.search(search_text, start=0)\nif search_match:\n    print(f\"\\nSearch found!\")\n    print(f\"Search match: {search_match.group(0).decode('utf-8')}\")\n\n# Error handling\ntry:\n    invalid_regex = OnigurumaRegex(b'[invalid')\nexcept OnigurumaError as e:\n    print(f\"\\nCaught expected error: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize `OnigurumaRegex` with a byte pattern and encoding, perform `match` and `search` operations on byte strings, and access matched groups. It also includes basic error handling for invalid regex patterns."},"warnings":[{"fix":"Always refer to Oniguruma's official documentation for pattern syntax and behavior. Do not assume `re` module compatibility.","message":"Onigurumacffi uses the Oniguruma regex engine, which has different syntax and behavior compared to Python's built-in `re` module. Features, character classes, and performance characteristics will differ.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Check the `onigurumacffi` GitHub README for the bundled Oniguruma version. For newer versions, monitor `onigurumacffi` releases or consider custom compilation.","message":"The `onigurumacffi` library statically links against a specific version of the Oniguruma C library (e.g., 6.9.8). If you need features or bug fixes from a newer Oniguruma C version, you might need to wait for a new `onigurumacffi` release or compile it yourself.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all patterns and input strings are encoded to `bytes` (e.g., `b'pattern'` or `'string'.encode('utf-8')`) before passing them to `onigurumacffi` functions. Decode results (e.g., `match.group(1).decode('utf-8')`) for string output.","message":"Oniguruma primarily operates on bytes, not Python strings. Patterns and input text passed to `OnigurumaRegex` methods must be `bytes` objects. While an `encoding` parameter is provided, direct byte handling is often necessary.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install onigurumacffi` to install the library.","cause":"The `onigurumacffi` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'onigurumacffi'"},{"fix":"Review and correct your regex pattern, consulting Oniguruma's documentation for proper syntax. Common issues include unescaped special characters or malformed groups.","cause":"The regular expression pattern provided is syntactically invalid according to the Oniguruma engine's rules.","error":"onigurumacffi.OnigurumaError: (syntax error) ..."},{"fix":"Encode your string pattern or input text to bytes. For example, change `'your_pattern'` to `b'your_pattern'` or `'your_string'.encode('utf-8')`.","cause":"You are passing a Python `str` object to `OnigurumaRegex` constructor or a match method, but it expects a `bytes` object.","error":"TypeError: argument 'pattern' must be bytes, not str"}]}