influxdb3-python 0.19.0__tar.gz → 0.20.0__tar.gz

{influxdb3_python-0.19.0 → influxdb3_python-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: influxdb3-python
-Version: 0.19.0
+Version: 0.20.0
 Summary: Community Python client for InfluxDB 3.0
 Home-page: https://github.com/InfluxCommunity/influxdb3-python
 Author: InfluxData
@@ -96,12 +96,52 @@ You can install 'influxdb3-python' using `pip`:
 pip install influxdb3-python
 ```
 
-Note: This does not include Pandas support. If you would like to use key features such as `to_pandas()`  and `write_file()` you will need to install `pandas` separately.
+Note: This does not include Pandas support. If you would like to use key features such as `to_pandas()`  and `write_file()`, or to use PyArrow data conversion methods with nanosecond timestamp precision, you will need to install `pandas` separately.
 
 *Note: Please make sure you are using 3.9 or above. For the best performance use 3.11+*
 
+## CLI (Agent-Friendly Query Tool)
+
+This package includes an `influx3` CLI for read/query workflows.
+
+### Run a query
+
+```bash
+influx3 query -d my_database "SELECT * FROM cpu LIMIT 5"
+```
+
+By default, output is JSON to stdout.
+
+### Supported formats
+
+- `json` (default)
+- `jsonl`
+- `csv`
+- `pretty`
+
+```bash
+influx3 query -d my_database --format csv "SELECT * FROM cpu LIMIT 5"
+```
+
+### Config precedence
+
+Configuration values are resolved in this order:
+
+1. CLI flags
+2. `INFLUXDB3_*` environment variables
+3. legacy `INFLUX_*` environment variables
+4. built-in defaults (host defaults to `http://127.0.0.1:8181`)
+
+Relevant environment variables:
+
+- `INFLUXDB3_HOST_URL` (legacy fallback: `INFLUX_HOST`)
+- `INFLUXDB3_DATABASE_NAME` (legacy fallback: `INFLUX_DATABASE`)
+- `INFLUXDB3_AUTH_TOKEN` (legacy fallback: `INFLUX_TOKEN`)
+
 # Usage
-One of the easiest ways to get started is to checkout the ["Pokemon Trainer Cookbook"](https://github.com/InfluxCommunity/influxdb3-python/blob/main/Examples/pokemon-trainer/cookbook.ipynb). This scenario takes you through the basics of both the client library and Pyarrow.
+One of the easiest ways to get started is to check out the ["Influxdb3 Python Basic Usage"](https://github.com/InfluxCommunity/influxdb3-python/blob/main/examples/jupyter/basic-write-query.ipynb) notebook. This scenario takes you through the core write and read APIs of the client library.
+
+Additional examples independent of jupyter are detailed in the [`./examples`](./examples/README.md) directory.
 
 ## Importing the Module
 ```python
@@ -252,6 +292,56 @@ client.write_dataframe(
 )
 ```
 
+### Accept partial writes and inspect failed lines
+`accept_partial` defaults to `True` and allows partial success when writing through the V3 API endpoint (`use_v2_api=False`) and a batch contains invalid lines.
+On partial failure, the client raises `InfluxDBPartialWriteError` with structured `line_errors`.
+
+```python
+from influxdb_client_3 import InfluxDBClient3
+from influxdb_client_3.exceptions import InfluxDBPartialWriteError
+
+client = InfluxDBClient3(
+    host="http://localhost:8181",
+    token="token",
+    database="db",
+    write_use_v2_api=False,
+)
+lp = "home,room=Sunroom temp=96 1735545600\nhome,room=Sunroom temp=\"hi\" 1735549200"
+
+try:
+    client.write(lp)  # accept_partial=True by default on V3 API endpoint
+except InfluxDBPartialWriteError as e:
+    for line_err in e.line_errors:
+        print(f"line {line_err.line_number} failed: {line_err.error_message} ({line_err.original_line})")
+```
+
+Disable partial writes:
+```python
+client = InfluxDBClient3(
+    host="http://localhost:8181",
+    token="token",
+    database="db",
+    write_use_v2_api=False,
+    write_accept_partial=False,
+)
+```
+
+### Compatibility with InfluxDB Clustered and InfluxDB Cloud Dedicated/Serverless
+Writes use the V2 API endpoint by default, so no additional configuration is required for these products.
+
+`use_v2_api` can be configured by:
+- `WriteOptions(use_v2_api=False)` (for V3 API endpoint features)
+- constructor kwarg: `write_use_v2_api=False`
+- env var: `INFLUX_WRITE_USE_V2_API=false`
+
+When `use_v2_api=True`:
+- `accept_partial` is not used
+- `no_sync=True` is invalid and rejected before dispatch with:
+  `invalid write options: no_sync cannot be used with use_v2_api`
+
+To use `no_sync` or `accept_partial` controls, set `use_v2_api=False`
+(for example with InfluxDB 3 Core/Enterprise).
+
 ## Querying
 
 ### Querying with SQL

{influxdb3_python-0.19.0 → influxdb3_python-0.20.0}/README.md

@@ -47,12 +47,52 @@ You can install 'influxdb3-python' using `pip`:
 pip install influxdb3-python
 ```
 
-Note: This does not include Pandas support. If you would like to use key features such as `to_pandas()`  and `write_file()` you will need to install `pandas` separately.
+Note: This does not include Pandas support. If you would like to use key features such as `to_pandas()`  and `write_file()`, or to use PyArrow data conversion methods with nanosecond timestamp precision, you will need to install `pandas` separately.
 
 *Note: Please make sure you are using 3.9 or above. For the best performance use 3.11+*
 
+## CLI (Agent-Friendly Query Tool)
+
+This package includes an `influx3` CLI for read/query workflows.
+
+### Run a query
+
+```bash
+influx3 query -d my_database "SELECT * FROM cpu LIMIT 5"
+```
+
+By default, output is JSON to stdout.
+
+### Supported formats
+
+- `json` (default)
+- `jsonl`
+- `csv`
+- `pretty`
+
+```bash
+influx3 query -d my_database --format csv "SELECT * FROM cpu LIMIT 5"
+```
+
+### Config precedence
+
+Configuration values are resolved in this order:
+
+1. CLI flags
+2. `INFLUXDB3_*` environment variables
+3. legacy `INFLUX_*` environment variables
+4. built-in defaults (host defaults to `http://127.0.0.1:8181`)
+
+Relevant environment variables:
+
+- `INFLUXDB3_HOST_URL` (legacy fallback: `INFLUX_HOST`)
+- `INFLUXDB3_DATABASE_NAME` (legacy fallback: `INFLUX_DATABASE`)
+- `INFLUXDB3_AUTH_TOKEN` (legacy fallback: `INFLUX_TOKEN`)
+
 # Usage
-One of the easiest ways to get started is to checkout the ["Pokemon Trainer Cookbook"](https://github.com/InfluxCommunity/influxdb3-python/blob/main/Examples/pokemon-trainer/cookbook.ipynb). This scenario takes you through the basics of both the client library and Pyarrow.
+One of the easiest ways to get started is to check out the ["Influxdb3 Python Basic Usage"](https://github.com/InfluxCommunity/influxdb3-python/blob/main/examples/jupyter/basic-write-query.ipynb) notebook. This scenario takes you through the core write and read APIs of the client library.
+
+Additional examples independent of jupyter are detailed in the [`./examples`](./examples/README.md) directory.
 
 ## Importing the Module
 ```python
@@ -203,6 +243,56 @@ client.write_dataframe(
 )
 ```
 
+### Accept partial writes and inspect failed lines
+`accept_partial` defaults to `True` and allows partial success when writing through the V3 API endpoint (`use_v2_api=False`) and a batch contains invalid lines.
+On partial failure, the client raises `InfluxDBPartialWriteError` with structured `line_errors`.
+
+```python
+from influxdb_client_3 import InfluxDBClient3
+from influxdb_client_3.exceptions import InfluxDBPartialWriteError
+
+client = InfluxDBClient3(
+    host="http://localhost:8181",
+    token="token",
+    database="db",
+    write_use_v2_api=False,
+)
+lp = "home,room=Sunroom temp=96 1735545600\nhome,room=Sunroom temp=\"hi\" 1735549200"
+
+try:
+    client.write(lp)  # accept_partial=True by default on V3 API endpoint
+except InfluxDBPartialWriteError as e:
+    for line_err in e.line_errors:
+        print(f"line {line_err.line_number} failed: {line_err.error_message} ({line_err.original_line})")
+```
+
+Disable partial writes:
+```python
+client = InfluxDBClient3(
+    host="http://localhost:8181",
+    token="token",
+    database="db",
+    write_use_v2_api=False,
+    write_accept_partial=False,
+)
+```
+
+### Compatibility with InfluxDB Clustered and InfluxDB Cloud Dedicated/Serverless
+Writes use the V2 API endpoint by default, so no additional configuration is required for these products.
+
+`use_v2_api` can be configured by:
+- `WriteOptions(use_v2_api=False)` (for V3 API endpoint features)
+- constructor kwarg: `write_use_v2_api=False`
+- env var: `INFLUX_WRITE_USE_V2_API=false`
+
+When `use_v2_api=True`:
+- `accept_partial` is not used
+- `no_sync=True` is invalid and rejected before dispatch with:
+  `invalid write options: no_sync cannot be used with use_v2_api`
+
+To use `no_sync` or `accept_partial` controls, set `use_v2_api=False`
+(for example with InfluxDB 3 Core/Enterprise).
+
 ## Querying
 
 ### Querying with SQL

{influxdb3_python-0.19.0 → influxdb3_python-0.20.0}/influxdb3_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: influxdb3-python
-Version: 0.19.0
+Version: 0.20.0
 Summary: Community Python client for InfluxDB 3.0
 Home-page: https://github.com/InfluxCommunity/influxdb3-python
 Author: InfluxData
@@ -96,12 +96,52 @@ You can install 'influxdb3-python' using `pip`:
 pip install influxdb3-python
 ```
 
-Note: This does not include Pandas support. If you would like to use key features such as `to_pandas()`  and `write_file()` you will need to install `pandas` separately.
+Note: This does not include Pandas support. If you would like to use key features such as `to_pandas()`  and `write_file()`, or to use PyArrow data conversion methods with nanosecond timestamp precision, you will need to install `pandas` separately.
 
 *Note: Please make sure you are using 3.9 or above. For the best performance use 3.11+*
 
+## CLI (Agent-Friendly Query Tool)
+
+This package includes an `influx3` CLI for read/query workflows.
+
+### Run a query
+
+```bash
+influx3 query -d my_database "SELECT * FROM cpu LIMIT 5"
+```
+
+By default, output is JSON to stdout.
+
+### Supported formats
+
+- `json` (default)
+- `jsonl`
+- `csv`
+- `pretty`
+
+```bash
+influx3 query -d my_database --format csv "SELECT * FROM cpu LIMIT 5"
+```
+
+### Config precedence
+
+Configuration values are resolved in this order:
+
+1. CLI flags
+2. `INFLUXDB3_*` environment variables
+3. legacy `INFLUX_*` environment variables
+4. built-in defaults (host defaults to `http://127.0.0.1:8181`)
+
+Relevant environment variables:
+
+- `INFLUXDB3_HOST_URL` (legacy fallback: `INFLUX_HOST`)
+- `INFLUXDB3_DATABASE_NAME` (legacy fallback: `INFLUX_DATABASE`)
+- `INFLUXDB3_AUTH_TOKEN` (legacy fallback: `INFLUX_TOKEN`)
+
 # Usage
-One of the easiest ways to get started is to checkout the ["Pokemon Trainer Cookbook"](https://github.com/InfluxCommunity/influxdb3-python/blob/main/Examples/pokemon-trainer/cookbook.ipynb). This scenario takes you through the basics of both the client library and Pyarrow.
+One of the easiest ways to get started is to check out the ["Influxdb3 Python Basic Usage"](https://github.com/InfluxCommunity/influxdb3-python/blob/main/examples/jupyter/basic-write-query.ipynb) notebook. This scenario takes you through the core write and read APIs of the client library.
+
+Additional examples independent of jupyter are detailed in the [`./examples`](./examples/README.md) directory.
 
 ## Importing the Module
 ```python
@@ -252,6 +292,56 @@ client.write_dataframe(
 )
 ```
 
+### Accept partial writes and inspect failed lines
+`accept_partial` defaults to `True` and allows partial success when writing through the V3 API endpoint (`use_v2_api=False`) and a batch contains invalid lines.
+On partial failure, the client raises `InfluxDBPartialWriteError` with structured `line_errors`.
+
+```python
+from influxdb_client_3 import InfluxDBClient3
+from influxdb_client_3.exceptions import InfluxDBPartialWriteError
+
+client = InfluxDBClient3(
+    host="http://localhost:8181",
+    token="token",
+    database="db",
+    write_use_v2_api=False,
+)
+lp = "home,room=Sunroom temp=96 1735545600\nhome,room=Sunroom temp=\"hi\" 1735549200"
+
+try:
+    client.write(lp)  # accept_partial=True by default on V3 API endpoint
+except InfluxDBPartialWriteError as e:
+    for line_err in e.line_errors:
+        print(f"line {line_err.line_number} failed: {line_err.error_message} ({line_err.original_line})")
+```
+
+Disable partial writes:
+```python
+client = InfluxDBClient3(
+    host="http://localhost:8181",
+    token="token",
+    database="db",
+    write_use_v2_api=False,
+    write_accept_partial=False,
+)
+```
+
+### Compatibility with InfluxDB Clustered and InfluxDB Cloud Dedicated/Serverless
+Writes use the V2 API endpoint by default, so no additional configuration is required for these products.
+
+`use_v2_api` can be configured by:
+- `WriteOptions(use_v2_api=False)` (for V3 API endpoint features)
+- constructor kwarg: `write_use_v2_api=False`
+- env var: `INFLUX_WRITE_USE_V2_API=false`
+
+When `use_v2_api=True`:
+- `accept_partial` is not used
+- `no_sync=True` is invalid and rejected before dispatch with:
+  `invalid write options: no_sync cannot be used with use_v2_api`
+
+To use `no_sync` or `accept_partial` controls, set `use_v2_api=False`
+(for example with InfluxDB 3 Core/Enterprise).
+
 ## Querying
 
 ### Querying with SQL

{influxdb3_python-0.19.0 → influxdb3_python-0.20.0}/influxdb3_python.egg-info/SOURCES.txt

@@ -2,26 +2,15 @@ LICENSE
 README.md
 pyproject.toml
 setup.py
-Examples/__init__.py
-Examples/basic_ssl_example.py
-Examples/batching_example.py
-Examples/cloud_dedicated_query.py
-Examples/cloud_dedicated_write.py
-Examples/config.py
-Examples/flight_options_example.py
-Examples/handle_http_error.py
-Examples/handle_query_error.py
-Examples/pandas_write.py
-Examples/query_async.py
-Examples/query_type.py
-Examples/query_with_middleware.py
-Examples/timeouts.py
 influxdb3_python.egg-info/PKG-INFO
 influxdb3_python.egg-info/SOURCES.txt
 influxdb3_python.egg-info/dependency_links.txt
+influxdb3_python.egg-info/entry_points.txt
 influxdb3_python.egg-info/requires.txt
 influxdb3_python.egg-info/top_level.txt
 influxdb_client_3/__init__.py
+influxdb_client_3/__main__.py
+influxdb_client_3/cli.py
 influxdb_client_3/py.typed
 influxdb_client_3/read_file.py
 influxdb_client_3/version.py
@@ -33,6 +22,7 @@ influxdb_client_3/write_client/__init__.py
 influxdb_client_3/write_client/configuration.py
 influxdb_client_3/write_client/extras.py
 influxdb_client_3/write_client/rest.py
+influxdb_client_3/write_client/write_defaults.py
 influxdb_client_3/write_client/_sync/__init__.py
 influxdb_client_3/write_client/_sync/api_client.py
 influxdb_client_3/write_client/_sync/rest.py
@@ -57,10 +47,9 @@ influxdb_client_3/write_client/domain/write_precision.py
 influxdb_client_3/write_client/domain/write_precision_converter.py
 influxdb_client_3/write_client/service/__init__.py
 influxdb_client_3/write_client/service/_base_service.py
-influxdb_client_3/write_client/service/signin_service.py
-influxdb_client_3/write_client/service/signout_service.py
 influxdb_client_3/write_client/service/write_service.py
 tests/test_api_client.py
+tests/test_cli.py
 tests/test_dataframe_serializer.py
 tests/test_date_helper.py
 tests/test_deep_merge.py

influxdb3_python-0.20.0/influxdb3_python.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+influx3 = influxdb_client_3.cli:main

{influxdb3_python-0.19.0 → influxdb3_python-0.20.0}/influxdb3_python.egg-info/top_level.txt

@@ -1,2 +1 @@
-Examples
 influxdb_client_3

{influxdb3_python-0.19.0 → influxdb3_python-0.20.0}/influxdb_client_3/__init__.py

@@ -29,6 +29,8 @@ INFLUX_PRECISION = "INFLUX_PRECISION"
 INFLUX_AUTH_SCHEME = "INFLUX_AUTH_SCHEME"
 INFLUX_GZIP_THRESHOLD = "INFLUX_GZIP_THRESHOLD"
 INFLUX_WRITE_NO_SYNC = "INFLUX_WRITE_NO_SYNC"
+INFLUX_WRITE_ACCEPT_PARTIAL = "INFLUX_WRITE_ACCEPT_PARTIAL"
+INFLUX_WRITE_USE_V2_API = "INFLUX_WRITE_USE_V2_API"
 INFLUX_WRITE_TIMEOUT = "INFLUX_WRITE_TIMEOUT"
 INFLUX_QUERY_TIMEOUT = "INFLUX_QUERY_TIMEOUT"
 INFLUX_DISABLE_GRPC_COMPRESSION = "INFLUX_DISABLE_GRPC_COMPRESSION"
@@ -155,19 +157,19 @@ def _parse_gzip_threshold(threshold: str) -> int:
     return threshold
 
 
-def _parse_write_no_sync(write_no_sync: str):
+def _parse_write_bool(value):
     """
-    Parses and validates the provided write no sync value.
+    Parses a truthy/falsy value for write options.
 
-    This function ensures that the given value is a valid boolean,
-    and it raises an appropriate error if the value is not valid.
+    The input is normalized to string and matched against common truthy values.
+    Any non-truthy value is treated as False.
 
-    :param write_no_sync: The input value to be parsed and validated.
-    :type write_no_sync: Any
-    :return: The validated write no sync value as an boolean.
+    :param value: The input value to be parsed and validated.
+    :type value: Any
+    :return: Parsed boolean value.
     :rtype: bool
     """
-    return write_no_sync.strip().lower() in ['true', '1', 't', 'y', 'yes']
+    return str(value).strip().lower() in ['true', '1', 't', 'y', 'yes']
 
 
 def _parse_timeout(to: str) -> int:
@@ -226,13 +228,11 @@ class InfluxDBClient3:
                                           Defaults to "multiprocessing.cpu_count() * 5".
         :key urllib3.util.retry.Retry retries: Set the default retry strategy that is used for all HTTP requests
                                                except batching writes. As a default there is no one retry strategy.
-        :key bool auth_basic: Set this to true to enable basic authentication when talking to a InfluxDB 1.8.x that
-                              does not use auth-enabled but is protected by a reverse proxy with basic authentication.
-                              (defaults to false, don't set to true when talking to InfluxDB 2)
-        :key str username: ``username`` to authenticate via username and password credentials to the InfluxDB 2.x
-        :key str password: ``password`` to authenticate via username and password credentials to the InfluxDB 2.x
         :key str query_timeout: int value used to set the client query API timeout in milliseconds.
         :key str write_timeout: int value used to set the client write API timeout in milliseconds.
+        :key bool write_accept_partial: allow partial writes when some lines fail.
+        :key bool write_use_v2_api: route writes through /api/v2/write compatibility endpoint.
+        :key bool write_no_sync: disable sync confirmation on V3 API endpoint writes.
         :key list[str] profilers: list of enabled Flux profilers
         """
         self._org = org if org is not None else "default"
@@ -243,6 +243,8 @@ class InfluxDBClient3:
         write_type = DefaultWriteOptions.write_type.value
         write_precision = DefaultWriteOptions.write_precision.value
         write_no_sync = DefaultWriteOptions.no_sync.value
+        write_accept_partial = DefaultWriteOptions.accept_partial.value
+        write_use_v2_api = DefaultWriteOptions.use_v2_api.value
         write_timeout = DefaultWriteOptions.timeout.value
 
         if isinstance(write_client_options, dict) and write_client_options.get('write_options') is not None:
@@ -250,15 +252,28 @@ class InfluxDBClient3:
             write_type = getattr(write_opts, 'write_type', write_type)
             write_precision = getattr(write_opts, 'write_precision', write_precision)
             write_no_sync = getattr(write_opts, 'no_sync', write_no_sync)
+            write_accept_partial = getattr(write_opts, 'accept_partial', write_accept_partial)
+            write_use_v2_api = getattr(write_opts, 'use_v2_api', write_use_v2_api)
             write_timeout = getattr(write_opts, 'timeout', write_timeout)
 
         if kw_keys.__contains__('write_timeout'):
             write_timeout = kwargs.get('write_timeout')
 
+        if kw_keys.__contains__('write_accept_partial') and kwargs.get('write_accept_partial') is not None:
+            write_accept_partial = _parse_write_bool(kwargs.get('write_accept_partial'))
+
+        if kw_keys.__contains__('write_use_v2_api') and kwargs.get('write_use_v2_api') is not None:
+            write_use_v2_api = _parse_write_bool(kwargs.get('write_use_v2_api'))
+
+        if kw_keys.__contains__('write_no_sync') and kwargs.get('write_no_sync') is not None:
+            write_no_sync = _parse_write_bool(kwargs.get('write_no_sync'))
+
         write_options = WriteOptions(
             write_type=write_type,
             write_precision=write_precision,
             no_sync=write_no_sync,
+            accept_partial=write_accept_partial,
+            use_v2_api=write_use_v2_api,
         )
 
         self._write_client_options = {
@@ -347,7 +362,15 @@ class InfluxDBClient3:
 
         write_no_sync = os.getenv(INFLUX_WRITE_NO_SYNC)
         if write_no_sync is not None:
-            write_options.no_sync = _parse_write_no_sync(write_no_sync)
+            write_options.no_sync = _parse_write_bool(write_no_sync)
+
+        write_accept_partial = os.getenv(INFLUX_WRITE_ACCEPT_PARTIAL)
+        if write_accept_partial is not None:
+            write_options.accept_partial = _parse_write_bool(write_accept_partial)
+
+        write_use_v2_api = os.getenv(INFLUX_WRITE_USE_V2_API)
+        if write_use_v2_api is not None:
+            write_options.use_v2_api = _parse_write_bool(write_use_v2_api)
 
         precision = os.getenv(INFLUX_PRECISION)
         if precision is not None:
@@ -388,6 +411,11 @@ class InfluxDBClient3:
         """
         Write data to InfluxDB.
 
+        Warning: When you write with only one Point or one Dict, and If that Point or Dict
+        contains fields with None value, those fields will not be written to InfluxDB.
+        If such fields are later queried explicitly, for example,
+        "SELECT field_with_value, field_with_null_value FROM my_table" an error will be thrown.
+
         :param record: The data point(s) to write.
         :type record: object or list of objects
         :param database: The database to write to. If not provided, uses the database provided during initialization.
@@ -397,10 +425,7 @@ class InfluxDBClient3:
         if database is None:
             database = self._database
 
-        try:
-            return self._write_api.write(bucket=database, record=record, **kwargs)
-        except InfluxDBError as e:
-            raise e
+        return self._write_api.write(bucket=database, record=record, **kwargs)
 
     def write_dataframe(
         self,

influxdb3_python-0.20.0/influxdb_client_3/__main__.py

@@ -0,0 +1,5 @@
+from influxdb_client_3.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())