Version 3.1.0: Various changes and improvements (#44)

This PR introduces a number of changes and improvements to the library
from real-world use:

 * Packtype grammar (i.e. `.pt` files) updates:
* New `variants` keyword, which can be used for feature-flagging or
allowing different activities to lag the bleeding edge;
* New 'normative points' syntax, which can be used for declaring key
items in an architectural specification that can then be used as anchors
in prose, models, or coverage;
* PackedAssembly gains a recursive tree printer, which can display
complex structures allowing for easier reading of constituent fields;
* PackedArray now extends from `Numeric` which allows it to be used in
comparisons, it also gains a `__str__` method to allow it to be printed
with ease;
* Minor optimisations to `BitVector` which yield a small performance
improvement;
* Extensions to a range of utility methods to better handle core types,
add support for copying instances, diffing two types, and more;
* Moves the minimum Python version forward to 3.12 - this allows for a
number of useful type hinting behaviours.

Author: Intuity

.github/workflows/docs.yml

@@ -25,10 +25,10 @@ jobs:
     timeout-minutes: 15
     steps          :
       - uses: actions/checkout@v4
-      - name: Set up Python 3.11
+      - name: Set up Python 3.13
         uses: actions/setup-python@v5
         with:
-          python-version: 3.11
+          python-version: 3.13
       - name : Install Poetry and environment
         shell: bash
         run  : |

.github/workflows/lint.yml

@@ -13,10 +13,10 @@ jobs:
     timeout-minutes: 15
     steps          :
       - uses: actions/checkout@v4
-      - name: Set up Python 3.11
+      - name: Set up Python 3.13
         uses: actions/setup-python@v5
         with:
-          python-version: 3.11
+          python-version: 3.13
       - name : Install Poetry and environment
         shell: bash
         run  : |

.github/workflows/pr_tests.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v2

docs/syntax/constant.md

@@ -14,15 +14,15 @@ custom grammar:
     from packtype import Constant
 
     @packtype.package()
-    class MyPackage:
+    class ThePackage:
         VALUE_A : Constant = 123
         VALUE_B : Constant[16] = 234
     ```
 
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         VALUE_A : constant = 123
             "Comments may be attached to values with a string following the definition"
         VALUE_B : constant[16] = 234
@@ -38,12 +38,12 @@ custom grammar:
 As rendered to SystemVerilog:
 
 ```sv linenums="1"
-package my_package;
+package the_package;
 
 localparam VALUE_A = 123;
 localparam bit [15:0] VALUE_B = 234;
 
-endpackage : my_package
+endpackage : the_package
 ```
 
 ## Syntax
@@ -58,15 +58,15 @@ allocate it.
 
     ```python linenums="1"
     @packtype.package()
-    class MyPackage:
+    class ThePackage:
         # Format: <NAME> : Constant = <VALUE>
         MY_CONSTANT : Constant = 123
     ```
 
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         // Format: <NAME> : constant = <VALUE>
         MY_CONSTANT : constant = 123
     }
@@ -79,7 +79,7 @@ from the declaration:
 
 ```python linenums="1"
 @packtype.package()
-class MyPackage:
+class ThePackage:
     # Format: <NAME> = <VALUE>
     MY_CONSTANT = 123
 ```
@@ -99,15 +99,15 @@ number of bits.
 
     ```python linenums="1"
     @packtype.package()
-    class MyPackage:
+    class ThePackage:
         # Format: <NAME> : Constant[<WIDTH>] = <VALUE>
         MY_CONSTANT : Constant[8] = 123
     ```
 
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         // Format: <NAME> : constant[<WIDTH>] = <VALUE>
         MY_CONSTANT : constant[8] = 123
     }
@@ -122,7 +122,7 @@ from other constant definitions within the package.
 
     ```python linenums="1"
     @packtype.package()
-    class MyPackage:
+    class ThePackage:
         DOUBLE_WIDTH : Constant = 32
         VALUE_A      : Constant = 9
         VALUE_B      : Constant = 3
@@ -132,7 +132,7 @@ from other constant definitions within the package.
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         DOUBLE_WIDTH : constant = 32
         VALUE_A      : constant = 9
         VALUE_B      : constant = 3
@@ -154,15 +154,15 @@ that is outside the legal range a `ValueError` will be raised:
 
     ```python linenums="1"
     @packtype.package()
-    class MyPackage:
+    class ThePackage:
         # Attempt to store 123 in a 4 bit value
         MY_CONSTANT : Constant[4] = 123
     ```
 
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         // Attempt to store 123 in a 4 bit value
         MY_CONSTANT : constant[4] = 123
     }

docs/syntax/docstrings.md

