rfctr: modernize opc.shared.lazyproperty

No need for two, use the already modernized `docx.shared.lazyproperty`.

Author: scanny

src/docx/opc/package.py

@@ -1,13 +1,20 @@
 """Objects that implement reading and writing OPC packages."""
 
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, Iterator
+
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.opc.packuri import PACKAGE_URI, PackURI
 from docx.opc.part import PartFactory
 from docx.opc.parts.coreprops import CorePropertiesPart
 from docx.opc.pkgreader import PackageReader
 from docx.opc.pkgwriter import PackageWriter
 from docx.opc.rel import Relationships
-from docx.opc.shared import lazyproperty
+from docx.shared import lazyproperty
+
+if TYPE_CHECKING:
+    from docx.opc.part import Part
 
 
 class OpcPackage:
@@ -56,7 +63,7 @@ def walk_rels(source, visited=None):
         for rel in walk_rels(self):
             yield rel
 
-    def iter_parts(self):
+    def iter_parts(self) -> Iterator[Part]:
         """Generate exactly one reference to each of the parts in the package by
         performing a depth-first traversal of the rels graph."""
 
@@ -76,7 +83,7 @@ def walk_parts(source, visited=[]):
         for part in walk_parts(self):
             yield part
 
-    def load_rel(self, reltype, target, rId, is_external=False):
+    def load_rel(self, reltype: str, target: Part | str, rId: str, is_external: bool = False):
         """Return newly added |_Relationship| instance of `reltype` between this part
         and `target` with key `rId`.
 
@@ -111,14 +118,14 @@ def next_partname(self, template):
                 return PackURI(candidate_partname)
 
     @classmethod
-    def open(cls, pkg_file):
+    def open(cls, pkg_file: str | IO[bytes]) -> OpcPackage:
         """Return an |OpcPackage| instance loaded with the contents of `pkg_file`."""
         pkg_reader = PackageReader.from_file(pkg_file)
         package = cls()
         Unmarshaller.unmarshal(pkg_reader, package, PartFactory)
         return package
 
-    def part_related_by(self, reltype):
+    def part_related_by(self, reltype: str) -> Part:
         """Return part to which this package has a relationship of `reltype`.
 
         Raises |KeyError| if no such relationship is found and |ValueError| if more than
@@ -127,13 +134,16 @@ def part_related_by(self, reltype):
         return self.rels.part_with_reltype(reltype)
 
     @property
-    def parts(self):
+    def parts(self) -> list[Part]:
         """Return a list containing a reference to each of the parts in this package."""
         return list(self.iter_parts())
 
-    def relate_to(self, part, reltype):
-        """Return rId key of relationship to `part`, from the existing relationship if
-        there is one, otherwise a newly created one."""
+    def relate_to(self, part: Part, reltype: str):
+        """Return rId key of new or existing relationship to `part`.
+
+        If a relationship of `reltype` to `part` already exists, its rId is returned. Otherwise a
+        new relationship is created and that rId is returned.
+        """
         rel = self.rels.get_or_add(reltype, part)
         return rel.rId
 
@@ -143,9 +153,11 @@ def rels(self):
         relationships for this package."""
         return Relationships(PACKAGE_URI.baseURI)
 
-    def save(self, pkg_file):
-        """Save this package to `pkg_file`, where `file` can be either a path to a file
-        (a string) or a file-like object."""
+    def save(self, pkg_file: str | IO[bytes]):
+        """Save this package to `pkg_file`.
+
+        `pkg_file` can be either a file-path or a file-like object.
+        """
         for part in self.parts:
             part.before_marshal()
         PackageWriter.write(pkg_file, self.rels, self.parts)
@@ -190,9 +202,7 @@ def _unmarshal_parts(pkg_reader, package, part_factory):
         """
         parts = {}
         for partname, content_type, reltype, blob in pkg_reader.iter_sparts():
