jlframework 1.0.19

A modular Python framework for full-stack development with Azure integration, SMS, SharePoint, and automation capabilities

JLFramework

A modular Python framework for full-stack development with FastAPI and Vue.js, plus comprehensive automation utilities for Azure, SMS, SharePoint, SQL, and more. Create production-ready applications in minutes with Django-like scaffolding and importable utilities.

✨ Features

🎯 Modular Architecture (New in v1.0.18!)

• Install Only What You Need - Three namespaces: core, automation, web
• Reduced Container Sizes - 3-9% smaller containers with optional dependencies
• Flexible Installation - Choose automation, web, or both
• 100% Backward Compatible - All existing code continues to work

🚀 Rapid Development

• Rapid Scaffolding - Create full-stack projects in under 5 minutes
• Production-Ready Templates - FastAPI backend + Vue.js frontends with best practices
• Django-like Experience - Clean imports and intuitive CLI commands

🏗️ Full-Stack Templates

• Multiple Frontend Options - Embedded, features, and marketplace templates
• Flexible & Modular - Use only what you need, mix and match templates
• Docker Ready - Dockerfiles included for all templates

🔧 Automation Utilities

• SMS Integration - Send SMS via Twilio with delivery tracking
• SharePoint/Email - Microsoft Graph API integration for emails and file operations
• SQL Management - Connection pooling, async/sync queries, retry logic
• Notifications - Automatic Slack and Teams notifications with decorators
• Azure Integration - App Configuration, Blob Storage, and more
• No Hardcoded Credentials - All config from Azure App Configuration or .env files

🔒 Security & Enterprise Features

• Security First - Tenant isolation, OIDC auth, audit logging built-in
• Batteries Included - Database, auth, logging, middleware, and more
• Multi-Environment - Dev, UAT, Prod configuration support

📦 Installation

Modular Installation (v1.0.18+)

# Core only (minimal dependencies)
pip install jlframework

# With automation support (Azure Functions, background jobs)
pip install jlframework[automation]

# With web support (FastAPI applications)
pip install jlframework[web]

# All features (automation + web)
pip install jlframework[all]

# With dev dependencies
pip install jlframework[dev]

What's Included in Each Installation?

Core (Always Installed):

• CLI tools and project templates
• Configuration management
• Azure integration (App Config, Blob Storage)
• SharePoint and Microsoft Graph
• Audit logging (MongoDB)
• SMS notifications (Twilio)
• Common utilities

Automation Extra ([automation]):

• SQL Manager with connection pooling
• API client with retry logic
• Automation workflow manager
• Data processing utilities (pandas, openpyxl)

Web Extra ([web]):

• FastAPI framework
• SQLAlchemy ORM
• Multi-tenant middleware
• Database session management
• Uvicorn server

🚀 Quick Start

1. Create a Full-Stack Project

# Initialize a new project
jlframework init my-awesome-app
cd my-awesome-app

# Add backend
jlframework add backend

# Add frontend
jlframework add frontend-embedded

# List available templates
jlframework list

2. Use Automation Utilities

New Namespace Imports (Recommended)

# Automation components
from jlframework.automation import (
    AutomationManager,
    SqlManager,
    CommonManager,
    ExecutionResult,
)

# Core utilities (shared)
from jlframework.core import (
    ConfigurationManager,
    SharePointManager,
    BlobStorageManager,
    SMSHandler,
)

# Example: Automation workflow
class MyAutomation(AutomationManager):
    async def start_processing(self, data):
        # Access pre-configured managers
        result = await self.db.execute_query("SELECT * FROM table")
        await self.audit.save_audit(audit_data)
        return result

Legacy Imports (Still Supported)

# Old style imports still work for backward compatibility
from jlframework import (
    SMSHandler,
    SharePointManager,
    SqlManager,
    slack_notification,
    teams_notification,
    BlobStorageManager,
    ExecutionResult,
)

# Send SMS
sms = SMSHandler()
sms.send_sms(to_number="[phone]", message="Hello!")

# Send Email via SharePoint
sp = SharePointManager()
await sp.send_email(
    subject="Test Email",
    body="Hello from jlframework!",
    to_recipients=["[e-mail]"]
)

