pykolofinance 8.14.0

A utility package for kolomoni banking microservices

Pykolofinance

A comprehensive utility package for Kolomoni banking microservices, providing authentication, logging, KYC verification, permissions management, and common banking utilities built with Django and Django REST Framework.

Features

• Custom Authentication: JWT-based authentication middleware for microservices
• Audit Logging: Comprehensive request/response logging to OpenSearch/Elasticsearch
• KYC Integration: Identity verification with multiple providers (Dojah, Mock)
• Permissions System: Flexible permission checking and management
• Common Utilities: Banking-specific helpers, serializers, and services
• OpenAPI Documentation: Auto-generated API docs with DRF Spectacular

Installation

Install Pykolofinance using pip:

pip install pykolofinance

Or using poetry:

poetry add pykolofinance

Quick Start

1. Add to Django Settings

Add pykolofinance to your INSTALLED_APPS and include the logging middleware:

INSTALLED_APPS = [
    # ... other apps
    'pykolofinance',
]

MIDDLEWARE = [
    # ... other middleware
    'pykolofinance.audtilog.opensearch_logger.#sym:OpenSearchLoggerMiddleware',
    # ... other middleware
]

2. Configure Authentication

Update your REST_FRAMEWORK settings:

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'pykolofinance.authentication.CustomJWTAuthentication',
        'rest_framework.authentication.BasicAuthentication',
        'rest_framework.authentication.SessionAuthentication',
    ),
    # ... other settings
}

3. Environment Variables

Set the required environment variables:

# For authentication service
AUTH_SERVICE_BASE_URL=https://your-auth-service-url

# For OpenSearch logging
PYKOLOFINANCE_OPENSEARCH_HOST=your-opensearch-host
PYKOLOFINANCE_OPENSEARCH_PORT=9200
PYKOLOFINANCE_OPENSEARCH_USERNAME=your-username
PYKOLOFINANCE_OPENSEARCH_PASSWORD=your-password
PYKOLOFINANCE_OPENSEARCH_INDEX_NAME=your-index-name

# Required Django settings
APP_NAME=your-app-name
ENVIRONMENT_INSTANCE=production

Usage

Authentication

The package provides a custom JWT authentication class that integrates with your authentication service:

from pykolofinance.authentication import CustomJWTAuthentication

# Automatically configured when added to REST_FRAMEWORK settings

Logging

Enable comprehensive API logging to OpenSearch with the APILoggerMiddleware:

1. Add Middleware

Add the middleware to your Django MIDDLEWARE settings:

MIDDLEWARE = [
    # ... other middleware
    'pykolofinance.audtilog.opensearch_logger.#sym:OpenSearchLoggerMiddleware',
    # ... other middleware
]

2. Configure OpenSearch

Set the required OpenSearch environment variables:

PYKOLOFINANCE_OPENSEARCH_HOST=your-opensearch-host
PYKOLOFINANCE_OPENSEARCH_PORT=9200
PYKOLOFINANCE_OPENSEARCH_USERNAME=your-username
PYKOLOFINANCE_OPENSEARCH_PASSWORD=your-password
PYKOLOFINANCE_OPENSEARCH_INDEX_NAME=your-index-name

3. Additional Settings

Configure logging behavior in your Django settings.py:

# Logging exclusions
API_LOGGER_SKIP_URL_NAME = ['health_check', 'metrics']  # Skip specific endpoints
API_LOGGER_SKIP_NAMESPACE = ['admin']  # Skip entire apps
API_LOGGER_EXCLUDE_HTTP_METHODS = ['GET']  # Exclude methods (default: GET)
API_LOGGER_EXCLUDE_KEYS = ['password', 'token', 'access', 'refresh']  # Hide sensitive data

# Additional required settings
APP_NAME = 'your-app-name'
ENVIRONMENT_INSTANCE = 'production'  # or 'staging', 'development'

The middleware automatically logs all API requests and responses, including execution time, user information, and masked sensitive data.

Configuration Validation

The package includes a get_opensearch_config() function that validates all required OpenSearch settings are properly configured:

from pykolofinance.audtilog.opensearch_logger import get_opensearch_config