-            parts[partname] = part_factory(
-                partname, content_type, reltype, blob, package
-            )
+            parts[partname] = part_factory(partname, content_type, reltype, blob, package)
         return parts
 
     @staticmethod
@@ -202,7 +212,5 @@ def _unmarshal_relationships(pkg_reader, package, parts):
         in `parts`."""
         for source_uri, srel in pkg_reader.iter_srels():
             source = package if source_uri == "/" else parts[source_uri]
-            target = (
-                srel.target_ref if srel.is_external else parts[srel.target_partname]
-            )
+            target = srel.target_ref if srel.is_external else parts[srel.target_partname]
             source.load_rel(srel.reltype, target, srel.rId, srel.is_external)

src/docx/opc/part.py

@@ -7,8 +7,9 @@
 from docx.opc.oxml import serialize_part_xml
 from docx.opc.packuri import PackURI
 from docx.opc.rel import Relationships
-from docx.opc.shared import cls_method_fn, lazyproperty
+from docx.opc.shared import cls_method_fn
 from docx.oxml.parser import parse_xml
+from docx.shared import lazyproperty
 
 if TYPE_CHECKING:
     from docx.package import Package
@@ -81,9 +82,10 @@ def drop_rel(self, rId: str):
     def load(cls, partname: str, content_type: str, blob: bytes, package: Package):
         return cls(partname, content_type, blob, package)
 
-    def load_rel(self, reltype, target, rId, is_external=False):
-        """Return newly added |_Relationship| instance of `reltype` between this part
-        and `target` with key `rId`.
+    def load_rel(self, reltype: str, target: Part | str, rId: str, is_external: bool = False):
+        """Return newly added |_Relationship| instance of `reltype`.
+
+        The new relationship relates the `target` part to this part with key `rId`.
 
         Target mode is set to ``RTM.EXTERNAL`` if `is_external` is |True|. Intended for
         use during load from a serialized package, where the rId is well-known. Other
@@ -118,7 +120,7 @@ def part_related_by(self, reltype: str) -> Part:
         """
         return self.rels.part_with_reltype(reltype)
 
-    def relate_to(self, target: Part, reltype: str, is_external: bool = False) -> str:
+    def relate_to(self, target: Part | str, reltype: str, is_external: bool = False) -> str:
         """Return rId key of relationship of `reltype` to `target`.
 
         The returned `rId` is from an existing relationship if there is one, otherwise a
@@ -142,7 +144,7 @@ def rels(self):
         """|Relationships| instance holding the relationships for this part."""
         return Relationships(self._partname.baseURI)
 
-    def target_ref(self, rId):
+    def target_ref(self, rId: str) -> str:
         """Return URL contained in target ref of relationship identified by `rId`."""
         rel = self.rels[rId]
         return rel.target_ref

src/docx/opc/pkgwriter.py

@@ -4,13 +4,20 @@
 OpcPackage.save().
 """
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterable
+
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.opc.oxml import CT_Types, serialize_part_xml
 from docx.opc.packuri import CONTENT_TYPES_URI, PACKAGE_URI
 from docx.opc.phys_pkg import PhysPkgWriter
 from docx.opc.shared import CaseInsensitiveDict
 from docx.opc.spec import default_content_types
 
