Skip to content

API Reference

Auto-generated API documentation from source code.

Module Functions

socials.parse(url)

Parse a single URL into a typed object.

Parameters:

Name Type Description Default
url str

URL to parse.

 required

Returns:

Type Description
SocialsURL | None

Parsed SocialsURL object, or None if not recognized.

Examples:

result = socials.parse("https://github.com/lorey/socials")
result.platform     # "github"
result.entity_type  # "repo"
Source code in socials/__init__.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
def parse(url: str) -> SocialsURL | None:
    """Parse a single URL into a typed object.

    Args:
        url: URL to parse.

    Returns:
        Parsed SocialsURL object, or None if not recognized.

    Examples:
        ```python
        result = socials.parse("https://github.com/lorey/socials")
        result.platform     # "github"
        result.entity_type  # "repo"
        ```

    """
    return _default_extractor.parse(url)

socials.parse_all(urls)

Parse multiple URLs and return an Extraction result.

Parameters:

Name Type Description Default
urls list[str]

List of URLs to parse.

 required

Returns:

Type Description
Extraction

Extraction object with helper methods for grouping/filtering.

Examples:

extraction = socials.parse_all(urls)
extraction.by_platform()  # {"github": [...], "twitter": [...]}
Source code in socials/__init__.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def parse_all(urls: list[str]) -> Extraction:
    """Parse multiple URLs and return an Extraction result.

    Args:
        urls: List of URLs to parse.

    Returns:
        Extraction object with helper methods for grouping/filtering.

    Examples:
        ```python
        extraction = socials.parse_all(urls)
        extraction.by_platform()  # {"github": [...], "twitter": [...]}
        ```

    """
    return _default_extractor.extract(urls)

Classes

socials.Extractor

Extractor for parsing social URLs.

Source code in socials/extractor.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
class Extractor:
    """Extractor for parsing social URLs."""

    def __init__(
        self,
        *,
        platforms: list[str] | None = None,
        strict: bool = False,
    ) -> None:
        """Initialize the extractor.

        Args:
            platforms: If provided, only include these platforms.
            strict: If True, raise ParseError for unrecognized URLs.

        """
        self._strict = strict
        self._registry = Registry()

        if platforms is None:
            platforms = list(DEFAULT_PARSERS.keys())

        for platform in platforms:
            try:
                parser = DEFAULT_PARSERS[platform]
            except KeyError:
                msg = f"Unknown platform: {platform}"
                raise ValueError(msg) from None
            self._registry.register(parser)

    def parse(self, url: str) -> SocialsURL | None:
        """Parse a single URL.

        Args:
            url: URL to parse.

        Returns:
            Parsed SocialsURL object, or None if not recognized.

        Raises:
            ParseError: If strict mode is enabled and URL is not recognized.

        """
        result = self._registry.parse(url)

        if result is None and self._strict:
            msg = f"Unrecognized URL: {url}"
            raise ParseError(msg)

        return result

    def extract(self, urls: list[str]) -> Extraction:
        """Parse multiple URLs.

        Args:
            urls: List of URLs to parse.

        Returns:
            Extraction object containing parsed results.

        """
        results: list[SocialsURL] = []
        for url in urls:
            result = self.parse(url)
            if result is not None:
                results.append(result)
        return Extraction(results)

parse(url)

Parse a single URL.

Parameters:

Name Type Description Default
url str

URL to parse.

 required

Returns:

Type Description
SocialsURL | None

Parsed SocialsURL object, or None if not recognized.

Raises:

Type Description
ParseError

If strict mode is enabled and URL is not recognized.
Source code in socials/extractor.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def parse(self, url: str) -> SocialsURL | None:
    """Parse a single URL.

    Args:
        url: URL to parse.

    Returns:
        Parsed SocialsURL object, or None if not recognized.

    Raises:
        ParseError: If strict mode is enabled and URL is not recognized.

    """
    result = self._registry.parse(url)

    if result is None and self._strict:
        msg = f"Unrecognized URL: {url}"
        raise ParseError(msg)

    return result

