Rename and expose the Buffer-ish TypeVar for prettier documentation
Marco Ricci

Marco Ricci commited on 2025-01-19 21:23:12
Zeige 1 geänderte Dateien mit 23 Einfügungen und 11 Löschungen.


Choose the more public name `T_Buffer`, and document this type variable,
so that the affected other types' documentation will be easier to read.
... ...
@@ -578,10 +578,22 @@ def clean_up_falsy_vault_config_values(  # noqa: C901,PLR0912
578 578
     return cleanup_completed
579 579
 
580 580
 
581
-B = TypeVar('B', bound=Buffer)
581
+if TYPE_CHECKING:
582
+    T_Buffer = TypeVar('T_Buffer', bound=Buffer)
583
+    """
584
+    A [`TypeVar`][] for classes implementing the [`Buffer`][] interface.
585
+
586
+    Warning:
587
+        Non-public attribute, provided for didactical and educational
588
+        purposes only.  Subject to change without notice, including
589
+        removal.
590
+
591
+        Additionally, this type variable is inaccessible at runtime.
592
+
593
+    """
582 594
 
583 595
 
584
-class SSHKeyCommentPair(NamedTuple, Generic[B]):
596
+class SSHKeyCommentPair(NamedTuple, Generic[T_Buffer]):
585 597
     """SSH key plus comment pair.  For typing purposes.
586 598
 
587 599
     Attributes:
... ...
@@ -590,9 +602,9 @@ class SSHKeyCommentPair(NamedTuple, Generic[B]):
590 602
 
591 603
     """
592 604
 
593
-    key: B
605
+    key: T_Buffer
594 606
     """"""
595
-    comment: B
607
+    comment: T_Buffer
596 608
     """"""
597 609
 
598 610
     def toreadonly(self) -> SSHKeyCommentPair[bytes]:
... ...
@@ -673,7 +685,7 @@ class SSH_AGENT(enum.Enum):  # noqa: N801
673 685
     """"""
674 686
 
675 687
 
676
-class StoreroomKeyPair(NamedTuple, Generic[B]):
688
+class StoreroomKeyPair(NamedTuple, Generic[T_Buffer]):
677 689
     """A pair of AES256 keys, one for encryption and one for signing.
678 690
 
679 691
     Attributes:
... ...
@@ -685,9 +697,9 @@ class StoreroomKeyPair(NamedTuple, Generic[B]):
685 697
 
686 698
     """
687 699
 
688
-    encryption_key: B
700
+    encryption_key: T_Buffer
689 701
     """"""
690
-    signing_key: B
702
+    signing_key: T_Buffer
691 703
     """"""
692 704
 
693 705
     def toreadonly(self) -> StoreroomKeyPair[bytes]:
... ...
@@ -698,7 +710,7 @@ class StoreroomKeyPair(NamedTuple, Generic[B]):
698 710
         )
699 711
 
700 712
 
701
-class StoreroomMasterKeys(NamedTuple, Generic[B]):
713
+class StoreroomMasterKeys(NamedTuple, Generic[T_Buffer]):
702 714
     """A triple of AES256 keys, for encryption, signing and hashing.
703 715
 
704 716
     Attributes:
... ...
@@ -713,11 +725,11 @@ class StoreroomMasterKeys(NamedTuple, Generic[B]):
713 725
 
714 726
     """
715 727
 
716
-    hashing_key: B
728
+    hashing_key: T_Buffer
717 729
     """"""
718
-    encryption_key: B
730
+    encryption_key: T_Buffer
719 731
     """"""
720
-    signing_key: B
732
+    signing_key: T_Buffer
721 733
     """"""
722 734
 
723 735
     def toreadonly(self) -> StoreroomMasterKeys[bytes]:
724 736