crate 1.0.0__tar.gz → 1.0.0.dev1__tar.gz

{crate-1.0.0 → crate-1.0.0.dev1}/DEVELOP.rst

@@ -5,12 +5,6 @@ CrateDB Python developer guide
 Setup
 =====
 
-Optionally install Python package and project manager ``uv``,
-in order to significantly speed up the package installation::
-
-    {apt,brew,pip,zypper} install uv
-    alias pip="uv pip"
-
 To start things off, bootstrap the sandbox environment::
 
     git clone https://github.com/crate/crate-python
@@ -32,40 +26,34 @@ see, for example, `useful command-line options for zope-testrunner`_.
 
 Run all tests::
 
-    poe test
+    ./bin/test -vvvv
 
 Run specific tests::
 
-    # Select modules.
-    bin/test -t test_cursor
-    bin/test -t client
-    bin/test -t testing
-
-    # Select doctests.
-    bin/test -t http.rst
+    ./bin/test -vvvv -t test_score
 
 Ignore specific test directories::
 
-    bin/test --ignore_dir=testing
+    ./bin/test -vvvv --ignore_dir=testing
 
 The ``LayerTest`` test cases have quite some overhead. Omitting them will save
 a few cycles (~70 seconds runtime)::
 
-    bin/test -t '!LayerTest'
+    ./bin/test -t '!LayerTest'
 
-Invoke all tests without integration tests (~10 seconds runtime)::
+Invoke all tests without integration tests (~15 seconds runtime)::
 
-    bin/test --layer '!crate.testing.layer.crate' --test '!LayerTest'
+    ./bin/test --layer '!crate.testing.layer.crate' --test '!LayerTest'
 
-Yet ~60 test cases, but only ~1 second runtime::
+Yet ~130 test cases, but only ~5 seconds runtime::
 
-    bin/test --layer '!crate.testing.layer.crate' --test '!LayerTest' \
+    ./bin/test --layer '!crate.testing.layer.crate' --test '!LayerTest' \
         -t '!test_client_threaded' -t '!test_no_retry_on_read_timeout' \
         -t '!test_wait_for_http' -t '!test_table_clustered_by'
 
 To inspect the whole list of test cases, run::
 
-    bin/test --list-tests
+    ./bin/test --list-tests
 
 You can run the tests against multiple Python interpreters with `tox`_::
 
@@ -83,28 +71,11 @@ are listening on the default CrateDB transport port to avoid side effects with
 the test layer.
 
 
-Formatting and linting code
-===========================
-
-To use Ruff for code formatting, according to the standards configured in
-``pyproject.toml``, use::
-
-    poe format
-
-To lint the code base using Ruff and mypy, use::
-
-    poe lint
-
-Linting and software testing, all together now::
-
-    poe check
-
-
 Renew certificates
 ==================
 
 For conducting TLS connectivity tests, there are a few X.509 certificates at
-`tests/assets/pki/*.pem`_. In order to renew them, follow the instructions
+`src/crate/client/pki/*.pem`_. In order to renew them, follow the instructions
 within the README file in this folder.
 
 
@@ -121,7 +92,7 @@ In the release branch:
 
 - Update ``__version__`` in ``src/crate/client/__init__.py``
 
-- Add a section for the new version in the ``CHANGES.rst`` file
+- Add a section for the new version in the ``CHANGES.txt`` file
 
 - Commit your changes with a message like "prepare release x.y.z"
 
@@ -130,7 +101,7 @@ In the release branch:
 - Create a tag by running ``./devtools/create_tag.sh``. This will trigger a
   Github action which releases the new version to PyPi.
 
-On branch ``main``:
+On master:
 
 - Update the release notes to reflect the release
 
@@ -171,7 +142,7 @@ nothing special you need to do to get the live docs to update.
 .. _Read the Docs: http://readthedocs.org
 .. _ReStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Sphinx: http://sphinx-doc.org/
