domaintools-api-test-upload 2.6.1__tar.gz → 2.6.3__tar.gz

{domaintools_api_test_upload-2.6.1/domaintools_api_test_upload.egg-info → domaintools_api_test_upload-2.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
-Name: domaintools-api-test-upload
-Version: 2.6.1
+Name: domaintools_api_test_upload
+Version: 2.6.3
 Summary: DomainTools Official Python API
 Author-email: DomainTools <integrations@domaintools.com>
 License: The MIT License (MIT)
@@ -354,6 +354,10 @@ To add more e2e tests, put these in the `../tests/e2e` folder.
         export TEST_USER=<user-key>
         export TEST_KEY=<api-key>
     ```
+- Run unit tests.
+    ```bash
+        tox -e
+    ```
 
 ## Run the end-to-end test script
 - Before running the test, be sure that docker is running.

{domaintools_api_test_upload-2.6.1 → domaintools_api_test_upload-2.6.3}/README.md

@@ -304,6 +304,10 @@ To add more e2e tests, put these in the `../tests/e2e` folder.
         export TEST_USER=<user-key>
         export TEST_KEY=<api-key>
     ```
+- Run unit tests.
+    ```bash
+        tox -e
+    ```
 
 ## Run the end-to-end test script
 - Before running the test, be sure that docker is running.

domaintools_api_test_upload-2.6.3/VERSION

@@ -0,0 +1 @@
+2.6.3

{domaintools_api_test_upload-2.6.1 → domaintools_api_test_upload-2.6.3}/domaintools/_version.py

@@ -20,4 +20,4 @@ OTHER DEALINGS IN THE SOFTWARE.
 
 """
 
-current = "2.6.1"
+current = "2.6.3"

{domaintools_api_test_upload-2.6.1 → domaintools_api_test_upload-2.6.3}/domaintools/api.py

@@ -5,8 +5,16 @@ from typing import Union
 
 import re
 import ssl
-
-from domaintools.constants import Endpoint, ENDPOINT_TO_SOURCE_MAP, RTTF_PRODUCTS_LIST, OutputFormat
+import yaml
+
+from domaintools.constants import (
+    Endpoint,
+    OutputFormat,
+    ENDPOINT_TO_SOURCE_MAP,
+    RTTF_PRODUCTS_LIST,
+    RTTF_PRODUCTS_CMD_MAPPING,
+    SPECS_MAPPING,
+)
 from domaintools._version import current as version
 from domaintools.results import (
     GroupedIterable,
@@ -16,6 +24,7 @@ from domaintools.results import (
     Results,
     FeedsResults,
 )
+from domaintools.decorators import api_endpoint, auto_patch_docstrings
 from domaintools.filters import (
     filter_by_riskscore,
     filter_by_expire_date,
@@ -34,6 +43,7 @@ def delimited(items, character="|"):
     return character.join(items) if type(items) in (list, tuple, set) else items
 
 
+@auto_patch_docstrings
 class API(object):
     """Enables interacting with the DomainTools API via Python:
 
@@ -88,8 +98,10 @@ class API(object):
         self.key_sign_hash = key_sign_hash
         self.default_parameters["app_name"] = app_name
         self.default_parameters["app_version"] = app_version
+        self.specs = {}
 
         self._build_api_url(api_url, api_port)
+        self._initialize_specs()
 
         if not https:
             raise Exception(
@@ -98,8 +110,25 @@ class API(object):
         if proxy_url and not isinstance(proxy_url, str):
             raise Exception("Proxy URL must be a string. For example: '127.0.0.1:8888'")
 
+    def _initialize_specs(self):
+        for spec_name, file_path in SPECS_MAPPING.items():
+            try:
+                with open(file_path, "r", encoding="utf-8") as f:
+                    spec_content = yaml.safe_load(f)
+                if not spec_content:
+                    raise ValueError("Spec file is empty or invalid.")
+
+                self.specs[spec_name] = spec_content
+
+            except Exception as e:
+                print(f"Error loading {file_path}: {e}")
+
     def _get_ssl_default_context(self, verify_ssl: Union[str, bool]):
-        return ssl.create_default_context(cafile=verify_ssl) if isinstance(verify_ssl, str) else verify_ssl
+        return (
+            ssl.create_default_context(cafile=verify_ssl)
+            if isinstance(verify_ssl, str)
+            else verify_ssl
+        )
 
     def _build_api_url(self, api_url=None, api_port=None):
         """Build the API url based on the given url and port. Defaults to `https://api.domaintools.com`"""
@@ -112,8 +141,12 @@ class API(object):
 
         self._rest_api_url = rest_api_url
 
-    def _rate_limit(self):
+    def _rate_limit(self, product):
         """Pulls in and enforces the latest rate limits for the specified user"""
+        if product in RTTF_PRODUCTS_LIST:
+            self.limits_set = False
+            return
+
         self.limits_set = True
         for product in self.account_information():
             limit_minutes = product["per_minute_limit"] or None
@@ -123,14 +156,21 @@ class API(object):
             hours = limit_hours and 3600 / float(limit_hours)
             minutes = limit_minutes and 60 / float(limit_minutes)
 
-            self.limits[product["id"]] = {"interval": timedelta(seconds=minutes or hours or default)}
+            self.limits[product["id"]] = {
+                "interval": timedelta(seconds=minutes or hours or default)
+            }
 
     def _results(self, product, path, cls=Results, **kwargs):
         """Returns _results for the specified API path with the specified **kwargs parameters"""
-        if product != "account-information" and self.rate_limit and not self.limits_set and not self.limits:
+        if (
+            product != "account-information"
+            and self.rate_limit
+            and not self.limits_set
+            and not self.limits
+        ):
             always_sign_api_key_previous_value = self.always_sign_api_key
             header_authentication_previous_value = self.header_authentication
-            self._rate_limit()
+            self._rate_limit(product)
             # Reset always_sign_api_key and header_authentication to its original
             # User-set values as these might be affected when self.account_information() was executed
             self.always_sign_api_key = always_sign_api_key_previous_value
@@ -171,7 +211,9 @@ class API(object):
             else:
                 raise ValueError(
                     "Invalid value '{0}' for 'key_sign_hash'. "
-                    "Values available are {1}".format(self.key_sign_hash, ",".join(AVAILABLE_KEY_SIGN_HASHES))
+                    "Values available are {1}".format(
+                        self.key_sign_hash, ",".join(AVAILABLE_KEY_SIGN_HASHES)
+                    )
                 )
 
             parameters["timestamp"] = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -183,7 +225,9 @@ class API(object):
 
     def account_information(self, **kwargs):
         """Provides a snapshot of your accounts current API usage"""
-        return self._results("account-information", "/v1/account", items_path=("products",), **kwargs)
+        return self._results(
+            "account-information", "/v1/account", items_path=("products",), **kwargs
+        )
 
     def available_api_calls(self):
         """Provides a list of api calls that you can use based on your account information."""
@@ -205,13 +249,23 @@ class API(object):
                 if not api_call.startswith("_") and callable(getattr(API, api_call, None))
             )
         )
