Handle deprecation of APIs and attributes (#1170)

* Add deprecation warnings

Add some mechanism for deprecated APIs and attributes.

* Deprecated attrs

* Add a note in APIs too

* Minor doc formatting.

* pre-commit fixes

Co-authored-by: ci.datadog-api-spec <[email protected]>

Author: therve

.generator/src/generator/formatter.py

@@ -96,7 +96,7 @@ def header(self, text, level, raw=None):
 
 
 def docstring(text):
-    return m2r2.convert(text.replace("\\n", "\\\\n"), renderer=CustomRenderer())[1:-1].replace("\\ ", " ").replace("\\`", "\\\\`")
+    return m2r2.convert(text.replace("\\n", "\\\\n"), renderer=CustomRenderer())[1:-1].replace("\\ ", " ").replace("\\`", "\\\\`").replace("\n\n\n", "\n\n")
 
 
 def _merge_imports(a, b):

.generator/src/generator/templates/api.j2

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import collections
 from typing import Any, Dict, List, Union
+import warnings
 
 from {{ package }}.api_client import ApiClient, Endpoint as _Endpoint
 from {{ package }}.model_utils import (
@@ -141,7 +142,7 @@ class {{ classname }}:
 {%- for path, method, operation in operations|sort(attribute="2.operationId") %}
 {%- set returnType = operation|return_type %}
     def {{ operation.operationId|safe_snake_case }}(self, {% for name, parameter in operation|parameters if parameter.required %}{{name|attribute_name}}: {{ get_type_for_parameter(parameter, typing=True) }}, {% endfor %}{% for name, parameter in operation|parameters if not parameter.required %}{% if loop.first %}*, {% endif %}{{name|attribute_name}}: Union[{{ get_type_for_parameter(parameter, typing=True) }}, UnsetType]=unset, {% endfor %}) -> {% if returnType %}{{ returnType.replace("[", "List[") }}{% else %}None{% endif %}:
-        """{{ operation.summary|indent(8) }}.
+        """{{ operation.summary|indent(8) }}.{% if operation.deprecated %} **Deprecated**.{% endif %}
 {% if operation.description %}
         {{ operation.description|docstring|indent(8) }}
 {% endif %}
@@ -168,6 +169,9 @@ class {{ classname }}:
         kwargs["{{ name|attribute_name }}"] = {{ name|attribute_name }}
 {%- endif %}
 {% endfor %}
+{%- if operation.deprecated %}
+        warnings.warn("{{ operation.operationId|safe_snake_case }} is deprecated", DeprecationWarning, stacklevel=2)
+{%- endif %}
         return self._{{ operation.operationId|safe_snake_case }}_endpoint.call_with_http_info(**kwargs)
     {%- if operation["x-pagination"] %}
     {%- set pagination = operation["x-pagination"] %}

.generator/src/generator/templates/model_generic.j2

@@ -107,7 +107,7 @@ class {{ name }}(ModelNormal):
         {{ model.description|docstring|indent(8) }}
 {%- for attr, definition in model.get("properties", {}).items() %}
 {# keep new line #}
-        :param {{ attr|attribute_name }}: {{ definition.description|docstring|indent(12) }}
+        :param {{ attr|attribute_name }}: {{ definition.description|docstring|indent(12) }}{% if definition.deprecated %} **Deprecated**.{% endif %}
         :type {{ attr|attribute_name }}: {{ get_type_for_attribute(model, attr, current_name=name) }}{% if definition.nullable %}, none_type{% endif %}{% if attr not in model.get("required", []) %}, optional{% endif %}
 {%- endfor %}
         """

src/datadog_api_client/v1/api/aws_logs_integration_api.py

@@ -175,7 +175,6 @@ def check_aws_logs_lambda_async(
         is the same as for Enable an AWS service log collection. Subsequent requests will always repeat the above, so this
         endpoint can be polled intermittently instead of blocking.
 
-
         * Returns a status of 'created' when it's checking if the Lambda exists in the account.
         * Returns a status of 'waiting' while checking.
         * Returns a status of 'checked and ok' if the Lambda exists.
@@ -201,7 +200,6 @@ def check_aws_logs_services_async(
         Done async, so can be repeatedly polled in a non-blocking fashion until
         the async request completes.
 
-
         * Returns a status of ``created`` when it's checking if the permissions exists
           in the AWS account.
         * Returns a status of ``waiting`` while checking.

src/datadog_api_client/v1/api/events_api.py

@@ -196,7 +196,6 @@ def list_events(
 
         **Notes** :
 
-
         *
           If the event you’re querying contains markdown formatting of any kind,
           you may see characters such as ``%`` , ``\\`` , ``n`` in your output.

src/datadog_api_client/v1/api/logs_api.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 from typing import Any, Dict, Union
+import warnings
 
 from datadog_api_client.api_client import ApiClient, Endpoint as _Endpoint
 from datadog_api_client.model_utils import (
@@ -158,18 +159,16 @@ def submit_log(
         content_encoding: Union[ContentEncoding, UnsetType] = unset,
         ddtags: Union[str, UnsetType] = unset,
     ) -> dict:
-        """Send logs.
+        """Send logs. **Deprecated**.
 
         Send your logs to your Datadog platform over HTTP. Limits per HTTP request are:
 
-
         * Maximum content size per payload (uncompressed): 5MB
         * Maximum size for a single log: 1MB
         * Maximum array size if sending multiple logs in an array: 1000 entries
 
         Any log exceeding 1MB is accepted and truncated by Datadog:
 
-
         * For a single log request, the API truncates the log at 1MB and returns a 2xx.
         * For a multi-logs request, the API processes all logs, truncates only logs larger than 1MB, and returns a 2xx.
 
@@ -178,7 +177,6 @@ def submit_log(
 
         The status codes answered by the HTTP API are:
 
-
         * 200: OK
         * 400: Bad request (likely an issue in the payload formatting)
         * 403: Permission issue (likely using an invalid API Key)
@@ -202,4 +200,5 @@ def submit_log(
 
         kwargs["body"] = body
 
+        warnings.warn("submit_log is deprecated", DeprecationWarning, stacklevel=2)
         return self._submit_log_endpoint.call_with_http_info(**kwargs)

src/datadog_api_client/v1/api/logs_pipelines_api.py

@@ -16,7 +16,6 @@ class LogsPipelinesApi:
     Pipelines and processors operate on incoming logs, parsing
     and transforming them into structured attributes for easier querying.
 
-
     *
       See the `pipelines configuration page <https://app.datadoghq.com/logs/pipelines>`_
       for a list of the pipelines and processors currently configured in web UI.

src/datadog_api_client/v1/api/metrics_api.py

@@ -25,7 +25,6 @@ class MetricsApi:
     """
     The metrics endpoint allows you to:
 
-
     * Post metrics data so it can be graphed on Datadog’s dashboards
     * Query metrics from any time period
     * Modify tag configurations for metrics
@@ -374,7 +373,6 @@ def submit_metrics(
 
         If you’re submitting metrics directly to the Datadog API without using DogStatsD, expect:
 
-
         * 64 bits for the timestamp
         * 64 bits for the value
         * 40 bytes for the metric names

src/datadog_api_client/v1/api/monitors_api.py

@@ -382,7 +382,6 @@ def create_monitor(
 
         The type of monitor chosen from:
 
-
         * anomaly: ``query alert``
         * APM: ``query alert`` or ``trace-analytics alert``
         * composite: ``composite``
@@ -410,7 +409,6 @@ def create_monitor(
 
         Example: ``time_aggr(time_window):space_aggr:metric{tags} [by {key}] operator #``
 
-
         * ``time_aggr`` : avg, sum, max, min, change, or pct_change
         * ``time_window`` : ``last_#m`` (with ``#`` between 1 and 10080 depending on the monitor type) or ``last_#h`` (with ``#`` between 1 and 168 depending on the monitor type) or ``last_1d`` , or ``last_1w``
         * ``space_aggr`` : avg, sum, min, or max
@@ -422,7 +420,6 @@ def create_monitor(
         If you are using the ``_change_`` or ``_pct_change_`` time aggregator, instead use ``change_aggr(time_aggr(time_window),
         timeshift):space_aggr:metric{tags} [by {key}] operator #`` with:
 
-
         * ``change_aggr`` change, pct_change
         * ``time_aggr`` avg, sum, max, min `Learn more <https://docs.datadoghq.com/monitors/create/types/#define-the-conditions>`_
         * ``time_window`` last_#m (between 1 and 2880 depending on the monitor type), last_#h (between 1 and 48 depending on the monitor type), or last_#d (1 or 2)
@@ -435,7 +432,6 @@ def create_monitor(
 
         Example: ``"check".over(tags).last(count).by(group).count_by_status()``
 
-
         * ``check`` name of the check, for example ``datadog.agent.up``
         * ``tags`` one or more quoted tags (comma-separated), or "*". for example: ``.over("env:prod", "role:db")`` ; ``over`` cannot be blank.
         * ``count`` must be at greater than or equal to your max threshold (defined in the ``options`` ). It is limited to 100.
@@ -447,7 +443,6 @@ def create_monitor(
 
         Example: ``events('sources:nagios status:error,warning priority:normal tags: "string query"').rollup("count").last("1h")"``
 
-
         * ``event`` , the event query string:
         * ``string_query`` free text query to match against event title and text.
         * ``sources`` event sources (comma-separated).
@@ -465,7 +460,6 @@ def create_monitor(
 
         Example: ``events(query).rollup(rollup_method[, measure]).last(time_window) operator #``
 
-
         * ``query`` The search query - following the `Log search syntax <https://docs.datadoghq.com/logs/search_syntax/>`_.
         * ``rollup_method`` The stats roll-up method - supports ``count`` , ``avg`` and ``cardinality``.
         * ``measure`` For ``avg`` and cardinality ``rollup_method`` - specify the measure or the facet name you want to use.
@@ -477,7 +471,6 @@ def create_monitor(
 
         Example: ``processes(search).over(tags).rollup('count').last(timeframe) operator #``
 
-
         * ``search`` free text search string for querying processes.
           Matching processes match results on the `Live Processes <https://docs.datadoghq.com/infrastructure/process/?tab=linuxwindows>`_ page.
         * ``tags`` one or more tags (comma-separated)
@@ -489,7 +482,6 @@ def create_monitor(
 
         Example: ``logs(query).index(index_name).rollup(rollup_method[, measure]).last(time_window) operator #``
 
-
         * ``query`` The search query - following the `Log search syntax <https://docs.datadoghq.com/logs/search_syntax/>`_.
         * ``index_name`` For multi-index organizations, the log index in which the request is performed.
         * ``rollup_method`` The stats roll-up method - supports ``count`` , ``avg`` and ``cardinality``.
@@ -502,7 +494,6 @@ def create_monitor(
 
         Example: ``12345 && 67890`` , where ``12345`` and ``67890`` are the IDs of non-composite monitors
 
-
         * ``name`` [ *required* , *default* = **dynamic, based on query** ]: The name of the alert.
         * ``message`` [ *required* , *default* = **dynamic, based on query** ]: A message to include with notifications for this monitor.
           Email notifications can be sent to specific users by using the same '@username' notation as events.
@@ -514,7 +505,6 @@ def create_monitor(
 
         Example: ``error_budget("slo_id").over("time_window") operator #``
 
-
         * ``slo_id`` : The alphanumeric SLO ID of the SLO you are configuring the alert for.
         * `time_window`: The time window of the SLO target you wish to alert on. Valid options: ``7d`` , ``30d`` , ``90d``.
         * ``operator`` : ``>=`` or ``>``
@@ -523,7 +513,6 @@ def create_monitor(
 
         Example: ``audits(query).rollup(rollup_method[, measure]).last(time_window) operator #``
 
-
         * ``query`` The search query - following the `Log search syntax <https://docs.datadoghq.com/logs/search_syntax/>`_.
         * ``rollup_method`` The stats roll-up method - supports ``count`` , ``avg`` and ``cardinality``.
         * ``measure`` For ``avg`` and cardinality ``rollup_method`` - specify the measure or the facet name you want to use.
@@ -537,7 +526,6 @@ def create_monitor(
 
         Example: ``ci-pipelines(query).rollup(rollup_method[, measure]).last(time_window) operator #``
 
-
         * ``query`` The search query - following the `Log search syntax <https://docs.datadoghq.com/logs/search_syntax/>`_.
         * ``rollup_method`` The stats roll-up method - supports ``count`` , ``avg`` , and ``cardinality``.
         * ``measure`` For ``avg`` and cardinality ``rollup_method`` - specify the measure or the facet name you want to use.
@@ -551,7 +539,6 @@ def create_monitor(
 
         Example: ``ci-tests(query).rollup(rollup_method[, measure]).last(time_window) operator #``
 
-
         * ``query`` The search query - following the `Log search syntax <https://docs.datadoghq.com/logs/search_syntax/>`_.
         * ``rollup_method`` The stats roll-up method - supports ``count`` , ``avg`` , and ``cardinality``.
         * ``measure`` For ``avg`` and cardinality ``rollup_method`` - specify the measure or the facet name you want to use.
@@ -566,7 +553,6 @@ def create_monitor(
         Example(RUM): ``error-tracking-rum(query).rollup(rollup_method[, measure]).last(time_window) operator #``
         Example(APM Traces): ``error-tracking-traces(query).rollup(rollup_method[, measure]).last(time_window) operator #``
 
-
         * ``query`` The search query - following the `Log search syntax <https://docs.datadoghq.com/logs/search_syntax/>`_.
         * ``rollup_method`` The stats roll-up method - supports ``count`` , ``avg`` , and ``cardinality``.
         * ``measure`` For ``avg`` and cardinality ``rollup_method`` - specify the measure or the facet name you want to use.
@@ -719,7 +705,6 @@ def search_monitor_groups(
         :type per_page: int, optional
         :param sort: String for sort order, composed of field and sort order separate by a comma, for example ``name,asc``. Supported sort directions: ``asc`` , ``desc``. Supported fields:
 
-
             * ``name``
             * ``status``
             * ``tags``
@@ -765,7 +750,6 @@ def search_monitors(
         :type per_page: int, optional
         :param sort: String for sort order, composed of field and sort order separate by a comma, for example ``name,asc``. Supported sort directions: ``asc`` , ``desc``. Supported fields:
 
-
             * ``name``
             * ``status``
             * ``tags``

src/datadog_api_client/v1/api/organizations_api.py

@@ -275,7 +275,6 @@ def upload_idp_for_org(
         There are a couple of options for updating the Identity Provider (IdP)
         metadata from your SAML IdP.
 
-
         *
           **Multipart Form-Data** : Post the IdP metadata file using a form post.