-.. _tests/assets/pki/*.pem: https://github.com/crate/crate-python/tree/main/tests/assets/pki
+.. _src/crate/client/pki/*.pem: https://github.com/crate/crate-python/tree/master/src/crate/client/pki
 .. _tox: http://testrun.org/tox/latest/
 .. _twine: https://pypi.python.org/pypi/twine
 .. _useful command-line options for zope-testrunner: https://pypi.org/project/zope.testrunner/#some-useful-command-line-options-to-get-you-started

{crate-1.0.0 → crate-1.0.0.dev1}/LICENSE

@@ -176,3 +176,73 @@
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+
+===============================================================================
+
+For the `docs` directory:
+
+The source files for the documentation are licensed under the Apache License
+Version 2.0. These source files are used by the project maintainers to build
+online documentation for end-users:
+
+  <https://crate.io/docs/clients/python/en/latest/>
+
+If you want to make contributions to the documentation, it may be necessary for
+you to build the documentation yourself by following the instructions in the
+`DEVELOP.rst` file. If you do this, a number of third-party software components
+are necessary.
+
+We do not ship the source code for these optional third-party software
+components or their dependencies, so we cannot make any guarantees about the
+licensing status of these components.
+
+However, for convenience, the documentation build system explicitly references
+the following software components (grouped by license):
+
+PSF License:
+
+ - Python 3 <https://docs.python.org/3/license.html>
+
+MIT License:
+
+ - pip <https://pypi.org/project/pip/>
+ - setuptools <https://pypi.org/project/setuptools/>
+ - sphinx-autobuild <https://pypi.org/project/sphinx-autobuild/>
+
+BSD License:
+
+ - alabaster <https://pypi.org/project/alabaster/>
+ - sphinx <https://pypi.org/project/Sphinx/>
+
+Apache License 2.0:
+
+ - crate-docs-theme <https://pypi.org/project/crate-docs-theme/>
+
+Please note that each of these components may specify its own dependencies and
+those dependencies may be licensed differently.

crate-1.0.0.dev1/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include *.rst
+recursive-include docs *.txt
+recursive-include src *.txt *.rst
+recursive-exclude src tests*.py

{crate-1.0.0 → crate-1.0.0.dev1}/NOTICE

@@ -1,5 +1,5 @@
 CrateDB Python Adapter
-Copyright 2013-2024 Crate.IO GmbH ("Crate")
+Copyright 2013-2022 Crate.IO GmbH ("Crate")
 
 
 Licensed to Crate.IO GmbH (referred to in this notice as "Crate") under one or

{crate-1.0.0 → crate-1.0.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: crate
-Version: 1.0.0
+Version: 1.0.0.dev1
 Summary: CrateDB Python Client
 Home-page: https://github.com/crate/crate-python
 Author: Crate.io
@@ -21,32 +21,15 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Database
 Requires-Python: >=3.6
 Description-Content-Type: text/x-rst
+Provides-Extra: test
+Provides-Extra: doc
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: urllib3
-Requires-Dist: verlib2
-Provides-Extra: doc
-Requires-Dist: crate-docs-theme>=0.26.5; extra == "doc"
-Requires-Dist: sphinx<9,>=3.5; extra == "doc"
-Provides-Extra: test
-Requires-Dist: backports.zoneinfo<1; python_version < "3.9" and extra == "test"
-Requires-Dist: certifi; extra == "test"
-Requires-Dist: createcoverage<2,>=1; extra == "test"
-Requires-Dist: mypy<1.14; extra == "test"
-Requires-Dist: poethepoet<0.30; extra == "test"
-Requires-Dist: ruff<0.8; extra == "test"
-Requires-Dist: stopit<2,>=1.1.2; extra == "test"
-Requires-Dist: tox<5,>=3; extra == "test"
-Requires-Dist: pytz; extra == "test"
-Requires-Dist: zc.customdoctests<2,>=1.0.1; extra == "test"
-Requires-Dist: zope.testing<6,>=4; extra == "test"
-Requires-Dist: zope.testrunner<7,>=5; extra == "test"
 
 =====================
 CrateDB Python Client
@@ -56,7 +39,7 @@ CrateDB Python Client
     :target: https://github.com/crate/crate-python/actions?workflow=Tests
     :alt: Build status
 
-.. image:: https://codecov.io/gh/crate/crate-python/branch/main/graph/badge.svg
+.. image:: https://codecov.io/gh/crate/crate-python/branch/master/graph/badge.svg
     :target: https://app.codecov.io/gh/crate/crate-python
     :alt: Coverage
 
@@ -152,3 +135,5 @@ GitHub`_. We appreciate contributions of any kind.
 .. _sqlalchemy-cratedb documentation: https://cratedb.com/docs/sqlalchemy-cratedb/
 .. _StackOverflow: https://stackoverflow.com/tags/cratedb
 .. _support channels: https://cratedb.com/support/
+
+

{crate-1.0.0 → crate-1.0.0.dev1}/README.rst

@@ -6,7 +6,7 @@ CrateDB Python Client
     :target: https://github.com/crate/crate-python/actions?workflow=Tests
     :alt: Build status
 
-.. image:: https://codecov.io/gh/crate/crate-python/branch/main/graph/badge.svg
+.. image:: https://codecov.io/gh/crate/crate-python/branch/master/graph/badge.svg
     :target: https://app.codecov.io/gh/crate/crate-python
     :alt: Coverage
 

crate-1.0.0.dev1/docs/.crate-docs/.build/_sources/appendices/data-types.rst.txt

@@ -0,0 +1,158 @@
+.. _data-types:
+
+==========
+Data types
+==========
+
+The :ref:`Database API client <connect>` and the :ref:`SQLAlchemy dialect
+<using-sqlalchemy>` use different Python data types. Consult the corresponding
+section for further information.
+
+.. rubric:: Table of contents
+
+.. contents::
+   :local:
+
+.. _data-types-db-api:
+
+Database API client
+===================
+
+This section documents data types for the CrateDB :ref:`Database API client
+<connect>`.
+
+.. CAUTION::
+
+    The CrateDB Database API client implementation is incomplete. For the time
+    being, the client uses native Python types.
+
+In general, types are mapped as follows:
+
+============= ===========
+CrateDB       Python
+============= ===========
+`boolean`__   `boolean`__
+`string`__    `str`__
+`int`__       `int`__
+`long`__      `int`__
+`short`__     `int`__
+`double`__    `float`__
+
+`float`__     `float`__
+`byte`__      `int`__
+`geo_point`__ `list`__
+`geo_shape`__ `dict`__
+`object`__    `dict`__
+`array`__     `list`__
+============= ===========
+
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#boolean
+__ https://docs.python.org/3/library/stdtypes.html#boolean-values
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#character-data
+__ https://docs.python.org/3/library/stdtypes.html#str
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ https://docs.python.org/3/library/functions.html#int
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ https://docs.python.org/3/library/functions.html#int
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ https://docs.python.org/3/library/functions.html#int
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ https://docs.python.org/3/library/functions.html#float
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ https://docs.python.org/3/library/functions.html#float
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ https://docs.python.org/3/library/functions.html#int
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#geo-point
+__ https://docs.python.org/3/library/stdtypes.html#list
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#geo-shape
+__ https://docs.python.org/3/library/stdtypes.html#dict
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#object
+__ https://docs.python.org/3/library/stdtypes.html#dict
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#array
+__ https://docs.python.org/3/library/stdtypes.html#list
+
+When writing to CrateDB, the following conversions take place:
+
+============= ====================================
+Python        CrateDB
+============= ====================================
+`Decimal`__   `string`__
+`date`__      `integer`__, `long`__, or `string`__
+`datetime`__  `integer`__, `long`__, or `string`__
+============= ====================================
+
+__ https://docs.python.org/3/library/decimal.html
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#character-data
+__ https://docs.python.org/3/library/datetime.html#date-objects
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#character-data
+__ https://docs.python.org/3/library/datetime.html#datetime-objects
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#character-data
+
+.. NOTE::
+
+    The type that ``date`` and ``datetime`` objects are mapped depends on the
+    CrateDB column type.
+
+.. _data-types-sqlalchemy:
+
+SQLAlchemy
+==========
+
+This section documents data types for the CrateDB :ref:`SQLAlchemy dialect
+<using-sqlalchemy>`.
+
+.. _sqlalchemy-type-map:
+
+Type map
+--------
+
+The CrateDB dialect maps between data types like so:
+
+================= =========================================
+CrateDB           SQLAlchemy
+================= =========================================
+`boolean`__       `Boolean`__
+`byte`__          `SmallInteger`__
+`short`__         `SmallInteger`__
+`integer`__       `Integer`__
+`long`__          `NUMERIC`__
+`float`__         `Float`__
+`double`__        `DECIMAL`__
+`timestamp`__     `TIMESTAMP`__
+`string`__        `String`__
+`array`__         `ARRAY`__
+`object`__        :ref:`object` |nbsp| (extension type)
+`array(object)`__ :ref:`objectarray` |nbsp| (extension type)
+`geo_point`__     :ref:`geopoint` |nbsp| (extension type)
+`geo_shape`__     :ref:`geoshape` |nbsp| (extension type)
+================= =========================================
+
+
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#boolean
+__ http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.Boolean
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.SmallInteger
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.SmallInteger
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.Integer
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.NUMERIC
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.Float
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#numeric-data
+__ http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.DECIMAL
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#dates-and-times
+__ http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.TIMESTAMP
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#character-data
+__ http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.String
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#array
+__ http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.ARRAY
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#object
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#array
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#geo-point
+__ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#geo-shape

crate-1.0.0.dev1/docs/.crate-docs/.build/_sources/appendices/index.rst.txt

@@ -0,0 +1,14 @@
+.. _appendices:
+
+==========
+Appendices
+==========
+
+Supplementary information for the CrateDB Python client library.
+
+.. rubric:: Table of contents
+
+.. toctree::
+   :maxdepth: 2
+
+   data-types

crate-1.0.0/docs/by-example/connection.rst → crate-1.0.0.dev1/docs/.crate-docs/.build/_sources/by-example/connection.rst.txt

@@ -21,7 +21,7 @@ connect()
 This section sets up a connection object, and inspects some of its attributes.
 
     >>> from crate.client import connect
-    >>> from crate.testing.util import ClientMocked
+    >>> from crate.client.test_util import ClientMocked
 
     >>> connection = connect(client=ClientMocked())
     >>> connection.lowest_server_version.version

crate-1.0.0/docs/by-example/cursor.rst → crate-1.0.0.dev1/docs/.crate-docs/.build/_sources/by-example/cursor.rst.txt

@@ -23,7 +23,7 @@ up the response for subsequent cursor operations.
     >>> from crate.client import connect
     >>> from crate.client.converter import DefaultTypeConverter
     >>> from crate.client.cursor import Cursor
-    >>> from crate.testing.util import ClientMocked
+    >>> from crate.client.test_util import ClientMocked
 
     >>> connection = connect(client=ClientMocked())
     >>> cursor = connection.cursor()
@@ -333,7 +333,7 @@ types. Currently, this is implemented for the CrateDB data types ``IP`` and
     >>> cursor.execute('')
 
     >>> cursor.fetchone()
-    ['foo', IPv4Address('10.10.10.1'), datetime.datetime(2022, 7, 18, 18, 10, 36, 758000, tzinfo=datetime.timezone.utc)]
+    ['foo', IPv4Address('10.10.10.1'), datetime.datetime(2022, 7, 18, 18, 10, 36, 758000)]
 
 
 Custom data type conversion
@@ -374,7 +374,8 @@ Proof that the converter works correctly, ``B\'0110\'`` should be converted to
 =======================================
 
 Based on the data type converter functionality, the driver offers a convenient
-interface to make it return ``datetime`` objects using the desired time zone.
+interface to make it return timezone-aware ``datetime`` objects, using the
+desired time zone.
 
 For your reference, in the following examples, epoch 1658167836758 is
 ``Mon, 18 Jul 2022 18:10:36 GMT``.

crate-1.0.0/docs/by-example/http.rst → crate-1.0.0.dev1/docs/.crate-docs/.build/_sources/by-example/http.rst.txt

@@ -42,7 +42,7 @@ When using a list of servers, the servers are selected by round-robin:
 
     >>> invalid_host = "invalid_host:9999"
     >>> even_more_invalid_host = "even_more_invalid_host:9999"
-    >>> http_client = HttpClient([crate_host, invalid_host, even_more_invalid_host], timeout=0.3)
+    >>> http_client = HttpClient([crate_host, invalid_host, even_more_invalid_host])
     >>> http_client._get_server()
     'http://127.0.0.1:44209'
 
@@ -56,19 +56,17 @@ When using a list of servers, the servers are selected by round-robin:
 
 Servers with connection errors will be removed from the active server list:
 
-    >>> http_client = HttpClient([invalid_host, even_more_invalid_host, crate_host], timeout=0.3)
+    >>> http_client = HttpClient([invalid_host, even_more_invalid_host, crate_host])
     >>> result = http_client.sql('select name from locations')
     >>> http_client._active_servers
     ['http://127.0.0.1:44209']
 
 Inactive servers will be re-added after a given time interval.
-To validate this, set the interval and timeout very short, and
-sleep after the first request::
+To validate this, set the interval very short and sleep for that interval:
 
     >>> http_client.retry_interval = 1
-    >>> result = http_client.sql('select name from locations')
     >>> import time; time.sleep(1)
-    >>> server = http_client._get_server()
+    >>> result = http_client.sql('select name from locations')
     >>> http_client._active_servers
     ['http://invalid_host:9999',
      'http://even_more_invalid_host:9999',
@@ -78,7 +76,7 @@ sleep after the first request::
 If no active servers are available and the retry interval is not reached, just use the oldest
 inactive one:
 
-    >>> http_client = HttpClient([invalid_host, even_more_invalid_host, crate_host], timeout=0.3)
+    >>> http_client = HttpClient([invalid_host, even_more_invalid_host, crate_host])
     >>> result = http_client.sql('select name from locations')
     >>> http_client._active_servers = []
     >>> http_client._get_server()