cvec 1.4.3__tar.gz → 1.5.2__tar.gz

cvec-1.5.2/.claude/settings.json

@@ -0,0 +1,51 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run python-claude session start"
+          },
+          {
+            "type": "command",
+            "command": "uv run python-claude git status"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run python-claude ruff format"
+          },
+          {
+            "type": "command",
+            "command": "uv run python-claude ruff check"
+          },
+          {
+            "type": "command",
+            "command": "uv run python-claude mypy"
+          },
+          {
+            "type": "command",
+            "command": "uv run python-claude pytest"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run python-claude edited"
+          }
+        ]
+      }
+    ]
+  }
+}

cvec-1.5.2/.claude/settings.local.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(chmod:*)",
+      "Bash(python:*)",
+      "Bash(git commit:*)",
+      "Bash(pytest:*)",
+      "Bash(python3 -m pytest:*)",
+      "Bash(poetry run pytest:*)",
+      "Bash(git add:*)",
+      "Bash(poetry run mypy:*)",
+      "Bash(git checkout:*)",
+      "Bash(poetry run ruff:*)",
+      "Bash(poetry install:*)",
+      "Bash(tree:*)",
+      "Bash(git mv:*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:pypi.org)",
+      "Bash(poetry run python:*)",
+      "Bash(poetry add:*)",
+      "Bash(git fetch:*)",
+      "Bash(git rebase:*)",
+      "Bash(git rm:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

