Skip to main content

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)

Source distribution for userfn 0.1.0
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)

Table of built distributions (wheels) for userfn 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page