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
• Async Client
• Configuration
• API Overview
• Data Models
• Caching
• WebSocket Events
• Error Handling
• Testing
• Contributing
• License

What You Get

• Simple API to connect to Space.
• An asynchronous client for services that run in an event loop.
• 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()

Async Client

Entitlement checks sit on the request path: a service asks Space "may this user do this?" before serving a request. Made synchronously from inside an event loop, that call blocks every other request the process is serving for as long as it takes - including the full timeout, when Space is slow or unreachable.

AsyncSpaceClient is the same client over httpx.AsyncClient. Same modules, same method names, same arguments, same exceptions; the calls are awaited.

from space_client import SpaceClientFactory

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

async with client as space:
	result = await space.features.evaluate("user-123", "serviceA-featureX")
	print(f"Feature enabled: {result.eval}")

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

Two differences, both consequences of running in a loop:

• The WebSocket is not opened by the constructor, because a constructor cannot await. Call await client.connect(), or use the client as an async context manager as above, when you want pricing events. HTTP calls work without it.
• Closing is awaited: await client.close(), or leave the async with.

Everything else - cache lookups and invalidation, request building, error handling - is shared code rather than a second copy, so the two clients cannot drift apart.

The cache providers remain synchronous. An in-memory lookup is not worth an await; a Redis one is a short local round trip, so if you are caching in Redis and want nothing at all blocking the loop, that is worth knowing.

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.).

AsyncSpaceClient

The same modules and the same methods, awaited. is_connected_to_space(), connect(), disconnect() and close() are coroutines; on, remove_listener and remove_all_listeners are not, since they only touch a local registry. Supports async with.

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.
• A request Space refused raises SpaceApiError, carrying the status code, the method and path, and whatever body came back.
• A request that never arrived raises SpaceConnectionError.
• FeatureModule.evaluate(...) returns an object containing error when Space answers successfully with something that is not a usable evaluation.

Both clients raise the same exceptions.

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.