microdf-python 1.5.8__py3-none-any.whl → 1.5.10__py3-none-any.whl

microdf/_docs.py

@@ -0,0 +1,144 @@
+"""Version-stable rendering of signatures for the API reference.
+
+`str(inspect.signature(...))` is not stable across versions: pandas 2 renders a
+Series annotation as ``pandas.core.series.Series`` and pandas 3 renders the
+same annotation as ``pandas.Series``, and from Python 3.14 ``Optional[int]``
+reprs as ``int | None``.  Generating ``docs/api.md`` from one of those and
+testing it against another is a guaranteed CI failure on some job.
+
+So the page and its test both render signatures through the functions here,
+which strip module qualifiers and put unions into a single form.  There is one
+renderer, imported from one place, so the page cannot disagree with the test.
+"""
+
+import inspect
+import re
+import types
+import typing
+
+__all__ = ["render_annotation", "render_signature", "markdown_signature"]
+
+_NoneType = type(None)
+
+# ``pandas.core.series.Series`` -> ``Series``.  Requires a dot, so string
+# literals inside e.g. ``Literal['a', 'b']`` are untouched.
+_QUALIFIER = re.compile(r"\b(?:[A-Za-z_][A-Za-z0-9_]*\.)+([A-Za-z_][A-Za-z0-9_]*)\b")
+
+
+def _split_top_level(text, sep="|"):
+    parts, depth, current = [], 0, ""
+    for char in text:
+        if char in "[({":
+            depth += 1
+        elif char in "])}":
+            depth -= 1
+        if char == sep and depth == 0:
+            parts.append(current)
+            current = ""
+        else:
+            current += char
+    parts.append(current)
+    return [part.strip() for part in parts]
+
+
+def _union(rendered):
+    """One spelling for a union, whatever the source spelling was."""
+    non_none = [part for part in rendered if part not in ("None", "NoneType")]
+    nones = len(rendered) - len(non_none)
+    if nones and len(non_none) == 1:
+        return f"Optional[{non_none[0]}]"
+    if nones:
+        return "Union[" + ", ".join(non_none + ["NoneType"]) + "]"
+    return "Union[" + ", ".join(non_none) + "]"
+
+
+def _clean_text(text):
+    """Normalise an annotation that reaches us as a string.
+
+    ``from __future__ import annotations`` in pandas means many of its
+    signatures carry string annotations such as ``'int | None'``.
+    """
+    text = text.strip()
+    if len(text) > 1 and text[0] == text[-1] and text[0] in "\"'":
+        text = text[1:-1].strip()
+    text = _QUALIFIER.sub(r"\1", text)
+    if "|" in text:
+        parts = _split_top_level(text)
+        if len(parts) > 1:
+            return _union([_clean_text(part) for part in parts])
+    return text
+
+
+def render_annotation(annotation):
+    """Render an annotation identically under any supported pandas/Python."""
+    if isinstance(annotation, str):
+        return _clean_text(annotation)
+    if isinstance(annotation, typing.ForwardRef):
+        return _clean_text(annotation.__forward_arg__)
+    if annotation is _NoneType:
+        return "NoneType"
+
+    origin = typing.get_origin(annotation)
+    if origin is not None:
+        args = typing.get_args(annotation)
+        if origin is typing.Union or origin is getattr(types, "UnionType", ()):
+            return _union([render_annotation(arg) for arg in args])
+        name = getattr(origin, "__name__", None) or _clean_text(repr(origin))
+        if not args:
+            return name
+        return f"{name}[{', '.join(render_annotation(arg) for arg in args)}]"
+
+    if isinstance(annotation, type):
+        return annotation.__name__
+    return _clean_text(repr(annotation))
+
+
+def render_signature(func):
+    """Render ``func``'s signature, without ``self``, version-stably.
+
+    Parameter names, kinds and defaults come straight from
+    ``inspect.signature``; only the annotation text is normalised.
+    """
+    signature = inspect.signature(func)
+    parts, previous_kind = [], None
+    for parameter in signature.parameters.values():
+        if parameter.name == "self" and not parts:
+            previous_kind = parameter.kind
+            continue
+        if (
+            previous_kind is inspect.Parameter.POSITIONAL_ONLY
+            and parameter.kind is not inspect.Parameter.POSITIONAL_ONLY
+        ):
+            parts.append("/")
+        if parameter.kind is inspect.Parameter.KEYWORD_ONLY and previous_kind not in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.KEYWORD_ONLY,
+        ):
+            parts.append("*")
+
+        rendered = parameter.name
+        if parameter.kind is inspect.Parameter.VAR_POSITIONAL:
+            rendered = "*" + rendered
+        elif parameter.kind is inspect.Parameter.VAR_KEYWORD:
+            rendered = "**" + rendered
+        if parameter.annotation is not inspect.Parameter.empty:
+            rendered += f": {render_annotation(parameter.annotation)}"
+            if parameter.default is not inspect.Parameter.empty:
+                rendered += f" = {parameter.default!r}"
+        elif parameter.default is not inspect.Parameter.empty:
+            rendered += f"={parameter.default!r}"
+        parts.append(rendered)
+        previous_kind = parameter.kind
+
+    if previous_kind is inspect.Parameter.POSITIONAL_ONLY:
+        parts.append("/")
+
+    text = "(" + ", ".join(parts) + ")"
+    if signature.return_annotation is not inspect.Signature.empty:
+        text += f" -> {render_annotation(signature.return_annotation)}"
+    return text
+
+
+def markdown_signature(func):
+    """``render_signature`` escaped for a markdown table cell."""
+    return render_signature(func).replace("|", r"\|")

microdf/microdataframe.py

@@ -41,7 +41,7 @@ class MicroDataFrame(WeightPropagationMixin, pd.DataFrame):
         set_weight_col.
 
         :param weights: Array of weights.
-        :type weights: np.array
+        :type weights: np.ndarray
         """
         super().__init__(*args, **kwargs)
         # pandas normalizes mixed-dimensional concat inputs through this
@@ -429,7 +429,7 @@ class MicroDataFrame(WeightPropagationMixin, pd.DataFrame):
         :param weights: Array of weights.
         :param preserve_old: If True, keeps the old weights as a column when
             new weights are provided.
-        :type weights: np.array
+        :type weights: np.ndarray
         """
         if preserve_old and self.weights_col is not None:
             self["old_" + self.weights_col] = self.weights

microdf/microseries.py

@@ -181,13 +181,13 @@ class MicroSeries(WeightPropagationMixin, pd.Series):
     # Keep inherited fallback paths working after overriding that handler.
     _HANDLED_TYPES = pd.Series._HANDLED_TYPES + (pd.Series, pd.DataFrame)
 
-    def __init__(self, *args, weights: np.array = None, **kwargs):
+    def __init__(self, *args, weights: np.ndarray = None, **kwargs):
         """A Series-inheriting class for weighted microdata.
 
         Weights can be provided at initialisation, or using set_weights.
 
         :param weights: Array of weights.
-        :type weights: np.array
+        :type weights: np.ndarray
         """
         super().__init__(*args, **kwargs)
         self.set_weights(weights)
@@ -347,14 +347,14 @@ class MicroSeries(WeightPropagationMixin, pd.Series):
         return fn
 
     def set_weights(
-        self, weights: np.array, preserve_old: Optional[bool] = False
+        self, weights: np.ndarray, preserve_old: Optional[bool] = False
     ) -> None:
         """Sets the weight values.
 
         :param weights: Array of weights.
         :param preserve_old: If True, keeps the old weights as a column when
             new weights are provided.
-        :type weights: np.array.
+        :type weights: np.ndarray.
         """
         if weights is None:
             self.weights = weight_series(np.ones(len(self)), self.index)
@@ -622,7 +622,7 @@ class MicroSeries(WeightPropagationMixin, pd.Series):
         x, y, weights, _ = pair
         return _weighted_correlation(x, y, weights)
 
