tokeocli/tokeo repository overview

⁠tokeo

Unleashing the Power of Python, Cement, Dramatiq, APScheduler, and gRPC for Superior EDA Solutions!

-- Event-Driven Architecture, Backend Automation, Event-Driven Automation --

⁠🚀 Accelerate Your Python Development

In an Event-Driven Architecture (EDA⁠) world, you need a fast and reliable development cycle, even for small projects.

Cement⁠ is a well-known Python⁠ project that enables building fast and well-documented CLI apps with ease.

The Dramatiq⁠ background task processing library, paired with RabbitMQ Message Broker⁠, provides a reliable and solid EDA environment.

An integrated gRPC⁠ service allows external access to available tasks and workflows.

For timed job execution, a background and interactive APScheduler⁠ cron service is included.

Fabric⁠ simplifies running task automation locally and remotely, configurable through YAML files and CLI arguments.

Expose your values and functions via NiceGUI⁠ web-based API and pages.

Kickstart your EDA projects with tokeo and experience a seamless development cycle.

Checkout   Spiral⁠   🍒   It takes you on an interactive journey through Tokeo's capabilities, providing a fully functional environment where you can witness Event-Driven Architecture in real-time.

Cheers
Tom

⁠💪 Why Choose Tokeo?

Tokeo is a robust CLI framework for task automation, message queues, and web interfaces, making it ideal for Python backend projects. Key features include:

• Integrated EDA Stack: Combines Dramatiq, RabbitMQ, and gRPC for efficient task processing and external access, plus APScheduler for scheduled jobs.
• Flexible Task Automation: Use Fabric-based tools (tokeo.ext.automate) to define and run local or remote tasks, with flexible configuration via YAML and CLI overrides.
• Extensible CLI: Built on Cement, Tokeo supports custom commands and plugins, simplifying complex workflows with minimal setup.
• Developer-Friendly Tools: The Makefile provides one-liners for formatting (fmt), linting (lint), testing (test), and packaging (sdist, wheel), speeding up development.
• DiskCache by tokeo.ext.diskcache enhances performance with disk-based caching for frequently accessed data, reducing load times and improving efficiency.
• Manage task execution rates using temper and throttle to prevent overloading with rate-limiting tools, ensuring stable and controlled processing.
• SMTP with Jinja2 Templates: Send emails with precise, individualized content using Jinja2 templates, supporting text, HTML, inline images, and attachments for dynamic communications.
• Simple debugging when using app.inspect. Provides basic debugging tools to inspect application state of vars and objects.
• Web Interface: Create beautiful UIs with the built-in NiceGUI extension to visualize data and interact with your application.

Whether you're building microservices, automating workflows, or prototyping, Tokeo provides the structure and flexibility to get started quickly.

⁠🛠️ Getting Started

⁠Installing Tokeo

# Install directly from Pypi.org
pip install tokeo

# Verify installation
tokeo --help

⁠Creating a New Project

Set up a Tokeo project in minutes:

# Define a dedicated space for your project
cd basepath/for/project

# Generate a new project (interactive prompts)
tokeo generate project your_app

# Or use defaults for quick setup
tokeo generate project your_app --defaults

⁠Use our docker container to create a New Project

Set up a Tokeo project in seconds:

# Define a dedicated space for your project
cd basepath/for/project

# Use docker image to generate a new project (interactive prompts)
docker run -it -v $(pwd)/your_app:/src tokeocli/tokeo generate project /src

⁠Setting Up Your Development Environment

# Enter the dedicated space for your project
cd your_app

# Prepare Python virtual environment
make venv

# Activate the virtual environment
source .venv/bin/activate

# Install development dependencies
make dev

# If using feature gRPC, generate code from proto files
make proto

# Verify your application is working
your_app --help

⁠📊 Exploring Tokeo Features on New Project

⁠Process Background Tasks with Dramatiq (needs a running RabbitMQ)

# Launch Dramatiq workers to process background tasks
your_app dramatiq serve

# Trigger a task (e.g., count-words)
your_app emit count-words --url https://github.com

⁠Expose Services via gRPC

# Start the gRPC server for external task access
your_app grpc serve

# Execute a task using the gRPC client
your_app grpc-client count-words --url https://github.com

⁠Schedule Recurring Tasks

# Run the scheduler with interactive shell
your_app scheduler launch

# Within the scheduler shell, list and manage tasks
Scheduler> list
Scheduler> tasks pause 1 2 3  # Pause task with ID 1, 2, 3
Scheduler> tasks resume 1  # Resume task with ID 1
Scheduler> tasks fire 1  # Resume task with ID 1

⁠Automate Operations

# Run automation tasks locally or remotely
your_app automate run uname --verbose --as-json

⁠Create Web Interfaces

# Start the web interface
your_app nicegui serve

# Access the interface at http://localhost:4123

⁠Use Diskcache

# List content
your_app cache list

# Set value
your_app cache set counter --value 1 --value-type int

# Get value
your_app cache get counter

⁠🧰 Developer Tools

Tokeo includes comprehensive tools to maintain code quality:

# Format your code
make fmt

# Run linting checks
make lint

# Run tests
make test

# Run tests with coverage report
make test cov=1

# Build documentation
make doc

# Check for outdated dependencies
make outdated

⁠🚀 Deployment Options

⁠Package Your Application

# Create source distribution
make sdist

# Create wheel package
make wheel

# Build Docker image
make docker

⁠📚 Project Structure

When you create a new project with Tokeo, you get a clean, modular structure:

• config/ - Configuration files for prod, stage, dev and test environments
• your_app/controllers/ - Command-line interface controllers
• your_app/core/logic - Space for your core application logic
• your_app/core/grpc/ - gRPC service definitions and implementations
• your_app/core/pages/ - Web interface pages and apis
• your_app/core/tasks/ - Implementations of actors, agents, automations, operations, performers etc.
• your_app/core/utils/ - A place to put your overall tools and helper functions
• tests/ - Test suite to ensure reliability

⁠🔮 Next Steps

Tokeo is designed to grow with your project. As you build, consider:

• Customizing the application structure for your specific needs
• Creating new controllers for additional commands
• Adding task processors for background workloads
• Designing web interfaces to visualize data
• Implementing automated deployment pipelines

Checkout the example project at Tokeo Spiral⁠ and explore the Makefile⁠ and extensions⁠ for more tools and customization options. Tokeo's modular design makes it easy to adapt for your backend needs.

tokeo is built with ❤️ by Tom Freudenberg - Empowering Python Applications