Skip to content

docs: rewrite README with examples, API reference, use cases - #1

Merged
kaizhu256 merged 10 commits into
sqlmath:betafrom
ababber:docs/readme-rewrite
Apr 8, 2026
Merged

docs: rewrite README with examples, API reference, use cases#1
kaizhu256 merged 10 commits into
sqlmath:betafrom
ababber:docs/readme-rewrite

Conversation

@ababber

@ababber ababber commented Mar 27, 2026

Copy link
Copy Markdown
Contributor

Summary

Complete README rewrite: value proposition, quick start (Python, Node, browser), categorized SQL functions, LightGBM (with Kaggle notebook link), use cases, comparison table, Python API reference, platform notes, and build instructions.

Review fixes (pre-merge):

  • Rolling median example uses PERCENTILE(..., 50) OVER(...)MEDIAN2 is aggregate-only and cannot be used as a window function
  • ARM64 row in platform table softened to "limited testing" pending verification

Test plan

  • npm run test --fast (maintainer)
  • Examples cross-checked against sqlmath source and live Python runs

Made with Cursor

- Full README from shadow work; final review fixes
- Use PERCENTILE for rolling median (MEDIAN2 is not window-capable)
- Soften ARM64 claim pending hardware verification

Made-with: Cursor
@kaizhu256

Copy link
Copy Markdown
Contributor
  • thx so much for the documentation! it looks so much better
  • can you look into this ci error? looks like there's a few invalid unicode characters in README.md
~/Documents/sqlmath$ python setup.py sdist

Traceback (most recent call last):
  File "C:\Users\kai.zhu\Documents\sqlmath\setup.py", line 647, in <module>
    main()
  File "C:\Users\kai.zhu\Documents\sqlmath\setup.py", line 617, in main
    build_sdist("dist")
  File "C:\Users\kai.zhu\Documents\sqlmath\setup.py", line 403, in build_sdist
    build_pkg_info()
  File "C:\Users\kai.zhu\Documents\sqlmath\setup.py", line 387, in build_pkg_info
    data += file1.read().strip() + "\n"
            ^^^^^^^^^^^^
  File "C:\Python312\Lib\encodings\cp1252.py", line 23, in decode
    return codecs.charmap_decode(input,self.errors,decoding_table)[0]
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
UnicodeDecodeError: 'charmap' codec can't decode byte 0x9d in position 11173: character maps to <undefined>

ababber added 2 commits March 27, 2026 15:57
…aths in CI

- setup.py: open pyproject.toml, README.md, MANIFEST.in, PKG-INFO, and
  sdist temp script with encoding=utf-8 (fixes cp1252 UnicodeDecodeError
  when embedding README in PKG-INFO on Windows).
- .ci.sh: resolve libomp via Homebrew ARM, Intel, or HOMEBREW_PREFIX;
  remove stale dylibs before copy; use pip show lightgbm for site-packages.
- PKG-INFO: regenerated from current README.md.

Made-with: Cursor
ababber added 3 commits April 3, 2026 12:58
Resolve README: keep rewritten intro and badges, restore Status table and
maintainer sections from upstream; dedupe Changelog block.

Made-with: Cursor
@ababber

ababber commented Apr 7, 2026

Copy link
Copy Markdown
Contributor Author

@kaizhu256

Following up on your previous comment:

  • UnicodeDecodeError when running python setup.py sdist on Windows with README.md embedded in PKG-INFO, that path is addressed on beta now: setup.py reads README.md (and related metadata files) with encoding="utf-8"
  • Windows no longer defaults to cp1252 and chokes on UTF-8 in the README (e.g. smart punctuation). The fix landed with fix: Windows UTF-8 sdist + Darwin libomp / lightgbm CI paths #3 -> v2026.3.31.
  • docs/readme-rewrite branch has beta merged in, so it carries the same setup.py behavior.

Merge readiness (FYI)

  • CI: Latest ci run is green on macos-15-intel, macos-latest, ubuntu-latest, and windows-2022 (full matrix for this PR).
  • Scope: This PR is documentation-only (README.md); no intent to change tooling or workflows beyond what’s already on beta via fix: Windows UTF-8 sdist + Darwin libomp / lightgbm CI paths #3.
  • Your side: maintainerCanModify is on — if you want tiny wording tweaks, feel free to edit the branch directly. If you prefer a clean history, squash-merge with the existing PR title (or similar) works.

Let me know if you'd like to change anything!

@kaizhu256
kaizhu256 merged commit 0cd78c1 into sqlmath:beta Apr 8, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants