From cb0497aa5298e8a7e74093c2d11e897285655e6f Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 27 Jun 2024 13:46:30 +0200 Subject: [PATCH 1/2] Documentation: Improve guidance about migrating to `sqlalchemy-cratedb` Mention the switchover both on the project's README, and the index page of the documentation, in order to give users who might be running into relevant flaws a better chance to discover the solution. Co-authored-by: Marios Trivyzas <5058131+matriv@users.noreply.github.com> --- README.rst | 18 +++++++++++++++--- docs/index.rst | 20 +++++++++++++++++--- 2 files changed, 32 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index 33811a00..ec7ce08b 100644 --- a/README.rst +++ b/README.rst @@ -58,7 +58,18 @@ To install the most recent driver version, run:: $ pip install --upgrade crate -Documentation and help +Migration Notes +=============== + +If you are migrating from previous versions of ``crate[sqlalchemy]<1.0.0``, you +will find that the newer releases ``crate>=1.0.0`` no longer include the +SQLAlchemy dialect for CrateDB. + +See `migrate to sqlalchemy-cratedb`_ for relevant guidelines about how to +successfully migrate to the `sqlalchemy-cratedb`_ package. + + +Documentation and Help ====================== - `CrateDB Python Client documentation`_ @@ -68,8 +79,8 @@ Documentation and help - Other `support channels`_ -Contributing -============ +Contributions +============= The CrateDB Python client library is an open source project, and is `managed on GitHub`_. We appreciate contributions of any kind. @@ -84,6 +95,7 @@ GitHub`_. We appreciate contributions of any kind. .. _DB API 2.0: https://peps.python.org/pep-0249/ .. _Developer documentation: DEVELOP.rst .. _managed on GitHub: https://github.com/crate/crate-python +.. _migrate to sqlalchemy-cratedb: https://cratedb.com/docs/sqlalchemy-cratedb/migrate-from-crate-client.html .. _PyPI: https://pypi.org/ .. _SQLAlchemy: https://www.sqlalchemy.org/ .. _sqlalchemy-cratedb: https://github.com/crate/sqlalchemy-cratedb diff --git a/docs/index.rst b/docs/index.rst index 6b941347..774fc2f8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,9 +27,6 @@ it has also been tested successfully with `PyPy`_. Please make sure to also visit the section about :ref:`other-options`, using the :ref:`crate-reference:interface-postgresql` interface of `CrateDB`_. -The :ref:`CrateDB dialect ` for `SQLAlchemy`_ is provided -by the ``sqlalchemy-cratedb`` package. - ************* Documentation @@ -98,6 +95,21 @@ please consult the :ref:`data-types` documentation page. data-types + +Migration Notes +=============== + +The :ref:`CrateDB dialect ` for `SQLAlchemy`_ is provided +by the `sqlalchemy-cratedb`_ package. + +If you are migrating from previous versions of ``crate[sqlalchemy]<1.0.0``, you +will find that the newer releases ``crate>=1.0.0`` no longer include the +SQLAlchemy dialect for CrateDB. + +See `migrate to sqlalchemy-cratedb`_ for relevant guidelines about how to +successfully migrate to the `sqlalchemy-cratedb`_ package. + + Examples ======== @@ -168,10 +180,12 @@ The project is licensed under the terms of the Apache 2.0 license, like .. _GeoJSON geometry objects: https://tools.ietf.org/html/rfc7946#section-3.1 .. _LICENSE: https://github.com/crate/crate-python/blob/master/LICENSE .. _managed on GitHub: https://github.com/crate/crate-python +.. _migrate to sqlalchemy-cratedb: https://cratedb.com/docs/sqlalchemy-cratedb/migrate-from-crate-client.html .. _pandas: https://en.wikipedia.org/wiki/Pandas_(software) .. _PEP 249: https://peps.python.org/pep-0249/ .. _PyPy: https://www.pypy.org/ .. _sample application: https://github.com/crate/crate-sample-apps/tree/main/python-flask .. _sample application documentation: https://github.com/crate/crate-sample-apps/blob/main/python-flask/documentation.md .. _SQLAlchemy: https://en.wikipedia.org/wiki/Sqlalchemy +.. _sqlalchemy-cratedb: https://github.com/crate/sqlalchemy-cratedb .. _Use CrateDB with pandas: https://github.com/crate/crate-qa/pull/246 From 4d61a4c596973b4a67bdf6680efd2821f1a1e88a Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 27 Jun 2024 14:34:30 +0200 Subject: [PATCH 2/2] Documentation: Improve "Examples" section on index page --- docs/index.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 774fc2f8..2fb2a7d6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -116,15 +116,16 @@ Examples - The :ref:`by-example` section enumerates concise examples demonstrating the different API interfaces of the CrateDB Python client library. Those are DB API, HTTP, and BLOB interfaces. + - Executable code examples are maintained within the `cratedb-examples repository`_. + `sqlalchemy-cratedb`_, `python-dataframe-examples`_, and `python-sqlalchemy-examples`_ + provide relevant code snippets about how to connect to CrateDB using + `SQLAlchemy`_, `pandas`_, or `Dask`_, and how to load and export data. + - The `sample application`_ and the corresponding `sample application documentation`_ demonstrate the use of the driver on behalf of an example - "guestbook" application. -- ``sqlalchemy-cratedb`` has relevant code snippets about how to - connect to CrateDB using `SQLAlchemy`_, `pandas`_, and `Dask`_. -- `Use CrateDB with pandas`_ has corresponding code snippets about how to - connect to CrateDB using `pandas`_, and how to load and export data. -- The `Apache Superset`_ and `FIWARE QuantumLeap data historian`_ projects. + "guestbook" application, using Flask. + .. toctree:: :maxdepth: 2 @@ -174,7 +175,7 @@ The project is licensed under the terms of the Apache 2.0 license, like .. _Create an issue: https://github.com/crate/crate-python/issues .. _Dask: https://en.wikipedia.org/wiki/Dask_(software) .. _development sandbox: https://github.com/crate/crate-python/blob/master/DEVELOP.rst -.. _cratedb-examples repository: https://github.com/crate/cratedb-examples/tree/main/by-language +.. _cratedb-examples repository: https://github.com/crate/cratedb-examples .. _FIWARE QuantumLeap data historian: https://github.com/orchestracities/ngsi-timeseries-api .. _GeoJSON: https://geojson.org/ .. _GeoJSON geometry objects: https://tools.ietf.org/html/rfc7946#section-3.1 @@ -184,6 +185,8 @@ The project is licensed under the terms of the Apache 2.0 license, like .. _pandas: https://en.wikipedia.org/wiki/Pandas_(software) .. _PEP 249: https://peps.python.org/pep-0249/ .. _PyPy: https://www.pypy.org/ +.. _python-dataframe-examples: https://github.com/crate/cratedb-examples/tree/main/by-dataframe +.. _python-sqlalchemy-examples: https://github.com/crate/cratedb-examples/tree/main/by-language/python-sqlalchemy .. _sample application: https://github.com/crate/crate-sample-apps/tree/main/python-flask .. _sample application documentation: https://github.com/crate/crate-sample-apps/blob/main/python-flask/documentation.md .. _SQLAlchemy: https://en.wikipedia.org/wiki/Sqlalchemy