3. Use Web Utilities

New Namespace Imports (Recommended)

from fastapi import FastAPI, Depends, Request
from sqlalchemy.orm import Session

# Web components
from jlframework.web import (
    restrict_access_middleware,
    database_middleware,
    initialize_database,
    get_db,
    get_tenant_id,
)

# Core utilities
from jlframework.core import ConfigurationManager

app = FastAPI()

# Initialize database
initialize_database("postgresql://user:pass@localhost/db")

# Add middleware
app.middleware("http")(restrict_access_middleware)
app.middleware("http")(database_middleware)

@app.get("/items")
async def get_items(request: Request, db: Session = Depends(get_db)):
    tenant_id = get_tenant_id(request)
    # Query tenant-specific data
    items = db.query(Item).filter(Item.tenant_id == tenant_id).all()
    return items

🔄 Migration Guide (v1.0.17 → v1.0.18)

No Breaking Changes!

All existing code continues to work without modifications. The modular architecture is 100% backward compatible.

Optional: Migrate to New Namespace Imports

For Automation Projects

# Before (still works)
from jlframework import AutomationManager, SqlManager, CommonManager

# After (recommended)
from jlframework.automation import AutomationManager, SqlManager, CommonManager
from jlframework.core import ConfigurationManager, SharePointManager

For Web Projects

# Before (still works)
from jlframework import restrict_access_middleware, get_db, initialize_database

# After (recommended)
from jlframework.web import restrict_access_middleware, get_db, initialize_database
from jlframework.core import ConfigurationManager

Update Installation

# Before
pip install jlframework

# After - Choose what you need
pip install jlframework[automation]  # For automation projects
pip install jlframework[web]         # For web projects
pip install jlframework[all]         # For both

📚 Namespace Organization

jlframework.core (Always Installed)

Shared utilities used by both automation and web applications:

• ConfigurationManager - Unified configuration management
• SharePointManager - SharePoint and Microsoft Graph integration
• GraphQLServiceManager - GraphQL client
• AuditManager - Audit logging to MongoDB
• BlobStorageManager - Azure Blob Storage operations
• SMSHandler - SMS notifications via Twilio
• Notification decorators (slack_notification, teams_notification)
• Common utilities and enums

jlframework.automation (Optional)

Components for Azure Functions and background automation:

• AutomationManager - Base class for automation workflows
• SqlManager - SQL database operations with connection pooling
• MainSubSysApiManager - API client with retry logic
• CommonManager - Common automation utilities
• ExecutionResult, AutomationDetails - Data classes

jlframework.web (Optional)

Components for FastAPI web applications:

• restrict_access_middleware - Multi-tenant access control
• database_middleware - Database session lifecycle
• initialize_database - Database initialization
• get_db, get_db_session - Database session management
• Settings, get_settings - Pydantic settings

💡 Why Modular Architecture?

Reduced Container Sizes

• Automation containers: 3-5% smaller (no FastAPI, SQLAlchemy, uvicorn)
• Web containers: 4-6% smaller (no pandas, pyodbc, aioodbc, openpyxl)

Faster Installations

Install only the dependencies you need for your specific use case.

Better Maintainability

Clear separation between automation and web components makes the codebase easier to understand and maintain.

Flexibility

Mix and match components based on your project requirements.

🎯 Use Cases

Automation Projects (Azure Functions, Background Jobs)

pip install jlframework[automation]

Perfect for:

• Azure Function apps
• Background job processors
• Data ETL pipelines
• Scheduled automation tasks

Web Projects (FastAPI Applications)

pip install jlframework[web]

Perfect for:

• REST APIs
• Multi-tenant SaaS applications
• Microservices
• Admin dashboards

Full-Stack Projects

pip install jlframework[all]

Perfect for:

• Projects using both automation and web components
• Monorepo applications
• Development environments recipient="[e-mail]" )

Query Database with Connection Pooling

sql = SqlManager() df = await sql.get_async("SELECT * FROM users", "users_data")

Automatic Notifications

@slack_notification() async def my_automation(self): # Your automation logic return ExecutionResult( status=ReportStatus.SUCCEEDED, records_processed=100 )

