=============== LIBRARY RULES =============== From library maintainers: - Install with pip install social-links but import from sociallinks (for example: from sociallinks import detect_platform, sanitize). - detect_platform() returns None for a bare username; pass the platform name to is_valid() or sanitize() to check a bare ID. - sanitize() and extract_id() raise URLMismatchError when the URL does not match the named platform. - Use the SocialLinks class for custom platforms; set_platform() raises PlatformAlreadyExistsError unless override=True. ### Install social-links with uv Source: https://github.com/ysskrishna/social-links/blob/main/README.md Install the social-links package using uv. ```bash uv pip install social-links ``` -------------------------------- ### List Platforms with list_platforms Source: https://github.com/ysskrishna/social-links/blob/main/README.md Returns a list of all available platform names. The example prints the count, which is 65+. ```python from sociallinks import list_platforms # Get all available platforms platforms = list_platforms() # Returns: ["behance", "dev_to", "dribbble", "github", "linkedin", ...] print(f"Supported platforms: {len(platforms)}") # 65+ ``` -------------------------------- ### Install social-links with pip Source: https://github.com/ysskrishna/social-links/blob/main/README.md Install the social-links package using pip. ```bash pip install social-links ``` -------------------------------- ### Quick Start: Using social-links functions Source: https://github.com/ysskrishna/social-links/blob/main/README.md Demonstrates the core functions: detect_platform, is_valid, sanitize, extract_id, and list_platforms. Shows expected outputs for a LinkedIn URL. ```python from sociallinks import detect_platform, sanitize, extract_id, is_valid, list_platforms # Detect platform from URL platform = detect_platform("https://www.linkedin.com/in/ysskrishna/") print(platform) # "linkedin" # Validate URL for a specific platform is_valid_url = is_valid("linkedin", "https://www.linkedin.com/in/ysskrishna/") print(is_valid_url) # True # Sanitize URL to canonical format sanitized = sanitize("linkedin", "https://www.linkedin.com/in/ysskrishna/") print(sanitized) # "https://linkedin.com/in/ysskrishna" # Extract username/ID from URL user_id = extract_id("linkedin", "https://www.linkedin.com/in/ysskrishna/") print(user_id) # "ysskrishna" # List all supported platforms platforms = list_platforms() print(f"Supported platforms: {len(platforms)}") # Supported platforms: 65+ ``` -------------------------------- ### detect_platform example Source: https://github.com/ysskrishna/social-links/blob/main/API.md Demonstrates platform detection for various URLs, including whitespace handling and returning None for bare usernames or unknown platforms. ```python from sociallinks import SocialLinks 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") # None (Username only, no URL) sl.detect_platform("https://example.com") # None (Unknown platform) sl.detect_platform(" https://instagram.com/user ") # 'instagram' (Whitespace handled) ``` -------------------------------- ### Build a custom platform manager Source: https://github.com/ysskrishna/social-links/blob/main/README.md Complete example showing how to add a custom platform to SocialLinks, including pattern definitions, sanitization, detection, and ID extraction. Demonstrates the set_platform, detect_platform, sanitize, extract_id, is_valid, and list_platforms methods. ```python from sociallinks import is_valid from sociallinks import SocialLinks # Start with predefined platforms sl = SocialLinks() # Add a custom platform my_platform = [{ "patterns": [ r"https?://(www\.)?mysite\.com/profile/(?P[A-Za-z0-9_]+)/?$", r"https?://(www\.)?mysite\.com/u/(?P[A-Za-z0-9_]+)/?$" ], "sanitized": "https://mysite.com/profile/{id}" }] sl.set_platform("mysite", my_platform) # Use it url = "https://www.mysite.com/u/johndoe" platform = sl.detect_platform(url) # "mysite" sanitized = sl.sanitize(platform, url) # "https://mysite.com/profile/johndoe" user_id = sl.extract_id(platform, url) # "johndoe" is_valid = sl.is_valid(platform, url) # True # View all platforms all_platforms = sl.list_platforms() print(f"Total platforms: {len(all_platforms)}") ``` -------------------------------- ### Configuration options for SocialLinks Source: https://github.com/ysskrishna/social-links/blob/main/README.md Configure the SocialLinks instance to start with an empty platform list or set custom regex compilation flags. Use use_predefined_platforms=False for custom platforms only, and regex_flags to control pattern matching behavior. ```python from sociallinks import SocialLinks import re # Start with empty platform list (useful for custom platforms only) sl = SocialLinks(use_predefined_platforms=False) # Configure regex compilation flags sl = SocialLinks(regex_flags=re.IGNORECASE | re.MULTILINE) ``` -------------------------------- ### Multiple dictionaries platform configuration (LinkedIn example) Source: https://github.com/ysskrishna/social-links/blob/main/README.md Define a platform configuration with different URL formats and different sanitization templates, such as LinkedIn personal profiles vs company/school pages. Each dictionary contains patterns and a sanitized template. ```python # Example: LinkedIn supports both personal profiles and company pages platform_config = [ { "patterns": [ r"https?://(www\.)?linkedin\.com/in/(?P[A-Za-z0-9_-]+)/?$", r"https?://linkedin\.com/mwlite/in/(?P[A-Za-z0-9_-]+)/?$" ], "sanitized": "https://linkedin.com/in/{id}" # Personal profiles }, { "patterns": [ r"https?://(www\.)?linkedin\.com/company/(?P[A-Za-z0-9_-]+)/?$", r"https?://(www\.)?linkedin\.com/school/(?P[A-Za-z0-9_-]+)/?$" ], "sanitized": "https://linkedin.com/company/{id}" # Company/school pages } ] ``` -------------------------------- ### List all registered platforms with list_platforms() Source: https://github.com/ysskrishna/social-links/blob/main/API.md Returns a list of platform names. The example checks that 'linkedin' and 'github' are present and that there are more than 50 platforms. ```python from sociallinks import list_platforms from sociallinks import list_platforms platforms = list_platforms() "linkedin" in platforms # True "github" in platforms # True len(platforms) > 50 # True ``` -------------------------------- ### is_valid example Source: https://github.com/ysskrishna/social-links/blob/main/API.md Shows validation of URLs against specific platforms, including bare IDs and handling of unknown platforms. ```python from sociallinks import SocialLinks 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") # True (Bare ID for a named platform) ``` -------------------------------- ### Get platform configuration with get_platform Source: https://github.com/ysskrishna/social-links/blob/main/API.md Retrieves the configuration for a specific platform. Raises PlatformNotFoundError if the platform doesn't exist. ```python from sociallinks import SocialLinks sl = SocialLinks() config = sl.get_platform("github") isinstance(config, list) # True "patterns" in config[0] # True "sanitized" in config[0] # True ``` -------------------------------- ### Handling multiple URL formats with different canonical forms Source: https://github.com/ysskrishna/social-links/blob/main/README.md Registers a platform with multiple pattern sets that normalize to different canonical forms (e.g., personal profiles vs company pages). Each pattern set has its own sanitized template. The example uses a LinkedIn-style platform with separate patterns for profiles and companies. ```python from sociallinks import SocialLinks sl = SocialLinks(use_predefined_platforms=False) # Example: Platform with personal profiles and company pages linkedin_style_platform = [ { "patterns": [ r"https?://(www\.)?example\.com/profile/(?P[A-Za-z0-9_-]+)/?$", r"https?://(www\.)?example\.com/user/(?P[A-Za-z0-9_-]+)/?$" ], "sanitized": "https://example.com/profile/{id}" # Personal profiles }, { "patterns": [ r"https?://(www\.)?example\.com/company/(?P[A-Za-z0-9_-]+)/?$", r"https?://(www\.)?example\.com/org/(?P[A-Za-z0-9_-]+)/?$" ], "sanitized": "https://example.com/company/{id}" # Company pages } ] sl.set_platform("example", linkedin_style_platform) # Personal profile URLs normalize to /profile/ sl.sanitize("example", "https://www.example.com/user/johndoe") # Returns: "https://example.com/profile/johndoe" # Company URLs normalize to /company/ sl.sanitize("example", "https://www.example.com/org/acme-corp") # Returns: "https://example.com/company/acme-corp" ``` -------------------------------- ### SocialLinks class example: detect and sanitize Source: https://github.com/ysskrishna/social-links/blob/main/API.md Shows how to instantiate SocialLinks, detect a platform, sanitize a URL, and set a custom platform when use_predefined_platforms is False. ```python from sociallinks import SocialLinks 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' sl = SocialLinks(use_predefined_platforms=False) custom = [{"patterns": [r"https?://example.com/(?P\w+)"], "sanitized": "https://example.com/{id}"}] sl.set_platform("example", custom) ``` -------------------------------- ### Single dictionary platform configuration Source: https://github.com/ysskrishna/social-links/blob/main/README.md Define a platform configuration with multiple patterns sharing the same sanitization template. Use named groups like (?P...) to capture identifiers, and end patterns with /?$ to match from the start. ```python platform_config = [{ "patterns": [ r"https?://(www\.)?example\.com/(?P[A-Za-z0-9_]+)/?$", r"https?://example\.com/user/(?P[A-Za-z0-9_]+)/?$" ], "sanitized": "https://example.com/{id}" }] ``` -------------------------------- ### detect_platform example Source: https://github.com/ysskrishna/social-links/blob/main/API.md Detects the social media platform from a URL. Returns the platform name (e.g., 'linkedin', 'github', 'x') if detected, otherwise None. Raises TypeError if url is not a string. ```python 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 ``` -------------------------------- ### sanitize() usage example Source: https://github.com/ysskrishna/social-links/blob/main/API.md Sanitizes URLs to canonical format for supported platforms. Raises TypeError, PlatformNotFoundError, URLMismatchError, or PlatformIDExtractionError on invalid input. ```python from sociallinks import sanitize 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' ``` -------------------------------- ### is_valid example Source: https://github.com/ysskrishna/social-links/blob/main/API.md Validates a URL against a specific platform. Returns True if the URL matches the platform's patterns, False otherwise (including if the platform doesn't exist). Raises TypeError if platform_name or url is not a string. ```python 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 ``` -------------------------------- ### extract_id() usage example Source: https://github.com/ysskrishna/social-links/blob/main/API.md Extracts the platform identifier from a URL. Raises TypeError, PlatformNotFoundError, URLMismatchError, or PlatformIDExtractionError on invalid input. ```python from sociallinks import extract_id from sociallinks import extract_id extract_id("linkedin", "https://www.linkedin.com/in/johndoe/") # 'johndoe' extract_id("github", "https://github.com/username") # 'username' extract_id("x", "https://twitter.com/elonmusk") # 'elonmusk' ``` -------------------------------- ### Validate URLs with is_valid Source: https://github.com/ysskrishna/social-links/blob/main/README.md Checks if a URL is valid for a specific platform. Accepts bare usernames as valid. Rejects URLs that do not start with the platform's URL, preventing embedded URLs. ```python from sociallinks import is_valid # Validate against specific platform is_valid("linkedin", "https://www.linkedin.com/in/ysskrishna/") # True is_valid("linkedin", "https://example.com") # False is_valid("github", "https://github.com/ysskrishna") # True # A bare username is valid for the platform you name is_valid("github", "ysskrishna") # True # The URL must start with the platform's URL (no embedded URLs) is_valid("github", "https://evil.com/?r=https://github.com/ysskrishna") # False ``` -------------------------------- ### Viewing platform configurations Source: https://github.com/ysskrishna/social-links/blob/main/README.md Retrieves the configuration for an existing platform using get_platform() and lists all available platforms with list_platforms(). The output shows the patterns and sanitized template for the requested platform. ```python from sociallinks import SocialLinks sl = SocialLinks() # Get configuration for an existing platform github_config = sl.get_platform("github") print(github_config) # See the patterns and sanitized template # List all available platforms platforms = sl.list_platforms() # Returns: ["behance", "dev_to", "dribbble", "github", "linkedin", ...] ``` -------------------------------- ### list_platforms() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Lists all available platform names. ```APIDOC ## list_platforms() ### Description Lists all available platform names. ### Method list_platforms ### Returns - (list) - List of platform names. ### Example ```python from sociallinks import SocialLinks sl = SocialLinks() platforms = sl.list_platforms() # Returns: ["behance", "dev_to", "dribbble", "github", "linkedin", ...] ``` ``` -------------------------------- ### list_platforms() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Lists all available platforms. ```APIDOC ## list_platforms() ### Description Lists all available platforms. ### Method Method ### Parameters None ### Returns A list of platform names. ### Example ```python all_platforms = sl.list_platforms() print(f"Total platforms: {len(all_platforms)}") ``` ``` -------------------------------- ### set_platforms() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Adds multiple platforms at once. Raises an error if any platform already exists and override is not set to True. ```APIDOC ## set_platforms() ### Description Adds multiple platforms at once. Raises an error if any platform already exists and override is not set to True. ### Method set_platforms ### Parameters - `platforms` (dict) - Required - A dictionary mapping platform names to their configurations. - `override` (bool) - Optional - Set to True to override existing platforms. ### Example ```python from sociallinks import SocialLinks sl = SocialLinks() new_platforms = { "platform1": [{ "patterns": [r"https?://example1.com/(?P[A-Za-z0-9_]+)"], "sanitized": "https://example1.com/{id}" }], "platform2": [{ "patterns": [r"https?://example2.com/(?P[A-Za-z0-9_]+)"], "sanitized": "https://example2.com/{id}" }] } sl.set_platforms(new_platforms, override=False) # Raises error if any exist sl.set_platforms(new_platforms, override=True) # Overrides existing platforms ``` ``` -------------------------------- ### SocialLinks() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Initializes the SocialLinks client. Optionally disables predefined platforms to work only with custom ones. ```APIDOC ## SocialLinks() ### Description Initializes the SocialLinks client. Optionally disables predefined platforms to work only with custom ones. ### Method Constructor ### Parameters - `use_predefined_platforms` (bool) - Optional - Set to False to disable predefined platforms. ### Example ```python from sociallinks import SocialLinks sl = SocialLinks(use_predefined_platforms=False) ``` ``` -------------------------------- ### Adding multiple platforms with set_platforms Source: https://github.com/ysskrishna/social-links/blob/main/README.md Adds multiple platforms at once using set_platforms(). With override=False, it raises an error if any platform already exists; with override=True, it overrides existing platforms. ```python from sociallinks import SocialLinks sl = SocialLinks() # Add multiple platforms at once new_platforms = { "platform1": [{ "patterns": [r"https?://example1.com/(?P[A-Za-z0-9_]+)"], "sanitized": "https://example1.com/{id}" }], "platform2": [{ "patterns": [r"https?://example2.com/(?P[A-Za-z0-9_]+)"], "sanitized": "https://example2.com/{id}" }] } sl.set_platforms(new_platforms, override=False) # Raises error if any exist sl.set_platforms(new_platforms, override=True) # Overrides existing platforms ``` -------------------------------- ### SocialLinks() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Initializes a new SocialLinks instance with predefined platforms. ```APIDOC ## SocialLinks() ### Description Initializes a new SocialLinks instance with predefined platforms. ### Method Constructor ### Syntax ```python sl = SocialLinks() ``` ### Parameters None ### Returns A new SocialLinks instance. ### Example ```python from sociallinks import SocialLinks sl = SocialLinks() ``` ``` -------------------------------- ### Modifying existing platforms Source: https://github.com/ysskrishna/social-links/blob/main/README.md Retrieves an existing platform's configuration with get_platform(), then modifies and overrides it using set_platform() with override=True. ```python from sociallinks import SocialLinks sl = SocialLinks() # Get existing configuration github_config = sl.get_platform("github") # Modify and override custom_github = [{ "patterns": [r"https?://github\.com/(?P[A-Za-z0-9_]+)/?$"], "sanitized": "https://github.com/{id}" }] sl.set_platform("github", custom_github, override=True) ``` -------------------------------- ### set_platform(name, patterns) Source: https://github.com/ysskrishna/social-links/blob/main/README.md Adds a custom platform with URL patterns and a sanitized template. ```APIDOC ## set_platform(name, patterns) ### Description Adds a custom platform with URL patterns and a sanitized template. ### Method Method ### Parameters - **name** (str) - Required - The platform name. - **patterns** (list) - Required - A list of dictionaries containing 'patterns' and 'sanitized' keys. ### Returns None ### Example ```python my_platform = [{ "patterns": [ r"https?://(www\.)?mysite\.com/profile/(?P[A-Za-z0-9_]+)/?$", r"https?://(www\.)?mysite\.com/u/(?P[A-Za-z0-9_]+)/?$" ], "sanitized": "https://mysite.com/profile/{id}" }] sl.set_platform("mysite", my_platform) ``` ``` -------------------------------- ### get_platform() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Retrieves the configuration (patterns and sanitized template) for a specified platform. ```APIDOC ## get_platform() ### Description Retrieves the configuration (patterns and sanitized template) for a specified platform. ### Method get_platform ### Parameters - `platform` (string) - Required - The platform name. ### Returns - (list) - The platform configuration. ### Example ```python from sociallinks import SocialLinks sl = SocialLinks() github_config = sl.get_platform("github") print(github_config) # See the patterns and sanitized template ``` ``` -------------------------------- ### list_platforms() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Returns a list of all available platform identifiers supported by the library. ```APIDOC ## list_platforms() ### Description Returns a list of all available platform identifiers supported by the library. ### Method Function ### Signature `list_platforms()` ### Parameters None ### Returns - **list of strings** - A list of all supported platform identifiers (e.g., ["behance", "dev_to", "dribbble", "github", "linkedin", ...]). ### Request Example ```python from sociallinks import list_platforms platforms = list_platforms() # Returns: ["behance", "dev_to", "dribbble", "github", "linkedin", ...] print(f"Supported platforms: {len(platforms)}") # 65+ ``` ``` -------------------------------- ### Adding platforms with set_platform Source: https://github.com/ysskrishna/social-links/blob/main/README.md Adds a new platform with set_platform(), which raises an error if the platform already exists. Use override=True to replace an existing platform, including predefined ones. ```python from sociallinks import SocialLinks sl = SocialLinks() # Add a new platform (raises error if platform already exists) custom_platform = [{ "patterns": [r"https?://example.com/(?P[A-Za-z0-9_]+)"], "sanitized": "https://example.com/{id}" }] sl.set_platform("example", custom_platform) # Override an existing platform (including predefined ones) sl.set_platform("github", custom_platform, override=True) ``` -------------------------------- ### SocialLinks constructor Source: https://github.com/ysskrishna/social-links/blob/main/README.md Creates a SocialLinks instance with optional configuration for custom platforms and regex flags. ```APIDOC ## SocialLinks(use_predefined_platforms=True, regex_flags=0) ### Description Creates a SocialLinks instance with optional configuration for custom platforms and regex flags. ### Method Constructor ### Parameters - **use_predefined_platforms** (boolean) - Optional - If False, starts with an empty platform list. Default is True. - **regex_flags** (int) - Optional - Regex compilation flags (e.g., re.IGNORECASE | re.MULTILINE). Default is 0. ### Example ```python from sociallinks import SocialLinks import re # Start with empty platform list sl = SocialLinks(use_predefined_platforms=False) # Configure regex flags sl = SocialLinks(regex_flags=re.IGNORECASE | re.MULTILINE) ``` ``` -------------------------------- ### Basic custom platform registration Source: https://github.com/ysskrishna/social-links/blob/main/README.md Registers a custom platform with a single URL pattern set using set_platform(). Requires use_predefined_platforms=False to disable built-in platforms. The platform is then used with detect_platform() and sanitize(). ```python from sociallinks import SocialLinks sl = SocialLinks(use_predefined_platforms=False) # Define a custom platform custom_platform = [{ "patterns": [ r"https?://(www\.)?example\.com/(?P[A-Za-z0-9_]+)/?$", r"https?://example\.com/user/(?P[A-Za-z0-9_]+)/?$" ], "sanitized": "https://example.com/{id}" }] # Register the platform sl.set_platform("example", custom_platform) # Use it sl.detect_platform("https://example.com/user123") # "example" sl.sanitize("example", "https://www.example.com/user123/") # "https://example.com/user123" ``` -------------------------------- ### Bulk add platforms with set_platforms Source: https://github.com/ysskrishna/social-links/blob/main/API.md Registers multiple platforms at once. Raises PlatformAlreadyExistsError if any platform exists and override is False; operation is all-or-nothing. ```python from sociallinks import SocialLinks sl = SocialLinks(use_predefined_platforms=False) new_platforms = { "platform1": [{ "patterns": [r"https?://example1.com/(?P\w+)"], "sanitized": "https://example1.com/{id}" }], "platform2": [{ "patterns": [r"https?://example2.com/(?P\w+)"], "sanitized": "https://example2.com/{id}" }] } sl.set_platforms(new_platforms) len(sl.list_platforms()) # 2 ``` -------------------------------- ### Detect Platform from URL Source: https://github.com/ysskrishna/social-links/blob/main/README.md Uses detect_platform() to identify the platform from a URL. Handles various URL formats, whitespace, and tracking parameters. Returns None for unrecognized URLs or bare usernames. ```python from sociallinks import detect_platform # Detect from full URL detect_platform("https://github.com/ysskrishna") # "github" detect_platform("https://x.com/ysskrishna") # "x" detect_platform("https://example.com") # None # Works with various URL formats detect_platform("http://linkedin.com/in/ysskrishna") detect_platform("www.facebook.com/ysskrishna") detect_platform(" https://instagram.com/ysskrishna ") # Handles whitespace # Share links with tracking parameters or fragments are accepted detect_platform("https://www.instagram.com/ysskrishna/?igsh=abc") # "instagram" detect_platform("https://github.com/ysskrishna?tab=repositories") # "github" # A bare username does not identify a platform detect_platform("ysskrishna") # None ``` -------------------------------- ### is_valid(platform, url) Source: https://github.com/ysskrishna/social-links/blob/main/README.md Checks if a URL is valid for a given platform. ```APIDOC ## is_valid(platform, url) ### Description Checks if a URL is valid for a given platform. ### Method Method ### Parameters - **platform** (str) - Required - The platform name. - **url** (str) - Required - The URL to validate. ### Returns True if the URL is valid, False otherwise. ### Example ```python is_valid = sl.is_valid(platform, url) # True ``` ``` -------------------------------- ### Using the SocialLinks class API Source: https://github.com/ysskrishna/social-links/blob/main/README.md Instantiate the SocialLinks class to access the same methods as module-level functions, with additional configuration options. Methods include detect_platform, is_valid, sanitize, extract_id, and list_platforms. ```python from sociallinks import SocialLinks sl = SocialLinks() # Same methods as module functions sl.detect_platform("https://github.com/ysskrishna") # "github" sl.is_valid("linkedin", "https://linkedin.com/in/user") # True sl.sanitize("github", "https://github.com/user") # "https://github.com/user" sl.extract_id("github", "https://github.com/user") # "user" sl.list_platforms() # ["behance", "dev_to", "dribbble", ...] ``` -------------------------------- ### detect_platform() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Detects the platform name from a given URL based on registered patterns. ```APIDOC ## detect_platform() ### Description Detects the platform name from a given URL based on registered patterns. ### Method detect_platform ### Parameters - `url` (string) - Required - The URL to detect the platform from. ### Returns - (string) - The platform name if detected, otherwise None. ### Example ```python from sociallinks import SocialLinks sl = SocialLinks(use_predefined_platforms=False) # After registering a custom platform sl.detect_platform("https://example.com/user123") # "example" ``` ``` -------------------------------- ### detect_platform(url) Source: https://github.com/ysskrishna/social-links/blob/main/README.md Detects the platform from a given URL. ```APIDOC ## detect_platform(url) ### Description Detects the platform from a given URL. ### Method Method ### Parameters - **url** (str) - Required - The URL to detect the platform from. ### Returns The platform name as a string, or None if not found. ### Example ```python url = "https://www.mysite.com/u/johndoe" platform = sl.detect_platform(url) # "mysite" ``` ``` -------------------------------- ### List all platforms with list_platforms Source: https://github.com/ysskrishna/social-links/blob/main/API.md Returns a list of all registered platform names in no particular order. ```python from sociallinks import SocialLinks sl = SocialLinks() platforms = sl.list_platforms() isinstance(platforms, list) # True "linkedin" in platforms # True "github" in platforms # True len(platforms) > 50 # True ``` -------------------------------- ### is_valid(platform, url) Source: https://github.com/ysskrishna/social-links/blob/main/README.md Validates whether a given URL is valid for a specified platform. Returns True if valid, False otherwise. ```APIDOC ## is_valid(platform, url) ### Description Validates whether a given URL is valid for a specified platform. Returns True if valid, False otherwise. ### Method Function ### Signature `is_valid(platform, url)` ### Parameters - **platform** (string) - Required - The platform identifier (e.g., "linkedin", "github"). - **url** (string) - Required - The URL to validate. A bare username is valid for the platform you name. The URL must start with the platform's URL (no embedded URLs). ### Returns - **boolean** - True if the URL is valid for the specified platform, False otherwise. ### Request Example ```python from sociallinks import is_valid is_valid("linkedin", "https://www.linkedin.com/in/ysskrishna/") # True is_valid("linkedin", "https://example.com") # False is_valid("github", "https://github.com/ysskrishna") # True is_valid("github", "ysskrishna") # True is_valid("github", "https://evil.com/?r=https://github.com/ysskrishna") # False ``` ``` -------------------------------- ### detect_platform(url) Source: https://github.com/ysskrishna/social-links/blob/main/README.md Detects the social media platform from a given URL. Returns the platform identifier as a string, or None if no platform is detected. ```APIDOC ## detect_platform(url) ### Description Detects the social media platform from a given URL. Returns the platform identifier as a string, or None if no platform is detected. ### Method Function ### Signature `detect_platform(url)` ### Parameters - **url** (string) - Required - The URL to detect the platform from. Accepts full URLs, various formats (http, https, www), whitespace, and share links with tracking parameters or fragments. ### Returns - **string or None** - The platform identifier (e.g., "github", "x", "instagram") or None if no platform is detected. ### Request Example ```python from sociallinks import detect_platform detect_platform("https://github.com/ysskrishna") # "github" detect_platform("https://x.com/ysskrishna") # "x" detect_platform("https://example.com") # None detect_platform("http://linkedin.com/in/ysskrishna") detect_platform("www.facebook.com/ysskrishna") detect_platform(" https://instagram.com/ysskrishna ") # Handles whitespace detect_platform("https://www.instagram.com/ysskrishna/?igsh=abc") # "instagram" detect_platform("https://github.com/ysskrishna?tab=repositories") # "github" detect_platform("ysskrishna") # None ``` ``` -------------------------------- ### sanitize(platform, url) Source: https://github.com/ysskrishna/social-links/blob/main/README.md Normalizes a URL to its canonical format for the specified platform. Returns the sanitized URL string. ```APIDOC ## sanitize(platform, url) ### Description Normalizes a URL to its canonical format for the specified platform. Returns the sanitized URL string. ### Method Function ### Signature `sanitize(platform, url)` ### Parameters - **platform** (string) - Required - The platform identifier (e.g., "linkedin", "github", "x"). - **url** (string) - Required - The URL to normalize. ### Returns - **string** - The canonical URL for the specified platform. ### Request Example ```python from sociallinks import sanitize sanitize("linkedin", "https://www.linkedin.com/in/ysskrishna/") # Returns: "https://linkedin.com/in/ysskrishna" sanitize("github", "http://www.github.com/ysskrishna") # Returns: "https://github.com/ysskrishna" sanitize("x", "https://twitter.com/ysskrishna") # Returns: "https://x.com/ysskrishna" ``` ``` -------------------------------- ### Add or update platform configuration Source: https://github.com/ysskrishna/social-links/blob/main/API.md Registers a new platform or updates an existing one with override=True. Raises PlatformAlreadyExistsError, InvalidPlatformError, or InvalidPlatformRegexError on invalid configuration. ```python from sociallinks import SocialLinks sl = SocialLinks(use_predefined_platforms=False) custom = [{ "patterns": [ r"https?://(www\.)?example\.com/(?P[A-Za-z0-9_]+)/?$", r"^(?P[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) ``` -------------------------------- ### PlatformAlreadyExistsError Source: https://github.com/ysskrishna/social-links/blob/main/API.md Raised when attempting to create a platform that already exists. This exception is raised when trying to register a platform with a name that is already in use. To replace an existing platform, use the `override=True` parameter with `SocialLinks.set_platform` or `SocialLinks.set_platforms`. ```APIDOC ## PlatformAlreadyExistsError ### Description Exception class (subclass of `PlatformError`). Raised when attempting to create a platform that already exists. This exception is raised when trying to register a platform with a name that is already in use. To replace an existing platform, use the `override=True` parameter with `SocialLinks.set_platform` or `SocialLinks.set_platforms`. ``` -------------------------------- ### SocialLinks.set_platforms(platforms: Dict[str, List[Dict[str, Any]]], *, override: bool = False) -> None Source: https://github.com/ysskrishna/social-links/blob/main/API.md Adds or updates multiple platform configurations in a single bulk operation. If any platform already exists, updates occur only when override=True (default behavior raises an error). ```APIDOC ## SocialLinks.set_platforms(platforms: Dict[str, List[Dict[str, Any]]], *, override: bool = False) -> None ### Description Adds or updates multiple platform configurations in a single bulk operation. 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. ### Method POST ### Endpoint SocialLinks.set_platforms ### Parameters #### Path Parameters - **platforms** (Dict[str, List[Dict[str, Any]]]) - Required - Dictionary mapping platform names to their configurations. Each value should be a `PlatformEntry` (list of dictionaries with "patterns" and "sanitized" keys). - **override** (bool) - Optional - If False (default), raises an error if any platform already exists. If True, replaces existing platform configurations. ### Response #### Success Response (200) - **None** - No return value. #### Error Response - **PlatformAlreadyExistsError** - If any platform already exists and override is False. - **InvalidPlatformError** - If any platform configuration is invalid. - **InvalidPlatformRegexError** - If any regex pattern is invalid. The operation is all-or-nothing: if any entry raises, no platform from this call is registered. ### Request Example ```python from sociallinks import SocialLinks sl = SocialLinks(use_predefined_platforms=False) new_platforms = { "platform1": [{ "patterns": [r"https?://example1.com/(?P\w+)"], "sanitized": "https://example1.com/{id}" }], "platform2": [{ "patterns": [r"https?://example2.com/(?P\w+)"], "sanitized": "https://example2.com/{id}" }] } sl.set_platforms(new_platforms) len(sl.list_platforms()) # 2 ``` ``` -------------------------------- ### sanitize() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Normalizes a URL for a given platform to its canonical form using the sanitized template. ```APIDOC ## sanitize() ### Description Normalizes a URL for a given platform to its canonical form using the sanitized template. ### Method sanitize ### Parameters - `platform` (string) - Required - The platform name. - `url` (string) - Required - The URL to sanitize. ### Returns - (string) - The sanitized URL. ### Example ```python from sociallinks import SocialLinks sl = SocialLinks(use_predefined_platforms=False) # After registering a custom platform sl.sanitize("example", "https://www.example.com/user123/") # "https://example.com/user123" ``` ``` -------------------------------- ### sanitize(platform, url) Source: https://github.com/ysskrishna/social-links/blob/main/README.md Sanitizes a URL for a given platform. ```APIDOC ## sanitize(platform, url) ### Description Sanitizes a URL for a given platform. ### Method Method ### Parameters - **platform** (str) - Required - The platform name. - **url** (str) - Required - The URL to sanitize. ### Returns The sanitized URL as a string. ### Example ```python sanitized = sl.sanitize(platform, url) # "https://mysite.com/profile/johndoe" ``` ``` -------------------------------- ### clear_platforms() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Clears all registered platforms. ```APIDOC ## clear_platforms() ### Description Clears all registered platforms. ### Method clear_platforms ### Example ```python from sociallinks import SocialLinks sl = SocialLinks() sl.clear_platforms() ``` ``` -------------------------------- ### SocialLinks(use_predefined_platforms: bool = True, regex_flags: int = re.IGNORECASE) Source: https://github.com/ysskrishna/social-links/blob/main/API.md Constructor for the SocialLinks class. Initializes the URL sanitizer and validator with optional custom platform support and regex flags. ```APIDOC ## SocialLinks(use_predefined_platforms: bool = True, regex_flags: int = re.IGNORECASE) ### Description Initializes a SocialLinks instance. When use_predefined_platforms is True, loads built-in platform definitions; otherwise starts empty. regex_flags controls pattern compilation. ### Parameters - **use_predefined_platforms** (bool) - Optional - Whether to load built-in platform definitions. Defaults to True. - **regex_flags** (int) - Optional - Regex flags for pattern compilation. Defaults to re.IGNORECASE. ### Example ```python from sociallinks import SocialLinks sl = SocialLinks() sl = SocialLinks(use_predefined_platforms=False) custom = [{"patterns": [r"https?://example.com/(?P\w+)"], "sanitized": "https://example.com/{id}"}] sl.set_platform("example", custom) ``` ``` -------------------------------- ### Removing platforms Source: https://github.com/ysskrishna/social-links/blob/main/README.md Deletes a single platform with delete_platform(), multiple platforms with delete_platforms(), and clears all platforms with clear_platforms(). ```python from sociallinks import SocialLinks sl = SocialLinks() # Delete a single platform sl.delete_platform("custom_platform") # Delete multiple platforms sl.delete_platforms(["platform1", "platform2"]) # Clear all platforms sl.clear_platforms() ``` -------------------------------- ### SocialLinks.get_platform(name: str) -> List[Dict[str, Any]] Source: https://github.com/ysskrishna/social-links/blob/main/API.md Retrieves the configuration for a specific platform. This can be useful for inspection or modification before re-adding with `set_platform()`. ```APIDOC ## SocialLinks.get_platform(name: str) -> List[Dict[str, Any]] ### Description Retrieves the configuration for a specific platform. This can be useful for inspection or modification before re-adding with `set_platform()`. ### Method GET ### Endpoint SocialLinks.get_platform ### Parameters #### Path Parameters - **name** (str) - Required - The name of the platform. ### Response #### Success Response (200) - **List[Dict[str, Any]]** - The platform configuration as a `PlatformEntry` (list of dictionaries with "patterns" and "sanitized" keys). #### Error Response - **PlatformNotFoundError** - If the platform doesn't exist. ### Request Example ```python from sociallinks import SocialLinks sl = SocialLinks() config = sl.get_platform("github") isinstance(config, list) # True "patterns" in config[0] # True "sanitized" in config[0] # True ``` ``` -------------------------------- ### Clear all platforms with clear_platforms Source: https://github.com/ysskrishna/social-links/blob/main/API.md Removes all platform configurations and compiled patterns. After calling, no platforms are available until new ones are added. ```python from sociallinks import SocialLinks sl = SocialLinks() len(sl.list_platforms()) > 0 # True sl.clear_platforms() sl.list_platforms() # [] ``` -------------------------------- ### Sanitize URLs with sanitize Source: https://github.com/ysskrishna/social-links/blob/main/README.md Normalizes URLs to canonical format. Removes www, http, and trailing slashes. Converts Twitter URLs to x.com. ```python from sociallinks import sanitize # Normalize to canonical format sanitize("linkedin", "https://www.linkedin.com/in/ysskrishna/") # Returns: "https://linkedin.com/in/ysskrishna" sanitize("github", "http://www.github.com/ysskrishna") # Returns: "https://github.com/ysskrishna" sanitize("x", "https://twitter.com/ysskrishna") # Returns: "https://x.com/ysskrishna" ``` -------------------------------- ### list_platforms() Source: https://github.com/ysskrishna/social-links/blob/main/API.md Lists all registered platform names. This is a convenience function that uses a default SocialLinks instance with predefined platforms, returning all platforms available for detection, validation, and sanitization. ```APIDOC ## list_platforms() ### Description 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. ### Method list_platforms() ### Returns - A list of platform names (strings) in no particular order. ### Request Example ```python from sociallinks import list_platforms platforms = list_platforms() "linkedin" in platforms # True "github" in platforms # True len(platforms) > 50 # True ``` ``` -------------------------------- ### Bulk delete platforms with delete_platforms Source: https://github.com/ysskrishna/social-links/blob/main/API.md Removes multiple platforms at once. Raises PlatformNotFoundError if any platform doesn't exist, with error message including all missing platforms. ```python from sociallinks import SocialLinks sl = SocialLinks() sl.delete_platforms(["linkedin", "github"]) "linkedin" in sl.list_platforms() # False "github" in sl.list_platforms() # False ``` -------------------------------- ### extract_id(platform, url) Source: https://github.com/ysskrishna/social-links/blob/main/README.md Extracts the username or profile ID from a URL for the specified platform. Returns the extracted ID as a string. ```APIDOC ## extract_id(platform, url) ### Description Extracts the username or profile ID from a URL for the specified platform. Returns the extracted ID as a string. ### Method Function ### Signature `extract_id(platform, url)` ### Parameters - **platform** (string) - Required - The platform identifier (e.g., "linkedin", "github", "x"). - **url** (string) - Required - The URL to extract the ID from. ### Returns - **string** - The extracted username or profile ID. ### Request Example ```python from sociallinks import extract_id extract_id("linkedin", "https://www.linkedin.com/in/ysskrishna/") # "ysskrishna" extract_id("github", "https://github.com/ysskrishna") # "ysskrishna" extract_id("x", "https://twitter.com/ysskrishna") # "ysskrishna" extract_id("linkedin", "https://linkedin.com/company/acme") # "acme" ``` ``` -------------------------------- ### delete_platforms() Source: https://github.com/ysskrishna/social-links/blob/main/README.md Deletes multiple platforms by name. ```APIDOC ## delete_platforms() ### Description Deletes multiple platforms by name. ### Method delete_platforms ### Parameters - `platforms` (list) - Required - List of platform names to delete. ### Example ```python from sociallinks import SocialLinks sl = SocialLinks() sl.delete_platforms(["platform1", "platform2"]) ``` ``` -------------------------------- ### SocialLinks.list_platforms() -> List[str] Source: https://github.com/ysskrishna/social-links/blob/main/API.md Lists all registered platform names. Returns a list of all platform names that are currently registered and available for use. ```APIDOC ## SocialLinks.list_platforms() -> List[str] ### Description Lists all registered platform names. Returns a list of all platform names that are currently registered and available for use. ### Method GET ### Endpoint SocialLinks.list_platforms ### Parameters None ### Response #### Success Response (200) - **List[str]** - A list of platform names (strings) in no particular order. ### Request Example ```python from sociallinks import SocialLinks sl = SocialLinks() platforms = sl.list_platforms() isinstance(platforms, list) # True "linkedin" in platforms # True "github" in platforms # True len(platforms) > 50 # True ``` ```