Update CHANGELOG.md; add sample code snippet for newly added ouput filtering in api wrapper

Author: briluza

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+### 2.0.0
+- [NEW] Modernize package - migrate package settings to pyproject.toml
+- [NEW] Migrate CLI wrapper to use `typer` library. (CLI comes now with new interface.)
+- [NEW] Add support for making `api_url` and `api_port` configurable.
+- [NEW] Add `--source-file` or `-s` cli parameter in `iris_investigate` and `iris_enrich` command to support file input instead of long comma-separated domains when typing the domains. Max of **100** domains in a single file.
+- [NEW] Add output filtering in `iris_investigate` and `iris_enrich` function in API wrapper (see sample code in `examples/iris_investigate_filter_output.py` folder). Changes includes the ff:
+    - Filtering of results "**>=**" to a given `risk_score`.
+    - Filtering of results based on `expiration_date` field. (`younger_than_date`, `older_than_date`)
+    - Filtering of results based on `updated_after` field.
+    - Filtering of results based on a missing field. (include_domains_with_missing_field` or `exclude_domains_with_missing_field`).
+- [NEW] Add support on removing/stripping colon in when passing a value in `--ssl_hash` in `iris_investigate` cli command.
+- [UPDATE] replace use of upcoming deprecated `datetime.uctnow()` to `timezone.utc`
+- [UPDATE] Improve help text in CLI commands.
+- [UPDATE] Remove `dateparser` dependency and use native python `datetime` library.
+- [FIX] Fix error in `-o` or `--out-file` parameter.
+
+
 ### 1.0.1
 
 - Adds support for the hourly query limit on the Account API endpoint

examples/iris_investigate_filter_output.py

@@ -0,0 +1,108 @@
+from domaintools import API
+
+
+dt_api = API(USER_NAME, KEY)
+domains = "int-chase.com, google.com"
+
+
+def sample_filter_by_risk_score():
+    """
+    Sample code snippet on how to use the output filtering by a given riskscore
+    """
+    response = dt_api.iris_investigate(domains=domains, risk_score=68)
+    output_domains = [
+        (result.get("domain"), result.get("domain_risk", {}).get("risk_score"))
+        for result in response.get("results") or []
+    ]
+    # this will output [('int-chase.com', 71)], assuming that this domain has a >= to the given riskscore
+    print(f"Filter by `risk_score` result: {output_domains}")
+
+
+def sample_filter_by_younger_than_date():
+    """
+    Sample code snippet on how to use the output filtering by younger_than_date.
+    The field being used in this filter is the `expiration_date`.
+    """
+    response = dt_api.iris_investigate(domains=domains, younger_than_date="2024-02-24")
+
+    output_domains = [
+        (result.get("domain"), result.get("expiration_date"))
+        for result in response.get("results") or []
+    ]
+    # this will output [('google.com', {'value': '2028-09-14', 'count': 9972})],
+    # assuming that this domain has a expiration_date <= to the given date.
+    print(f"Filter by `younger_than_date` result: {output_domains}")
+
+
+def sample_filter_by_older_than_date():
+    """
+    Sample code snippet on how to use the output filtering by older_than_date.
+    The field being used in this filter is the `expiration_date`.
+    """
+    response = dt_api.iris_investigate(domains=domains, older_than_date="2024-02-24")
+
+    output_domains = [
+        (result.get("domain"), result.get("expiration_date"))
+        for result in response.get("results") or []
+    ]
+    # this will output  [('int-chase.com', {'value': '2021-10-13', 'count': 118259})],
+    # assuming that this domain has a expiration_date <= to the given date.
+    print(f"Filter by `older_than_date` result: {output_domains}")
+
+
+def sample_filter_by_updated_after():
+    """
+    Sample code snippet on how to use the output filtering by updated_after.
+    The field being used in this filter is the `data_updated_timestamp`.
+    """
+    response = dt_api.iris_investigate(domains=domains, updated_after="2024-02-24")
+
+    output_domains = [
+        (result.get("domain"), result.get("data_updated_timestamp"))
+        for result in response.get("results") or []
+    ]
+    # this will output  [('google.com', {'value': '2028-09-14', 'count': 9972})],
+    # assuming that this domain has a data_updated_timestamp >= to the given `updated_after` date.
+    print(f"Filter by `updated_after` result: {output_domains}")
+
+
+def sample_filter_by_include_domains_with_missing_field():
+    """
+    Sample code snippet on how to use the output filtering to include
+    the domain even the given field is missing or empty in the result set.
+    """
+    response = dt_api.iris_investigate(
+        domains=domains, include_domains_with_missing_field="popularity_rank"
+    )
+
+    # this will output  [('google.com', 1), ('int-chase.com', '')]
+    output_domains = [
+        (result.get("domain"), result.get("popularity_rank"))
+        for result in response.get("results") or []
+    ]
+    print(f"Filter by `include_domains_with_missing_field` result: {output_domains}")
+
+
+def sample_filter_by_exclude_domains_with_missing_field():
+    """
+    Sample code snippet on how to use the output filtering to exclude
+    the domain even the given field is missing or empty in the result set.
+    """
+    response = dt_api.iris_investigate(
+        domains=domains, exclude_domains_with_missing_field="popularity_rank"
+    )
+
+    # this will only output [('google.com', 1)] as the popularity rank in other domain is missing/empty
+    output_domains = [
+        (result.get("domain"), result.get("popularity_rank"))
+        for result in response.get("results") or []
+    ]
+    print(f"Filter by `exclude_domains_with_missing_field` result: {output_domains}")
+
+
+sample_filter_by_risk_score()
+sample_filter_by_younger_than_date()
+sample_filter_by_older_than_date()
+sample_filter_by_updated_after()
+sample_filter_by_include_domains_with_missing_field()
+sample_filter_by_exclude_domains_with_missing_field()