Space Python Client

Python client library for Space, a pricing-driven self-adaptation platform for SaaS applications.

Table of Contents

• What You Get
• Requirements
• Installation
• Quick Start in 5 Minutes
• Configuration
• API Overview
• Data Models
• Caching
• WebSocket Events
• Error Handling
• Testing
• Contributing
• License

What You Get

• Simple API to connect to Space.
• Contract lifecycle operations.
• Feature evaluation with optional expected consumption.
• Revert operation for optimistic usage updates.
• Pricing token generation.
• Built-in in-memory cache and optional Redis cache.
• WebSocket events for real-time pricing updates.

Requirements

• Python 3.10+

Installation

pip install space-python-client

Optional Redis support:

pip install "space-python-client[redis]"

Quick Start in 5 Minutes

from space_client import SpaceClientFactory

client = SpaceClientFactory.connect(
	"http://localhost:3000",
	"your-api-key",
	10_000,
)

healthy = client.is_connected_to_space()
print(f"Connected: {healthy}")

result = client.features.evaluate("user-123", "serviceA-featureX")
if result.error is not None:
	print(f"Evaluation error: {result.error.message}")
else:
	print(f"Feature enabled: {result.eval}")

pricing_token = client.features.generate_user_pricing_token("user-123")
print(f"Pricing token: {pricing_token}")

client.close()

Configuration

You can connect using either convenience factory arguments or SpaceConnectionOptions.

Option A: simple connection

from space_client import SpaceClientFactory

client = SpaceClientFactory.connect("http://localhost:3000", "your-api-key")

Option B: custom timeout

client = SpaceClientFactory.connect("http://localhost:3000", "your-api-key", 15000)

Option C: full options object

from space_client import SpaceClientFactory
from space_client.types import CacheOptions, SpaceConnectionOptions

options = SpaceConnectionOptions(
	url="http://localhost:3000",
	api_key="your-api-key",
	timeout=15000,
	cache=CacheOptions(enabled=True),
)

client = SpaceClientFactory.connect(options)

SpaceClientFactory.connect(...) validation rules:

• URL is required and must start with http:// or https://.
• API key is required.
• Timeout must be a positive number.

API Overview

SpaceClientFactory

SpaceClient

Main entry point. Exposes modules as public fields:

• contracts
• features
• cache

Core methods:

Java-style aliases are also available (isConnectedToSpace, removeListener, removeAllListeners, etc.).

ContractModule

Java-style aliases are also available (getContract, addContract, etc.).

FeatureModule

Java-style aliases are also available (revertEvaluation, generateUserPricingToken).

Data Models

Main model classes are exported from space_client.types:

• SpaceConnectionOptions
• CacheOptions, CacheType, ExternalCacheConfig, RedisConfig
• Contract, ContractToCreate, Subscription
• FeatureEvaluationResult, EvaluationError
• BillingPeriod, BillingPeriodToCreate, ContractHistoryEntry, UsageLevel, UserContact
• SpaceEvent

Caching

Built-in cache is enabled with:

from space_client.types import CacheOptions, SpaceConnectionOptions

options = SpaceConnectionOptions(
	url="http://localhost:3000",
	api_key="your-api-key",
	cache=CacheOptions(enabled=True),
)

Redis cache example:

from space_client.types import (
	CacheOptions,
	CacheType,
	ExternalCacheConfig,
	RedisConfig,
	SpaceConnectionOptions,
)

options = SpaceConnectionOptions(
	url="http://localhost:3000",
	api_key="your-api-key",
	cache=CacheOptions(
		enabled=True,
		type=CacheType.REDIS,
		external=ExternalCacheConfig(
			redis=RedisConfig(host="localhost", port=6379),
		),
		ttl=300,
	),
)

WebSocket Events

Supported event names:

• synchronized
• pricing_created
• pricing_archived
• pricing_actived
• service_disabled
• error

Example:

def on_pricing_created(details):
	print("Pricing changed:", details)


client.on("pricing_created", on_pricing_created)
client.connect()

Error Handling

• Factory validation raises ValueError for invalid input.
• Runtime HTTP failures are converted to None/False return values where appropriate.
• FeatureModule.evaluate(...) returns an object containing error when request handling fails.

Testing

Run tests locally:

pip install -e .[dev]
pytest

CI executes tests on every pull request for Python 3.10, 3.11, and 3.12.

Contributing

1. Create a branch from main.
2. Add or update tests for every behavior change.
3. Open a pull request.

License

MIT License.