-    def quantile(self, q: np.array, skipna: bool = True) -> pd.Series:
+    def quantile(self, q: np.ndarray, skipna: bool = True) -> pd.Series:
         """Calculates weighted quantiles of the MicroSeries.
 
         Uses the inverse CDF method: the q-th quantile is the smallest
@@ -630,7 +630,7 @@ class MicroSeries(WeightPropagationMixin, pd.Series):
         the default behavior of R's survey::svyquantile.
 
         :param q: Quantile(s) to calculate, must be in [0, 1].
-        :type q: float or np.array
+        :type q: float or np.ndarray
         :param skipna: Exclude NaN values (default True). NaN sorts to the
             end of the array, so leaving NaN rows in would let their weight
             inflate the cumulative distribution and push the cutoff upward.
@@ -974,6 +974,11 @@ class MicroSeries(WeightPropagationMixin, pd.Series):
 
     @vector_function
     def quintile_rank(self) -> "MicroSeries":
+        """Calculate weighted quintile ranks (1-5).
+
+        :returns: MicroSeries of quintile ranks.
+        :rtype: MicroSeries
+        """
         return MicroSeries(
             np.minimum(np.ceil(self.rank(pct=True) * 5), 5),
             weights=self.weights,
@@ -981,6 +986,11 @@ class MicroSeries(WeightPropagationMixin, pd.Series):
 
     @vector_function
     def quartile_rank(self) -> "MicroSeries":
+        """Calculate weighted quartile ranks (1-4).
+
+        :returns: MicroSeries of quartile ranks.
+        :rtype: MicroSeries
+        """
         return MicroSeries(
             np.minimum(np.ceil(self.rank(pct=True) * 4), 4),
             weights=self.weights,
@@ -988,6 +998,11 @@ class MicroSeries(WeightPropagationMixin, pd.Series):
 
     @vector_function
     def percentile_rank(self) -> "MicroSeries":
+        """Calculate weighted percentile ranks (1-100).
+
+        :returns: MicroSeries of percentile ranks.
+        :rtype: MicroSeries
+        """
         return MicroSeries(
             np.minimum(np.ceil(self.rank(pct=True) * 100), 100),
             weights=self.weights,

microdf/tests/test_docs_api_coverage.py

@@ -0,0 +1,160 @@
+"""The API reference must list every public method, in both directions.
+
+A one-way check lets the page fall behind the code silently, which is how the
+weighted estimators came to be missing from it.
+"""
+
+import inspect
+import re
+from pathlib import Path
+
+import pytest
+
+import microdf as mdf
+from microdf._docs import markdown_signature
+
+DOCS = Path(__file__).resolve().parents[2] / "docs" / "api.md"
+
+# docs/ is not shipped in the sdist or the wheel, so these cannot run against an
+# installed copy of the package.
+pytestmark = pytest.mark.skipif(
+    not DOCS.exists(), reason="docs/api.md is not present in the installed package"
+)
+
+# Public names that read as internals rather than API a user would call.
+INTERNAL = {
+    "scalar_function",
+    "vector_function",
+    "override_df_functions",
+    "catch_series_relapse",
+    "get_args_as_micro_series",
+}
+
+
+def documented_names():
+    return set(re.findall(r"^\| `(\w+)` \|", DOCS.read_text(), re.M))
+
+
+def public_methods(cls):
+    """Public names this class defines itself.
+
+    Anything inherited unchanged from pandas is pandas' to document; what
+    matters here is what microdf adds or overrides.
+    """
+    names = set()
+    for name, attr in vars(cls).items():
+        if name.startswith("_") or name in INTERNAL:
+            continue
+        if callable(attr) or isinstance(attr, property):
+            names.add(name)
+    return names
+
+
+def test_every_documented_method_exists():
+    documented = documented_names()
+    real = (
+        public_methods(mdf.MicroSeries)
+        | public_methods(mdf.MicroDataFrame)
+        | {"replicate_variance", "replicate_standard_error"}
+    )
+    assert not (documented - real), f"documented but absent: {documented - real}"
+
+
+def test_every_public_method_is_documented():
+    documented = documented_names()
+    for cls in (mdf.MicroSeries, mdf.MicroDataFrame):
+        missing = public_methods(cls) - documented
+        assert not missing, (
+            f"{cls.__name__} methods missing from docs/api.md: {sorted(missing)}"
+        )
+
+
+def test_documented_weight_behaviour_holds():
+    """Pin the claims the page makes that a docstring does not enforce.
+
+    Every error found in review was in a description written by hand rather
+    than taken from a docstring, so the ones that remain are asserted here.
+    """
+    import numpy as np
+    import pandas as pd
+
+    frame = mdf.MicroDataFrame(
+        {"x": [1.0, 2.0, 3.0, 4.0], "y": [1.0, 4.0, 2.0, 8.0]},
+        weights=[1.0, 1.0, 1.0, 5.0],
+    )
+    replicated = pd.DataFrame(
+        {"x": [1.0, 2.0, 3.0] + [4.0] * 5, "y": [1.0, 4.0, 2.0] + [8.0] * 5}
+    )
+
+    # The page says these are frequency-weighted, as of #330.
+    assert frame.cov().loc["x", "y"] == pytest.approx(replicated.cov().loc["x", "y"])
+    assert frame.corr().loc["x", "y"] == pytest.approx(replicated.corr().loc["x", "y"])
+
+    # Each frame cell is the corresponding MicroSeries value.
+    assert frame.cov().loc["x", "y"] == pytest.approx(frame.x.cov(frame.y))
+    assert frame.x.cov(frame.y) == pytest.approx(replicated.cov().loc["x", "y"])
+
+    # The page says equals compares weights.
+    light = mdf.MicroSeries([1, 2, 3], weights=[1, 1, 1])
+    heavy = mdf.MicroSeries([1, 2, 3], weights=[9, 9, 9])
+    assert not light.equals(heavy)
+
+    # The page says cumsum drops the weights.
+    assert not hasattr(frame.x.cumsum(), "weights")
+
+    # The page says repeat repeats the weights alongside the values.
+    repeated = mdf.MicroSeries([1.0, 2.0], weights=[3.0, 4.0]).repeat(2)
+    assert list(np.asarray(repeated.weights)) == [3.0, 3.0, 4.0, 4.0]
+
+
+def test_no_row_is_missing_its_description():
+    """Every documented method needs a description.
+
+    A row whose description cell is blank is the signature of a source change
+    that the page was never regenerated for, which happened three times in
+    review before this test existed.
+    """
+    blank = re.findall(
+        r"^\| `(\w+)` \| (?:`[^`]*`|\*attribute\*) \|\s*\|$", DOCS.read_text(), re.M
+    )
+    assert not blank, f"rows with no description: {blank}"
+
+
+def test_signatures_match_the_live_ones():
+    """The rendered signature must be the one the code actually has.
+
+    The comparison is structural, not textual: both sides go through
+    `microdf._docs.markdown_signature`, which builds the text from parameter
+    names, kinds and defaults (stable across versions) and normalises the
+    annotations, so `pandas.core.series.Series` under pandas 2 and
+    `pandas.Series` under pandas 3 render alike, as do `Optional[int]` and the
+    `int | None` that Python 3.14 reprs it as. `docs/build_api.py` renders the
+    page with the same function, so the page and this test cannot disagree.
+
+    Rows are attributed to the class whose `## ` heading they fall under, since
+    several names exist on both.
+    """
+    current, mismatches = None, []
+    for line in DOCS.read_text().split("\n"):
+        if line.startswith("## MicroSeries"):
+            current = mdf.MicroSeries
+        elif line.startswith("## MicroDataFrame"):
+            current = mdf.MicroDataFrame
+        elif line.startswith("## "):
+            current = None
+        row = re.match(r"^\| `(\w+)` \| `([^`]*)` \|", line)
+        if not row or current is None:
+            continue
+        name, rendered = row.groups()
+        func = inspect.getattr_static(current, name, None)
+        if func is None or isinstance(func, property):
+            continue
+        try:
+            live = markdown_signature(func)
+        except (TypeError, ValueError):
+            continue
+        if live != rendered:
+            mismatches.append((current.__name__, name, rendered, live))
+    assert not mismatches, (
+        f"page is out of date with the code; rerun docs/build_api.py: {mismatches}"
+    )

{microdf_python-1.5.8.dist-info → microdf_python-1.5.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microdf-python
-Version: 1.5.8
+Version: 1.5.10
 Summary: Weighted pandas DataFrames and Series for survey microdata
 Author-email: Max Ghenis <max@policyengine.org>
 License: MIT

{microdf_python-1.5.8.dist-info → microdf_python-1.5.10.dist-info}/RECORD

@@ -1,12 +1,14 @@
 microdf/__init__.py,sha256=G4m4UDiGePngG1i0DdGYhsTAXqyDELR6Mbq72OXOMG0,790
+microdf/_docs.py,sha256=_mNNEUyutcOZxE1bArXnSqNNeNgXIACJQ0BzB6VTtqE,5371
 microdf/_weights.py,sha256=uBOcTZGmVJlzi27sSAALSTb4V9j56tXuaBfJB83x7j0,10303
-microdf/microdataframe.py,sha256=2HFXbS4gAmOQKX6eYcI5vwafCqv9aBzl3lDLODU9SXg,43436
-microdf/microseries.py,sha256=ZjSiUg88zOWAslUl2QpJWK0BcglbG-l7bU6_preOqNs,50039
+microdf/microdataframe.py,sha256=LrNDlb6oYUk6uu3f8a7BzViAd5a_tJa0N_XU5js4gaM,43440
+microdf/microseries.py,sha256=EUOQyAZS3QMqfgI-SMu7I9V45R0TGXv7sv3tOm5oFPY,50483
 microdf/replication.py,sha256=3iZ6xG24ucKofVwmXxyd7ME6rZP6iJVnN9JpWcPxg9s,7697
 microdf/tests/conftest.py,sha256=u-EMyX1-u_nM-YO0RJYCzYHQDXxUI2WQE6GkyJlErqg,150
 microdf/tests/test_aggregation_errors.py,sha256=9jJDiEyxMb2z1Zmj-o8AHDNp8LOputbEkAMefifnWaE,2013
 microdf/tests/test_binary_weight_alignment.py,sha256=d3-e7Kb6G8J22aVFTi3sOGUyDODKT1p0-XsEvMZBDvo,8115
 microdf/tests/test_dataframe_weight_storage.py,sha256=m77cbDn521ehIJWbgirjhL5Q5byBdm-UZhFkGx7mp6A,3667
+microdf/tests/test_docs_api_coverage.py,sha256=-YPtY4xxMzUQ7S2Sib5iF72BpEvz1llBS2IloMh-oxI,5771
 microdf/tests/test_microseries_dataframe.py,sha256=vL0fg_NydU6a5myVVtXyHMr8eQOB_yyAkZYwLmoEnOA,30075
 microdf/tests/test_nullify_weights_index.py,sha256=kZgzMaZEa_PXbsor2S4E-6VRid3C3rcC9ufk0qa7mgY,341
 microdf/tests/test_pandas3_compatibility.py,sha256=A34Ni_WQ303sSNv-sqv5CGAQp54zj-ZSGAPEBHZslNI,8573
@@ -18,8 +20,8 @@ microdf/tests/test_ufunc_weight_dispatch.py,sha256=abQ5I4wFRM3poxO76nbR_1dQymHka
 microdf/tests/test_version_metadata.py,sha256=M1EabzHLKZZw3Djd6Zu2UuMQtDLV6rZ1zDrOU7W_jf0,227
 microdf/tests/test_weight_propagation.py,sha256=YCHZRdeWyWEwnHdpoY1jRBgFLQcBE1nLs61LrcT1wao,20359
 microdf/tests/test_weighted_cov_corr.py,sha256=Ag4YJDy0eH3r_DhOaiX44kEZ0GHuQOoQtBVAOAkBXmw,18291
-microdf_python-1.5.8.dist-info/licenses/LICENSE,sha256=uPs-ASYnzlldpf2z8jeRgQFeEH3FLhSuX0rw0OKWoDU,1067
-microdf_python-1.5.8.dist-info/METADATA,sha256=cG5neCZ-WXOvFPEZNt1saWP2WPD4URKohDdmwn_1t-M,3535
-microdf_python-1.5.8.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-microdf_python-1.5.8.dist-info/top_level.txt,sha256=T2WFPTygQQMdS3GF8YpZ12DKfMGrspbZ3r7z-e3KfiM,8
-microdf_python-1.5.8.dist-info/RECORD,,
+microdf_python-1.5.10.dist-info/licenses/LICENSE,sha256=uPs-ASYnzlldpf2z8jeRgQFeEH3FLhSuX0rw0OKWoDU,1067
+microdf_python-1.5.10.dist-info/METADATA,sha256=p3-fM3i4b6dR59QzsUdNn7uxranyhhqLZmjuIQpielM,3536
+microdf_python-1.5.10.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+microdf_python-1.5.10.dist-info/top_level.txt,sha256=T2WFPTygQQMdS3GF8YpZ12DKfMGrspbZ3r7z-e3KfiM,8
+microdf_python-1.5.10.dist-info/RECORD,,