varmeta 0.1.0__tar.gz

varmeta-0.1.0/.bumpversion.cfg

@@ -0,0 +1,8 @@
+[bumpversion]
+current_version = 0.0.1
+commit = True
+tag = True
+
+[bumpversion:file:src/varmeta/__init__.py]
+
+[bumpversion:file:pyproject.toml]

varmeta-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

varmeta-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.11.9
+    hooks:
+    # Run the linter.
+    -   id: ruff
+    # Run the formatter.
+    -   id: ruff-format

varmeta-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

varmeta-0.1.0/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "."
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

varmeta-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Reuben Rusk
+
+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.

varmeta-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: varmeta
+Version: 0.1.0
+Summary: Lightweight variable metadata management.
+Author-email: Reuben Rusk <pythoro@mindquip.com>
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: numpy>=1.11.0
+Requires-Dist: pandas>=2.3.1
+Description-Content-Type: text/markdown
+
+
+# varmeta
+
+`varmeta` is a small and lightweight Python package for managing and using variable metadata in scientific, engineering, and data analysis workflows in outputs. It's designed with type safety in mind for use with modern IDEs like VSCode + pylance.
+
+## Purpose
+
+We often have variables with several components (e.g. x, y, and z components). We want to use them as lists or arrays, but tabulate them nicely for outputs. `varmeta` solves this problem in a simple way. 
+
+- Set up a dictionary of Var instances, with string keys.
+- Set up matching dictionaries of data.
+- Create pandas dataframes with nice multi-index headings containing not just the variable keys, but also their names and units, OR:
+- Split variables into components automatically for other uses.
+
+## Quick-start tutorial
+
+### 1. Define variables with metadata
+
+Let's first set up some imports, constants, and Var instances. 
+
+```python
+import varmeta as vm
+
+TEMP = "temperature"
+FORCE = "force"
+
+# Scalar variable
+temperature = vm.Var(
+	key=TEMP,
+	name="Temperature",
+	units="Celsius",
+	desciption="Ambient temperature",
+	components=None
+)
+
+# Vector variable (e.g., 3D force)
+force = vm.Var(
+	key=FORCE,
+	name="Force",
+	units="N",
+	desciption="Force vector",
+	components=("x", "y", "z"),
+	component_axis=1
+)
+```
+
+### 2. Use literal keys for Var and data dictionaries
+
+Use shared literal string keys for dictionaries of Var instances and
+data dictionaries.
+
+```python
+data_dct = {
+	TEMP: 25.0,
+	FORCE: [10.0, 20.0, 30.0]
+}
+
+var_dct = vm.VarDict({
+	TEMP: temperature,
+	FORCE: force
+})
+```
+
+### 3. Unpack data with components
+
+```python
+vars, vals = vm.unpack(var_dct, data_dct)
+print(vars)
+# {'temp': Temperature [Celsius], 'force_x': Force - x [N], 'force_y': Force - y [N], 'force_z': Force - z [N]}
+print(vals)
+# {'temp': 25.0, 'force_x': 10.0, 'force_y': 20.0, 'force_z': 30.0}
+```
+
+### 5. Tabulate dict-based data into pandas DataFrames
+
+It's easy to tabulate data into a DataFrame. Data is automatically unpacked,
+even numpy arrays!
+
+```python
+data_dct = {FORCE: [[200, 250, -30], [300, 350, -100]], TEMP: [30, 40]}
+df = vm.dict_to_df(var_dct, data_dct)
+print(df)
+# key     force_x   force_y   force_z        temp
+# name  Force - x Force - y Force - z Temperature
+# units         N         N         N     Celsius
+# 0           200       250       -30          30
+# 1           300       350      -100          40
+data_dct = {TEMP: [30, 40], FORCE: [[200, 250, -30], [300, 350, -100]]}
+df = vm.dict_to_df(var_dct, data_dct)
+print(df)
+# key          temp   force_x   force_y   force_z
+# name  Temperature Force - x Force - y Force - z
+# units     Celsius         N         N         N
+# 0              30       200       250       -30
+# 1              40       300       350      -100
+```
+
+### 6. Tabulate records easily
+
+Say we'd had many records instead. We can make tables with lists of data
+in dictionaries, unpacking each automatically, like this:
+
+```python
+data_dict_lst = [
+	{FORCE: [200, 250, -30], TEMP: 30},
+	{FORCE: [300, 350, -100], TEMP: 40},
+]
+df = vm.records_to_df(var_dct, data_dict_lst)
+print(df)
+# key     force_x   force_y   force_z        temp
+# name  Force - x Force - y Force - z Temperature
+# units         N         N         N     Celsius
+# 0           200       250       -30          30
+# 1           300       350      -100          40
+```
+
+## Serialisation
+
+We can convert to dictionaries like this:
+```python
+var_data = vm.vars_to_dict(var_dct)
+print(var_data)
+# Output
+# {'temp': {'key': 'temp', 'name': 'Temperature', 'units': 'Celsius', 'desciption': 'Ambient temperature', 'components': None, 'component_axis': 0, 'data_type': 'object'}, 'force': {'key': 'force', 'name': 'Force', 'units': 'N', 'desciption': 'Force vector', 'components': ('x', 'y', 'z'), 'component_axis': 1, 'data_type': 'object'}}
+```
+
+Then we can convert back to Var instances like this:
+```python
+var_dct_recreated = vm.vars_from_dict(var_data)
+for k, v in var_dct_recreated:
+	print(f"k: match is {v == var_dct[k]}")
+# Output
+# temp: match is True
+# force: match is True
+```
+
+The data (`var_data`) can be easily saved and read from JSON using the 
+standard *json* library. 
+
+
+
+
+

