distparser 0.2.0__py3-none-any.whl

distparser/__init__.py

@@ -0,0 +1,21 @@
+"""distparser – parse function-call strings into frozen scipy.stats distributions."""
+
+from distparser.core import (
+    REGISTRY,
+    DistParserError,
+    ParseError,
+    UnknownDistributionError,
+    parse_dist,
+    register_distribution,
+)
+from distparser.version import __version__
+
+__all__ = [
+    "__version__",
+    "DistParserError",
+    "ParseError",
+    "UnknownDistributionError",
+    "REGISTRY",
+    "parse_dist",
+    "register_distribution",
+]

distparser/core.py

@@ -0,0 +1,205 @@
+"""Core parsing logic and distribution registry."""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import Any
+
+from scipy.stats import (
+    beta,
+    cauchy,
+    chi2,
+    expon,
+    f,
+    gamma,
+    laplace,
+    logistic,
+    lognorm,
+    norm,
+    pareto,
+    rayleigh,
+    t,
+    uniform,
+    weibull_min,
+)
+
+__all__ = [
+    "DistParserError",
+    "ParseError",
+    "UnknownDistributionError",
+    "REGISTRY",
+    "parse_dist",
+    "register_distribution",
+]
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class DistParserError(Exception):
+    """Base exception for all distparser errors."""
+
+
+class ParseError(DistParserError):
+    """Raised when a distribution string cannot be parsed."""
+
+
+class UnknownDistributionError(DistParserError):
+    """Raised when a distribution name is not in the registry."""
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+REGISTRY: dict[str, dict[str, Any]] = {
+    # Shape-parameter distributions (alphabetical)
+    "beta": {"class": beta, "param_order": ["a", "b", "loc", "scale"]},
+    "chi2": {"class": chi2, "param_order": ["df", "loc", "scale"]},
+    "f": {"class": f, "param_order": ["dfn", "dfd", "loc", "scale"]},
+    "gamma": {"class": gamma, "param_order": ["a", "loc", "scale"]},
+    "lognorm": {"class": lognorm, "param_order": ["s", "loc", "scale"]},
+    "pareto": {"class": pareto, "param_order": ["b", "loc", "scale"]},
+    "t": {"class": t, "param_order": ["df", "loc", "scale"]},
+    "weibull_min": {"class": weibull_min, "param_order": ["c", "loc", "scale"]},
+    # Loc/scale-only distributions (alphabetical)
+    "cauchy": {"class": cauchy, "param_order": ["loc", "scale"]},
+    "expon": {"class": expon, "param_order": ["loc", "scale"]},
+    "laplace": {"class": laplace, "param_order": ["loc", "scale"]},
+    "logistic": {"class": logistic, "param_order": ["loc", "scale"]},
+    "norm": {"class": norm, "param_order": ["loc", "scale"]},
+    "rayleigh": {"class": rayleigh, "param_order": ["loc", "scale"]},
+    "uniform": {"class": uniform, "param_order": ["loc", "scale"]},
+}
+
+
+def register_distribution(
+    name: str,
+    dist_class: Any,
+    param_order: list[str],
+) -> None:
+    """Register a new distribution in the global registry.
+
+    Args:
+        name: Name used in parse strings (e.g. ``"gumbel"``).
+        dist_class: A scipy.stats distribution class.
+        param_order: Ordered list of parameter names for positional arguments.
+    """
+    REGISTRY[name] = {"class": dist_class, "param_order": list(param_order)}
+
+
+# ---------------------------------------------------------------------------
+# Argument splitting (comma-aware, quote-safe)
+# ---------------------------------------------------------------------------
+
+
+def _split_args(args_str: str) -> list[str]:
+    """Split *args_str* on commas, respecting single- and double-quoted regions.
+
+    Empty parts are filtered out so that ``"norm()"`` yields ``[]``.
+    """
+    parts: list[str] = []
+    current: list[str] = []
+    in_single = False
+    in_double = False
+
+    for ch in args_str:
+        if ch == "'" and not in_double:
+            in_single = not in_single
+            current.append(ch)
+        elif ch == '"' and not in_single:
+            in_double = not in_double
+            current.append(ch)
+        elif ch == "," and not in_single and not in_double:
+            parts.append("".join(current).strip())
+            current = []
+        else:
+            current.append(ch)
+
+    parts.append("".join(current).strip())
+    return [p for p in parts if p]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+_NAME_RE = re.compile(r"^([a-zA-Z_][a-zA-Z0-9_]*)\s*\((.*)\)$")
+
+
+def parse_dist(s: str) -> Any:
+    """Parse a function-call string into a frozen ``scipy.stats`` distribution.
+
+    Args:
+        s: A string like ``"norm(loc=0, scale=1)"`` or ``"uniform(0, 1)"``.
+
+    Returns:
+        A frozen scipy.stats distribution object (callable for ``.rvs()``).
+
+    Raises:
+        ParseError: If the string cannot be parsed.
+        UnknownDistributionError: If the distribution name is not registered.
+
+    Examples:
+        >>> from distparser import parse_dist
+        >>> d = parse_dist("norm(loc=0, scale=1)")
+        >>> d.rvs(size=3)  # doctest: +SKIP
+        array([...])
+    """
+    s = s.strip()
+    m = _NAME_RE.match(s)
+    if not m:
+        raise ParseError(f"Cannot parse {s!r}. Expected format: 'name(args)'.")
+
+    name = m.group(1)
+    if name not in REGISTRY:
+        raise UnknownDistributionError(
+            f"Unknown distribution {name!r}. Registered: {', '.join(sorted(REGISTRY))}."
+        )
+
+    entry = REGISTRY[name]
+    dist_class = entry["class"]
+    param_order: list[str] = entry["param_order"]
+
+    raw_args = _split_args(m.group(2))
+
+    # Separate positional values from keyword assignments
+    positional: list[Any] = []
+    keyword: dict[str, Any] = {}
+
+    for arg in raw_args:
+        arg = arg.strip()
+        if "=" in arg:
+            key, val_str = arg.split("=", 1)
+            key = key.strip()
+            val_str = val_str.strip()
+            keyword[key] = _eval_arg(val_str, s)
+        else:
+            positional.append(_eval_arg(arg, s))
+
+    # Build final parameter dict: positional first, keywords override
+    params: dict[str, Any] = {}
+    for i, value in enumerate(positional):
+        if i >= len(param_order):
+            raise ParseError(
+                f"Too many positional arguments in {s!r}. "
+                f"{name!r} accepts at most {len(param_order)} "
+                f"positional args: {', '.join(param_order)}."
+            )
+        params[param_order[i]] = value
+
+    params.update(keyword)
+
+    return dist_class(**params)
+
+
+def _eval_arg(raw: str, full_str: str) -> Any:
+    """Evaluate a single argument value via ``ast.literal_eval``, with a
+    helpful error message on failure."""
+    try:
+        return ast.literal_eval(raw)
+    except (ValueError, SyntaxError) as exc:
+        raise ParseError(f"Cannot evaluate {raw!r} in {full_str!r}: {exc}") from exc