extract(urls)

Parse multiple URLs.

Parameters:

Name Type Description Default
urls list[str]

List of URLs to parse.

 required

Returns:

Type Description
Extraction

Extraction object containing parsed results.
Source code in socials/extractor.py 
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
def extract(self, urls: list[str]) -> Extraction:
    """Parse multiple URLs.

    Args:
        urls: List of URLs to parse.

    Returns:
        Extraction object containing parsed results.

    """
    results: list[SocialsURL] = []
    for url in urls:
        result = self.parse(url)
        if result is not None:
            results.append(result)
    return Extraction(results)

socials.Extraction

Result of extracting social URLs from a list of URLs.

Source code in socials/extractor.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
class Extraction:
    """Result of extracting social URLs from a list of URLs."""

    def __init__(self, results: list[SocialsURL]) -> None:
        """Initialize with parsed URL results.

        Args:
            results: List of parsed SocialsURL objects.

        """
        self._results = results

    def all(self) -> list[SocialsURL]:
        """Return all parsed URLs.

        Returns:
            List of all SocialsURL objects.

        """
        return list(self._results)

    def by_platform(self) -> dict[str, list[SocialsURL]]:
        """Group results by platform.

        Returns:
            Dictionary mapping platform names to lists of URLs.

        """
        grouped: dict[str, list[SocialsURL]] = defaultdict(list)
        for result in self._results:
            grouped[result.platform].append(result)
        return dict(grouped)

    def by_type(self) -> dict[str, list[SocialsURL]]:
        """Group results by entity type.

        Returns:
            Dictionary mapping entity types to lists of URLs.

        """
        grouped: dict[str, list[SocialsURL]] = defaultdict(list)
        for result in self._results:
            grouped[result.entity_type].append(result)
        return dict(grouped)

    # 0.x backwards compatibility methods (deprecated)

    def _get_compat_url(self, url_obj: SocialsURL) -> str:
        """Get URL string for backwards compat (applies cleaning like 0.x)."""
        if isinstance(url_obj, EmailURL):
            return url_obj.email
        return url_obj.url

    def get_matches_per_platform(self) -> dict[str, list[str]]:
        """Get URL strings grouped by platform.

        .. deprecated:: 1.0
            Use :meth:`by_platform` instead, which returns typed URL objects.

        Returns:
            Dictionary mapping platform names to lists of URL strings.

        """
        warnings.warn(
            "get_matches_per_platform() is deprecated, use by_platform() instead",
            DeprecationWarning,
            stacklevel=2,
        )
        result: dict[str, list[str]] = defaultdict(list)
        for url_obj in self._results:
            result[url_obj.platform].append(self._get_compat_url(url_obj))
        return dict(result)

    def get_matches_for_platform(self, platform: str) -> list[str]:
        """Get URL strings for a specific platform.

        .. deprecated:: 1.0
            Use :meth:`by_platform` instead, which returns typed URL objects.

        Args:
            platform: Platform name to filter by.

        Returns:
            List of URL strings for the given platform.

        """
        warnings.warn(
            "get_matches_for_platform() is deprecated, "
            "use by_platform()[platform] instead",
            DeprecationWarning,
            stacklevel=2,
        )
        return [
            self._get_compat_url(url_obj)
            for url_obj in self._results
            if url_obj.platform == platform
        ]

all()

Return all parsed URLs.

Returns:

Type Description
list[SocialsURL]

List of all SocialsURL objects.
Source code in socials/extractor.py 
30
31
32
33
34
35
36
37
def all(self) -> list[SocialsURL]:
    """Return all parsed URLs.

    Returns:
        List of all SocialsURL objects.

    """
    return list(self._results)

by_platform()

Group results by platform.

Returns:

Type Description
dict[str, list[SocialsURL]]

