dr-frames 0.1.0__tar.gz

dr_frames-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Ruff
+.ruff_cache/
+
+# Build
+*.manifest
+*.spec
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS
+.DS_Store
+Thumbs.db

dr_frames-0.1.0/LICENSE

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

dr_frames-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: dr-frames
+Version: 0.1.0
+Summary: Pandas/DataFrame utilities for data manipulation, filtering, aggregation, and schema management
+Project-URL: Homepage, https://github.com/drothermel/dr_frames
+Project-URL: Repository, https://github.com/drothermel/dr_frames
+Author-email: Danielle Rothermel <danielle.rothermel@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aggregation,data-manipulation,dataframe,filtering,pandas,schema
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: formatting
+Requires-Dist: pyyaml>=6.0.0; extra == 'formatting'
+Requires-Dist: rich>=13.0.0; extra == 'formatting'
+Requires-Dist: tabulate>=0.9.0; extra == 'formatting'
+Description-Content-Type: text/markdown
+
+# dr_frames
+
+Pandas/DataFrame utilities for data manipulation, filtering, aggregation, and schema management.
+
+## Installation
+
+```bash
+pip install dr-frames
+```
+
+For table formatting features (console, markdown, latex):
+```bash
+pip install dr-frames[formatting]
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+from dr_frames import (
+    coerce_numeric_cols,
+    filter_to_range,
+    move_cols_to_beginning,
+    select_subset,
+)
+
+df = pd.DataFrame({
+    "name": ["alice", "bob", "charlie"],
+    "value": ["1.0", "2.0", "3.0"],
+    "category": ["x", "y", "x"],
+})
+
+result = (
+    df.pipe(coerce_numeric_cols, ["value"])
+    .pipe(select_subset, {"category": "x"})
+    .pipe(filter_to_range, "value", 0.5, 2.5)
+)
+```
+
+## Module Overview
+
+| Module | Purpose | Key Functions |
+|--------|---------|---------------|
+| **columns** | Column selection & reordering | `move_cols_to_beginning`, `get_cols_by_prefix`, `strip_col_prefixes` |
+| **filtering** | Row filtering | `select_subset`, `filter_to_range`, `make_filter_fxn` |
+| **cells** | Cell-level operations | `ensure_column`, `map_column_with_fallback`, `force_set_cell` |
+| **types** | Type coercion | `coerce_numeric_cols`, `coerce_string_cols` |
+| **aggregation** | GroupBy & reduction | `aggregate_over_seeds`, `apply_aggregations`, `unique_non_null` |
+| **parsing** | String list parsing | `parse_first_element`, `sum_list_elements`, `is_homogeneous` |
+| **schema** | Data field metadata | `DataField`, `ComputedField`, `DataFormat` |
+| **profiling** | Column auto-tagging | `DFColInfo`, `ColInfo`, `looks_like_json` |
+| **formatting** | Table output | `format_table`, `format_coverage_table` |
+
+## Documentation
+
+- [Full API Reference](docs/api.md)
+- Module guides: [columns](docs/columns.md) | [filtering](docs/filtering.md) | [cells](docs/cells.md) | [types](docs/types.md) | [aggregation](docs/aggregation.md) | [parsing](docs/parsing.md) | [schema](docs/schema.md) | [profiling](docs/profiling.md) | [formatting](docs/formatting.md)
+- [Recipes & Patterns](docs/recipes.md)
+
+### Auto-generated API Docs
+
+```bash
+# Serve interactive docs locally
+uv run pdoc dr_frames
+
+# Generate static HTML
+uv run pdoc dr_frames -o docs/api_html
+```
+
+## Quick Reference
+
+### Column Operations
+```python
+from dr_frames import (
+    contained_cols,          # cols that exist in df
+    remaining_cols,          # cols NOT in a list
+    get_cols_by_prefix,      # cols starting with prefix
+    get_cols_by_contains,    # cols containing substring
+    move_cols_to_beginning,  # reorder cols
+    move_cols_with_prefix_to_end,
+    strip_col_prefixes,      # rename by removing prefix
+    drop_all_null_cols,      # remove empty columns
+)
+```
+
+### Filtering
+```python
+from dr_frames import (
+    select_subset,           # filter by exact column values
+    apply_filters_to_df,     # filter by value lists
+    filter_to_value,         # single value filter
+    filter_to_values,        # multi-value filter
+    filter_to_range,         # numeric range filter
+    filter_to_best_metric,   # keep best per group
+    make_filter_fxn,         # compose filters
+)
+```
+
+### Cell Operations
+```python
+from dr_frames import (
+    ensure_column,           # add column if missing
+    fill_missing_values,     # fillna with defaults dict
+    rename_columns,          # safe rename (skips missing)
+    map_column_with_fallback,# map values, keep unmapped
+    apply_column_converters, # apply functions to columns
+    maybe_update_cell,       # update if currently null
+    force_set_cell,          # always update
+    masked_getter,           # get value where mask is true
+    masked_setter,           # set value where mask is true
+)
+```
+
+### Type Coercion
+```python
+from dr_frames import (
+    coerce_numeric_cols,     # convert to float/int
+    coerce_string_cols,      # convert to string dtype
+    is_string_series,        # check if series is strings
+)
+```
+
+### Aggregation
+```python
+from dr_frames import (
+    aggregate_over_seeds,    # mean/std/count by config
+    apply_aggregations,      # flexible groupby
+    unique_non_null,         # unique values excluding null
+    unique_by_col,           # unique values in column
+    get_constant_cols,       # cols with single value
+    fillna_with_defaults,    # fill nulls from dict
+    maybe_pipe,              # conditional pipe
+)
+```
+
+### Parsing
+```python
+from dr_frames import (
+    parse_list_string,       # "[1,2,3]" -> [1,2,3]
+    parse_first_element,     # "[1,2,3]" -> 1.0
+    sum_list_elements,       # "[1,2,3]" -> 6.0
+    is_homogeneous,          # "[1,1,1]" -> True
+)
+```
+
+### Schema
+```python
+from dr_frames import (
+    DataField,               # field with metadata
+    ComputedField,           # derived field
+    MetricDataField,         # metric with group info
+    DataFormat,              # container for fields
+)
+```
+
+### Profiling
+```python
+from dr_frames import (
+    DFColInfo,               # catalog of column info
+    ColInfo,                 # single column metadata
+    looks_like_json,         # detect JSON strings
+    looks_like_path,         # detect file paths
+    infer_series_base_tag_type,  # infer dtype tags
+)
+```
+
+### Formatting (requires `[formatting]` extra)
+```python
+from dr_frames import (
+    format_table,            # render table in multiple formats
+    format_coverage_table,   # show column coverage stats
+    FORMATTER_TYPES,         # available formatters
+    OUTPUT_FORMATS,          # available output formats
+)
+```
+
+## License
+
+MIT

