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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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.

Happy Coding

Metadata

Release files for pykolofinance 8.16.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pykolofinance 8.16.0
File	Size	Uploaded
pykolofinance-8.16.0.tar.gz	31.1 kB	May 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pykolofinance 8.16.0
File	Interpreter	ABI	Platform	Reset
pykolofinance-8.16.0-py3-none-any.whl 39.8 kB May 21, 2026	Python 3	none	any	Details

Total release size: 70.9 kB

Release files / pykolofinance-8.16.0.tar.gz

Download URL	pykolofinance-8.16.0.tar.gz
Size	31.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`54ea6ae5fe94f5d956ad4824dc7653856f2f6b87f3f8cd022741a874e773d82e`
BLAKE2b-256 checksum How to use checksums	`8be7bc9ffd4b9c7b82eb3e0137203dd123f9a9011843aff3e260d2ab13abb84d`
Upload date	May 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.4 {"installer":{"name":"uv","version":"0.11.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / pykolofinance-8.16.0-py3-none-any.whl

Download URL	pykolofinance-8.16.0-py3-none-any.whl
Size	39.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`545894dcf4d550116105178b6684b3873c06fd8d9f74e3b0f3cccaf29afa3944`
BLAKE2b-256 checksum How to use checksums	`4a431c11aa8ea886c432a93d0fdd376ebfeb6091e803be37cc6a7743656e4746`
Upload date	May 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.4 {"installer":{"name":"uv","version":"0.11.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`