Models
Data models and types used throughout Naminter.
API Reference
Data models for WMN dataset structures, enumeration results, and responses.
module-attribute
WMN_REQUIRED_KEYS = frozenset({'name', 'uri_check', 'e_code', 'e_string', 'm_string', 'm_code', 'known', 'cat'})
Bases: StrEnum
Status of username search results.
Bases: TypedDict
Type definition for a single site in the WMN dataset structure.
Required: name, uri_check, e_code, e_string, m_string, m_code, known, cat.
Optional with conditions
post_body: Must contain {account}. When present, headers
is required and {account} is not required in uri_check.
headers: Required when post_body is present. Must be dict[str, str].
uri_check: Must contain {account} when post_body is absent.
strip_bad_char: Characters to strip from username before substitution.
uri_pretty: Display URL template (not validated).
valid: Site validity flag (not validated).
protection: Protection mechanisms (not validated).
dataclass
Summary of the loaded WhatsMyName dataset and filters applied.
| ATTRIBUTE | DESCRIPTION |
|---|---|
license |
License information from the dataset.
TYPE:
|
authors |
Authors of the dataset.
TYPE:
|
site_names |
Names of all sites included.
TYPE:
|
sites_count |
Total number of sites.
TYPE:
|
categories |
Categories of the included sites.
TYPE:
|
categories_count |
Number of unique categories.
TYPE:
|
known_count |
Total number of known usernames across all sites.
TYPE:
|
dataclass
WMNResult(*, name, category, username, status, uri_check=None, uri_pretty=None, status_code=None, headers=None, text=None, elapsed=None, error=None, created_at=(lambda: now(UTC))())
Result of testing a username on a site.
| ATTRIBUTE | DESCRIPTION |
|---|---|
name |
Site name from the WMN dataset.
TYPE:
|
category |
Site category from the WMN dataset.
TYPE:
|
username |
Username that was tested.
TYPE:
|
status |
Detection status of the username on the site.
TYPE:
|
uri_check |
URL used for the check (request URL).
TYPE:
|
uri_pretty |
Optional "pretty" URL for display/reporting.
TYPE:
|
status_code |
HTTP status code of the response.
TYPE:
|
headers |
HTTP response headers.
TYPE:
|
text |
Response body text.
TYPE:
|
elapsed |
Time elapsed for the HTTP request.
TYPE:
|
error |
Error message if the check failed.
TYPE:
|
created_at |
Timestamp when the result was created.
TYPE:
|
classmethod
Create error result.
| PARAMETER | DESCRIPTION |
|---|---|
username
|
Username being checked.
TYPE:
|
message
|
Error message.
TYPE:
|
site
|
Site configuration.
TYPE:
|
uri_check
|
Optional URL used for the check.
TYPE:
|
uri_pretty
|
Optional pretty URL for display.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
WMNResult
|
Result with ERROR status.
TYPE:
|
classmethod
classmethod
Create WMNResult from HTTP response by evaluating detection criteria.
| PARAMETER | DESCRIPTION |
|---|---|
username
|
Username being checked.
TYPE:
|
uri_check
|
URL that was checked (request URL).
TYPE:
|
uri_pretty
|
Pretty URL for display, or None to use uri_check.
TYPE:
|
response
|
HTTP response object.
TYPE:
|
site
|
Site configuration dictionary with detection criteria.
TYPE:
|
mode
|
Detection mode (ANY or ALL).
TYPE:
|
exclude_text
|
When True, omit response text from the result.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
WMNResult
|
Result with determined status.
TYPE:
|
Convert the result to a plain dictionary.
| PARAMETER | DESCRIPTION |
|---|---|
exclude_text
|
When True, omit the response text field.
TYPE:
|
exclude_none
|
When True, omit fields with None values.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any]
|
dict[str, Any]: Dictionary representation of this result. |
dataclass
Result of validation testing for a site's detection methods.
| ATTRIBUTE | DESCRIPTION |
|---|---|
name |
Site name from the WMN dataset.
TYPE:
|
category |
Site category from the WMN dataset.
TYPE:
|
results |
List of individual WMNResult objects, or None.
TYPE:
|
error |
Error message if testing failed.
TYPE:
|
created_at |
Timestamp when the test result was created.
TYPE:
|
status |
Aggregate status computed from individual results.
TYPE:
|
classmethod
Create WMNTestResult from a site configuration.
| PARAMETER | DESCRIPTION |
|---|---|
site
|
Site configuration dictionary.
TYPE:
|
results
|
Optional list of WMNResult objects.
TYPE:
|
error
|
Optional error message.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
WMNTestResult
|
Result with name and category from site.
TYPE:
|
Convert the test result to a plain dictionary.
| PARAMETER | DESCRIPTION |
|---|---|
exclude_text
|
When True, omit response text from nested results.
TYPE:
|
exclude_none
|
When True, omit fields with None values.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any]
|
dict[str, Any]: Dictionary representation of this test result. |
dataclass
HTTP response abstraction used by session adapters.
| ATTRIBUTE | DESCRIPTION |
|---|---|
status_code |
HTTP status code of the response.
TYPE:
|
text |
Response body text.
TYPE:
|
elapsed |
Time elapsed for the HTTP request.
TYPE:
|
headers |
HTTP response headers, or None if unavailable.
TYPE:
|
Parse the response body as JSON and return the resulting object.
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | list[Any] | str | int | float | bool | None
|
dict[str, Any] | list[Any] | str | int | float | bool | None: The parsed JSON value. |
| RAISES | DESCRIPTION |
|---|---|
JSONDecodeError
|
If the response text is not valid JSON. |