UserFn Python SDK
The official Python SDK for UserFn.
This SDK provides server-side evaluation for UserFn features, allowing you to implement feature flags, user segmentation, and messaging triggers directly in your Python services.
Features
- Identity & Segmentation: Track users and evaluate audience segments based on traits.
- Feature Flags: Deterministic, rule-based feature flags with percentage rollouts.
- Messaging Triggers: Evaluate eligibility for campaigns (Modals, Banners) based on context and user traits.
- Cross-Language Consistency: Uses FNV-1a hashing to ensure consistent flag rollout buckets across Python and TypeScript SDKs.
Installation
pip install userfn
Quick Start
from userfn.client import UserFnClient, UserFnOptions
# 1. Initialize Client
client = UserFnClient(UserFnOptions(
api_key='your-api-key',
# Optional: Pre-load flags for immediate availability
bootstrap_flags={'new-feature': True}
))
# 2. Identify User
# Traits are used for rule evaluation (segments, flags)
client.identify('user-123', {
'email': 'alice@example.com',
'plan': 'pro',
'beta_tester': True
})
# 3. Check Feature Flags
# Returns the variation value (boolean, string, number, or dict)
if client.get_flag('new-feature', default_value=False):
print('Rendering new feature...')
# 4. Check Messaging Triggers
# Check if the user is eligible for any campaigns on this route/event
campaigns = client.trigger('url_match', '/dashboard')
for campaign in campaigns:
print(f"Triggered campaign: {campaign.id} ({campaign.kind})")
print(f"Content: {campaign.content.body}")
Core Concepts
Identity
All evaluations are context-aware. Use client.identify(id, traits) to set the current user context. The traits you provide are matched against Segment and Flag rules.
Feature Flags
Flags are evaluated locally based on the loaded configuration.
- Rules: Target specific users or segments.
- Rollouts: deterministic percentage-based rollouts (e.g., "50% of users").
- Variations: Flags can return complex JSON objects, not just booleans.
Segments
Define reusable audience rules (e.g., "Pro Users", "Internal Staff"). These are referenced by Feature Flags and Messaging Campaigns.
Messaging
The Python SDK evaluates eligibility for messaging campaigns. Unlike the client-side JS SDK, it does not render UI. It ensures that backend triggers (like an API call or a specific route) adhere to frequency caps and targeting rules defined in your campaigns.
Usage Guide
Manual Configuration
If you are running in an environment where you need to inject configuration manually (e.g. testing):
from userfn.types import FlagConfig, FlagVariation, FlagRule
# Define a flag programmatically
my_flag = FlagConfig(
key='beta-access',
enabled=True,
default_value=False,
variations=[
FlagVariation(id='on', value=True),
FlagVariation(id='off', value=False)
],
rules=[
FlagRule(id='r1', rollout_percentage=10, variation_id='on')
]
)
client.set_flags([my_flag])
Development
Running Tests
# Install dependencies
pip install -e ".[dev]"
# Run tests
pytest
License
MIT
Metadata
Release files for userfn 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| userfn-0.1.0.tar.gz | 8.2 kB | Without provenance | Details for userfn-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| userfn-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for userfn-0.1.0-py3-none-any.whl |
Total release size: 17.3 kB
Release files / userfn-0.1.0.tar.gz
| Download URL | userfn-0.1.0.tar.gz |
|---|---|
| Size | 8.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
28654d4606e07f4e5af7033833e955fd1fb932992e249dcef609b825e6cb121c
|
|
BLAKE2b-256 checksum How to use checksums |
361cea55fd5df007aaf3548040712ce515865263f423e7fc8d706fb91372bf5e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / userfn-0.1.0-py3-none-any.whl
| Download URL | userfn-0.1.0-py3-none-any.whl |
|---|---|
| Size | 9.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2249e04a2a9c4aed81065f2f38baf8b86aba76eaac18dbcf9996de90e1d5b144
|
|
BLAKE2b-256 checksum How to use checksums |
77970bae26834534cb44d0e41168204741b5240c0337b356e7fa564c0730066b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for userfn 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.