Helper Utilities

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_grpc/api.py
• src/flext_grpc/_utilities/grpc.py
• src/flext_grpc/_utilities/__init__.py
• tests/unit/test_utilities.py
• examples/01_basic_usage.py
• src/flext_grpc/README.md

The Helper Utilities in the flext-grpc platform provide a suite of low-level tools designed to simplify gRPC-specific operations, such as address parsing, entity creation, and system information retrieval. These utilities act as a bridge between high-level platform facades and raw gRPC/network operations, ensuring consistency across the codebase while enforcing validation rules for network addresses and port configurations.

Sources: src/flext_grpc/_utilities/grpc.py, src/flext_grpc/README.md:120-125

Network and Address Utilities

The platform includes robust utilities for handling gRPC network targets and addresses. These tools manage the parsing of target strings (e.g., "localhost:50051") into distinct host and port components, as well as the inverse operation of formatting these components into standard address strings.

Address Management Functions

Function	Purpose	Returns
parse_address	Splits a target string into host and port.	tuple[str, int]
format_address	Combines host and port into a single string.	str
validate_host	Validates that a hostname is non-empty.	bool
validate_port	Ensures a port is within valid numeric ranges.	bool

Sources: src/flext_grpc/_utilities/grpc.py, tests/unit/test_utilities.py:16-32

Address Processing Logic

The following diagram illustrates the flow of validating and parsing a gRPC target string using the helper utilities.

The utility ensures that inputs like localhost:50051 are properly decomposed and validated against system constraints before being used to initialize entities.
Sources: src/flext_grpc/_utilities/grpc.py, tests/unit/test_utilities.py:16-32

Entity Factory Utilities

To maintain architectural consistency, the helper utilities provide factory-like methods for creating domain entities. These methods encapsulate the instantiation logic for servers, clients, channels, and streams, ensuring they are correctly populated with initial state and identifiers.

Key Factory Methods

• create_client_entity(target): Creates a FlextGrpcClient entity and its associated channel for a specific network target.
• create_server_entity(host, port): Initializes a FlextGrpcServer with the specified network configuration.
• create_channel_entity(target): Generates a FlextGrpcChannel for tracking the state of a connection to a specific target.
• create_service_entity(name): Defines a new gRPC service entity by name.
• create_stream_entity(method, type): Creates a stream operation entity defining the gRPC pattern (e.g., unary or server_streaming).

Sources: src/flext_grpc/_utilities/grpc.py, tests/unit/test_utilities.py:34-62

Entity Relationship Structure

This class diagram shows the relationships between entities typically generated by the utility factory methods.

State and System Monitoring

The utilities also provide introspection capabilities for the platform, allowing developers to retrieve human-readable names for internal states and access underlying system performance data.

Introspection Methods

• system_info(): Returns a dictionary containing system-level metrics and environment details relevant to gRPC performance, such as CPU or memory statistics.
• channel_state_name(state): Converts internal gRPC channel state representations into descriptive string names (e.g., converting an "idle" state identifier).
• server_state_name(state): Provides string representations for server lifecycle states like "stopped", "starting", or "running".

Sources: src/flext_grpc/_utilities/grpc.py, tests/unit/test_utilities.py:64-78

Implementation Snippets

The following code demonstrates how these utilities are typically invoked within the platform's test suite to verify network logic.

# From tests/unit/test_utilities.py
def test_grpc_parse_address(self) -> None:
    """Test gRPC address parsing utility."""
    parsed = u.Grpc.parse_address("localhost:50051")
    host, port = parsed
    assert host == "localhost"
    assert port == 50051

def test_create_server_entity(self) -> None:
    """Test server entity creation."""
    server = tm.ok(u.Grpc.create_server_entity("localhost", 50051))
    assert server.host == "localhost"
    assert server.port == 50051

Sources: tests/unit/test_utilities.py:16-24, tests/unit/test_utilities.py:41-45

Conclusion

Helper Utilities form the foundational logic for network handling and entity lifecycle initialization in flext-grpc. By centralizing address parsing, validation, and factory logic into the _utilities.grpc module, the platform ensures that all gRPC components operate on verified and consistent network data.

Sources: src/flext_grpc/README.md:120-130, src/flext_grpc/_utilities/grpc.py