Clarify Python library usage and document current ScanCode limitations

[vidhiii1711]

Fixes #3130

Tasks

• Removed references to non-existent Python scan APIs from library_usage.rst
• Documented the current limitation of ScanCode’s Python usage
• Added a correct, working example showing how to run ScanCode from Python using subprocess
• Included a minimal import example to demonstrate supported module imports
• Updated tests to validate importability without assuming unsupported APIs

Testing

-> Verified ScanCode modules can be imported successfully
-> Relevant tests were run locally
-> Full test suite was not executed due to long runtime
Signed-off-by: Vidhi Singh [email protected]

[stefan6419846]

Coming from the perspective of an actual API user, the following aspects are not clear to me:

• Why do I need a full installation of SCTK to use the Python-based API?
• If you show that scancode.api can be imported in an example, why not showing actual examples of using it?
• I have been using scancode.api and other specific modules for years without larger issues. Should we really consider it non-stable? (There are some new attributes from time to time, but this generally does not hurt.)

In general, it seems like the docs proposed for this issue in #4473 seem more reasonable.

[vidhiii1711]

@stefan6419846 Thanks for the detailed feedback — that’s very helpful.

I took a conservative approach while documenting this because I couldn’t find an officially documented, supported scan API and wanted to avoid presenting an example that might be misleading for new users.

That said, your point about long-term practical usage of scancode.api makes sense. I’m happy to revise the documentation to include a concrete, real-world example based on commonly used APIs if that’s preferred.

I’ll also revisit the installation section and clarify why a full install is currently recommended.

If you have a specific example or pattern you’d recommend (similar to what’s discussed in #4473), I’d be glad to align the docs with that approach.