influxdata-plugin-utils 0.1.0__tar.gz

influxdata_plugin_utils-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.claude
+.context
+.worktrees/
+*.pyc

influxdata_plugin_utils-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-08
+
+### Added
+
+- `config` — dynaconf-backed config loading (`load_plugin_config`), plugin
+  directory resolution (`resolve_plugin_dir`, `resolve_path`), re-exported
+  `Validator`.
+- `introspection` — schema helpers (`get_table_names`, `get_tag_names`,
+  `get_field_names`) and `query_window`, with optional TTL caching.
+- `parsing` — `parse_timedelta`, `parse_timestamp_ns`, `parse_int`,
+  `parse_bool`, `parse_delimited_list`, `parse_key_value`.
+- `cache` — `cached` TTL wrapper over `influxdb3_local.cache`.
+- `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

influxdata_plugin_utils-0.1.0/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   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.

influxdata_plugin_utils-0.1.0/LICENSE-MIT

@@ -0,0 +1,25 @@
+Copyright (c) 2020 InfluxData
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

influxdata_plugin_utils-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: influxdata-plugin-utils
+Version: 0.1.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
+Author: InfluxData
+License-Expression: MIT OR Apache-2.0
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Keywords: influxdb,influxdb3,plugins
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Requires-Dist: dynaconf>=3.2
+Description-Content-Type: text/markdown
+
+# influxdata-plugin-utils
+
+Shared helpers for InfluxDB 3 plugins.
+
+## Install
+
+```bash
+pip install influxdata-plugin-utils
+```
+
+Editable, for local development:
+
+```bash
+pip install -e influxdata-plugin-utils
+```
+
+## Modules
+
+| 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()`                                               |
+| `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`                                 |
+
+## Config: precedence
+
+`load_plugin_config` merges sources low → high: **env vars → engine `args` → TOML file**. A provided TOML config file overrides everything. Environment variables are read only when their exact names are passed via `env_keys=[...]`; nothing is read from the environment by default.
+
+```python
+from influxdata_plugin_utils.config import load_plugin_config, Validator
+from influxdata_plugin_utils.parsing import parse_timedelta
+
+def process_scheduled_call(influxdb3_local, call_time, args):
+    cfg = load_plugin_config(
+        args,
+        validators=[
+            Validator("source_table", must_exist=True),
+            Validator("batch_size", default=1000, gte=1, lte=10000, cast=int),
+            Validator("window", default="5min", cast=parse_timedelta),
+        ],
+    )
+    influxdb3_local.info(f"{cfg.source_table} window={cfg.window}")
+```
+
+TOML becomes native — no manual string parsing:
+
+```toml
+source_table = "cpu"
+batch_size = 2000
+excluded_fields = ["usage_idle", "usage_guest"]
+```
+
+## Write helpers
+
+`LineBuilder` is a runtime global injected into the plugin, so builders take the
+class as their first argument:
+
+```python
+from influxdata_plugin_utils.write import build_line, write_data
+
+lines = [
+    build_line(LineBuilder, "cpu", tags={"host": "a"}, fields={"usage": 12.5}, time_ns=ts)
+]
+write_data(influxdb3_local, lines)            # batched + retried by default
+# write_data(influxdb3_local, lines, batch=False, retries=0)  # opt out
+```
+
+## License
+
+Licensed under either of [Apache License 2.0](LICENSE-APACHE) or
+[MIT license](LICENSE-MIT) at your option.

influxdata_plugin_utils-0.1.0/README.md

