Core API¶

The main class for advanced usage, custom platforms, and platform management.

The SocialLinks class provides full control over platform configurations, custom regex flags, and bulk platform operations. Use this when you need to customize platform behavior or manage multiple platforms programmatically.

For simple use cases, see the Basic API convenience functions.

sociallinks.core.SocialLinks ¶

SocialLinks(use_predefined_platforms: bool = True, regex_flags: int = re.IGNORECASE)

Social Media URL Sanitizer and Validator.

Python library to validate, sanitize, and detect social media URLs. Support for LinkedIn, Instagram, TikTok, X/Twitter, GitHub, Facebook, YouTube, and 50+ platforms. Features automatic URL normalization and zero dependencies. Easy to use, regex-powered, and customizable.

The class uses regex patterns to match URLs against platform-specific formats and can normalize them to canonical forms. It also supports custom platform definitions for extensibility.

Attributes:

Name	Type	Description
`platforms`	`PlatformEntries`	Dictionary of platform configurations.
`regex_flags`	`int`	Regex flags used for pattern compilation.

Examples:

Basic usage with predefined platforms:

>>> sl = SocialLinks()
>>> sl.detect_platform("https://linkedin.com/in/johndoe")
'linkedin'
>>> sl.sanitize("linkedin", "https://www.linkedin.com/in/johndoe/")
'https://linkedin.com/in/johndoe'

Custom platforms:

>>> sl = SocialLinks(use_predefined_platforms=False)
>>> custom = [{"patterns": [r"https?://example.com/(?P<id>\w+)"],
...            "sanitized": "https://example.com/{id}"}]
>>> sl.set_platform("example", custom)

Initialize the SocialLinks instance.

Parameters:

Name	Type	Description	Default
`use_predefined_platforms`	`bool`	If True, loads 50+ predefined social media platforms (LinkedIn, GitHub, Twitter/X, etc.). If False, starts with an empty platform list. Defaults to True.	`True`
`regex_flags`	`int`	Regex flags to use for pattern compilation. Defaults to `re.IGNORECASE`. Can be combined with other flags like `re.MULTILINE` using bitwise OR (\|).	`IGNORECASE`

Examples:

>>> # Use predefined platforms (default)
>>> sl = SocialLinks()
>>> len(sl.list_platforms()) > 50
True

>>> # Start with empty platform list
>>> sl = SocialLinks(use_predefined_platforms=False)
>>> sl.list_platforms()
[]

>>> # Use custom regex flags
>>> import re
>>> sl = SocialLinks(regex_flags=re.IGNORECASE | re.MULTILINE)

clear_platforms ¶

clear_platforms() -> None

Remove all platform configurations.

Clears both the platform registry and compiled patterns. After calling this method, no platforms will be available until new ones are added.

Examples:

>>> sl = SocialLinks()
>>> len(sl.list_platforms()) > 0
True
>>> sl.clear_platforms()
>>> sl.list_platforms()
[]

delete_platform ¶

delete_platform(name: str) -> None

Delete a platform configuration.

Removes a platform from the registry. The platform will no longer be available for detection, validation, or sanitization.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the platform to delete.	required

Raises:

Type	Description
`PlatformNotFoundError`	If the platform doesn't exist.

Examples:

>>> sl = SocialLinks()
>>> "linkedin" in sl.list_platforms()
True
>>> sl.delete_platform("linkedin")
>>> "linkedin" in sl.list_platforms()
False

delete_platforms ¶

delete_platforms(names: List[str]) -> None

Delete multiple platform configurations at once.

Bulk operation to remove multiple platforms. This is more efficient than calling delete_platform() multiple times.

Parameters:

Name	Type	Description	Default
`names`	`List[str]`	List of platform names to delete.	required

Raises:

Type	Description
`PlatformNotFoundError`	If any of the specified platforms don't exist. The error message includes all missing platforms.

Examples:

>>> sl = SocialLinks()
>>> sl.delete_platforms(["linkedin", "github"])
>>> "linkedin" in sl.list_platforms()
False
>>> "github" in sl.list_platforms()
False