dr_frames-0.1.0/README.md

@@ -0,0 +1,179 @@
+# dr_frames
+
+Pandas/DataFrame utilities for data manipulation, filtering, aggregation, and schema management.
+
+## Installation
+
+```bash
+pip install dr-frames
+```
+
+For table formatting features (console, markdown, latex):
+```bash
+pip install dr-frames[formatting]
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+from dr_frames import (
+    coerce_numeric_cols,
+    filter_to_range,
+    move_cols_to_beginning,
+    select_subset,
+)
+
+df = pd.DataFrame({
+    "name": ["alice", "bob", "charlie"],
+    "value": ["1.0", "2.0", "3.0"],
+    "category": ["x", "y", "x"],
+})
+
+result = (
+    df.pipe(coerce_numeric_cols, ["value"])
+    .pipe(select_subset, {"category": "x"})
+    .pipe(filter_to_range, "value", 0.5, 2.5)
+)
+```
+
+## Module Overview
+
+| Module | Purpose | Key Functions |
+|--------|---------|---------------|
+| **columns** | Column selection & reordering | `move_cols_to_beginning`, `get_cols_by_prefix`, `strip_col_prefixes` |
+| **filtering** | Row filtering | `select_subset`, `filter_to_range`, `make_filter_fxn` |
+| **cells** | Cell-level operations | `ensure_column`, `map_column_with_fallback`, `force_set_cell` |
+| **types** | Type coercion | `coerce_numeric_cols`, `coerce_string_cols` |
+| **aggregation** | GroupBy & reduction | `aggregate_over_seeds`, `apply_aggregations`, `unique_non_null` |
+| **parsing** | String list parsing | `parse_first_element`, `sum_list_elements`, `is_homogeneous` |
+| **schema** | Data field metadata | `DataField`, `ComputedField`, `DataFormat` |
+| **profiling** | Column auto-tagging | `DFColInfo`, `ColInfo`, `looks_like_json` |
+| **formatting** | Table output | `format_table`, `format_coverage_table` |
+
+## Documentation
+
+- [Full API Reference](docs/api.md)
+- Module guides: [columns](docs/columns.md) | [filtering](docs/filtering.md) | [cells](docs/cells.md) | [types](docs/types.md) | [aggregation](docs/aggregation.md) | [parsing](docs/parsing.md) | [schema](docs/schema.md) | [profiling](docs/profiling.md) | [formatting](docs/formatting.md)
+- [Recipes & Patterns](docs/recipes.md)
+
+### Auto-generated API Docs
+
+```bash
+# Serve interactive docs locally
+uv run pdoc dr_frames
+
+# Generate static HTML
+uv run pdoc dr_frames -o docs/api_html
+```
+
+## Quick Reference
+
+### Column Operations
+```python
+from dr_frames import (
+    contained_cols,          # cols that exist in df
+    remaining_cols,          # cols NOT in a list
+    get_cols_by_prefix,      # cols starting with prefix
+    get_cols_by_contains,    # cols containing substring
+    move_cols_to_beginning,  # reorder cols
+    move_cols_with_prefix_to_end,
+    strip_col_prefixes,      # rename by removing prefix
+    drop_all_null_cols,      # remove empty columns
+)
+```
+
+### Filtering
+```python
+from dr_frames import (
+    select_subset,           # filter by exact column values
+    apply_filters_to_df,     # filter by value lists
+    filter_to_value,         # single value filter
+    filter_to_values,        # multi-value filter
+    filter_to_range,         # numeric range filter
+    filter_to_best_metric,   # keep best per group
+    make_filter_fxn,         # compose filters
+)
+```
+
+### Cell Operations
+```python
+from dr_frames import (
+    ensure_column,           # add column if missing
+    fill_missing_values,     # fillna with defaults dict
+    rename_columns,          # safe rename (skips missing)
+    map_column_with_fallback,# map values, keep unmapped
+    apply_column_converters, # apply functions to columns
+    maybe_update_cell,       # update if currently null
+    force_set_cell,          # always update
+    masked_getter,           # get value where mask is true
+    masked_setter,           # set value where mask is true
+)
+```
+
+### Type Coercion
+```python
+from dr_frames import (
+    coerce_numeric_cols,     # convert to float/int
+    coerce_string_cols,      # convert to string dtype
+    is_string_series,        # check if series is strings
+)
+```
+
+### Aggregation
+```python
+from dr_frames import (
+    aggregate_over_seeds,    # mean/std/count by config
+    apply_aggregations,      # flexible groupby
+    unique_non_null,         # unique values excluding null
+    unique_by_col,           # unique values in column
+    get_constant_cols,       # cols with single value
+    fillna_with_defaults,    # fill nulls from dict
+    maybe_pipe,              # conditional pipe
+)
+```
+
+### Parsing
+```python
+from dr_frames import (
+    parse_list_string,       # "[1,2,3]" -> [1,2,3]
+    parse_first_element,     # "[1,2,3]" -> 1.0
+    sum_list_elements,       # "[1,2,3]" -> 6.0
+    is_homogeneous,          # "[1,1,1]" -> True
+)
+```
+
+### Schema
+```python
+from dr_frames import (
+    DataField,               # field with metadata
+    ComputedField,           # derived field
+    MetricDataField,         # metric with group info
+    DataFormat,              # container for fields
+)
+```
+
+### Profiling
+```python
+from dr_frames import (
+    DFColInfo,               # catalog of column info
+    ColInfo,                 # single column metadata
+    looks_like_json,         # detect JSON strings
+    looks_like_path,         # detect file paths
+    infer_series_base_tag_type,  # infer dtype tags
+)
+```
+
+### Formatting (requires `[formatting]` extra)
+```python
+from dr_frames import (
+    format_table,            # render table in multiple formats
+    format_coverage_table,   # show column coverage stats
+    FORMATTER_TYPES,         # available formatters
+    OUTPUT_FORMATS,          # available output formats
+)
+```
+
+## License
+
+MIT

