gh-131178: Fix mimetypes CLI docs to mention that errors go to stdout by htjworld · Pull Request #149683 · python/cpython

htjworld · 2026-05-11T14:39:18Z

The mimetypes documentation states that errors go to the standard error stream, but the CLI has always written all output — including errors — to stdout.

Fix the documentation to match the actual behavior, and add subprocess-based tests for the command-line interface.

Changes:

Doc/library/mimetypes.rst: Correct "standard error stream" → "standard output stream"; update stale examples (filename.pict is now a recognized type, error message strings did not match actual output).
Lib/test/test_mimetypes.py: Add subprocess-based tests verifying CLI output format and exit codes.

Issue: Add tests for command-line interface #131178

read-the-docs-community · 2026-05-11T14:42:07Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32921239 | 📁 Comparing 4b28aed against main (2d3dec0)

🔍 Preview build

63 files changed · + 1 added · ± 62 modified

+ Added

deprecations/pending-removal-in-3.21.html

± Modified

sobolevn

This is a rather hard problem: when docs do not represent the reality, we can either fix docs or fix the code.

I guess a lot of places already rely on the fact that errors and results are in the stdout, not in stderr.

So, I think that it would be better to change the docs.

sobolevn · 2026-05-11T15:06:29Z

+
+    def test_type_lookup(self):
+        rc, stdout, stderr = assert_python_ok('-m', 'mimetypes', 'foo.pdf')
+        self.assertIn(b'application/pdf', stdout)


Why not asserting the full stdout contents?

sobolevn · 2026-05-11T15:07:25Z

+    def test_type_lookup_unknown(self):
+        rc, stdout, stderr = assert_python_failure('-m', 'mimetypes', 'foo.unknownext12345')
+        self.assertEqual(stdout, b'')
+        self.assertIn(b'error:', stderr)


And the same here: we can assert the full error response.

sobolevn · 2026-05-11T15:08:17Z

+    has_error = False
+    for result in results:
+        if result.startswith("error: "):
+            print(result, file=sys.stderr, flush=True)


This is a behavior change, please revert it.

sobolevn · 2026-05-11T15:08:49Z

@@ -0,0 +1,2 @@
+Fix :mod:`mimetypes` CLI to write error messages to stderr instead of stdout,


And since we revert the behavior change, we need to remove this file as well :)

Per sobolevn's review: revert the behavior change that routed error messages to stderr, as existing code may rely on stdout behavior. Instead update docs to accurately reflect that errors go to stdout. Also update tests to assert full output contents as suggested.

htjworld · 2026-05-11T15:56:41Z

I have made the requested changes; please review again

bedevere-app · 2026-05-11T15:56:47Z

Thanks for making the requested changes!

: please review the changes made to this pull request.

sobolevn · 2026-05-11T16:36:21Z

+
+    def test_unknown_flag(self):
+        rc, stdout, stderr = assert_python_failure('-m', 'mimetypes', '--unknown-flag')
+        self.assertNotEqual(rc, 0)


assert the output please :)

sobolevn · 2026-05-11T16:39:09Z

@@ -0,0 +1,2 @@
+Add subprocess-based tests for the :mod:`mimetypes` command-line interface,


we don't add news for docs / tests only changes.

sobolevn · 2026-05-11T16:41:14Z

+
+    def test_extension_flag(self):
+        rc, stdout, stderr = assert_python_ok('-m', 'mimetypes', '-e', 'image/jpeg')
+        self.assertIn(b'.jpg', stdout)


Let's use assertEqual here as well.

htjworld · 2026-05-11T22:11:58Z

thanks for the review appreciate it
I have made the requested changes; please review again

bedevere-app · 2026-05-11T22:12:04Z

Thanks for making the requested changes!

: please review the changes made to this pull request.

sobolevn · 2026-05-12T07:33:30Z

+    def test_unknown_flag(self):
+        rc, stdout, stderr = assert_python_failure('-m', 'mimetypes', '--unknown-flag')
+        self.assertEqual(stdout, b'')
+        self.assertIn(b'error', stderr)


Suggested change

self.assertIn(b'error', stderr)

self.assertIn(b'error: unrecognized arguments: --unknown-flag', stderr)

python-cla-bot · 2026-05-12T08:02:38Z

All commit authors signed the Contributor License Agreement.

sobolevn

Thanks!

sobolevn · 2026-05-12T11:58:19Z

CC @clin1234 who commits regularly to mimetypes :)

clin1234

If CI passes, it LGTM ;-)

htjworld · 2026-05-31T06:39:33Z

Hi @sobolevn, gentle ping 🙂 — is there anything else needed on my end for this to move forward? Thanks!

…docs Restore the original filename.pict / --lenient example and the filename.xxx multi-input example. Keep only the genuinely-needed fix: the error message string ("unknown extension of X" was never emitted; the CLI prints "media type unknown for X").

Co-authored-by: sobolevn <mail@sobolevn.me>

sobolevn · 2026-05-31T07:17:19Z

Thanks a lot!

htjworld · 2026-05-31T07:20:12Z

Thank you for the thorough review!

miss-islington-app · 2026-05-31T07:45:52Z

Thanks @htjworld for the PR, and @sobolevn for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

miss-islington-app · 2026-05-31T07:46:05Z

Sorry, @htjworld and @sobolevn, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 2b94b923943a1f75cdbd5a5e4e2eb5f93eb43e23 3.13

bedevere-app · 2026-05-31T07:46:05Z

GH-150655 is a backport of this pull request to the 3.15 branch.

bedevere-app · 2026-05-31T07:46:10Z

GH-150656 is a backport of this pull request to the 3.14 branch.

sobolevn · 2026-05-31T07:50:04Z

@htjworld can you please follow the instructions in #149683 (comment) and create a manual 3.13 backport?

htjworld · 2026-05-31T08:09:58Z

@sobolevn, I looked into the 3.13 backport — the mimetypes CLI was reworked after 3.13, so the changes don't seem to apply cleanly:

The Command-line usage section this PR edits doesn't exist in 3.13 (it appears to have been added in 3.14).
The 3.13 CLI still uses the old getopt-based implementation and prints I don't know anything about type X rather than error: media type unknown for X, so the new CommandLineSubprocessTest assertions would fail there.

Would it make sense to drop the needs backport to 3.13 label?

sobolevn · 2026-05-31T08:10:41Z

Then no - thanks for the investigation :)

