Docs for pull request 2304

Author: github-actions[doc-deploy-bot]

pulls/2304/_modules/dpctl/program/utils/_utils.html

@@ -626,6 +626,7 @@ <h1>All modules for which code is available</h1>
 <li><a href="dpctl/enum_types.html">dpctl.enum_types</a></li>
 <li><a href="dpctl/memory/_memory.html">dpctl.memory._memory</a></li>
 <li><a href="dpctl/program/_program.html">dpctl.program._program</a></li>
+<li><a href="dpctl/program/utils/_utils.html">dpctl.program.utils._utils</a></li>
 <li><a href="dpctl/utils/_intel_device_info.html">dpctl.utils._intel_device_info</a></li>
 <li><a href="dpctl/utils/_onetrace_context.html">dpctl.utils._onetrace_context</a></li>
 </ul></ul>

pulls/2304/_modules/index.html

@@ -37,3 +37,15 @@ execution via :py:meth:`dpctl.SyclQueue.submit`.
     :nosignatures:
 
     SyclKernelBundleCompilationError
+
+:py:mod:`dpctl.program.utils`
+-----------------------------
+
+.. py:module:: dpctl.program.utils
+
+.. currentmodule:: dpctl.program.utils
+
+.. autofunction:: parse_spirv_specializations
+
+.. autoclass:: SpecializationConstantInfo
+    :members:

pulls/2304/_sources/api_reference/dpctl/program.rst.txt

@@ -185,7 +185,7 @@
           <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
         </button>
       </div>
-      <label class="toc-overlay-icon toc-header-icon no-toc" for="__toc">
+      <label class="toc-overlay-icon toc-header-icon" for="__toc">
         <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
       </label>
     </div>
@@ -615,7 +615,7 @@
               <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
             </button>
           </div>
-          <label class="toc-overlay-icon toc-content-icon no-toc" for="__toc">
+          <label class="toc-overlay-icon toc-content-icon" for="__toc">
             <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
           </label>
         </div>
@@ -668,6 +668,57 @@
 </tbody>
 </table>
 </div>
+<section id="module-dpctl.program.utils">
+<span id="dpctl-program-utils"></span><h2><a class="reference internal" href="#module-dpctl.program.utils" title="dpctl.program.utils"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpctl.program.utils</span></code></a><a class="headerlink" href="#module-dpctl.program.utils" title="Permalink to this heading">¶</a></h2>
+<dl class="py function">
+<dt class="sig sig-object py" id="dpctl.program.utils.parse_spirv_specializations">
+<span class="sig-prename descclassname"><span class="pre">dpctl.program.utils.</span></span><span class="sig-name descname"><span class="pre">parse_spirv_specializations</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">spv_bytes</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#bytes" title="(in Python v3.14)"><span class="pre">bytes</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#bytearray" title="(in Python v3.14)"><span class="pre">bytearray</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#memoryview" title="(in Python v3.14)"><span class="pre">memoryview</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="(in Python v3.14)"><span class="pre">tuple</span></a><span class="p"><span class="pre">[</span></span><span class="pre">dpctl.program.utils._utils.SpecializationConstantInfo</span><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="../../_modules/dpctl/program/utils/_utils.html#parse_spirv_specializations"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dpctl.program.utils.parse_spirv_specializations" title="Permalink to this definition">¶</a></dt>
+<dd><p>Parses SPIR-V byte stream to extract information about specializations,
+including the specialization IDs, types, names, and default values.</p>
+<p>Note that the dtype information may be imprecise, as the compiler may
+choose to, for example, represent a bool as char, or may represent both
+signed and unsigned integers as unsigned integer bit buckets of the same
+length.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters<span class="colon">:</span></dt>
+<dd class="field-odd"><p><strong>spv_bytes</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#bytes" title="(in Python v3.14)"><em>bytes</em></a><em> | </em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#bytearray" title="(in Python v3.14)"><em>bytearray</em></a><em> | </em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#memoryview" title="(in Python v3.14)"><em>memoryview</em></a>) – the SPIR-V byte stream.</p>
+</dd>
+<dt class="field-even">Returns<span class="colon">:</span></dt>
+<dd class="field-even"><p><p>a tuple of parsed constants and their information represented by
+<cite>SpecializationConstantInfo</cite> objects, sorted by their
+specialization IDs. The length of the tuple is equal to the number
+of specialization constants found. Each
+<cite>SpecializationConstantInfo</cite> object contains the following
+attributes:</p>
+<ul class="simple">
+<li><p><cite>spec_id</cite> (int): The specialization ID.</p></li>
+<li><p><cite>dtype</cite> (str): A NumPy style string representing the data type.</p></li>
+<li><dl class="simple">
+<dt><cite>itemsize</cite> (int): The size of the specialization constant in</dt><dd><p>bytes.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><cite>name</cite> (str): The variable name. If not preserved in the binary,</dt><dd><p>a default name in the format <cite>unnamed_spec_const_{spec_id}</cite> is
+used.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><cite>default_value</cite> (int | float | bool | None): The default value of</dt><dd><p>the specialization constant. If not specified, <cite>None</cite> is used.</p>
+</dd>
+</dl>
+</li>
+</ul>
+</p>
+</dd>
+<dt class="field-odd">Return type<span class="colon">:</span></dt>
+<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="(in Python v3.14)">tuple</a>[SpecializationConstantInfo]</p>
+</dd>
+</dl>
+</dd></dl>
+
+</section>
 </section>
 
         </article>
@@ -713,9 +764,31 @@
 
       </footer>
     </div>