varmeta-0.1.0/README.md

@@ -0,0 +1,143 @@
+
+# varmeta
+
+`varmeta` is a small and lightweight Python package for managing and using variable metadata in scientific, engineering, and data analysis workflows in outputs. It's designed with type safety in mind for use with modern IDEs like VSCode + pylance.
+
+## Purpose
+
+We often have variables with several components (e.g. x, y, and z components). We want to use them as lists or arrays, but tabulate them nicely for outputs. `varmeta` solves this problem in a simple way. 
+
+- Set up a dictionary of Var instances, with string keys.
+- Set up matching dictionaries of data.
+- Create pandas dataframes with nice multi-index headings containing not just the variable keys, but also their names and units, OR:
+- Split variables into components automatically for other uses.
+
+## Quick-start tutorial
+
+### 1. Define variables with metadata
+
+Let's first set up some imports, constants, and Var instances. 
+
+```python
+import varmeta as vm
+
+TEMP = "temperature"
+FORCE = "force"
+
+# Scalar variable
+temperature = vm.Var(
+	key=TEMP,
+	name="Temperature",
+	units="Celsius",
+	desciption="Ambient temperature",
+	components=None
+)
+
+# Vector variable (e.g., 3D force)
+force = vm.Var(
+	key=FORCE,
+	name="Force",
+	units="N",
+	desciption="Force vector",
+	components=("x", "y", "z"),
+	component_axis=1
+)
+```
+
+### 2. Use literal keys for Var and data dictionaries
+
+Use shared literal string keys for dictionaries of Var instances and
+data dictionaries.
+
+```python
+data_dct = {
+	TEMP: 25.0,
+	FORCE: [10.0, 20.0, 30.0]
+}
+
+var_dct = vm.VarDict({
+	TEMP: temperature,
+	FORCE: force
+})
+```
+
+### 3. Unpack data with components
+
+```python
+vars, vals = vm.unpack(var_dct, data_dct)
+print(vars)
+# {'temp': Temperature [Celsius], 'force_x': Force - x [N], 'force_y': Force - y [N], 'force_z': Force - z [N]}
+print(vals)
+# {'temp': 25.0, 'force_x': 10.0, 'force_y': 20.0, 'force_z': 30.0}
+```
+
+### 5. Tabulate dict-based data into pandas DataFrames
+
+It's easy to tabulate data into a DataFrame. Data is automatically unpacked,
+even numpy arrays!
+
+```python
+data_dct = {FORCE: [[200, 250, -30], [300, 350, -100]], TEMP: [30, 40]}
+df = vm.dict_to_df(var_dct, data_dct)
+print(df)
+# key     force_x   force_y   force_z        temp
+# name  Force - x Force - y Force - z Temperature
+# units         N         N         N     Celsius
+# 0           200       250       -30          30
+# 1           300       350      -100          40
+data_dct = {TEMP: [30, 40], FORCE: [[200, 250, -30], [300, 350, -100]]}
+df = vm.dict_to_df(var_dct, data_dct)
+print(df)
+# key          temp   force_x   force_y   force_z
+# name  Temperature Force - x Force - y Force - z
+# units     Celsius         N         N         N
+# 0              30       200       250       -30
+# 1              40       300       350      -100
+```
+
+### 6. Tabulate records easily
+
+Say we'd had many records instead. We can make tables with lists of data
+in dictionaries, unpacking each automatically, like this:
+
+```python
+data_dict_lst = [
+	{FORCE: [200, 250, -30], TEMP: 30},
+	{FORCE: [300, 350, -100], TEMP: 40},
+]
+df = vm.records_to_df(var_dct, data_dict_lst)
+print(df)
+# key     force_x   force_y   force_z        temp
+# name  Force - x Force - y Force - z Temperature
+# units         N         N         N     Celsius
+# 0           200       250       -30          30
+# 1           300       350      -100          40
+```
+
+## Serialisation
+
+We can convert to dictionaries like this:
+```python
+var_data = vm.vars_to_dict(var_dct)
+print(var_data)
+# Output
+# {'temp': {'key': 'temp', 'name': 'Temperature', 'units': 'Celsius', 'desciption': 'Ambient temperature', 'components': None, 'component_axis': 0, 'data_type': 'object'}, 'force': {'key': 'force', 'name': 'Force', 'units': 'N', 'desciption': 'Force vector', 'components': ('x', 'y', 'z'), 'component_axis': 1, 'data_type': 'object'}}
+```
+
+Then we can convert back to Var instances like this:
+```python
+var_dct_recreated = vm.vars_from_dict(var_data)
+for k, v in var_dct_recreated:
+	print(f"k: match is {v == var_dct[k]}")
+# Output
+# temp: match is True
+# force: match is True
+```
+
+The data (`var_data`) can be easily saved and read from JSON using the 
+standard *json* library. 
+
+
+
+
+

