pkg-peiwen-stat 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Peiwen Xu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,74 @@
1
+ Metadata-Version: 2.4
2
+ Name: pkg_peiwen_stat
3
+ Version: 0.1.0
4
+ Summary: 小型统计包:演示真实项目的结构(子包、随包数据、命令行入口、运行时依赖)
5
+ Author-email: Peiwen Xu <pwshyu@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://pypi.org/project/pkg-peiwen-stat/
8
+ Keywords: statistics,demo,packaging
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Requires-Python: >=3.9
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: python-dateutil>=2.8
15
+ Dynamic: license-file
16
+
17
+ # pkg_peiwen_stat
18
+
19
+ 一个小型统计包,用来演示**真实项目**的包结构:三个子包、随包数据集、命令行入口、一个运行时依赖。
20
+
21
+ 它算不了什么高级统计——但它的目录结构,和你真实项目该有的样子是一致的。
22
+
23
+ ## 安装
24
+
25
+ ```bash
26
+ pip install pkg-peiwen-stat
27
+ ```
28
+
29
+ ## 用命令行
30
+
31
+ ```bash
32
+ peiwen-stat # 用内置数据集
33
+ peiwen-stat --json # 输出 JSON
34
+ peiwen-stat --dataset my.csv # 用自己的 csv(需要 name,date,score 三列)
35
+ ```
36
+
37
+ ## 用 Python
38
+
39
+ ```python
40
+ from pkg_peiwen_stat import describe, load_rows
41
+
42
+ rows = load_rows() # 读内置 datasets/scores.csv
43
+ describe([r["score"] for r in rows])
44
+ # {'n': 8, 'mean': ..., 'median': ..., 'stdev': ..., 'q1': ..., 'q3': ...}
45
+ ```
46
+
47
+ ## 目录
48
+
49
+ ```
50
+ src/pkg_peiwen_stat/
51
+ ├── __init__.py # 门面:导出 + 版本号
52
+ ├── _version.py # 版本号单源
53
+ ├── exceptions.py # 自定义异常
54
+ ├── cli.py # 命令行入口
55
+ ├── io/ # 子包:读数据
56
+ │ └── csv_io.py
57
+ ├── stats/ # 子包:算统计量
58
+ │ ├── describe.py
59
+ │ └── compare.py
60
+ └── datasets/ # 子包:随包数据
61
+ └── scores.csv
62
+ ```
63
+
64
+ ## 这个包和 `pkg_peiwen` 的区别
65
+
66
+ | | pkg_peiwen | pkg_peiwen_stat |
67
+ |---|---|---|
68
+ | 模块数 | 1 | 9 |
69
+ | 子包 | 无 | 3(io / stats / datasets) |
70
+ | 随包数据 | 无 | 有(csv) |
71
+ | 命令行入口 | 无 | 有(`peiwen-stat`) |
72
+ | 运行时依赖 | 无 | `python-dateutil` |
73
+
74
+ 两者的 `pyproject.toml` 骨架完全一样,多出来的只有三块配置:`packages.find`、`package-data`、`project.scripts`。
@@ -0,0 +1,58 @@
1
+ # pkg_peiwen_stat
2
+
3
+ 一个小型统计包,用来演示**真实项目**的包结构:三个子包、随包数据集、命令行入口、一个运行时依赖。
4
+
5
+ 它算不了什么高级统计——但它的目录结构,和你真实项目该有的样子是一致的。
6
+
7
+ ## 安装
8
+
9
+ ```bash
10
+ pip install pkg-peiwen-stat
11
+ ```
12
+
13
+ ## 用命令行
14
+
15
+ ```bash
16
+ peiwen-stat # 用内置数据集
17
+ peiwen-stat --json # 输出 JSON
18
+ peiwen-stat --dataset my.csv # 用自己的 csv(需要 name,date,score 三列)
19
+ ```
20
+
21
+ ## 用 Python
22
+
23
+ ```python
24
+ from pkg_peiwen_stat import describe, load_rows
25
+
26
+ rows = load_rows() # 读内置 datasets/scores.csv
27
+ describe([r["score"] for r in rows])
28
+ # {'n': 8, 'mean': ..., 'median': ..., 'stdev': ..., 'q1': ..., 'q3': ...}
29
+ ```
30
+
31
+ ## 目录
32
+
33
+ ```
34
+ src/pkg_peiwen_stat/
35
+ ├── __init__.py # 门面:导出 + 版本号
36
+ ├── _version.py # 版本号单源
37
+ ├── exceptions.py # 自定义异常
38
+ ├── cli.py # 命令行入口
39
+ ├── io/ # 子包:读数据
40
+ │ └── csv_io.py
41
+ ├── stats/ # 子包:算统计量
42
+ │ ├── describe.py
43
+ │ └── compare.py
44
+ └── datasets/ # 子包:随包数据
45
+ └── scores.csv
46
+ ```
47
+
48
+ ## 这个包和 `pkg_peiwen` 的区别
49
+
50
+ | | pkg_peiwen | pkg_peiwen_stat |
51
+ |---|---|---|
52
+ | 模块数 | 1 | 9 |
53
+ | 子包 | 无 | 3(io / stats / datasets) |
54
+ | 随包数据 | 无 | 有(csv) |
55
+ | 命令行入口 | 无 | 有(`peiwen-stat`) |
56
+ | 运行时依赖 | 无 | `python-dateutil` |
57
+
58
+ 两者的 `pyproject.toml` 骨架完全一样,多出来的只有三块配置:`packages.find`、`package-data`、`project.scripts`。
@@ -0,0 +1,31 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "pkg_peiwen_stat"
7
+ version = "0.1.0"
8
+ description = "小型统计包:演示真实项目的结构(子包、随包数据、命令行入口、运行时依赖)"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Peiwen Xu", email = "pwshyu@gmail.com" }]
13
+ requires-python = ">=3.9"
14
+ dependencies = ["python-dateutil>=2.8"]
15
+ keywords = ["statistics", "demo", "packaging"]
16
+ classifiers = [
17
+ "Programming Language :: Python :: 3",
18
+ "Operating System :: OS Independent",
19
+ ]
20
+
21
+ [project.scripts]
22
+ peiwen-stat = "pkg_peiwen_stat.cli:main"
23
+
24
+ [project.urls]
25
+ Homepage = "https://pypi.org/project/pkg-peiwen-stat/"
26
+
27
+ [tool.setuptools.packages.find]
28
+ where = ["src"]
29
+
30
+ [tool.setuptools.package-data]
31
+ pkg_peiwen_stat = ["datasets/*.csv"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,21 @@
1
+ """pkg_peiwen_stat —— 演示真实项目结构的小型统计包。
2
+
3
+ 三个子包(stats / io / datasets)、随包数据、命令行入口,外加一个运行时依赖。
4
+ """
5
+
6
+ from ._version import __version__
7
+ from .exceptions import DataError
8
+ from .io import load_rows
9
+ from .stats import cohens_d, describe, mean, median, quantile, stdev
10
+
11
+ __all__ = [
12
+ "__version__",
13
+ "DataError",
14
+ "load_rows",
15
+ "describe",
16
+ "mean",
17
+ "median",
18
+ "quantile",
19
+ "stdev",
20
+ "cohens_d",
21
+ ]
@@ -0,0 +1,3 @@
1
+ """版本号单源:只在改版本时动这一个文件。"""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,38 @@
1
+ """命令行入口:安装后敲 `peiwen-stat`。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+
8
+ from . import __version__
9
+ from .exceptions import DataError
10
+ from .io import load_rows
11
+ from .stats import describe
12
+
13
+
14
+ def build_parser() -> argparse.ArgumentParser:
15
+ p = argparse.ArgumentParser(prog="peiwen-stat", description="读一份分数表,报描述统计")
16
+ p.add_argument("--dataset", metavar="PATH", help="csv 路径;不填就用内置数据集")
17
+ p.add_argument("--json", action="store_true", help="输出 JSON 而不是表格")
18
+ p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
19
+ return p
20
+
21
+
22
+ def main(argv=None) -> int:
23
+ args = build_parser().parse_args(argv)
24
+ try:
25
+ rows = load_rows(args.dataset)
26
+ stats = describe([r["score"] for r in rows])
27
+ except DataError as exc:
28
+ print(f"出错了:{exc}")
29
+ return 1
30
+
31
+ if args.json:
32
+ print(json.dumps({"rows": len(rows), "stats": stats}, ensure_ascii=False, indent=2))
33
+ return 0
34
+
35
+ print(f"数据:{args.dataset or '内置数据集'} 行数:{stats['n']}")
36
+ for key, label in (("mean", "均值"), ("median", "中位数"), ("stdev", "标准差"), ("q1", "下四分位"), ("q3", "上四分位")):
37
+ print(f" {label:<5}{stats[key]:>8.2f}")
38
+ return 0
@@ -0,0 +1 @@
1
+ """随包数据:scores.csv 会被打进 wheel(见 pyproject 的 package-data)。"""
@@ -0,0 +1,9 @@
1
+ name,date,score
2
+ A,2026-01-05,88
3
+ B,2026-01-06,92
4
+ C,2026-01-07,79
5
+ D,2026-01-08,95
6
+ E,2026-01-09,84
7
+ F,2026-01-12,90
8
+ G,2026-01-13,73
9
+ H,2026-01-14,86
@@ -0,0 +1,5 @@
1
+ """包自己的异常类型。"""
2
+
3
+
4
+ class DataError(ValueError):
5
+ """数据不合法(缺列、空文件、解析失败)时抛出。"""
@@ -0,0 +1,5 @@
1
+ """读取数据。"""
2
+
3
+ from .csv_io import load_rows
4
+
5
+ __all__ = ["load_rows"]
@@ -0,0 +1,51 @@
1
+ """读 csv:不传路径就读随包的内置数据集。
2
+
3
+ 用 importlib.resources 定位文件,这样装到任何地方都找得到;
4
+ 用 dateutil 解析日期列,演示"运行时依赖"是怎么被用上的。
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import csv
10
+ import io
11
+ import pathlib
12
+
13
+ from importlib.resources import files
14
+
15
+ from dateutil import parser as date_parser
16
+
17
+ from ..exceptions import DataError
18
+
19
+ REQUIRED = ("name", "date", "score")
20
+
21
+
22
+ def _read_text(path) -> tuple[str, str]:
23
+ if path is None:
24
+ text = files("pkg_peiwen_stat").joinpath("datasets/scores.csv").read_text(encoding="utf-8")
25
+ return text, "内置数据集 datasets/scores.csv"
26
+ with open(path, encoding="utf-8") as fh:
27
+ return fh.read(), str(path)
28
+
29
+
30
+ def load_rows(path=None) -> list[dict]:
31
+ """读入 name/date/score 三列;date 用 dateutil 解析成 date 对象。"""
32
+ text, source = _read_text(path)
33
+ rows: list[dict] = []
34
+ reader = csv.DictReader(io.StringIO(text))
35
+ missing = [c for c in REQUIRED if c not in (reader.fieldnames or [])]
36
+ if missing:
37
+ raise DataError(f"{source} 缺列:{', '.join(missing)}(需要 {', '.join(REQUIRED)})")
38
+ for row in reader:
39
+ try:
40
+ rows.append(
41
+ {
42
+ "name": row["name"],
43
+ "date": date_parser.parse(row["date"]).date(),
44
+ "score": float(row["score"]),
45
+ }
46
+ )
47
+ except (TypeError, ValueError) as exc:
48
+ raise DataError(f"{source} 有一行格式不对:{row}") from exc
49
+ if not rows:
50
+ raise DataError(f"{source} 是空的")
51
+ return rows
@@ -0,0 +1,6 @@
1
+ """统计量:描述统计与效应量。"""
2
+
3
+ from .compare import cohens_d
4
+ from .describe import describe, mean, median, quantile, stdev
5
+
6
+ __all__ = ["describe", "mean", "median", "quantile", "stdev", "cohens_d"]
@@ -0,0 +1,14 @@
1
+ """两组比较:均值差与 Cohen's d。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .describe import mean, stdev
6
+
7
+
8
+ def cohens_d(a, b) -> float:
9
+ """两组样本的 Cohen's d(用合并标准差)。"""
10
+ sd_a, sd_b = stdev(a), stdev(b)
11
+ pooled = ((sd_a ** 2 + sd_b ** 2) / 2) ** 0.5
12
+ if pooled == 0:
13
+ return 0.0
14
+ return (mean(a) - mean(b)) / pooled
@@ -0,0 +1,67 @@
1
+ """几个最基础的描述统计量,手写实现,不依赖 numpy。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import math
6
+
7
+ from ..exceptions import DataError
8
+
9
+
10
+ def _check(values):
11
+ values = list(values)
12
+ if not values:
13
+ raise DataError("没有数据可算")
14
+ return [float(v) for v in values]
15
+
16
+
17
+ def mean(values) -> float:
18
+ """算术平均。"""
19
+ data = _check(values)
20
+ return sum(data) / len(data)
21
+
22
+
23
+ def median(values) -> float:
24
+ """中位数:偶数个取中间两个的平均。"""
25
+ data = sorted(_check(values))
26
+ n = len(data)
27
+ mid = n // 2
28
+ if n % 2:
29
+ return data[mid]
30
+ return (data[mid - 1] + data[mid]) / 2
31
+
32
+
33
+ def quantile(values, q: float) -> float:
34
+ """分位数,线性插值(和 numpy 的默认算法一致)。q 取 0–1。"""
35
+ if not 0 <= q <= 1:
36
+ raise DataError(f"分位数要在 0–1 之间,收到 {q}")
37
+ data = sorted(_check(values))
38
+ if len(data) == 1:
39
+ return data[0]
40
+ pos = (len(data) - 1) * q
41
+ lo = math.floor(pos)
42
+ hi = math.ceil(pos)
43
+ if lo == hi:
44
+ return data[int(pos)]
45
+ return data[lo] + (pos - lo) * (data[hi] - data[lo])
46
+
47
+
48
+ def stdev(values) -> float:
49
+ """样本标准差(分母 n-1)。"""
50
+ data = _check(values)
51
+ if len(data) < 2:
52
+ raise DataError("样本标准差至少要 2 个数据点")
53
+ mu = sum(data) / len(data)
54
+ return math.sqrt(sum((x - mu) ** 2 for x in data) / (len(data) - 1))
55
+
56
+
57
+ def describe(values) -> dict:
58
+ """一次给出 n / mean / median / stdev / q1 / q3。"""
59
+ data = _check(values)
60
+ return {
61
+ "n": len(data),
62
+ "mean": mean(data),
63
+ "median": median(data),
64
+ "stdev": stdev(data) if len(data) > 1 else 0.0,
65
+ "q1": quantile(data, 0.25),
66
+ "q3": quantile(data, 0.75),
67
+ }
@@ -0,0 +1,74 @@
1
+ Metadata-Version: 2.4
2
+ Name: pkg_peiwen_stat
3
+ Version: 0.1.0
4
+ Summary: 小型统计包:演示真实项目的结构(子包、随包数据、命令行入口、运行时依赖)
5
+ Author-email: Peiwen Xu <pwshyu@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://pypi.org/project/pkg-peiwen-stat/
8
+ Keywords: statistics,demo,packaging
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Requires-Python: >=3.9
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: python-dateutil>=2.8
15
+ Dynamic: license-file
16
+
17
+ # pkg_peiwen_stat
18
+
19
+ 一个小型统计包,用来演示**真实项目**的包结构:三个子包、随包数据集、命令行入口、一个运行时依赖。
20
+
21
+ 它算不了什么高级统计——但它的目录结构,和你真实项目该有的样子是一致的。
22
+
23
+ ## 安装
24
+
25
+ ```bash
26
+ pip install pkg-peiwen-stat
27
+ ```
28
+
29
+ ## 用命令行
30
+
31
+ ```bash
32
+ peiwen-stat # 用内置数据集
33
+ peiwen-stat --json # 输出 JSON
34
+ peiwen-stat --dataset my.csv # 用自己的 csv(需要 name,date,score 三列)
35
+ ```
36
+
37
+ ## 用 Python
38
+
39
+ ```python
40
+ from pkg_peiwen_stat import describe, load_rows
41
+
42
+ rows = load_rows() # 读内置 datasets/scores.csv
43
+ describe([r["score"] for r in rows])
44
+ # {'n': 8, 'mean': ..., 'median': ..., 'stdev': ..., 'q1': ..., 'q3': ...}
45
+ ```
46
+
47
+ ## 目录
48
+
49
+ ```
50
+ src/pkg_peiwen_stat/
51
+ ├── __init__.py # 门面:导出 + 版本号
52
+ ├── _version.py # 版本号单源
53
+ ├── exceptions.py # 自定义异常
54
+ ├── cli.py # 命令行入口
55
+ ├── io/ # 子包:读数据
56
+ │ └── csv_io.py
57
+ ├── stats/ # 子包:算统计量
58
+ │ ├── describe.py
59
+ │ └── compare.py
60
+ └── datasets/ # 子包:随包数据
61
+ └── scores.csv
62
+ ```
63
+
64
+ ## 这个包和 `pkg_peiwen` 的区别
65
+
66
+ | | pkg_peiwen | pkg_peiwen_stat |
67
+ |---|---|---|
68
+ | 模块数 | 1 | 9 |
69
+ | 子包 | 无 | 3(io / stats / datasets) |
70
+ | 随包数据 | 无 | 有(csv) |
71
+ | 命令行入口 | 无 | 有(`peiwen-stat`) |
72
+ | 运行时依赖 | 无 | `python-dateutil` |
73
+
74
+ 两者的 `pyproject.toml` 骨架完全一样,多出来的只有三块配置:`packages.find`、`package-data`、`project.scripts`。
@@ -0,0 +1,21 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/pkg_peiwen_stat/__init__.py
5
+ src/pkg_peiwen_stat/_version.py
6
+ src/pkg_peiwen_stat/cli.py
7
+ src/pkg_peiwen_stat/exceptions.py
8
+ src/pkg_peiwen_stat.egg-info/PKG-INFO
9
+ src/pkg_peiwen_stat.egg-info/SOURCES.txt
10
+ src/pkg_peiwen_stat.egg-info/dependency_links.txt
11
+ src/pkg_peiwen_stat.egg-info/entry_points.txt
12
+ src/pkg_peiwen_stat.egg-info/requires.txt
13
+ src/pkg_peiwen_stat.egg-info/top_level.txt
14
+ src/pkg_peiwen_stat/datasets/__init__.py
15
+ src/pkg_peiwen_stat/datasets/scores.csv
16
+ src/pkg_peiwen_stat/io/__init__.py
17
+ src/pkg_peiwen_stat/io/csv_io.py
18
+ src/pkg_peiwen_stat/stats/__init__.py
19
+ src/pkg_peiwen_stat/stats/compare.py
20
+ src/pkg_peiwen_stat/stats/describe.py
21
+ tests/test_smoke.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ peiwen-stat = pkg_peiwen_stat.cli:main
@@ -0,0 +1 @@
1
+ python-dateutil>=2.8
@@ -0,0 +1 @@
1
+ pkg_peiwen_stat
@@ -0,0 +1,14 @@
1
+ """最朴素的测试:python tests/test_smoke.py(先 pip install -e .)。"""
2
+
3
+ from pkg_peiwen_stat import __version__, cohens_d, describe, load_rows
4
+ from pkg_peiwen_stat.io.csv_io import load_rows as load_rows_again
5
+
6
+ rows = load_rows()
7
+ assert len(rows) >= 5
8
+ assert isinstance(rows[0]["date"], type(rows[0]["date"]))
9
+ stats = describe([r["score"] for r in rows])
10
+ assert stats["n"] == len(rows)
11
+ assert stats["q1"] <= stats["median"] <= stats["q3"]
12
+ assert abs(cohens_d([1, 2, 3], [1, 2, 3])) == 0.0
13
+ assert load_rows_again is load_rows
14
+ print(f"{__version__} 自检通过:{len(rows)} 行, mean={stats['mean']:.2f}")