…tdout (GH-149683) (#150656) gh-131178: Fix mimetypes CLI docs, mention that errors go to stdout (GH-149683) (cherry picked from commit 2b94b92) Co-authored-by: htjworld <116538001+htjworld@users.noreply.github.com> Co-authored-by: sobolevn <mail@sobolevn.me>

…tdout (GH-149683) (#150655) gh-131178: Fix mimetypes CLI docs, mention that errors go to stdout (GH-149683) (cherry picked from commit 2b94b92) Co-authored-by: htjworld <116538001+htjworld@users.noreply.github.com> Co-authored-by: sobolevn <mail@sobolevn.me>

pythongh-149682: Fix mimetypes CLI to write error messages to stderr

c87667b

htjworld requested a review from a team as a code owner May 11, 2026 14:39

bedevere-app Bot mentioned this pull request May 11, 2026

mimetypes CLI writes error messages to stdout instead of stderr #149682

Closed

bedevere-app Bot added the awaiting review label May 11, 2026

htjworld mentioned this pull request May 11, 2026

gh-131178: Add tests for mimetypes command-line interface #149681

Closed

Remove inline comments from docs examples

77e5b2a

htjworld changed the title ~~gh-149682: Fix mimetypes CLI to write error messages to stderr~~ Fix mimetypes CLI to write error messages to stderr May 11, 2026

htjworld changed the title ~~Fix mimetypes CLI to write error messages to stderr~~ gh-149682: Fix mimetypes CLI to write error messages to stderr May 11, 2026

htjworld changed the title ~~gh-149682: Fix mimetypes CLI to write error messages to stderr~~ gh-131178: Fix mimetypes CLI to write error messages to stderr May 11, 2026

bedevere-app Bot mentioned this pull request May 11, 2026

Add tests for command-line interface #131178

Open

9 tasks

sobolevn reviewed May 11, 2026

View reviewed changes

htjworld added 2 commits May 12, 2026 00:33

Add NEWS entry for mimetypes CLI tests

ad605cd

bedevere-app Bot added awaiting change review and removed awaiting review labels May 11, 2026

sobolevn reviewed May 11, 2026

View reviewed changes

Address review feedback: strengthen test assertions, remove NEWS entry

f6db7b1

sobolevn reviewed May 12, 2026

View reviewed changes

sobolevn added the skip news label May 12, 2026

pythongh-131178: fix test_unknown_flag to supply positional arg

edf95da

pythongh-131178: add @force_not_colorized to test_unknown_flag

b00896c

sobolevn approved these changes May 12, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting change review labels May 12, 2026

clin1234 reviewed May 12, 2026

View reviewed changes

sobolevn changed the title ~~gh-131178: Fix mimetypes CLI to write error messages to stderr~~ gh-131178: Fix mimetypes CLI docs to mention that errors go to stdout May 31, 2026

sobolevn added needs backport to 3.15 pre-release feature fixes, bugs and security fixes needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels May 31, 2026

Merge branch 'main' into pythongh-149682-mimetypes-fix-stderr

e0409b3

sobolevn reviewed May 31, 2026

View reviewed changes

Comment thread Doc/library/mimetypes.rst

Comment thread Doc/library/mimetypes.rst

sobolevn reviewed May 31, 2026

View reviewed changes

Comment thread Doc/library/mimetypes.rst

Update Doc/library/mimetypes.rst

4b28aed

Co-authored-by: sobolevn <mail@sobolevn.me>

sobolevn approved these changes May 31, 2026

View reviewed changes

sobolevn enabled auto-merge (squash) May 31, 2026 07:17

sobolevn merged commit 2b94b92 into python:main May 31, 2026
52 checks passed

bedevere-app Bot removed the awaiting merge label May 31, 2026

bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label May 31, 2026

miss-islington-app Bot assigned sobolevn May 31, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label May 31, 2026

		@@ -0,0 +1,2 @@
		Fix :mod:`mimetypes` CLI to write error messages to stderr instead of stdout,

		@@ -0,0 +1,2 @@
		Add subprocess-based tests for the :mod:`mimetypes` command-line interface,

	self.assertIn(b'error', stderr)
	self.assertIn(b'error: unrecognized arguments: --unknown-flag', stderr)

Uh oh!

Conversation

htjworld commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

sobolevn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

htjworld commented May 11, 2026

Uh oh!

bedevere-app Bot commented May 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

htjworld commented May 11, 2026

Uh oh!

bedevere-app Bot commented May 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

python-cla-bot Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sobolevn left a comment

Choose a reason for hiding this comment

Uh oh!

sobolevn commented May 12, 2026

Uh oh!

clin1234 left a comment

Choose a reason for hiding this comment

Uh oh!

htjworld commented May 31, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sobolevn commented May 31, 2026

Uh oh!

htjworld commented May 31, 2026

Uh oh!

Uh oh!

miss-islington-app Bot commented May 31, 2026

Uh oh!

miss-islington-app Bot commented May 31, 2026

Uh oh!

bedevere-app Bot commented May 31, 2026

Uh oh!

bedevere-app Bot commented May 31, 2026

Uh oh!

sobolevn commented May 31, 2026

Uh oh!

htjworld commented May 31, 2026

Uh oh!

sobolevn commented May 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

htjworld commented May 11, 2026 •

edited

Loading

read-the-docs-community Bot commented May 11, 2026 •

edited

Loading

python-cla-bot Bot commented May 12, 2026 •

edited

Loading