influxdata-plugin-utils 0.1.0__tar.gz → 0.2.0__tar.gz

{influxdata_plugin_utils-0.1.0 → influxdata_plugin_utils-0.2.0}/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-12
+
+### Added
+
+- `write.write_data` — optional `database` parameter for writing to another
+  database.
+- `introspection` — optional `database` parameter for schema helpers and
+  `query_window`.
+- `parsing.parse_timedelta` — `ms` (milliseconds) and `us` (microseconds)
+  duration units.
+
+### Changed
+
+- `write.write_data` — `no_sync` now defaults to `None`: writes go through
+  `write` / `write_to_db` (available on all InfluxDB 3 versions); passing a
+  boolean switches to `write_sync` / `write_sync_to_db` (InfluxDB 3.8+).
+
 ## [0.1.0] - 2026-07-08
 
 ### Added
@@ -22,5 +39,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `write` — `build_line`, `build_line_typed`, `add_field_with_type`,
   `write_data` (batching + retry), `BatchLines`.
 
-[Unreleased]: https://github.com/influxdata/influxdb3_plugins/compare/utils-v0.1.0...HEAD
-[0.1.0]: https://github.com/influxdata/influxdb3_plugins/releases/tag/utils-v0.1.0
+[Unreleased]: https://github.com/influxdata/influxdb3_plugins/compare/utils-v0.2.0...HEAD
+[0.2.0]: https://github.com/influxdata/influxdb3_plugins/compare/utils-v0.1.0...utils-v0.2.0
+[0.1.0]: https://github.com/influxdata/influxdb3_plugins/releases/tag/utils-v0.1.0