### 3. Use FastAPI Utilities

```python
from fastapi import FastAPI, Request, Depends
from sqlalchemy.orm import Session
from jlframework import (
    get_db,
    CommonManager,
    AuditManager,
    restrict_access_middleware,
)

app = FastAPI()

# Add middleware
app.middleware("http")(restrict_access_middleware)

@app.get("/api/v1/items")
async def get_items(
    request: Request,
    db: Session = Depends(get_db)
):
    # Get tenant ID from request
    tenant_id = CommonManager.get_tenant_id(request)
    
    # Query database
    items = db.query(Item).filter_by(tenant_id=tenant_id).all()
    
    return {"items": items}

🎯 New Automation Modules (v1.0.7)

SMS Handler

Send SMS messages via Twilio with delivery tracking:

from jlframework import SMSHandler

sms = SMSHandler()

# Send single SMS
sms.send_sms(
    to_number="[phone]",
    message="Your verification code is 123456"
)

# Send bulk SMS
sms.send_bulk_sms(
    to_numbers=["[phone]", "+0987654321"],
    message="Bulk notification"
)

# Check delivery status
status = sms.get_message_status(message_sid)

SharePoint Manager

Microsoft Graph API integration for emails and file operations:

from jlframework import SharePointManager, ContentType

sp = SharePointManager()

# Send email with attachments
await sp.send_email(
    subject="Monthly Report",
    body="<h1>Report</h1><p>Please find attached...</p>",
    recipient="[e-mail]",
    attachments=["report.pdf"],
    content_type=ContentType.Html
)

# Upload file to SharePoint/OneDrive
await sp.upload_file_to_drive(
    folder_path="/Shared Documents/Reports",
    file_name="report.pdf",
    file_path="./report.pdf"
)

# Search SharePoint
results = await sp.search_items_in_drive("quarterly report")

SQL Manager

Singleton SQL manager with connection pooling and retry logic:

from jlframework import SqlManager
import pandas as pd

sql = SqlManager()

# Async query (returns DataFrame)
df = await sql.get_async(
    query="SELECT * FROM customers WHERE region = ?",
    header="customers",
    params=("North",)
)

# Sync query
df = sql.get_sync(
    query="SELECT * FROM orders",
    header="orders"
)

# Execute non-query
await sql.execute_async(
    query="UPDATE customers SET status = ? WHERE id = ?",
    params=("active", 123)
)

# Health check
is_healthy = await sql.check_health()

Notification Decorators

Automatic Slack and Teams notifications:

from jlframework import slack_notification, teams_notification, ExecutionResult, ReportStatus

class MyAutomation:
    @slack_notification()
    async def process_data(self):
        # Your automation logic
        records = await self.fetch_data()
        await self.process_records(records)
        
        # Return execution result
        return ExecutionResult(
            status=ReportStatus.SUCCEEDED,
            records_processed=len(records),
            records_failed=0,
            execution_time=120.5
        )
    
    @teams_notification()
    async def generate_report(self):
        # Automatically sends Teams notification on success/failure
        report = await self.create_report()
        return ExecutionResult(
            status=ReportStatus.SUCCEEDED,
            message="Report generated successfully"
        )

Azure Integration

Azure App Configuration and Blob Storage:

from jlframework import AzureAppConfig, BlobStorageManager

# Load configuration from Azure App Configuration
config = AzureAppConfig()
db_connection = config.get_config_value("DatabaseConnectionString")
api_key = config.get_config_value("ApiKey")

# Use Blob Storage
blob = BlobStorageManager()

# Upload file
await blob.upload_file(
    container_name="reports",
    blob_name="monthly-report.pdf",
    data=file_content
)

# Download file
content = await blob.download_file(
    container_name="reports",
    blob_name="monthly-report.pdf"
)

# List blobs
blobs = await blob.list_blobs(container_name="reports")

📚 Available Templates

Backend

FastAPI backend with:

• Domain-driven design structure
• SQLAlchemy ORM with multiple database support
• Tenant-based access control middleware
• Audit logging with MongoDB
• Azure integration (optional)
• Docker support
• Environment-based configuration

Frontend - Embedded

Vue.js 3 embedded application with:

• Vite build system
• TypeScript support
• Vue Router
• OIDC authentication (optional)
• API service layer
• Tailwind CSS
• Docker + Nginx deployment

Frontend - Features

Vue.js 3 micro-frontend features:

• Modular component architecture
• Custom event system
• Shared state management
• Independent deployment

Frontend - Marketplace

Vue.js 3 marketplace application:

• Full marketplace UI
• Product catalog
• User management
• OIDC authentication

🎯 CLI Commands

jlframework init

Initialize a new project with configuration files.

jlframework init my-project
jlframework init my-project --no-git  # Skip git initialization

jlframework add

Add a template to your project.

jlframework add backend
jlframework add frontend-embedded
jlframework add frontend-features
jlframework add frontend-marketplace
jlframework add backend --skip-install  # Skip dependency installation

jlframework list

List all available templates.

jlframework list

📖 Complete Import Reference

Automation Modules

from jlframework import (
    # SMS Integration
    SMSHandler,
    
    # SharePoint & Email
    SharePointManager,
    ContentType,
    GraphMethod,
    
    # SQL Management
    SqlManager,
    
    # Notifications
    slack_notification,
    teams_notification,
    
    # Azure Integration
    AzureAppConfig,
    BlobStorageManager,
    
    # Utilities
    ExecutionResult,
    ReportStatus,
    ReportRequestError,
    ReportStatusError,
    get_iana_timezone,
)

FastAPI Utilities

from jlframework import (
    # Database
    get_db,
    get_db_session,
    database_middleware,
    initialize_database,
    
    # Handlers
    CommonManager,
    AuditManager,
    AuditData,
    
    # Enums
    AuditStatus,
    AuditAction,
    EntityType,
    
    # Middleware
    restrict_access_middleware,
    get_tenant_id,
    
    # Configuration
    Settings,
    get_settings,
    
    # API Client
    MainSubSysApiManager,
    RequestType,
    ApiError,
    retry_with_backoff,
)

🔧 Configuration

Environment Variables

Create a .env file or use Azure App Configuration:

# Azure App Configuration (Recommended)
APP_CONFIGURATION_CONNECTION_STRING=Endpoint=https://...
APPLICATION_ENVIRONMENT=Dev  # or Uat, Prod

# Or use individual environment variables
# Twilio SMS
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_MESSAGING_SERVICE_SID=your_service_sid

# Microsoft Graph (SharePoint/Email)
MICROSOFT_TENANT_ID=your_tenant_id
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret

# SQL Database
SQL_CONNECTION_STRING=mssql+pyodbc://...

# Slack Notifications
SLACK_SUCCESS_WEBHOOK=https://hooks.slack.com/...
SLACK_FAILURE_WEBHOOK=https://hooks.slack.com/...

# Teams Notifications
TEAMS_WEBHOOK=https://outlook.office.com/webhook/...

# Azure Storage
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...

Centralized Configuration Manager (v1.0.13+)

New in v1.0.13: Unified configuration management with ConfigurationManager:

from jlframework.core.config_manager import ConfigurationManager

# Get singleton instance (loads from Azure App Configuration once)
config = ConfigurationManager.get_instance()

# Recommended: Use typed getters with Keys enum
api_url = config.get(config.Keys.MAIN_API_URL)
timeout = config.get_int(config.Keys.TIMEOUT, default=30)
debug = config.get_bool(config.Keys.DEBUG, default=False)

# Backward compatible: Attribute access still works
redis_url = config.Redis
storage = config.StorageConnectionString

Benefits:

• ✅ Single source of truth for all configuration
• ✅ Thread-safe singleton pattern
• ✅ Azure connection string loaded only once
• ✅ Type-safe with ConfigurationKeys enum
• ✅ Backward compatible with old code

See CONFIGURATION_MIGRATION_GUIDE.md for migration details.

Azure App Configuration (Legacy)

Deprecated in v1.0.13, use ConfigurationManager instead:

from jlframework import AzureAppConfig

# Old way (still works but deprecated)
config = AzureAppConfig()
twilio_sid = config.get_config_value("TwilioAccountSid")
db_connection = config.get_config_value("DatabaseConnectionString")

🏗️ Project Structure

After running jlframework init and adding templates:

my-project/
├── .jlframework.json      # Project configuration
├── README.md              # Project documentation
├── .gitignore            # Git ignore patterns
├── .env                  # Environment variables
├── backend/              # FastAPI backend
│   ├── main.py
│   ├── routes.py
│   ├── requirements.txt
│   ├── Dockerfile
│   ├── configs/
│   ├── domains/
│   └── shared/
└── frontend/
    ├── embedded/         # Embedded Vue.js app
    ├── features/         # Micro-frontend features
    └── marketplace/      # Marketplace Vue.js app

🐳 Docker Support

All templates include Dockerfiles for containerization:

# Backend
cd backend
docker build -t my-backend .
docker run -p 8000:8000 my-backend

# Frontend
cd frontend/embedded
docker build -t my-frontend .
docker run -p 80:80 my-frontend

🧪 Development

Running Backend

cd backend
pip install -r requirements.txt
python main.py

Running Frontend

cd frontend/embedded
npm install
npm run dev

📝 Complete Examples

Azure Function App with Automation

import azure.functions as func
from jlframework import (
    AzureAppConfig,
    SqlManager,
    SharePointManager,
    slack_notification,
    ExecutionResult,
    ReportStatus
)

# Load configuration from Azure App Configuration
config = AzureAppConfig()

class DataProcessor:
    def __init__(self):
        self.sql = SqlManager()
        self.sp = SharePointManager()
    
    @slack_notification()
    async def process_daily_report(self):
        # Fetch data from database
        df = await self.sql.get_async(
            "SELECT * FROM orders WHERE date = CAST(GETDATE() AS DATE)",
            "daily_orders"
        )
        
        # Process data
        total_orders = len(df)
        total_revenue = df['amount'].sum()
        
        # Send email report
        await self.sp.send_email(
            subject=f"Daily Report - {total_orders} orders",
            body=f"<h1>Daily Report</h1><p>Total Revenue: ${total_revenue}</p>",
            recipient="[e-mail]"
        )
        
        return ExecutionResult(
            status=ReportStatus.SUCCEEDED,
            records_processed=total_orders,
            message=f"Processed {total_orders} orders"
        )

# Azure Function
async def main(timer: func.TimerRequest) -> None:
    processor = DataProcessor()
    await processor.process_daily_report()

Core Python Application

import asyncio
from jlframework import (
    AzureAppConfig,
    SMSHandler,
    SqlManager,
    ExecutionResult,
    ReportStatus
)

async def send_customer_notifications():
    # Load config
    config = AzureAppConfig()
    
    # Initialize services
    sms = SMSHandler()
    sql = SqlManager()
    
    # Get customers to notify
    customers = await sql.get_async(
        "SELECT phone, name FROM customers WHERE notify = 1",
        "customers"
    )
    
    # Send SMS to each customer
    for _, customer in customers.iterrows():
        sms.send_sms(
            to_number=customer['phone'],
            message=f"Hello {customer['name']}, your order is ready!"
        )
    
    print(f"Sent {len(customers)} notifications")

if __name__ == "__main__":
    asyncio.run(send_customer_notifications())

FastAPI with Full Features

from fastapi import FastAPI, Request, Depends
from sqlalchemy.orm import Session
from jlframework import (
    get_db,
    CommonManager,
    AuditManager,
    AuditData,
    AuditStatus,
    AuditAction,
    EntityType,
    restrict_access_middleware,
    database_middleware,
)

app = FastAPI(title="My API")

# Add middlewares
app.middleware("http")(database_middleware)
app.middleware("http")(restrict_access_middleware)

# Initialize audit manager
audit = AuditManager(
    app_id=1,
    tenant_id="default",
    mongo_connection_string=config.mongo_connection
)

@app.post("/api/v1/customers")
async def create_customer(
    request: Request,
    customer_data: dict,
    db: Session = Depends(get_db)
):
    tenant_id = CommonManager.get_tenant_id(request)
    client_info = CommonManager.get_client_info(request)
    
    # Create customer
    customer = Customer(**customer_data, tenant_id=tenant_id)
    db.add(customer)
    db.commit()
    
    # Log audit
    await audit.save_audit(AuditData(
        status=AuditStatus.SUCCESS,
        action=AuditAction.CREATE,
        entity_type=EntityType.Customer,
        entity_id=customer.id,
        user_id=client_info['user_id'],
        ip_address=client_info['ip_address']
    ))
    
    return {"customer": customer}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

🎯 Use Cases

Perfect For:

• ✅ Azure Function Apps (HTTP, Timer, Queue, Blob triggers)
• ✅ Core Python automation scripts
• ✅ FastAPI web applications
• ✅ Standalone data processing applications
• ✅ Microservices with Azure integration
• ✅ Full-stack web applications
• ✅ Enterprise automation workflows

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Built with FastAPI
• Frontend powered by Vue.js
• CLI built with Click
• SMS via Twilio
• Email/SharePoint via Microsoft Graph
• Azure integration via Azure SDK

📞 Support

• 📧 Email: [e-mail]
• 👨‍💻 Developer: Shamasulhaq
• 🐛 Issues: GitHub Issues
• 📦 PyPI: jlframework

🗺️ Roadmap

• SMS integration (Twilio) ✅ v1.0.7
• SharePoint/Email integration (Microsoft Graph) ✅ v1.0.7
• SQL connection pooling and management ✅ v1.0.7
• Slack and Teams notification decorators ✅ v1.0.7
• Azure App Configuration integration ✅ v1.0.7
• Additional database support (MongoDB, PostgreSQL)
• More frontend templates (React, Angular)
• Code generators for models, routes, services
• Database migration tools
• Testing utilities
• Deployment helpers (Kubernetes, Docker Compose)
• VS Code extension
• Web-based project configurator

🎉 What's New

v1.0.15 - Quality Improvements (Current)

• 🔧 Code Quality - Improved code organization and formatting
• 📝 Documentation - Enhanced docstrings and inline documentation
• ✅ Testing - Expanded test coverage and regression tests
• 🐛 Bug Fixes - Minor bug fixes and improvements
• 📊 Metrics - Improved code maintainability and reduced complexity

v1.0.14 - Configuration Consolidation ⚠️ BREAKING CHANGES

• 🔄 Unified Configuration - All configuration now uses ConfigurationManager
• ❌ Removed Deprecated Classes - appconfig_handler.py and azure_config.py removed
• ✅ Backward Compatible - Attribute access still works for smooth migration
• 📚 Migration Guide - See CONFIGURATION_MIGRATION_GUIDE.md

Migration Required: If you were using AzureAppConfig or Configurations, update to ConfigurationManager:

# Old way (v1.0.13 and earlier) - NO LONGER WORKS
from jlframework import AzureAppConfig
config = AzureAppConfig()
value = config.get_config_value("SomeKey")

# New way (v1.0.14+) - REQUIRED
from jlframework.core.config_manager import ConfigurationManager
config = ConfigurationManager.get_instance()
value = config.get("SomeKey")
# Or use attribute access (backward compatible)
value = config.SomeKey

v1.0.13 - Centralized Configuration

• ✨ ConfigurationManager - Unified configuration management
• 🔒 Thread-Safe Singleton - Single source of truth for all configuration
• 🎯 Type-Safe Access - ConfigurationKeys enum for type safety
• ⚡ Performance - Azure connection string loaded only once

v1.0.7 - Automation Modules

• ✨ SMS Handler - Send SMS via Twilio with delivery tracking
• ✨ SharePoint Manager - Microsoft Graph API for emails and file operations
• ✨ SQL Manager - Connection pooling, async/sync queries, retry logic
• ✨ Notification Decorators - Automatic Slack and Teams notifications
• ✨ Enhanced Azure Integration - Better App Configuration and Blob Storage support
• ✨ ExecutionResult - Standardized automation result tracking
• ✨ No Hardcoded Credentials - All config from Azure or environment variables

---

Made with ❤️ by the JLFramework Team