# This function checks for required settings:
# - PYKOLOFINANCE_OPENSEARCH_HOST
# - PYKOLOFINANCE_OPENSEARCH_PORT
# - PYKOLOFINANCE_OPENSEARCH_USERNAME
# - PYKOLOFINANCE_OPENSEARCH_PASSWORD
# - PYKOLOFINANCE_OPENSEARCH_INDEX_NAME

config = get_opensearch_config()

KYC Verification

Use the KYC service for identity verification:

from pykolofinance.kyc.verifier import KYCVerifier

verifier = KYCVerifier()
result = verifier.verify_identity(user_data)

Permissions

Implement permission checking:

from pykolofinance.permissions.checker import PermissionChecker

checker = PermissionChecker()
if checker.has_permission(user, 'required_permission'):
    # Proceed with operation

Configuration

Required Environment Variables

• AUTH_SERVICE_BASE_URL: Base URL for the authentication service
• PYKOLOFINANCE_OPENSEARCH_HOST: OpenSearch host URL
• PYKOLOFINANCE_OPENSEARCH_PORT: OpenSearch port (default: 9200)
• PYKOLOFINANCE_OPENSEARCH_USERNAME: OpenSearch username
• PYKOLOFINANCE_OPENSEARCH_PASSWORD: OpenSearch password
• PYKOLOFINANCE_OPENSEARCH_INDEX_NAME: OpenSearch index name for logs

Required Django Settings

Add these to your Django settings.py:

APP_NAME = 'your-app-name'  # Required for logging
ENVIRONMENT_INSTANCE = 'production'  # or 'staging', 'development'

Optional Settings

Configure logging behavior:

# Logging exclusions
API_LOGGER_SKIP_URL_NAME = ['health_check', 'metrics']  # Skip specific endpoints
API_LOGGER_SKIP_NAMESPACE = ['admin']  # Skip entire apps
API_LOGGER_EXCLUDE_HTTP_METHODS = ['GET', 'PATCH']  # Exclude HTTP methods
API_LOGGER_EXCLUDE_KEYS = ['password', 'token', 'access', 'refresh']  # Hide sensitive data

Dependencies

• Django >= 5.2.14
• Django REST Framework >= 3.17.1
• Django REST Framework Simple JWT >= 5.5.1
• DRF Spectacular >= 0.29.0
• OpenSearch Python >= 3.2.0
• Redis >= 7.4.0
• And more...

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/your-repo/pykolofinance.git
cd pykolofinance

# Install dependencies
pip install -e .
pip install -r requirements.txt

# Run tests
pytest

Building

uv build

Publishing

uv publish

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Release Notes

Latest Updates

• OpenSearch Logger Middleware Update: Updated middleware path from pykolofinance.audtilog.logger.APILoggerMiddleware to pykolofinance.audtilog.opensearch_logger.OpenSearchLoggerMiddleware for improved organization and clarity.

For a complete list of changes, see the CHANGELOG.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions or issues, please open an issue on GitHub or contact the maintainers.

Sensitive data will be replaced with "FILTERED".

---

= KYC

== 1. Verification

The service includes a KYC verification service. There are three verification types:

. BVN . NIN . BVN_SELFIE

We currently have two providers:

. MOCK . DOJAH

By default, the provider is set to MOCK. To override the default value, set PYKOLO_DEFAULT_IDENTITY_SERVICE in your settings file to your preferred provider:

[source,python]

PYKOLO_DEFAULT_IDENTITY_SERVICE = "DOJAH"

Please note that when you switch the provider to DOJAH, you are required to set DOJAH_API_URL, DOJAH_APP_ID, and DOJAH_API_KEY in your settings.py file. Please note that the DOJAH API URL must be without a trailing slash /.

[source,python]

from pykolofinance.kyc.verifier import get_identity_data

identity_data = get_identity_data(identity_type, identity_number, image=None, user_id=None)

Note that an image is required while verifying BVN_SELFIE.

.Table Contributors |=== |Name |Role |Email |Daniel Ale |SA |[e-mail] |Isaiah Aimiton |BE |[e-mail] |=== [quote]

---

Happy Coding

---