distparser/version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

distparser-0.2.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: distparser
+Version: 0.2.0
+Summary: Parse function-call strings into frozen scipy.stats distributions
+Author-email: Juyoung Choi <njuyoung35@gmail.com>
+Maintainer-email: Juyoung Choi <njuyoung35@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/njuyoung35/distparser
+Project-URL: Repository, https://github.com/njuyoung35/distparser
+Project-URL: Documentation, https://distparser.readthedocs.io
+Keywords: scipy,distribution,parsing,rvs
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Requires-Python: <3.14,>=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: numpy>=1.21.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-rtd-theme>=2.0.0; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
+Dynamic: license-file
+
+# distparser
+
+**Parse function‑call syntax strings into frozen `scipy.stats` distributions**
+
+[![PyPI version](https://badge.fury.io/py/distparser.svg)](https://badge.fury.io/py/distparser)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why `distparser`?
+
+When you have configuration files or user input that specifies a probability
+distribution (e.g. `"norm(loc=0, scale=1)"`), you want to turn that string
+into a ready‑to‑sample object. `distparser` does exactly that, with a tiny
+API and zero surprises.
+
+## Installation
+
+```bash
+pip install distparser
+```
+
+## Quick Start
+
+```
+from distparser import parse_dist
+
+# Positional arguments (order matters)
+dist = parse_dist("uniform(0, 1)")
+sample = dist.rvs()          # e.g. 0.374
+
+# Keyword arguments (order ignored)
+dist = parse_dist("norm(loc=0, scale=1)")
+samples = dist.rvs(size=5)   # array([-0.12, 1.03, ...])
+
+# Mixed (positional + keyword) – works, but not recommended
+dist = parse_dist("expon(scale=2, loc=1)")
+```
+
+## Supported Distributions
+
+Built‑in registry covers the most common continuous distributions:
+
+- `uniform(loc, scale)`
+- `norm(loc, scale)`
+- `expon(loc, scale)`
+- … and many more (see [docs](https://distparser.readthedocs.io)).
+
+You can **add your own** at runtime:
+
+```python
+from distparser import register_distribution
+from scipy.stats import gumbel_r
+
+register_distribution("gumbel", gumbel_r, ["loc", "scale"])
+```
+
+## Development
+
+See [AGENTS.md](AGENTS.md) for development setup and guidelines.
+
+## License
+
+MIT

distparser-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+distparser/__init__.py,sha256=L9T5BxwGDZreNT1_PTI2uv_HGqz7jx7Z1nhqPBmjNgA,458
+distparser/core.py,sha256=8h90DkS0qPgqz5-Q1KsFjOspR4EJEO4tw_k-jiIjjUI,6382
+distparser/version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+distparser-0.2.0.dist-info/licenses/LICENSE,sha256=u8RNx2_GVxKIxW51x77acSpdaMhiEUg_Qjvw9jqYpVs,1069
+distparser-0.2.0.dist-info/METADATA,sha256=xLGHsex2fbO1EuJVPaGAwiokkcnP7I9BwA4_lFbLziA,2955
+distparser-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+distparser-0.2.0.dist-info/top_level.txt,sha256=DuNswEAnvWst95hInDz0BwoaJK68emKziYILsPiPrYM,11
+distparser-0.2.0.dist-info/RECORD,,

distparser-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

distparser-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juyoung Choi
+
+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.

distparser-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+distparser