From 08976f5d3abd266bde14f3788a1bb134cafd21c4 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Wed, 26 Jun 2024 11:59:17 +0400 Subject: [PATCH] Convert README to markdown for static HTML embedding --- MANIFEST.in | 2 +- README.md | 110 ++++++++++++++++++++++++++ README.rst | 124 ------------------------------ docs/logo-elastic-glyph-color.svg | 16 ++++ setup.py | 18 +---- 5 files changed, 130 insertions(+), 140 deletions(-) create mode 100644 README.md delete mode 100644 README.rst create mode 100644 docs/logo-elastic-glyph-color.svg diff --git a/MANIFEST.in b/MANIFEST.in index fc0d54c5de..f7a1c216de 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,7 +1,7 @@ include CONTRIBUTING.md include LICENSE include MANIFEST.in -include README.rst +include README.md include NOTICE include CHANGELOG.md include setup.py diff --git a/README.md b/README.md new file mode 100644 index 0000000000..80039ad4b4 --- /dev/null +++ b/README.md @@ -0,0 +1,110 @@ +

+ Elastic logo +

+ +# Elasticsearch Python Client + +

+ PyPI Version + Python Versions + Conda Version + Downloads +

+

+ Build Status on GitHub + Buildkite Status on Buildkite + Documentation Status
+ +*The official Python client for Elasticsearch.* +