varmeta-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "varmeta"
+version = "0.1.0"
+description = "Lightweight variable metadata management."
+readme = "README.md"
+authors = [
+    { name = "Reuben Rusk", email = "pythoro@mindquip.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "numpy>=1.11.0",
+    "pandas>=2.3.1",
+]
+
+[project.scripts]
+varmeta = "varmeta:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+    "ruff>=0.12.9",
+]
+
+[tool.ruff]
+line-length = 79
+output-format = "concise"
+
+[tool.ruff.lint]
+select = ["E", "F", "B", "C90", "I", "UP", "SIM", "D", "ANN"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["ANN", "D"]

varmeta-0.1.0/src/varmeta/__init__.py

@@ -0,0 +1,32 @@
+"""varmeta: Lightweight variable metadata management for data workflows.
+
+This package provides hashable variable objects with units, descriptions, and
+component support, enabling robust metadata handling, serialization, and
+integration with pandas and other tools.
+"""
+
+__version__ = "0.1.0"
+
+from .vars import (
+    Var,
+    VarData,
+    VarDict,
+    dict_to_df,
+    records_to_df,
+    unpack,
+    vars_from_dict,
+    vars_to_dict,
+    vars_to_multi_index_data,
+)
+
+__all__ = [
+    "Var",
+    "vars_to_multi_index_data",
+    "dict_to_df",
+    "VarData",
+    "VarDict",
+    "records_to_df",
+    "unpack",
+    "vars_to_dict",
+    "vars_from_dict",
+]