domaintools-api-test-upload 2.7.4__tar.gz → 2.8.0__tar.gz

{domaintools_api_test_upload-2.7.4/domaintools_api_test_upload.egg-info → domaintools_api_test_upload-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domaintools_api_test_upload
-Version: 2.7.4
+Version: 2.8.0
 Summary: DomainTools Official Python API
 Author-email: DomainTools <integrations@domaintools.com>
 License: The MIT License (MIT)
@@ -50,6 +50,10 @@ Requires-Dist: typer
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: mock; extra == "test"
+Requires-Dist: vcrpy; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: yarl; extra == "test"
 Dynamic: license-file
 
 ![domaintools](https://github.com/DomainTools/python_api/raw/main/artwork/logo.png)
@@ -199,6 +203,32 @@ You can get the status code of a response outside of exception handling by doing
 api.domain_profile('google.com').status == 200
 ```
 
+IrisQL
+===================
+
+IrisQL is a query language for Iris Investigate that lets you express complex, multi-field searches in a single request. Pass the query as a raw string via the `irisql` parameter. The query must begin with `# IrisQL-1.0`.
+
+```python
+query = """# IrisQL-1.0
+DOMAIN CONTAINS "phishing"
+AND
+RISK_SCORE GREATER_THAN 85
+"""
+
+results = api.iris_investigate(irisql=query)
+print(results["results_count"])
+for domain in results:
+    print(domain["domain"])
+```
+
+Pagination parameters (`page_size`, `sort_by`, `position`) are supported alongside IrisQL via `**kwargs`:
+
+```python
+results = api.iris_investigate(irisql=query, page_size=50, sort_by="risk_score", position=0)
+```
+
+When `irisql` is set, any domain or filter parameters passed alongside it are silently ignored. IrisQL uses header-based authentication (`X-Api-Key`) automatically.
+
 Using the API Asynchronously
 ===================
 
@@ -255,6 +285,18 @@ Optionally, you can specify the desired format (html, xml, json, or list) of the
 domaintools domain_search google --max_length 10 -u $TEST_USER -k $TEST_KEY -f html
 ```
 
+IrisQL queries are supported via the `--irisql` flag on `iris_investigate`. The query must begin with `# IrisQL-1.0` on its own line:
+
+```bash
+domaintools iris_investigate --irisql $'# IrisQL-1.0\nDOMAIN CONTAINS "phishing"' -u $TEST_USER -k $TEST_KEY
+```
+
+Pagination parameters can be passed alongside the IrisQL query:
+
+```bash
+domaintools iris_investigate --irisql $'# IrisQL-1.0\nDOMAIN CONTAINS "phishing"' --page-size 50 --sort-by risk_score -u $TEST_USER -k $TEST_KEY
+```
+
 To avoid having to type in your API key repeatedly, you can specify them in `~/.dtapi` separated by a new line:
 
 ```bash
@@ -343,12 +385,11 @@ To add more e2e tests, put these in the `../tests/e2e` folder.
         source venv/bin/activate
     ```
 
-- Install dependencies.
+- Install dependencies (with test extras):
     ```bash
-        pip install -r requirements/development.txt
+        pip install -e ".[test]"
     ```
-
-- From the python_api project root directory, install the package.
+    Or without test dependencies:
     ```bash
         pip install -e .
     ```

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/README.md

@@ -145,6 +145,32 @@ You can get the status code of a response outside of exception handling by doing
 api.domain_profile('google.com').status == 200
 ```
 
+IrisQL
+===================
+
+IrisQL is a query language for Iris Investigate that lets you express complex, multi-field searches in a single request. Pass the query as a raw string via the `irisql` parameter. The query must begin with `# IrisQL-1.0`.
+
+```python
+query = """# IrisQL-1.0
+DOMAIN CONTAINS "phishing"
+AND
+RISK_SCORE GREATER_THAN 85
+"""
+
+results = api.iris_investigate(irisql=query)
+print(results["results_count"])
+for domain in results:
+    print(domain["domain"])
+```
+
+Pagination parameters (`page_size`, `sort_by`, `position`) are supported alongside IrisQL via `**kwargs`:
+
+```python
+results = api.iris_investigate(irisql=query, page_size=50, sort_by="risk_score", position=0)
+```
+
+When `irisql` is set, any domain or filter parameters passed alongside it are silently ignored. IrisQL uses header-based authentication (`X-Api-Key`) automatically.
+
 Using the API Asynchronously
 ===================
 
@@ -201,6 +227,18 @@ Optionally, you can specify the desired format (html, xml, json, or list) of the
 domaintools domain_search google --max_length 10 -u $TEST_USER -k $TEST_KEY -f html
 ```
 
+IrisQL queries are supported via the `--irisql` flag on `iris_investigate`. The query must begin with `# IrisQL-1.0` on its own line:
+
+```bash
+domaintools iris_investigate --irisql $'# IrisQL-1.0\nDOMAIN CONTAINS "phishing"' -u $TEST_USER -k $TEST_KEY
+```
+
+Pagination parameters can be passed alongside the IrisQL query:
+
+```bash
+domaintools iris_investigate --irisql $'# IrisQL-1.0\nDOMAIN CONTAINS "phishing"' --page-size 50 --sort-by risk_score -u $TEST_USER -k $TEST_KEY
+```
+
 To avoid having to type in your API key repeatedly, you can specify them in `~/.dtapi` separated by a new line:
 
 ```bash
@@ -289,12 +327,11 @@ To add more e2e tests, put these in the `../tests/e2e` folder.
         source venv/bin/activate
     ```
 
-- Install dependencies.
+- Install dependencies (with test extras):
     ```bash
-        pip install -r requirements/development.txt
+        pip install -e ".[test]"
     ```
-
-- From the python_api project root directory, install the package.
+    Or without test dependencies:
     ```bash
         pip install -e .
     ```

domaintools_api_test_upload-2.8.0/VERSION

@@ -0,0 +1 @@
+2.8.0

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools/_version.py

@@ -20,4 +20,4 @@ OTHER DEALINGS IN THE SOFTWARE.
 
 """
 
-current = "2.7.4"
+current = "2.8.0"

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools/api.py

@@ -128,11 +128,7 @@ class API(object):
                 print(f"Error loading {specs_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`"""
@@ -160,18 +156,11 @@ 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(product)
@@ -215,9 +204,7 @@ 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")
@@ -229,9 +216,7 @@ 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."""
@@ -290,6 +275,57 @@ class API(object):
         """Returns a profile for the specified domain name"""
         return self._results("domain-profile", "/v1/{0}".format(query))
 
+    def domain_history(
+        self,
+        query,
+        include_fields=None,
+        exclude_fields=None,
+        page_size=None,
+        offset=None,
+        next=None,
+        parsed_whois=None,
+        parsed_domain_rdap=None,
+        **kwargs,
+    ):
+        """Returns the history of changes for a given domain name.
+
+        Results are returned in reverse chronological order. Each change event includes
+        a timestamp, the field that changed, and the complete before/after domain state.
+
+        Args:
+            query: The apex domain name to retrieve history for (e.g. "domaintools.com").
+            include_fields: Comma-separated list of exact field names. Only change events
+                matching these fields appear in results. Cannot be combined with
+                exclude_fields. Supports aggregate prefixes (e.g. "all_ssl", "all_ip").
+                Example: "ip,registrar,all_ssl"
+            exclude_fields: Comma-separated list of exact field names. Change events
+                matching these fields are omitted. Cannot be combined with include_fields.
+                Example: "all_web_trackers,all_ssl"
+            page_size: Number of change events per page. Maximum and default is 100.
+            offset: 0-indexed starting point for pagination. Increment by page_size for
+                each subsequent page.
+            next: When True, includes a next URL in the response for cursor-based
+                pagination. Auth parameters must still be included when following it.
+            parsed_whois: When True, includes the full parsed WHOIS record in the
+                before/after objects of each change event.
+            parsed_domain_rdap: When True, includes the full parsed Domain RDAP record
+                in the before/after objects of each change event.
+        """
+        return self._results(
+            "domain-history",
+            "/v1/domain-history",
+            domain=query,
+            include_fields=include_fields,
+            exclude_fields=exclude_fields,
+            page_size=page_size,
+            offset=offset,
+            next=next,
+            parsed_whois=parsed_whois,
+            parsed_domain_rdap=parsed_domain_rdap,
+            items_path=("changes",),
+            **kwargs,
+        )
+
     def domain_search(
         self,
         query,
@@ -434,9 +470,7 @@ 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."""
@@ -610,12 +644,8 @@ 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(
             [
@@ -677,19 +707,20 @@ class API(object):
         create_date=None,
         active=None,
         search_hash=None,
-        risk_score=None,
+        risk_score_threshold=None,
         younger_than_date=None,
         older_than_date=None,
         updated_after=None,
         include_domains_with_missing_field=None,
         exclude_domains_with_missing_field=None,
+        irisql=None,
         **kwargs,
     ):
         """Returns back a list of domains based on the provided filters.
 
         You can loop over results of your investigation as if it was a native Python list:
 
-            for result in api.iris_investigate(ip='199.30.228.112'):  # Enables looping over all related results
+            for result in api.iris_investigate(ip='199.30.228.112'):
 
         api.iris_investigate(QUERY)['results_count'] Returns the number of results returned with this request
         api.iris_investigate(QUERY)['total_count'] Returns the number of results available within Iris
@@ -698,9 +729,27 @@ class API(object):
         api.iris_investigate(QUERY)['position'] Returns the position key that can be used to retrieve the next page:
             next_page = api.iris_investigate(QUERY, position=api.iris_investigate(QUERY)['position'])
 
-        for enrichment in api.iris_enrich(i):  # Enables looping over all returned enriched domains
+        IrisQL mode (mutually exclusive with all other search parameters):
+
+        irisql: str: A raw IrisQL query string. Must begin with '# IrisQL-1.0'.
+            Sent as a raw POST body (text/plain). When set, all domain/filter params are ignored.
+            Pagination params (page_size, sort_by, position) are still supported via **kwargs.
+
+            Example:
+                api.iris_investigate(irisql='# IrisQL-1.0\\nDOMAIN CONTAINS "phishing"', page_size=50, sort_by='risk_score')
 
         """
+        if irisql is not None:
+            if domains:
+                print("Warning: irisql is set — ignoring 'domains' and other search parameters. IrisQL query takes precedence.")
+            return self._results(
+                "iris-investigate",
+                "/v1/iris-investigate/",
+                items_path=("results",),
+                irisql=irisql,
+                **kwargs,
+            )
+
         # We put search_hash in the signature definition so the CLI can see it as a valid arg
         if search_hash:
             kwargs["search_hash"] = search_hash
@@ -732,7 +781,7 @@ class API(object):
 
         filtered_results = DTResultFilter(result_set=results).by(
             [
-                filter_by_riskscore(threshold=risk_score),
+                filter_by_riskscore(threshold=risk_score_threshold),
                 filter_by_expire_date(date=younger_than_date, lookup_type="before"),
                 filter_by_expire_date(date=older_than_date, lookup_type="after"),
                 filter_by_date_updated_after(date=updated_after),

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools/base_results.py

@@ -108,6 +108,17 @@ class Results(MutableMapping, MutableSequence):
                 "iris-enrich",
                 "iris-detect-escalate-domains",
             ]:
+                if self.product == "iris-investigate" and "irisql" in self.kwargs:
+                    irisql_query = self.kwargs["irisql"]
+                    auth_keys = {"api_username", "timestamp", "signature", "api_key"}
+                    query_params = {k: v for k, v in self.kwargs.items() if k != "irisql" and k not in auth_keys}
+                    query_params.update(self.api.extra_request_params)
+                    return session.post(
+                        url=self.url,
+                        content=irisql_query,
+                        params=query_params,
+                        headers={**headers, "Content-Type": "text/plain", "X-Api-Key": self.api.key},
+                    )
                 post_data = self.kwargs.copy()
                 post_data.update(self.api.extra_request_params)
                 return session.post(url=self.url, data=post_data, headers=headers)
@@ -277,6 +288,8 @@ class Results(MutableMapping, MutableSequence):
 
     @property
     def json(self):
+        if self._data is not None:
+            return self
         self.kwargs.pop("format", None)
         return self.__class__(
             format="json",

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools/cli/api.py

@@ -230,28 +230,21 @@ class DTCLICommand:
                     description=f"Preparing results with format of {response_format}...",
                 )
 
+                if name not in ("available_api_calls",) and not getattr(response, "product", None) in RTTF_PRODUCTS_LIST:
+                    response.data()
+
                 output = cls._get_formatted_output(
                     cmd_name=name, response=response, out_format=response_format
                 )
 
-                if isinstance(out_file, _io.TextIOWrapper):
-                    progress.update(
-                        task_id,
-                        description=f"Printing the results with format of {response_format}...",
-                    )
-                    # use rich `print` command to prettify the ouput in sys.stdout
-                    if name not in ("available_api_calls",) and response.product in RTTF_PRODUCTS_LIST:
-                        for feeds in response.response():
-                            print(feeds)
-                    else:
-                        print(response)
+            if isinstance(out_file, _io.TextIOWrapper):
+                if name not in ("available_api_calls",) and response.product in RTTF_PRODUCTS_LIST:
+                    for feeds in response.response():
+                        print(feeds)
                 else:
-                    progress.update(
-                        task_id,
-                        description=f"Writing results to {out_file}",
-                    )
-                    # if it's a file then write
-                    out_file.write(output if output.endswith("\n") else output + "\n")
+                    print(output)
+            else:
+                out_file.write(output if output.endswith("\n") else output + "\n")
         except Exception as e:
             if isinstance(e, ServiceException):
                 code = typer.style(getattr(e, "code", 400), fg=typer.colors.BRIGHT_RED)

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools/cli/commands/domains.py

@@ -87,6 +87,51 @@ def domain_profile(
     DTCLICommand.run(name=c.DOMAIN_PROFILE, params=ctx.params)
 
 
+@dt_cli.command(
+    name=c.DOMAIN_HISTORY,
+    help=get_cli_helptext_by_name(command_name=c.DOMAIN_HISTORY),
+)
+def domain_history(
+    ctx: typer.Context,
+    query: str = typer.Option(..., "-q", "--query", help="The apex domain name to retrieve history for (e.g. domaintools.com)."),
+    include_fields: str = typer.Option(None, "--include-fields", help="Comma-separated list of exact field names. Only change events matching these fields appear in results. Cannot be combined with --exclude-fields. Example: ip,registrar,all_ssl"),
+    exclude_fields: str = typer.Option(None, "--exclude-fields", help="Comma-separated list of exact field names. Change events matching these fields are omitted. Cannot be combined with --include-fields. Example: all_web_trackers,all_ssl"),
+    page_size: int = typer.Option(None, "--page-size", help="Number of change events per page. Maximum is 100 (default: 100)."),
+    offset: int = typer.Option(None, "--offset", help="0-indexed starting point for pagination. Increment by page-size for each subsequent page."),
+    next: bool = typer.Option(None, "--next", help="When true, includes a next URL in the response for cursor-based pagination."),
+    parsed_whois: bool = typer.Option(None, "--parsed-whois", help="When true, includes the full parsed WHOIS record in the before/after objects of each change event."),
+    parsed_domain_rdap: bool = typer.Option(None, "--parsed-domain-rdap", help="When true, includes the full parsed Domain RDAP record in the before/after objects of each change event."),
+    user: str = typer.Option(None, "-u", "--user", help="Domaintools API Username."),
+    key: str = typer.Option(None, "-k", "--key", help="DomainTools API key"),
+    creds_file: str = typer.Option(
+        "~/.dtapi",
+        "-c",
+        "--credfile",
+        help="Optional file with API username and API key, one per line.",
+    ),
+    rate_limit: bool = typer.Option(
+        False,
+        "-l",
+        "--rate-limit",
+        help="Rate limit API calls against the API based on per minute limits.",
+    ),
+    format: str = typer.Option(
+        "json",
+        "-f",
+        "--format",
+        help="Output format in {'list', 'json', 'xml', 'html'}",
+        callback=DTCLICommand.validate_format_input,
+    ),
+    out_file: typer.FileTextWrite = typer.Option(sys.stdout, "-o", "--out-file", help="Output file (defaults to stdout)"),
+    no_verify_ssl: bool = typer.Option(
+        False,
+        "--no-verify-ssl",
+        help="Skip verification of SSL certificate when making HTTPs API calls",
+    ),
+):
+    DTCLICommand.run(name=c.DOMAIN_HISTORY, params=ctx.params)
+
+
 @dt_cli.command(
     name=c.DOMAIN_SEARCH,
     help=get_cli_helptext_by_name(command_name=c.DOMAIN_SEARCH),
@@ -666,6 +711,7 @@ def risk_evidence(
 
 __all__ = [
     "brand_monitor",
+    "domain_history",
     "domain_profile",
     "domain_search",
     "name_server_monitor",

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools/cli/commands/iris.py

@@ -23,6 +23,11 @@ def iris_investigate(
     create_date: str = typer.Option(None, "--create-date", help="The create date."),
     active: bool = typer.Option(None, "--active", help="The domains that are in active state"),
     search_hash: str = typer.Option(None, "--search-hash", help="The search hash to use"),
+    irisql: str = typer.Option(
+        None,
+        "--irisql",
+        help="IrisQL query string (must begin with '# IrisQL-1.0'). Mutually exclusive with domain/filter params. Pagination kwargs (--page-size, --sort-by, --position) are still supported.",
+    ),
     src_file: str = typer.Option(
         None,
         "-s",

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools/cli/constants.py

@@ -4,6 +4,7 @@ AVAILABLE_API_CALLS = "available_api_calls"
 
 # domains
 BRAND_MONITOR = "brand_monitor"
+DOMAIN_HISTORY = "domain_history"
 DOMAIN_PROFILE = "domain_profile"
 DOMAIN_SEARCH = "domain_search"
 HOSTING_HISTORY = "hosting_history"

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools/cli/utils.py

@@ -35,6 +35,7 @@ _command_help_mapper = {
     c.IRIS_INVESTIGATE: _iris_investigate_helptext(),
     c.IRIS_ENRICH: "Returns back enriched data related to the specified domains using our Iris Enrich service.",
     c.BRAND_MONITOR: "Pass in one or more terms as a list or separated by the pipe character ( | )",
+    c.DOMAIN_HISTORY: "Returns the history of changes for a given domain name.",
     c.DOMAIN_PROFILE: "Returns a profile for the specified domain name",
     c.DOMAIN_SEARCH: """Each term in the query string must be at least three characters long. Pass in a list or use spaces to separate multiple terms.""",
     c.HOSTING_HISTORY: "Returns the hosting history from the given domain name.",

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools/decorators.py

@@ -51,9 +51,7 @@ def api_endpoint(spec_name: str, path: str, methods: Union[str, List[str]]):
 
             if "domains" in arguments.keys():
                 domains = arguments.pop("domains")
-                arguments["domain"] = (
-                    ",".join(domains) if isinstance(domains, (list, tuple)) else domains
-                )
+                arguments["domain"] = ",".join(domains) if isinstance(domains, (list, tuple)) else domains
 
             if spec:
                 # Determine which HTTP method is currently being executed.
@@ -61,6 +59,8 @@ def api_endpoint(spec_name: str, path: str, methods: Union[str, List[str]]):
                 # Otherwise, default to the first method defined in the decorator.
                 current_method = kwargs.get("method", normalized_methods[0])
 
+                filtered_arguments = {k: v for k, v in arguments.items() if v is not None}
+
                 # Run Validation
                 # This will raise a ValueError and stop execution if validation fails.
                 try:
@@ -68,7 +68,7 @@ def api_endpoint(spec_name: str, path: str, methods: Union[str, List[str]]):
                         spec=spec,
                         path=path,
                         method=current_method,
-                        parameters=arguments,
+                        parameters=filtered_arguments,
                     )
                 except ValueError as e:
                     print(f"[Validation Error] {e}")

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0/domaintools_api_test_upload.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domaintools_api_test_upload
-Version: 2.7.4
+Version: 2.8.0
 Summary: DomainTools Official Python API
 Author-email: DomainTools <integrations@domaintools.com>
 License: The MIT License (MIT)
@@ -50,6 +50,10 @@ Requires-Dist: typer
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: mock; extra == "test"
+Requires-Dist: vcrpy; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: yarl; extra == "test"
 Dynamic: license-file
 
 ![domaintools](https://github.com/DomainTools/python_api/raw/main/artwork/logo.png)
@@ -199,6 +203,32 @@ You can get the status code of a response outside of exception handling by doing
 api.domain_profile('google.com').status == 200
 ```
 
+IrisQL
+===================
+
+IrisQL is a query language for Iris Investigate that lets you express complex, multi-field searches in a single request. Pass the query as a raw string via the `irisql` parameter. The query must begin with `# IrisQL-1.0`.
+
+```python
+query = """# IrisQL-1.0
+DOMAIN CONTAINS "phishing"
+AND
+RISK_SCORE GREATER_THAN 85
+"""
+
+results = api.iris_investigate(irisql=query)
+print(results["results_count"])
+for domain in results:
+    print(domain["domain"])
+```
+
+Pagination parameters (`page_size`, `sort_by`, `position`) are supported alongside IrisQL via `**kwargs`:
+
+```python
+results = api.iris_investigate(irisql=query, page_size=50, sort_by="risk_score", position=0)
+```
+
+When `irisql` is set, any domain or filter parameters passed alongside it are silently ignored. IrisQL uses header-based authentication (`X-Api-Key`) automatically.
+
 Using the API Asynchronously
 ===================
 
@@ -255,6 +285,18 @@ Optionally, you can specify the desired format (html, xml, json, or list) of the
 domaintools domain_search google --max_length 10 -u $TEST_USER -k $TEST_KEY -f html
 ```
 
+IrisQL queries are supported via the `--irisql` flag on `iris_investigate`. The query must begin with `# IrisQL-1.0` on its own line:
+
+```bash
+domaintools iris_investigate --irisql $'# IrisQL-1.0\nDOMAIN CONTAINS "phishing"' -u $TEST_USER -k $TEST_KEY
+```
+
+Pagination parameters can be passed alongside the IrisQL query:
+
+```bash
+domaintools iris_investigate --irisql $'# IrisQL-1.0\nDOMAIN CONTAINS "phishing"' --page-size 50 --sort-by risk_score -u $TEST_USER -k $TEST_KEY
+```
+
 To avoid having to type in your API key repeatedly, you can specify them in `~/.dtapi` separated by a new line:
 
 ```bash
@@ -343,12 +385,11 @@ To add more e2e tests, put these in the `../tests/e2e` folder.
         source venv/bin/activate
     ```
 
-- Install dependencies.
+- Install dependencies (with test extras):
     ```bash
-        pip install -r requirements/development.txt
+        pip install -e ".[test]"
     ```
-
-- From the python_api project root directory, install the package.
+    Or without test dependencies:
     ```bash
         pip install -e .
     ```

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools_api_test_upload.egg-info/requires.txt

@@ -6,3 +6,7 @@ typer
 [test]
 pytest
 mock
+vcrpy
+pytest-asyncio
+pytest-cov
+yarl

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/domaintools_async/__init__.py

@@ -46,9 +46,21 @@ class AsyncResults(Results):
         session_params_and_headers = self._get_session_params_and_headers()
         headers = session_params_and_headers.get("headers")
         if self.product in ["iris-investigate", "iris-enrich", "iris-detect-escalate-domains"]:
-            post_data = self.kwargs.copy()
-            post_data.update(self.api.extra_request_params)
-            results = await session.post(url=self.url, data=post_data, headers=headers)
+            if self.product == "iris-investigate" and "irisql" in self.kwargs:
+                irisql_query = self.kwargs["irisql"]
+                auth_keys = {"api_username", "timestamp", "signature", "api_key"}
+                query_params = {k: v for k, v in self.kwargs.items() if k != "irisql" and k not in auth_keys}
+                query_params.update(self.api.extra_request_params)
+                results = await session.post(
+                    url=self.url,
+                    content=irisql_query,
+                    params=query_params,
+                    headers={**headers, "Content-Type": "text/plain", "X-Api-Key": self.api.key},
+                )
+            else:
+                post_data = self.kwargs.copy()
+                post_data.update(self.api.extra_request_params)
+                results = await session.post(url=self.url, data=post_data, headers=headers)
         elif self.product in ["iris-detect-manage-watchlist-domains"]:
             patch_data = self.kwargs.copy()
             patch_data.update(self.api.extra_request_params, headers=headers)

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/pyproject.toml

@@ -41,7 +41,7 @@ Homepage = "https://github.com/domaintools/python_api"
 domaintools = "domaintools.cli:run"
 
 [project.optional-dependencies]
-test = ["pytest", "mock"]
+test = ["pytest", "mock", "vcrpy", "pytest-asyncio", "pytest-cov", "yarl"]
 
 [tool.setuptools]
 packages = [
@@ -58,5 +58,8 @@ domaintools = ["specs/*.yaml"]
 [tool.setuptools.dynamic]
 version = { "file" = "VERSION" }
 
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
 [tool.black]
 line-length = 110

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/tests/test_api.py

@@ -1,6 +1,7 @@
 """Tests the Python interface for DomainTools APIs"""
 
 from os import environ
+from unittest.mock import MagicMock, patch, call
 
 import json
 import pytest
@@ -10,6 +11,7 @@ from inspect import isgenerator
 
 from domaintools import API, exceptions
 from tests.settings import api, feeds_api, vcr
+from tests.responses.iris_investigate_data import domaintools as iris_investigate_fixture
 
 
 @vcr.use_cassette
@@ -68,6 +70,22 @@ def test_domain_profile():
         assert "ip_address" in history
 
 
+@vcr.use_cassette
+def test_domain_history():
+    api_call = api.domain_history("chat.com", include_fields="registrar")
+    with api_call as result:
+        assert "domain" in result
+        assert "count" in result
+        assert "registration_source" in result
+        assert "changes" in result
+
+        for change in api_call:
+            assert "timestamp" in change
+            assert "field" in change
+            assert "before" in change
+            assert "after" in change
+
+
 @vcr.use_cassette
 def test_domain_search():
     api_call = api.domain_search("google")
@@ -143,7 +161,6 @@ def test_name_server_monitor():
 def test_parsed_whois():
     api_call = api.parsed_whois("google.com")
     with api_call as result:
-        assert "registrant" in result
         assert "registration" in result
         assert "name_servers" in result
         assert "whois" in result
@@ -291,8 +308,6 @@ def test_whois():
         assert "whois" in whois
         assert "record_source" in whois
 
-        assert "abusecomplaints@markmonitor.com" in api_call.emails()
-
 
 @vcr.use_cassette
 def test_whois_history():
@@ -450,6 +465,73 @@ def test_iris_investigate():
         assert result["domain"] in ["amazon.com", "google.com"]
 
 
+def test_iris_investigate_irisql_calls_results_with_irisql():
+    query = "# IrisQL-1.0\nDOMAIN CONTAINS \"phishing\""
+    with patch.object(api, "_results") as mock_results:
+        api.iris_investigate(irisql=query)
+        mock_results.assert_called_once_with(
+            "iris-investigate",
+            "/v1/iris-investigate/",
+            items_path=("results",),
+            irisql=query,
+        )
+
+
+def test_iris_investigate_irisql_with_pagination_kwargs():
+    query = "# IrisQL-1.0\nDOMAIN CONTAINS \"phishing\""
+    with patch.object(api, "_results") as mock_results:
+        api.iris_investigate(irisql=query, page_size=50, sort_by="risk_score", position=0)
+        mock_results.assert_called_once_with(
+            "iris-investigate",
+            "/v1/iris-investigate/",
+            items_path=("results",),
+            irisql=query,
+            page_size=50,
+            sort_by="risk_score",
+            position=0,
+        )
+
+
+def test_iris_investigate_irisql_warns_and_ignores_domains(capsys):
+    query = "# IrisQL-1.0\nDOMAIN CONTAINS \"phishing\""
+    with patch.object(api, "_results"):
+        api.iris_investigate(irisql=query, domains=["google.com"])
+    captured = capsys.readouterr()
+    assert "Warning" in captured.out
+    assert "irisql" in captured.out
+
+
+def test_iris_investigate_irisql_does_not_require_other_params():
+    query = "# IrisQL-1.0\nDOMAIN CONTAINS \"phishing\""
+    with patch.object(api, "_results"):
+        api.iris_investigate(irisql=query)
+
+
+def test_iris_investigate_irisql_request_uses_raw_body():
+    query = "# IrisQL-1.0\nDOMAIN CONTAINS \"phishing\""
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.json.return_value = {"response": {"results": [], "results_count": 0}}
+
+    with patch("domaintools.base_results.Client") as mock_client:
+        mock_session = MagicMock()
+        mock_client.return_value.__enter__.return_value = mock_session
+        mock_session.post.return_value = mock_response
+
+        result = api.iris_investigate(irisql=query)
+        result.data()
+
+        _, kwargs = mock_session.post.call_args
+        assert kwargs.get("content") == query
+        assert "data" not in kwargs
+        assert kwargs.get("headers", {}).get("Content-Type") == "text/plain"
+        assert kwargs.get("headers", {}).get("X-Api-Key") == api.key
+        for auth_key in ("api_username", "timestamp", "signature", "api_key"):
+            assert auth_key not in kwargs.get("params", {})
+
+
+
+
 @vcr.use_cassette
 def test_iris_detect_monitors():
     with pytest.raises(ValueError):
@@ -476,7 +558,7 @@ def test_iris_detect_watched_domains():
     detect_results = api.iris_detect_watched_domains(
         monitor_id="nAwmQg2pqg", sort=["risk_score"], order="desc"
     )
-    assert len(detect_results["watchlist_domains"]) == 3
+    assert len(detect_results["watchlist_domains"]) == 5
 
     detect_results = api.iris_detect_watched_domains(escalation_types="blocked")
     assert detect_results["count"] == 1

domaintools_api_test_upload-2.8.0/tests/test_async.py

@@ -0,0 +1,91 @@
+"""Tests async interaction support for DomainTools APIs"""
+
+import asyncio
+import pytest
+from unittest.mock import MagicMock, AsyncMock, patch
+
+from tests.settings import api, vcr
+
+
+@vcr.use_cassette
+@pytest.mark.asyncio
+async def test_async_iteration():
+    results = await api.domain_search("google")
+    assert results
+
+    list_of_domains = []
+    for domain in results:
+        list_of_domains += domain
+
+    for domain in list_of_domains:
+        assert type(domain) == str
+
+
+@vcr.use_cassette
+@pytest.mark.asyncio
+async def test_async_context_manager():
+    results = await api.domain_search("google")
+    assert results
+
+
+@vcr.use_cassette
+@pytest.mark.asyncio
+async def test_async_simple_await():
+    results = await api.domain_search("google")
+    assert results
+
+
+@vcr.use_cassette
+@pytest.mark.asyncio
+async def test_async_simple_await_post():
+    investigation_results = await api.iris_investigate(domains=["amazon.com", "google.com"])
+    assert investigation_results["results_count"]
+    for result in investigation_results:
+        assert result["domain"] in ["amazon.com", "google.com"]
+
+
+@vcr.use_cassette
+@pytest.mark.asyncio
+async def test_async_simple_await_patch():
+    detect_results = await api.iris_detect_manage_watchlist_domains(watchlist_domain_ids=["gae08rdVWG"], state="watched")
+    assert detect_results["watchlist_domains"][0]["state"] == "watched"
+
+
+@pytest.mark.asyncio
+async def test_async_irisql_uses_raw_body():
+    query = "# IrisQL-1.0\nDOMAIN CONTAINS \"phishing\""
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.json.return_value = {"response": {"results": [], "results_count": 0}}
+
+    with patch("domaintools_async.AsyncClient") as mock_client:
+        mock_session = AsyncMock()
+        mock_client.return_value.__aenter__.return_value = mock_session
+        mock_session.post.return_value = mock_response
+
+        result = await api.iris_investigate(irisql=query)
+
+        _, kwargs = mock_session.post.call_args
+        assert kwargs.get("content") == query
+        assert "data" not in kwargs
+        assert kwargs.get("headers", {}).get("Content-Type") == "text/plain"
+
+
+@pytest.mark.asyncio
+async def test_async_irisql_with_pagination_kwargs():
+    query = "# IrisQL-1.0\nDOMAIN CONTAINS \"phishing\""
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.json.return_value = {"response": {"results": [], "results_count": 0}}
+
+    with patch("domaintools_async.AsyncClient") as mock_client:
+        mock_session = AsyncMock()
+        mock_client.return_value.__aenter__.return_value = mock_session
+        mock_session.post.return_value = mock_response
+
+        result = await api.iris_investigate(irisql=query, page_size=50, sort_by="risk_score")
+
+        _, kwargs = mock_session.post.call_args
+        assert kwargs.get("content") == query
+        assert "page_size" in kwargs.get("params", {})
+        assert "sort_by" in kwargs.get("params", {})

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/tests/test_cli.py

@@ -27,9 +27,16 @@ def test_valid_command():
 
 def test_invalid_command():
     result = runner.invoke(dt_cli, ["test_invalid_command"])
-    assert "No such command 'test_invalid_command'." in result.stdout
+    assert "No such command 'test_invalid_command'." in result.output
 
 
 def test_no_creds_file_not_found():
     result = runner.invoke(dt_cli, ["iris_investigate", "--domain", "domaintools.com"])
     assert "No such file or directory" in result.stdout
+
+
+def test_iris_investigate_irisql_flag_accepted():
+    result = runner.invoke(dt_cli, ["iris_investigate", "--irisql", "# IrisQL-1.0\nDOMAIN CONTAINS \"phishing\"", "--help"])
+    assert "--irisql" in result.stdout
+
+

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/tests/test_decorators.py

@@ -217,3 +217,35 @@ class TestApiEndpointDecorator:
             call_kwargs = mock_validate.call_args[1]
 
             assert call_kwargs.get("parameters") == {"name": "test-name"}
+
+    def test_none_arguments_are_filtered_before_validation(self, mock_client):
+        """
+        Test that parameters with None values are excluded from the arguments
+        passed to the validator.
+        """
+
+        @api_endpoint(spec_name="v1", path="/users", methods="POST")
+        def create_user(name=None, status=None):
+            return "Success"
+
+        with patch("domaintools.request_validator.RequestValidator.validate") as mock_validate:
+            create_user(mock_client, name="Alice", status=None)
+
+            call_kwargs = mock_validate.call_args[1]
+            assert call_kwargs.get("parameters") == {"name": "Alice"}
+            assert "status" not in call_kwargs.get("parameters", {})
+
+    def test_all_none_arguments_passes_empty_parameters(self, mock_client):
+        """
+        Test that when all arguments are None, an empty dict is passed to the validator.
+        """
+
+        @api_endpoint(spec_name="v1", path="/users", methods="POST")
+        def create_user(name=None, body=None):
+            return "Success"
+
+        with patch("domaintools.request_validator.RequestValidator.validate") as mock_validate:
+            create_user(mock_client, name=None, body=None)
+
+            call_kwargs = mock_validate.call_args[1]
+            assert call_kwargs.get("parameters") == {}

{domaintools_api_test_upload-2.7.4 → domaintools_api_test_upload-2.8.0}/tests/test_filters.py

@@ -16,20 +16,17 @@ class DTFiltersTest(unittest.TestCase):
         domaintools_iris_result = iris_investigate_data.domaintools()
         int_chase_iris_result = iris_investigate_data.int_chase()
 
-        test_results = {
-            "results": domaintools_iris_result["results"]
-            + int_chase_iris_result["results"]
-        }
+        test_results = {"results": domaintools_iris_result["results"] + int_chase_iris_result["results"]}
 
         self.dt_res_filter = DTResultFilter(result_set=test_results)
 
     def test_filter_by_riskscore(self):
         """Test domaintools filter by riskcore"""
-        risk_score = 69
+        risk_score_threshold = 69
 
         result = self.dt_res_filter.by(
             [
-                filter_by_riskscore(threshold=risk_score),
+                filter_by_riskscore(threshold=risk_score_threshold),
             ]
         )
 
@@ -77,9 +74,7 @@ class DTFiltersTest(unittest.TestCase):
 
         results = self.dt_res_filter.by(
             [
-                filter_by_field(
-                    field=include_domains_with_missing_field, filter_type="include"
-                ),
+                filter_by_field(field=include_domains_with_missing_field, filter_type="include"),
             ]
         )
 
@@ -90,9 +85,7 @@ class DTFiltersTest(unittest.TestCase):
 
         results = self.dt_res_filter.by(
             [
-                filter_by_field(
-                    field=exclude_domains_with_missing_field, filter_type="exclude"
-                ),
+                filter_by_field(field=exclude_domains_with_missing_field, filter_type="exclude"),
             ]
         )
 

domaintools_api_test_upload-2.7.4/VERSION

@@ -1 +0,0 @@
-2.7.4

domaintools_api_test_upload-2.7.4/tests/test_async.py

@@ -1,50 +0,0 @@
-"""Tests async interaction support for DomainTools APIs"""
-
-import asyncio
-import pytest
-
-from tests.settings import api, vcr
-
-
-@vcr.use_cassette
-@pytest.mark.asyncio
-async def test_async_iteration():
-    results = await api.domain_search("google")
-    assert results
-
-    list_of_domains = []
-    for domain in results:
-        list_of_domains += domain
-
-    for domain in list_of_domains:
-        assert type(domain) == str
-
-
-@vcr.use_cassette
-@pytest.mark.asyncio
-async def test_async_context_manager():
-    results = await api.domain_search("google")
-    assert results
-
-
-@vcr.use_cassette
-@pytest.mark.asyncio
-async def test_async_simple_await():
-    results = await api.domain_search("google")
-    assert results
-
-
-@vcr.use_cassette
-@pytest.mark.asyncio
-async def test_async_simple_await_post():
-    investigation_results = await api.iris_investigate(domains=["amazon.com", "google.com"])
-    assert investigation_results["results_count"]
-    for result in investigation_results:
-        assert result["domain"] in ["amazon.com", "google.com"]
-
-
-@vcr.use_cassette
-@pytest.mark.asyncio
-async def test_async_simple_await_patch():
-    detect_results = await api.iris_detect_manage_watchlist_domains(watchlist_domain_ids=["gae08rdVWG"], state="watched")
-    assert detect_results["watchlist_domains"][0]["state"] == "watched"