+ + +## Features + +* Translating basic Python data types to and from JSON +* Configurable automatic discovery of cluster nodes +* Persistent connections +* Load balancing (with pluggable selection strategy) across available nodes +* Failed connection penalization (time based - failed connections won't be + retried until a timeout is reached) +* Support for TLS and HTTP authentication +* Thread safety across requests +* Pluggable architecture +* Helper functions for idiomatically using APIs together + + +## Installation + +[Download the latest version of Elasticsearch](https://www.elastic.co/downloads/elasticsearch) +or +[sign-up](https://cloud.elastic.co/registration?elektra=en-ess-sign-up-page) +for a free trial of Elastic Cloud. + +Refer to the [Installation section](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/getting-started-python.html#_installation) +of the getting started documentation. + + +## Connecting + +Refer to the [Connecting section](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/getting-started-python.html#_connecting) +of the getting started documentation. + + +## Usage +----- + +* [Creating an index](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/getting-started-python.html#_creating_an_index) +* [Indexing a document](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/getting-started-python.html#_indexing_documents) +* [Getting documents](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/getting-started-python.html#_getting_documents) +* [Searching documents](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/getting-started-python.html#_searching_documents) +* [Updating documents](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/getting-started-python.html#_updating_documents) +* [Deleting documents](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/getting-started-python.html#_deleting_documents) +* [Deleting an index](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/getting-started-python.html#_deleting_an_index) + + +## Compatibility + +Language clients are forward compatible; meaning that the clients support +communicating with greater or equal minor versions of Elasticsearch without +breaking. It does not mean that the clients automatically support new features +of newer Elasticsearch versions; it is only possible after a release of a new +client version. For example, a 8.12 client version won't automatically support +the new features of the 8.13 version of Elasticsearch, the 8.13 client version +is required for that. Elasticsearch language clients are only backwards +compatible with default distributions and without guarantees made. + +| Elasticsearch Version | Elasticsearch-PHP Branch | Supported | +| --------------------- | ------------------------ | --------- | +| main | main | | +| 8.x | 8.x | 8.x | +| 7.x | 7.x | 7.17 | + + +If you have a need to have multiple versions installed at the same time older +versions are also released as ``elasticsearch7`` and ``elasticsearch8``. + + +## Documentation + +Documentation for the client is [available on elastic.co] and [Read the Docs]. + +[available on elastic.co]: https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html +[Read the Docs]: https://elasticsearch-py.readthedocs.io + + +## Feedback 🗣️ + +The engineering team here at Elastic is looking for developers to participate in +research and feedback sessions to learn more about how you use our Python client and +what improvements we can make to their design and your workflow. If you're interested in +sharing your insights into developer experience and language client design, please fill +out this [short form]. Depending on the number of responses we get, we may either +contact you for a 1:1 conversation or a focus group with other developers who use the +same client. Thank you in advance - your feedback is crucial to improving the user +experience for all Elasticsearch developers! + +[short form]: https://forms.gle/bYZwDQXijfhfwshn9 + +## License + +This software is licensed under the [Apache License 2.0](./LICENSE). See [NOTICE](./NOTICE). diff --git a/README.rst b/README.rst deleted file mode 100644 index 83500a1aaf..0000000000 --- a/README.rst +++ /dev/null @@ -1,124 +0,0 @@ -.. raw:: html - - - -Elasticsearch Python Client -=========================== - -.. image:: https://img.shields.io/pypi/v/elasticsearch - :target: https://pypi.org/project/elasticsearch - -.. image:: https://img.shields.io/conda/vn/conda-forge/elasticsearch?color=blue - :target: https://anaconda.org/conda-forge/elasticsearch - -.. image:: https://static.pepy.tech/badge/elasticsearch - :target: https://pepy.tech/project/elasticsearch?versions=* - -.. image:: https://badge.buildkite.com/68e22afcb2ea8f6dcc20834e3a5b5ab4431beee33d3bd751f3.svg - :target: https://buildkite.com/elastic/elasticsearch-py-integration-tests - -.. image:: https://readthedocs.org/projects/elasticsearch-py/badge/?version=latest&style=flat - :target: https://elasticsearch-py.readthedocs.io - -*The official Python client for Elasticsearch.* - - -Features --------- - -* Translating basic Python data types to and from JSON -* Configurable automatic discovery of cluster nodes -* Persistent connections -* Load balancing (with pluggable selection strategy) across available nodes -* Failed connection penalization (time based - failed connections won't be - retried until a timeout is reached) -* Support for TLS and HTTP authentication -* Thread safety across requests -* Pluggable architecture -* Helper functions for idiomatically using APIs together - - -Installation ------------- - -`Download the latest version of Elasticsearch `_ -or -`sign-up `_ -for a free trial of Elastic Cloud. - -Refer to the `Installation section `_ -of the getting started documentation. - - -Connecting ----------- - -Refer to the `Connecting section `_ -of the getting started documentation. - - -Usage ------ - -* `Creating an index `_ -* `Indexing a document `_ -* `Getting documents `_ -* `Searching documents `_ -* `Updating documents `_ -* `Deleting documents `_ -* `Deleting an index `_ - - -Compatibility -------------- - -Language clients are forward compatible; meaning that the clients support -communicating with greater or equal minor versions of Elasticsearch without -breaking. It does not mean that the clients automatically support new features -of newer Elasticsearch versions; it is only possible after a release of a new -client version. For example, a 8.12 client version won't automatically support -the new features of the 8.13 version of Elasticsearch, the 8.13 client version -is required for that. Elasticsearch language clients are only backwards -compatible with default distributions and without guarantees made. - -+-----------------------+-------------------------+-----------+ -| Elasticsearch version | elasticsearch-py branch | Supported | -+=======================+=========================+===========+ -| main | main | | -+-----------------------+-------------------------+-----------+ -| 8.x | 8.x | 8.x | -+-----------------------+-------------------------+-----------+ -| 7.x | 7.x | 7.17 | -+-----------------------+-------------------------+-----------+ - -If you have a need to have multiple versions installed at the same time older -versions are also released as ``elasticsearch7`` and ``elasticsearch8``. - - -Documentation -------------- - -Documentation for the client is `available on elastic.co`_ and `Read the Docs`_. - -.. _available on elastic.co: https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html -.. _Read the Docs: https://elasticsearch-py.readthedocs.io - - -Feedback 🗣️ ------------ - -The engineering team here at Elastic is looking for developers to participate in -research and feedback sessions to learn more about how you use our Python client and -what improvements we can make to their design and your workflow. If you're interested in -sharing your insights into developer experience and language client design, please fill -out this `short form`_. Depending on the number of responses we get, we may either -contact you for a 1:1 conversation or a focus group with other developers who use the -same client. Thank you in advance - your feedback is crucial to improving the user -experience for all Elasticsearch developers! - -.. _short form: https://forms.gle/bYZwDQXijfhfwshn9 - -License -------- - -Copyright 2023 Elasticsearch B.V. Licensed under the Apache License, Version 2.0. diff --git a/docs/logo-elastic-glyph-color.svg b/docs/logo-elastic-glyph-color.svg new file mode 100644 index 0000000000..37a3492918 --- /dev/null +++ b/docs/logo-elastic-glyph-color.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/setup.py b/setup.py index 2910aeb3e3..93fd60f050 100644 --- a/setup.py +++ b/setup.py @@ -30,19 +30,7 @@ ).group(1) with open(join(base_dir, "README.rst")) as f: - # Remove reST raw directive from README as they're not allowed on PyPI - # Those blocks start with a newline and continue until the next newline - mode = None - lines = [] - for line in f: - if line.startswith(".. raw::"): - mode = "ignore_nl" - elif line == "\n": - mode = "wait_nl" if mode == "ignore_nl" else None - if mode is None: - lines.append(line) - - long_description = "".join(lines) + readme = f.read() packages = [ @@ -56,8 +44,8 @@ description="Python client for Elasticsearch", license="Apache-2.0", url="https://github.com/elastic/elasticsearch-py", - long_description=long_description, - long_description_content_type="text/x-rst", + long_description=readme, + long_description_content_type="text/markdown", version=package_version, author="Elastic Client Library Maintainers", author_email="client-libs@elastic.co",