API Reference - Utilities

This section documents utility functions and helpers.

Template Engine

Template engine for code scaffolding.

This module provides a template engine for generating code files and project scaffolding using Python’s string.Template.

class socialseed_e2e.utils.template_engine.TemplateEngine(template_dir: Path | str | None = None)[source]

Bases: object

Template engine for code generation and scaffolding.

This class provides methods to load and render templates with variable substitution. Templates are stored as files and can be rendered with custom variables.

template_dir: Directory containing template files

Example

>>> engine = TemplateEngine()
>>> result = engine.render('service_page.py', {
...     'service_name': 'users-api',
...     'class_name': 'UsersApi'
... })

__init__(template_dir: Path | str | None = None)[source]

Initialize the template engine.

Parameters:: template_dir – Directory containing template files. If None, uses the default templates directory.

load_template(template_name: str) → Template[source]

Load a template from file.

Parameters:: template_name – Name of the template file (with or without .template extension)
Returns:: A string.Template instance
Return type:: Template
Raises:: FileNotFoundError – If template file doesn’t exist

render(template_name: str, variables: Dict[str, str] | None = None) → str[source]

Render a template with variable substitution.

Parameters:

template_name – Name of the template file
variables – Dictionary of variables for substitution

Returns:

Rendered template content

Return type:

str

Raises:

FileNotFoundError – If template file doesn’t exist

render_to_file(template_name: str, variables: Dict[str, str] | None, output_path: str | Path, overwrite: bool = False) → Path[source]

Render a template and write to file.

Parameters:

template_name – Name of the template file
variables – Dictionary of variables for substitution
output_path – Path where to write the rendered content
overwrite – If True, overwrite existing file

Returns:

Path to the written file

Return type:

Path

Raises:

FileNotFoundError – If template file doesn’t exist
FileExistsError – If output file exists and overwrite=False

list_templates() → list[source]

List all available templates.

Returns:: List of template file names
Return type:: list

get_template_variables(template_name: str) → list[source]

Extract variable names from a template.

Parameters:: template_name – Name of the template file
Returns:: List of variable names used in the template
Return type:: list

validate_variables(template_name: str, variables: Dict[str, str]) → tuple[source]

Validate that all required variables are provided.

Parameters:

template_name – Name of the template file
variables – Dictionary of variables to validate

Returns:

(missing_vars, extra_vars)

missing_vars: List of variables in template but not in variables dict
extra_vars: List of variables in variables dict but not in template

Return type:

tuple

socialseed_e2e.utils.template_engine.to_class_name(name: str) → str[source]

Convert a service name to a class name.

Converts names like ‘users-api’ or ‘users_api’ to ‘UsersApi’.

Parameters:: name – Service name (e.g., ‘users-api’, ‘users_api’)
Returns:: Class name (e.g., ‘UsersApi’)
Return type:: str

Example

>>> to_class_name('users-api')
'UsersApi'
>>> to_class_name('my_service')
'MyService'

socialseed_e2e.utils.template_engine.to_snake_case(name: str) → str[source]

Convert a service name to snake_case.

Converts names like ‘users-api’ to ‘users_api’.

Parameters:: name – Service name (e.g., ‘users-api’)
Returns:: Snake case name (e.g., ‘users_api’)
Return type:: str

Example

>>> to_snake_case('users-api')
'users_api'
>>> to_snake_case('MyService')
'my_service'

socialseed_e2e.utils.template_engine.to_camel_case(name: str) → str[source]

Convert a service name to camelCase.

Converts names like ‘users-api’ to ‘usersApi’.

Parameters:: name – Service name (e.g., ‘users-api’)
Returns:: Camel case name (e.g., ‘usersApi’)
Return type:: str

Example

>>> to_camel_case('users-api')
'usersApi'
>>> to_camel_case('my_service')
'myService'

String Utilities

Validators

Validation helpers for socialseed-e2e.

This module provides validation functions for common use cases including URL validation, configuration validation, data type validation, and response validation.

exception socialseed_e2e.utils.validators.ValidationError(message: str, field: str | None = None, value: Any = None)[source]

Bases: Exception

Exception raised when validation fails.

message: Explanation of the validation error

field: Name of the field that failed validation (if applicable)

value: The value that failed validation (if applicable)

__init__(message: str, field: str | None = None, value: Any = None)[source]

socialseed_e2e.utils.validators.validate_url(url: str, require_scheme: bool = True, allowed_schemes: List[str] | None = None, field_name: str = 'url') → str[source]

Validate a URL string.

Parameters:

url – The URL to validate
require_scheme – Whether the URL must have a scheme (http/https)
allowed_schemes – List of allowed schemes (default: [‘http’, ‘https’])
field_name – Name of the field for error messages

Returns:

The validated URL string

Raises:

ValidationError – If URL is invalid

Example

>>> validate_url("https://api.example.com")
'https://api.example.com'
>>> validate_url("not-a-url")
ValidationError: Invalid URL format

socialseed_e2e.utils.validators.validate_base_url(base_url: str, field_name: str = 'base_url') → str[source]

Validate a base URL for API services.

Similar to validate_url but specifically for API base URLs, ensuring no trailing slash for consistent endpoint construction.