@@ -0,0 +1,73 @@
+# influxdata-plugin-utils
+
+Shared helpers for InfluxDB 3 plugins.
+
+## Install
+
+```bash
+pip install influxdata-plugin-utils
+```
+
+Editable, for local development:
+
+```bash
+pip install -e influxdata-plugin-utils
+```
+
+## Modules
+
+| 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()`                                               |
+| `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`                                 |
+
+## Config: precedence
+
+`load_plugin_config` merges sources low → high: **env vars → engine `args` → TOML file**. A provided TOML config file overrides everything. Environment variables are read only when their exact names are passed via `env_keys=[...]`; nothing is read from the environment by default.
+
+```python
+from influxdata_plugin_utils.config import load_plugin_config, Validator
+from influxdata_plugin_utils.parsing import parse_timedelta
+
+def process_scheduled_call(influxdb3_local, call_time, args):
+    cfg = load_plugin_config(
+        args,
+        validators=[
+            Validator("source_table", must_exist=True),
+            Validator("batch_size", default=1000, gte=1, lte=10000, cast=int),
+            Validator("window", default="5min", cast=parse_timedelta),
+        ],
+    )
+    influxdb3_local.info(f"{cfg.source_table} window={cfg.window}")
+```
+
+TOML becomes native — no manual string parsing:
+
+```toml
+source_table = "cpu"
+batch_size = 2000
+excluded_fields = ["usage_idle", "usage_guest"]
+```
+
+## Write helpers
+
+`LineBuilder` is a runtime global injected into the plugin, so builders take the
+class as their first argument:
+
+```python
+from influxdata_plugin_utils.write import build_line, write_data
+
+lines = [
+    build_line(LineBuilder, "cpu", tags={"host": "a"}, fields={"usage": 12.5}, time_ns=ts)
+]
+write_data(influxdb3_local, lines)            # batched + retried by default
+# write_data(influxdb3_local, lines, batch=False, retries=0)  # opt out
+```
+
+## License
+
+Licensed under either of [Apache License 2.0](LICENSE-APACHE) or
+[MIT license](LICENSE-MIT) at your option.

influxdata_plugin_utils-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "influxdata-plugin-utils"
+dynamic = ["version"]
+description = "Shared helpers for InfluxDB 3 plugins."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT OR Apache-2.0"
+license-files = ["LICENSE-MIT", "LICENSE-APACHE"]
+authors = [{ name = "InfluxData" }]
+keywords = ["influxdb", "influxdb3", "plugins"]
+dependencies = ["dynaconf>=3.2"]
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/influxdata/influxdb3_plugins"
+Repository = "https://github.com/influxdata/influxdb3_plugins"
+
+[tool.hatch.version]
+path = "src/influxdata_plugin_utils/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/influxdata_plugin_utils"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "CHANGELOG.md", "LICENSE-MIT", "LICENSE-APACHE"]

influxdata_plugin_utils-0.1.0/src/influxdata_plugin_utils/__init__.py

@@ -0,0 +1,64 @@
+"""Shared helpers for InfluxDB 3 plugins.
+
+Modules:
+    config         - dynaconf-backed config loading, path resolution, validation
+    introspection  - schema introspection and minimal time-window queries
+    parsing        - duration / timestamp / int / bool / list / key=value parsers
+    cache          - TTL cache over influxdb3_local.cache
+    write          - LineBuilder builders and resilient write_data
+"""
+
+__version__ = "0.1.0"
+
+from . import cache, config, introspection, parsing, write
+from .cache import cached
+from .config import Validator, load_plugin_config, resolve_path, resolve_plugin_dir
+from .introspection import (
+    get_field_names,
+    get_table_names,
+    get_tag_names,
+    query_window,
+)
+from .parsing import (
+    parse_bool,
+    parse_delimited_list,
+    parse_int,
+    parse_key_value,
+    parse_timedelta,
+    parse_timestamp_ns,
+)
+from .write import (
+    BatchLines,
+    add_field_with_type,
+    build_line,
+    build_line_typed,
+    write_data,
+)
+
+__all__ = [
+    "cache",
+    "config",
+    "introspection",
+    "parsing",
+    "write",
+    "cached",
+    "Validator",
+    "load_plugin_config",
+    "resolve_path",
+    "resolve_plugin_dir",
+    "get_field_names",
+    "get_table_names",
+    "get_tag_names",
+    "query_window",
+    "parse_bool",
+    "parse_delimited_list",
+    "parse_int",
+    "parse_key_value",
+    "parse_timedelta",
+    "parse_timestamp_ns",
+    "BatchLines",
+    "add_field_with_type",
+    "build_line",
+    "build_line_typed",
+    "write_data",
+]

influxdata_plugin_utils-0.1.0/src/influxdata_plugin_utils/cache.py

@@ -0,0 +1,25 @@
+"""TTL caching over the plugin runtime cache (``influxdb3_local.cache``)."""
+
+from typing import Callable
+
+__all__ = ["cached"]
+
+
+def cached(
+    influxdb3_local, key: str, producer: Callable[[], object], *, ttl_seconds: int = 3600
+):
+    """Return a cached value, or produce it, store it with a TTL, and return it.
+
+    Args:
+        influxdb3_local: InfluxDB client instance (exposes ``.cache``).
+        key: Cache key.
+        producer: Zero-arg callable that computes the value on a cache miss.
+        ttl_seconds: Time-to-live for the stored value (default 1 hour).
+    """
+    cache = influxdb3_local.cache
+    value = cache.get(key)
+    if value is not None:
+        return value
+    value = producer()
+    cache.put(key, value, ttl_seconds)
+    return value

influxdata_plugin_utils-0.1.0/src/influxdata_plugin_utils/config.py

@@ -0,0 +1,113 @@
+"""Plugin configuration loading backed by dynaconf.
+
+Loads a plugin's TOML config (resolved via the plugin directory), merges
+environment variables and engine-supplied ``args``, and validates the result.
+dynaconf is an implementation detail and must not leak into plugin code beyond
+the re-exported ``Validator``.
+"""
+
+import os
+import tomllib
+from pathlib import Path
+
+from dynaconf import Dynaconf, Validator
+
+__all__ = ["resolve_plugin_dir", "resolve_path", "load_plugin_config", "Validator"]
+
+
+def resolve_plugin_dir() -> Path:
+    """Resolve the plugin directory from the environment.
+
+    Order: ``PLUGIN_DIR`` -> ``INFLUXDB3_PLUGIN_DIR`` -> parent of ``VIRTUAL_ENV``.
+    """
+    for env_var in ("PLUGIN_DIR", "INFLUXDB3_PLUGIN_DIR"):
+        value = os.environ.get(env_var)
+        if value:
+            return Path(value)
+    virtual_env = os.environ.get("VIRTUAL_ENV")
+    if virtual_env:
+        return Path(virtual_env).parent
+    raise ValueError(
+        "Cannot resolve plugin directory: set PLUGIN_DIR, INFLUXDB3_PLUGIN_DIR, "
+        "or run inside the processing engine venv (VIRTUAL_ENV)."
+    )
+
+
+def resolve_path(path: str) -> Path:
+    """Resolve a possibly relative path against the plugin directory.
+
+    Absolute paths are returned unchanged.
+    """
+    candidate = Path(path)
+    if candidate.is_absolute():
+        return candidate
+    return resolve_plugin_dir() / candidate
+
+
+def load_plugin_config(
+    args: dict,
+    validators: list[Validator] | None = None,
+    *,
+    env_keys: list[str] | None = None,
+    config_file_path_arg: str = "config_file_path",
+    source: str = "merge",
+) -> Dynaconf:
+    """Load and validate plugin configuration.
+
+    Layers are merged per key (low -> high): env vars -> ``args`` -> TOML file.
+    Within a layer, later keys override earlier ones; layers do not replace each
+    other wholesale. dynaconf is used for casting and validation only.
+
+    Args:
+        args: The dict passed to the plugin entry point (``None`` is treated as
+            empty). The TOML file path is read from ``args[config_file_path_arg]``
+            when present.
+        validators: Optional dynaconf ``Validator`` objects for required keys,
+            type casting, and bounds.
+        env_keys: Explicit environment variable names to read. Nothing is read
+            from the environment when omitted; each name is lowercased to form
+            the config key.
+        config_file_path_arg: Name of the ``args`` key holding the TOML path.
+        source: Which non-env layers to apply. ``"merge"`` uses both ``args``
+            and TOML (TOML highest); ``"args"`` uses only ``args``; ``"toml"``
+            uses only the TOML file. The env layer always applies underneath.
+
+    Returns:
+        A ``Dynaconf`` settings object; access values as attributes or items.
+    """
+    if source not in ("merge", "args", "toml"):
+        raise ValueError(
+            f"Invalid source {source!r}. Supported: merge, args, toml"
+        )
+
+    # the engine passes None when a trigger has no arguments
+    args = args or {}
+
+    layers: dict = {}
+
+    # 1. env vars (lowest): only the explicitly requested names
+    for env_var in env_keys or []:
+        value = os.environ.get(env_var)
+        if value is not None:
+            layers[env_var.lower()] = value
+
+    # 2. engine args (middle)
+    if source in ("merge", "args"):
+        for key, value in args.items():
+            if key != config_file_path_arg:
+                layers[key] = value
+
+    # 3. TOML file (highest)
+    if source in ("merge", "toml"):
+        config_file_path = args.get(config_file_path_arg)
+        if config_file_path:
+            with open(resolve_path(config_file_path), "rb") as config_file:
+                layers.update(tomllib.load(config_file))
+
+    # loaders=[] disables the DYNACONF_* env loader; env is read only via env_keys
+    settings = Dynaconf(loaders=[])
+    settings.update(layers)
+    if validators:
+        settings.validators.register(*validators)
+    settings.validators.validate()
+    return settings

influxdata_plugin_utils-0.1.0/src/influxdata_plugin_utils/introspection.py

@@ -0,0 +1,122 @@
+"""Schema introspection and minimal query helpers.
+
+Each helper takes ``influxdb3_local`` explicitly and may optionally use the
+TTL cache. Queries mirror the patterns already used across the plugins.
+"""
+
+from .cache import cached
+
+__all__ = [
+    "get_table_names",
+    "get_tag_names",
+    "get_field_names",
+    "query_window",
+]
+
+_TAG_DATA_TYPE = "Dictionary(Int32, Utf8)"
+_NUMERIC_TYPES = {"Int64", "UInt64", "Float64", "Int32", "Float32"}
+
+
+def _quote_identifier(identifier: str) -> str:
+    """Quote a SQL identifier, escaping embedded double quotes."""
+    return '"' + identifier.replace('"', '""') + '"'
+
+
+def get_table_names(
+    influxdb3_local, *, 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")
+        return [
+            row["table_name"]
+            for row in rows
+            if row.get("table_type") == "BASE TABLE"
+        ]
+
+    if use_cache:
+        return cached(influxdb3_local, "shared:tables", producer, ttl_seconds=ttl_seconds)
+    return producer()
+
+
+def get_tag_names(
+    influxdb3_local, table: str, *, use_cache: bool = True, ttl_seconds: int = 3600
+) -> list[str]:
+    """Return tag column names of a table (``Dictionary(Int32, Utf8)`` columns)."""
+
+    def producer() -> list[str]:
+        query = (
+            "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}
+        )
+        return [row["column_name"] for row in rows]
+
+    if use_cache:
+        return cached(
+            influxdb3_local, f"shared:tags:{table}", producer, ttl_seconds=ttl_seconds
+        )
+    return producer()
+
+
+def get_field_names(
+    influxdb3_local,
+    table: str,
+    *,
+    numeric_only: bool = False,
+    use_cache: bool = True,
+    ttl_seconds: int = 3600,
+) -> list[str]:
+    """Return field column names of a table (excludes tags and ``time``).
+
+    With ``numeric_only=True`` only integer/float columns are returned.
+    """
+
+    def producer() -> list[str]:
+        query = (
+            "SELECT column_name, data_type FROM information_schema.columns "
+            "WHERE table_name = $table"
+        )
+        rows = influxdb3_local.query(query, {"table": table})
+        names: list[str] = []
+        for row in rows:
+            name = row["column_name"]
+            data_type = row.get("data_type", "")
+            if name == "time" or data_type == _TAG_DATA_TYPE:
+                continue
+            if numeric_only and data_type not in _NUMERIC_TYPES:
+                continue
+            names.append(name)
+        return names
+
+    if use_cache:
+        key = f"shared:fields:{table}:{int(numeric_only)}"
+        return cached(influxdb3_local, key, producer, ttl_seconds=ttl_seconds)
+    return producer()
+
+
+def query_window(
+    influxdb3_local,
+    table: str,
+    *,
+    start,
+    end,
+    columns: list[str] | None = None,
+) -> list[dict]:
+    """Run a basic ``time``-window query and return rows (``[]`` if none).
+
+    ``start``/``end`` are passed as query parameters; provide values the engine
+    accepts for ``time`` comparisons (e.g. RFC3339 strings).
+    """
+    selected = (
+        ", ".join(_quote_identifier(column) for column in columns) if columns else "*"
+    )
+    query = (
+        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 []

influxdata_plugin_utils-0.1.0/src/influxdata_plugin_utils/parsing.py

@@ -0,0 +1,127 @@
+"""Parsing helpers for plugin configuration values.
+
+Each parser accepts a raw string (as delivered via CLI/trigger args) and can be
+used directly or as a dynaconf ``cast=`` callable. Only simple formats are
+supported here; plugin-specific nested formats stay in their plugins.
+"""
+
+import re
+from datetime import datetime, timedelta, timezone
+
+__all__ = [
+    "parse_timedelta",
+    "parse_timestamp_ns",
+    "parse_int",
+    "parse_bool",
+    "parse_delimited_list",
+    "parse_key_value",
+]
+
+_DURATION_RE = re.compile(r"^\s*(\d+)\s*([a-zA-Z]+)\s*$")
+_DURATION_UNITS = {
+    "s": "seconds",
+    "min": "minutes",
+    "h": "hours",
+    "d": "days",
+    "w": "weeks",
+}
+
+_TIMESTAMP_UNIT_NS = {"ns": 1, "us": 1_000, "ms": 1_000_000, "s": 1_000_000_000}
+
+_TRUE = {"true", "t", "1", "yes", "on"}
+_FALSE = {"false", "f", "0", "no", "off"}
+
+
+def parse_timedelta(raw) -> timedelta:
+    """Parse a duration like ``30s``, ``5min``, ``1h``, ``2d``, ``1w``."""
+    if isinstance(raw, timedelta):
+        return raw
+    match = _DURATION_RE.match(str(raw))
+    if not match:
+        raise ValueError(f"Invalid duration: {raw!r}")
+    magnitude, unit = int(match.group(1)), match.group(2).lower()
+    if unit not in _DURATION_UNITS:
+        raise ValueError(f"Unknown duration unit {unit!r} in {raw!r}")
+    return timedelta(**{_DURATION_UNITS[unit]: magnitude})
+
+
+def parse_timestamp_ns(value, time_format: str) -> int:
+    """Convert a timestamp to integer nanoseconds.
+
+    Numeric epoch units: ``ns``, ``us``, ``ms``, ``s``.
+    ``datetime``: ISO-8601 string or ``datetime`` object; naive values are UTC.
+    """
+    if time_format in _TIMESTAMP_UNIT_NS:
+        unit = _TIMESTAMP_UNIT_NS[time_format]
+        if isinstance(value, float):
+            return int(value * unit)
+        try:
+            # exact integer path: no float64 rounding of ns/us epochs
+            return int(value) * unit
+        except (TypeError, ValueError):
+            return int(float(value) * unit)
+    if time_format == "datetime":
+        if isinstance(value, datetime):
+            dt = value
+        elif isinstance(value, str):
+            dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        else:
+            raise ValueError(
+                f"datetime format requires str or datetime, got {type(value)}"
+            )
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return int(dt.timestamp() * 1_000_000_000)
+    raise ValueError(
+        f"Unknown time format: {time_format!r}. Supported: ns, us, ms, s, datetime"
+    )
+
+
+def parse_int(raw, *, minimum: int | None = None, maximum: int | None = None) -> int:
+    """Parse an integer with optional inclusive bounds."""
+    try:
+        value = int(str(raw).strip())
+    except (TypeError, ValueError):
+        raise ValueError(f"Invalid integer: {raw!r}")
+    if minimum is not None and value < minimum:
+        raise ValueError(f"Value {value} below minimum {minimum}")
+    if maximum is not None and value > maximum:
+        raise ValueError(f"Value {value} above maximum {maximum}")
+    return value
+
+
+def parse_bool(raw) -> bool:
+    """Parse a boolean from common truthy/falsy strings."""
+    if isinstance(raw, bool):
+        return raw
+    text = str(raw).strip().lower()
+    if text in _TRUE:
+        return True
+    if text in _FALSE:
+        return False
+    raise ValueError(f"Invalid boolean: {raw!r}")
+
+
+def parse_delimited_list(raw, *, sep: str = " ") -> list[str]:
+    """Split a delimited string into a list of non-empty trimmed items."""
+    if isinstance(raw, (list, tuple)):
+        return [str(item).strip() for item in raw if str(item).strip()]
+    return [item.strip() for item in str(raw).split(sep) if item.strip()]
+
+
+def parse_key_value(
+    raw, *, pair_sep: str = " ", kv_sep: str = "="
+) -> dict[str, str]:
+    """Parse a flat ``key=value`` map from a delimited string."""
+    if isinstance(raw, dict):
+        return {str(key): str(value) for key, value in raw.items()}
+    result: dict[str, str] = {}
+    for pair in str(raw).split(pair_sep):
+        pair = pair.strip()
+        if not pair:
+            continue
+        if kv_sep not in pair:
+            raise ValueError(f"Invalid pair {pair!r} (missing {kv_sep!r})")
+        key, value = pair.split(kv_sep, 1)
+        result[key.strip()] = value.strip()
+    return result

influxdata_plugin_utils-0.1.0/src/influxdata_plugin_utils/write.py

@@ -0,0 +1,192 @@
+"""Write helpers: LineBuilder construction and resilient writes.
+
+The processing engine injects ``LineBuilder`` as a runtime global inside the
+plugin, so it is not importable here. Builder helpers therefore receive the
+``LineBuilder`` class as their first argument (pass the plugin's global), while
+write helpers operate on already-built line objects and need no class.
+"""
+
+import math
+import random
+import time
+
+from .parsing import parse_bool
+
+__all__ = [
+    "add_field_with_type",
+    "build_line",
+    "build_line_typed",
+    "write_data",
+    "BatchLines",
+]
+
+_INT64_MIN = -(2**63)
+_INT64_MAX = 2**63 - 1
+_UINT64_MAX = 2**64 - 1
+
+
+class BatchLines:
+    """Join multiple LineBuilder outputs into a single write payload."""
+
+    def __init__(self, line_builders):
+        self._line_builders = list(line_builders)
+        self._built: str | None = None
+
+    def build(self) -> str:
+        if self._built is None:
+            lines = [str(builder.build()) for builder in self._line_builders]
+            if not lines:
+                raise ValueError("write received no lines to build")
+            self._built = "\n".join(lines)
+        return self._built
+
+
+def _infer_type(value) -> str:
+    if isinstance(value, bool):
+        return "bool"
+    if isinstance(value, int):
+        return "int"
+    if isinstance(value, float):
+        return "float"
+    return "string"
+
+
+def add_field_with_type(line, field_key: str, value, field_type: str):
+    """Add a field to a LineBuilder with explicit type conversion.
+
+    Supported types: ``int``, ``uint``, ``float``, ``bool``, ``string``.
+    """
+    if field_type == "int":
+        ival = int(value)
+        if not (_INT64_MIN <= ival <= _INT64_MAX):
+            raise ValueError(
+                f"int field {field_key!r} out of int64 range: {ival}"
+            )
+        line.int64_field(field_key, ival)
+    elif field_type == "uint":
+        uval = int(value)
+        if not (0 <= uval <= _UINT64_MAX):
+            raise ValueError(
+                f"uint field {field_key!r} out of uint64 range: {uval}"
+            )
+        line.uint64_field(field_key, uval)
+    elif field_type == "float":
+        fval = float(value)
+        if not math.isfinite(fval):
+            raise ValueError(f"float field {field_key!r} is not finite: {value!r}")
+        line.float64_field(field_key, fval)
+    elif field_type == "bool":
+        # strings are parsed strictly; everything else via Python truthiness
+        bval = parse_bool(value) if isinstance(value, str) else bool(value)
+        line.bool_field(field_key, bval)
+    elif field_type == "string":
+        line.string_field(field_key, str(value))
+    else:
+        raise ValueError(
+            f"Unsupported field type {field_type!r} for {field_key!r}"
+        )
+    return line
+
+
+def build_line(
+    line_builder_cls,
+    measurement: str,
+    *,
+    tags: dict | None = None,
+    fields: dict | None = None,
+    time_ns: int | None = None,
+):
+    """Build a LineBuilder, inferring each field's type from its value.
+
+    Variant for the common case where Python types map cleanly to line types.
+    Raises ``ValueError`` when no non-``None`` fields remain.
+    """
+    line = line_builder_cls(measurement)
+    for key, value in (tags or {}).items():
+        if value is None:
+            continue
+        line.tag(key, str(value))
+    field_count = 0
+    for key, value in (fields or {}).items():
+        if value is None:
+            continue
+        add_field_with_type(line, key, value, _infer_type(value))
+        field_count += 1
+    if not field_count:
+        # fail early: a field-less line would poison the whole batched write
+        raise ValueError(f"line for {measurement!r} has no fields")
+    if time_ns is not None:
+        line.time_ns(time_ns)
+    return line
+
+
+def build_line_typed(
+    line_builder_cls,
+    measurement: str,
+    *,
+    tags: dict | None = None,
+    typed_fields: dict | None = None,
+    time_ns: int | None = None,
+):
+    """Build a LineBuilder with explicit field types.
+
+    Variant for when types must be forced. ``typed_fields`` maps each field to a
+    ``(value, type)`` tuple, where ``type`` is one of the
+    :func:`add_field_with_type` types. Raises ``ValueError`` when no
+    non-``None`` fields remain.
+    """
+    line = line_builder_cls(measurement)
+    for key, value in (tags or {}).items():
+        if value is None:
+            continue
+        line.tag(key, str(value))
+    field_count = 0
+    for key, (value, field_type) in (typed_fields or {}).items():
+        if value is None:
+            continue
+        add_field_with_type(line, key, value, field_type)
+        field_count += 1
+    if not field_count:
+        raise ValueError(f"line for {measurement!r} has no fields")
+    if time_ns is not None:
+        line.time_ns(time_ns)
+    return line
+
+
+def write_data(
+    influxdb3_local,
+    line_builders,
+    *,
+    batch: bool = True,
+    retries: int = 3,
+    base_delay: float = 1.0,
+    no_sync: bool = True,
+) -> None:
+    """Write LineBuilder objects with optional batching and retry.
+
+    Args:
+        influxdb3_local: InfluxDB client instance.
+        line_builders: Iterable of LineBuilder objects (``None`` items skipped).
+        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).
+        base_delay: Base seconds for exponential backoff with jitter.
+        no_sync: Passed through to ``write_sync``.
+    """
+    builders = [builder for builder in line_builders if builder is not None]
+    if not builders:
+        return
+
+    payloads = [BatchLines(builders)] if batch else builders
+    attempts = max(retries, 0) + 1
+
+    for payload in payloads:
+        for attempt in range(attempts):
+            try:
+                influxdb3_local.write_sync(payload, no_sync=no_sync)
+                break
+            except Exception:
+                if attempt == attempts - 1:
+                    raise
+                delay = (2**attempt) * base_delay + random.uniform(0, base_delay)
+                time.sleep(delay)