domaintools-api-test-upload 2.10.0__tar.gz → 3.0.0__tar.gz

{domaintools_api_test_upload-2.10.0 → domaintools_api_test_upload-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domaintools-api-test-upload
-Version: 2.10.0
+Version: 3.0.0
 Summary: DomainTools Official Python API
 Author-email: DomainTools <integrations@domaintools.com>
 License: The MIT License (MIT)
@@ -102,6 +102,41 @@ being passed in as method arguments:
 api.iris_enrich('domaintools.com')
 ```
 
+Namespaced Access
+===================
+
+In v3, each product family is also accessible as a named client attribute. Use namespaced
+access to scope calls to a specific product or to pass a single client to a helper function:
+
+```python
+api.iris.iris_investigate(domain='domaintools.com')
+api.feeds.nod(after='-60')
+api.domains.domain_profile('domaintools.com')
+api.detect.iris_detect_monitors()
+api.ips.host_domains('8.8.8.8')
+api.accounts.account_information()
+```
+
+Individual clients can also be constructed directly, sharing a single `DTAuth` object:
+
+```python
+from domaintools.auth.dt_auth import DTAuth
+from domaintools.clients.feeds import FeedsAPI
+
+auth = DTAuth('my_user', 'my_key')
+feeds = FeedsAPI(auth)
+```
+
+Pass `None` as the username if you are only using header-authenticated endpoints (RTTF feeds):
+
+```python
+auth = DTAuth(None, 'my_key')
+feeds = FeedsAPI(auth)
+```
+
+> **Upgrading from v2?** See [docs/v3-migration.md](docs/v3-migration.md) for a full list of
+> what changed and what stayed the same.
+
 You can get an overview of every endpoint that you can interact with using the builtin help function:
 
 ```python
@@ -150,14 +185,22 @@ api.iris_enrich('domaintools.com').data() == {'response': { ... }}
 api.iris_enrich('domaintools.com').response() == { ... }
 ```
 
-You can directly get the html, xml, or json version of the response by calling `.(html|xml|json)()` These only work with non AsyncResults:
+You can get the html, xml, or json version of the response using the `.html`, `.xml`, and `.json` properties. These return a new result object configured for that format — use `str()` to get the raw string:
 ```python
-json = str(api.domain_search('google').json())
-xml = str(api.domain_search('google').xml())
-html = str(api.domain_search('google').html())
+json_str = str(api.domain_search('google').json)
+xml_str  = str(api.domain_search('google').xml)
+html_str = str(api.domain_search('google').html)
 ```
 
-If any API call is unsuccesfull, one of the exceptions defined in `domaintools.exceptions` will be raised:
+You can also pass `format` directly to any endpoint method. For `xml` and `html` the result is a raw string — use `str(result)` or `result.data()` to access it. Dict-style access (`result["key"]`, iteration) is JSON-only:
+```python
+result = api.whois('google.com', format='xml')
+xml_str = str(result)       # raw XML string
+xml_str = result.data()     # same
+result['registrant']        # TypeError — use format='json' for key access
+```
+
+If any API call is unsuccessful, one of the exceptions defined in `domaintools.exceptions` will be raised:
 
 ```python-traceback
 api.domain_profile('notvalid').data()
@@ -203,6 +246,69 @@ You can get the status code of a response outside of exception handling by doing
 api.domain_profile('google.com').status == 200
 ```
 
+Parsed WHOIS and RDAP
+===================
+
+`parsed_whois()` and `parsed_domain_rdap()` return the most recent registration record for a domain, already broken
+out into fields. Both return result objects that behave like the standard results (dict access, `.data()`,
+`.response()`) and add a `.flattened()` helper:
+
+```python
+whois = api.parsed_whois('domaintools.com')
+print(whois['parsed_whois']['registrar']['name'])
+print(whois['parsed_whois']['created_date'])
+
+rdap = api.parsed_domain_rdap('domaintools.com')
+print(rdap['parsed_domain_rdap']['nameservers'])
+```
+
+`.flattened()` returns a single-level `OrderedDict`, which is convenient for CSV rows or dataframes:
+
+```python
+flat = api.parsed_whois('domaintools.com').flattened()
+flat['domain']             # 'domaintools.com'
+flat['name_servers']       # 'ns1.example.net | ns2.example.net'  (lists are joined with ' | ')
+flat['registrar_name']     # registrar fields are prefixed with 'registrar_'
+flat['registrant_email']   # contact fields are prefixed with the contact type
+
+flat = api.parsed_domain_rdap('domaintools.com').flattened()
+flat['nameservers']        # 'ns1.example.net | ns2.example.net'
+flat['registrar_name']
+flat['contact_roles_1']    # RDAP contacts are numbered from 1: contact_<field>_<n>
+flat['contact_email_1']
+```
+
+`.flattened()` needs a JSON result. Calling it on a `format='xml'` or `format='html'` result raises
+`UnsupportedFormatOperation`.
+
+### Domain history with parsed records
+
+`domain_history()` returns the change events for a domain. It supports field filtering, pagination, and embedding the
+full parsed WHOIS / RDAP record in each event's `before` / `after` objects:
+
+```python
+history = api.domain_history(
+    'domaintools.com',
+    include_fields='ip,registrar',   # or exclude_fields='all_ssl' (do not combine the two)
+    page_size=50,                    # max 100
+    offset=0,                        # 0-indexed; increment by page_size for the next page
+    parsed_whois=True,               # embed the parsed WHOIS record in before/after
+    parsed_domain_rdap=True,         # embed the parsed Domain RDAP record in before/after
+)
+for change in history:
+    print(change)
+```
+
+Pass `next=True` to get a `next` URL in the response for cursor-based pagination.
+
+The same options are available on the command line:
+
+```bash
+domaintools parsed_whois -q domaintools.com -u $TEST_USER -k $TEST_KEY
+domaintools parsed_domain_rdap -q domaintools.com -u $TEST_USER -k $TEST_KEY
+domaintools domain_history -q domaintools.com --include-fields ip,registrar --page-size 50 --parsed-whois -u $TEST_USER -k $TEST_KEY
+```
+
 IrisQL
 ===================
 

{domaintools_api_test_upload-2.10.0 → domaintools_api_test_upload-3.0.0}/README.md

@@ -44,6 +44,41 @@ being passed in as method arguments:
 api.iris_enrich('domaintools.com')
 ```
 
+Namespaced Access
+===================
+
+In v3, each product family is also accessible as a named client attribute. Use namespaced
+access to scope calls to a specific product or to pass a single client to a helper function:
+
+```python
+api.iris.iris_investigate(domain='domaintools.com')
+api.feeds.nod(after='-60')
+api.domains.domain_profile('domaintools.com')
+api.detect.iris_detect_monitors()
+api.ips.host_domains('8.8.8.8')
+api.accounts.account_information()
+```
+
+Individual clients can also be constructed directly, sharing a single `DTAuth` object:
+
+```python
+from domaintools.auth.dt_auth import DTAuth
+from domaintools.clients.feeds import FeedsAPI
+
+auth = DTAuth('my_user', 'my_key')
+feeds = FeedsAPI(auth)
+```
+
+Pass `None` as the username if you are only using header-authenticated endpoints (RTTF feeds):
+
+```python
+auth = DTAuth(None, 'my_key')
+feeds = FeedsAPI(auth)
+```
+
+> **Upgrading from v2?** See [docs/v3-migration.md](docs/v3-migration.md) for a full list of
+> what changed and what stayed the same.
+
 You can get an overview of every endpoint that you can interact with using the builtin help function:
 
 ```python
@@ -92,14 +127,22 @@ api.iris_enrich('domaintools.com').data() == {'response': { ... }}
 api.iris_enrich('domaintools.com').response() == { ... }
 ```
 
-You can directly get the html, xml, or json version of the response by calling `.(html|xml|json)()` These only work with non AsyncResults:
+You can get the html, xml, or json version of the response using the `.html`, `.xml`, and `.json` properties. These return a new result object configured for that format — use `str()` to get the raw string:
 ```python
-json = str(api.domain_search('google').json())
-xml = str(api.domain_search('google').xml())
-html = str(api.domain_search('google').html())
+json_str = str(api.domain_search('google').json)
+xml_str  = str(api.domain_search('google').xml)
+html_str = str(api.domain_search('google').html)
 ```
 
-If any API call is unsuccesfull, one of the exceptions defined in `domaintools.exceptions` will be raised:
+You can also pass `format` directly to any endpoint method. For `xml` and `html` the result is a raw string — use `str(result)` or `result.data()` to access it. Dict-style access (`result["key"]`, iteration) is JSON-only:
+```python
+result = api.whois('google.com', format='xml')
+xml_str = str(result)       # raw XML string
+xml_str = result.data()     # same
+result['registrant']        # TypeError — use format='json' for key access
+```
+
+If any API call is unsuccessful, one of the exceptions defined in `domaintools.exceptions` will be raised:
 
 ```python-traceback
 api.domain_profile('notvalid').data()
@@ -145,6 +188,69 @@ You can get the status code of a response outside of exception handling by doing
 api.domain_profile('google.com').status == 200
 ```
 
+Parsed WHOIS and RDAP
+===================
+
+`parsed_whois()` and `parsed_domain_rdap()` return the most recent registration record for a domain, already broken
+out into fields. Both return result objects that behave like the standard results (dict access, `.data()`,
+`.response()`) and add a `.flattened()` helper:
+
+```python
+whois = api.parsed_whois('domaintools.com')
+print(whois['parsed_whois']['registrar']['name'])
+print(whois['parsed_whois']['created_date'])
+
+rdap = api.parsed_domain_rdap('domaintools.com')
+print(rdap['parsed_domain_rdap']['nameservers'])
+```
+
+`.flattened()` returns a single-level `OrderedDict`, which is convenient for CSV rows or dataframes:
+
+```python
+flat = api.parsed_whois('domaintools.com').flattened()
+flat['domain']             # 'domaintools.com'
+flat['name_servers']       # 'ns1.example.net | ns2.example.net'  (lists are joined with ' | ')
+flat['registrar_name']     # registrar fields are prefixed with 'registrar_'
+flat['registrant_email']   # contact fields are prefixed with the contact type
+
+flat = api.parsed_domain_rdap('domaintools.com').flattened()
+flat['nameservers']        # 'ns1.example.net | ns2.example.net'
+flat['registrar_name']
+flat['contact_roles_1']    # RDAP contacts are numbered from 1: contact_<field>_<n>
+flat['contact_email_1']
+```
+
+`.flattened()` needs a JSON result. Calling it on a `format='xml'` or `format='html'` result raises
+`UnsupportedFormatOperation`.
+
+### Domain history with parsed records
+
+`domain_history()` returns the change events for a domain. It supports field filtering, pagination, and embedding the
+full parsed WHOIS / RDAP record in each event's `before` / `after` objects:
+
+```python
+history = api.domain_history(
+    'domaintools.com',
+    include_fields='ip,registrar',   # or exclude_fields='all_ssl' (do not combine the two)
+    page_size=50,                    # max 100
+    offset=0,                        # 0-indexed; increment by page_size for the next page
+    parsed_whois=True,               # embed the parsed WHOIS record in before/after
+    parsed_domain_rdap=True,         # embed the parsed Domain RDAP record in before/after
+)
+for change in history:
+    print(change)
+```
+
+Pass `next=True` to get a `next` URL in the response for cursor-based pagination.
+
+The same options are available on the command line:
+
+```bash
+domaintools parsed_whois -q domaintools.com -u $TEST_USER -k $TEST_KEY
+domaintools parsed_domain_rdap -q domaintools.com -u $TEST_USER -k $TEST_KEY
+domaintools domain_history -q domaintools.com --include-fields ip,registrar --page-size 50 --parsed-whois -u $TEST_USER -k $TEST_KEY
+```
+
 IrisQL
 ===================
 

domaintools_api_test_upload-3.0.0/VERSION

@@ -0,0 +1 @@
+3.0.0

domaintools_api_test_upload-3.0.0/domaintools/__init__.py

@@ -0,0 +1,29 @@
+"""DomainTools Official Python API"""
+
+from domaintools._version import current
+from domaintools.api import API
+from domaintools.auth.dt_auth import AuthMode, DTAuth
+from domaintools.clients import (
+    AccountsAPI,
+    CertsAPI,
+    DetectAPI,
+    DomainsAPI,
+    FeedsAPI,
+    IpsAPI,
+    IrisAPI,
+)
+
+__version__ = current
+
+__all__ = [
+    "API",
+    "DTAuth",
+    "AuthMode",
+    "DomainsAPI",
+    "IpsAPI",
+    "IrisAPI",
+    "AccountsAPI",
+    "DetectAPI",
+    "FeedsAPI",
+    "CertsAPI",
+]

{domaintools_api_test_upload-2.10.0 → domaintools_api_test_upload-3.0.0}/domaintools/_version.py

@@ -20,4 +20,4 @@ OTHER DEALINGS IN THE SOFTWARE.
 
 """
 
-current = "2.10.0"
+current = "3.0.0"

domaintools_api_test_upload-3.0.0/domaintools/api.py

@@ -0,0 +1,217 @@
+from typing import Optional, Union
+
+from domaintools._version import current as version
+from domaintools.auth.dt_auth import AuthMode, DTAuth
+from domaintools.clients import (
+    METHOD_REGISTRY,
+    AccountsAPI,
+    BaseClient,
+    CertsAPI,
+    DetectAPI,
+    DomainsAPI,
+    FeedsAPI,
+    IpsAPI,
+    IrisAPI,
+    RateLimiter,
+)
+
+
+def _make_delegate(client_attr: str, method_name: str):
+    """Return a method that forwards calls from API to the named method on a product client.
+
+    Used after the class definition to stamp real methods onto API for every name in
+    METHOD_REGISTRY, so flat access (api.nod(), api.iris_investigate()) works without
+    __getattr__ magic — making the methods visible to dir(), hasattr(), and patch.object().
+    """
+
+    def delegate(self, *args, **kwargs):
+        return getattr(getattr(self, client_attr), method_name)(*args, **kwargs)
+
+    delegate.__name__ = method_name
+    delegate.__qualname__ = f"API.{method_name}"
+    return delegate
+
+
+class API:
+    """Enables interacting with the DomainTools API via Python:
+
+        from domaintools import API
+
+        api = API('my_name', 'my_key')
+        results = api.domain_search('domain')
+
+    By default the API will automatically space out your requests to match your rate limits.
+    If your running over multiple Python runtimes, have your own rate limiting approach, or are doing a one-off
+    query (such as for a CLI command) you can set rate_limit=False to turn this feature off.
+
+    Namespaced client access is also supported:
+        api.domains.whois('domaintools.com')
+        api.feeds.nod(after=-60)
+        api.iris.iris_investigate(domain='domaintools.com')
+    """
+
+    def __init__(
+        self,
+        username: Optional[str],
+        key: str,
+        https: bool = True,
+        verify_ssl: Union[str, bool] = True,
+        rate_limit: bool = True,
+        proxy_url: Optional[str] = None,
+        always_sign_api_key: Optional[bool] = None,
+        header_authentication: Optional[bool] = None,
+        key_sign_hash: str = "sha256",
+        app_name: str = "python_wrapper",
+        app_version: str = version,
+        api_url: Optional[str] = None,
+        api_port: Optional[int] = None,
+        **default_parameters,
+    ):
+        self._auth = DTAuth(username, key, key_sign_hash=key_sign_hash)
+
+        standard_mode, feeds_mode = API._resolve_auth_modes(always_sign_api_key, header_authentication)
+
+        shared = dict(
+            https=https,
+            verify_ssl=verify_ssl,
+            rate_limit=rate_limit,
+            proxy_url=proxy_url,
+            app_name=app_name,
+            app_version=app_version,
+            api_url=api_url,
+            api_port=api_port,
+            default_parameters=default_parameters if default_parameters else {},
+        )
+
+        rate_limiter = RateLimiter()
+
+        def _make_client(cls, auth_mode=standard_mode, **kwargs):
+            client_kwargs = shared.copy()
+            client_kwargs["rate_limiter"] = rate_limiter
+            if auth_mode is not None:
+                client_kwargs["auth_mode"] = auth_mode
+            client_kwargs.update(kwargs)
+            return cls(self._auth, **client_kwargs)
+
+        self.domains = _make_client(DomainsAPI)
+        self.ips = _make_client(IpsAPI)
+        self.iris = _make_client(IrisAPI)
+        self.accounts = _make_client(AccountsAPI)
+        self.detect = _make_client(DetectAPI)
+        self.feeds = _make_client(FeedsAPI, auth_mode=feeds_mode, rate_limit=False)
+        self.certs = _make_client(CertsAPI)
+
+    # back Compatiblity read-only properties
+    @property
+    def key(self) -> str:
+        return self._auth.key
+
+    @property
+    def limits(self) -> dict:
+        return self.domains._rate_limiter.limits
+
+    @property
+    def limits_set(self) -> bool:
+        return self.domains._rate_limiter.limits_set
+
+    @property
+    def always_sign_api_key(self) -> bool:
+        return self.feeds.auth_mode == AuthMode.HMAC
+
+    @always_sign_api_key.setter
+    def always_sign_api_key(self, value: bool) -> None:
+        standard_mode, feeds_mode = API._resolve_auth_modes(value, None)
+        for client in (self.domains, self.ips, self.iris, self.accounts, self.detect, self.certs):
+            client.auth_mode = standard_mode
+        self.feeds.auth_mode = feeds_mode
+
+    @property
+    def header_authentication(self) -> bool:
+        return self.feeds.auth_mode == AuthMode.HEADER
+
+    @header_authentication.setter
+    def header_authentication(self, value: bool) -> None:
+        standard_mode, feeds_mode = API._resolve_auth_modes(None, value)
+        for client in (self.domains, self.ips, self.iris, self.accounts, self.detect, self.certs):
+            client.auth_mode = standard_mode
+        self.feeds.auth_mode = feeds_mode
+
+    @property
+    def verify_ssl(self):
+        return self.domains.verify_ssl
+
+    @verify_ssl.setter
+    def verify_ssl(self, value) -> None:
+        for client in (self.domains, self.ips, self.iris, self.accounts, self.detect, self.feeds, self.certs):
+            client.verify_ssl = value
+
+    @property
+    def proxy_url(self) -> Optional[str]:
+        return self.domains.proxy_url
+
+    @proxy_url.setter
+    def proxy_url(self, value: Optional[str]) -> None:
+        for client in (self.domains, self.ips, self.iris, self.accounts, self.detect, self.feeds, self.certs):
+            client.proxy_url = value
+
+    @property
+    def rate_limit(self) -> bool:
+        return self.domains.rate_limit
+
+    @property
+    def https(self) -> bool:
+        return True
+
+    @staticmethod
+    def _resolve_auth_modes(
+        always_sign_api_key: Optional[bool],
+        header_authentication: Optional[bool],
+    ) -> tuple:
+        """Translate legacy v2 bool kwargs into (standard_mode, feeds_mode) AuthMode values.
+
+        Both None → (None, None): each client falls back to its DEFAULT_AUTH_MODE.
+        Both True → ValueError: mutually exclusive options.
+
+        Examples:
+            API(user, key)                                              → (None, None)
+            API(user, key, always_sign_api_key=True)                   → (HMAC,      HMAC)
+            API(user, key, header_authentication=True)                 → (HEADER,    HEADER)
+            API(user, key, always_sign_api_key=False)                  → (PLAIN_KEY, HEADER)
+            API(user, key, always_sign_api_key=False,
+                           header_authentication=False)                → (PLAIN_KEY, PLAIN_KEY)
+        """
+        if always_sign_api_key is True and header_authentication is True:
+            raise ValueError(
+                "Passing both always_sign_api_key=True and header_authentication=True is not supported. "
+                "Choose one auth method: HMAC (always_sign_api_key=True) or HEADER (header_authentication=True)."
+            )
+        if always_sign_api_key is None and header_authentication is None:
+            return (None, None)
+
+        #                                           standard_mode       feeds_mode
+        _AUTH_MODE_TABLE = {
+            (True, None): (AuthMode.HMAC, AuthMode.HMAC),
+            (True, False): (AuthMode.HMAC, AuthMode.HMAC),
+            (False, None): (AuthMode.PLAIN_KEY, AuthMode.HEADER),
+            (False, False): (AuthMode.PLAIN_KEY, AuthMode.PLAIN_KEY),
+            (False, True): (AuthMode.HEADER, AuthMode.HEADER),
+            (None, True): (AuthMode.HEADER, AuthMode.HEADER),
+            (None, False): (AuthMode.HMAC, AuthMode.PLAIN_KEY),
+        }
+
+        return _AUTH_MODE_TABLE[(always_sign_api_key, header_authentication)]
+
+    def __getattr__(self, name: str):
+        attr = METHOD_REGISTRY.get(name)
+        if attr is None:
+            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+        return getattr(getattr(self, attr), name)
+
+
+# Generate explicit delegate methods on API at class definition time.
+# Skips 'iris' because api.iris is already the IrisAPI instance (set in __init__
+# as an instance attribute, which shadows the class-level delegate).
+for _method_name, _client_attr in METHOD_REGISTRY.items():
+    if _method_name == "iris":
+        continue
+    setattr(API, _method_name, _make_delegate(_client_attr, _method_name))

domaintools_api_test_upload-3.0.0/domaintools/auth/__init__.py

@@ -0,0 +1 @@
+# domaintools/auth

domaintools_api_test_upload-3.0.0/domaintools/auth/dt_auth.py

@@ -0,0 +1,73 @@
+from datetime import datetime, timezone
+from enum import Enum
+from hashlib import sha1, sha256
+from hmac import new as hmac
+from typing import Dict, Optional, Tuple
+
+AVAILABLE_KEY_SIGN_HASHES = ["sha1", "sha256"]
+
+_HASH_MAP = {"sha1": sha1, "sha256": sha256}
+
+
+class AuthMode(Enum):
+    HMAC = "hmac"
+    HEADER = "header"
+    PLAIN_KEY = "plain_key"
+
+
+class DTAuth:
+    """Owns credentials and the signing algorithm.  Pure — no per-request mutation of self."""
+
+    def __init__(
+        self,
+        username: Optional[str],
+        key: str,
+        *,
+        key_sign_hash: str = "sha256",
+    ):
+        if key_sign_hash not in AVAILABLE_KEY_SIGN_HASHES:
+            raise ValueError(
+                "Invalid value '{0}' for 'key_sign_hash'. "
+                "Values available are {1}".format(key_sign_hash, ",".join(AVAILABLE_KEY_SIGN_HASHES))
+            )
+        self.username = username
+        self.key = key
+        self.key_sign_hash = key_sign_hash
+
+    def sign(self, path: str, params: Dict) -> Dict:
+        """Return a copy of params with api_username, timestamp, and signature added.
+
+        Path is normalized to a leading '/' before signing (v2 parity).
+        """
+        if self.username is None:
+            raise ValueError("username is required for HMAC authentication")
+        sign_path = path if path.startswith("/") else f"/{path}"
+        params_copy = dict(params)
+        params_copy["api_username"] = self.username
+        params_copy["timestamp"] = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        params_copy["signature"] = hmac(
+            self.key.encode("utf8"),
+            "".join([self.username, params_copy["timestamp"], sign_path]).encode("utf8"),
+            digestmod=_HASH_MAP[self.key_sign_hash],
+        ).hexdigest()
+        return params_copy
+
+    def apply(self, path: str, params: Dict, *, mode: AuthMode) -> Tuple[Dict, Dict]:
+        """Single entry point for auth.  Returns (params_copy, headers).
+
+        Pure function of its arguments — does not mutate self or the caller's params dict.
+        """
+        params_copy = dict(params)
+        headers: Dict[str, str] = {}
+
+        if mode == AuthMode.HMAC:
+            params_copy = self.sign(path, params_copy)
+        elif mode == AuthMode.HEADER:
+            headers["X-Api-Key"] = self.key
+        elif mode == AuthMode.PLAIN_KEY:
+            if self.username is None:
+                raise ValueError("username is required for PLAIN_KEY authentication")
+            params_copy["api_username"] = self.username
+            params_copy["api_key"] = self.key
+
+        return params_copy, headers