-        return sorted(
-            [
-                snakecase(p["id"])
-                for p in self.account_information()["products"]
-                if snakecase(p["id"]) in api_calls
-            ]
-        )
+
+        account_information = self.account_information()
+
+        available_calls = set()
+        for product in self.account_information():
+            product_id = product["id"]
+            # for RTUF endpoints as we use different func name in our wrapper
+            if product_id in RTTF_PRODUCTS_LIST:
+                if rttf_api_command := RTTF_PRODUCTS_CMD_MAPPING.get(product_id):
+                    available_calls.add(rttf_api_command)
+
+            # for IRIS endpoints
+            snakecase_pid = snakecase(product_id)
+            if snakecase_pid in api_calls:
+                available_calls.add(snakecase_pid)
+
+        return sorted(available_calls)
 
     def brand_monitor(self, query, exclude=None, domain_status=None, days_back=None, **kwargs):
         """Pass in one or more terms as a list or separated by the pipe character ( | )"""
@@ -376,7 +430,9 @@ class API(object):
 
     def reverse_ip(self, domain=None, limit=None, **kwargs):
         """Pass in a domain name."""
-        return self._results("reverse-ip", "/v1/{0}/reverse-ip".format(domain), limit=limit, **kwargs)
+        return self._results(
+            "reverse-ip", "/v1/{0}/reverse-ip".format(domain), limit=limit, **kwargs
+        )
 
     def host_domains(self, ip=None, limit=None, **kwargs):
         """Pass in an IP address."""
@@ -550,8 +606,12 @@ class API(object):
         younger_than_date = kwargs.pop("younger_than_date", {}) or None
         older_than_date = kwargs.pop("older_than_date", {}) or None
         updated_after = kwargs.pop("updated_after", {}) or None