@@ -13,14 +13,14 @@ Descriptions can be added with normal [Python docstrings]((https://peps.python.o
     from packtype import Constant
 
     @packtype.package()
-    class MyPackage:
+    class ThePackage:
         """
         Package decription,
         using normal Python docstrings
         """
         ...
 
-    @MyPackage.enum()
+    @ThePackage.enum()
     class Fruit:
         """
         Class description,
@@ -35,7 +35,7 @@ Descriptions can be added with normal [Python docstrings]((https://peps.python.o
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         """
         Package description
         using multiline docstring syntax

docs/syntax/enum.md

@@ -15,10 +15,10 @@ custom grammar:
     from packtype import Constant
 
     @packtype.package()
-    class MyPackage:
+    class ThePackage:
         ...
 
-    @MyPackage.enum()
+    @ThePackage.enum()
     class Fruit:
         """Description of the enumeration can go here"""
         APPLE  : Constant
@@ -30,7 +30,7 @@ custom grammar:
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         enum fruit_t {
             "Description of the enumeration can go here"
             @prefix=FRUIT
@@ -45,7 +45,7 @@ custom grammar:
 As rendered to SystemVerilog:
 
 ```sv linenums="1"
-package my_package;
+package the_package;
 
 typedef enum logic [1:0] {
     FRUIT_APPLE,
@@ -54,7 +54,7 @@ typedef enum logic [1:0] {
     FRUIT_BANANA
 } fruit_t;
 
-endpackage : my_package
+endpackage : the_package
 ```
 
 
@@ -151,7 +151,7 @@ values and continue to enumerate from that point:
     import packtype
     from packtype import Constant
 
-    @MyPackage.enum(width=8)
+    @ThePackage.enum(width=8)
     class Opcodes:
         ALU_ADD : Constant = 0x10
         ALU_SUB : Constant # Infers 0x11
@@ -167,7 +167,7 @@ values and continue to enumerate from that point:
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         enum [8] opcodes_t {
           ALU_ADD : constant = 0x10
           ALU_SUB : constant // Infers 0x11

docs/syntax/instance.md

@@ -13,31 +13,31 @@ custom grammar:
     from packtype import Constant, Scalar
 
     @packtype.package()
-    class MyPackage:
+    class ThePackage:
         pass
 
-    @MyPackage.enum()
+    @ThePackage.enum()
     class Month:
         JAN : Constant
         FEB : Constant
         ...
         DEC : Constant
 
-    @MyPackage.struct()
+    @ThePackage.struct()
     class Date:
         year  : Scalar[12]
         month : Month
         day   : Scalar[5]
 
-    MyPackage._pt_attach_instance("SUMMER_START", Month.JUN)
-    MyPackage._pt_attach_instance("SUMMER_END", Month.AUG)
-    MyPackage._pt_attach_instance("CHRISTMAS", Date(year=2025, month=Month.DEC, day=25))
+    ThePackage._pt_attach_instance("SUMMER_START", Month.JUN)
+    ThePackage._pt_attach_instance("SUMMER_END", Month.AUG)
+    ThePackage._pt_attach_instance("CHRISTMAS", Date(year=2025, month=Month.DEC, day=25))
     ```
 
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         enum month_e {
             JAN : constant
             FEB : constant
@@ -64,7 +64,7 @@ custom grammar:
 As rendered to SystemVerilog:
 
 ```sv linenums="1"
-package my_package;
+package the_package;
 
 localparam month_e SUMMER_START = month_e'(7);
 
@@ -77,5 +77,5 @@ localparam date_t CHRISTMAS = '{
     , year: 12'h7E9
 };
 
-endpackage : my_package
+endpackage : the_package
 ```

docs/syntax/package.md

@@ -13,15 +13,15 @@ custom grammar:
     import packtype
 
     @packtype.package()
-    class MyPackage:
+    class ThePackage:
         """Description of what purpose this package serves"""
         ...
     ```
 
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         """Description of what purpose this package serves"""
         // ...
     }
@@ -30,11 +30,11 @@ custom grammar:
 As rendered to SystemVerilog:
 
 ```sv linenums="1"
-package my_package;
+package the_package;
 
 // ...attached definitions...
 
-endpackage : my_package
+endpackage : the_package
 ```
 
 ## Imports

docs/syntax/scalar.md

@@ -14,7 +14,7 @@ custom grammar:
     from packtype import Constant, Scalar
 
     @packtype.package()
-    class MyPackage:
+    class ThePackage:
         # Constants
         TYPE_A_W : Constant = 29
         TYPE_B_W : Constant = 13
@@ -28,7 +28,7 @@ custom grammar:
 === "Packtype (.pt)"
 
     ```sv linenums="1"
-    package my_package {
+    package the_package {
         // Constants
         TYPE_A_W : constant = 29
         TYPE_B_W : constant = 13
@@ -49,7 +49,7 @@ custom grammar:
 As rendered to SystemVerilog:
 
 ```sv linenums="1"
-package my_package;
+package the_package;
 
 localparam TYPE_A_W = 29;
 localparam TYPE_B_W = 13;
@@ -58,7 +58,7 @@ typedef logic [28:0] type_a_t;
 typedef logic [12:0] type_b_t;
 typedef logic [6:0] type_c_t;
 
-endpackage : my_package
+endpackage : the_package
 ```
 
 !!! note
@@ -78,7 +78,7 @@ to unsigned.
 
 ```python
 @packtype.package()
-class MyPackage:
+class ThePackage:
     # Format: <NAME> : Scalar[<WIDTH>, <SIGNED>]
     MyType : Scalar[123, False]
 ```