Basic API¶

Convenience functions for common operations using a default SocialLinks instance.

This module provides simple, functional API for common operations like detecting platforms, validating URLs, and sanitizing URLs. These functions use a default SocialLinks instance with predefined platforms.

For advanced usage (custom platforms, regex flags, platform management), use the SocialLinks class directly.

sociallinks.basic ¶

Module-level convenience functions for basic usage.

This module provides simple, functional API for common operations like detecting platforms, validating URLs, and sanitizing URLs. These functions use a default SocialLinks instance with predefined platforms.

For advanced usage (custom platforms, regex flags, platform management), use the SocialLinks class directly.

detect_platform ¶

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

Detect the social media platform from a URL.

This is a convenience function that uses a default SocialLinks instance with predefined platforms. For custom configurations (regex flags, custom platforms), use the SocialLinks class directly.

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:

>>> from sociallinks import detect_platform
>>> detect_platform("https://linkedin.com/in/johndoe")
'linkedin'
>>> detect_platform("https://github.com/username")
'github'
>>> detect_platform("https://example.com")
None

is_valid ¶

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

Validate a URL against a specific platform.

This is a convenience function that uses a default SocialLinks instance with predefined platforms. For custom configurations, use the SocialLinks class directly.

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:

>>> from sociallinks import is_valid
>>> is_valid("linkedin", "https://www.linkedin.com/in/johndoe/")
True
>>> is_valid("linkedin", "https://github.com/username")
False
>>> is_valid("github", "https://github.com/username")
True

sanitize ¶

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

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

This is a convenience function that uses a default SocialLinks instance with predefined platforms. For custom configurations, use the SocialLinks class directly.

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:

>>> from sociallinks import sanitize
>>> sanitize("linkedin", "https://www.linkedin.com/in/johndoe/")
'https://linkedin.com/in/johndoe'
>>> sanitize("github", "http://www.github.com/username")
'https://github.com/username'
>>> sanitize("x", "https://twitter.com/username")
'https://x.com/username'

list_platforms ¶

list_platforms() -> List[str]

List all registered platform names.

This is a convenience function that uses a default SocialLinks instance with predefined platforms. Returns all platforms available for detection, validation, and sanitization.

Returns:

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

Examples:

>>> from sociallinks import list_platforms
>>> platforms = list_platforms()
>>> "linkedin" in platforms
True
>>> "github" in platforms
True
>>> len(platforms) > 50
True