Added a file format version number to the header

docs/_build/html/_modules/fast_package_file.html

@@ -174,6 +174,8 @@ <h1>Source code for fast_package_file</h1><div class="highlight"><pre>
 <span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span>
     <span class="n">tqdm</span> <span class="o">=</span> <span class="kc">None</span>
 
+<span class="n">FORMAT_VERSION</span> <span class="o">=</span> <span class="mi">1</span>
+
 
 <span class="k">class</span> <span class="nc">PackagedDataFile</span><span class="p">:</span>
     <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data_file_path</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">prepare</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span> <span class="n">decomp_func</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[[</span><span class="nb">bytes</span><span class="p">],</span> <span class="nb">bytes</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
@@ -197,6 +199,10 @@ <h1>Source code for fast_package_file</h1><div class="highlight"><pre>
                 <span class="k">raise</span> <span class="n">PackageDataError</span><span class="p">(</span><span class="s2">&quot;Don&#39;t have read permissions for &#39;</span><span class="si">{}</span><span class="s2">&#39;&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__data_file_path</span><span class="p">))</span>
 
             <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__data_file_path</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">data_file_init</span><span class="p">:</span>
+                <span class="n">format_version</span> <span class="o">=</span> <span class="nb">int</span><span class="o">.</span><span class="n">from_bytes</span><span class="p">(</span><span class="n">data_file_init</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">&#39;little&#39;</span><span class="p">)</span>
+                <span class="k">if</span> <span class="n">format_version</span> <span class="o">!=</span> <span class="n">FORMAT_VERSION</span><span class="p">:</span>
+                    <span class="k">raise</span> <span class="n">PackageDataError</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">{}</span><span class="s2"> is corrupted or malformed (loaded file format version is </span><span class="si">{}</span><span class="s2">, should be </span><span class="si">{}</span><span class="s2">)&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__data_file_path</span><span class="p">,</span> <span class="n">format_version</span><span class="p">,</span> <span class="n">FORMAT_VERSION</span><span class="p">))</span>
+
                 <span class="bp">self</span><span class="o">.</span><span class="n">__loc_data_length</span> <span class="o">=</span> <span class="nb">int</span><span class="o">.</span><span class="n">from_bytes</span><span class="p">(</span><span class="n">data_file_init</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">8</span><span class="p">),</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">&#39;little&#39;</span><span class="p">)</span>  <span class="c1"># read header length</span>
                 <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">__loc_data_length</span> <span class="o">&lt;</span> <span class="mi">0</span> <span class="ow">or</span> <span class="bp">self</span><span class="o">.</span><span class="n">__loc_data_length</span> <span class="o">&gt;</span> <span class="mi">1000000000000</span><span class="p">:</span>  <span class="c1"># 1 TB seems to be a reasonable limit</span>
                     <span class="k">raise</span> <span class="n">PackageDataError</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">{}</span><span class="s2"> is corrupted or malformed (header length is </span><span class="si">{}</span><span class="s2">)&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__data_file_path</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">__loc_data_length</span><span class="p">))</span>
@@ -243,7 +249,7 @@ <h1>Source code for fast_package_file</h1><div class="highlight"><pre>
             <span class="k">raise</span> <span class="n">PackageDataError</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">{}</span><span class="s2"> is corrupted or malformed (file &#39;</span><span class="si">{}</span><span class="s2">&#39; doesn&#39;t exist in location header)&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__data_file_path</span><span class="p">,</span> <span class="n">file</span><span class="p">))</span>
 
         <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__data_file_path</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">data_file</span><span class="p">:</span>
-            <span class="n">data_file</span><span class="o">.</span><span class="n">seek</span><span class="p">(</span><span class="n">file_loc_data</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">__loc_data_length</span> <span class="o">+</span> <span class="mi">10</span><span class="p">)</span>  <span class="c1"># account for header and other data</span>
+            <span class="n">data_file</span><span class="o">.</span><span class="n">seek</span><span class="p">(</span><span class="n">file_loc_data</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">__loc_data_length</span> <span class="o">+</span> <span class="mi">12</span><span class="p">)</span>  <span class="c1"># account for header and other data</span>
             <span class="n">data_file_raw</span> <span class="o">=</span> <span class="n">data_file</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">file_loc_data</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
 
         <span class="k">if</span> <span class="n">file_loc_data</span><span class="p">[</span><span class="mi">2</span><span class="p">]:</span>  <span class="c1"># is compressed</span>
@@ -464,6 +470,7 @@ <h1>Source code for fast_package_file</h1><div class="highlight"><pre>
     <span class="n">loc_data_save_length</span> <span class="o">=</span> <span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">loc_data_save_out</span><span class="p">))</span><span class="o">.</span><span class="n">to_bytes</span><span class="p">(</span><span class="mi">8</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">&#39;little&#39;</span><span class="p">)</span>  <span class="c1"># get its length as an 8 bit binary</span>
 
     <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="s1">&#39;wb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">out_file</span><span class="p">:</span>
+        <span class="n">out_file</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">FORMAT_VERSION</span><span class="o">.</span><span class="n">to_bytes</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">&#39;little&#39;</span><span class="p">))</span>  <span class="c1"># add the file format version</span>
         <span class="n">out_file</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">loc_data_save_length</span><span class="p">)</span>  <span class="c1"># add the header&#39;s length</span>
         <span class="n">out_file</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">compress</span><span class="o">.</span><span class="n">to_bytes</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">&#39;little&#39;</span><span class="p">))</span>  <span class="c1"># add the header&#39;s compressed state</span>
         <span class="n">out_file</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">crc32_paths</span><span class="o">.</span><span class="n">to_bytes</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">byteorder</span><span class="o">=</span><span class="s1">&#39;little&#39;</span><span class="p">))</span>  <span class="c1"># add the header&#39;s path format</span>

docs/_build/html/_sources/guide/format.rst.txt

@@ -3,10 +3,11 @@ Packaged data file format
 
 Although the builder and loader for this format are implemented in Python, the format can of course be read by any languange.
 
-	* ``0x00`` (8-byte unsigned little-endian int): Size of the file location header, in bytes, as stored in the file (i.e. after compression).
-	* ``0x08`` (1-byte bool): Whether the header is compressed (not including these first 10 bytes, which are never compressed).
-	* ``0x09`` (1-byte bool): Whether the file paths use crc32 encoding.
-	* ``0x0A`` (UTF-8 string): The file location header, as JSON.
+	* ``0x00`` (2-byte unsigned little-endian int): File format version.
+	* ``0x01`` (8-byte unsigned little-endian int): Size of the file location header, in bytes, as stored in the file (i.e. after compression).
+	* ``0x09`` (1-byte bool): Whether the header is compressed (not including these first 10 bytes, which are never compressed).
+	* ``0x0A`` (1-byte bool): Whether the file paths use crc32 encoding.
+	* ``0x0B`` (UTF-8 string): The file location header, as JSON.
 	* The rest is file data, placed end-to-end.
 
 File location header (JSON)

docs/_build/html/guide/format.html

@@ -158,10 +158,11 @@ <h1>Packaged data file format<a class="headerlink" href="#packaged-data-file-for
 <p>Although the builder and loader for this format are implemented in Python, the format can of course be read by any languange.</p>
 <blockquote>
 <div><ul class="simple">
-<li><p><code class="docutils literal notranslate"><span class="pre">0x00</span></code> (8-byte unsigned little-endian int): Size of the file location header, in bytes, as stored in the file (i.e. after compression).</p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">0x08</span></code> (1-byte bool): Whether the header is compressed (not including these first 10 bytes, which are never compressed).</p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">0x09</span></code> (1-byte bool): Whether the file paths use crc32 encoding.</p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">0x0A</span></code> (UTF-8 string): The file location header, as JSON.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">0x00</span></code> (2-byte unsigned little-endian int): File format version.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">0x01</span></code> (8-byte unsigned little-endian int): Size of the file location header, in bytes, as stored in the file (i.e. after compression).</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">0x09</span></code> (1-byte bool): Whether the header is compressed (not including these first 10 bytes, which are never compressed).</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">0x0A</span></code> (1-byte bool): Whether the file paths use crc32 encoding.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">0x0B</span></code> (UTF-8 string): The file location header, as JSON.</p></li>
 <li><p>The rest is file data, placed end-to-end.</p></li>
 </ul>
 </div></blockquote>