# json-criteria
`json-criteria` is a lightweight, dependency-free Python library designed for evaluating data against serializable JSON criteria. It offers a variety of built-in operators, supports custom operators, and can handle complex nested conditions, making it a valuable and flexible tool for condition-based decision-making.
## Why use `json-criteria`?
* **Serialization to JSON**
* The criteria used by `json-criteria` can be easily serialized to JSON format. This enables the persistence of criteria, making it suitable for storage in databases or external configurations.
* **Dynamic Criteria Adjustment**
* Since the criteria is stored as JSON, it allows for dynamic adjustments without the need for code deployment. Criteria can be modified or extended as needed, providing the ability to adapt application behavior without code changes.
* **Flexibility and Maintainability**
* Storing conditions in a serializable format enhances application flexibility and maintainability. Criteria can be fine-tuned, added, or removed independently of the application code, resulting in a more adaptable and easier-to-maintain system.
* **Dependency-Free**
* `json-criteria` is intentionally designed to be lightweight and dependency-free, ensuring ease of integration into diverse projects without introducing unnecessary dependencies.
In summary, `json-criteria` empowers developers with a versatile and lightweight solution for handling criteria, fostering a more dynamic, adaptable, and maintainable approach to decision-making in applications.
## Examples
### Simple Condition
Evaluate a single condition:
```python
from json_criteria import meets_criteria
# Define a record and criteria
record = {'name': 'Joe', 'age': 30}
criteria = {'key': 'age', 'op': 'equal_to', 'value': 30}
# Check if the record meets the criteria
# `result` will be True
result = meets_criteria(record, criteria)
```
### Nested Conditions
Handle more complex scenarios with nested conditions:
```python
from json_criteria import meets_criteria
# Define a record
record = {
'name': 'Alice',
'age': 28,
'department': 'Engineering',
'experience_years': 5,
'is_manager': False
}
# criteria:
# (age >= 25 AND experience_years >= 3) OR (department is 'Engineering' AND is_manager is True)
criteria = {
'OR': [
{'AND': [
{'key': 'age', 'op': 'greater_than_or_equal_to', 'value': 25},
{'key': 'experience_years', 'op': 'greater_than_or_equal_to', 'value': 3}
]},
{'AND': [
{'key': 'department', 'op': 'equals', 'value': 'Engineering'},
{'key': 'is_manager', 'op': 'equals', 'value': True}
]}
]
}
# Check if the record meets the criteria
# `result` will be True
result = meets_criteria(record, criteria)
```
### Simple Custom Operator
Pass in a `Config` object to specify custom operators.
```python
from json_criteria import meets_criteria, Config
def custom1(record_value, value):
return record_value + value == 60
record = { 'name': 'Joe', 'age': 30 }
criteria = { 'key': 'age', 'op': 'custom1', 'value': 30 }
config = Config(custom_ops = { 'custom1': custom1 })
# `result` will be True
result = meets_criteria(record, criteria, config)
```
These examples demonstrate the simplicity and flexibility of `json_criteria` in handling both basic and intricate conditions for evaluating data. The library's support for nested conditions enables the representation of complex logical structures, making it a valuable tool for decision-making in various scenarios.
## Criteria
Criteria in `json-criteria` are represented as dictionaries, specifying the conditions that record(s) must satisfy. This allows for flexible and expressive criteria, supporting both simple conditions and intricate logical structures with AND, OR, and NOT operators.
A condition is composed of three fundamental components:
* `key`: The key to be evaluated.
* `op`: The operator indicating the comparison type.
* `value`: The expected value for the specified key.
Additional keys, such as `id` and `description`, can be included without impacting functionality. This feature provides the flexibility to add context or relevant information to the criteria.
### Built-In Operators:
* `equal_to`
* `not_equal_to`
* `greater_than`
* `less_than`
* `greater_than_or_equal_to`
* `less_than_or_equal_to`
* `in`
* `not_in`
* `contains`
* `not_contains`
* `starts_with`
* `not_starts_with`
* `ends_with`
* `not_ends_with`
* `matches_regex`
These operators provide a comprehensive set of comparisons to handle a wide range of conditions in your criteria.
## API
Below you will find documentation for each library function, including examples.
### `all_meet_criteria`
Determine if all records in a given list meet the specified criteria. This function evaluates whether all records in the provided list satisfy the specified criteria, providing a straightforward way to ensure that the entire dataset meets the required conditions.
```python
from json_criteria import all_meet_criteria
# Define a list of user records
user_records = [
{'name': 'Alice', 'age': 28, 'department': 'Engineering', 'is_manager': False},
{'name': 'Bob', 'age': 35, 'department': 'Marketing', 'is_manager': True},
{'name': 'Charlie', 'age': 45, 'department': 'Sales', 'is_manager': False}
]
# criteria: age >= 25 AND (is_manager is True OR department is 'Engineering')
criteria = {
'AND': [
{'key': 'age', 'op': 'greater_than_or_equal_to', 'value': 25},
{'OR': [
{'key': 'is_manager', 'op': 'equals', 'value': True},
{'key': 'department', 'op': 'equals', 'value': 'Engineering'}
]}
]
}
# Check if all user records meet the criteria
# `result` will be True
result = all_meet_criteria(user_records, criteria)
```
### `any_meet_criteria`
This function determines whether any record in the provided list satisfies the specified criteria, offering a convenient way to identify if at least one record meets the required conditions.
```python
from json_criteria import any_meet_criteria
# Define a list of employee records and a criteria
employee_records = [
{'name': 'Alice', 'age': 32, 'department': 'Sales'},
{'name': 'Bob', 'age': 45, 'department': 'Marketing'},
{'name': 'Charlie', 'age': 28, 'department': 'Engineering'},
{'name': 'David', 'age': 37, 'department': 'Sales'},
]
# criteria: age greater than 35 OR (department is 'Engineering' AND age is less than 30)
criteria = {
'OR': [
{'key': 'age', 'op': 'greater_than', 'value': 35},
{'AND': [
{'key': 'department', 'op': 'equal_to', 'value': 'Engineering'},
{'key': 'age', 'op': 'less_than', 'value': 30}
]}
]
}
# Check if any employee record meets the criteria
# `result` will be True
result = any_meet_criteria(employee_records, criteria)
```
### `apply_using_criteria`
Apply a specified function to each record that meets the given criteria. This function allows for targeted and conditional transformations on a list of records, enhancing flexibility in data manipulation.
```python
from json_criteria import apply_using_criteria
# Define a list of user records and a criteria
user_records = [
{'name': 'Joe', 'age': 30, 'department': 'Sales'},
{'name': 'John', 'age': 60, 'department': 'Marketing'},
{'name': 'Alice', 'age': 25, 'department': 'Engineering'},
]
# criteria: Apply the function to records where age is less than 40 AND belong to the 'Engineering' department
criteria = {
'AND': [
{'key': 'age', 'op': 'less_than', 'value': 40},
{'key': 'department', 'op': 'equal_to', 'value': 'Engineering'}
]
}
# Define a function to apply (e.g., mark users as active)
def mark_as_active(record):
record['is_active'] = True
return record
# Apply the specified function to records meeting the criteria
# `result` will be:
# [{'name': 'Joe', 'age': 30, 'department': 'Sales'},
# {'name': 'John', 'age': 60, 'department': 'Marketing'},
# {'name': 'Alice', 'age': 25, 'department': 'Engineering', 'is_active': True}]
result = apply_using_criteria(user_records, criteria, mark_as_active)
```
### `combine_criteria`
Combine multiple criteria using the AND or OR operator. This function allows for the composition of more complex logical conditions by nesting individual criteria within a larger structure.
```python
from json_criteria import combine_criteria
# Define two individual criteria
criteria1 = {
'AND': [
{'key': 'name', 'op': 'starts_with', 'value': 'S'},
{'key': 'age', 'op': 'equal_to', 'value': 100}
]
}
criteria2 = {
'OR': [
{'key': 'name', 'op': 'starts_with', 'value': 'L'},
{'key': 'age', 'op': 'equal_to', 'value': 20}
]
}
# Combine criteria using the AND operator
# `result` will be:
# {
# 'AND': [
# { 'AND': [
# { 'key': 'name', 'op': 'starts_with', 'value': 'S' },
# { 'key': 'age', 'op': 'equal_to', 'value': 100 }
# ]
# },
# { 'OR': [
# { 'key': 'name', 'op': 'starts_with', 'value': 'L' },
# { 'key': 'age', 'op': 'equal_to', 'value': 20 }
# ]
# }
# ]
# }
result = combine_criteria('AND', [criteria1, criteria2])
```
### `filter_using_criteria`
Filter a list of records based on the given criteria. This function provides a mechanism for selectively extracting records that meet specific conditions, enhancing the flexibility of data filtering.
```python
from json_criteria import filter_using_criteria
# Define a list of employee records
employee_records = [
{'name': 'Alice', 'age': 28, 'department': 'Engineering', 'is_manager': False},
{'name': 'Bob', 'age': 35, 'department': 'Marketing', 'is_manager': True},
{'name': 'Charlie', 'age': 45, 'department': 'Sales', 'is_manager': False},
{'name': 'Susan', 'age': 30, 'department': 'Engineering', 'is_manager': True}
]
# criteria: (age >= 30 AND is_manager is True) OR (department is 'Engineering' AND name starts with 'S')
criteria = {
'OR': [
{'AND': [
{'key': 'age', 'op': 'greater_than_or_equal_to', 'value': 30},
{'key': 'is_manager', 'op': 'equals', 'value': True}
]},
{'AND': [
{'key': 'department', 'op': 'equals', 'value': 'Engineering'},
{'key': 'name', 'op': 'starts_with', 'value': 'S'}
]}
]
}
# Filter employee records based on the criteria
# `result` will be: [
# {'name': 'Bob', 'age': 35, 'department': 'Marketing', 'is_manager': True},
# {'name': 'Susan', 'age': 30, 'department': 'Engineering', 'is_manager': True}
# ]
result = filter_using_criteria(employee_records, criteria)
```
### `find_using_criteria`
Find the first record that meets the given criteria. Returns `None` if none is found. This function provides a convenient way to locate the initial occurrence of a record satisfying specific conditions within a list.
```python
from json_criteria import find_using_criteria
# Define a list of employee records
employee_records = [
{'name': 'Alice', 'age': 28, 'department': 'Engineering', 'is_manager': False},
{'name': 'Bob', 'age': 35, 'department': 'Marketing', 'is_manager': True},
{'name': 'Charlie', 'age': 45, 'department': 'Sales', 'is_manager': False},
{'name': 'Susan', 'age': 30, 'department': 'Engineering', 'is_manager': True}
]
# criteria: Find the first employee who is a manager and older than 30
criteria = {'AND': [
{'key': 'is_manager', 'op': 'equals', 'value': True},
{'key': 'age', 'op': 'greater_than', 'value': 30}
]}
# Find the first employee record meeting the criteria
# `result` will be: {'name': 'Bob', 'age': 35, 'department': 'Marketing', 'is_manager': True}
result = find_using_criteria(employee_records, criteria)
```
### `get_all_criteria`
Given a record and a list of criteria, get all criteria that the record meets. This function is useful for analyzing and identifying the specific criteria that a record satisfies within a given list.
```python
from json_criteria import get_all_criteria
# Define a user
user = {
'name': 'Alice',
'age': 28,
'interests': ['Technology', 'Books'],
'purchased_products': ['Laptop']
}
# criteria list:
criteria_list = [
# User has an interest in 'Technology' AND (User is older than 25 OR User has purchased a 'Laptop')
{'id': 10, 'AND': [
{'key': 'interests', 'op': 'contains', 'value': 'Technology'},
{'OR': [
{'key': 'age', 'op': 'greater_than', 'value': 25},
{'key': 'purchased_products', 'op': 'contains', 'value': 'Laptop'}
]}
]},
# User has an interest in 'Books' AND User has not purchased a 'Tablet'
{'id': 11, 'AND': [
{'key': 'interests', 'op': 'contains', 'value': 'Books'},
{'key': 'purchased_products', 'op': 'not_contains', 'value': 'Tablet'}
]}
]
# Get all criteria that the user meets
# `result` will be:
# [{'id': 10, 'AND': [
# {'key': 'interests', 'op': 'contains', 'value': 'Technology'},
# {'OR': [
# {'key': 'age', 'op': 'greater_than', 'value': 25},
# {'key': 'purchased_products', 'op': 'contains', 'value': 'Laptop'}
# ]}
# ]}]
result = get_all_criteria(user, criteria_list)
```
### `meets_criteria`
Determine if a record meets the given criteria. This function provides a flexible and expressive way to evaluate whether a record satisfies specified conditions, supporting a variety of operators for comprehensive criteria checks.
```python
from json_criteria import meets_criteria
# Define a record for a user
user_record = {
'user_type': 1,
'email': 'test@email.com',
'is_active': True,
'age': 30,
'department': 'Engineering'
}
# Criteria Description:
# - User type is 1
# - AND (Email ends with '@email.com' OR (Is active AND Age is less than 40))
# - AND (Department is 'Engineering' AND (Is active OR Age is greater than or equal to 30))
# - AND (User type is not 2 AND Email does not end with '@test.com')
criteria = {
'AND': [
{'key': 'user_type', 'op': 'equal_to', 'value': 1},
{'OR': [
{'key': 'email', 'op': 'ends_with', 'value': '@email.com'},
{'AND': [
{'key': 'is_active', 'op': 'equal_to', 'value': True},
{'key': 'age', 'op': 'less_than', 'value': 40}
]}
]},
{'AND': [
{'key': 'department', 'op': 'equal_to', 'value': 'Engineering'},
{'OR': [
{'key': 'is_active', 'op': 'equal_to', 'value': True},
{'key': 'age', 'op': 'greater_than_or_equal_to', 'value': 30}
]}
]},
{'AND': [
{'key': 'user_type', 'op': 'not_equal_to', 'value': 2},
{'key': 'email', 'op': 'not_ends_with', 'value': '@test.com'}
]}
]
}
# Check if the user record meets the specified criteria
# `result` will be True
result = meets_criteria(user_record, criteria)
```
### Configuration
Configuring `json-criteria` is optional. By default, the library works without any additional setup. However, if you want to customize the behavior, such as adding custom operators, you can create a `Config` object and pass it to the library function being called. Available configuration options are detailed below.
#### custom_ops
This option allows you to define custom operators. To use it, provide a dictionary where the keys are the operator names, and the values are the corresponding operator functions. Each operator function receives two arguments:
1. `record_value`: The value from the data record.
2. `value`: The value specified in the criteria.
```python
from json_criteria import Config
def same_len(record_value, value):
return len(record_value) == len(value)
config = Config(custom_ops = { 'same_len': same_len })
```
## Contributing Guide
I welcome all pull requests. Please make sure you add appropriate test cases for any features added.
To run tests: `python3 -m unittest`
To lint: `pylint src`
Raw data
{
"_id": null,
"home_page": null,
"name": "json-criteria",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "adaptable, compare, comparison, conditions, criteria, data evaluation, decision making, decision-making, decisions, dependency-free, dynamic adjustment, eligibility, evaluation, flexibility, flexible, json, logic, maintainability, maintainable, nested, nested conditions, operators, persistence, rules, serializable, serialization, serialized",
"author": "Matthew Fay",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cf/11/a3bc61a23cef9d4109500f1870787a2d3da92f8ee700e67ff2214c50c0cf/json_criteria-0.2.0.tar.gz",
"platform": null,
"description": "# json-criteria\n\n`json-criteria` is a lightweight, dependency-free Python library designed for evaluating data against serializable JSON criteria. It offers a variety of built-in operators, supports custom operators, and can handle complex nested conditions, making it a valuable and flexible tool for condition-based decision-making.\n\n## Why use `json-criteria`?\n\n* **Serialization to JSON**\n * The criteria used by `json-criteria` can be easily serialized to JSON format. This enables the persistence of criteria, making it suitable for storage in databases or external configurations.\n* **Dynamic Criteria Adjustment**\n * Since the criteria is stored as JSON, it allows for dynamic adjustments without the need for code deployment. Criteria can be modified or extended as needed, providing the ability to adapt application behavior without code changes.\n* **Flexibility and Maintainability**\n * Storing conditions in a serializable format enhances application flexibility and maintainability. Criteria can be fine-tuned, added, or removed independently of the application code, resulting in a more adaptable and easier-to-maintain system.\n* **Dependency-Free**\n * `json-criteria` is intentionally designed to be lightweight and dependency-free, ensuring ease of integration into diverse projects without introducing unnecessary dependencies.\n\nIn summary, `json-criteria` empowers developers with a versatile and lightweight solution for handling criteria, fostering a more dynamic, adaptable, and maintainable approach to decision-making in applications.\n\n## Examples\n\n### Simple Condition\n\nEvaluate a single condition:\n\n```python\nfrom json_criteria import meets_criteria\n\n# Define a record and criteria\nrecord = {'name': 'Joe', 'age': 30}\ncriteria = {'key': 'age', 'op': 'equal_to', 'value': 30}\n\n# Check if the record meets the criteria\n# `result` will be True\nresult = meets_criteria(record, criteria)\n```\n\n### Nested Conditions\n\nHandle more complex scenarios with nested conditions:\n\n```python\nfrom json_criteria import meets_criteria\n\n# Define a record\nrecord = {\n 'name': 'Alice',\n 'age': 28,\n 'department': 'Engineering',\n 'experience_years': 5,\n 'is_manager': False\n}\n\n# criteria:\n# (age >= 25 AND experience_years >= 3) OR (department is 'Engineering' AND is_manager is True)\ncriteria = {\n 'OR': [\n {'AND': [\n {'key': 'age', 'op': 'greater_than_or_equal_to', 'value': 25},\n {'key': 'experience_years', 'op': 'greater_than_or_equal_to', 'value': 3}\n ]},\n {'AND': [\n {'key': 'department', 'op': 'equals', 'value': 'Engineering'},\n {'key': 'is_manager', 'op': 'equals', 'value': True}\n ]}\n ]\n}\n\n# Check if the record meets the criteria\n# `result` will be True\nresult = meets_criteria(record, criteria)\n```\n\n### Simple Custom Operator\n\nPass in a `Config` object to specify custom operators.\n\n```python\nfrom json_criteria import meets_criteria, Config\n\ndef custom1(record_value, value):\n return record_value + value == 60\n\nrecord = { 'name': 'Joe', 'age': 30 }\ncriteria = { 'key': 'age', 'op': 'custom1', 'value': 30 }\nconfig = Config(custom_ops = { 'custom1': custom1 })\n\n# `result` will be True\nresult = meets_criteria(record, criteria, config)\n```\n\nThese examples demonstrate the simplicity and flexibility of `json_criteria` in handling both basic and intricate conditions for evaluating data. The library's support for nested conditions enables the representation of complex logical structures, making it a valuable tool for decision-making in various scenarios.\n\n## Criteria\n\nCriteria in `json-criteria` are represented as dictionaries, specifying the conditions that record(s) must satisfy. This allows for flexible and expressive criteria, supporting both simple conditions and intricate logical structures with AND, OR, and NOT operators.\n\nA condition is composed of three fundamental components:\n\n* `key`: The key to be evaluated.\n* `op`: The operator indicating the comparison type.\n* `value`: The expected value for the specified key.\n\nAdditional keys, such as `id` and `description`, can be included without impacting functionality. This feature provides the flexibility to add context or relevant information to the criteria.\n\n### Built-In Operators:\n\n* `equal_to`\n* `not_equal_to`\n* `greater_than`\n* `less_than`\n* `greater_than_or_equal_to`\n* `less_than_or_equal_to`\n* `in`\n* `not_in`\n* `contains`\n* `not_contains`\n* `starts_with`\n* `not_starts_with`\n* `ends_with`\n* `not_ends_with`\n* `matches_regex`\n\nThese operators provide a comprehensive set of comparisons to handle a wide range of conditions in your criteria.\n\n## API\n\nBelow you will find documentation for each library function, including examples.\n\n### `all_meet_criteria`\n\nDetermine if all records in a given list meet the specified criteria. This function evaluates whether all records in the provided list satisfy the specified criteria, providing a straightforward way to ensure that the entire dataset meets the required conditions.\n\n```python\nfrom json_criteria import all_meet_criteria\n\n# Define a list of user records\nuser_records = [\n {'name': 'Alice', 'age': 28, 'department': 'Engineering', 'is_manager': False},\n {'name': 'Bob', 'age': 35, 'department': 'Marketing', 'is_manager': True},\n {'name': 'Charlie', 'age': 45, 'department': 'Sales', 'is_manager': False}\n]\n\n# criteria: age >= 25 AND (is_manager is True OR department is 'Engineering')\ncriteria = {\n 'AND': [\n {'key': 'age', 'op': 'greater_than_or_equal_to', 'value': 25},\n {'OR': [\n {'key': 'is_manager', 'op': 'equals', 'value': True},\n {'key': 'department', 'op': 'equals', 'value': 'Engineering'}\n ]}\n ]\n}\n\n# Check if all user records meet the criteria\n# `result` will be True\nresult = all_meet_criteria(user_records, criteria)\n```\n\n### `any_meet_criteria`\n\nThis function determines whether any record in the provided list satisfies the specified criteria, offering a convenient way to identify if at least one record meets the required conditions.\n\n```python\nfrom json_criteria import any_meet_criteria\n\n# Define a list of employee records and a criteria\nemployee_records = [\n {'name': 'Alice', 'age': 32, 'department': 'Sales'},\n {'name': 'Bob', 'age': 45, 'department': 'Marketing'},\n {'name': 'Charlie', 'age': 28, 'department': 'Engineering'},\n {'name': 'David', 'age': 37, 'department': 'Sales'},\n]\n\n# criteria: age greater than 35 OR (department is 'Engineering' AND age is less than 30)\ncriteria = {\n 'OR': [\n {'key': 'age', 'op': 'greater_than', 'value': 35},\n {'AND': [\n {'key': 'department', 'op': 'equal_to', 'value': 'Engineering'},\n {'key': 'age', 'op': 'less_than', 'value': 30}\n ]}\n ]\n}\n\n# Check if any employee record meets the criteria\n# `result` will be True\nresult = any_meet_criteria(employee_records, criteria)\n```\n\n### `apply_using_criteria`\n\nApply a specified function to each record that meets the given criteria. This function allows for targeted and conditional transformations on a list of records, enhancing flexibility in data manipulation.\n\n```python\nfrom json_criteria import apply_using_criteria\n\n# Define a list of user records and a criteria\nuser_records = [\n {'name': 'Joe', 'age': 30, 'department': 'Sales'},\n {'name': 'John', 'age': 60, 'department': 'Marketing'},\n {'name': 'Alice', 'age': 25, 'department': 'Engineering'},\n]\n\n# criteria: Apply the function to records where age is less than 40 AND belong to the 'Engineering' department\ncriteria = {\n 'AND': [\n {'key': 'age', 'op': 'less_than', 'value': 40},\n {'key': 'department', 'op': 'equal_to', 'value': 'Engineering'}\n ]\n}\n\n# Define a function to apply (e.g., mark users as active)\ndef mark_as_active(record):\n record['is_active'] = True\n return record\n\n# Apply the specified function to records meeting the criteria\n# `result` will be:\n# [{'name': 'Joe', 'age': 30, 'department': 'Sales'},\n# {'name': 'John', 'age': 60, 'department': 'Marketing'},\n# {'name': 'Alice', 'age': 25, 'department': 'Engineering', 'is_active': True}]\nresult = apply_using_criteria(user_records, criteria, mark_as_active)\n```\n\n### `combine_criteria`\n\nCombine multiple criteria using the AND or OR operator. This function allows for the composition of more complex logical conditions by nesting individual criteria within a larger structure.\n\n```python\nfrom json_criteria import combine_criteria\n\n# Define two individual criteria\ncriteria1 = {\n 'AND': [\n {'key': 'name', 'op': 'starts_with', 'value': 'S'},\n {'key': 'age', 'op': 'equal_to', 'value': 100}\n ]\n}\n\ncriteria2 = {\n 'OR': [\n {'key': 'name', 'op': 'starts_with', 'value': 'L'},\n {'key': 'age', 'op': 'equal_to', 'value': 20}\n ]\n}\n\n# Combine criteria using the AND operator\n# `result` will be:\n# {\n# 'AND': [\n# { 'AND': [\n# { 'key': 'name', 'op': 'starts_with', 'value': 'S' }, \n# { 'key': 'age', 'op': 'equal_to', 'value': 100 }\n# ] \n# },\n# { 'OR': [\n# { 'key': 'name', 'op': 'starts_with', 'value': 'L' }, \n# { 'key': 'age', 'op': 'equal_to', 'value': 20 }\n# ]\n# }\n# ]\n# }\nresult = combine_criteria('AND', [criteria1, criteria2])\n```\n\n### `filter_using_criteria`\n\nFilter a list of records based on the given criteria. This function provides a mechanism for selectively extracting records that meet specific conditions, enhancing the flexibility of data filtering.\n\n```python\nfrom json_criteria import filter_using_criteria\n\n# Define a list of employee records\nemployee_records = [\n {'name': 'Alice', 'age': 28, 'department': 'Engineering', 'is_manager': False},\n {'name': 'Bob', 'age': 35, 'department': 'Marketing', 'is_manager': True},\n {'name': 'Charlie', 'age': 45, 'department': 'Sales', 'is_manager': False},\n {'name': 'Susan', 'age': 30, 'department': 'Engineering', 'is_manager': True}\n]\n\n# criteria: (age >= 30 AND is_manager is True) OR (department is 'Engineering' AND name starts with 'S')\ncriteria = {\n 'OR': [\n {'AND': [\n {'key': 'age', 'op': 'greater_than_or_equal_to', 'value': 30},\n {'key': 'is_manager', 'op': 'equals', 'value': True}\n ]},\n {'AND': [\n {'key': 'department', 'op': 'equals', 'value': 'Engineering'},\n {'key': 'name', 'op': 'starts_with', 'value': 'S'}\n ]}\n ]\n}\n\n# Filter employee records based on the criteria\n# `result` will be: [\n# {'name': 'Bob', 'age': 35, 'department': 'Marketing', 'is_manager': True},\n# {'name': 'Susan', 'age': 30, 'department': 'Engineering', 'is_manager': True}\n# ]\nresult = filter_using_criteria(employee_records, criteria)\n```\n\n### `find_using_criteria`\n\nFind the first record that meets the given criteria. Returns `None` if none is found. This function provides a convenient way to locate the initial occurrence of a record satisfying specific conditions within a list.\n\n```python\nfrom json_criteria import find_using_criteria\n\n# Define a list of employee records\nemployee_records = [\n {'name': 'Alice', 'age': 28, 'department': 'Engineering', 'is_manager': False},\n {'name': 'Bob', 'age': 35, 'department': 'Marketing', 'is_manager': True},\n {'name': 'Charlie', 'age': 45, 'department': 'Sales', 'is_manager': False},\n {'name': 'Susan', 'age': 30, 'department': 'Engineering', 'is_manager': True}\n]\n\n# criteria: Find the first employee who is a manager and older than 30\ncriteria = {'AND': [\n {'key': 'is_manager', 'op': 'equals', 'value': True},\n {'key': 'age', 'op': 'greater_than', 'value': 30}\n]}\n\n# Find the first employee record meeting the criteria\n# `result` will be: {'name': 'Bob', 'age': 35, 'department': 'Marketing', 'is_manager': True}\nresult = find_using_criteria(employee_records, criteria)\n```\n\n### `get_all_criteria`\n\nGiven a record and a list of criteria, get all criteria that the record meets. This function is useful for analyzing and identifying the specific criteria that a record satisfies within a given list.\n\n```python\nfrom json_criteria import get_all_criteria\n\n# Define a user\nuser = {\n 'name': 'Alice',\n 'age': 28,\n 'interests': ['Technology', 'Books'],\n 'purchased_products': ['Laptop']\n}\n\n# criteria list:\ncriteria_list = [\n # User has an interest in 'Technology' AND (User is older than 25 OR User has purchased a 'Laptop')\n {'id': 10, 'AND': [\n {'key': 'interests', 'op': 'contains', 'value': 'Technology'},\n {'OR': [\n {'key': 'age', 'op': 'greater_than', 'value': 25},\n {'key': 'purchased_products', 'op': 'contains', 'value': 'Laptop'}\n ]}\n ]},\n # User has an interest in 'Books' AND User has not purchased a 'Tablet'\n {'id': 11, 'AND': [\n {'key': 'interests', 'op': 'contains', 'value': 'Books'},\n {'key': 'purchased_products', 'op': 'not_contains', 'value': 'Tablet'}\n ]}\n]\n\n# Get all criteria that the user meets\n# `result` will be:\n# [{'id': 10, 'AND': [\n# {'key': 'interests', 'op': 'contains', 'value': 'Technology'},\n# {'OR': [\n# {'key': 'age', 'op': 'greater_than', 'value': 25},\n# {'key': 'purchased_products', 'op': 'contains', 'value': 'Laptop'}\n# ]}\n# ]}]\nresult = get_all_criteria(user, criteria_list)\n```\n\n### `meets_criteria`\n\nDetermine if a record meets the given criteria. This function provides a flexible and expressive way to evaluate whether a record satisfies specified conditions, supporting a variety of operators for comprehensive criteria checks.\n\n```python\nfrom json_criteria import meets_criteria\n\n# Define a record for a user\nuser_record = {\n 'user_type': 1,\n 'email': 'test@email.com',\n 'is_active': True,\n 'age': 30,\n 'department': 'Engineering'\n}\n\n# Criteria Description:\n# - User type is 1\n# - AND (Email ends with '@email.com' OR (Is active AND Age is less than 40))\n# - AND (Department is 'Engineering' AND (Is active OR Age is greater than or equal to 30))\n# - AND (User type is not 2 AND Email does not end with '@test.com')\ncriteria = {\n 'AND': [\n {'key': 'user_type', 'op': 'equal_to', 'value': 1},\n {'OR': [\n {'key': 'email', 'op': 'ends_with', 'value': '@email.com'},\n {'AND': [\n {'key': 'is_active', 'op': 'equal_to', 'value': True},\n {'key': 'age', 'op': 'less_than', 'value': 40}\n ]}\n ]},\n {'AND': [\n {'key': 'department', 'op': 'equal_to', 'value': 'Engineering'},\n {'OR': [\n {'key': 'is_active', 'op': 'equal_to', 'value': True},\n {'key': 'age', 'op': 'greater_than_or_equal_to', 'value': 30}\n ]}\n ]},\n {'AND': [\n {'key': 'user_type', 'op': 'not_equal_to', 'value': 2},\n {'key': 'email', 'op': 'not_ends_with', 'value': '@test.com'}\n ]}\n ]\n}\n\n# Check if the user record meets the specified criteria\n# `result` will be True\nresult = meets_criteria(user_record, criteria)\n```\n\n### Configuration\n\nConfiguring `json-criteria` is optional. By default, the library works without any additional setup. However, if you want to customize the behavior, such as adding custom operators, you can create a `Config` object and pass it to the library function being called. Available configuration options are detailed below.\n\n#### custom_ops\n\nThis option allows you to define custom operators. To use it, provide a dictionary where the keys are the operator names, and the values are the corresponding operator functions. Each operator function receives two arguments:\n\n1. `record_value`: The value from the data record.\n2. `value`: The value specified in the criteria.\n\n```python\nfrom json_criteria import Config\n\ndef same_len(record_value, value):\n return len(record_value) == len(value)\n\nconfig = Config(custom_ops = { 'same_len': same_len })\n```\n\n## Contributing Guide\n\nI welcome all pull requests. Please make sure you add appropriate test cases for any features added.\n\nTo run tests: `python3 -m unittest`\n\nTo lint: `pylint src`\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library designed for evaluating data against serializable JSON criteria",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/MatthewFay/json-criteria",
"Issues": "https://github.com/MatthewFay/json-criteria/issues"
},
"split_keywords": [
"adaptable",
" compare",
" comparison",
" conditions",
" criteria",
" data evaluation",
" decision making",
" decision-making",
" decisions",
" dependency-free",
" dynamic adjustment",
" eligibility",
" evaluation",
" flexibility",
" flexible",
" json",
" logic",
" maintainability",
" maintainable",
" nested",
" nested conditions",
" operators",
" persistence",
" rules",
" serializable",
" serialization",
" serialized"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ccdbb0bc785f48d94f83f423af98db2ce2b0831724c34f731967fd81d0709ed8",
"md5": "62afa6d6fa77a30183e05b129af55694",
"sha256": "b3c8335543b56164b4eae57c3eab132abbde14a93c96dcb2fef3cb8a445a7ccf"
},
"downloads": -1,
"filename": "json_criteria-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62afa6d6fa77a30183e05b129af55694",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12947,
"upload_time": "2024-04-28T03:40:02",
"upload_time_iso_8601": "2024-04-28T03:40:02.994662Z",
"url": "https://files.pythonhosted.org/packages/cc/db/b0bc785f48d94f83f423af98db2ce2b0831724c34f731967fd81d0709ed8/json_criteria-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cf11a3bc61a23cef9d4109500f1870787a2d3da92f8ee700e67ff2214c50c0cf",
"md5": "0d25506270bd2e55b87fd4bd953ebae3",
"sha256": "14ef0aa5b006e3818028af4b870f920c25f1a6c5184b7eb8b83ddcbad340c0fb"
},
"downloads": -1,
"filename": "json_criteria-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "0d25506270bd2e55b87fd4bd953ebae3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11855,
"upload_time": "2024-04-28T03:40:04",
"upload_time_iso_8601": "2024-04-28T03:40:04.884476Z",
"url": "https://files.pythonhosted.org/packages/cf/11/a3bc61a23cef9d4109500f1870787a2d3da92f8ee700e67ff2214c50c0cf/json_criteria-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-28 03:40:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MatthewFay",
"github_project": "json-criteria",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "json-criteria"
}
JSON