Dictionary mapping platform names to lists of URLs.
Source code in socials/extractor.py 
39
40
41
42
43
44
45
46
47
48
49
def by_platform(self) -> dict[str, list[SocialsURL]]:
    """Group results by platform.

    Returns:
        Dictionary mapping platform names to lists of URLs.

    """
    grouped: dict[str, list[SocialsURL]] = defaultdict(list)
    for result in self._results:
        grouped[result.platform].append(result)
    return dict(grouped)

by_type()

Group results by entity type.

Returns:

Type Description
dict[str, list[SocialsURL]]

Dictionary mapping entity types to lists of URLs.
Source code in socials/extractor.py 
51
52
53
54
55
56
57
58
59
60
61
def by_type(self) -> dict[str, list[SocialsURL]]:
    """Group results by entity type.

    Returns:
        Dictionary mapping entity types to lists of URLs.

    """
    grouped: dict[str, list[SocialsURL]] = defaultdict(list)
    for result in self._results:
        grouped[result.entity_type].append(result)
    return dict(grouped)

socials.registry.Registry

Registry that maps hostnames to platform parsers.

When multiple parsers could handle the same URL, the first registered parser takes priority. This is a "first match wins" policy.

Source code in socials/registry.py 
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
class Registry:
    """Registry that maps hostnames to platform parsers.

    When multiple parsers could handle the same URL, the first registered
    parser takes priority. This is a "first match wins" policy.
    """

    def __init__(self, parsers: list[PlatformParser] | None = None) -> None:
        """Initialize registry with optional list of parsers.

        Args:
            parsers: List of platform parsers to register.

        """
        self._parsers: list[PlatformParser] = []
        if parsers:
            for parser in parsers:
                self.register(parser)

    def register(self, parser: PlatformParser) -> None:
        """Register a new parser.

        If another parser already handles the same schemes, a warning is issued.
        The first registered parser takes priority (first match wins).

        Args:
            parser: Parser to register.

        """
        # Check for scheme overlap with existing parsers (ignore http/https since
        # those are differentiated by hostname, not scheme)
        dominated_schemes = {"http", "https"}
        for existing in self._parsers:
            overlap = (parser.schemes & existing.schemes) - dominated_schemes
            if overlap:
                warnings.warn(
                    f"Parser '{parser.platform}' has overlapping schemes {overlap} "
                    f"with existing parser '{existing.platform}'. "
                    f"First registered parser ('{existing.platform}') takes priority.",
                    stacklevel=2,
                )
                break  # Only warn once

        self._parsers.append(parser)

    def get_parser_for_url(self, url: str) -> PlatformParser | None:
        """Find the parser that handles the given URL.

        Args:
            url: URL to find parser for.

        Returns:
            Parser that handles the URL, or None.

        """
        scheme = extract_scheme(url)

        if scheme in ("http", "https"):
            hostname = extract_hostname(url)
            return self.get_parser_for_hostname(hostname)

        if scheme:
            return self.get_parser_for_scheme(scheme)

        # No scheme (e.g., raw email) - try all parsers
        for parser in self._parsers:
            if parser.parse(url) is not None:
                return parser
        return None

    def get_parser_for_scheme(self, scheme: str) -> PlatformParser | None:
        """Find the parser that handles the given URL scheme.

        Args:
            scheme: URL scheme to find parser for (e.g., 'mailto', 'tel').

        Returns:
            Parser that handles the scheme, or None.

        """
        for parser in self._parsers:
            if scheme in parser.schemes:
                return parser
        return None

    def get_parser_for_hostname(self, hostname: str) -> PlatformParser | None:
        """Find the parser that handles the given hostname.

        Args:
            hostname: Hostname to find parser for.

        Returns:
            Parser that handles the hostname, or None.

        """
        for parser in self._parsers:
            if parser.handles_hostname(hostname):
                return parser
        return None

    def parse(self, url: str) -> SocialsURL | None:
        """Parse a URL using the appropriate parser.

        Args:
            url: URL to parse.

        Returns:
            Parsed URL object, or None if no parser handles it.

        """
        parser = self.get_parser_for_url(url)
        if parser is None:
            return None
        return parser.parse(url)

    @property
    def parsers(self) -> list[PlatformParser]:
        """Return list of registered parsers."""
        return list(self._parsers)

