smpub - Smart Publisher
CLI/API framework based on SmartRoute
Build CLI and API applications with automatic command dispatch using SmartRoute.
What is smpub?
The Problem
When you write a Python library, you typically need to provide multiple interfaces:
Pythonic API - Import and use directly in code
CLI interface - Command-line usage for scripts and users
HTTP/API - Web access, integrations, remote calls
Traditionally, this means writing three different interfaces with lots of boilerplate code.
The Solution
smpub (Smart Publisher) offers an elegant approach:
Write your library once using SmartRoute for method dispatch
Get three interfaces automatically: Python, CLI, and HTTP/API
SmartRoute provides an elegant Pythonic dispatch system using decorators. smpub takes that dispatch system and automatically transforms it into CLI commands and HTTP endpoints.
Key Concept
Pythonic dispatch (SmartRoute) → Automatic CLI + HTTP (smpub)
One codebase, three interfaces:
# 1. Your library (uses SmartRoute for elegant dispatch)
from smartroute import Router, route
class MyService:
api = Router(name='my')
@api
def my_operation(self, param: str):
"""Process a parameter."""
return {"result": param}
# 2. Publishing layer (uses smpub) - just ~20 lines!
from smartpublisher import Publisher
class MyApp(Publisher):
def on_init(self):
self.publish("service", MyService())
Result: Your service is now accessible three ways:
Python API (direct import):
from myapp import MyService
service = MyService()
result = service.my_operation("test")
CLI (automatic):
python myapp.py service operation test
HTTP API (automatic):
# Start server
python myapp.py
# Call API
curl http://localhost:8000/service/operation \
-H "Content-Type: application/json" \
-d '{"param": "test"}'
# OpenAPI/Swagger UI at http://localhost:8000/docs
Why SmartRoute?
SmartRoute provides an elegant Pythonic dispatch system with:
Clean decorator syntax (
@api)Plugin chain for cross-cutting concerns (logging, validation, transactions)
Type-safe method routing
Composable behavior
When you use SmartRoute, your code is already well-structured for dispatch. smpub simply transforms that dispatch into multiple interfaces.
Real-world example: See the Demo Shop - a complete e-commerce application showing SmartRoute plugins for database transactions, validation, and format negotiation. Published in ~20 lines with smpub.
Features
🎯 Publisher Pattern - Register handlers and expose them via CLI/API
🔀 SmartRoute Integration - Instance-scoped routing and dispatch
💻 CLI Generation - Automatic command-line interface
✅ Pydantic Validation - Automatic type validation and conversion
🎨 Interactive Mode - Optional questionary-based parameter prompting
🌐 HTTP/API Mode - FastAPI integration with Swagger UI
📝 Registry System - Local/global app registration
🏗️ Clean API - Simple decorator-based handler definition
Quick Start
Installation
pip install smartpublisher
# With HTTP support
pip install smartpublisher[http]
# Interactive mode uses questionary (install separately)
pip install questionary
Basic Example
from smartpublisher import Publisher, PublishedClass
from smartroute import Router, route
class UserHandler(PublishedClass):
__slots__ = ('users',)
api = Router(name='user')
def __init__(self):
self.users = {}
@api
def user_add(self, name: str, email: str) -> str:
"""Add a new user."""
self.users[name] = email
return f"User {name} added"
@api
def user_list(self) -> list:
"""List all users."""
return list(self.users.keys())
class MainClass(Publisher):
def initialize(self):
self.users = UserHandler()
self.publish('users', self.users, cli=True, openapi=True)
if __name__ == "__main__":
app = MainClass()
app.run() # Auto-detect CLI or HTTP mode
CLI Mode
# Run commands
python myapp.py users add john john@example.com
python myapp.py users list
# Interactive mode
python myapp.py users add --interactive
HTTP Mode
# Start HTTP server
python myapp.py
# Access Swagger UI
open http://localhost:8000/docs
Documentation
Guides
Examples
API Reference
Part of Genro-Libs Family
smpub is part of the Genro-Libs toolkit, a collection of general-purpose Python developer tools.
Related Projects:
smartroute - Instance-scoped routing engine (used by smpub)
gtext - Text transformation tool
License
MIT License - see LICENSE file for details.