Created get-min-py pkg

Author: adamlui

docs/README.md

@@ -23,6 +23,15 @@
 [API usage](https://github.com/adamlui/python-utils/tree/main/find-project-root/#api-usage) /
 [Discuss](https://github.com/adamlui/python-utils/discussions)
 
+### <a href="https://github.com/adamlui/python-utils/tree/main/get-min-py/#readme">📊 get-min-py</a>
+
+> Get the minimum Python version required for a PyPI package.
+<br>[Install](https://github.com/adamlui/python-utils/tree/main/get-min-py/#-installation) /
+[Readme](https://github.com/adamlui/python-utils/tree/main/get-min-py/#readme) /
+[API usage](https://github.com/adamlui/python-utils/tree/main/get-min-py/#-api-usage) /
+[CLI usage](https://github.com/adamlui/python-utils/tree/main/get-min-py/#-cli-usage) /
+[Discuss](https://github.com/adamlui/python-utils/discussions)
+
 ### <a href="https://github.com/adamlui/python-utils/tree/main/latin-locales/#readme">🇪🇸 latin-locales</a>
 
 > ISO 639-1 (2-letter) codes for Latin locales.

get-min-py/docs/LICENSE.md

@@ -0,0 +1,21 @@
+# 🏛️ MIT License
+
+**Copyright © 2026 [Adam Lui](https://github.com/adamlui)**
+
+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.

get-min-py/docs/README.md

@@ -0,0 +1,65 @@
+<a id="top"></a>
+
+# > get-min-py
+
+<a href="https://github.com/adamlui/python-utils/releases/tag/get-min-py-1.0.0">
+    <img height=31 src="https://img.shields.io/badge/Latest_Build-1.0.0-32fcee.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://github.com/adamlui/python-utils/blob/main/get-min-py/docs/LICENSE.md">
+    <img height=31 src="https://img.shields.io/badge/License-MIT-f99b27.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.codefactor.io/repository/github/adamlui/python-utils">
+    <img height=31 src="https://img.shields.io/codefactor/grade/github/adamlui/python-utils?label=Code+Quality&logo=codefactor&logoColor=white&labelColor=464646&color=a0fc55&style=for-the-badge"></a>
+<a href="https://sonarcloud.io/component_measures?metric=new_vulnerabilities&id=adamlui_python-utils">
+    <img height=31 src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fsonarcloud.io%2Fapi%2Fmeasures%2Fcomponent%3Fcomponent%3Dadamlui_python-utils%26metricKeys%3Dvulnerabilities&query=%24.component.measures.0.value&style=for-the-badge&logo=sonarcloud&logoColor=white&labelColor=464646&label=Vulnerabilities&color=fafc74"></a>
+
+> ### _Get the minimum Python version required for a PyPI package._
+
+Uses `python-requires`, or classifiers if not found.
+
+## ⚡ Installation
+
+```bash
+pip install get-min-py
+```
+
+## 💻 Command line usage
+
+```bash
+get-min-py <pkg>[,pkg_b,pkg_c] # or check-min-py
+```
+
+Example:
+
+<img src="https://cdn.jsdelivr.net/gh/adamlui/python-utils@97a74a8/get-min-py/assets/images/cli-output.png">
+
+CLI options:
+
+| Option                            | Description
+| --------------------------------- | -----------------
+| `-h`, `--help`                    | Show help screen
+| `-v`, `--version`                 | Show version
+| `-V`, `--debug [targetConfigKey]` | Show debug logs
+| `--docs`                          | Open docs URL
+
+## 🔌 API usage
+
+```py
+import get_min_py
+
+# Single package
+result = get_min_py('requests')
+print(result) # '3.9'
+
+# Multiple packages
+results = get_min_py(['numpy', 'pandas', 'flask'])
+print(results) # ['3.11', '3.11', '3.9']
+```
+
+_Note: Most type checkers will falsely warn_ `get_min_py` _is not a callable module because they are incapable of analyzing runtime behavior (where the module is replaced w/ a function for cleaner, direct access). You can safely suppress such warnings using_ `# type: ignore`.
+
+## MIT License
+
+Copyright © 2023–2026 [Adam Lui](https://github.com/adamlui).
+
+#
+
+<a href="#top">Back to top ↑</a>

get-min-py/docs/SECURITY.md

@@ -0,0 +1,3 @@
+# 🛡️ Security Policy
+
+If you find a vulnerability, please e-mail security@tidelift.com and a fix will be coordinated within 2 business days.

get-min-py/noxfile.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+from types import SimpleNamespace as sn
+
+import nox
+
+pkg = sn(dir=Path(__file__).parent.name)
+pkg.name = pkg.dir.replace('-', '_')
+paths = sn(utils=sn(bump='utils/bump.py', clean='utils/clean.py', publish='utils/publish.sh'))
+
+def session(func) : return nox.session(venv_backend='none', name=func.__name__.replace('_', '-'))(func)
+
+# SESSIONS
+
+@session
+def dev(session) : session.run('pip', 'install', '-e', '.') ; session.run(pkg.dir, '--help', *session.posargs)
+@session
+def debug(session) : session.run('py', '-m', pkg.name, '--debug', *session.posargs, env={ 'PYTHONPATH': 'src' })
+
+@session
+def lint(session) : session.run('ruff', 'check', '.', *session.posargs)
+@session
+def lint_fix(session) : session.run('ruff', 'check', '.', '--fix', *session.posargs)
+
+@session
+def bump_patch(session, no_push=True):
+    cmd = ['py', paths.utils.bump, '--patch']
+    if no_push : cmd.append('--no-push')
+    session.run(*cmd, *session.posargs)
+@session
+def bump_minor(session, no_push=True):
+    cmd = ['py', paths.utils.bump, '--minor']
+    if no_push : cmd.append('--no-push')
+    session.run(*cmd, *session.posargs)
+@session
+def bump_feat(session, no_push=True):
+    bump_minor(session, no_push)
+@session
+def bump_major(session, no_push=True):
+    cmd = ['py', paths.utils.bump, '--major']
+    if no_push : cmd.append('--no-push')
+    session.run(*cmd, *session.posargs)
+
+@session
+def build(session) : clean(session) ; session.run('py', '-m', 'build') ; print('Build complete!')
+@session
+def publish(session) : session.run('bash', paths.utils.publish, *session.posargs)
+
+@session
+def deploy_patch(session) : bump_patch(session, no_push=False) ; build(session) ; publish(session)
+@session
+def deploy_minor(session) : bump_minor(session, no_push=False) ; build(session) ; publish(session)
+@session
+def deploy_feat(session) : deploy_minor(session)
+@session
+def deploy_major(session) : bump_major(session, no_push=False) ; build(session) ; publish(session)
+
+@session
+def clean(session, *args) : session.run('py', paths.utils.clean, *args)

get-min-py/pyproject.toml

@@ -0,0 +1,106 @@
+[build-system]
+requires = [
+    "setuptools~=82.0.0",
+    "wheel",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "get-min-py"
+version = "1.0.0"
+description = "Get the minimum Python version required for a PyPI package."
+authors = [
+    { name = "Adam Lui", email = "adam@kudoai.com" },
+]
+readme = "docs/README.md"
+license = "MIT"
+license-files = [
+    "docs/LICENSE.md",
+]
+dependencies = [
+    "colorama~=0.4.6 ; platform_system == 'Windows'",
+    "json5~=0.13.0",
+    "ucs-detect~=2.0.2",
+]
+requires-python = ">=3.8,<4"
+keywords = [
+    "api",
+    "auto-detect",
+    "classifiers",
+    "cli",
+    "compatibility",
+    "console",
+    "dev-tool",
+    "minimum-version",
+    "package-metadata",
+    "pypi",
+    "python-version",
+    "requires-python",
+    "version-check",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+    "Topic :: Internet",
+    "Topic :: Internet :: WWW/HTTP",
+]
+
+[project.urls]
+Changelog = "https://github.com/adamlui/python-utils/releases/tag/get-min-py-1.0.0"
+Documentation = "https://github.com/adamlui/python-utils/tree/main/get-min-py/docs"
+Funding = "https://github.com/sponsors/adamlui"
+Homepage = "https://github.com/adamlui/python-utils/tree/main/get-min-py/#readme"
+Issues = "https://github.com/adamlui/python-utils/issues"
+"PyPI Stats" = "https://pepy.tech/projects/get-min-py"
+Releases = "https://github.com/adamlui/python-utils/releases"
+Repository = "https://github.com/adamlui/python-utils"
+
+[project.scripts]
+get-min-py = "get_min_py.cli.__main__:main"
+get-min-ver = "get_min_py.cli.__main__:main"
+check-min-py = "get_min_py.cli.__main__:main"
+check-min-ver = "get_min_py.cli.__main__:main"
+getminpy = "get_min_py.cli.__main__:main"
+getminver = "get_min_py.cli.__main__:main"
+checkminpy = "get_min_py.cli.__main__:main"
+checkminver = "get_min_py.cli.__main__:main"
+
+[project.optional-dependencies]
+dev = [
+    "nox>=2026.2.9",
+    "remove-json-keys~=1.8.3",
+    "tomli~=2.4.0",
+    "tomli-w~=1.2.0",
+    "translate-messages~=1.8.3",
+]
+
+[tool.setuptools.packages.find]
+where = [
+    "src",
+]
+
+[tool.setuptools.package-data]
+get_min_py = [
+    "data/*.json",
+    "data/_locales/en/messages.json",
+]

get-min-py/src/get_min_py/__init__.py

@@ -0,0 +1,7 @@
+import sys
+
+from .api import get_min_py
+from . import cli
+
+sys.modules[__name__].cli = cli # type: ignore
+sys.modules[__name__] = get_min_py # type: ignore

get-min-py/src/get_min_py/api.py

@@ -0,0 +1,51 @@
+import json, re, urllib.request as http
+from pathlib import Path
+from typing import Union, List, Optional
+
+api = json.loads((Path(__file__).parent / 'data/package_data.json').read_text())
+
+def get_min_py(pkg_names: Union[str, List[str]]) -> Union[Optional[str], List[Optional[str]]]:
+    if isinstance(pkg_names, str) : pkg_names = [pkg_names]
+    results: List[Optional[str]] = []
+
+    for pkg_name in pkg_names: # get min py
+        try:
+            req = http.Request(f'https://pypi.org/pypi/{pkg_name}/json')
+            req.add_header('User-Agent', f"{api['name']}/{api['version']}")
+            resp = http.urlopen(req, timeout=5)
+            pkg_info = json.loads(resp.read())['info']
+
+            # Check `requires_python`
+            requires_python = pkg_info.get('requires_python')
+            if requires_python:
+                ver_match = re.search(r'(>|>=|==|~=)\s*(\d+\.\d+(?:\.\d+)?)', requires_python)
+                if ver_match:
+                    op, version = ver_match.group(1), ver_match.group(2)
+                    if op == '>': # return minor-bumped
+                        major, minor = version.split('.')[:2]
+                        results.append(f'{major}.{int(minor) + 1}')
+                    else: # >=|==|~=
+                        results.append(version) # as-is
+                    continue # to next pkg
+
+            # Check classifiers
+            classifiers, versions = pkg_info.get('classifiers', []), []
+            for classifier in classifiers:
+                if classifier.startswith('Programming Language :: Python ::'):
+                    ver_match = re.search(r'(\d+(?:\.\d+)?)', classifier)
+                    if ver_match : versions.append(ver_match.group())
+            if versions: # append lowest
+                decimal_vers = [ver for ver in versions if '.' in ver]
+                if decimal_vers:
+                    decimal_vers.sort(key=lambda ver: [int(x) for x in ver.split('.')])
+                    results.append(decimal_vers[0])
+                else:
+                    results.append(min(versions, key=int))
+                continue # to next pkg
+            else : results.append(None)
+
+        except Exception as err:
+            print(f'Error fetching data for {pkg_name}: {err}')
+            results.append(None)
+
+    return results[0] if len(pkg_names) == 1 else results

get-min-py/src/get_min_py/cli/__init__.py

@@ -0,0 +1,31 @@
+import sys
+
+from ..api import get_min_py
+from .lib import init, log, settings
+
+def main():
+    if len(sys.argv) == 1 : sys.argv.append('--help')
+    cli = init.cli()
+
+    # Process early-exit args (e.g. --help, --version)
+    for ctrl_name, ctrl in vars(settings.controls).items():
+        if getattr(ctrl, 'exit', False) and getattr(cli.config, ctrl_name, False):
+            if hasattr(ctrl, 'handler') : ctrl.handler(cli)
+            sys.exit(0)
+
+    # Process pkgs
+    pkgs = []
+    for arg in sys.argv[1:]:
+        if arg.startswith('-') : continue
+        pkgs.extend([pkg.strip() for pkg in arg.split(',') if pkg.strip()])
+    if pkgs:
+        results = get_min_py(pkgs)
+        results = [results] if not isinstance(results, list) else results
+        for pkg, version in zip(pkgs, results):
+            if version:
+                log.info(f'{log.colors.bw}{pkg}:{log.colors.nc} Python {version}')
+            else:
+                log.dim(f'{pkg}: {cli.msgs.log_NO_REQ_FOUND}', no_newline=True)
+        log.line_break()
+
+if __name__ == '__main__' : main()