dr_frames-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "dr-frames"
+version = "0.1.0"
+description = "Pandas/DataFrame utilities for data manipulation, filtering, aggregation, and schema management"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Danielle Rothermel", email = "danielle.rothermel@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = ["pandas", "dataframe", "data-manipulation", "filtering", "aggregation", "schema"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pandas>=2.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+formatting = [
+    "rich>=13.0.0",
+    "tabulate>=0.9.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/drothermel/dr_frames"
+Repository = "https://github.com/drothermel/dr_frames"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build]
+exclude = [
+  "docs",
+  "docs/**",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dr_frames"]
+
+[dependency-groups]
+dev = [
+    "pdoc>=15.0.0",
+    "pytest>=8.4.1",
+    "pyyaml>=6.0.0",
+    "rich>=13.0.0",
+    "ruff>=0.9.0",
+    "tabulate>=0.9.0",
+    "ty>=0.0.14",
+]
+
+[tool.ruff]
+include = [
+    "src/**/*.py",
+    "tests/**/*.py",
+]
+line-length = 88
+cache-dir = ".ruff_cache"
+exclude = ["outputs/*", "notebooks/*", "plots/*", "data/*", "docs/*"]
+
+[tool.ruff.format]
+indent-style = "space"
+quote-style = "double"

dr_frames-0.1.0/src/dr_frames/__init__.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from .aggregation import (
+    aggregate_over_seeds,
+    apply_aggregations,
+    fillna_with_defaults,
+    get_constant_cols,
+    maybe_pipe,
+    unique_by_col,
+    unique_by_cols,
+    unique_non_null,
+)
+from .cells import (
+    apply_column_converters,
+    apply_if_column,
+    ensure_column,
+    fill_missing_values,
+    force_set_cell,
+    group_col_by_prefix,
+    map_column_with_fallback,
+    masked_getter,
+    masked_setter,
+    maybe_update_cell,
+    rename_columns,
+    require_row_index,
+)
+from .columns import (
+    apply_skip,
+    contained_cols,
+    drop_all_null_cols,
+    get_cols_by_contains,
+    get_cols_by_prefix,
+    move_cols_to_beginning,
+    move_cols_with_prefix_to_end,
+    move_numeric_cols_to_end,
+    remaining_cols,
+    strip_col_prefixes,
+    strip_col_prefixes_batch,
+)
+from .filtering import (
+    apply_filters_to_df,
+    filter_to_best_metric,
+    filter_to_range,
+    filter_to_value,
+    filter_to_values,
+    make_filter_fxn,
+    select_subset,
+)
+from .parsing import (
+    is_homogeneous,
+    parse_first_element,
+    parse_list_string,
+    sum_list_elements,
+)
+from .profiling import (
+    ColInfo,
+    DFColInfo,
+    infer_col_name_contains_tags,
+    infer_col_name_prefix_tags,
+    infer_col_name_suffix_tags,
+    infer_series_base_tag_type,
+    infer_tags_from_series_sample,
+    looks_like_json,
+    looks_like_path,
+)
+from .schema import (
+    ComputedField,
+    DataField,
+    DataFormat,
+    MetricDataField,
+)
+from .types import (
+    coerce_numeric_cols,
+    coerce_string_cols,
+    is_string_series,
+)
+
+try:
+    from .formatting import (  # noqa: F401
+        FORMATTER_TYPES,
+        OUTPUT_FORMATS,
+        format_coverage_table,
+        format_table,
+    )
+
+    _HAS_FORMATTING = True
+except ImportError:
+    _HAS_FORMATTING = False
+
+__all__ = [
+    "aggregate_over_seeds",
+    "apply_aggregations",
+    "apply_column_converters",
+    "apply_filters_to_df",
+    "apply_if_column",
+    "apply_skip",
+    "coerce_numeric_cols",
+    "coerce_string_cols",
+    "ColInfo",
+    "ComputedField",
+    "contained_cols",
+    "DataField",
+    "DataFormat",
+    "DFColInfo",
+    "drop_all_null_cols",
+    "ensure_column",
+    "fill_missing_values",
+    "fillna_with_defaults",
+    "filter_to_best_metric",
+    "filter_to_range",
+    "filter_to_value",
+    "filter_to_values",
+    "force_set_cell",
+    "get_cols_by_contains",
+    "get_cols_by_prefix",
+    "get_constant_cols",
+    "group_col_by_prefix",
+    "infer_col_name_contains_tags",
+    "infer_col_name_prefix_tags",
+    "infer_col_name_suffix_tags",
+    "infer_series_base_tag_type",
+    "infer_tags_from_series_sample",
+    "is_homogeneous",
+    "is_string_series",
+    "looks_like_json",
+    "looks_like_path",
+    "make_filter_fxn",
+    "map_column_with_fallback",
+    "masked_getter",
+    "masked_setter",
+    "maybe_pipe",
+    "maybe_update_cell",
+    "MetricDataField",
+    "move_cols_to_beginning",
+    "move_cols_with_prefix_to_end",
+    "move_numeric_cols_to_end",
+    "parse_first_element",
+    "parse_list_string",
+    "remaining_cols",
+    "rename_columns",
+    "require_row_index",
+    "select_subset",
+    "strip_col_prefixes",
+    "strip_col_prefixes_batch",
+    "sum_list_elements",
+    "unique_by_col",
+    "unique_by_cols",
+    "unique_non_null",
+]
+
+if _HAS_FORMATTING:
+    __all__.extend(
+        [
+            "format_table",
+            "format_coverage_table",
+            "FORMATTER_TYPES",
+            "OUTPUT_FORMATS",
+        ]
+    )
+
+__version__ = "0.1.0"