Hyphen Python SDK

The official Python SDK for Hyphen - providing feature toggles, IP geolocation, and link shortening services.

Installation

pip install hyphen

For development:

pip install hyphen[dev]

Quick Start

Environment Variables

You can set API credentials using environment variables:

export HYPHEN_API_KEY="your_api_key"export HYPHEN_PUBLIC_API_KEY="your_public_api_key"export HYPHEN_APPLICATION_ID="your_application_id"export HYPHEN_ORGANIZATION_ID="your_organization_id"

Feature Toggles

Manage feature flags for your application with targeting support.

• Website
• Guides

Basic Usage

fromhyphenimportFeatureToggle, ToggleContexttoggle=FeatureToggle(
application_id='your_application_id',
api_key='your_api_key',
environment='production', # Optional, defaults to HYPHEN_ENVIRONMENT or "production"
)
# Get a boolean toggle with default valueenabled=toggle.get_boolean('my-feature', default=False)
print('Feature enabled:', enabled)

Targeting Context

Use targeting context to evaluate toggles based on user attributes:

fromhyphenimportFeatureToggle, ToggleContext# Set a default context for all evaluationstoggle=FeatureToggle(
application_id='your_application_id',
api_key='your_api_key',
default_context=ToggleContext(
targeting_key='user_123',
user={'id': 'user_123', 'email': 'user@example.com'},
)
)
# Or pass context per requestcontext=ToggleContext(
targeting_key='user_456',
ip_address='192.168.1.1',
custom_attributes={'plan': 'premium', 'beta_tester': True}
)
enabled=toggle.get_boolean('premium-feature', default=False, context=context)

Type-Safe Toggle Methods

fromhyphenimportFeatureToggletoggle=FeatureToggle(
application_id='your_application_id',
api_key='your_api_key',
)
# Boolean togglesenabled=toggle.get_boolean('feature-flag', default=False)
# String togglestheme=toggle.get_string('ui-theme', default='light')
# Numeric togglesmax_items=toggle.get_number('max-items', default=10)
# JSON object togglesconfig=toggle.get_object('feature-config', default={'enabled': False})

Get Multiple Toggles

fromhyphenimportFeatureToggletoggle=FeatureToggle(
application_id='your_application_id',
api_key='your_api_key',
)
toggles=toggle.get_toggles(['feature-a', 'feature-b', 'feature-c'])
print('Toggles:', toggles) # {'feature-a': True, 'feature-b': 42, 'feature-c': 'enabled'}

Error Handling

fromhyphenimportFeatureToggledefhandle_toggle_error(error):
print(f'Toggle evaluation failed: {error}')
toggle=FeatureToggle(
application_id='your_application_id',
api_key='your_api_key',
on_error=handle_toggle_error, # Errors call this instead of raising
)
# Returns default value on error instead of raisingenabled=toggle.get_boolean('my-feature', default=False)

Toggles support multiple data types:

• Boolean: True or False
• Number: 42 (int or float)
• String: "Hello World!"
• JSON: {"id": "Hello World!"}

NetInfo - IP Geolocation

Look up IP address geolocation information.

• Website
• Guides

Get Single IP Information

fromhyphenimportNetInfonet_info=NetInfo(api_key='your_api_key')
ip_info=net_info.get_ip_info('8.8.8.8')
print('IP Info:', ip_info)

Get Multiple IP Information

fromhyphenimportNetInfonet_info=NetInfo(api_key='your_api_key')
ips= ['8.8.8.8', '1.1.1.1']
ip_infos=net_info.get_ip_infos(ips)
print('IP Infos:', ip_infos)

Link - Short Code Service

Create and manage short URLs and QR codes.

• Website
• Guides
• API Reference

Creating a Short Code

fromhyphenimportLinklink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
response=link.create_short_code(
long_url='https://hyphen.ai',
domain='test.h4n.link',
options={
'tags': ['sdk-test', 'unit-test'],
}
)
print('Short Code Response:', response)

Updating a Short Code

fromhyphenimportLinklink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
response=link.update_short_code(
code='code_1234567890',
options={
'title': 'Updated Short Code',
'tags': ['sdk-test', 'unit-test'],
'long_url': 'https://hyphen.ai/updated',
}
)
print('Update Response:', response)

Getting a Short Code

fromhyphenimportLinklink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
response=link.get_short_code('code_1234567890')
print('Short Code:', response)

Getting Short Codes

fromhyphenimportLinklink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
response=link.get_short_codes(
title='My Short Codes',
tags=['sdk-test', 'unit-test']
)
print('Short Codes:', response)

Getting Organization Tags

fromhyphenimportLinklink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
tags=link.get_tags()
print('Tags:', tags)

Get Short Code Stats

fromhyphenimportLinkfromdatetimeimportdatetimelink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
stats=link.get_short_code_stats(
code='code_1234567890',
start_date=datetime(2023, 1, 1),
end_date=datetime(2023, 12, 31)
)
print('Stats:', stats)

Deleting a Short Code

fromhyphenimportLinklink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
response=link.delete_short_code('code_1234567890')
print('Delete Response:', response)

Creating a QR Code

fromhyphenimportLink, QrSizelink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
response=link.create_qr_code(
code='code_1234567890',
options={
'title': 'My QR Code',
'backgroundColor': '#ffffff',
'color': '#000000',
'size': QrSize.MEDIUM,
}
)
print('QR Code:', response)

Get QR Code by ID

fromhyphenimportLinklink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
response=link.get_qr_code('code_1234567890', 'qr_1234567890')
print('QR Code:', response)

Get QR Codes for a Short Code

fromhyphenimportLinklink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
response=link.get_qr_codes('code_1234567890')
print('QR Codes:', response)

Deleting a QR Code

fromhyphenimportLinklink=Link(
organization_id='your_organization_id',
api_key='your_api_key',
)
response=link.delete_qr_code('code_1234567890', 'qr_1234567890')
print('Delete Response:', response)

Development

Setup

# Clone the repository
git clone https://github.com/Hyphen/python-sdk.git
cd python-sdk
# Install dependencies
pip install -e ".[dev]"

Testing

Create a .env file with your test credentials:

HYPHEN_PUBLIC_API_KEY=your_public_api_key
HYPHEN_API_KEY=your_api_key
HYPHEN_APPLICATION_ID=your_application_id
HYPHEN_LINK_DOMAIN=your_link_domain
HYPHEN_ORGANIZATION_ID=your_organization_id

Run tests:

pytest

Linting

ruff check hyphen tests

Type Checking

mypy hyphen

Releasing

Releases are published to PyPI automatically when a GitHub Release is created.

To release a new version:

1. Update the version in pyproject.toml and hyphen/__init__.py
2. Commit the version change: git commit -am "chore: bump version to X.Y.Z"
3. Push to main: git push origin main
4. Create a new GitHub Release:
   • Tag: vX.Y.Z (e.g., v0.1.0)
   • Title: vX.Y.Z
   • Description: Release notes
5. The release workflow will automatically run tests and publish to PyPI

Note: Publishing uses PyPI's trusted publisher (OIDC) - no API token needed.

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Make your changes and commit them with clear messages:
   • feat: describe the feature
   • fix: describe the bug fix
   • chore: describe maintenance task
4. Run tests and linting to ensure quality
5. Push your changes to your forked repository
6. Create a pull request to the main repository

License

This project is licensed under the MIT License. See the LICENSE file for details.

Copyright © 2025 Hyphen, Inc. All rights reserved.