parsers property

Return list of registered parsers.

__init__(parsers=None)

Initialize registry with optional list of parsers.

Parameters:

Name Type Description Default
parsers list[PlatformParser] | None

List of platform parsers to register.

 None
Source code in socials/registry.py 
21
22
23
24
25
26
27
28
29
30
31
def __init__(self, parsers: list[PlatformParser] | None = None) -> None:
    """Initialize registry with optional list of parsers.

    Args:
        parsers: List of platform parsers to register.

    """
    self._parsers: list[PlatformParser] = []
    if parsers:
        for parser in parsers:
            self.register(parser)

get_parser_for_hostname(hostname)

Find the parser that handles the given hostname.

Parameters:

Name Type Description Default
hostname str

Hostname to find parser for.

 required

Returns:

Type Description
PlatformParser | None

Parser that handles the hostname, or None.
Source code in socials/registry.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def get_parser_for_hostname(self, hostname: str) -> PlatformParser | None:
    """Find the parser that handles the given hostname.

    Args:
        hostname: Hostname to find parser for.

    Returns:
        Parser that handles the hostname, or None.

    """
    for parser in self._parsers:
        if parser.handles_hostname(hostname):
            return parser
    return None

get_parser_for_scheme(scheme)

Find the parser that handles the given URL scheme.

Parameters:

Name Type Description Default
scheme str

URL scheme to find parser for (e.g., 'mailto', 'tel').

 required

Returns:

Type Description
PlatformParser | None

Parser that handles the scheme, or None.
Source code in socials/registry.py 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def get_parser_for_scheme(self, scheme: str) -> PlatformParser | None:
    """Find the parser that handles the given URL scheme.

    Args:
        scheme: URL scheme to find parser for (e.g., 'mailto', 'tel').

    Returns:
        Parser that handles the scheme, or None.

    """
    for parser in self._parsers:
        if scheme in parser.schemes:
            return parser
    return None

get_parser_for_url(url)

Find the parser that handles the given URL.

Parameters:

Name Type Description Default
url str

URL to find parser for.

 required

Returns:

Type Description
PlatformParser | None

Parser that handles the URL, or None.
Source code in socials/registry.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def get_parser_for_url(self, url: str) -> PlatformParser | None:
    """Find the parser that handles the given URL.

    Args:
        url: URL to find parser for.

    Returns:
        Parser that handles the URL, or None.

    """
    scheme = extract_scheme(url)

    if scheme in ("http", "https"):
        hostname = extract_hostname(url)
        return self.get_parser_for_hostname(hostname)

    if scheme:
        return self.get_parser_for_scheme(scheme)

    # No scheme (e.g., raw email) - try all parsers
    for parser in self._parsers:
        if parser.parse(url) is not None:
            return parser
    return None

parse(url)

Parse a URL using the appropriate parser.

Parameters:

Name Type Description Default
url str

URL to parse.

 required

Returns:

Type Description
SocialsURL | None

Parsed URL object, or None if no parser handles it.
Source code in socials/registry.py 
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def parse(self, url: str) -> SocialsURL | None:
    """Parse a URL using the appropriate parser.

    Args:
        url: URL to parse.

    Returns:
        Parsed URL object, or None if no parser handles it.

    """
    parser = self.get_parser_for_url(url)
    if parser is None:
        return None
    return parser.parse(url)

register(parser)

Register a new parser.

If another parser already handles the same schemes, a warning is issued. The first registered parser takes priority (first match wins).

Parameters:

Name Type Description Default
parser PlatformParser

Parser to register.

 required