-    <aside class="toc-drawer no-toc">
+    <aside class="toc-drawer">
 
 
+      <div class="toc-sticky toc-scroll">
+        <div class="toc-title-container">
+          <span class="toc-title">
+            On this page
+          </span>
+        </div>
+        <div class="toc-tree-container">
+          <div class="toc-tree">
+            <ul>
+<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpctl.program</span></code></a><ul>
+<li><a class="reference internal" href="#module-dpctl.program.utils"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpctl.program.utils</span></code></a><ul>
+<li><a class="reference internal" href="#dpctl.program.utils.parse_spirv_specializations"><code class="docutils literal notranslate"><span class="pre">parse_spirv_specializations()</span></code></a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+
+          </div>
+        </div>
+      </div>
+      
 
     </aside>
   </div>

pulls/2304/api_reference/dpctl/program.html

@@ -690,7 +690,7 @@ <h2>Installation using pip<a class="headerlink" href="#installation-using-pip" t
 <section id="installation-via-intel-r-distribution-for-python">
 <h2>Installation via Intel(R) Distribution for Python<a class="headerlink" href="#installation-via-intel-r-distribution-for-python" title="Permalink to this heading">¶</a></h2>
 <p><a class="reference external" href="https://www.intel.com/content/www/us/en/developer/tools/oneapi/distribution-for-python.html">Intel(R) Distribution for Python*</a> is distributed as a conda-based installer
-and includes <a class="reference internal" href="../api_reference/dpctl/index.html#module-dpctl" title="dpctl"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpctl</span></code></a> along with its dependencies and sister projects <a class="reference external" href="https://intelpython.github.io/dpnp/overview.html#module-dpnp" title="(in Data Parallel Extension for NumPy v0.21.0dev0+43.g92d2c81563)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpnp</span></code></a>
+and includes <a class="reference internal" href="../api_reference/dpctl/index.html#module-dpctl" title="dpctl"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpctl</span></code></a> along with its dependencies and sister projects <a class="reference external" href="https://intelpython.github.io/dpnp/overview.html#module-dpnp" title="(in Data Parallel Extension for NumPy v0.21.0dev0+65.gffccc2ee6d7)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpnp</span></code></a>
 and <a class="reference external" href="https://intelpython.github.io/numba-dpex/latest/index.html#module-numba_dpex" title="(in numba-dpex)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numba_dpex</span></code></a>.</p>
 <p>Once the installed environment is activated, <code class="docutils literal notranslate"><span class="pre">dpctl</span></code> should be ready to use.</p>
 </section>

pulls/2304/beginners_guides/installation.html

@@ -807,6 +807,13 @@ <h2>D</h2>
 
         <ul>
           <li><a href="api_reference/dpctl/program.html#module-dpctl.program">module</a>
+</li>
+        </ul></li>
+        <li>
+    dpctl.program.utils
+
+        <ul>
+          <li><a href="api_reference/dpctl/program.html#module-dpctl.program.utils">module</a>
 </li>
         </ul></li>
         <li>
@@ -949,15 +956,15 @@ <h2>D</h2>
           <li><a href="api_reference/libsyclinterface/generated/global.html#index-21">function</a>
 </li>
         </ul></li>
+    </ul></td>
+    <td style="width: 33%; vertical-align: top;"><ul>
         <li>
     DPCTLDevice_GetMaxMemAllocSize
 
         <ul>
           <li><a href="api_reference/libsyclinterface/generated/global.html#index-22">function</a>
 </li>
         </ul></li>
-    </ul></td>
-    <td style="width: 33%; vertical-align: top;"><ul>
         <li>
     DPCTLDevice_GetMaxReadImageArgs
 
@@ -1572,6 +1579,8 @@ <h2>M</h2>
           <li><a href="api_reference/dpctl/memory.html#module-dpctl.memory">dpctl.memory</a>
 </li>
           <li><a href="api_reference/dpctl/program.html#module-dpctl.program">dpctl.program</a>
+</li>
+          <li><a href="api_reference/dpctl/program.html#module-dpctl.program.utils">dpctl.program.utils</a>
 </li>
           <li><a href="api_reference/dpctl/utils.html#module-dpctl.utils">dpctl.utils</a>
 </li>
@@ -1653,6 +1662,8 @@ <h2>P</h2>
 </li>
         </ul></li>
         <li><a href="api_reference/dpctl/generated/generated/dpctl.SyclDevice.parent_device.html#dpctl.SyclDevice.parent_device">parent_device (dpctl.SyclDevice attribute)</a>
+</li>
+        <li><a href="api_reference/dpctl/program.html#dpctl.program.utils.parse_spirv_specializations">parse_spirv_specializations() (in module dpctl.program.utils)</a>
 </li>
         <li><a href="api_reference/dpctl/generated/generated/dpctl.SyclDevice.partition_max_sub_devices.html#dpctl.SyclDevice.partition_max_sub_devices">partition_max_sub_devices (dpctl.SyclDevice attribute)</a>
 </li>

pulls/2304/genindex.html

@@ -643,6 +643,12 @@ <h1>Python Module Index</h1>
         <a href="api_reference/dpctl/program.html#module-dpctl.program"><code class="xref">dpctl.program</code></a></td><td>
     <em></em></td>
   </tr>
+  <tr class="cg-1">
+    <td></td>
+    <td>&#160;&#160;&#160;
+        <a href="api_reference/dpctl/program.html#module-dpctl.program.utils"><code class="xref">dpctl.program.utils</code></a></td><td>
+    <em></em></td>
+  </tr>
   <tr class="cg-1">
     <td></td>
     <td>&#160;&#160;&#160;