# Flipt Client Python
[](https://pypi.org/project/flipt-client)
The `flipt-client-python` library contains the Python source code for the Flipt [client-side evaluation](https://www.flipt.io/docs/integration/client) client.
## Installation
```bash
pip install flipt-client
```
## How Does It Work?
The `flipt-client-python` library is a wrapper around the [flipt-engine-ffi](https://github.com/flipt-io/flipt-client-sdks/tree/main/flipt-engine-ffi) library.
All evaluation happens within the SDK, using the shared library built from the [flipt-engine-ffi](https://github.com/flipt-io/flipt-client-sdks/tree/main/flipt-engine-ffi) library.
Because the evaluation happens within the SDK, the SDKs can be used in environments where the Flipt server is not available or reachable after the initial data is fetched.
## Data Fetching
Upon instantiation, the `flipt-client-python` library will fetch the flag state from the Flipt server and store it in memory. This means that the first time you use the SDK, it will make a request to the Flipt server.
### Polling (Default)
By default, the SDK will poll the Flipt server for new flag state at a regular interval. This interval can be configured using the `update_interval` option when constructing a client. The default interval is 120 seconds.
### Streaming (Flipt Cloud/Flipt v2)
[Flipt Cloud](https://flipt.io/cloud) and [Flipt v2](https://docs.flipt.io/v2) users can use the `streaming` fetch method to stream flag state changes from the Flipt server to the SDK.
When in streaming mode, the SDK will connect to the Flipt server and open a persistent connection that will remain open until the client is closed. The SDK will then receive flag state changes in real-time.
### Retries
The SDK will automatically retry fetching (or initiating streaming) flag state if the client is unable to reach the Flipt server temporarily.
The SDK will retry up to 3 times with an exponential backoff interval between retries. The base delay is 1 second and the maximum delay is 30 seconds.
Retriable errors include:
- `429 Too Many Requests`
- `502 Bad Gateway`
- `503 Service Unavailable`
- `504 Gateway Timeout`
- Other potential transient network or DNS errors
## Supported Architectures
This SDK currently supports the following OSes/architectures:
- Linux x86_64
- Linux arm64
- MacOS x86_64
- MacOS arm64
- Windows x86_64
## Migration Notes
### Pre-1.0.0 -> 1.0.0
This section is for users who are migrating from a previous (pre-1.0.0) version of the SDK.
- `FliptEvaluationClient` has been renamed to `FliptClient`.
- The `namespace` argument is now part of `ClientOptions` as `namespace` (and optionally `environment`).
- `update_interval` and `request_timeout` are now `timedelta` objects instead of `int`.
- All response models are now Pydantic models with explicit types and improved docstrings.
- Backwards compatibility with Pydantic v1 is now maintained.
- All errors now inherit from `FliptError` and use specific subclasses like `ValidationError` and `EvaluationError`.
- The client and models now follow Python naming conventions (snake_case for methods and fields).
- The minimum supported Python version is now 3.8.
## Usage
```python
from flipt_client import FliptClient
from flipt_client.models import ClientOptions, ClientTokenAuthentication
client = FliptClient(
opts=ClientOptions(
url="http://localhost:8080",
authentication=ClientTokenAuthentication(client_token="your-token"),
)
)
variant_result = client.evaluate_variant(flag_key="flag1", entity_id="entity", context={"fizz": "buzz"})
print(variant_result)
# Important: always close the client to release resources
client.close()
```
### Constructor Arguments
The `FliptClient` constructor accepts a single `opts` argument:
- `opts`: An instance of the `ClientOptions` class. The structure is:
- `environment`: The environment (Flipt v2) to fetch flag state from. If not provided, the client will default to the `default` environment.
- `namespace`: The namespace to fetch flag state from. If not provided, the client will default to the `default` namespace.
- `url`: The URL of the upstream Flipt instance. Defaults to `http://localhost:8080`.
- `request_timeout`: Timeout for requests. Defaults to no timeout.
- `update_interval`: Interval to fetch new flag state. Defaults to 120s.
- `authentication`: Authentication strategy. See [Authentication](#authentication).
- `reference`: The namespace or reference key. Defaults to `default`.
- `fetch_mode`: Fetch mode (`polling` or `streaming`). Defaults to polling.
- `error_strategy`: Error strategy (`fail` or `fallback`). Defaults to fail.
- `snapshot`: A base64 encoded snapshot of the engine state. Defaults to `None`. See [Snapshotting](#snapshotting).
- `tls_config`: TLS configuration for connecting to Flipt servers with custom certificates. See [TLS Configuration](#tls-configuration).
### Authentication
The `FliptClient` supports:
- No Authentication (default)
- [Client Token Authentication](https://docs.flipt.io/authentication/using-tokens)
- [JWT Authentication](https://docs.flipt.io/authentication/using-jwts)
### TLS Configuration
The `FliptClient` supports TLS configuration for connecting to Flipt servers with custom certificates, self-signed certificates, or mutual TLS authentication.
The `tls_config` option accepts a `TlsConfig` object with the following options:
- `ca_cert_file`: Path to custom CA certificate file (PEM format). Use this to trust self-signed certificates or custom certificate authorities.
- `ca_cert_data`: Raw CA certificate content (PEM format). Alternative to `ca_cert_file` for providing certificate data directly.
- `insecure_skip_verify`: Skip certificate verification (development only). Set to `True` to disable TLS certificate and hostname verification. **Warning: Only use this for development/testing.**
- `insecure_skip_hostname_verify`: Skip hostname verification while maintaining certificate validation (development only). Set to `True` to disable hostname verification but still validate the certificate chain. **Warning: Only use this for development/testing.**
- `client_cert_file`: Client certificate file for mutual TLS (PEM format). Required for mTLS authentication.
- `client_key_file`: Client key file for mutual TLS (PEM format). Required for mTLS authentication.
- `client_cert_data`: Raw client certificate content (PEM format). Alternative to `client_cert_file`.
- `client_key_data`: Raw client key content (PEM format). Alternative to `client_key_file`.
**Note:** Data fields (`*_data`) take precedence over file paths (`*_file`) when both are provided.
#### Examples
**Self-signed certificate with custom CA:**
```python
from flipt_client import FliptClient
from flipt_client.models import ClientOptions, TlsConfig
# Using CA certificate file
tls_config = TlsConfig(
ca_cert_file="/path/to/ca.crt"
)
client = FliptClient(
opts=ClientOptions(
url="https://flipt.example.com:8443",
tls_config=tls_config
)
)
```
**Skip certificate verification (development only):**
```python
tls_config = TlsConfig(
insecure_skip_verify=True
)
client = FliptClient(
opts=ClientOptions(
url="https://localhost:8443",
tls_config=tls_config
)
)
```
**Self-signed certificate with hostname mismatch:**
```python
# For self-signed certificates with hostname mismatch
tls_config = TlsConfig(
ca_cert_file="/path/to/ca.crt",
insecure_skip_hostname_verify=True
)
client = FliptClient(
opts=ClientOptions(
url="https://localhost:8443",
tls_config=tls_config
)
)
```
**Mutual TLS authentication:**
```python
tls_config = TlsConfig(
ca_cert_file="/path/to/ca.crt",
client_cert_file="/path/to/client.crt",
client_key_file="/path/to/client.key"
)
client = FliptClient(
opts=ClientOptions(
url="https://flipt.example.com:8443",
tls_config=tls_config
)
)
```
**Using certificate data instead of files:**
```python
# Read certificate contents
with open("/path/to/ca.crt", "r") as f:
ca_cert_data = f.read()
tls_config = TlsConfig(
ca_cert_data=ca_cert_data
)
client = FliptClient(
opts=ClientOptions(
url="https://flipt.example.com:8443",
tls_config=tls_config
)
)
```
### Error Handling
All errors raised by the client derive from `flipt_client.errors.FliptError`:
- `ValidationError`: Raised for invalid arguments or configuration.
- `EvaluationError`: Raised for evaluation failures (e.g., flag not found).
Example:
```python
from flipt_client.errors import ValidationError, EvaluationError
try:
client.evaluate_variant(flag_key=None, entity_id="entity")
except ValidationError as e:
print(f"Validation error: {e}")
except EvaluationError as e:
print(f"Evaluation error: {e}")
```
### Snapshotting
The client supports snapshotting of flag state as well as seeding the client with a snapshot for evaluation. This is helpful if you want to use the client in an environment where the Flipt server is not guaranteed to be available or reachable on startup.
To get the snapshot for the client, you can use the `get_snapshot` method. This returns a base64 encoded JSON string that represents the flag state for the client.
You can set the snapshot for the client using the `snapshot` option when constructing a client.
**Note:** You most likely will want to also set the `error_strategy` to `fallback` when using snapshots. This will ensure that you wont get an error if the Flipt server is not available or reachable even on the initial fetch.
You also may want to store the snapshot in a local file so that you can use it to seed the client on startup.
> [!IMPORTANT]
> If the Flipt server becomes reachable after the setting the snapshot, the client will replace the snapshot with the new flag state from the Flipt server.
## Contributing
Contributions are welcome! Please feel free to open an issue or submit a Pull Request.
## License
This project is licensed under the [MIT License](LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/flipt-io/flipt-client-sdks",
"name": "flipt-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Flipt Devs",
"author_email": "dev@flipt.io",
"download_url": "https://files.pythonhosted.org/packages/48/3e/7334f2e2c098b92530d729378910d28c8e689191319d91749f993c56ecdd/flipt_client-1.3.0.tar.gz",
"platform": null,
"description": "# Flipt Client Python\n\n[](https://pypi.org/project/flipt-client)\n\nThe `flipt-client-python` library contains the Python source code for the Flipt [client-side evaluation](https://www.flipt.io/docs/integration/client) client.\n\n## Installation\n\n```bash\npip install flipt-client\n```\n\n## How Does It Work?\n\nThe `flipt-client-python` library is a wrapper around the [flipt-engine-ffi](https://github.com/flipt-io/flipt-client-sdks/tree/main/flipt-engine-ffi) library.\n\nAll evaluation happens within the SDK, using the shared library built from the [flipt-engine-ffi](https://github.com/flipt-io/flipt-client-sdks/tree/main/flipt-engine-ffi) library.\n\nBecause the evaluation happens within the SDK, the SDKs can be used in environments where the Flipt server is not available or reachable after the initial data is fetched.\n\n## Data Fetching\n\nUpon instantiation, the `flipt-client-python` library will fetch the flag state from the Flipt server and store it in memory. This means that the first time you use the SDK, it will make a request to the Flipt server.\n\n### Polling (Default)\n\nBy default, the SDK will poll the Flipt server for new flag state at a regular interval. This interval can be configured using the `update_interval` option when constructing a client. The default interval is 120 seconds.\n\n### Streaming (Flipt Cloud/Flipt v2)\n\n[Flipt Cloud](https://flipt.io/cloud) and [Flipt v2](https://docs.flipt.io/v2) users can use the `streaming` fetch method to stream flag state changes from the Flipt server to the SDK.\n\nWhen in streaming mode, the SDK will connect to the Flipt server and open a persistent connection that will remain open until the client is closed. The SDK will then receive flag state changes in real-time.\n\n### Retries\n\nThe SDK will automatically retry fetching (or initiating streaming) flag state if the client is unable to reach the Flipt server temporarily.\n\nThe SDK will retry up to 3 times with an exponential backoff interval between retries. The base delay is 1 second and the maximum delay is 30 seconds.\n\nRetriable errors include:\n\n- `429 Too Many Requests`\n- `502 Bad Gateway`\n- `503 Service Unavailable`\n- `504 Gateway Timeout`\n- Other potential transient network or DNS errors\n\n## Supported Architectures\n\nThis SDK currently supports the following OSes/architectures:\n\n- Linux x86_64\n- Linux arm64\n- MacOS x86_64\n- MacOS arm64\n- Windows x86_64\n\n## Migration Notes\n\n### Pre-1.0.0 -> 1.0.0\n\nThis section is for users who are migrating from a previous (pre-1.0.0) version of the SDK.\n\n- `FliptEvaluationClient` has been renamed to `FliptClient`.\n- The `namespace` argument is now part of `ClientOptions` as `namespace` (and optionally `environment`).\n- `update_interval` and `request_timeout` are now `timedelta` objects instead of `int`.\n- All response models are now Pydantic models with explicit types and improved docstrings.\n- Backwards compatibility with Pydantic v1 is now maintained.\n- All errors now inherit from `FliptError` and use specific subclasses like `ValidationError` and `EvaluationError`.\n- The client and models now follow Python naming conventions (snake_case for methods and fields).\n- The minimum supported Python version is now 3.8.\n\n## Usage\n\n```python\nfrom flipt_client import FliptClient\nfrom flipt_client.models import ClientOptions, ClientTokenAuthentication\n\nclient = FliptClient(\n opts=ClientOptions(\n url=\"http://localhost:8080\",\n authentication=ClientTokenAuthentication(client_token=\"your-token\"),\n )\n)\n\nvariant_result = client.evaluate_variant(flag_key=\"flag1\", entity_id=\"entity\", context={\"fizz\": \"buzz\"})\nprint(variant_result)\n\n# Important: always close the client to release resources\nclient.close()\n```\n\n### Constructor Arguments\n\nThe `FliptClient` constructor accepts a single `opts` argument:\n\n- `opts`: An instance of the `ClientOptions` class. The structure is:\n - `environment`: The environment (Flipt v2) to fetch flag state from. If not provided, the client will default to the `default` environment.\n - `namespace`: The namespace to fetch flag state from. If not provided, the client will default to the `default` namespace.\n - `url`: The URL of the upstream Flipt instance. Defaults to `http://localhost:8080`.\n - `request_timeout`: Timeout for requests. Defaults to no timeout.\n - `update_interval`: Interval to fetch new flag state. Defaults to 120s.\n - `authentication`: Authentication strategy. See [Authentication](#authentication).\n - `reference`: The namespace or reference key. Defaults to `default`.\n - `fetch_mode`: Fetch mode (`polling` or `streaming`). Defaults to polling.\n - `error_strategy`: Error strategy (`fail` or `fallback`). Defaults to fail.\n - `snapshot`: A base64 encoded snapshot of the engine state. Defaults to `None`. See [Snapshotting](#snapshotting).\n - `tls_config`: TLS configuration for connecting to Flipt servers with custom certificates. See [TLS Configuration](#tls-configuration).\n\n### Authentication\n\nThe `FliptClient` supports:\n\n- No Authentication (default)\n- [Client Token Authentication](https://docs.flipt.io/authentication/using-tokens)\n- [JWT Authentication](https://docs.flipt.io/authentication/using-jwts)\n\n### TLS Configuration\n\nThe `FliptClient` supports TLS configuration for connecting to Flipt servers with custom certificates, self-signed certificates, or mutual TLS authentication.\n\nThe `tls_config` option accepts a `TlsConfig` object with the following options:\n\n- `ca_cert_file`: Path to custom CA certificate file (PEM format). Use this to trust self-signed certificates or custom certificate authorities.\n- `ca_cert_data`: Raw CA certificate content (PEM format). Alternative to `ca_cert_file` for providing certificate data directly.\n- `insecure_skip_verify`: Skip certificate verification (development only). Set to `True` to disable TLS certificate and hostname verification. **Warning: Only use this for development/testing.**\n- `insecure_skip_hostname_verify`: Skip hostname verification while maintaining certificate validation (development only). Set to `True` to disable hostname verification but still validate the certificate chain. **Warning: Only use this for development/testing.**\n- `client_cert_file`: Client certificate file for mutual TLS (PEM format). Required for mTLS authentication.\n- `client_key_file`: Client key file for mutual TLS (PEM format). Required for mTLS authentication.\n- `client_cert_data`: Raw client certificate content (PEM format). Alternative to `client_cert_file`.\n- `client_key_data`: Raw client key content (PEM format). Alternative to `client_key_file`.\n\n**Note:** Data fields (`*_data`) take precedence over file paths (`*_file`) when both are provided.\n\n#### Examples\n\n**Self-signed certificate with custom CA:**\n\n```python\nfrom flipt_client import FliptClient\nfrom flipt_client.models import ClientOptions, TlsConfig\n\n# Using CA certificate file\ntls_config = TlsConfig(\n ca_cert_file=\"/path/to/ca.crt\"\n)\n\nclient = FliptClient(\n opts=ClientOptions(\n url=\"https://flipt.example.com:8443\",\n tls_config=tls_config\n )\n)\n```\n\n**Skip certificate verification (development only):**\n\n```python\ntls_config = TlsConfig(\n insecure_skip_verify=True\n)\n\nclient = FliptClient(\n opts=ClientOptions(\n url=\"https://localhost:8443\",\n tls_config=tls_config\n )\n)\n```\n\n**Self-signed certificate with hostname mismatch:**\n\n```python\n# For self-signed certificates with hostname mismatch\ntls_config = TlsConfig(\n ca_cert_file=\"/path/to/ca.crt\",\n insecure_skip_hostname_verify=True\n)\n\nclient = FliptClient(\n opts=ClientOptions(\n url=\"https://localhost:8443\",\n tls_config=tls_config\n )\n)\n```\n\n**Mutual TLS authentication:**\n\n```python\ntls_config = TlsConfig(\n ca_cert_file=\"/path/to/ca.crt\",\n client_cert_file=\"/path/to/client.crt\",\n client_key_file=\"/path/to/client.key\"\n)\n\nclient = FliptClient(\n opts=ClientOptions(\n url=\"https://flipt.example.com:8443\",\n tls_config=tls_config\n )\n)\n```\n\n**Using certificate data instead of files:**\n\n```python\n# Read certificate contents\nwith open(\"/path/to/ca.crt\", \"r\") as f:\n ca_cert_data = f.read()\n\ntls_config = TlsConfig(\n ca_cert_data=ca_cert_data\n)\n\nclient = FliptClient(\n opts=ClientOptions(\n url=\"https://flipt.example.com:8443\",\n tls_config=tls_config\n )\n)\n```\n\n### Error Handling\n\nAll errors raised by the client derive from `flipt_client.errors.FliptError`:\n\n- `ValidationError`: Raised for invalid arguments or configuration.\n- `EvaluationError`: Raised for evaluation failures (e.g., flag not found).\n\nExample:\n\n```python\nfrom flipt_client.errors import ValidationError, EvaluationError\n\ntry:\n client.evaluate_variant(flag_key=None, entity_id=\"entity\")\nexcept ValidationError as e:\n print(f\"Validation error: {e}\")\nexcept EvaluationError as e:\n print(f\"Evaluation error: {e}\")\n```\n\n### Snapshotting\n\nThe client supports snapshotting of flag state as well as seeding the client with a snapshot for evaluation. This is helpful if you want to use the client in an environment where the Flipt server is not guaranteed to be available or reachable on startup.\n\nTo get the snapshot for the client, you can use the `get_snapshot` method. This returns a base64 encoded JSON string that represents the flag state for the client.\n\nYou can set the snapshot for the client using the `snapshot` option when constructing a client.\n\n**Note:** You most likely will want to also set the `error_strategy` to `fallback` when using snapshots. This will ensure that you wont get an error if the Flipt server is not available or reachable even on the initial fetch.\n\nYou also may want to store the snapshot in a local file so that you can use it to seed the client on startup.\n\n> [!IMPORTANT]\n> If the Flipt server becomes reachable after the setting the snapshot, the client will replace the snapshot with the new flag state from the Flipt server.\n\n## Contributing\n\nContributions are welcome! Please feel free to open an issue or submit a Pull Request.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Flipt Client Evaluation SDK",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/flipt-io/flipt-client-sdks",
"Repository": "https://github.com/flipt-io/flipt-client-sdks"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "39dd45dbdf68303a41dfcc5bcee0685b97de08fcf4df192e57be8ca7ad9dffe7",
"md5": "7defa1e970f33217f215181721823ae5",
"sha256": "d6c03513942e6b97b164606e80df478b8f9def7111366fa40ec105a73c11bcef"
},
"downloads": -1,
"filename": "flipt_client-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7defa1e970f33217f215181721823ae5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 23718220,
"upload_time": "2025-07-11T20:53:22",
"upload_time_iso_8601": "2025-07-11T20:53:22.315960Z",
"url": "https://files.pythonhosted.org/packages/39/dd/45dbdf68303a41dfcc5bcee0685b97de08fcf4df192e57be8ca7ad9dffe7/flipt_client-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "483e7334f2e2c098b92530d729378910d28c8e689191319d91749f993c56ecdd",
"md5": "244e28abcfbc25611643d179df4dc042",
"sha256": "d05e250207f4fed9c32f8c6d5d9593f55f018436c570192a441be62f245c4ea3"
},
"downloads": -1,
"filename": "flipt_client-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "244e28abcfbc25611643d179df4dc042",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 23584533,
"upload_time": "2025-07-11T20:53:24",
"upload_time_iso_8601": "2025-07-11T20:53:24.847637Z",
"url": "https://files.pythonhosted.org/packages/48/3e/7334f2e2c098b92530d729378910d28c8e689191319d91749f993c56ecdd/flipt_client-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 20:53:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "flipt-io",
"github_project": "flipt-client-sdks",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flipt-client"
}
JSON
