eqlpy 1.0.0

EQL support library for Python 3

eqlpy

eqlpy is a Python package designed to facilitate interaction with the Encrypt Query Language (EQL). It provides classes and methods to encode and decode values when working with encrypted data in a PostgreSQL database.

Table of contents

• Features
• Installation
• Usage
  • EQL value classes
    • EqlInt
    • EqlBool
    • EqlDate
    • EqlFloat
    • EqlText
    • EqlJsonb
  • EqlRow class
• Contributing
• License
• Contact

Features

• Data type handling: Supports various data types including integers, booleans, dates, floats, text, and JSONB.
• Database formatting: Converts Python data types to the format required by EQL for database operations.
• Parsing and reconstruction: Parses and reconstructs data from the database back into Python types.

Supported database packages

Currently, eqlpy supports either of the following database packages:

• psycopg 3
• sqlalchemy + psycopg 2

For code examples of storing and querying encrypted data with CipherStash Proxy using those packages, refer to examples directory and integration tests.

Installation

To install eqlpy, use the following command:

pip install eqlpy

You can find the latest version on the Python Package Index (PyPI).

Usage

Importing the package

from eqlpy import (
    EqlInt,
    EqlBool,
    EqlDate,
    EqlFloat,
    EqlText,
    EqlJsonb,
    EqlRow
)

EQL value classes

Each EQL value class inherits from the base EqlValue class and handles specific data types.

EqlInt

Handles integer values.

eql_int = EqlInt(42, 'users', 'age')
db_format = eql_int.to_db_format()
print(db_format)

EqlBool

Handles boolean values.

eql_bool = EqlBool(True, 'users', 'is_active')
db_format = eql_bool.to_db_format()
print(db_format)

EqlDate

Handles date values.

from datetime import date

eql_date = EqlDate(date.today(), 'users', 'created_at')
db_format = eql_date.to_db_format()
print(db_format)

EqlFloat

Handles floating-point values.

eql_float = EqlFloat(3.14, 'measurements', 'value')
db_format = eql_float.to_db_format()
print(db_format)

EqlText

Handles text values.

eql_text = EqlText('Hello, World!', 'messages', 'content')
db_format = eql_text.to_db_format()
print(db_format)

EqlJsonb

Handles JSONB values.

eql_jsonb = EqlJsonb({'key': 'value'}, 'configs', 'data')
db_format = eql_jsonb.to_db_format()
print(db_format)

Parsing values from database format

Use the from_parsed_json method to convert database-formatted JSON back to Python types.

import json

db_data = '{"k": "pt", "p": "42", "i": {"t": "users", "c": "age"}, "v": 1, "q": null}'
parsed = json.loads(db_data)
value = EqlInt.from_parsed_json(parsed)
print(value)  # Output: 42

EqlRow class

EqlRow maps database rows to Python objects using a column_function_map to process each column.

from datetime import datetime

row = {
    'id': '1',
    'age': '42',
    'is_active': 'true',
    'created_at': '2021-01-01',
    'value': '3.14',
    'content': 'Hello, World!',
    'data': '{"key": "value"}'
}

column_function_map = {
    'id': int,
    'age': int,
    'is_active': lambda x: x.lower() == 'true',
    'created_at': lambda x: datetime.fromisoformat(x).date(),
    'value': float,
    'data': json.loads
}

eql_row = EqlRow(column_function_map, row)
print(eql_row.row)

Output:

{
    'id': 1,
    'age': 42,
    'is_active': True,
    'created_at': datetime.date(2021, 1, 1),
    'value': 3.14,
    'content': 'Hello, World!',
    'data': {'key': 'value'}
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request on the GitHub repository.

License

This project is licensed under the MIT License.