Parameters:

base_url – The base URL to validate
field_name – Name of the field for error messages

Returns:

The validated base URL (without trailing slash)

Raises:

ValidationError – If base URL is invalid

socialseed_e2e.utils.validators.validate_port(port: int | str, field_name: str = 'port') → int[source]

Validate a port number.

Parameters:

port – Port number to validate
field_name – Name of the field for error messages

Returns:

Validated port number as integer

Raises:

ValidationError – If port is invalid

socialseed_e2e.utils.validators.validate_timeout(timeout: int | str, field_name: str = 'timeout') → int[source]

Validate a timeout value in milliseconds.

Parameters:

timeout – Timeout in milliseconds
field_name – Name of the field for error messages

Returns:

Validated timeout as integer

Raises:

ValidationError – If timeout is invalid

socialseed_e2e.utils.validators.validate_service_name(name: str, field_name: str = 'service_name') → str[source]

Validate a service name.

Service names should be: - Alphanumeric with hyphens and underscores - Start with letter - Between 1 and 50 characters

Parameters:

name – Service name to validate
field_name – Name of the field for error messages

Returns:

Validated service name

Raises:

ValidationError – If name is invalid

socialseed_e2e.utils.validators.validate_string(value: Any, field_name: str = 'value', min_length: int | None = None, max_length: int | None = None, pattern: str | Pattern | None = None, allow_blank: bool = True) → str[source]

Validate a string value.

Parameters:

value – Value to validate
field_name – Name of the field for error messages
min_length – Minimum string length (optional)
max_length – Maximum string length (optional)
pattern – Regex pattern to match (optional)
allow_blank – Whether empty strings are allowed

Returns:

Validated string

Raises:

ValidationError – If value is invalid

socialseed_e2e.utils.validators.validate_integer(value: Any, field_name: str = 'value', min_value: int | None = None, max_value: int | None = None) → int[source]

Validate an integer value.

Parameters:

value – Value to validate
field_name – Name of the field for error messages
min_value – Minimum allowed value (optional)
max_value – Maximum allowed value (optional)

Returns:

Validated integer

Raises:

ValidationError – If value is invalid

socialseed_e2e.utils.validators.validate_email(email: str, field_name: str = 'email') → str[source]

Validate an email address.

Parameters:

email – Email address to validate
field_name – Name of the field for error messages

Returns:

Validated email address

Raises:

ValidationError – If email is invalid

socialseed_e2e.utils.validators.validate_uuid(uuid_str: str, field_name: str = 'uuid') → str[source]

Validate a UUID string.

Parameters:

uuid_str – UUID string to validate
field_name – Name of the field for error messages

Returns:

Validated UUID string

Raises:

ValidationError – If UUID is invalid

socialseed_e2e.utils.validators.validate_status_code(status: int, expected: int | List[int], field_name: str = 'status_code') → int[source]

Validate an HTTP status code.

Parameters:

status – Actual status code
expected – Expected status code(s)
field_name – Name of the field for error messages

Returns:

Validated status code

Raises:

ValidationError – If status doesn’t match expected

socialseed_e2e.utils.validators.validate_json_response(data: Any, required_fields: List[str] | None = None, field_types: Dict[str, type] | None = None, field_name: str = 'response') → Dict[str, Any][source]

Validate a JSON response structure.

Parameters:

data – JSON data to validate
required_fields – List of required field names
field_types – Dictionary of field names to expected types
field_name – Name of the field for error messages

Returns:

Validated data as dictionary

Raises:

ValidationError – If data structure is invalid

socialseed_e2e.utils.validators.validate_pagination_response(data: Dict[str, Any], items_field: str = 'items', total_field: str = 'total', page_field: str = 'page', field_name: str = 'pagination') → Dict[str, Any][source]

Validate a paginated response structure.

Parameters:

data – Response data to validate
items_field – Name of the items field
total_field – Name of the total count field
page_field – Name of the page field
field_name – Name of the field for error messages

Returns:

Validated data

Raises:

ValidationError – If pagination structure is invalid

socialseed_e2e.utils.validators.validate_list(value: Any, field_name: str = 'value', min_length: int | None = None, max_length: int | None = None, item_validator: Callable[[Any], None] | None = None) → List[Any][source]

Validate a list value.

Parameters:

value – Value to validate
field_name – Name of the field for error messages
min_length – Minimum list length (optional)
max_length – Maximum list length (optional)
item_validator – Optional function to validate each item

Returns:

Validated list

Raises:

ValidationError – If value is invalid

socialseed_e2e.utils.validators.validate_dict(value: Any, field_name: str = 'value', required_keys: List[str] | None = None, value_types: Dict[str, type] | None = None) → Dict[str, Any][source]

Validate a dictionary value.

Parameters:

value – Value to validate
field_name – Name of the field for error messages
required_keys – List of required keys
value_types – Dictionary of keys to expected value types

Returns:

Validated dictionary

Raises:

ValidationError – If value is invalid

Headers

Header definitions for API requests.

socialseed_e2e.core.headers.get_combined_headers(custom_headers: Dict[str, str] | None = None) → Dict[str, str][source]: Combine default headers with custom ones.