From d08860a357617dc3fccdecd1fe097b6765fa1c3c Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Wed, 28 Oct 2020 13:49:05 -0500 Subject: [PATCH] [7.x] Document all APIs, add stability warning --- docs/sphinx/api.rst | 44 ++- docs/sphinx/xpack.rst | 302 +++++++----------- elasticsearch/_async/client/__init__.py | 20 ++ elasticsearch/_async/client/autoscaling.py | 44 ++- elasticsearch/_async/client/autoscaling.pyi | 28 +- elasticsearch/_async/client/cluster.py | 20 ++ elasticsearch/_async/client/eql.py | 15 + elasticsearch/_async/client/indices.py | 35 ++ elasticsearch/_async/client/ml.py | 70 ++++ elasticsearch/_async/client/monitoring.py | 5 + elasticsearch/_async/client/rollup.py | 40 +++ .../_async/client/searchable_snapshots.py | 20 ++ elasticsearch/client/__init__.py | 20 ++ elasticsearch/client/autoscaling.py | 44 ++- elasticsearch/client/autoscaling.pyi | 28 +- elasticsearch/client/cluster.py | 20 ++ elasticsearch/client/eql.py | 15 + elasticsearch/client/indices.py | 35 ++ elasticsearch/client/ml.py | 70 ++++ elasticsearch/client/monitoring.py | 5 + elasticsearch/client/rollup.py | 40 +++ elasticsearch/client/searchable_snapshots.py | 20 ++ utils/generate_api.py | 2 + utils/templates/base | 7 + 24 files changed, 696 insertions(+), 253 deletions(-) diff --git a/docs/sphinx/api.rst b/docs/sphinx/api.rst index 0cb004ab..aba925ef 100644 --- a/docs/sphinx/api.rst +++ b/docs/sphinx/api.rst @@ -15,7 +15,7 @@ consistency and safety**. ``from`` and ``doc_type`` instead of ``type`` as parameter names. -Global options +Global Options -------------- Some parameters are added by the client itself and can be used in all API @@ -109,6 +109,30 @@ Elasticsearch .. py:module:: elasticsearch.client +Async Search +------------ + +.. autoclass:: AsyncSearchClient + :members: + +Cat +--- + +.. autoclass:: CatClient + :members: + +Cluster +------- + +.. autoclass:: ClusterClient + :members: + +Dangling Indices +---------------- + +.. autoclass:: DanglingIndicesClient + :members: + Indices ------- @@ -121,22 +145,16 @@ Ingest .. autoclass:: IngestClient :members: -Cluster -------- - -.. autoclass:: ClusterClient - :members: - Nodes ----- .. autoclass:: NodesClient :members: -Cat ---- +Remote +------ -.. autoclass:: CatClient +.. autoclass:: RemoteClient :members: Snapshot @@ -150,9 +168,3 @@ Tasks .. autoclass:: TasksClient :members: - -Dangling Indices ----------------- - -.. autoclass:: DanglingIndicesClient - :members: diff --git a/docs/sphinx/xpack.rst b/docs/sphinx/xpack.rst index 652c40ee..e60ece7b 100644 --- a/docs/sphinx/xpack.rst +++ b/docs/sphinx/xpack.rst @@ -8,247 +8,179 @@ reporting, and graph capabilities into one easy-to-install package. While the X-Pack components are designed to work together seamlessly, you can easily enable or disable the features you want to use. +.. py:module:: elasticsearch.client -Info ----- -`X-Pack info `_ +X-Pack Info +----------- + +`X-Pack Info API `_ provides general info about the installed X-Pack. -.. py:module:: elasticsearch.client.xpack - .. autoclass:: XPackClient :members: - -Async Search APIs ------------------ - -`Async Search API `_ -lets you asynchronously execute a search request, monitor its progress, -and retrieve partial results as they become available. - -.. py:module:: elasticsearch.client.async_search - -.. autoclass:: AsyncSearchClient - :members: - - -Autoscaling APIs ------------------ +Autoscaling +----------- `Autoscaling API `_ -gets the current autoscaling decision based on the configured autoscaling policy. - -.. py:module:: elasticsearch.client.autoscaling +is used to perform autoscaling operations. .. autoclass:: AutoscalingClient :members: +Cross-Cluster Replication +------------------------- -EQL APIs --------- - -`EQL API `_ -allows querying with Event Query Language (EQL) to search logs and events and match -them with shared properties. - -.. py:module:: elasticsearch.client.eql - -.. autoclass:: EqlClient - :members: - - -Graph Explore APIs ------------------- - -`Graph Explore API `_ -enables you to extract and summarize information about the documents and terms in your Elasticsearch index. - -.. py:module:: elasticsearch.client.graph - - -.. autoclass:: GraphClient - :members: - -Licensing APIs --------------- - -`Licensing API `_ -can be used to manage your licences. - - -.. py:module:: elasticsearch.client.license - - -.. autoclass:: LicenseClient - :members: - -Machine Learning APIs ---------------------- - -`Machine Learning `_ -can be useful for discovering new patterns about your data. For a more detailed explanation -about X-Pack's machine learning please refer to the official documentation. - - -.. py:module:: elasticsearch.client.ml - - -.. autoclass:: MlClient - :members: - -Security APIs -------------- - -`Security API `_ -can be used to help secure your Elasticsearch cluster. Integrating with LDAP and Active Directory. - -.. py:module:: elasticsearch.client.security - - -.. autoclass:: SecurityClient - :members: - -Watcher APIs -------------- - -`Watcher API `_ -can be used to notify you when certain pre-defined thresholds have happened. - -.. py:module:: elasticsearch.client.watcher - -.. autoclass:: WatcherClient - :members: - - -Migration APIs ---------------- - -`Migration API `_ -helps simplify upgrading X-Pack indices from one version to another. - -.. py:module:: elasticsearch.client.migration - -.. autoclass:: MigrationClient - :members: - - -Enrich APIs ------------- - -`Enrich API `_ -can be used to add data from your existing indices to incoming documents during ingest. - -.. py:module:: elasticsearch.client.enrich - -.. autoclass:: EnrichClient - :members: - -SQL APIs --------- - -The `SQL REST API `_ -accepts SQL in a JSON document, executes it, and returns the results. - -.. py:module:: elasticsearch.client.sql - -.. autoclass:: SqlClient - :members: - -Cross-Cluster Replication APIs -------------------------------- - -`Cross-Cluster Replication API `_ -used to perform cross-cluster replication operations. - -.. py:module:: elasticsearch.client.ccr +`Cross-Cluster Replication APIs `_ +are used to perform cross-cluster replication operations. .. autoclass:: CcrClient :members: +Enrich +------ -Monitoring APIs +`Enrich APIs `_ +can be used to add data from your existing indices to incoming documents during ingest. + +.. autoclass:: EnrichClient + :members: + +EQL +--- + +`EQL APIs `_ +accept EQL to query event-based time series data, such as logs, metrics, and traces. + +.. autoclass:: EqlClient + :members: + +Graph Explore +------------- + +`Graph Explore API `_ +enables you to extract and summarize information about the documents and terms in your Elasticsearch index. + +.. autoclass:: GraphClient + :members: + +Index Lifecycle Management (ILM) +-------------------------------- + +`Index Lifecycle Management APIs `_ +used to set up policies to automatically manage the index lifecycle. + +.. autoclass:: IlmClient + :members: + +Licensing +--------- + +`License APIs `_ +can be used to manage your licences. + +.. autoclass:: LicenseClient + :members: + +Machine Learning ---------------- +`Machine Learning APIs `_ +can be useful for discovering new patterns about your data. For a more detailed explanation +about X-Pack's machine learning please refer to the official documentation. + +.. autoclass:: MlClient + :members: + +Migration +--------- + +`Migration API `_ +helps simplify upgrading X-Pack indices from one version to another. + +.. autoclass:: MigrationClient + :members: + +Monitoring +---------- + `Monitoring API `_ used to collect data from the Elasticsearch nodes, Logstash nodes, Kibana instances, and Beats in your cluster. -.. py:module:: elasticsearch.client.monitoring - .. autoclass:: MonitoringClient :members: - -Rollup APIs ------------- +Rollup +------ `Rollup API `_ enables searching through rolled-up data using the standard query DSL. -.. py:module:: elasticsearch.client.rollup - .. autoclass:: RollupClient :members: +Searchable Snapshots +-------------------- -Snapshot Lifecycle Management APIs +`Searchable Snapshots API `_ +used to perform searchable snapshots operations. + +.. autoclass:: SearchableSnapshotsClient + :members: + +Security +-------- + +`Security API `_ +can be used to help secure your Elasticsearch cluster. Integrating with LDAP and Active Directory. + +.. autoclass:: SecurityClient + :members: + +Snapshot Lifecycle Management (SLM) ----------------------------------- `Snapshot Lifecycle Management API `_ can be used to set up policies to automatically take snapshots and control how long they are retained. -.. py:module:: elasticsearch.client.slm - .. autoclass:: SlmClient :members: +SQL +--- -Searchable Snapshots APIs -------------------------- +The `SQL REST API `_ +accepts SQL in a JSON document, executes it, and returns the results. -`Searchable Snapshots API `_ -used to perform searchable snapshots operations. - -.. py:module:: elasticsearch.client.searchable_snapshots - -.. autoclass:: SearchableSnapshotsClient +.. autoclass:: SqlClient :members: - -Index Lifecycle Management APIs --------------------------------- - -`Index Lifecycle Management API `_ -used to set up policies to automatically manage the index lifecycle. - -.. py:module:: elasticsearch.client.ilm - -.. autoclass:: IlmClient - :members: - - -Transform APIs +SSL Certificate --------------- +`SSL Certificate API `_ +enables you to retrieve information about the X.509 certificates that are used +to encrypt communications in your Elasticsearch cluster. + +.. autoclass:: SslClient + :members: + +Transform +--------- + `Transform API `_ manages transformation operations from grabbing data from source indices, transforms it, and saves it to a destination index. -.. py:module:: elasticsearch.client.transform - .. autoclass:: TransformClient :members: +Watcher +------- -Deprecation APIs ------------------ +`Watcher APIs `_ +can be used to notify you when certain pre-defined thresholds have happened. -`Deprecation API `_ -used to retrieve information about different cluster, node, and index level settings that use deprecated features -that will be removed or changed in the next major version. - -.. py:module:: elasticsearch.client.deprecation - -.. autoclass:: DeprecationClient +.. autoclass:: WatcherClient :members: diff --git a/elasticsearch/_async/client/__init__.py b/elasticsearch/_async/client/__init__.py index deb8b4b2..0985a1ba 100644 --- a/elasticsearch/_async/client/__init__.py +++ b/elasticsearch/_async/client/__init__.py @@ -1348,6 +1348,11 @@ class AsyncElasticsearch(object): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg body: The ranking evaluation search definition, including search requests, document ratings and ranking metric definition. :arg index: A comma-separated list of index names to search; use @@ -1469,6 +1474,11 @@ class AsyncElasticsearch(object): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg body: The script to execute """ return await self.transport.perform_request( @@ -2062,6 +2072,11 @@ class AsyncElasticsearch(object): Returns all script contexts. ``_ + + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version """ return await self.transport.perform_request( "GET", "/_script_context", params=params, headers=headers @@ -2073,6 +2088,11 @@ class AsyncElasticsearch(object): Returns available script types, languages and contexts ``_ + + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version """ return await self.transport.perform_request( "GET", "/_script_language", params=params, headers=headers diff --git a/elasticsearch/_async/client/autoscaling.py b/elasticsearch/_async/client/autoscaling.py index 918899a5..cb335b15 100644 --- a/elasticsearch/_async/client/autoscaling.py +++ b/elasticsearch/_async/client/autoscaling.py @@ -19,18 +19,6 @@ from .utils import NamespacedClient, query_params, SKIP_IN_PATH, _make_path class AutoscalingClient(NamespacedClient): - @query_params() - async def get_autoscaling_decision(self, params=None, headers=None): - """ - Gets the current autoscaling decision based on the configured autoscaling - policy, indicating whether or not autoscaling is needed. - - ``_ - """ - return await self.transport.perform_request( - "GET", "/_autoscaling/decision", params=params, headers=headers - ) - @query_params() async def delete_autoscaling_policy(self, name, params=None, headers=None): """ @@ -38,6 +26,11 @@ class AutoscalingClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: the name of the autoscaling policy """ if name in SKIP_IN_PATH: @@ -57,6 +50,11 @@ class AutoscalingClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: the name of the autoscaling policy """ if name in SKIP_IN_PATH: @@ -76,6 +74,11 @@ class AutoscalingClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: the name of the autoscaling policy :arg body: the specification of the autoscaling policy """ @@ -90,3 +93,20 @@ class AutoscalingClient(NamespacedClient): headers=headers, body=body, ) + + @query_params() + async def get_autoscaling_capacity(self, params=None, headers=None): + """ + Gets the current autoscaling capacity based on the configured autoscaling + policy. + + ``_ + + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + """ + return await self.transport.perform_request( + "GET", "/_autoscaling/capacity", params=params, headers=headers + ) diff --git a/elasticsearch/_async/client/autoscaling.pyi b/elasticsearch/_async/client/autoscaling.pyi index 283f3764..1d7482b3 100644 --- a/elasticsearch/_async/client/autoscaling.pyi +++ b/elasticsearch/_async/client/autoscaling.pyi @@ -19,20 +19,6 @@ from typing import Any, MutableMapping, Optional, Union, Collection from .utils import NamespacedClient class AutoscalingClient(NamespacedClient): - async def get_autoscaling_decision( - self, - *, - pretty: Optional[bool] = ..., - human: Optional[bool] = ..., - error_trace: Optional[bool] = ..., - format: Optional[str] = ..., - filter_path: Optional[Union[str, Collection[str]]] = ..., - request_timeout: Optional[Union[int, float]] = ..., - ignore: Optional[Union[int, Collection[int]]] = ..., - opaque_id: Optional[str] = ..., - params: Optional[MutableMapping[str, Any]] = ..., - headers: Optional[MutableMapping[str, str]] = ... - ) -> Any: ... async def delete_autoscaling_policy( self, name: Any, @@ -79,3 +65,17 @@ class AutoscalingClient(NamespacedClient): params: Optional[MutableMapping[str, Any]] = ..., headers: Optional[MutableMapping[str, str]] = ... ) -> Any: ... + async def get_autoscaling_capacity( + self, + *, + pretty: Optional[bool] = ..., + human: Optional[bool] = ..., + error_trace: Optional[bool] = ..., + format: Optional[str] = ..., + filter_path: Optional[Union[str, Collection[str]]] = ..., + request_timeout: Optional[Union[int, float]] = ..., + ignore: Optional[Union[int, Collection[int]]] = ..., + opaque_id: Optional[str] = ..., + params: Optional[MutableMapping[str, Any]] = ..., + headers: Optional[MutableMapping[str, str]] = ... + ) -> Any: ... diff --git a/elasticsearch/_async/client/cluster.py b/elasticsearch/_async/client/cluster.py index 8d817156..9fc529f1 100644 --- a/elasticsearch/_async/client/cluster.py +++ b/elasticsearch/_async/client/cluster.py @@ -268,6 +268,11 @@ class ClusterClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit operation timeout @@ -289,6 +294,11 @@ class ClusterClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The comma separated names of the component templates :arg local: Return local information, do not retrieve the state from master node (default: false) @@ -309,6 +319,11 @@ class ClusterClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg body: The template definition :arg create: Whether the index template should only be added if @@ -335,6 +350,11 @@ class ClusterClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg local: Return local information, do not retrieve the state from master node (default: false) diff --git a/elasticsearch/_async/client/eql.py b/elasticsearch/_async/client/eql.py index d5e72789..a30cdb6c 100644 --- a/elasticsearch/_async/client/eql.py +++ b/elasticsearch/_async/client/eql.py @@ -26,6 +26,11 @@ class EqlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg index: The name of the index to scope the operation :arg body: Eql request body. Use the `query` to limit the query scope. @@ -57,6 +62,11 @@ class EqlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The async search ID """ if id in SKIP_IN_PATH: @@ -74,6 +84,11 @@ class EqlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The async search ID :arg keep_alive: Update the time interval in which the results (partial or final) for this search will be available Default: 5d diff --git a/elasticsearch/_async/client/indices.py b/elasticsearch/_async/client/indices.py index 4e9df53a..9614f858 100644 --- a/elasticsearch/_async/client/indices.py +++ b/elasticsearch/_async/client/indices.py @@ -1372,6 +1372,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit operation timeout @@ -1393,6 +1398,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg flat_settings: Return settings in flat format (default: false) @@ -1415,6 +1425,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The comma separated names of the index templates :arg flat_settings: Return settings in flat format (default: false) @@ -1434,6 +1449,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg body: The template definition :arg cause: User defined reason for creating/updating the index @@ -1462,6 +1482,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the index (it must be a concrete index name) :arg body: New index template definition, which will be included @@ -1505,6 +1530,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg body: New index template definition to be simulated, if no index template name is specified :arg name: The name of the index template @@ -1530,6 +1560,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: A comma-separated list of names or wildcard expressions :arg expand_wildcards: Whether wildcard expressions should get diff --git a/elasticsearch/_async/client/ml.py b/elasticsearch/_async/client/ml.py index d8f0ab56..2bb20892 100644 --- a/elasticsearch/_async/client/ml.py +++ b/elasticsearch/_async/client/ml.py @@ -278,6 +278,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg body: The contents of the file to be analyzed :arg charset: Optional parameter to specify the character set of the file @@ -1302,6 +1307,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to delete :arg force: True if the job should be forcefully deleted :arg timeout: Controls the time to wait until a job is deleted. @@ -1324,6 +1334,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg body: The evaluation definition """ if body in SKIP_IN_PATH: @@ -1344,6 +1359,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to fetch :arg allow_no_match: Whether to ignore if a wildcard expression matches no data frame analytics. (This includes `_all` string or when no @@ -1372,6 +1392,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics stats to fetch :arg allow_no_match: Whether to ignore if a wildcard expression matches no data frame analytics. (This includes `_all` string or when no @@ -1399,6 +1424,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to create :arg body: The data frame analytics configuration """ @@ -1423,6 +1453,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to start :arg body: The start data frame analytics parameters :arg timeout: Controls the time to wait until the task has @@ -1446,6 +1481,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to stop :arg body: The stop data frame analytics parameters :arg allow_no_match: Whether to ignore if a wildcard expression @@ -1475,6 +1515,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg model_id: The ID of the trained model to delete """ if model_id in SKIP_IN_PATH: @@ -1496,6 +1541,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg body: The data frame analytics config to explain :arg id: The ID of the data frame analytics to explain """ @@ -1523,6 +1573,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg model_id: The ID of the trained models to fetch :arg allow_no_match: Whether to ignore if a wildcard expression matches no trained models. (This includes `_all` string or when no @@ -1562,6 +1617,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg model_id: The ID of the trained models stats to fetch :arg allow_no_match: Whether to ignore if a wildcard expression matches no trained models. (This includes `_all` string or when no @@ -1588,6 +1648,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg model_id: The ID of the trained models to store :arg body: The trained model configuration """ @@ -1631,6 +1696,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to update :arg body: The data frame analytics settings to update """ diff --git a/elasticsearch/_async/client/monitoring.py b/elasticsearch/_async/client/monitoring.py index 15bbf5e5..30e40a80 100644 --- a/elasticsearch/_async/client/monitoring.py +++ b/elasticsearch/_async/client/monitoring.py @@ -26,6 +26,11 @@ class MonitoringClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg body: The operation definition and data (action-data pairs), separated by newlines :arg doc_type: Default document type for items which don't diff --git a/elasticsearch/_async/client/rollup.py b/elasticsearch/_async/client/rollup.py index 539f70f7..cd25f4ca 100644 --- a/elasticsearch/_async/client/rollup.py +++ b/elasticsearch/_async/client/rollup.py @@ -26,6 +26,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the job to delete """ if id in SKIP_IN_PATH: @@ -42,6 +47,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the job(s) to fetch. Accepts glob patterns, or left blank for all jobs """ @@ -57,6 +67,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the index to check rollup capabilities on, or left blank for all jobs """ @@ -72,6 +87,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg index: The rollup index or index pattern to obtain rollup capabilities from. """ @@ -89,6 +109,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the job to create :arg body: The job configuration """ @@ -113,6 +138,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg index: The indices or index-pattern(s) (containing rollup or regular data) that should be searched :arg body: The search request body @@ -141,6 +171,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the job to start """ if id in SKIP_IN_PATH: @@ -160,6 +195,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the job to stop :arg timeout: Block for (at maximum) the specified duration while waiting for the job to stop. Defaults to 30s. diff --git a/elasticsearch/_async/client/searchable_snapshots.py b/elasticsearch/_async/client/searchable_snapshots.py index 7e5cb92f..087deeca 100644 --- a/elasticsearch/_async/client/searchable_snapshots.py +++ b/elasticsearch/_async/client/searchable_snapshots.py @@ -26,6 +26,11 @@ class SearchableSnapshotsClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg index: A comma-separated list of index name to limit the operation :arg allow_no_indices: Whether to ignore if a wildcard indices @@ -51,6 +56,11 @@ class SearchableSnapshotsClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg repository: The name of the repository containing the snapshot of the index to mount :arg snapshot: The name of the snapshot of the index to mount @@ -80,6 +90,11 @@ class SearchableSnapshotsClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg repository: The repository for which to get the stats for """ if repository in SKIP_IN_PATH: @@ -99,6 +114,11 @@ class SearchableSnapshotsClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg index: A comma-separated list of index names """ return await self.transport.perform_request( diff --git a/elasticsearch/client/__init__.py b/elasticsearch/client/__init__.py index 155e9a2c..cf127125 100644 --- a/elasticsearch/client/__init__.py +++ b/elasticsearch/client/__init__.py @@ -1340,6 +1340,11 @@ class Elasticsearch(object): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg body: The ranking evaluation search definition, including search requests, document ratings and ranking metric definition. :arg index: A comma-separated list of index names to search; use @@ -1459,6 +1464,11 @@ class Elasticsearch(object): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg body: The script to execute """ return self.transport.perform_request( @@ -2050,6 +2060,11 @@ class Elasticsearch(object): Returns all script contexts. ``_ + + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version """ return self.transport.perform_request( "GET", "/_script_context", params=params, headers=headers @@ -2061,6 +2076,11 @@ class Elasticsearch(object): Returns available script types, languages and contexts ``_ + + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version """ return self.transport.perform_request( "GET", "/_script_language", params=params, headers=headers diff --git a/elasticsearch/client/autoscaling.py b/elasticsearch/client/autoscaling.py index d2dc7ed0..c1cd8bfe 100644 --- a/elasticsearch/client/autoscaling.py +++ b/elasticsearch/client/autoscaling.py @@ -19,18 +19,6 @@ from .utils import NamespacedClient, query_params, SKIP_IN_PATH, _make_path class AutoscalingClient(NamespacedClient): - @query_params() - def get_autoscaling_decision(self, params=None, headers=None): - """ - Gets the current autoscaling decision based on the configured autoscaling - policy, indicating whether or not autoscaling is needed. - - ``_ - """ - return self.transport.perform_request( - "GET", "/_autoscaling/decision", params=params, headers=headers - ) - @query_params() def delete_autoscaling_policy(self, name, params=None, headers=None): """ @@ -38,6 +26,11 @@ class AutoscalingClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: the name of the autoscaling policy """ if name in SKIP_IN_PATH: @@ -57,6 +50,11 @@ class AutoscalingClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: the name of the autoscaling policy """ if name in SKIP_IN_PATH: @@ -76,6 +74,11 @@ class AutoscalingClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: the name of the autoscaling policy :arg body: the specification of the autoscaling policy """ @@ -90,3 +93,20 @@ class AutoscalingClient(NamespacedClient): headers=headers, body=body, ) + + @query_params() + def get_autoscaling_capacity(self, params=None, headers=None): + """ + Gets the current autoscaling capacity based on the configured autoscaling + policy. + + ``_ + + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + """ + return self.transport.perform_request( + "GET", "/_autoscaling/capacity", params=params, headers=headers + ) diff --git a/elasticsearch/client/autoscaling.pyi b/elasticsearch/client/autoscaling.pyi index d9e786d6..d9ee4fa1 100644 --- a/elasticsearch/client/autoscaling.pyi +++ b/elasticsearch/client/autoscaling.pyi @@ -19,20 +19,6 @@ from typing import Any, MutableMapping, Optional, Union, Collection from .utils import NamespacedClient class AutoscalingClient(NamespacedClient): - def get_autoscaling_decision( - self, - *, - pretty: Optional[bool] = ..., - human: Optional[bool] = ..., - error_trace: Optional[bool] = ..., - format: Optional[str] = ..., - filter_path: Optional[Union[str, Collection[str]]] = ..., - request_timeout: Optional[Union[int, float]] = ..., - ignore: Optional[Union[int, Collection[int]]] = ..., - opaque_id: Optional[str] = ..., - params: Optional[MutableMapping[str, Any]] = ..., - headers: Optional[MutableMapping[str, str]] = ... - ) -> Any: ... def delete_autoscaling_policy( self, name: Any, @@ -79,3 +65,17 @@ class AutoscalingClient(NamespacedClient): params: Optional[MutableMapping[str, Any]] = ..., headers: Optional[MutableMapping[str, str]] = ... ) -> Any: ... + def get_autoscaling_capacity( + self, + *, + pretty: Optional[bool] = ..., + human: Optional[bool] = ..., + error_trace: Optional[bool] = ..., + format: Optional[str] = ..., + filter_path: Optional[Union[str, Collection[str]]] = ..., + request_timeout: Optional[Union[int, float]] = ..., + ignore: Optional[Union[int, Collection[int]]] = ..., + opaque_id: Optional[str] = ..., + params: Optional[MutableMapping[str, Any]] = ..., + headers: Optional[MutableMapping[str, str]] = ... + ) -> Any: ... diff --git a/elasticsearch/client/cluster.py b/elasticsearch/client/cluster.py index 539e4fc5..88e56b28 100644 --- a/elasticsearch/client/cluster.py +++ b/elasticsearch/client/cluster.py @@ -268,6 +268,11 @@ class ClusterClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit operation timeout @@ -289,6 +294,11 @@ class ClusterClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The comma separated names of the component templates :arg local: Return local information, do not retrieve the state from master node (default: false) @@ -309,6 +319,11 @@ class ClusterClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg body: The template definition :arg create: Whether the index template should only be added if @@ -335,6 +350,11 @@ class ClusterClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg local: Return local information, do not retrieve the state from master node (default: false) diff --git a/elasticsearch/client/eql.py b/elasticsearch/client/eql.py index 499febef..52b7c143 100644 --- a/elasticsearch/client/eql.py +++ b/elasticsearch/client/eql.py @@ -26,6 +26,11 @@ class EqlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg index: The name of the index to scope the operation :arg body: Eql request body. Use the `query` to limit the query scope. @@ -57,6 +62,11 @@ class EqlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The async search ID """ if id in SKIP_IN_PATH: @@ -74,6 +84,11 @@ class EqlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The async search ID :arg keep_alive: Update the time interval in which the results (partial or final) for this search will be available Default: 5d diff --git a/elasticsearch/client/indices.py b/elasticsearch/client/indices.py index ec4e9b7e..1abbd1f4 100644 --- a/elasticsearch/client/indices.py +++ b/elasticsearch/client/indices.py @@ -1368,6 +1368,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg master_timeout: Specify timeout for connection to master :arg timeout: Explicit operation timeout @@ -1389,6 +1394,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg flat_settings: Return settings in flat format (default: false) @@ -1411,6 +1421,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The comma separated names of the index templates :arg flat_settings: Return settings in flat format (default: false) @@ -1430,6 +1445,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the template :arg body: The template definition :arg cause: User defined reason for creating/updating the index @@ -1458,6 +1478,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: The name of the index (it must be a concrete index name) :arg body: New index template definition, which will be included @@ -1501,6 +1526,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg body: New index template definition to be simulated, if no index template name is specified :arg name: The name of the index template @@ -1526,6 +1556,11 @@ class IndicesClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg name: A comma-separated list of names or wildcard expressions :arg expand_wildcards: Whether wildcard expressions should get diff --git a/elasticsearch/client/ml.py b/elasticsearch/client/ml.py index 1f556f28..cbe5a8c9 100644 --- a/elasticsearch/client/ml.py +++ b/elasticsearch/client/ml.py @@ -270,6 +270,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg body: The contents of the file to be analyzed :arg charset: Optional parameter to specify the character set of the file @@ -1290,6 +1295,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to delete :arg force: True if the job should be forcefully deleted :arg timeout: Controls the time to wait until a job is deleted. @@ -1312,6 +1322,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg body: The evaluation definition """ if body in SKIP_IN_PATH: @@ -1332,6 +1347,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to fetch :arg allow_no_match: Whether to ignore if a wildcard expression matches no data frame analytics. (This includes `_all` string or when no @@ -1360,6 +1380,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics stats to fetch :arg allow_no_match: Whether to ignore if a wildcard expression matches no data frame analytics. (This includes `_all` string or when no @@ -1387,6 +1412,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to create :arg body: The data frame analytics configuration """ @@ -1409,6 +1439,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to start :arg body: The start data frame analytics parameters :arg timeout: Controls the time to wait until the task has @@ -1432,6 +1467,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to stop :arg body: The stop data frame analytics parameters :arg allow_no_match: Whether to ignore if a wildcard expression @@ -1461,6 +1501,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg model_id: The ID of the trained model to delete """ if model_id in SKIP_IN_PATH: @@ -1482,6 +1527,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg body: The data frame analytics config to explain :arg id: The ID of the data frame analytics to explain """ @@ -1509,6 +1559,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg model_id: The ID of the trained models to fetch :arg allow_no_match: Whether to ignore if a wildcard expression matches no trained models. (This includes `_all` string or when no @@ -1548,6 +1603,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg model_id: The ID of the trained models stats to fetch :arg allow_no_match: Whether to ignore if a wildcard expression matches no trained models. (This includes `_all` string or when no @@ -1574,6 +1634,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg model_id: The ID of the trained models to store :arg body: The trained model configuration """ @@ -1617,6 +1682,11 @@ class MlClient(NamespacedClient): ``_ + .. warning:: + + This API is **beta** so may include breaking changes + or be removed in a future version + :arg id: The ID of the data frame analytics to update :arg body: The data frame analytics settings to update """ diff --git a/elasticsearch/client/monitoring.py b/elasticsearch/client/monitoring.py index 665041cc..a9da548b 100644 --- a/elasticsearch/client/monitoring.py +++ b/elasticsearch/client/monitoring.py @@ -26,6 +26,11 @@ class MonitoringClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg body: The operation definition and data (action-data pairs), separated by newlines :arg doc_type: Default document type for items which don't diff --git a/elasticsearch/client/rollup.py b/elasticsearch/client/rollup.py index 7c81b3e9..92d5254c 100644 --- a/elasticsearch/client/rollup.py +++ b/elasticsearch/client/rollup.py @@ -26,6 +26,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the job to delete """ if id in SKIP_IN_PATH: @@ -42,6 +47,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the job(s) to fetch. Accepts glob patterns, or left blank for all jobs """ @@ -57,6 +67,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the index to check rollup capabilities on, or left blank for all jobs """ @@ -72,6 +87,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg index: The rollup index or index pattern to obtain rollup capabilities from. """ @@ -89,6 +109,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the job to create :arg body: The job configuration """ @@ -111,6 +136,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg index: The indices or index-pattern(s) (containing rollup or regular data) that should be searched :arg body: The search request body @@ -139,6 +169,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the job to start """ if id in SKIP_IN_PATH: @@ -158,6 +193,11 @@ class RollupClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg id: The ID of the job to stop :arg timeout: Block for (at maximum) the specified duration while waiting for the job to stop. Defaults to 30s. diff --git a/elasticsearch/client/searchable_snapshots.py b/elasticsearch/client/searchable_snapshots.py index 061eda0d..7426b4a0 100644 --- a/elasticsearch/client/searchable_snapshots.py +++ b/elasticsearch/client/searchable_snapshots.py @@ -26,6 +26,11 @@ class SearchableSnapshotsClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg index: A comma-separated list of index name to limit the operation :arg allow_no_indices: Whether to ignore if a wildcard indices @@ -51,6 +56,11 @@ class SearchableSnapshotsClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg repository: The name of the repository containing the snapshot of the index to mount :arg snapshot: The name of the snapshot of the index to mount @@ -80,6 +90,11 @@ class SearchableSnapshotsClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg repository: The repository for which to get the stats for """ if repository in SKIP_IN_PATH: @@ -99,6 +114,11 @@ class SearchableSnapshotsClient(NamespacedClient): ``_ + .. warning:: + + This API is **experimental** so may include breaking changes + or be removed in a future version + :arg index: A comma-separated list of index names """ return self.transport.perform_request( diff --git a/utils/generate_api.py b/utils/generate_api.py index 8c0b51de..dd6503a9 100644 --- a/utils/generate_api.py +++ b/utils/generate_api.py @@ -168,6 +168,8 @@ class API: self._def = definition self.description = "" self.doc_url = "" + self.stability = self._def.get("stability", "stable") + if isinstance(definition["documentation"], str): self.doc_url = definition["documentation"] else: diff --git a/utils/templates/base b/utils/templates/base index 82f5fae2..028fce3e 100644 --- a/utils/templates/base +++ b/utils/templates/base @@ -9,6 +9,13 @@ `<{{ api.doc_url }}>`_ {% endif %} + {% if api.stability != "stable" %} + + .. warning:: + + This API is **{{ api.stability }}** so may include breaking changes + or be removed in a future version + {% endif %} {% if api.params|list|length %} {% for p, info in api.params %}