Source code in socials/registry.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def register(self, parser: PlatformParser) -> None:
    """Register a new parser.

    If another parser already handles the same schemes, a warning is issued.
    The first registered parser takes priority (first match wins).

    Args:
        parser: Parser to register.

    """
    # Check for scheme overlap with existing parsers (ignore http/https since
    # those are differentiated by hostname, not scheme)
    dominated_schemes = {"http", "https"}
    for existing in self._parsers:
        overlap = (parser.schemes & existing.schemes) - dominated_schemes
        if overlap:
            warnings.warn(
                f"Parser '{parser.platform}' has overlapping schemes {overlap} "
                f"with existing parser '{existing.platform}'. "
                f"First registered parser ('{existing.platform}') takes priority.",
                stacklevel=2,
            )
            break  # Only warn once

    self._parsers.append(parser)

Protocols

socials.protocols.SocialsURL

Bases: Protocol

Common interface all parsed URLs implement.

Source code in socials/protocols.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
@runtime_checkable
class SocialsURL(Protocol):
    """Common interface all parsed URLs implement."""

    @property
    def url(self) -> str:
        """Original URL string."""
        ...

    @property
    def platform(self) -> str:
        """Platform identifier (e.g., 'github', 'twitter')."""
        ...

    @property
    def entity_type(self) -> str:
        """Entity type (e.g., 'profile', 'repo')."""
        ...

    def get_parent(self) -> SocialsURL | None:
        """Return immediate parent (issue → repo)."""
        ...

    def get_root(self) -> SocialsURL:
        """Return top of hierarchy (issue → profile/org)."""
        ...

    def get_ancestors(self) -> list[SocialsURL]:
        """Return full chain from parent to root: [repo, profile]."""
        ...

entity_type property

Entity type (e.g., 'profile', 'repo').

platform property

Platform identifier (e.g., 'github', 'twitter').

url property

Original URL string.

get_ancestors()

Return full chain from parent to root: [repo, profile].

Source code in socials/protocols.py 
39
40
41
def get_ancestors(self) -> list[SocialsURL]:
    """Return full chain from parent to root: [repo, profile]."""
    ...

get_parent()

Return immediate parent (issue → repo).

Source code in socials/protocols.py 
31
32
33
def get_parent(self) -> SocialsURL | None:
    """Return immediate parent (issue → repo)."""
    ...

get_root()

Return top of hierarchy (issue → profile/org).

Source code in socials/protocols.py 
35
36
37
def get_root(self) -> SocialsURL:
    """Return top of hierarchy (issue → profile/org)."""
    ...

socials.protocols.PlatformParser

Bases: Protocol

Interface for platform-specific URL parsers.

Source code in socials/protocols.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
@runtime_checkable
class PlatformParser(Protocol):
    """Interface for platform-specific URL parsers."""

    platform: str
    schemes: ClassVar[set[str]]

    def handles_hostname(self, hostname: str) -> bool:
        """Check if this parser handles the given hostname."""
        ...

    def parse(self, url: str) -> SocialsURL | None:
        """Parse URL into typed object, or None if not recognized."""
        ...

handles_hostname(hostname)

Check if this parser handles the given hostname.

Source code in socials/protocols.py 
51
52
53
def handles_hostname(self, hostname: str) -> bool:
    """Check if this parser handles the given hostname."""
    ...

parse(url)

Parse URL into typed object, or None if not recognized.

Source code in socials/protocols.py 
55
56
57
def parse(self, url: str) -> SocialsURL | None:
    """Parse URL into typed object, or None if not recognized."""
    ...

socials.protocols.ParseError

Bases: Exception

Raised when URL parsing fails (if strict mode enabled).

Source code in socials/protocols.py 
8
9
class ParseError(Exception):
    """Raised when URL parsing fails (if strict mode enabled)."""

Platform URL Types

All URL types implement the SocialsURL protocol (see above) with get_parent(), get_root(), and get_ancestors() methods. Below are the platform-specific attributes for each type.

GitHub

socials.platforms.github.GitHubProfileURL

Bases: BaseModel

GitHub user or organization profile URL.