-        include_domains_with_missing_field = kwargs.pop("include_domains_with_missing_field", {}) or None
-        exclude_domains_with_missing_field = kwargs.pop("exclude_domains_with_missing_field", {}) or None
+        include_domains_with_missing_field = (
+            kwargs.pop("include_domains_with_missing_field", {}) or None
+        )
+        exclude_domains_with_missing_field = (
+            kwargs.pop("exclude_domains_with_missing_field", {}) or None
+        )
 
         filtered_results = DTResultFilter(result_set=results).by(
             [
@@ -604,6 +664,7 @@ class API(object):
             **kwargs,
         )
 
+    @api_endpoint(spec_name="iris", path="/v1/iris-investigate/", methods="post")
     def iris_investigate(
         self,
         domains=None,
@@ -621,29 +682,6 @@ class API(object):
         **kwargs,
     ):
         """Returns back a list of domains based on the provided filters.
-        The following filters are available beyond what is parameterized as kwargs:
-
-            - ip: Search for domains having this IP.
-            - email: Search for domains with this email in their data.
-            - email_domain: Search for domains where the email address uses this domain.
-            - nameserver_host: Search for domains with this nameserver.
-            - nameserver_domain: Search for domains with a nameserver that has this domain.
-            - nameserver_ip: Search for domains with a nameserver on this IP.
-            - registrar: Search for domains with this registrar.
-            - registrant: Search for domains with this registrant name.
-            - registrant_org: Search for domains with this registrant organization.
-            - mailserver_host: Search for domains with this mailserver.
-            - mailserver_domain: Search for domains with a mailserver that has this domain.
-            - mailserver_ip: Search for domains with a mailserver on this IP.
-            - redirect_domain: Search for domains which redirect to this domain.
-            - ssl_hash: Search for domains which have an SSL certificate with this hash.
-            - ssl_subject: Search for domains which have an SSL certificate with this subject string.
-            - ssl_email: Search for domains which have an SSL certificate with this email in it.
-            - ssl_org: Search for domains which have an SSL certificate with this organization in it.
-            - google_analytics: Search for domains which have this Google Analytics code.
-            - adsense: Search for domains which have this AdSense code.
-            - tld: Filter by TLD. Must be combined with another parameter.
-            - search_hash: Use search hash from Iris to bring back domains.
 
         You can loop over results of your investigation as if it was a native Python list:
 
@@ -1275,7 +1313,7 @@ class API(object):
             kwargs.pop("headers", None)
 
         return self._results(
-            f"domain-risk-feed-({source})",
+            f"real-time-domain-risk-({source})",
             f"v1/{endpoint}/domainrisk/",
             response_path=(),
             cls=FeedsResults,
@@ -1309,7 +1347,7 @@ class API(object):
             kwargs.pop("headers", None)
 
         return self._results(
-            f"domain-hotlist-feed-({source})",
+            f"real-time-domain-hotlist-({source})",
             f"v1/{endpoint}/domainhotlist/",
             response_path=(),
             cls=FeedsResults,

{domaintools_api_test_upload-2.6.1 → domaintools_api_test_upload-2.6.3}/domaintools/base_results.py

@@ -94,8 +94,7 @@ class Results(MutableMapping, MutableSequence):
                 headers["accept"] = HEADER_ACCEPT_KEY_CSV_FORMAT
 
         if self.api.header_authentication:
-            header_key_for_api_key = "X-Api-Key" if is_rttf_product else "X-API-Key"
-            headers[header_key_for_api_key] = self.api.key
+            headers["X-Api-Key"] = self.api.key
 
         session_param_and_headers = {"parameters": parameters, "headers": headers}
         return session_param_and_headers
@@ -342,7 +341,9 @@ class Results(MutableMapping, MutableSequence):
         )
 
     def as_list(self):
-        return "\n".join([json.dumps(item, indent=4, separators=(",", ": ")) for item in self._items()])
+        return "\n".join(
+            [json.dumps(item, indent=4, separators=(",", ": ")) for item in self._items()]
+        )
 
     def __str__(self):
         return str(

{domaintools_api_test_upload-2.6.1 → domaintools_api_test_upload-2.6.3}/domaintools/cli/api.py

@@ -222,7 +222,6 @@ class DTCLICommand:
                     header_authentication=header_authentication,
                 )
                 dt_api_func = getattr(dt_api, name)
-
                 params = params | kwargs
 
                 response = dt_api_func(**params)
@@ -241,7 +240,7 @@ class DTCLICommand:
                         description=f"Printing the results with format of {response_format}...",
                     )
                     # use rich `print` command to prettify the ouput in sys.stdout
-                    if response.product in RTTF_PRODUCTS_LIST:
+                    if name not in ("available_api_calls",) and response.product in RTTF_PRODUCTS_LIST:
                         for feeds in response.response():
                             print(feeds)
                     else:

domaintools_api_test_upload-2.6.3/domaintools/constants.py

@@ -0,0 +1,63 @@
+from enum import Enum
+
+
+class Endpoint(Enum):
+    FEED = "feed"
+    DOWNLOAD = "download"
+
+
+class Source(Enum):
+    API = "api"
+    S3 = "s3"
+
+
+class OutputFormat(Enum):
+    JSONL = "jsonl"
+    CSV = "csv"
+
+
+HEADER_ACCEPT_KEY_CSV_FORMAT = "text/csv"
+
+ENDPOINT_TO_SOURCE_MAP = {
+    Endpoint.FEED.value: Source.API,
+    Endpoint.DOWNLOAD.value: Source.S3,
+}
+
+RTTF_PRODUCTS_LIST = [
+    "newly-active-domains-feed-(api)",
+    "newly-active-domains-feed-(s3)",
+    "newly-observed-domains-feed-(api)",
+    "newly-observed-domains-feed-(s3)",
+    "newly-observed-hosts-feed-(api)",
+    "newly-observed-hosts-feed-(s3)",
+    "real-time-domain-hotlist-(api)",
+    "real-time-domain-hotlist-(s3)",
+    "domain-registration-data-access-protocol-feed-(api)",
+    "domain-registration-data-access-protocol-feed-(s3)",
+    "real-time-domain-risk-(api)",
+    "real-time-domain-risk-(s3)",
+    "real-time-domain-discovery-feed-(api)",
+    "real-time-domain-discovery-feed-(s3)",
+]
+
+RTTF_PRODUCTS_CMD_MAPPING = {
+    "newly-active-domains-feed-(api)": "nad",
+    "newly-active-domains-feed-(s3)": "nad",
+    "newly-observed-domains-feed-(api)": "nod",
+    "newly-observed-domains-feed-(s3)": "nod",
+    "newly-observed-hosts-feed-(api)": "noh",
+    "newly-observed-hosts-feed-(s3)": "noh",
+    "real-time-domain-hotlist-(api)": "domainhotlist",
+    "real-time-domain-hotlist-(s3)": "domainhotlist",
+    "domain-registration-data-access-protocol-feed-(api)": "domainrdap",
+    "domain-registration-data-access-protocol-feed-(s3)": "domainrdap",
+    "real-time-domain-risk-(api)": "realtime_domain_risk",
+    "real-time-domain-risk-(s3)": "realtime_domain_risk",
+    "real-time-domain-discovery-feed-(api)": "domaindiscovery",
+    "real-time-domain-discovery-feed-(s3)": "domaindiscovery",
+}
+
+SPECS_MAPPING = {
+    "iris": "domaintools/specs/iris-openapi.yaml",
+    # "rttf": "domaintools/specs/feeds-openapi.yaml",
+}

domaintools_api_test_upload-2.6.3/domaintools/decorators.py

@@ -0,0 +1,57 @@
+import functools
+
+from typing import List, Union
+
+from domaintools.docstring_patcher import DocstringPatcher
+
+
+def api_endpoint(spec_name: str, path: str, methods: Union[str, List[str]]):
+    """
+    Decorator to tag a method as an API endpoint.
+
+    Args:
+        spec_name: The key for the spec in api_instance.specs
+        path: The API path (e.g., "/users")
+        methods: A single method ("get") or list of methods (["get", "post"])
+                 that this function handles.
+    """
+
+    def decorator(func):
+        func._api_spec_name = spec_name
+        func._api_path = path
+
+        # Always store the methods as a list
+        if isinstance(methods, str):
+            func._api_methods = [methods]
+        else:
+            func._api_methods = methods
+
+        @functools.wraps(func)
+        def wrapper(self, *args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Copy all tags to the wrapper
+        wrapper._api_spec_name = func._api_spec_name
+        wrapper._api_path = func._api_path
+        wrapper._api_methods = func._api_methods
+        return wrapper
+
+    return decorator
+
+
+def auto_patch_docstrings(cls):
+    original_init = cls.__init__
+
+    @functools.wraps(original_init)
+    def new_init(self, *args, **kwargs):
+        original_init(self, *args, **kwargs)
+        try:
+            # We instantiate our patcher and run it
+            patcher = DocstringPatcher()
+            patcher.patch(self)
+        except Exception as e:
+            print(f"Auto-patching failed: {e}")
+
+    cls.__init__ = new_init
+
+    return cls