+if TYPE_CHECKING:
+    from docx.opc.part import Part
+
 
 class PackageWriter:
     """Writes a zip-format OPC package to `pkg_file`, where `pkg_file` can be either a
@@ -38,13 +45,13 @@ def _write_content_types_stream(phys_writer, parts):
         phys_writer.write(CONTENT_TYPES_URI, cti.blob)
 
     @staticmethod
-    def _write_parts(phys_writer, parts):
+    def _write_parts(phys_writer: PhysPkgWriter, parts: Iterable[Part]):
         """Write the blob of each part in `parts` to the package, along with a rels item
         for its relationships if and only if it has any."""
         for part in parts:
             phys_writer.write(part.partname, part.blob)
-            if len(part._rels):
-                phys_writer.write(part.partname.rels_uri, part._rels.xml)
+            if len(part.rels):
+                phys_writer.write(part.partname.rels_uri, part.rels.xml)
 
     @staticmethod
     def _write_pkg_rels(phys_writer, pkg_rels):

src/docx/opc/rel.py

@@ -2,10 +2,13 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict
+from typing import TYPE_CHECKING, Any, Dict
 
 from docx.opc.oxml import CT_Relationships
 
+if TYPE_CHECKING:
+    from docx.opc.part import Part
+
 
 class Relationships(Dict[str, "_Relationship"]):
     """Collection object for |_Relationship| instances, having list semantics."""
@@ -16,7 +19,7 @@ def __init__(self, baseURI: str):
         self._target_parts_by_rId: Dict[str, Any] = {}
 
     def add_relationship(
-        self, reltype: str, target: str | Any, rId: str, is_external: bool = False
+        self, reltype: str, target: Part | str, rId: str, is_external: bool = False
     ) -> "_Relationship":
         """Return a newly added |_Relationship| instance."""
         rel = _Relationship(rId, reltype, target, self._baseURI, is_external)
@@ -25,7 +28,7 @@ def add_relationship(
             self._target_parts_by_rId[rId] = target
         return rel
 
-    def get_or_add(self, reltype, target_part):
+    def get_or_add(self, reltype: str, target_part: Part) -> _Relationship:
         """Return relationship of `reltype` to `target_part`, newly added if not already
         present in collection."""
         rel = self._get_matching(reltype, target_part)
@@ -64,7 +67,9 @@ def xml(self):
             rels_elm.add_rel(rel.rId, rel.reltype, rel.target_ref, rel.is_external)
         return rels_elm.xml
 
-    def _get_matching(self, reltype, target, is_external=False):
+    def _get_matching(
+        self, reltype: str, target: Part | str, is_external: bool = False
+    ) -> _Relationship | None:
         """Return relationship of matching `reltype`, `target`, and `is_external` from
         collection, or None if not found."""
 
@@ -99,7 +104,7 @@ def _get_rel_of_type(self, reltype):
         return matching[0]
 
     @property
-    def _next_rId(self):
+    def _next_rId(self) -> str:
         """Next available rId in collection, starting from 'rId1' and making use of any
         gaps in numbering, e.g. 'rId2' for rIds ['rId1', 'rId3']."""
         for n in range(1, len(self) + 2):
@@ -135,8 +140,7 @@ def rId(self):
     def target_part(self):
         if self._is_external:
             raise ValueError(
-                "target_part property on _Relationship is undef"
-                "ined when target mode is External"
+                "target_part property on _Relationship is undef" "ined when target mode is External"
             )
         return self._target
 

src/docx/opc/shared.py

@@ -1,7 +1,13 @@
 """Objects shared by opc modules."""
 
+from __future__ import annotations
 
-class CaseInsensitiveDict(dict):
+from typing import Any, Dict, TypeVar
+
+_T = TypeVar("_T")
+
+
+class CaseInsensitiveDict(Dict[str, Any]):
     """Mapping type that behaves like dict except that it matches without respect to the
     case of the key.
 
@@ -23,23 +29,3 @@ def __setitem__(self, key, value):
 def cls_method_fn(cls: type, method_name: str):
     """Return method of `cls` having `method_name`."""
     return getattr(cls, method_name)
-
-
-def lazyproperty(f):
-    """@lazyprop decorator.
-
-    Decorated method will be called only on first access to calculate a cached property
-    value. After that, the cached value is returned.
-    """
-    cache_attr_name = "_%s" % f.__name__  # like '_foobar' for prop 'foobar'
-    docstring = f.__doc__
-
-    def get_prop_value(obj):
-        try:
-            return getattr(obj, cache_attr_name)
-        except AttributeError:
-            value = f(obj)
-            setattr(obj, cache_attr_name, value)
-            return value
-
-    return property(get_prop_value, doc=docstring)