Full disclosure: UnAIMyText is my employer's product, and it appears third in the tool list near the end. Everything else here is plain Python you can run without us.

The one-line description in pyproject.toml is the most-read sentence in most Python packages, and it's often the least edited. The Python Packaging User Guide's page on writing pyproject.toml says it should be a one-line description of the project, shown as the "headline" of the project page on PyPI and in places like lists of search results. The longer text belongs in readme.

Lately I keep seeing headlines like this one, usually generated along with the scaffold:

[project] name = "snowlog" version = "0.3.1" description = "Snowlog is a powerful and robust Python library that seamlessly empowers developers to streamline winter weather logging workflows." 

So I wrote pydesc, a small linter that reads [project].description, flags the usual problems, and (optionally) asks Qwen on Alibaba Cloud Model Studio for a plainer rewrite. It's 89 lines of Python 3.11+ standard library: tomllib to parse, urllib to call the API. No openai package, no requests.

What it checks

  • missing: no [project].description at all.
  • multi-line: the guide asks for one line.
  • long: over 100 characters. That limit is mine, not a packaging rule; change MAX if you disagree.
  • restates name: the headline starts with the project name, which PyPI already shows right above it.
  • filler opener: "A Python package for...", "This library...". Every package on PyPI is a Python package.
  • buzzwords: a short list (seamless, robust, leverage, powerful, streamline, and so on). Whole words only, so "empowers" doesn't match "empower"; I left that strict on purpose.

Exit code is 0 when the description passes and 1 when anything is flagged, so it can sit in CI.

The code

#!/usr/bin/env python3 """pydesc: lint [project].description in pyproject.toml, optionally ask Qwen for a rewrite.""" import json, os, re, sys, tomllib, urllib.request, urllib.error BUZZ = ["seamless", "seamlessly", "robust", "leverage", "cutting-edge", "comprehensive", "powerful", "effortlessly", "empower", "streamline", "next-generation", "unlock"] MAX = 100 # my own limit, not a packaging rule def lint(path): with open(path, "rb") as f: data = tomllib.load(f) proj = data.get("project", {}) name = proj.get("name", "") desc = proj.get("description") if desc is None: return name, None, ["missing: no [project].description"] issues = [] if "\n" in desc: issues.append("multi-line: description should be one line") if len(desc) > MAX: issues.append(f"long: {len(desc)} chars (limit {MAX})") low = desc.lower() if name and low.startswith(name.lower()): issues.append(f"restates name: starts with '{name}'") if re.match(r"(a|an|this)\s+(python\s+)?(package|library|tool)\b", low): issues.append("filler opener: '" + " ".join(desc.split()[:2]) + " ...'") hits = [w for w in BUZZ if re.search(r"\b" + re.escape(w) + r"\b", low)] if hits: issues.append("buzzwords: " + ", ".join(hits)) return name, desc, issues def rewrite(name, desc): key = os.environ.get("DASHSCOPE_API_KEY") if not key: sys.exit("pydesc: set DASHSCOPE_API_KEY to use --rewrite") base = os.environ.get("QWEN_BASE_URL", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1") body = { "model": os.environ.get("QWEN_MODEL", "qwen-plus"), "max_tokens": 60, "messages": [ {"role": "system", "content": "Rewrite this PyPI one-line description. Plain words, " "under 100 characters, one line, no buzzwords, do not start with the project name. " "Reply with the line only."}, {"role": "user", "content": f"Project: {name}\nDescription: {desc}"}, ], } req = urllib.request.Request(base.rstrip("/") + "/chat/completions", data=json.dumps(body).encode(), headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"}) try: with urllib.request.urlopen(req, timeout=30) as r: out = json.load(r) except urllib.error.HTTPError as e: try: msg = json.load(e)["error"]["code"] except Exception: msg = "no JSON body" sys.exit(f"pydesc: HTTP {e.code} from Qwen ({msg})") return out["choices"][0]["message"]["content"].strip() def main(argv): args = [a for a in argv if a != "--rewrite"] path = args[0] if args else "pyproject.toml" name, desc, issues = lint(path) if not issues: print(f"ok: {desc}") return 0 for i in issues: print(f"{path}: {i}") if "--rewrite" in argv and desc: line = rewrite(name, desc) print(f"suggested: {line}") _, _, again = lint_text(name, line) for i in again: print(f" still: {i}") return 1 def lint_text(name, desc): import tempfile with tempfile.NamedTemporaryFile("w", suffix=".toml", delete=False) as t: t.write("[project]\n" + f"name = {json.dumps(name)}\n" + f"description = {json.dumps(desc)}\n") try: return lint(t.name) finally: os.unlink(t.name) if __name__ == "__main__": sys.exit(main(sys.argv[1:])) 