{influxdata_plugin_utils-0.1.0 → influxdata_plugin_utils-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: influxdata-plugin-utils
-Version: 0.1.0
+Version: 0.2.0
 Summary: Shared helpers for InfluxDB 3 plugins.
 Project-URL: Homepage, https://github.com/influxdata/influxdb3_plugins
 Project-URL: Repository, https://github.com/influxdata/influxdb3_plugins
@@ -36,7 +36,7 @@ pip install -e influxdata-plugin-utils
 | Module          | What it provides                                                                                                            |
 |-----------------|-----------------------------------------------------------------------------------------------------------------------------|
 | `config`        | `load_plugin_config(args, validators)` (dynaconf-backed), `resolve_plugin_dir()`, `resolve_path()`, re-exported `Validator` |
-| `introspection` | `get_table_names()`, `get_tag_names()`, `get_field_names()`, `query_window()`                                               |
+| `introspection` | `get_table_names()`, `get_tag_names()`, `get_field_names()`, `query_window()` with optional `database=`                    |
 | `parsing`       | `parse_timedelta()`, `parse_timestamp_ns()`, `parse_int()`, `parse_bool()`, `parse_delimited_list()`, `parse_key_value()`   |
 | `cache`         | `cached(influxdb3_local, key, producer, ttl_seconds=3600)`                                                                  |
 | `write`         | `build_line()`, `build_line_typed()`, `add_field_with_type()`, `write_data()`, `BatchLines`                                 |
@@ -82,9 +82,32 @@ lines = [
 ]
 write_data(influxdb3_local, lines)            # batched + retried by default
 # write_data(influxdb3_local, lines, batch=False, retries=0)  # opt out
+# write_data(influxdb3_local, lines, database="other_db")     # another database
+# write_data(influxdb3_local, lines, no_sync=True)            # write_sync API (3.8+)
+```
+
+## Cross-database queries
+
+On InfluxDB versions that support processing-engine cross-database queries,
+the introspection helpers accept `database=` and pass it through to
+`influxdb3_local.query`.
+Cached schema results are separated per database.
+
+```python
+from influxdata_plugin_utils.introspection import get_field_names, query_window
+
+fields = get_field_names(influxdb3_local, "cpu", database="source_db")
+rows = query_window(
+    influxdb3_local,
+    "cpu",
+    start=start,
+    end=end,
+    columns=fields,
+    database="source_db",
+)
 ```
 
 ## License
 
 Licensed under either of [Apache License 2.0](LICENSE-APACHE) or
-[MIT license](LICENSE-MIT) at your option.
+[MIT license](LICENSE-MIT) at your option.

{influxdata_plugin_utils-0.1.0 → influxdata_plugin_utils-0.2.0}/README.md

@@ -19,7 +19,7 @@ pip install -e influxdata-plugin-utils
 | Module          | What it provides                                                                                                            |
 |-----------------|-----------------------------------------------------------------------------------------------------------------------------|
 | `config`        | `load_plugin_config(args, validators)` (dynaconf-backed), `resolve_plugin_dir()`, `resolve_path()`, re-exported `Validator` |
-| `introspection` | `get_table_names()`, `get_tag_names()`, `get_field_names()`, `query_window()`                                               |
+| `introspection` | `get_table_names()`, `get_tag_names()`, `get_field_names()`, `query_window()` with optional `database=`                    |
 | `parsing`       | `parse_timedelta()`, `parse_timestamp_ns()`, `parse_int()`, `parse_bool()`, `parse_delimited_list()`, `parse_key_value()`   |
 | `cache`         | `cached(influxdb3_local, key, producer, ttl_seconds=3600)`                                                                  |
 | `write`         | `build_line()`, `build_line_typed()`, `add_field_with_type()`, `write_data()`, `BatchLines`                                 |
@@ -65,9 +65,32 @@ lines = [
 ]
 write_data(influxdb3_local, lines)            # batched + retried by default
 # write_data(influxdb3_local, lines, batch=False, retries=0)  # opt out
+# write_data(influxdb3_local, lines, database="other_db")     # another database
+# write_data(influxdb3_local, lines, no_sync=True)            # write_sync API (3.8+)
+```
+
+## Cross-database queries
+
+On InfluxDB versions that support processing-engine cross-database queries,
+the introspection helpers accept `database=` and pass it through to
+`influxdb3_local.query`.
+Cached schema results are separated per database.
+
+```python
+from influxdata_plugin_utils.introspection import get_field_names, query_window
+
+fields = get_field_names(influxdb3_local, "cpu", database="source_db")
+rows = query_window(
+    influxdb3_local,
+    "cpu",
+    start=start,
+    end=end,
+    columns=fields,
+    database="source_db",
+)
 ```
 
 ## License
 
 Licensed under either of [Apache License 2.0](LICENSE-APACHE) or
-[MIT license](LICENSE-MIT) at your option.
+[MIT license](LICENSE-MIT) at your option.

{influxdata_plugin_utils-0.1.0 → influxdata_plugin_utils-0.2.0}/src/influxdata_plugin_utils/__init__.py

@@ -8,7 +8,7 @@ Modules:
     write          - LineBuilder builders and resilient write_data
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 from . import cache, config, introspection, parsing, write
 from .cache import cached

{influxdata_plugin_utils-0.1.0 → influxdata_plugin_utils-0.2.0}/src/influxdata_plugin_utils/introspection.py

@@ -2,6 +2,8 @@
 
 Each helper takes ``influxdb3_local`` explicitly and may optionally use the
 TTL cache. Queries mirror the patterns already used across the plugins.
+Helpers accept an optional ``database`` argument for engines that support
+cross-database plugin queries.
 """
 
 from .cache import cached
@@ -22,13 +24,40 @@ def _quote_identifier(identifier: str) -> str:
     return '"' + identifier.replace('"', '""') + '"'
 
 
+def _query(
+    influxdb3_local,
+    query: str,
+    args: dict | None = None,
+    database: str | None = None,
+):
+    """Run a plugin query, preserving the old call shape when no database is set."""
+    if database is None:
+        if args is None:
+            return influxdb3_local.query(query)
+        return influxdb3_local.query(query, args)
+    if args is None:
+        return influxdb3_local.query(query, database=database)
+    return influxdb3_local.query(query, args, database=database)
+
+
+def _cache_key(base: str, database: str | None) -> str:
+    """Return a cache key, keeping existing default-database keys unchanged."""
+    if database is None:
+        return base
+    return f"{base}:database:{database}"
+
+
 def get_table_names(
-    influxdb3_local, *, use_cache: bool = True, ttl_seconds: int = 3600
+    influxdb3_local,
+    *,
+    database: str | None = None,
+    use_cache: bool = True,
+    ttl_seconds: int = 3600,
 ) -> list[str]:
     """Return base table names via ``SHOW TABLES``."""
 
     def producer() -> list[str]:
-        rows = influxdb3_local.query("SHOW TABLES")
+        rows = _query(influxdb3_local, "SHOW TABLES", database=database)
         return [
             row["table_name"]
             for row in rows
@@ -36,12 +65,22 @@ def get_table_names(
         ]
 
     if use_cache:
-        return cached(influxdb3_local, "shared:tables", producer, ttl_seconds=ttl_seconds)
+        return cached(
+            influxdb3_local,
+            _cache_key("shared:tables", database),
+            producer,
+            ttl_seconds=ttl_seconds,
+        )
     return producer()
 
 
 def get_tag_names(
-    influxdb3_local, table: str, *, use_cache: bool = True, ttl_seconds: int = 3600
+    influxdb3_local,
+    table: str,
+    *,
+    database: str | None = None,
+    use_cache: bool = True,
+    ttl_seconds: int = 3600,
 ) -> list[str]:
     """Return tag column names of a table (``Dictionary(Int32, Utf8)`` columns)."""
 
@@ -50,14 +89,20 @@ def get_tag_names(
             "SELECT column_name FROM information_schema.columns "
             "WHERE table_name = $table AND data_type = $data_type"
         )
-        rows = influxdb3_local.query(
-            query, {"table": table, "data_type": _TAG_DATA_TYPE}
+        rows = _query(
+            influxdb3_local,
+            query,
+            {"table": table, "data_type": _TAG_DATA_TYPE},
+            database=database,
         )
         return [row["column_name"] for row in rows]
 
     if use_cache:
         return cached(
-            influxdb3_local, f"shared:tags:{table}", producer, ttl_seconds=ttl_seconds
+            influxdb3_local,
+            _cache_key(f"shared:tags:{table}", database),
+            producer,
+            ttl_seconds=ttl_seconds,
         )
     return producer()
 
@@ -67,6 +112,7 @@ def get_field_names(
     table: str,
     *,
     numeric_only: bool = False,
+    database: str | None = None,
     use_cache: bool = True,
     ttl_seconds: int = 3600,
 ) -> list[str]:
@@ -80,7 +126,7 @@ def get_field_names(
             "SELECT column_name, data_type FROM information_schema.columns "
             "WHERE table_name = $table"
         )
-        rows = influxdb3_local.query(query, {"table": table})
+        rows = _query(influxdb3_local, query, {"table": table}, database=database)
         names: list[str] = []
         for row in rows:
             name = row["column_name"]
@@ -93,7 +139,7 @@ def get_field_names(
         return names
 
     if use_cache:
-        key = f"shared:fields:{table}:{int(numeric_only)}"
+        key = _cache_key(f"shared:fields:{table}:{int(numeric_only)}", database)
         return cached(influxdb3_local, key, producer, ttl_seconds=ttl_seconds)
     return producer()
 
@@ -105,6 +151,7 @@ def query_window(
     start,
     end,
     columns: list[str] | None = None,
+    database: str | None = None,
 ) -> list[dict]:
     """Run a basic ``time``-window query and return rows (``[]`` if none).
 
@@ -118,5 +165,10 @@ def query_window(
         f"SELECT {selected} FROM {_quote_identifier(table)} "
         "WHERE time >= $start AND time < $end ORDER BY time"
     )
-    rows = influxdb3_local.query(query, {"start": start, "end": end})
-    return rows or []
+    rows = _query(
+        influxdb3_local,
+        query,
+        {"start": start, "end": end},
+        database=database,
+    )
+    return rows or []

{influxdata_plugin_utils-0.1.0 → influxdata_plugin_utils-0.2.0}/src/influxdata_plugin_utils/parsing.py

@@ -19,6 +19,8 @@ __all__ = [
 
 _DURATION_RE = re.compile(r"^\s*(\d+)\s*([a-zA-Z]+)\s*$")
 _DURATION_UNITS = {
+    "us": "microseconds",
+    "ms": "milliseconds",
     "s": "seconds",
     "min": "minutes",
     "h": "hours",
@@ -33,7 +35,7 @@ _FALSE = {"false", "f", "0", "no", "off"}
 
 
 def parse_timedelta(raw) -> timedelta:
-    """Parse a duration like ``30s``, ``5min``, ``1h``, ``2d``, ``1w``."""
+    """Parse a duration like ``500us``, ``100ms``, ``30s``, ``5min``, ``1h``, ``2d``, ``1w``."""
     if isinstance(raw, timedelta):
         return raw
     match = _DURATION_RE.match(str(raw))

{influxdata_plugin_utils-0.1.0 → influxdata_plugin_utils-0.2.0}/src/influxdata_plugin_utils/write.py

@@ -9,6 +9,7 @@ write helpers operate on already-built line objects and need no class.
 import math
 import random
 import time
+from functools import partial
 
 from .parsing import parse_bool
 
@@ -160,7 +161,8 @@ def write_data(
     batch: bool = True,
     retries: int = 3,
     base_delay: float = 1.0,
-    no_sync: bool = True,
+    no_sync: bool | None = None,
+    database: str | None = None,
 ) -> None:
     """Write LineBuilder objects with optional batching and retry.
 
@@ -170,8 +172,17 @@ def write_data(
         batch: Combine all lines into one payload via :class:`BatchLines`.
             Set ``False`` to write each line individually.
         retries: Number of extra attempts on failure (``0`` disables retry).
+            Effective only when ``no_sync`` is set: the default buffered
+            ``write`` / ``write_to_db`` never raise at call time.
         base_delay: Base seconds for exponential backoff with jitter.
-        no_sync: Passed through to ``write_sync``.
+        no_sync: When set, writes go through ``write_sync`` /
+            ``write_sync_to_db`` with this flag (requires InfluxDB 3.8+),
+            which write immediately and raise on failure. When ``None``
+            (default), the universally available ``write`` / ``write_to_db``
+            are used: they only queue lines that are flushed after plugin
+            execution completes, so failures are not reported to the caller.
+        database: Target database; when ``None``, writes to the trigger's
+            database.
     """
     builders = [builder for builder in line_builders if builder is not None]
     if not builders:
@@ -180,13 +191,23 @@ def write_data(
     payloads = [BatchLines(builders)] if batch else builders
     attempts = max(retries, 0) + 1
 
+    if no_sync is None:
+        if database is not None:
+            write_fn = partial(influxdb3_local.write_to_db, database)
+        else:
+            write_fn = influxdb3_local.write
+    elif database is not None:
+        write_fn = partial(influxdb3_local.write_sync_to_db, database, no_sync=no_sync)
+    else:
+        write_fn = partial(influxdb3_local.write_sync, no_sync=no_sync)
+
     for payload in payloads:
         for attempt in range(attempts):
             try:
-                influxdb3_local.write_sync(payload, no_sync=no_sync)
+                write_fn(payload)
                 break
             except Exception:
                 if attempt == attempts - 1:
                     raise
                 delay = (2**attempt) * base_delay + random.uniform(0, base_delay)
-                time.sleep(delay)
+                time.sleep(delay)