Parameter Validation System

The Saner Python SDK includes a built-in parameter validation engine that verifies request inputs before sending them to the server. This ensures incorrect values are detected immediately and reported with clear, actionable error messages.

Instead of discovering mistakes after an API request fails, developers receive instant feedback directly in their scripts.

This validation layer is one of the key reliability features of the SDK.

Note: Parameter validation behaves identically across all three client classes (SanerClient, PlatformClient, CvemClient); the examples below use flat resource access (client.Organization...) as if client is a PlatformClient scoped to the platform product, since that's the shortest form. On a SanerClient instance, prefix with the namespace instead: client.platform.Organization.... See the "Client Types" guide for the full comparison.

Why Parameter Validation Matters

Client-side validation provides several advantages:

• prevents invalid API calls from reaching the server
• reduces debugging time
• improves automation reliability
• detects integration mistakes early
• produces clear error messages explaining what went wrong
• eliminates unnecessary network requests

Example:

response = client.Organization.get(organization=123)

Error raised:

TypeError: organization must be string

The request never reaches the API server, saving time and avoiding runtime failures.

Discover Parameter Types Directly in Your IDE

The Saner SDK provides rich inline docstrings that allow developers to view parameter requirements directly inside their IDE.

When hovering over a method or its parameters, you can instantly see:

• parameter type requirements
• required vs optional parameters
• allowed enum values
• formatting expectations
• usage notes

Example:

client.Organization.get(organization="ExampleOrg")

Hovering over:

organization

will display its expected type and description inside your editor.

This enables developers to identify correct parameter formats without switching to external documentation.

For more details, see the "IDE Docstring Support" guide.

Mandatory Field Validation

Required parameters are enforced automatically.

If a required parameter is missing or empty, the SDK raises an exception immediately.

Example:

response = client.Organization.remove(name="")

Error:

ValueError: name cannot be empty

This prevents incomplete payloads from being sent to the API server.

Type Validation

Each parameter is validated against its expected type before execution.

Supported validations include:

• string values
• integers
• list[str]
• list[dict]
• dict[str, str]
• structured JSON payloads

Example:

response = client.Organization.get(organization=123)

Error:

TypeError: organization must be string

This ensures the request matches the expected API schema exactly.

Enum Validation (Allowed Values Only)

Parameters restricted to predefined values are validated automatically.

Example validator definition:

forcereboot = Field(optional=True, enum=["TRUE", "FALSE"])

Valid usage:

forcereboot="TRUE"

Invalid usage:

forcereboot="YES"

Error:

ValueError: forcereboot must be one of ['TRUE', 'FALSE']

This prevents unsupported configuration values from reaching the API server.

Format Validation

Structured formats are validated automatically.

Supported formats include:

Example:

email="admin.example.com"

Error:

ValueError: email must be a valid email

Every format rule matches the entire value, not just a leading portion, so a value that looks valid at the start but carries something extra is rejected rather than silently truncated to its valid-looking prefix:

email="[email protected]<newline>Bcc: [email protected]"
email="[email protected], [email protected]"

Both raise ValueError: email must be a valid email. Control characters and embedded whitespace are rejected outright, since a value like the first example is designed to smuggle extra content into a field the server later treats as an email header.

IPv4 validation is similarly strict about ambiguous input:

ip="010.0.0.1"

ValueError: ip must be valid IPv4 address

A leading zero is rejected rather than silently interpreted as decimal: some resolvers read 010 as octal (8), so accepting it would let the same string mean two different addresses depending on what parses it downstream.

This ensures parameters follow correct formatting before transmission.

Length Validation

Parameters with length constraints are validated automatically.

Example validator definition:

username = Field(min_length=5, max_length=50)

Invalid usage:

username="abc"

Error:

ValueError: username must be at least 5 characters

Another example:

username="a" * 100

Error:

ValueError: username must be <= 50 characters

Boolean String Validation

Some API parameters accept boolean values as strings.

Example:

sslverify="yes"

Error:

ValueError: sslverify must be either true or false

Correct usage:

sslverify="true"

Password Strength Validation

Credential parameters enforce strong password rules automatically.

Requirements include:

• minimum 8 characters
• maximum 100 characters
• at least one digit
• at least one uppercase character
• at least one lowercase character
• at least one special character

Example:

password="weakpass"

Error:

ValueError: password must contain a special character

This helps enforce secure integrations by default.

List Validation

List-based parameters are validated element-by-element.

Example:

emails=["[email protected]", 123]

Error:

ValueError: emails[1] must be string

Supported list validation types:

• list[str]
• list[email]
• list[dict]

Combining List Validation with Format and Length Rules

A list[str] parameter can also carry the same format and length rules used for a single string: each rule is then applied to every element of the list, and a failure is reported with its index.

Example validator definition:

groupname = Field(
    required=True,
    list_string=True,
    max_length=50,
    regex=r"^[A-Za-z0-9._\- ]+$",
)

Valid usage:

groupname=["prod-servers", "db.cluster"]

Invalid usage, with one entry exceeding the length limit:

groupname=["prod-servers", "x" * 100]

Error:

ValueError: groupname[1] must be <= 50 characters

Invalid usage, with one entry failing the pattern:

groupname=["../../etc/passwd"]

Error:

ValueError: groupname[0] has invalid format

This applies to any scalar rule (max_length, min_length, regex, email, enum, date, and similar) whenever it is combined with list_string=True.

IPv4 and MAC Address Validation

Network-related parameters are validated for correctness.

Example:

ip="192.168.1.999"

Error:

ValueError: ip must be valid IPv4 address

Example:

mac="invalid-mac"

Error:

ValueError: mac must be valid MAC address

JSON Payload Validation

Structured JSON inputs must be valid dictionaries or lists.

Example:

payload="invalid"

Error:

TypeError: payload must be valid JSON object (dict or list)

Example Validation Flow

When calling any SDK method, validation occurs in the following order:

Step 1 → required field validation
Step 2 → type validation
Step 3 → format validation
Step 4 → enum validation
Step 5 → length validation
Step 6 → request execution

If any validation step fails, execution stops immediately with a clear error message.

Benefits for Developers

The validation system improves integration quality by:

• catching mistakes instantly
• preventing malformed API requests
• reducing debugging cycles
• providing human-readable error messages
• enforcing correct parameter usage
• improving production automation stability

These safeguards make the Saner Python SDK safer and easier to use across both small scripts and enterprise-scale automation workflows.