detect_platform ¶

detect_platform(url: str) -> Optional[str]

Detect the social media platform from a URL.

Analyzes the provided URL against all registered platform patterns and returns the first matching platform name. The URL is automatically stripped of leading/trailing whitespace before matching.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL or username to analyze. Can be a full URL (e.g., "https://linkedin.com/in/johndoe") or just a username (e.g., "johndoe"). Whitespace is automatically stripped.	required

Returns:

Type	Description
`Optional[str]`	The platform name (e.g., "linkedin", "github", "x") if detected,
`Optional[str]`	None if no platform matches.

Raises:

Type	Description
`TypeError`	If url is not a string.

Examples:

>>> sl = SocialLinks()
>>> sl.detect_platform("https://linkedin.com/in/johndoe")
'linkedin'
>>> sl.detect_platform("https://github.com/username")
'github'
>>> sl.detect_platform("https://x.com/username")
'x'
>>> sl.detect_platform("johndoe")  # Username only, no URL
None
>>> sl.detect_platform("https://example.com")  # Unknown platform
None
>>> sl.detect_platform("  https://instagram.com/user  ")  # Whitespace handled
'instagram'

get_platform ¶

get_platform(name: str) -> PlatformEntry

Get the configuration for a specific platform.

Retrieves the platform configuration, which can be useful for inspection or modification before re-adding with set_platform().

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the platform.	required

Returns:

Type	Description
`PlatformEntry`	The platform configuration as a `PlatformEntry` (list of
`PlatformEntry`	dictionaries with "patterns" and "sanitized" keys).

Raises:

Type	Description
`PlatformNotFoundError`	If the platform doesn't exist.

Examples:

>>> sl = SocialLinks()
>>> config = sl.get_platform("github")
>>> isinstance(config, list)
True
>>> "patterns" in config[0]
True
>>> "sanitized" in config[0]
True

is_valid ¶

is_valid(platform_name: str, url: str) -> bool

Validate a URL against a specific platform.

Checks if the provided URL matches any of the patterns defined for the specified platform. The URL is automatically stripped of leading/trailing whitespace before validation.

Parameters:

Name	Type	Description	Default
`platform_name`	`str`	The name of the platform to validate against (e.g., "linkedin", "github", "x").	required
`url`	`str`	The URL to validate. Can be a full URL or just a username. Whitespace is automatically stripped.	required

Returns:

Type	Description
`bool`	True if the URL matches the platform's patterns, False otherwise.
`bool`	Also returns False if the platform doesn't exist.

Raises:

Type	Description
`TypeError`	If platform_name or url is not a string.

Examples:

>>> sl = SocialLinks()
>>> sl.is_valid("linkedin", "https://www.linkedin.com/in/johndoe/")
True
>>> sl.is_valid("linkedin", "https://github.com/username")
False
>>> sl.is_valid("github", "https://github.com/username")
True
>>> sl.is_valid("unknown_platform", "https://example.com")
False
>>> sl.is_valid("linkedin", "johndoe")  # Username only
False

list_platforms ¶

list_platforms() -> List[str]

List all registered platform names.

Returns a list of all platform names that are currently registered and available for use.

Returns:

Type	Description
`List[str]`	A list of platform names (strings) in no particular order.

Examples:

>>> sl = SocialLinks()
>>> platforms = sl.list_platforms()
>>> isinstance(platforms, list)
True
>>> "linkedin" in platforms
True
>>> "github" in platforms
True
>>> len(platforms) > 50
True

sanitize ¶

sanitize(platform_name: str, url: str) -> str

Sanitize a URL to its canonical format for a specific platform.

Normalizes a URL to the canonical format defined for the platform. Extracts the platform-specific identifier (username, profile ID, etc.) from the URL and formats it according to the platform's sanitized template. The URL is automatically stripped of leading/trailing whitespace before processing.

Parameters:

Name	Type	Description	Default
`platform_name`	`str`	The name of the platform (e.g., "linkedin", "github", "x").	required
`url`	`str`	The URL to sanitize. Must match one of the platform's patterns. Whitespace is automatically stripped.	required

