gh-138952: Document platform.machine() output casing inconsistency across platforms

[Aniketsy]

This PR updates the documentation for platform.machine() in platform.rst to clarify that the output is system-dependent and may differ in casing and naming conventions across platforms.
For example, on Apple Silicon macOS it may return 'arm64' (lowercase), while on Windows-on-ARM it may return 'ARM64' (uppercase).

Please let me know if my approach or fix needs any improvements . I’m open to feedback and happy to make changes based on suggestions.
Thankyou !

---

📚 Documentation preview 📚: https://cpython-previews--138962.org.readthedocs.build/

• Issue: Inconsistency: upper vs lower case inconsistency in platform.machine() on Windows-on-ARM vs Apple Silicon ARM64 #138952

[StanFromIreland]

Please wrap to 79 characters.

[Aniketsy]

Thanks! I’ve updated it.

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[ned-deily]

See my comment on the issue suggesting any wording added here should not imply that the platform string can be parsed consistently for things like CPU architectures.

[juj]

What codebase generates those strings? Is it somehow the underlying native system?

If Python docs recommend users to normalize the strings, shouldn't Python by itself Just Do It for the user? If not, why shouldn't it? I.e. this seems a bit like documenting/validating a bug as intended behavior, without an apparent reason of why that bug should be a feature in the first place.

When ned mentions that platform string should not be parsed to find the current CPU architecture, then that is fine, and like ned pointed out in the ticket, that would be then good to be mentioned in documentation. It also then raises the obvious question of what should users utilize to detect the CPU architecture, if platform.machine() is not it?

I.e. instead of documenting "This function should not be used to detect CPU architecture", a good documentation would state "This function should not be used to detect CPU architecture, because of X. To detect the CPU architecture, see Y instead."

[Aniketsy]

@ned-deily Thanks! for the feedback.
Should it look like this?

.. note::

   The output of :func:`platform.machine` is system-dependent and may differ
   in casing and naming conventions across platforms. The returned string is
   intended for direct equality checks only and should not be parsed or used
   to infer architecture or platform details, as its format may be ambiguous
   or vary between platforms.

Please let me know if I’ve misunderstood your suggestion.

[StanFromIreland]

IMO, I think this whole section is a little excessive, I think just this would be fine:

.. function:: machine()

   Returns the machine type, e.g. ``'AMD64'``. An empty string is returned if the
   value cannot be determined.

   The output is platform-dependent and may differ in casing and naming
   conventions.

If we do want to stay with the note, please remove the link to the function, it is unnecessary.

[Aniketsy]

Should I update the changes as per your suggestions and remove the note section?

[ned-deily]

I agree with @StanFromIreland's suggestion here. @Aniketsy, it would be nice if you could update the PR accordingly.

[Aniketsy]

@ned-deily I’ve updated the PR as suggested.

[miss-islington-app]

Thanks @Aniketsy for the PR, and @ned-deily for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @Aniketsy for the PR, and @ned-deily for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[bedevere-app]

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

[bedevere-app]

GH-139046 is a backport of this pull request to the 3.13 branch.