SCIM2 Filter Parser

Warnings

• breaking When 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)`).
• gotcha The `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.
• gotcha By 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`
• gotcha The 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.

Install

• pip install scim2-filter-parser Install latest version

Imports

• 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.

Quickstart

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}")