From 889107c66d1c49c60765f654d530d5463f37905f Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Fri, 8 Nov 2024 07:02:53 +0400 Subject: [PATCH] Emit Python warnings for beta and tech preview APIs (#2675) (cherry picked from commit 066465ef011c336a7b29958e30b39420e483a788) --- elasticsearch/_async/client/__init__.py | 3 ++ elasticsearch/_async/client/cat.py | 9 +++- elasticsearch/_async/client/connector.py | 33 +++++++++++++- elasticsearch/_async/client/features.py | 3 +- elasticsearch/_async/client/fleet.py | 10 ++++- elasticsearch/_async/client/indices.py | 11 ++++- elasticsearch/_async/client/inference.py | 12 +++++- elasticsearch/_async/client/nodes.py | 10 ++++- elasticsearch/_async/client/rollup.py | 16 ++++++- .../_async/client/search_application.py | 16 ++++++- .../_async/client/searchable_snapshots.py | 10 ++++- elasticsearch/_async/client/snapshot.py | 9 +++- elasticsearch/_async/client/tasks.py | 11 ++++- elasticsearch/_async/client/utils.py | 4 ++ elasticsearch/_sync/client/__init__.py | 3 ++ elasticsearch/_sync/client/cat.py | 9 +++- elasticsearch/_sync/client/connector.py | 33 +++++++++++++- elasticsearch/_sync/client/features.py | 3 +- elasticsearch/_sync/client/fleet.py | 10 ++++- elasticsearch/_sync/client/indices.py | 11 ++++- elasticsearch/_sync/client/inference.py | 12 +++++- elasticsearch/_sync/client/nodes.py | 10 ++++- elasticsearch/_sync/client/rollup.py | 16 ++++++- .../_sync/client/search_application.py | 16 ++++++- .../_sync/client/searchable_snapshots.py | 10 ++++- elasticsearch/_sync/client/snapshot.py | 9 +++- elasticsearch/_sync/client/tasks.py | 11 ++++- elasticsearch/_sync/client/utils.py | 41 ++++++++++++++++++ elasticsearch/exceptions.py | 4 ++ test_elasticsearch/test_client/test_utils.py | 43 ++++++++++++++++++- 30 files changed, 373 insertions(+), 25 deletions(-) diff --git a/elasticsearch/_async/client/__init__.py b/elasticsearch/_async/client/__init__.py index 771420ced..3086538e2 100644 --- a/elasticsearch/_async/client/__init__.py +++ b/elasticsearch/_async/client/__init__.py @@ -82,8 +82,10 @@ _TYPE_HOSTS, CLIENT_META_SERVICE, SKIP_IN_PATH, + Stability, _quote, _rewrite_parameters, + _stability_warning, client_node_configs, is_requests_http_auth, is_requests_node_class, @@ -3554,6 +3556,7 @@ async def render_search_template( @_rewrite_parameters( body_fields=("context", "context_setup", "script"), ) + @_stability_warning(Stability.EXPERIMENTAL) async def scripts_painless_execute( self, *, diff --git a/elasticsearch/_async/client/cat.py b/elasticsearch/_async/client/cat.py index 2c8e8e055..257470b84 100644 --- a/elasticsearch/_async/client/cat.py +++ b/elasticsearch/_async/client/cat.py @@ -20,7 +20,13 @@ from elastic_transport import ObjectApiResponse, TextApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class CatClient(NamespacedClient): @@ -2517,6 +2523,7 @@ async def snapshots( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def tasks( self, *, diff --git a/elasticsearch/_async/client/connector.py b/elasticsearch/_async/client/connector.py index ac2f1de31..34d566333 100644 --- a/elasticsearch/_async/client/connector.py +++ b/elasticsearch/_async/client/connector.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class ConnectorClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def check_in( self, *, @@ -67,6 +74,7 @@ async def check_in( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) async def delete( self, *, @@ -115,6 +123,7 @@ async def delete( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) async def get( self, *, @@ -170,6 +179,7 @@ async def get( "sync_cursor", ), ) + @_stability_warning(Stability.EXPERIMENTAL) async def last_sync( self, *, @@ -299,6 +309,7 @@ async def last_sync( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) + @_stability_warning(Stability.BETA) async def list( self, *, @@ -372,6 +383,7 @@ async def list( "service_type", ), ) + @_stability_warning(Stability.BETA) async def post( self, *, @@ -453,6 +465,7 @@ async def post( "service_type", ), ) + @_stability_warning(Stability.BETA) async def put( self, *, @@ -529,6 +542,7 @@ async def put( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) async def sync_job_cancel( self, *, @@ -576,6 +590,7 @@ async def sync_job_cancel( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) async def sync_job_delete( self, *, @@ -620,6 +635,7 @@ async def sync_job_delete( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) async def sync_job_get( self, *, @@ -664,6 +680,7 @@ async def sync_job_get( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) + @_stability_warning(Stability.BETA) async def sync_job_list( self, *, @@ -743,6 +760,7 @@ async def sync_job_list( @_rewrite_parameters( body_fields=("id", "job_type", "trigger_method"), ) + @_stability_warning(Stability.BETA) async def sync_job_post( self, *, @@ -802,6 +820,7 @@ async def sync_job_post( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def update_active_filtering( self, *, @@ -845,6 +864,7 @@ async def update_active_filtering( @_rewrite_parameters( body_fields=("api_key_id", "api_key_secret_id"), ) + @_stability_warning(Stability.BETA) async def update_api_key_id( self, *, @@ -903,6 +923,7 @@ async def update_api_key_id( @_rewrite_parameters( body_fields=("configuration", "values"), ) + @_stability_warning(Stability.BETA) async def update_configuration( self, *, @@ -958,6 +979,7 @@ async def update_configuration( @_rewrite_parameters( body_fields=("error",), ) + @_stability_warning(Stability.EXPERIMENTAL) async def update_error( self, *, @@ -1013,6 +1035,7 @@ async def update_error( @_rewrite_parameters( body_fields=("advanced_snippet", "filtering", "rules"), ) + @_stability_warning(Stability.BETA) async def update_filtering( self, *, @@ -1074,6 +1097,7 @@ async def update_filtering( @_rewrite_parameters( body_fields=("validation",), ) + @_stability_warning(Stability.EXPERIMENTAL) async def update_filtering_validation( self, *, @@ -1127,6 +1151,7 @@ async def update_filtering_validation( @_rewrite_parameters( body_fields=("index_name",), ) + @_stability_warning(Stability.BETA) async def update_index_name( self, *, @@ -1180,6 +1205,7 @@ async def update_index_name( @_rewrite_parameters( body_fields=("description", "name"), ) + @_stability_warning(Stability.BETA) async def update_name( self, *, @@ -1234,6 +1260,7 @@ async def update_name( @_rewrite_parameters( body_fields=("is_native",), ) + @_stability_warning(Stability.BETA) async def update_native( self, *, @@ -1286,6 +1313,7 @@ async def update_native( @_rewrite_parameters( body_fields=("pipeline",), ) + @_stability_warning(Stability.BETA) async def update_pipeline( self, *, @@ -1339,6 +1367,7 @@ async def update_pipeline( @_rewrite_parameters( body_fields=("scheduling",), ) + @_stability_warning(Stability.BETA) async def update_scheduling( self, *, @@ -1391,6 +1420,7 @@ async def update_scheduling( @_rewrite_parameters( body_fields=("service_type",), ) + @_stability_warning(Stability.BETA) async def update_service_type( self, *, @@ -1443,6 +1473,7 @@ async def update_service_type( @_rewrite_parameters( body_fields=("status",), ) + @_stability_warning(Stability.EXPERIMENTAL) async def update_status( self, *, diff --git a/elasticsearch/_async/client/features.py b/elasticsearch/_async/client/features.py index 62e730285..32fecf55a 100644 --- a/elasticsearch/_async/client/features.py +++ b/elasticsearch/_async/client/features.py @@ -20,7 +20,7 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import _rewrite_parameters +from .utils import Stability, _rewrite_parameters, _stability_warning class FeaturesClient(NamespacedClient): @@ -62,6 +62,7 @@ async def get_features( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def reset_features( self, *, diff --git a/elasticsearch/_async/client/fleet.py b/elasticsearch/_async/client/fleet.py index a2ca88f00..eb05f0352 100644 --- a/elasticsearch/_async/client/fleet.py +++ b/elasticsearch/_async/client/fleet.py @@ -20,7 +20,13 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class FleetClient(NamespacedClient): @@ -91,6 +97,7 @@ async def global_checkpoints( @_rewrite_parameters( body_name="searches", ) + @_stability_warning(Stability.EXPERIMENTAL) async def msearch( self, *, @@ -277,6 +284,7 @@ async def msearch( "from": "from_", }, ) + @_stability_warning(Stability.EXPERIMENTAL) async def search( self, *, diff --git a/elasticsearch/_async/client/indices.py b/elasticsearch/_async/client/indices.py index 5c8c337d1..e884cd8ff 100644 --- a/elasticsearch/_async/client/indices.py +++ b/elasticsearch/_async/client/indices.py @@ -20,7 +20,13 @@ from elastic_transport import HeadApiResponse, ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class IndicesClient(NamespacedClient): @@ -1032,6 +1038,7 @@ async def delete_template( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def disk_usage( self, *, @@ -1114,6 +1121,7 @@ async def disk_usage( @_rewrite_parameters( body_name="config", ) + @_stability_warning(Stability.EXPERIMENTAL) async def downsample( self, *, @@ -1488,6 +1496,7 @@ async def explain_data_lifecycle( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def field_usage_stats( self, *, diff --git a/elasticsearch/_async/client/inference.py b/elasticsearch/_async/client/inference.py index 701ba6835..a3ddb1628 100644 --- a/elasticsearch/_async/client/inference.py +++ b/elasticsearch/_async/client/inference.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class InferenceClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def delete( self, *, @@ -93,6 +100,7 @@ async def delete( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def get( self, *, @@ -151,6 +159,7 @@ async def get( @_rewrite_parameters( body_fields=("input", "query", "task_settings"), ) + @_stability_warning(Stability.EXPERIMENTAL) async def inference( self, *, @@ -237,6 +246,7 @@ async def inference( @_rewrite_parameters( body_name="inference_config", ) + @_stability_warning(Stability.EXPERIMENTAL) async def put( self, *, diff --git a/elasticsearch/_async/client/nodes.py b/elasticsearch/_async/client/nodes.py index 17c0f5401..a7b516588 100644 --- a/elasticsearch/_async/client/nodes.py +++ b/elasticsearch/_async/client/nodes.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse, TextApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class NodesClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def clear_repositories_metering_archive( self, *, @@ -76,6 +83,7 @@ async def clear_repositories_metering_archive( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def get_repositories_metering_info( self, *, diff --git a/elasticsearch/_async/client/rollup.py b/elasticsearch/_async/client/rollup.py index 6ccba08ab..154090dd2 100644 --- a/elasticsearch/_async/client/rollup.py +++ b/elasticsearch/_async/client/rollup.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class RollupClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def delete_job( self, *, @@ -66,6 +73,7 @@ async def delete_job( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def get_jobs( self, *, @@ -110,6 +118,7 @@ async def get_jobs( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def get_rollup_caps( self, *, @@ -155,6 +164,7 @@ async def get_rollup_caps( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def get_rollup_index_caps( self, *, @@ -209,6 +219,7 @@ async def get_rollup_index_caps( ), ignore_deprecated_options={"headers"}, ) + @_stability_warning(Stability.EXPERIMENTAL) async def put_job( self, *, @@ -327,6 +338,7 @@ async def put_job( @_rewrite_parameters( body_fields=("aggregations", "aggs", "query", "size"), ) + @_stability_warning(Stability.EXPERIMENTAL) async def rollup_search( self, *, @@ -397,6 +409,7 @@ async def rollup_search( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def start_job( self, *, @@ -437,6 +450,7 @@ async def start_job( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def stop_job( self, *, diff --git a/elasticsearch/_async/client/search_application.py b/elasticsearch/_async/client/search_application.py index e4d0838e5..b8462f575 100644 --- a/elasticsearch/_async/client/search_application.py +++ b/elasticsearch/_async/client/search_application.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class SearchApplicationClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.BETA) async def delete( self, *, @@ -67,6 +74,7 @@ async def delete( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def delete_behavioral_analytics( self, *, @@ -108,6 +116,7 @@ async def delete_behavioral_analytics( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) async def get( self, *, @@ -148,6 +157,7 @@ async def get( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def get_behavioral_analytics( self, *, @@ -193,6 +203,7 @@ async def get_behavioral_analytics( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) + @_stability_warning(Stability.BETA) async def list( self, *, @@ -243,6 +254,7 @@ async def list( @_rewrite_parameters( body_name="search_application", ) + @_stability_warning(Stability.BETA) async def put( self, *, @@ -299,6 +311,7 @@ async def put( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def put_behavioral_analytics( self, *, @@ -342,6 +355,7 @@ async def put_behavioral_analytics( body_fields=("params",), ignore_deprecated_options={"params"}, ) + @_stability_warning(Stability.BETA) async def search( self, *, diff --git a/elasticsearch/_async/client/searchable_snapshots.py b/elasticsearch/_async/client/searchable_snapshots.py index 5d5b9a8a3..092e29ede 100644 --- a/elasticsearch/_async/client/searchable_snapshots.py +++ b/elasticsearch/_async/client/searchable_snapshots.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class SearchableSnapshotsClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def cache_stats( self, *, @@ -75,6 +82,7 @@ async def cache_stats( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def clear_cache( self, *, diff --git a/elasticsearch/_async/client/snapshot.py b/elasticsearch/_async/client/snapshot.py index 2223ca978..b9dfdc634 100644 --- a/elasticsearch/_async/client/snapshot.py +++ b/elasticsearch/_async/client/snapshot.py @@ -20,7 +20,13 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class SnapshotClient(NamespacedClient): @@ -617,6 +623,7 @@ async def get_repository( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def repository_verify_integrity( self, *, diff --git a/elasticsearch/_async/client/tasks.py b/elasticsearch/_async/client/tasks.py index fcfe84185..ca9c38eae 100644 --- a/elasticsearch/_async/client/tasks.py +++ b/elasticsearch/_async/client/tasks.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class TasksClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def cancel( self, *, @@ -87,6 +94,7 @@ async def cancel( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def get( self, *, @@ -138,6 +146,7 @@ async def get( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) async def list( self, *, diff --git a/elasticsearch/_async/client/utils.py b/elasticsearch/_async/client/utils.py index ec0a6e4b8..97918d9e4 100644 --- a/elasticsearch/_async/client/utils.py +++ b/elasticsearch/_async/client/utils.py @@ -20,10 +20,12 @@ _TYPE_HOSTS, CLIENT_META_SERVICE, SKIP_IN_PATH, + Stability, _base64_auth_header, _quote, _quote_query, _rewrite_parameters, + _stability_warning, client_node_configs, is_requests_http_auth, is_requests_node_class, @@ -37,8 +39,10 @@ "_quote_query", "_TYPE_HOSTS", "SKIP_IN_PATH", + "Stability", "client_node_configs", "_rewrite_parameters", + "_stability_warning", "is_requests_http_auth", "is_requests_node_class", ] diff --git a/elasticsearch/_sync/client/__init__.py b/elasticsearch/_sync/client/__init__.py index 4f1498e66..d92347291 100644 --- a/elasticsearch/_sync/client/__init__.py +++ b/elasticsearch/_sync/client/__init__.py @@ -82,8 +82,10 @@ _TYPE_HOSTS, CLIENT_META_SERVICE, SKIP_IN_PATH, + Stability, _quote, _rewrite_parameters, + _stability_warning, client_node_configs, is_requests_http_auth, is_requests_node_class, @@ -3552,6 +3554,7 @@ def render_search_template( @_rewrite_parameters( body_fields=("context", "context_setup", "script"), ) + @_stability_warning(Stability.EXPERIMENTAL) def scripts_painless_execute( self, *, diff --git a/elasticsearch/_sync/client/cat.py b/elasticsearch/_sync/client/cat.py index 0048c8eb5..c3ddf4dc6 100644 --- a/elasticsearch/_sync/client/cat.py +++ b/elasticsearch/_sync/client/cat.py @@ -20,7 +20,13 @@ from elastic_transport import ObjectApiResponse, TextApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class CatClient(NamespacedClient): @@ -2517,6 +2523,7 @@ def snapshots( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def tasks( self, *, diff --git a/elasticsearch/_sync/client/connector.py b/elasticsearch/_sync/client/connector.py index 2c64c556d..58d551bb7 100644 --- a/elasticsearch/_sync/client/connector.py +++ b/elasticsearch/_sync/client/connector.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class ConnectorClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def check_in( self, *, @@ -67,6 +74,7 @@ def check_in( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) def delete( self, *, @@ -115,6 +123,7 @@ def delete( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) def get( self, *, @@ -170,6 +179,7 @@ def get( "sync_cursor", ), ) + @_stability_warning(Stability.EXPERIMENTAL) def last_sync( self, *, @@ -299,6 +309,7 @@ def last_sync( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) + @_stability_warning(Stability.BETA) def list( self, *, @@ -372,6 +383,7 @@ def list( "service_type", ), ) + @_stability_warning(Stability.BETA) def post( self, *, @@ -453,6 +465,7 @@ def post( "service_type", ), ) + @_stability_warning(Stability.BETA) def put( self, *, @@ -529,6 +542,7 @@ def put( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) def sync_job_cancel( self, *, @@ -576,6 +590,7 @@ def sync_job_cancel( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) def sync_job_delete( self, *, @@ -620,6 +635,7 @@ def sync_job_delete( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) def sync_job_get( self, *, @@ -664,6 +680,7 @@ def sync_job_get( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) + @_stability_warning(Stability.BETA) def sync_job_list( self, *, @@ -743,6 +760,7 @@ def sync_job_list( @_rewrite_parameters( body_fields=("id", "job_type", "trigger_method"), ) + @_stability_warning(Stability.BETA) def sync_job_post( self, *, @@ -802,6 +820,7 @@ def sync_job_post( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def update_active_filtering( self, *, @@ -845,6 +864,7 @@ def update_active_filtering( @_rewrite_parameters( body_fields=("api_key_id", "api_key_secret_id"), ) + @_stability_warning(Stability.BETA) def update_api_key_id( self, *, @@ -903,6 +923,7 @@ def update_api_key_id( @_rewrite_parameters( body_fields=("configuration", "values"), ) + @_stability_warning(Stability.BETA) def update_configuration( self, *, @@ -958,6 +979,7 @@ def update_configuration( @_rewrite_parameters( body_fields=("error",), ) + @_stability_warning(Stability.EXPERIMENTAL) def update_error( self, *, @@ -1013,6 +1035,7 @@ def update_error( @_rewrite_parameters( body_fields=("advanced_snippet", "filtering", "rules"), ) + @_stability_warning(Stability.BETA) def update_filtering( self, *, @@ -1074,6 +1097,7 @@ def update_filtering( @_rewrite_parameters( body_fields=("validation",), ) + @_stability_warning(Stability.EXPERIMENTAL) def update_filtering_validation( self, *, @@ -1127,6 +1151,7 @@ def update_filtering_validation( @_rewrite_parameters( body_fields=("index_name",), ) + @_stability_warning(Stability.BETA) def update_index_name( self, *, @@ -1180,6 +1205,7 @@ def update_index_name( @_rewrite_parameters( body_fields=("description", "name"), ) + @_stability_warning(Stability.BETA) def update_name( self, *, @@ -1234,6 +1260,7 @@ def update_name( @_rewrite_parameters( body_fields=("is_native",), ) + @_stability_warning(Stability.BETA) def update_native( self, *, @@ -1286,6 +1313,7 @@ def update_native( @_rewrite_parameters( body_fields=("pipeline",), ) + @_stability_warning(Stability.BETA) def update_pipeline( self, *, @@ -1339,6 +1367,7 @@ def update_pipeline( @_rewrite_parameters( body_fields=("scheduling",), ) + @_stability_warning(Stability.BETA) def update_scheduling( self, *, @@ -1391,6 +1420,7 @@ def update_scheduling( @_rewrite_parameters( body_fields=("service_type",), ) + @_stability_warning(Stability.BETA) def update_service_type( self, *, @@ -1443,6 +1473,7 @@ def update_service_type( @_rewrite_parameters( body_fields=("status",), ) + @_stability_warning(Stability.EXPERIMENTAL) def update_status( self, *, diff --git a/elasticsearch/_sync/client/features.py b/elasticsearch/_sync/client/features.py index 96748493f..83aa4127e 100644 --- a/elasticsearch/_sync/client/features.py +++ b/elasticsearch/_sync/client/features.py @@ -20,7 +20,7 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import _rewrite_parameters +from .utils import Stability, _rewrite_parameters, _stability_warning class FeaturesClient(NamespacedClient): @@ -62,6 +62,7 @@ def get_features( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def reset_features( self, *, diff --git a/elasticsearch/_sync/client/fleet.py b/elasticsearch/_sync/client/fleet.py index 098981d07..a8a86a7df 100644 --- a/elasticsearch/_sync/client/fleet.py +++ b/elasticsearch/_sync/client/fleet.py @@ -20,7 +20,13 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class FleetClient(NamespacedClient): @@ -91,6 +97,7 @@ def global_checkpoints( @_rewrite_parameters( body_name="searches", ) + @_stability_warning(Stability.EXPERIMENTAL) def msearch( self, *, @@ -277,6 +284,7 @@ def msearch( "from": "from_", }, ) + @_stability_warning(Stability.EXPERIMENTAL) def search( self, *, diff --git a/elasticsearch/_sync/client/indices.py b/elasticsearch/_sync/client/indices.py index bcd064b1c..92133311a 100644 --- a/elasticsearch/_sync/client/indices.py +++ b/elasticsearch/_sync/client/indices.py @@ -20,7 +20,13 @@ from elastic_transport import HeadApiResponse, ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class IndicesClient(NamespacedClient): @@ -1032,6 +1038,7 @@ def delete_template( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def disk_usage( self, *, @@ -1114,6 +1121,7 @@ def disk_usage( @_rewrite_parameters( body_name="config", ) + @_stability_warning(Stability.EXPERIMENTAL) def downsample( self, *, @@ -1488,6 +1496,7 @@ def explain_data_lifecycle( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def field_usage_stats( self, *, diff --git a/elasticsearch/_sync/client/inference.py b/elasticsearch/_sync/client/inference.py index 08f9da4aa..9f58dfbfc 100644 --- a/elasticsearch/_sync/client/inference.py +++ b/elasticsearch/_sync/client/inference.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class InferenceClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def delete( self, *, @@ -93,6 +100,7 @@ def delete( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def get( self, *, @@ -151,6 +159,7 @@ def get( @_rewrite_parameters( body_fields=("input", "query", "task_settings"), ) + @_stability_warning(Stability.EXPERIMENTAL) def inference( self, *, @@ -237,6 +246,7 @@ def inference( @_rewrite_parameters( body_name="inference_config", ) + @_stability_warning(Stability.EXPERIMENTAL) def put( self, *, diff --git a/elasticsearch/_sync/client/nodes.py b/elasticsearch/_sync/client/nodes.py index c605a7b6b..5c8e36979 100644 --- a/elasticsearch/_sync/client/nodes.py +++ b/elasticsearch/_sync/client/nodes.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse, TextApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class NodesClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def clear_repositories_metering_archive( self, *, @@ -76,6 +83,7 @@ def clear_repositories_metering_archive( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def get_repositories_metering_info( self, *, diff --git a/elasticsearch/_sync/client/rollup.py b/elasticsearch/_sync/client/rollup.py index 9ed2c25fa..75d86e361 100644 --- a/elasticsearch/_sync/client/rollup.py +++ b/elasticsearch/_sync/client/rollup.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class RollupClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def delete_job( self, *, @@ -66,6 +73,7 @@ def delete_job( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def get_jobs( self, *, @@ -110,6 +118,7 @@ def get_jobs( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def get_rollup_caps( self, *, @@ -155,6 +164,7 @@ def get_rollup_caps( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def get_rollup_index_caps( self, *, @@ -209,6 +219,7 @@ def get_rollup_index_caps( ), ignore_deprecated_options={"headers"}, ) + @_stability_warning(Stability.EXPERIMENTAL) def put_job( self, *, @@ -327,6 +338,7 @@ def put_job( @_rewrite_parameters( body_fields=("aggregations", "aggs", "query", "size"), ) + @_stability_warning(Stability.EXPERIMENTAL) def rollup_search( self, *, @@ -397,6 +409,7 @@ def rollup_search( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def start_job( self, *, @@ -437,6 +450,7 @@ def start_job( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def stop_job( self, *, diff --git a/elasticsearch/_sync/client/search_application.py b/elasticsearch/_sync/client/search_application.py index 7b7619fa7..42b042434 100644 --- a/elasticsearch/_sync/client/search_application.py +++ b/elasticsearch/_sync/client/search_application.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class SearchApplicationClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.BETA) def delete( self, *, @@ -67,6 +74,7 @@ def delete( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def delete_behavioral_analytics( self, *, @@ -108,6 +116,7 @@ def delete_behavioral_analytics( ) @_rewrite_parameters() + @_stability_warning(Stability.BETA) def get( self, *, @@ -148,6 +157,7 @@ def get( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def get_behavioral_analytics( self, *, @@ -193,6 +203,7 @@ def get_behavioral_analytics( @_rewrite_parameters( parameter_aliases={"from": "from_"}, ) + @_stability_warning(Stability.BETA) def list( self, *, @@ -243,6 +254,7 @@ def list( @_rewrite_parameters( body_name="search_application", ) + @_stability_warning(Stability.BETA) def put( self, *, @@ -299,6 +311,7 @@ def put( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def put_behavioral_analytics( self, *, @@ -342,6 +355,7 @@ def put_behavioral_analytics( body_fields=("params",), ignore_deprecated_options={"params"}, ) + @_stability_warning(Stability.BETA) def search( self, *, diff --git a/elasticsearch/_sync/client/searchable_snapshots.py b/elasticsearch/_sync/client/searchable_snapshots.py index 2db8dfb04..45104eefc 100644 --- a/elasticsearch/_sync/client/searchable_snapshots.py +++ b/elasticsearch/_sync/client/searchable_snapshots.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class SearchableSnapshotsClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def cache_stats( self, *, @@ -75,6 +82,7 @@ def cache_stats( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def clear_cache( self, *, diff --git a/elasticsearch/_sync/client/snapshot.py b/elasticsearch/_sync/client/snapshot.py index a52498c63..e65dee0ec 100644 --- a/elasticsearch/_sync/client/snapshot.py +++ b/elasticsearch/_sync/client/snapshot.py @@ -20,7 +20,13 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class SnapshotClient(NamespacedClient): @@ -617,6 +623,7 @@ def get_repository( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def repository_verify_integrity( self, *, diff --git a/elasticsearch/_sync/client/tasks.py b/elasticsearch/_sync/client/tasks.py index 5474ef2de..f69ef007c 100644 --- a/elasticsearch/_sync/client/tasks.py +++ b/elasticsearch/_sync/client/tasks.py @@ -20,12 +20,19 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters +from .utils import ( + SKIP_IN_PATH, + Stability, + _quote, + _rewrite_parameters, + _stability_warning, +) class TasksClient(NamespacedClient): @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def cancel( self, *, @@ -87,6 +94,7 @@ def cancel( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def get( self, *, @@ -138,6 +146,7 @@ def get( ) @_rewrite_parameters() + @_stability_warning(Stability.EXPERIMENTAL) def list( self, *, diff --git a/elasticsearch/_sync/client/utils.py b/elasticsearch/_sync/client/utils.py index 1d1a983ac..959f61bfd 100644 --- a/elasticsearch/_sync/client/utils.py +++ b/elasticsearch/_sync/client/utils.py @@ -20,6 +20,7 @@ import urllib.parse import warnings from datetime import date, datetime +from enum import Enum, auto from functools import wraps from typing import ( TYPE_CHECKING, @@ -55,6 +56,8 @@ url_to_node_config, ) +from elasticsearch.exceptions import GeneralAvailabilityWarning + from ..._version import __versionstr__ from ...compat import to_bytes, to_str, warn_stacklevel @@ -70,6 +73,13 @@ # Default User-Agent used by the client USER_AGENT = create_user_agent("elasticsearch-py", __versionstr__) + +class Stability(Enum): + STABLE = auto() + BETA = auto() + EXPERIMENTAL = auto() + + _TYPE_HOSTS = Union[ str, Sequence[Union[str, Mapping[str, Union[str, int]], NodeConfig]] ] @@ -450,6 +460,37 @@ def wrapped(*args: Any, **kwargs: Any) -> Any: return wrapper +def _stability_warning( + stability: Stability, + version: Optional[str] = None, + message: Optional[str] = None, +) -> Callable[[F], F]: + def wrapper(api: F) -> F: + @wraps(api) + def wrapped(*args: Any, **kwargs: Any) -> Any: + if stability == Stability.BETA: + warnings.warn( + "This API is in beta and is subject to change. " + "The design and code is less mature than official GA features and is being provided as-is with no warranties. " + "Beta features are not subject to the support SLA of official GA features.", + category=GeneralAvailabilityWarning, + stacklevel=warn_stacklevel(), + ) + elif stability == Stability.EXPERIMENTAL: + warnings.warn( + "This API is in technical preview and may be changed or removed in a future release. " + "Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.", + category=GeneralAvailabilityWarning, + stacklevel=warn_stacklevel(), + ) + + return api(*args, **kwargs) + + return wrapped # type: ignore[return-value] + + return wrapper + + def is_requests_http_auth(http_auth: Any) -> bool: """Detect if an http_auth value is a custom Requests auth object""" try: diff --git a/elasticsearch/exceptions.py b/elasticsearch/exceptions.py index f58706774..dc410ae30 100644 --- a/elasticsearch/exceptions.py +++ b/elasticsearch/exceptions.py @@ -115,6 +115,10 @@ class ElasticsearchWarning(TransportWarning): """ +class GeneralAvailabilityWarning(TransportWarning): + """Warning that is raised when a feature is not yet GA.""" + + # Aliases for backwards compatibility ElasticsearchDeprecationWarning = ElasticsearchWarning RequestError = BadRequestError diff --git a/test_elasticsearch/test_client/test_utils.py b/test_elasticsearch/test_client/test_utils.py index e53145bfd..e4713ff1c 100644 --- a/test_elasticsearch/test_client/test_utils.py +++ b/test_elasticsearch/test_client/test_utils.py @@ -16,7 +16,12 @@ # under the License. -from elasticsearch._sync.client.utils import _quote +import warnings + +import pytest + +from elasticsearch._sync.client.utils import Stability, _quote, _stability_warning +from elasticsearch.exceptions import GeneralAvailabilityWarning def test_handles_ascii(): @@ -36,3 +41,39 @@ def test_handles_unicode(): def test_handles_unicode2(): string = "中*文," assert "%E4%B8%AD*%E6%96%87," == _quote(string) + + +class TestStabilityWarning: + def test_default(self): + + @_stability_warning(stability=Stability.STABLE) + def func_default(*args, **kwargs): + pass + + with warnings.catch_warnings(): + warnings.simplefilter("error") + func_default() + + def test_beta(self, recwarn): + + @_stability_warning(stability=Stability.BETA) + def func_beta(*args, **kwargs): + pass + + with pytest.warns( + GeneralAvailabilityWarning, + match="This API is in beta and is subject to change.", + ): + func_beta() + + def test_experimental(self, recwarn): + + @_stability_warning(stability=Stability.EXPERIMENTAL) + def func_experimental(*args, **kwargs): + pass + + with pytest.warns( + GeneralAvailabilityWarning, + match="This API is in technical preview and may be changed or removed in a future release.", + ): + func_experimental()