pandas-dstoolkit 0.15.2__py3-none-any.whl

dstoolkit/__init__.py

@@ -0,0 +1,75 @@
+"""dstoolkit: data cleaning and exploratory analysis helpers for pandas.
+
+Everything is available from the top level:
+
+    import dstoolkit as dst
+
+    df = dst.convert_types(raw)         # yes/no text -> True/False, date text -> dates
+    df = dst.clean(df, missing={"numeric": "median"})
+    dst.show_distribution_profile(df["age"])
+    dst.profile(df).save("report.html")
+    dst.validate(df, {"age": {"min": 0, "max": 120}})
+
+or from its module: `dstoolkit.cleaning`, `dstoolkit.exploration`,
+`dstoolkit.profiling`, `dstoolkit.validation` and `dstoolkit.monitoring`
+(`compare()`: has new data drifted from the training data?). The scikit-learn
+transformers (MissingFiller, OutlierCapper, CategoryEncoder, Scaler, DateFeatures) are in
+`dstoolkit.transformers` and need the optional scikit-learn extra.
+"""
+
+from . import cleaning, exploration, monitoring, profiling, validation
+from ._messages import get_message_output, set_message_output
+from .cleaning import (
+    add_age_column,
+    clean,
+    clean_column_names,
+    convert_types,
+    encode_categorical,
+    fill_missing,
+    find_outliers,
+    handle_outliers,
+    log_transform,
+    normalize,
+    remove_duplicates,
+    standardize_labels,
+    to_boolean,
+    to_category,
+    to_datetime_columns,
+    winsorize,
+)
+from .exploration import (
+    add_passed,
+    associations,
+    drop_nulls,
+    fit_line,
+    show_counts,
+    show_density,
+    show_distribution,
+    show_distribution_profile,
+    show_eda,
+    show_eda_table,
+    show_grouped_box,
+    show_histogram,
+    show_scatter,
+)
+from .monitoring import compare
+from .profiling import ColumnProfile, Profile, Suggestion, TargetProfile, profile
+from .validation import ColumnRule, Comparison, RuleResult, ValidationError, ValidationReport, validate
+
+__version__ = "0.15.2"
+
+# The transformers need scikit-learn (an optional extra), so they're imported on
+# first use: `dst.Scaler` works when scikit-learn is installed, and `import
+# dstoolkit` never needs it.
+_TRANSFORMERS = ("MissingFiller", "OutlierCapper", "CategoryEncoder", "Scaler", "DateFeatures")
+
+
+def __getattr__(name: str) -> object:
+    if name in _TRANSFORMERS:
+        from . import transformers
+        return getattr(transformers, name)
+    raise AttributeError(f"module 'dstoolkit' has no attribute {name!r}")
+
+__all__ = ["cleaning", "exploration", "monitoring", "profiling", "validation", "__version__",
+           "set_message_output", "get_message_output",
+           *cleaning.__all__, *exploration.__all__, *monitoring.__all__, *profiling.__all__, *validation.__all__]

dstoolkit/_messages.py

@@ -0,0 +1,92 @@
+"""Where dstoolkit's one-line summaries go ("Filled missing values: age (263)", ...).
+
+Every message is sent to the standard `logging` logger named "dstoolkit" at
+INFO level. What happens next depends on set_message_output():
+
+- "print" (default): the logger writes the message to the screen (standard
+  output), exactly like print(), so notebooks and scripts show it.
+- "logging": the logger hands messages to your own logging setup instead, so
+  they get your timestamps and format and go wherever your logs go (a file,
+  AWS CloudWatch from a Lambda function, ...).
+- "off": nothing is shown anywhere.
+
+`verbose=False` on any function still silences that one call.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Literal
+
+MessageOutput = Literal["print", "logging", "off"]
+
+logger = logging.getLogger("dstoolkit")
+
+
+class _StdoutHandler(logging.Handler):
+    """Writes the bare message to whatever sys.stdout is at that moment.
+
+    Looking sys.stdout up on every message (rather than once, like
+    logging.StreamHandler) keeps Jupyter, pytest's capsys and
+    contextlib.redirect_stdout working.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            sys.stdout.write(self.format(record) + "\n")
+        except Exception:  # pragma: no cover - logging must never crash the caller
+            self.handleError(record)
+
+
+_console = _StdoutHandler()
+_output: MessageOutput = "print"
+
+
+def set_message_output(output: MessageOutput) -> None:
+    """Choose where dstoolkit's summaries go: "print" (default), "logging" or "off".
+
+    "logging" sends them to the "dstoolkit" logger at INFO level and lets your
+    logging configuration handle them, for example:
+
+        import logging
+        logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s")
+        dst.set_message_output("logging")
+
+    The setting applies to the whole Python session.
+    """
+    global _output
+    if output not in ("print", "logging", "off"):
+        raise ValueError(f'output must be "print", "logging" or "off", got {output!r}')
+    _output = output
+    # Remove every copy of the print handler, including one left by an earlier import of
+    # this module (importlib.reload or Jupyter's %autoreload), so messages never print twice
+    for handler in list(logger.handlers):
+        if type(handler).__name__ == "_StdoutHandler":
+            logger.removeHandler(handler)
+    if output == "print":
+        logger.addHandler(_console)
+        logger.setLevel(logging.INFO)
+        logger.propagate = False      # don't also pass it to the app's logging setup
+    elif output == "logging":
+        logger.setLevel(logging.NOTSET)   # the app's logging configuration decides
+        logger.propagate = True
+    else:
+        logger.setLevel(logging.CRITICAL + 1)
+        logger.propagate = False
+
+
+def get_message_output() -> MessageOutput:
+    """The current setting of set_message_output()."""
+    return _output
+
+
+def say(verbose: bool, message: str) -> None:
+    """Send one summary message, unless this call was made with verbose=False."""
+    if verbose:
+        logger.info(message)
+
+
+if not any(isinstance(h, logging.NullHandler) for h in logger.handlers):
+    logger.addHandler(logging.NullHandler())   # standard library practice for packages
+set_message_output("print")