cvec-1.5.2/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: Continuous Integration
+
+on:
+  pull_request:
+    paths:
+      - .github/workflows/ci.yml
+      - uv.lock
+      - pyproject.toml
+      - src/**
+      - tests/**
+  push:
+    paths:
+      - .github/workflows/ci.yml
+      - uv.lock
+      - pyproject.toml
+      - src/**
+      - tests/**
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - uses: CVector-Energy/python-test@uv
+        with:
+          python-version: ${{ matrix.python-version }}
+          src-dirs: .

cvec-1.5.2/.github/workflows/license-check-python.yml

@@ -0,0 +1,17 @@
+name: Python License Check
+
+on:
+  push:
+
+jobs:
+  license-check:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      - name: Check Python licenses
+        uses: CVector-Energy/pyproject-license-check@main
+        with:
+          app-id: ${{ vars.APP_ID }}
+          app-private-key: ${{ secrets.APP_PRIVATE_KEY }}

cvec-1.5.2/.github/workflows/pyproject-license-check.yml

@@ -0,0 +1,17 @@
+name: Python License Check
+
+on:
+  push:
+
+jobs:
+  license-check:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      - name: Check Python licenses
+        uses: CVector-Energy/pyproject-license-check@main
+        with:
+          app-id: ${{ vars.APP_ID }}
+          app-private-key: ${{ secrets.APP_PRIVATE_KEY }}

cvec-1.5.2/.gitignore

@@ -0,0 +1,177 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+.aider*
+
+.vscode/

cvec-1.5.2/CLAUDE.md

@@ -0,0 +1 @@
+- Name files for their main export, transforming Python names from PascalCase to underscore_case. For example, the file that defines the EAVFilter class should be named eav_filter.py.

{cvec-1.4.3 → cvec-1.5.2}/PKG-INFO

@@ -1,23 +1,23 @@
 Metadata-Version: 2.4
 Name: cvec
-Version: 1.4.3
+Version: 1.5.2
 Summary: SDK for CVector Energy
+Author-email: CVector <support@cvector.energy>
 License-Expression: MIT
 License-File: LICENSE
-Author: CVector
-Author-email: support@cvector.energy
-Requires-Python: >=3.10
+Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Intended Audience :: Developers
 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 :: 3.14
-Requires-Dist: pyarrow (>=22.0.0)
-Requires-Dist: pydantic (>=2.12.0)
+Requires-Python: >=3.10
+Requires-Dist: brotli<2,>=1.2.0
+Requires-Dist: pyarrow>=22.0.0
+Requires-Dist: pydantic>=2.12.0
 Description-Content-Type: text/markdown
 
 # CVec Client Library
@@ -55,7 +55,7 @@ import cvec
 from datetime import datetime
 ```
 
-Construct the CVec client. The host, tenant, and api_key can be given through parameters to the constructor or from the environment variables CVEC_HOST, and CVEC_API_KEY:
+Construct the CVec client. The host and api_key can be given through parameters to the constructor or from the environment variables CVEC_HOST and CVEC_API_KEY:
 
 ```
 cvec = cvec.CVec()
@@ -110,7 +110,7 @@ mygroup/myedge/compressor01/motor/power_kw
 
 ### Metric Data
 
-The main content for a metric is a set of points where the metric value changed. These are returned as a Pandas Dataframe with columns for name, time, value_double, value_string.
+The main content for a metric is a set of points where the metric value changed. These are returned with columns for name, time, value_double, value_string.
 
 To get all of the value changes for all metrics at 10am on 2025-05-14, run:
 
@@ -136,6 +136,17 @@ Example output:
 
 [46257 rows x 4 columns]
 ```
+#### Pandas Data Frames
+
+Use the `get_metric_arrow` function to efficiently load data into a pandas DataFrame like this:
+
+```python
+import pandas as pd
+import pyarrow as pa
+
+reader = pa.ipc.open_file(cvec.get_metric_arrow(names=["tag1", "tag2"]))
+df = reader.read_pandas()
+```
 
 ### Adding Metric Data
 
@@ -220,9 +231,9 @@ The script automatically:
 
 The SDK provides an API client class named `CVec` with the following functions.
 
-## `__init__(?host, ?tenant, ?api_key, ?default_start_at, ?default_end_at)`
+## `__init__(?host, ?api_key, ?default_start_at, ?default_end_at)`
 
-Setup the SDK with the given host and API Key. The host and API key are loaded from environment variables CVEC_HOST, CVEC_API_KEY, if they are not given as arguments to the constructor. The `default_start_at` and `default_end_at` can provide a default query time interval for API methods.
+Setup the SDK with the given host and API Key. The host and API key are loaded from environment variables CVEC_HOST and CVEC_API_KEY if they are not given as arguments to the constructor. The tenant ID is automatically fetched from the host's `/config` endpoint. The `default_start_at` and `default_end_at` can provide a default query time interval for API methods.
 
 ## `get_spans(name, ?start_at, ?end_at, ?limit)`
 
@@ -284,3 +295,113 @@ Fetch actual data values from modeling metrics within a time range in Apache Arr
 
 Returns Arrow IPC format data that can be read using `pyarrow.ipc.open_file()`.
 
+## `get_eav_tables()`
+
+Get all EAV (Entity-Attribute-Value) tables for the tenant. EAV tables store semi-structured data where each row represents an entity with flexible attributes.
+
+Returns a list of `EAVTable` objects, each containing:
+- `id`: The table's UUID
+- `tenant_id`: The tenant ID
+- `name`: Human-readable table name
+- `created_at`: When the table was created
+- `updated_at`: When the table was last updated
+
+Example:
+```python
+tables = cvec.get_eav_tables()
+for table in tables:
+    print(f"{table.name} (id: {table.id})")
+```
+
+## `get_eav_columns(table_id)`
+
+Get all columns for a specific EAV table.
+
+- `table_id`: The UUID of the EAV table
+
+Returns a list of `EAVColumn` objects, each containing:
+- `eav_table_id`: The parent table's UUID
+- `eav_column_id`: The column's ID (used for queries)
+- `name`: Human-readable column name
+- `type`: Data type (`"number"`, `"string"`, or `"boolean"`)
+- `created_at`: When the column was created
+
+Example:
+```python
+columns = cvec.get_eav_columns("00000000-0000-0000-0000-000000000000")
+for column in columns:
+    print(f"  {column.name} ({column.type}, id: {column.eav_column_id})")
+```
+
+## `select_from_eav(table_name, ?column_names, ?filters)`
+
+Query pivoted data from EAV tables using human-readable names. This is the recommended method for most use cases as it allows you to work with table and column names instead of UUIDs.
+
+- `table_name`: Name of the EAV table to query
+- `column_names`: Optional list of column names to include. If `None`, all columns are returned.
+- `filters`: Optional list of `EAVFilter` objects to filter results
+
+Each `EAVFilter` must use `column_name` and can specify:
+- `column_name`: The column name to filter on (required)
+- `numeric_min`: Minimum numeric value (inclusive)
+- `numeric_max`: Maximum numeric value (exclusive)
+- `string_value`: Exact string value to match
+- `boolean_value`: Boolean value to match
+
+Returns a list of dictionaries (maximum 1000 rows), each representing a row with an `id` field and fields for each requested column.
+
+Example:
+```python
+from cvec import CVec, EAVFilter
+
+# Query with filters
+filters = [
+    EAVFilter(column_name="Weight", numeric_min=100, numeric_max=200),
+    EAVFilter(column_name="Status", string_value="ACTIVE"),
+]
+
+rows = cvec.select_from_eav(
+    table_name="Production Data",
+    column_names=["Date", "Weight", "Status"],
+    filters=filters,
+)
+
+for row in rows:
+    print(row)
+```
+
+## `select_from_eav_id(table_id, ?column_ids, ?filters)`
+
+Query pivoted data from EAV tables using table and column IDs directly. This is a lower-level method for cases where you already have the UUIDs and want to avoid name lookups.
+
+- `table_id`: UUID of the EAV table to query
+- `column_ids`: Optional list of column IDs to include. If `None`, all columns are returned.
+- `filters`: Optional list of `EAVFilter` objects to filter results
+
+Each `EAVFilter` must use `column_id` and can specify:
+- `column_id`: The column ID to filter on (required)
+- `numeric_min`: Minimum numeric value (inclusive)
+- `numeric_max`: Maximum numeric value (exclusive)
+- `string_value`: Exact string value to match
+- `boolean_value`: Boolean value to match
+
+Returns a list of dictionaries (up to 1000), each representing a row. Each row has a field for each column plus an `id` (the "row ID").
+
+Example:
+```python
+from cvec import EAVFilter
+
+filters = [
+    EAVFilter(column_id="abcd", numeric_min=100, numeric_max=200),
+    EAVFilter(column_id="efgh", string_value="ACTIVE"),
+]
+
+rows = cvec.select_from_eav_id(
+    table_id="00000000-0000-0000-0000-000000000000",
+    column_ids=["abcd", "efgh", "ijkl"],
+    filters=filters,
+)
+
+for row in rows:
+    print(f"ID: {row['id']}, Values: {row}")
+```

{cvec-1.4.3 → cvec-1.5.2}/README.md

@@ -33,7 +33,7 @@ import cvec
 from datetime import datetime
 ```
 
-Construct the CVec client. The host, tenant, and api_key can be given through parameters to the constructor or from the environment variables CVEC_HOST, and CVEC_API_KEY:
+Construct the CVec client. The host and api_key can be given through parameters to the constructor or from the environment variables CVEC_HOST and CVEC_API_KEY:
 
 ```
 cvec = cvec.CVec()
@@ -88,7 +88,7 @@ mygroup/myedge/compressor01/motor/power_kw
 
 ### Metric Data
 
-The main content for a metric is a set of points where the metric value changed. These are returned as a Pandas Dataframe with columns for name, time, value_double, value_string.
+The main content for a metric is a set of points where the metric value changed. These are returned with columns for name, time, value_double, value_string.
 
 To get all of the value changes for all metrics at 10am on 2025-05-14, run:
 
@@ -114,6 +114,17 @@ Example output:
 
 [46257 rows x 4 columns]
 ```
+#### Pandas Data Frames
+
+Use the `get_metric_arrow` function to efficiently load data into a pandas DataFrame like this:
+
+```python
+import pandas as pd
+import pyarrow as pa
+
+reader = pa.ipc.open_file(cvec.get_metric_arrow(names=["tag1", "tag2"]))
+df = reader.read_pandas()
+```
 
 ### Adding Metric Data
 
@@ -198,9 +209,9 @@ The script automatically:
 
 The SDK provides an API client class named `CVec` with the following functions.
 
-## `__init__(?host, ?tenant, ?api_key, ?default_start_at, ?default_end_at)`
+## `__init__(?host, ?api_key, ?default_start_at, ?default_end_at)`
 
-Setup the SDK with the given host and API Key. The host and API key are loaded from environment variables CVEC_HOST, CVEC_API_KEY, if they are not given as arguments to the constructor. The `default_start_at` and `default_end_at` can provide a default query time interval for API methods.
+Setup the SDK with the given host and API Key. The host and API key are loaded from environment variables CVEC_HOST and CVEC_API_KEY if they are not given as arguments to the constructor. The tenant ID is automatically fetched from the host's `/config` endpoint. The `default_start_at` and `default_end_at` can provide a default query time interval for API methods.
 
 ## `get_spans(name, ?start_at, ?end_at, ?limit)`
 
@@ -261,3 +272,114 @@ Fetch actual data values from modeling metrics within a time range in Apache Arr
 - `end_at`: Optional end time for the query (uses class default if not specified)
 
 Returns Arrow IPC format data that can be read using `pyarrow.ipc.open_file()`.
+
+## `get_eav_tables()`
+
+Get all EAV (Entity-Attribute-Value) tables for the tenant. EAV tables store semi-structured data where each row represents an entity with flexible attributes.
+
+Returns a list of `EAVTable` objects, each containing:
+- `id`: The table's UUID
+- `tenant_id`: The tenant ID
+- `name`: Human-readable table name
+- `created_at`: When the table was created
+- `updated_at`: When the table was last updated
+
+Example:
+```python
+tables = cvec.get_eav_tables()
+for table in tables:
+    print(f"{table.name} (id: {table.id})")
+```
+
+## `get_eav_columns(table_id)`
+
+Get all columns for a specific EAV table.
+
+- `table_id`: The UUID of the EAV table
+
+Returns a list of `EAVColumn` objects, each containing:
+- `eav_table_id`: The parent table's UUID
+- `eav_column_id`: The column's ID (used for queries)
+- `name`: Human-readable column name
+- `type`: Data type (`"number"`, `"string"`, or `"boolean"`)
+- `created_at`: When the column was created
+
+Example:
+```python
+columns = cvec.get_eav_columns("00000000-0000-0000-0000-000000000000")
+for column in columns:
+    print(f"  {column.name} ({column.type}, id: {column.eav_column_id})")
+```
+
+## `select_from_eav(table_name, ?column_names, ?filters)`
+
+Query pivoted data from EAV tables using human-readable names. This is the recommended method for most use cases as it allows you to work with table and column names instead of UUIDs.
+
+- `table_name`: Name of the EAV table to query
+- `column_names`: Optional list of column names to include. If `None`, all columns are returned.
+- `filters`: Optional list of `EAVFilter` objects to filter results
+
+Each `EAVFilter` must use `column_name` and can specify:
+- `column_name`: The column name to filter on (required)
+- `numeric_min`: Minimum numeric value (inclusive)
+- `numeric_max`: Maximum numeric value (exclusive)
+- `string_value`: Exact string value to match
+- `boolean_value`: Boolean value to match
+
+Returns a list of dictionaries (maximum 1000 rows), each representing a row with an `id` field and fields for each requested column.
+
+Example:
+```python
+from cvec import CVec, EAVFilter
+
+# Query with filters
+filters = [
+    EAVFilter(column_name="Weight", numeric_min=100, numeric_max=200),
+    EAVFilter(column_name="Status", string_value="ACTIVE"),
+]
+
+rows = cvec.select_from_eav(
+    table_name="Production Data",
+    column_names=["Date", "Weight", "Status"],
+    filters=filters,
+)
+
+for row in rows:
+    print(row)
+```
+
+## `select_from_eav_id(table_id, ?column_ids, ?filters)`
+
+Query pivoted data from EAV tables using table and column IDs directly. This is a lower-level method for cases where you already have the UUIDs and want to avoid name lookups.
+
+- `table_id`: UUID of the EAV table to query
+- `column_ids`: Optional list of column IDs to include. If `None`, all columns are returned.
+- `filters`: Optional list of `EAVFilter` objects to filter results
+
+Each `EAVFilter` must use `column_id` and can specify:
+- `column_id`: The column ID to filter on (required)
+- `numeric_min`: Minimum numeric value (inclusive)
+- `numeric_max`: Maximum numeric value (exclusive)
+- `string_value`: Exact string value to match
+- `boolean_value`: Boolean value to match
+
+Returns a list of dictionaries (up to 1000), each representing a row. Each row has a field for each column plus an `id` (the "row ID").
+
+Example:
+```python
+from cvec import EAVFilter
+
+filters = [
+    EAVFilter(column_id="abcd", numeric_min=100, numeric_max=200),
+    EAVFilter(column_id="efgh", string_value="ACTIVE"),
+]
+
+rows = cvec.select_from_eav_id(
+    table_id="00000000-0000-0000-0000-000000000000",
+    column_ids=["abcd", "efgh", "ijkl"],
+    filters=filters,
+)
+
+for row in rows:
+    print(f"ID: {row['id']}, Values: {row}")
+```