Returns:

Type	Description
`str`	The sanitized URL in canonical format for the platform.

Raises:

Type	Description
`TypeError`	If platform_name or url is not a string.
`PlatformNotFoundError`	If the platform doesn't exist.
`URLMismatchError`	If the URL doesn't match any of the platform's patterns or if the URL is empty.
`PlatformIDExtractionError`	If the platform identifier cannot be extracted from the URL.

Examples:

>>> sl = SocialLinks()
>>> sl.sanitize("linkedin", "https://www.linkedin.com/in/johndoe/")
'https://linkedin.com/in/johndoe'
>>> sl.sanitize("github", "http://www.github.com/username")
'https://github.com/username'
>>> sl.sanitize("x", "https://twitter.com/username")
'https://x.com/username'
>>> sl.sanitize("linkedin", "https://linkedin.com/in/john-doe-123")
'https://linkedin.com/in/john-doe-123'

set_platform ¶

set_platform(name: str, data: PlatformEntry, *, override: bool = False) -> None

Add or update a platform configuration.

Registers a new platform. If the platform already exists, updates it only when override=True (default behavior raises an error). The platform patterns are compiled immediately and made available for use.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the platform (e.g., "custom_platform").	required
`data`	`PlatformEntry`	Platform configuration as a list of dictionaries. Each dictionary should contain: - "patterns": A regex pattern string or list of patterns that match URLs for this platform. Patterns should use named groups like `(?P<id>...)` to capture identifiers. - "sanitized": A template string for the canonical URL format, using `{id}` as a placeholder for the extracted identifier.	required
`override`	`bool`	If False (default), raises an error if the platform already exists. If True, replaces the existing platform configuration.	`False`

Raises:

Type	Description
`PlatformAlreadyExistsError`	If the platform already exists and override is False.
`InvalidPlatformError`	If the platform configuration is invalid (no valid patterns or templates).
`InvalidPlatformRegexError`	If any regex pattern is invalid.

Examples:

>>> sl = SocialLinks(use_predefined_platforms=False)
>>> custom = [{
...     "patterns": [
...         r"https?://(www\.)?example\.com/(?P<id>[A-Za-z0-9_]+)/?$",
...         r"^(?P<id>[A-Za-z0-9_]+)$"
...     ],
...     "sanitized": "https://example.com/{id}"
... }]
>>> sl.set_platform("example", custom)
>>> sl.detect_platform("https://example.com/user123")
'example'
>>> sl.sanitize("example", "https://example.com/user123")
'https://example.com/user123'

>>> # Update existing platform
>>> sl.set_platform("example", custom, override=True)

set_platforms ¶

set_platforms(platforms: PlatformEntries, *, override: bool = False) -> None

Add or update multiple platform configurations at once.

Bulk operation to register multiple platforms. If any platform already exists, updates occur only when override=True (default behavior raises an error). This is more efficient than calling set_platform() multiple times.

Parameters:

Name	Type	Description	Default
`platforms`	`PlatformEntries`	Dictionary mapping platform names to their configurations. Each value should be a `PlatformEntry` (list of dictionaries with "patterns" and "sanitized" keys).	required
`override`	`bool`	If False (default), raises an error if any platform already exists. If True, replaces existing platform configurations.	`False`

Raises:

Type	Description
`PlatformAlreadyExistsError`	If any platform already exists and override is False.
`InvalidPlatformError`	If any platform configuration is invalid.
`InvalidPlatformRegexError`	If any regex pattern is invalid.

Examples:

>>> sl = SocialLinks(use_predefined_platforms=False)
>>> new_platforms = {
...     "platform1": [{
...         "patterns": [r"https?://example1.com/(?P<id>\w+)"],
...         "sanitized": "https://example1.com/{id}"
...     }],
...     "platform2": [{
...         "patterns": [r"https?://example2.com/(?P<id>\w+)"],
...         "sanitized": "https://example2.com/{id}"
...     }]
... }
>>> sl.set_platforms(new_platforms)
>>> len(sl.list_platforms())
2