Source code in socials/platforms/github.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
class GitHubProfileURL(BaseModel, frozen=True):
    """GitHub user or organization profile URL."""

    url: str
    platform: Literal["github"] = "github"
    entity_type: Literal["profile"] = "profile"
    username: str

    def __hash__(self) -> int:
        """Return hash based on URL."""
        return hash(self.url)

    def get_parent(self) -> None:
        """Return parent (None for profiles)."""
        return

    def get_root(self) -> GitHubProfileURL:
        """Return root of hierarchy (self for profiles)."""
        return self

    def get_ancestors(self) -> list[SocialsURL]:
        """Return ancestors (empty for profiles)."""
        return []

socials.platforms.github.GitHubRepoURL

Bases: BaseModel

GitHub repository URL.

Source code in socials/platforms/github.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
class GitHubRepoURL(BaseModel, frozen=True):
    """GitHub repository URL."""

    url: str
    platform: Literal["github"] = "github"
    entity_type: Literal["repo"] = "repo"
    owner: str
    repo: str

    def __hash__(self) -> int:
        """Return hash based on URL."""
        return hash(self.url)

    def get_parent(self) -> GitHubProfileURL:
        """Return parent profile."""
        return GitHubProfileURL(
            url=f"https://github.com/{self.owner}",
            username=self.owner,
        )

    def get_root(self) -> GitHubProfileURL:
        """Return root of hierarchy."""
        return self.get_parent()

    def get_ancestors(self) -> list[SocialsURL]:
        """Return ancestors."""
        return [self.get_parent()]

Twitter

socials.platforms.twitter.TwitterProfileURL

Bases: BaseModel

Twitter/X user profile URL.

Source code in socials/platforms/twitter.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
class TwitterProfileURL(BaseModel, frozen=True):
    """Twitter/X user profile URL."""

    url: str
    platform: Literal["twitter"] = "twitter"
    entity_type: Literal["profile"] = "profile"
    username: str

    def __hash__(self) -> int:
        """Return hash based on URL."""
        return hash(self.url)

    def get_parent(self) -> None:
        """Return parent (None for profiles)."""
        return

    def get_root(self) -> TwitterProfileURL:
        """Return root of hierarchy (self for profiles)."""
        return self

    def get_ancestors(self) -> list[SocialsURL]:
        """Return ancestors (empty for profiles)."""
        return []

LinkedIn

socials.platforms.linkedin.LinkedInProfileURL

Bases: BaseModel

LinkedIn personal profile URL.

Source code in socials/platforms/linkedin.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
class LinkedInProfileURL(BaseModel, frozen=True):
    """LinkedIn personal profile URL."""

    url: str
    platform: Literal["linkedin"] = "linkedin"
    entity_type: Literal["profile"] = "profile"
    username: str

    def __hash__(self) -> int:
        """Return hash based on URL."""
        return hash(self.url)

    def get_parent(self) -> None:
        """Return parent (None for profiles)."""
        return

    def get_root(self) -> LinkedInProfileURL:
        """Return root of hierarchy (self for profiles)."""
        return self

    def get_ancestors(self) -> list[SocialsURL]:
        """Return ancestors (empty for profiles)."""
        return []

socials.platforms.linkedin.LinkedInCompanyURL

Bases: BaseModel

LinkedIn company page URL.

Source code in socials/platforms/linkedin.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
class LinkedInCompanyURL(BaseModel, frozen=True):
    """LinkedIn company page URL."""

    url: str
    platform: Literal["linkedin"] = "linkedin"
    entity_type: Literal["company"] = "company"
    company_id: str

    def __hash__(self) -> int:
        """Return hash based on URL."""
        return hash(self.url)

    def get_parent(self) -> None:
        """Return parent (None for companies)."""
        return

    def get_root(self) -> LinkedInCompanyURL:
        """Return root of hierarchy (self for companies)."""
        return self

    def get_ancestors(self) -> list[SocialsURL]:
        """Return ancestors (empty for companies)."""
        return []

Facebook

socials.platforms.facebook.FacebookProfileURL

Bases: BaseModel

