From 04c193d33310e24abb7027b607b5125817c20902 Mon Sep 17 00:00:00 2001
From: Vidhi Singh <vidhiii0909@gmail.com>
Date: Sat, 31 Jan 2026 23:21:44 +0530
Subject: [PATCH 1/2] Added docs on Scancode Libraray and added a test

---
 docs/scancode_api_example.py | 9 +++++++++
 1 file changed, 9 insertions(+)
 create mode 100644 docs/scancode_api_example.py

diff --git a/docs/scancode_api_example.py b/docs/scancode_api_example.py
new file mode 100644
index 0000000000..c9ab4e7a51
--- /dev/null
+++ b/docs/scancode_api_example.py
@@ -0,0 +1,9 @@
+import scancode
+import scancode.api
+
+print("ScanCode modules imported successfully")
+
+
+# ScanCode does not currently expose a stable public Python API
+# This example demonstrates importability only
+

From e62c396ddd387fe7cb6e222d36c935a2c3ff0188 Mon Sep 17 00:00:00 2001
From: Vidhi Singh <vidhiii0909@gmail.com>
Date: Sat, 31 Jan 2026 23:22:36 +0530
Subject: [PATCH 2/2] Added docs on Scancode Libraray and added a test

---
 docs/source/how-to-guides/library_usage.rst   | 66 +++++++++++++++++++
 .../test_library_usage_example.py             |  2 +
 2 files changed, 68 insertions(+)
 create mode 100644 docs/source/how-to-guides/library_usage.rst
 create mode 100644 tests/packagedcode/test_library_usage_example.py

diff --git a/docs/source/how-to-guides/library_usage.rst b/docs/source/how-to-guides/library_usage.rst
new file mode 100644
index 0000000000..6ed431a13a
--- /dev/null
+++ b/docs/source/how-to-guides/library_usage.rst
@@ -0,0 +1,66 @@
+Using ScanCode from Python
+=========================
+
+ScanCode Toolkit is primarily designed to be used as a command-line tool.
+At present, it does **not** expose a stable, documented public Python API
+for invoking scans programmatically.
+
+However, ScanCode can still be integrated into Python-based workflows by
+invoking its command-line interface from Python code. ScanCode modules
+can also be imported, though execution-related APIs are considered internal
+and subject to change.
+
+Installation
+------------
+
+ScanCode Toolkit must be installed with all optional dependencies:
+
+.. code-block:: bash
+
+    pip install scancode-toolkit[full]
+
+
+Using ScanCode via subprocess
+-----------------------------
+
+The recommended way to execute a ScanCode scan from Python is by invoking
+the ScanCode command-line interface using the ``subprocess`` module.
+
+.. code-block:: python
+
+    import subprocess
+
+    subprocess.run(
+        [
+            "scancode",
+            "--license",
+            "--json-pp",
+            "results.json",
+            "/path/to/scan",
+        ],
+        check=True,
+    )
+
+
+Importing ScanCode modules
+--------------------------
+
+ScanCode modules can be imported in Python. This can be useful for accessing
+internal utilities or for exploratory purposes, but these APIs are not
+considered stable for running scans.
+
+.. code-block:: python
+
+    import scancode
+    import scancode.api
+
+
+Notes
+-----
+
+- ScanCode does not currently provide a public Python function to run scans
+  directly.
+- Internal APIs may change without notice and should not be relied upon for
+  production integrations.
+- For full scan configuration options, refer to the ScanCode command-line
+  documentation.
diff --git a/tests/packagedcode/test_library_usage_example.py b/tests/packagedcode/test_library_usage_example.py
new file mode 100644
index 0000000000..6f242ed569
--- /dev/null
+++ b/tests/packagedcode/test_library_usage_example.py
@@ -0,0 +1,2 @@
+def test_import_and_basic_scan():
+   import scancode.api