Registry / serialization / scim2-filter-parser

scim2-filter-parser

library0.7.0pypypi✓ verified 22d ago

scim2-filter-parser (SFP) is a customizable Python library designed to parse and transpile SCIM 2.0 filter queries. It breaks down SCIM queries into tokens, constructs an Abstract Syntax Tree (AST), and can then convert this AST into other query languages, such as SQL WHERE clauses or Django Q objects. The library is currently at version 0.7.0 and is actively maintained.

serialization database web-framework

pip install scim2-filter-parser

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · SCIM2-FILTER-PARSE

scim2-filter-parser

serializationpythonv0.7.0

Install

1.6s avg

Import

61ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.7.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.062s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.060s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SQLQuery

✓ from scim2_filter_parser.queries import SQLQuery

Primary class for transpiling SCIM filters to SQL.

get_query

✓ from scim2_filter_parser.transpilers.django_q_object import get_query

Function to transpile SCIM filters into Django Q objects.

This quickstart demonstrates how to use `scim2-filter-parser` to convert a SCIM filter string into a SQL WHERE clause and corresponding parameters. It highlights the use of `SQLQuery`, an `attribute_map` to link SCIM attributes to database columns, and optional `joins` for complex queries. The output provides a parameterized query suitable for execution with database connectors, emphasizing safe practices against SQL injection.

from scim2_filter_parser.queries import SQLQuery # Define a mapping from SCIM attributes to your database column names. # This is crucial for the parser to generate correct SQL. attribute_map = { 'userName': 'users.username', 'emails.value': 'emails.email_address', 'emails.type': 'emails.type', 'name.familyName': 'users.last_name', 'name.givenName': 'users.first_name' } # Define necessary SQL JOINs if your SCIM attributes span multiple tables. joins = [ 'LEFT JOIN emails ON emails.user_id = users.id' ] scim_filter = 'userName eq "bjensen" or emails[type eq "work" and value co "@example.com"]' try: # Instantiate the SQLQuery parser query_builder = SQLQuery( scim_filter=scim_filter, attribute_map=attribute_map, joins=joins ) # Get the generated SQL WHERE clause and parameters sql_where_clause = query_builder.sql query_parameters = query_builder.params print(f"Generated SQL WHERE clause: {sql_where_clause}") print(f"Query parameters: {query_parameters}") # Example of how you might use it (DO NOT run this directly without proper DB connection and sanitization): # import sqlite3 # conn = sqlite3.connect(':memory:') # cursor = conn.cursor() # # For demonstration, imagine 'users' and 'emails' tables exist # # cursor.execute(f"SELECT * FROM users {joins[0]} WHERE {sql_where_clause}", query_parameters) # # results = cursor.fetchall() # # print(f"Query results: {results}") except Exception as e: print(f"An error occurred: {e}")

Debug

Known issues

breakingWhen using the raw SQL output (e.g., from the command-line tool or if you concatenate `sql_where_clause` directly without `query_parameters`), there is a significant risk of SQL injection. The library provides `params` separately for safe parameterized query execution.

fix

Always use the `SQLQuery.sql` output as the query string and `SQLQuery.params` as the separate sequence of parameters when executing with a database driver (e.g., `cursor.execute(sql_query, query_parameters)`).

affects: All versions

gotchaThe `attribute_map` is highly specific to your database schema and must be carefully configured. Incorrect mappings will lead to invalid SQL queries or unexpected filtering behavior.

fix

Thoroughly review and test your `attribute_map` configuration to ensure SCIM attributes correctly map to your database tables and columns, including handling of complex attributes and multi-valued attributes.

affects: All versions

gotchaBy default, `SQLQuery` uses `%s` as the placeholder for query parameters, which is common in PostgreSQL. If your database (e.g., SQLite, MySQL with `?` or named parameters) requires a different placeholder, you must subclass `SQLQuery` and override the `placeholder` class variable.

fix

For databases requiring different parameter placeholders, subclass `SQLQuery`:
`class CustomSQLQuery(SQLQuery):
    placeholder = '?' # Or other required placeholder`

affects: All versions

gotchaThe library primarily demonstrates SQL output. If you intend to use it with Django models, you need to import and use `scim2_filter_parser.transpilers.django_q_object.get_query` to generate Django Q objects, which has a different API.

fix

For Django integration, import `from scim2_filter_parser.transpilers.django_q_object import get_query` and consult the GitHub README for usage examples with Django Q objects.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'scim2_filter_parser'

The `scim2-filter-parser` library has not been installed or is not available in the current Python environment.

fix

pip install scim2-filter-parser

scim2_filter_parser.exceptions.SCIMFilterSyntaxError

The provided SCIM filter string contains a syntax error, such as an incomplete expression, invalid characters, or incorrect operator usage.

fix

Review and correct the SCIM filter string to ensure it strictly adheres to the SCIM 2.0 filter syntax specification.

NameError: name 'TranspilerType' is not defined

The `TranspilerType` enum, required for specifying the target language in the `transpile` method, was used without being imported.

fix

Add `from scim2_filter_parser.transpiler import TranspilerType` to your script.

TypeError: Argument must be of type <enum 'TranspilerType'>, received type <class 'str'>

The `transpile` method expects a specific member of the `TranspilerType` enum, but a string or other incompatible type was provided instead.

fix

Pass a valid `TranspilerType` enum member, such as `TranspilerType.DJANGO_Q` or `TranspilerType.SQL`, to the `transpile` method.

Upgrade

Version history

0.7.0latest on PyPI · released Jul 20, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node