sosmed-scanner 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nuzuli
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,130 @@
1
+ Metadata-Version: 2.4
2
+ Name: sosmed-scanner
3
+ Version: 0.4.0
4
+ Summary: Check whether a username exists on public profile pages - 20 platforms, zero dependencies (Python standard library only).
5
+ Author: Nuzuli
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/Nuzuli/sosmed-scanner
8
+ Project-URL: Repository, https://github.com/Nuzuli/sosmed-scanner
9
+ Keywords: username-checker,osint,cli,social-media
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: Internet
16
+ Requires-Python: >=3.8
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Dynamic: license-file
20
+
21
+ # Sosmed Scanner
22
+
23
+
24
+
25
+ ![CI](https://github.com/Nuzuli/sosmed-scanner/actions/workflows/ci.yml/badge.svg)
26
+
27
+ ![Demo](demo.gif)
28
+
29
+
30
+
31
+ A small Python command-line tool that checks whether a username exists on public profile pages. It uses only the standard library and reads public information only.
32
+
33
+ ## Project Type
34
+
35
+ This is a standard library only command-line tool, not infrastructure code.
36
+
37
+ ## Features
38
+
39
+ - Checks 20 platforms: GitHub, GitLab, Reddit, Medium, DEV, PyPI, YouTube, Mastodon, Tumblr, Flickr, SoundCloud, Dribbble, Linktree, Gravatar, Codeberg, SourceHut, Keybase, Chess.com, Docker Hub, and Hugging Face.
40
+ - Three clear statuses: `found`, `not_found`, and `unknown` (for blocked or failed requests).
41
+ - Plain text, JSON, or CSV output.
42
+ - Polite by default: sends a descriptive User-Agent, uses a timeout, and waits between requests.
43
+ - Optional debug logging with `--verbose`.
44
+ - No third-party runtime dependencies.
45
+
46
+ ## Architecture
47
+
48
+ - `sosmed_scanner/network.py`: HTTP request helper. Network errors are returned as data, never raised.
49
+ - `sosmed_scanner/scanner.py`: platform list, username validation, and the scan loop.
50
+ - `sosmed_scanner/cli.py`: argument parsing, logging setup, and output formatting.
51
+ - `tests/`: unit and integration tests that use mocks, so no real network access is needed.
52
+
53
+ ### Quick Start (fresh clone)
54
+
55
+ The tool itself runs on Python 3.8 or newer and has no dependencies. The development toolchain (tests, lint, type checks) is pinned for Python 3.12, which is what CI uses.
56
+
57
+ ```bash
58
+ git clone https://github.com/Nuzuli/sosmed-scanner.git
59
+ cd sosmed-scanner
60
+ python -m venv .venv
61
+ source .venv/bin/activate
62
+ pip install -r requirements-dev.lock
63
+ pytest
64
+ ```
65
+
66
+ On Windows, activate the environment with `.venv\Scripts\activate`.
67
+
68
+ `requirements-dev.lock` is committed to the repository and checked by CI, so every install uses the same pinned versions. After changing `requirements-dev.txt`, regenerate the lockfile by running the "Update lockfile" workflow in the Actions tab; CI fails if the two files disagree.
69
+
70
+ ## Usage
71
+
72
+ Run from the repository root:
73
+
74
+ `python -m sosmed_scanner.cli target_username`
75
+
76
+ Options:
77
+
78
+ - `-p`, `--platform NAME`: scan only this platform (repeatable), for example `-p github -p dev`
79
+ - `--json`: print results as JSON
80
+ - `--csv`: print results as CSV (columns: platform, status, url, detail)
81
+ - `--delay SECONDS`: pause between requests (default `0.5`)
82
+ - `-v`, `--verbose`: print debug details to stderr
83
+
84
+ Example output:
85
+
86
+ ```
87
+ GitHub found https://github.com/alice
88
+ GitLab not_found https://gitlab.com/alice
89
+ Reddit unknown https://www.reddit.com/user/alice (HTTP 429)
90
+ ```
91
+ ## Logging
92
+
93
+ Diagnostic messages are emitted at DEBUG level as one JSON object per record. Every record has an `event` key plus event-specific fields, for example:
94
+
95
+ ```json
96
+ {"event": "fetch_done", "status": 200, "url": "https://github.com/octocat"}
97
+ ```
98
+
99
+ Events: `scan_start`, `platform_result`, `scan_done`, `fetch_start`, `fetch_done`, `fetch_failed`.
100
+
101
+ ## Exit Codes
102
+
103
+ - `0`: scan finished
104
+ - `2`: invalid input (bad username or unknown platform)
105
+
106
+ ## Understanding Results
107
+
108
+ - `found`: the profile page returned HTTP 200.
109
+ - `not_found`: the profile page returned HTTP 404.
110
+ - `unknown`: anything else, such as rate limiting, blocking, or a network error. The `detail` field explains why.
111
+
112
+ ## Development
113
+
114
+ Run the checks locally:
115
+
116
+ ```
117
+ ruff check sosmed_scanner tests
118
+ mypy sosmed_scanner
119
+ pytest -v --cov=sosmed_scanner --cov-fail-under=80
120
+ ```
121
+
122
+ The same checks, plus a dependency audit, run on every push through GitHub Actions.
123
+
124
+ ## Responsible Use
125
+
126
+ Use this tool only for lawful purposes, such as checking your own username or brand. It reads public pages only. Respect each platform's terms of service and do not use it for harassment or profiling people.
127
+
128
+ ## License
129
+
130
+ MIT License. See `LICENSE`.
@@ -0,0 +1,110 @@
1
+ # Sosmed Scanner
2
+
3
+
4
+
5
+ ![CI](https://github.com/Nuzuli/sosmed-scanner/actions/workflows/ci.yml/badge.svg)
6
+
7
+ ![Demo](demo.gif)
8
+
9
+
10
+
11
+ A small Python command-line tool that checks whether a username exists on public profile pages. It uses only the standard library and reads public information only.
12
+
13
+ ## Project Type
14
+
15
+ This is a standard library only command-line tool, not infrastructure code.
16
+
17
+ ## Features
18
+
19
+ - Checks 20 platforms: GitHub, GitLab, Reddit, Medium, DEV, PyPI, YouTube, Mastodon, Tumblr, Flickr, SoundCloud, Dribbble, Linktree, Gravatar, Codeberg, SourceHut, Keybase, Chess.com, Docker Hub, and Hugging Face.
20
+ - Three clear statuses: `found`, `not_found`, and `unknown` (for blocked or failed requests).
21
+ - Plain text, JSON, or CSV output.
22
+ - Polite by default: sends a descriptive User-Agent, uses a timeout, and waits between requests.
23
+ - Optional debug logging with `--verbose`.
24
+ - No third-party runtime dependencies.
25
+
26
+ ## Architecture
27
+
28
+ - `sosmed_scanner/network.py`: HTTP request helper. Network errors are returned as data, never raised.
29
+ - `sosmed_scanner/scanner.py`: platform list, username validation, and the scan loop.
30
+ - `sosmed_scanner/cli.py`: argument parsing, logging setup, and output formatting.
31
+ - `tests/`: unit and integration tests that use mocks, so no real network access is needed.
32
+
33
+ ### Quick Start (fresh clone)
34
+
35
+ The tool itself runs on Python 3.8 or newer and has no dependencies. The development toolchain (tests, lint, type checks) is pinned for Python 3.12, which is what CI uses.
36
+
37
+ ```bash
38
+ git clone https://github.com/Nuzuli/sosmed-scanner.git
39
+ cd sosmed-scanner
40
+ python -m venv .venv
41
+ source .venv/bin/activate
42
+ pip install -r requirements-dev.lock
43
+ pytest
44
+ ```
45
+
46
+ On Windows, activate the environment with `.venv\Scripts\activate`.
47
+
48
+ `requirements-dev.lock` is committed to the repository and checked by CI, so every install uses the same pinned versions. After changing `requirements-dev.txt`, regenerate the lockfile by running the "Update lockfile" workflow in the Actions tab; CI fails if the two files disagree.
49
+
50
+ ## Usage
51
+
52
+ Run from the repository root:
53
+
54
+ `python -m sosmed_scanner.cli target_username`
55
+
56
+ Options:
57
+
58
+ - `-p`, `--platform NAME`: scan only this platform (repeatable), for example `-p github -p dev`
59
+ - `--json`: print results as JSON
60
+ - `--csv`: print results as CSV (columns: platform, status, url, detail)
61
+ - `--delay SECONDS`: pause between requests (default `0.5`)
62
+ - `-v`, `--verbose`: print debug details to stderr
63
+
64
+ Example output:
65
+
66
+ ```
67
+ GitHub found https://github.com/alice
68
+ GitLab not_found https://gitlab.com/alice
69
+ Reddit unknown https://www.reddit.com/user/alice (HTTP 429)
70
+ ```
71
+ ## Logging
72
+
73
+ Diagnostic messages are emitted at DEBUG level as one JSON object per record. Every record has an `event` key plus event-specific fields, for example:
74
+
75
+ ```json
76
+ {"event": "fetch_done", "status": 200, "url": "https://github.com/octocat"}
77
+ ```
78
+
79
+ Events: `scan_start`, `platform_result`, `scan_done`, `fetch_start`, `fetch_done`, `fetch_failed`.
80
+
81
+ ## Exit Codes
82
+
83
+ - `0`: scan finished
84
+ - `2`: invalid input (bad username or unknown platform)
85
+
86
+ ## Understanding Results
87
+
88
+ - `found`: the profile page returned HTTP 200.
89
+ - `not_found`: the profile page returned HTTP 404.
90
+ - `unknown`: anything else, such as rate limiting, blocking, or a network error. The `detail` field explains why.
91
+
92
+ ## Development
93
+
94
+ Run the checks locally:
95
+
96
+ ```
97
+ ruff check sosmed_scanner tests
98
+ mypy sosmed_scanner
99
+ pytest -v --cov=sosmed_scanner --cov-fail-under=80
100
+ ```
101
+
102
+ The same checks, plus a dependency audit, run on every push through GitHub Actions.
103
+
104
+ ## Responsible Use
105
+
106
+ Use this tool only for lawful purposes, such as checking your own username or brand. It reads public pages only. Respect each platform's terms of service and do not use it for harassment or profiling people.
107
+
108
+ ## License
109
+
110
+ MIT License. See `LICENSE`.
@@ -0,0 +1,49 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "sosmed-scanner"
7
+ version = "0.4.0"
8
+ description = "Check whether a username exists on public profile pages - 20 platforms, zero dependencies (Python standard library only)."
9
+ readme = "README.md"
10
+ requires-python = ">=3.8"
11
+ license = { text = "MIT" }
12
+ authors = [
13
+ { name = "Nuzuli" },
14
+ ]
15
+ keywords = ["username-checker", "osint", "cli", "social-media"]
16
+ classifiers = [
17
+ "Development Status :: 3 - Alpha",
18
+ "Environment :: Console",
19
+ "Intended Audience :: Developers",
20
+ "License :: OSI Approved :: MIT License",
21
+ "Programming Language :: Python :: 3",
22
+ "Topic :: Internet",
23
+ ]
24
+
25
+ [project.urls]
26
+ Homepage = "https://github.com/Nuzuli/sosmed-scanner"
27
+ Repository = "https://github.com/Nuzuli/sosmed-scanner"
28
+
29
+ [project.scripts]
30
+ sosmed-scanner = "sosmed_scanner.cli:main"
31
+
32
+ [tool.setuptools]
33
+ packages = ["sosmed_scanner"]
34
+
35
+ [tool.ruff]
36
+ line-length = 100
37
+
38
+ [tool.ruff.lint]
39
+ select = ["E", "F", "W"]
40
+ ignore = ["W292"]
41
+
42
+ [tool.mypy]
43
+ python_version = "3.12"
44
+ warn_return_any = true
45
+ warn_unused_ignores = true
46
+
47
+ [tool.pytest.ini_options]
48
+ testpaths = ["tests"]
49
+ pythonpath = ["."]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """Sosmed Scanner: check username availability from public profile pages."""
2
+
3
+ __version__ = "0.4.0"
@@ -0,0 +1,124 @@
1
+ """Command-line interface for Sosmed Scanner."""
2
+
3
+ import argparse
4
+ import csv
5
+ import io
6
+ import json
7
+ import logging
8
+ import sys
9
+ from dataclasses import asdict
10
+ from typing import List, Optional, Sequence
11
+
12
+ from sosmed_scanner.scanner import PLATFORMS, ScanResult, scan_username
13
+
14
+ # Fixed name: __name__ is "__main__" when run with `python -m`.
15
+ logger = logging.getLogger("sosmed_scanner.cli")
16
+
17
+
18
+ def configure_logging(verbose: bool) -> None:
19
+ """Send log messages to stderr; show debug details when verbose."""
20
+ package_logger = logging.getLogger("sosmed_scanner")
21
+ package_logger.handlers.clear()
22
+ handler = logging.StreamHandler(sys.stderr)
23
+ handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
24
+ package_logger.addHandler(handler)
25
+ package_logger.setLevel(logging.DEBUG if verbose else logging.WARNING)
26
+ package_logger.propagate = False
27
+
28
+
29
+ def build_parser() -> argparse.ArgumentParser:
30
+ parser = argparse.ArgumentParser(
31
+ prog="sosmed_scanner",
32
+ description="Check whether a username exists on public profile pages.",
33
+ )
34
+ parser.add_argument("username", help="Username to look up")
35
+ parser.add_argument(
36
+ "-p",
37
+ "--platform",
38
+ action="append",
39
+ help="Limit the scan to a platform (repeatable). Available: "
40
+ + ", ".join(PLATFORMS),
41
+ )
42
+ parser.add_argument(
43
+ "--json", action="store_true", help="Print results as JSON"
44
+ )
45
+ parser.add_argument(
46
+ "--csv", action="store_true", help="Print results as CSV"
47
+ )
48
+ parser.add_argument(
49
+ "--delay",
50
+ type=float,
51
+ default=0.5,
52
+ help="Seconds to wait between requests (default: 0.5)",
53
+ )
54
+ parser.add_argument(
55
+ "-v",
56
+ "--verbose",
57
+ action="store_true",
58
+ help="Show debug details on stderr",
59
+ )
60
+ return parser
61
+
62
+
63
+ def validate_platforms(names: Optional[Sequence[str]]) -> None:
64
+ """Raise ValueError naming the unknown platforms and the valid choices.
65
+
66
+ Names are matched case-insensitively, like the scanner itself does.
67
+ """
68
+ if not names:
69
+ return
70
+ known = {name.lower() for name in PLATFORMS}
71
+ unknown = [name for name in names if name.lower() not in known]
72
+ if unknown:
73
+ raise ValueError(
74
+ f"Unknown platform: {', '.join(unknown)}. "
75
+ f"Available: {', '.join(PLATFORMS)}"
76
+ )
77
+
78
+
79
+ def format_results(results: List[ScanResult]) -> str:
80
+ """Render results as aligned plain text."""
81
+ lines = []
82
+ for item in results:
83
+ line = f"{item.platform:<12} {item.status:<10} {item.url}"
84
+ if item.detail:
85
+ line += f" ({item.detail})"
86
+ lines.append(line)
87
+ return "\n".join(lines)
88
+
89
+
90
+ def format_csv(results: List[ScanResult]) -> str:
91
+ """Render results as CSV with a header row."""
92
+ buffer = io.StringIO()
93
+ writer = csv.writer(buffer)
94
+ writer.writerow(["platform", "status", "url", "detail"])
95
+ for item in results:
96
+ writer.writerow(
97
+ [item.platform, item.status, item.url, item.detail or ""]
98
+ )
99
+ return buffer.getvalue().rstrip("\r\n")
100
+
101
+
102
+ def main(argv: Optional[Sequence[str]] = None) -> int:
103
+ """Run the CLI and return an exit code (0 ok, 2 invalid input)."""
104
+ args = build_parser().parse_args(argv)
105
+ configure_logging(args.verbose)
106
+ try:
107
+ validate_platforms(args.platform)
108
+ results = scan_username(
109
+ args.username, platforms=args.platform, delay=args.delay
110
+ )
111
+ except ValueError as error:
112
+ logger.error("%s", error)
113
+ return 2
114
+ if args.json:
115
+ print(json.dumps([asdict(item) for item in results], indent=2))
116
+ elif args.csv:
117
+ print(format_csv(results))
118
+ else:
119
+ print(format_results(results))
120
+ return 0
121
+
122
+
123
+ if __name__ == "__main__":
124
+ sys.exit(main())
@@ -0,0 +1,24 @@
1
+ """Structured (JSON) logging helper."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import logging
6
+ from typing import Any
7
+
8
+
9
+ def log_event(
10
+ logger: logging.Logger,
11
+ event: str,
12
+ *,
13
+ level: int = logging.DEBUG,
14
+ **fields: Any,
15
+ ) -> None:
16
+ """Emit one log record whose message is a JSON object.
17
+
18
+ The payload always has an "event" key; extra keyword arguments
19
+ become additional keys. Non-serializable values fall back to str().
20
+ """
21
+ if not logger.isEnabledFor(level):
22
+ return
23
+ payload = {"event": event, **fields}
24
+ logger.log(level, json.dumps(payload, default=str, sort_keys=True))
@@ -0,0 +1,46 @@
1
+ """Low-level HTTP helpers built on the standard library only."""
2
+
3
+ import logging
4
+ import urllib.error
5
+ import urllib.request
6
+ from dataclasses import dataclass
7
+ from typing import Optional
8
+
9
+ from sosmed_scanner import __version__
10
+ from sosmed_scanner.log import log_event
11
+
12
+ USER_AGENT = (
13
+ f"sosmed-scanner/{__version__} (+https://github.com/Nuzuli/sosmed-scanner)"
14
+ )
15
+ DEFAULT_TIMEOUT = 8.0
16
+
17
+ logger = logging.getLogger(__name__)
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class HttpResult:
22
+ """Outcome of a single HTTP request."""
23
+
24
+ url: str
25
+ status: Optional[int]
26
+ error: Optional[str] = None
27
+
28
+
29
+ def fetch_status(url: str, timeout: float = DEFAULT_TIMEOUT) -> HttpResult:
30
+ """Request a public URL and return its HTTP status code.
31
+
32
+ Network problems never raise: they are reported through ``error``.
33
+ """
34
+ log_event(logger, "fetch_start", url=url, timeout=timeout)
35
+ request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
36
+ try:
37
+ with urllib.request.urlopen(request, timeout=timeout) as response:
38
+ log_event(logger, "fetch_done", url=url, status=response.status)
39
+ return HttpResult(url=url, status=response.status)
40
+ except urllib.error.HTTPError as error:
41
+ log_event(logger, "fetch_done", url=url, status=error.code)
42
+ return HttpResult(url=url, status=error.code)
43
+ except OSError as error:
44
+ # URLError and TimeoutError are both subclasses of OSError.
45
+ log_event(logger, "fetch_failed", url=url, error=error)
46
+ return HttpResult(url=url, status=None, error=str(error))
@@ -0,0 +1,141 @@
1
+ """Scan public profile pages for a username."""
2
+
3
+ import logging
4
+ import re
5
+ import time
6
+ from dataclasses import dataclass
7
+ from typing import Callable, Dict, List, Optional, Sequence
8
+
9
+ from sosmed_scanner.log import log_event
10
+ from sosmed_scanner.network import HttpResult, fetch_status
11
+
12
+ logger = logging.getLogger(__name__)
13
+
14
+ PLATFORMS: Dict[str, str] = {
15
+ "GitHub": "https://github.com/{username}",
16
+ "GitLab": "https://gitlab.com/{username}",
17
+ "Reddit": "https://www.reddit.com/user/{username}",
18
+ "Medium": "https://medium.com/@{username}",
19
+ "DEV": "https://dev.to/{username}",
20
+ "PyPI": "https://pypi.org/user/{username}/",
21
+ "YouTube": "https://www.youtube.com/@{username}",
22
+ "Mastodon": "https://mastodon.social/@{username}",
23
+ "Tumblr": "https://{username}.tumblr.com",
24
+ "Flickr": "https://www.flickr.com/photos/{username}",
25
+ "SoundCloud": "https://soundcloud.com/{username}",
26
+ "Dribbble": "https://dribbble.com/{username}",
27
+ "Linktree": "https://linktr.ee/{username}",
28
+ "Gravatar": "https://gravatar.com/{username}",
29
+ "Codeberg": "https://codeberg.org/{username}",
30
+ "SourceHut": "https://sr.ht/~{username}",
31
+ "Keybase": "https://keybase.io/{username}",
32
+ "Chess.com": "https://www.chess.com/member/{username}",
33
+ "Docker Hub": "https://hub.docker.com/u/{username}",
34
+ "Hugging Face": "https://huggingface.co/{username}",
35
+ }
36
+
37
+ USERNAME_PATTERN = re.compile(r"^[A-Za-z0-9._-]{1,39}$")
38
+
39
+ FOUND = "found"
40
+ NOT_FOUND = "not_found"
41
+ UNKNOWN = "unknown"
42
+
43
+
44
+ class InvalidUsernameError(ValueError):
45
+ """Raised when a username contains unsupported characters."""
46
+
47
+
48
+ @dataclass(frozen=True)
49
+ class ScanResult:
50
+ """Result of checking one platform."""
51
+
52
+ platform: str
53
+ url: str
54
+ status: str
55
+ detail: Optional[str] = None
56
+
57
+
58
+ def validate_username(username: str) -> str:
59
+ """Return the cleaned username or raise InvalidUsernameError."""
60
+ cleaned = username.strip()
61
+ if not USERNAME_PATTERN.match(cleaned):
62
+ raise InvalidUsernameError(
63
+ "Username must be 1-39 characters: letters, digits, '.', '_' or '-'."
64
+ )
65
+ return cleaned
66
+
67
+
68
+ def classify(result: HttpResult) -> str:
69
+ """Map an HTTP result to found, not_found, or unknown."""
70
+ if result.status == 200:
71
+ return FOUND
72
+ if result.status == 404:
73
+ return NOT_FOUND
74
+ return UNKNOWN
75
+
76
+
77
+ def select_platforms(names: Optional[Sequence[str]]) -> Dict[str, str]:
78
+ """Return the platforms to scan, matching names case-insensitively."""
79
+ if not names:
80
+ return dict(PLATFORMS)
81
+ lookup = {name.lower(): name for name in PLATFORMS}
82
+ selected: Dict[str, str] = {}
83
+ for name in names:
84
+ key = lookup.get(name.lower())
85
+ if key is None:
86
+ raise ValueError(f"Unknown platform: {name}")
87
+ selected[key] = PLATFORMS[key]
88
+ return selected
89
+
90
+
91
+ def scan_username(
92
+ username: str,
93
+ platforms: Optional[Sequence[str]] = None,
94
+ fetch: Callable[[str], HttpResult] = fetch_status,
95
+ delay: float = 0.0,
96
+ sleep: Callable[[float], None] = time.sleep,
97
+ ) -> List[ScanResult]:
98
+ """Check a username on each selected platform, one request at a time."""
99
+ cleaned = validate_username(username)
100
+ targets = select_platforms(platforms)
101
+ results: List[ScanResult] = []
102
+ log_event(
103
+ logger,
104
+ "scan_start",
105
+ username=cleaned,
106
+ platforms=len(targets),
107
+ delay=delay,
108
+ )
109
+ for index, (name, template) in enumerate(targets.items()):
110
+ if index > 0 and delay > 0:
111
+ sleep(delay)
112
+ url = template.format(username=cleaned)
113
+ outcome = fetch(url)
114
+ detail = outcome.error
115
+ if detail is None and outcome.status not in (200, 404):
116
+ detail = f"HTTP {outcome.status}"
117
+ status = classify(outcome)
118
+ log_event(
119
+ logger,
120
+ "platform_result",
121
+ platform=name,
122
+ status=status,
123
+ url=url,
124
+ )
125
+ results.append(
126
+ ScanResult(
127
+ platform=name,
128
+ url=url,
129
+ status=status,
130
+ detail=detail,
131
+ )
132
+ )
133
+ found = sum(1 for item in results if item.status == FOUND)
134
+ log_event(
135
+ logger,
136
+ "scan_done",
137
+ username=cleaned,
138
+ checked=len(results),
139
+ found=found,
140
+ )
141
+ return results