Running it

python3 pydesc.py samples/robotic.toml python3 pydesc.py samples/robotic.toml --rewrite # needs DASHSCOPE_API_KEY 

Output on the sample above (exit code 1):

samples/robotic.toml: long: 131 chars (limit 100) samples/robotic.toml: restates name: starts with 'snowlog' samples/robotic.toml: buzzwords: seamlessly, robust, powerful, streamline 

And on description = "A Python package for splitting gift costs":

samples/filler.toml: filler opener: 'A Python ...' 

The Qwen call

Model Studio has an OpenAI-compatible interface, so the request is the familiar POST .../chat/completions with a bearer key, model, messages and max_tokens. According to Alibaba Cloud's OpenAI-compatibility docs, the base URL depends on your region, and the API key has to be created in the console of the region whose endpoint you call. The docs also describe newer workspace-based domains (for Singapore, https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1) and ask users to migrate from the older dashscope-intl.aliyuncs.com host. The script defaults to the older Singapore host because it doesn't need a workspace ID; set QWEN_BASE_URL to your workspace URL to follow the migration. The model defaults to qwen-plus and can be changed with QWEN_MODEL.

The rewrite is linted again with the same rules, and anything still wrong is printed as still:. Models don't always follow "under 100 characters."

How I tested it

I don't have a funded Model Studio account, so the honest version is: tested against a local mock, plus one real request with a fake key. 14 checks in a shell script, all passing on Python 3.13.5:

  • each rule fires on its sample, and a clean description prints ok: with exit 0;
  • a missing DASHSCOPE_API_KEY exits with a clear message instead of a traceback;
  • against a small http.server mock, the request goes to /compatible-mode/v1/chat/completions with a Bearer header, model qwen-plus (and qwen-max when overridden), max_tokens 60, a system and a user message, and the user message starts with Project: snowlog;
  • the mock's canned reply prints as a suggestion, and a mock 401 is reported cleanly.

With the mock's canned reply, --rewrite prints:

samples/robotic.toml: long: 131 chars (limit 100) samples/robotic.toml: restates name: starts with 'snowlog' samples/robotic.toml: buzzwords: seamlessly, robust, powerful, streamline suggested: Log winter weather readings and plot them, one command per day 

That suggestion is the mock's fixed text, not a real Qwen answer. The real endpoint with a fake key returned HTTP 401 with the code invalid_api_key, which the script reports as:

pydesc: HTTP 401 from Qwen (invalid_api_key) 

Wiring it into CI

Because the exit code is the only signal, any CI system works. In a GitHub Actions job I run python3 pydesc.py as a plain step after checkout, with nothing to install as long as the runner's Python is 3.11 or newer (that's when tomllib arrived), since everything else is standard library too. I keep --rewrite out of CI on purpose: a pipeline that calls a paid model on every push is a pipeline someone will eventually disable. Locally, I run the rewrite once when the linter complains, read the suggestion, and edit the TOML by hand. The suggestion is a starting point, not a commit.

Five free tools for the human pass

A linter catches patterns; it can't tell you whether the headline sounds like a person wrote it. For the README intro and changelog prose around it:

  1. Vale - a rules-based prose linter you can run in CI next to this one. Great for consistency; it won't rewrite anything.
  2. Hemingway Editor - paste the README intro and it highlights long sentences. Ignore its complaints about technical words.
  3. UnAIMyText - free, no signup, up to 500 words per input in Standard mode. I use it on README intros that came out of a scaffold or an assistant; it turns "a robust, seamless solution for" into plain statements. Check that version numbers and API names survive.
  4. LanguageTool - free grammar checks that mostly leave code-ish terms alone.
  5. QuillBot - fine for rephrasing one sentence; it tends to drift on technical terms, so diff the result.

FAQ

Is this the best free AI humanizer for package descriptions?
For a one-liner, the linter plus your own judgment is usually enough. For longer README intros that sound generated, I'd try UnAIMyText first as a free AI humanizer, with Vale or LanguageTool for checks.

Why not use the openai client with a custom base URL?
You can, and Alibaba's docs show that approach. I wanted zero dependencies for a CI check.

Does PyPI enforce any of these rules?
Not that I'm aware of. These are style checks based on the guide's "one line, headline" description.

Verdict

Lint the headline mechanically, rewrite it with Qwen if you like, and then read it yourself. For the longer prose around it, UnAIMyText is my pick among free AI humanizers, because it strips the generated gloss without touching your facts if you check the output.