Installation & Quickstart
Relevant source files
The following files were used as context for generating this wiki page:
The flext-grpc platform is an enterprise-grade gRPC communication framework built on Clean Architecture and Domain-Driven Design (DDD) principles. It provides high-performance gRPC services with a focus on type safety, immutable domain entities, and consistent error handling through the Result (r) pattern.
This guide covers the necessary steps to set up the development environment, install dependencies, and execute basic operations using the FlextGrpc facade. For deeper architectural insights, refer to the Module Organization sections in the project source documentation.
Sources: src/README.md:1-25, README.md:1-10
Prerequisites and Installation
The project requires Python 3.13+ and uses Poetry for dependency management. It is built as part of the FLEXT ecosystem, depending on flext-core and flext-cli.
Environment Setup
To prepare the development environment, execute the following commands in order:
# Install development dependencies
make install-dev
# Set up the environment
make setup
# Verify the installation and configuration
make diagnose
Sources: examples/README.md:144-162, pyproject.toml:44-46
Core Dependencies
The platform integrates several enterprise-standard libraries to handle gRPC communication and configuration validation.
| Dependency | Purpose | Version |
|---|---|---|
grpcio | Core gRPC Python implementation | >=1.80.0 |
protobuf | Message serialization | >=6.33.6 |
pydantic | Configuration validation and settings | >=2.13.3 |
flext-core | Foundation patterns (Result pattern, DI) | latest |
prometheus-client | Observability and metrics | >=0.25.0 |
Sources: pyproject.toml:29-41, src/README.md:158-166
Architecture Overview
The platform follows a strict layered approach to ensure separation of concerns. This structure must be respected when installing or extending the module.
The diagram above illustrates the Clean Architecture dependency flow where external layers depend on inner layers, but never vice versa.
Sources: src/README.md:42-55, src/flext_grpc/README.md:145-155
Quickstart Guide
The fastest way to interact with the platform is through the FlextGrpc facade. This unified interface handles the creation of servers, clients, and services while enforcing domain validation rules.
Basic Entity Creation
The following pattern demonstrates how to initialize a server and validate its business rules.
from flext_grpc import FlextGrpc, FlextGrpcConstants
grpc = FlextGrpc()
# Create a server entity
server_result = grpc.create_server(
host=FlextGrpcConstants.Grpc.NETWORK_DEFAULT_HOST,
port=FlextGrpcConstants.Grpc.NETWORK_DEFAULT_GRPC_PORT,
max_workers=10
)
if server_result.success:
server = server_result.value
# Domain validation is mandatory for business logic enforcement
validation = server.validate_business_rules()
if validation.success:
print(f"Server {server.id} is ready.")
Sources: examples/01_basic_usage.py:27-41, examples/README.md:188-208
Server Lifecycle Flow
Operations return a Result object (r), requiring explicit success/failure handling.
This flow ensures that no server enters a "running" state without passing domain-specific validation gates.
Sources: src/README.md:95-103, examples/01_basic_usage.py:72-85
Validation and Quality Gates
Before committing changes or deploying, several quality gates must be passed to ensure compliance with FLEXT standards.
Quality Commands
The project uses a make contract for consistent validation:
make check: Performs a quick health check of the codebase.make test: Runs the test suite and generates coverage reports.make val: Executes the complete validation pipeline (linting, types, tests).
Sources: README.md:31-33, tests/README.md:214-225
Configuration Management
Settings are managed via FlextGrpcSettings, which uses Pydantic for runtime type checking.
| Parameter | Type | Default | Description |
|---|---|---|---|
host | TGrpcHost | localhost | Network address for the service |
port | TGrpcPort | 50051 | Port (Range 1024-65535) |
max_workers | int | 10 | Thread pool size for handling requests |
timeout | float | 30.0 | Global operation timeout in seconds |
Sources: src/flext_grpc/README.md:73-85, examples/02_advanced_usage.py:53-57
Summary
To begin using flext-grpc, ensure your environment meets the Python 3.13 requirement, install dependencies via the provided make commands, and utilize the FlextGrpc facade for entity management. The system's reliance on the Result pattern and domain validation ensures that all gRPC operations are robust and type-safe from initialization through execution.
Sources: src/README.md:215-225, examples/README.md:235-245