Facebook user or page profile URL.

Source code in socials/platforms/facebook.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
class FacebookProfileURL(BaseModel, frozen=True):
    """Facebook user or page profile URL."""

    url: str
    platform: Literal["facebook"] = "facebook"
    entity_type: Literal["profile"] = "profile"
    username: Optional[str] = None
    user_id: Optional[str] = None

    def __hash__(self) -> int:
        """Return hash based on URL."""
        return hash(self.url)

    def get_parent(self) -> None:
        """Return parent (None for profiles)."""
        return

    def get_root(self) -> FacebookProfileURL:
        """Return root of hierarchy (self for profiles)."""
        return self

    def get_ancestors(self) -> list[SocialsURL]:
        """Return ancestors (empty for profiles)."""
        return []

Instagram

socials.platforms.instagram.InstagramProfileURL

Bases: BaseModel

Instagram user profile URL.

Source code in socials/platforms/instagram.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
class InstagramProfileURL(BaseModel, frozen=True):
    """Instagram user profile URL."""

    url: str
    platform: Literal["instagram"] = "instagram"
    entity_type: Literal["profile"] = "profile"
    username: str

    def __hash__(self) -> int:
        """Return hash based on URL."""
        return hash(self.url)

    def get_parent(self) -> None:
        """Return parent (None for profiles)."""
        return

    def get_root(self) -> InstagramProfileURL:
        """Return root of hierarchy (self for profiles)."""
        return self

    def get_ancestors(self) -> list[SocialsURL]:
        """Return ancestors (empty for profiles)."""
        return []

YouTube

socials.platforms.youtube.YouTubeChannelURL

Bases: BaseModel

YouTube channel URL.

Source code in socials/platforms/youtube.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
class YouTubeChannelURL(BaseModel, frozen=True):
    """YouTube channel URL."""

    url: str
    platform: Literal["youtube"] = "youtube"
    entity_type: Literal["channel"] = "channel"
    channel_id: Optional[str] = None
    username: Optional[str] = None
    custom_url: Optional[str] = None

    def __hash__(self) -> int:
        """Return hash based on URL."""
        return hash(self.url)

    def get_parent(self) -> None:
        """Return parent (None for channels)."""
        return

    def get_root(self) -> YouTubeChannelURL:
        """Return root of hierarchy (self for channels)."""
        return self

    def get_ancestors(self) -> list[SocialsURL]:
        """Return ancestors (empty for channels)."""
        return []

Email and Phone

socials.platforms.misc.EmailURL

Bases: BaseModel

Email address (mailto: URL or plain email).

Source code in socials/platforms/misc.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class EmailURL(BaseModel, frozen=True):
    """Email address (mailto: URL or plain email)."""

    url: str
    platform: Literal["email"] = "email"
    entity_type: Literal["email"] = "email"
    email: str

    def __hash__(self) -> int:
        """Return hash based on URL."""
        return hash(self.url)

    def get_parent(self) -> None:
        """Return parent (None for emails)."""
        return

    def get_root(self) -> EmailURL:
        """Return root of hierarchy (self for emails)."""
        return self

    def get_ancestors(self) -> list[SocialsURL]:
        """Return ancestors (empty for emails)."""
        return []

socials.platforms.misc.PhoneURL

Bases: BaseModel

Phone number (tel: URL).

Source code in socials/platforms/misc.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
class PhoneURL(BaseModel, frozen=True):
    """Phone number (tel: URL)."""

    url: str
    platform: Literal["phone"] = "phone"
    entity_type: Literal["phone"] = "phone"
    number: str

    def __hash__(self) -> int:
        """Return hash based on URL."""
        return hash(self.url)

    def get_parent(self) -> None:
        """Return parent (None for phone numbers)."""
        return

    def get_root(self) -> PhoneURL:
        """Return root of hierarchy (self for phone numbers)."""
        return self

    def get_ancestors(self) -> list[SocialsURL]:
        """Return ancestors (empty for phone numbers)."""
        return []