diff --git a/docs/source/contributing/conventions/const-vendor-pairing.rst b/docs/source/contributing/conventions/const-vendor-pairing.rst index 677e0f309e..f9d6160d40 100644 --- a/docs/source/contributing/conventions/const-vendor-pairing.rst +++ b/docs/source/contributing/conventions/const-vendor-pairing.rst @@ -99,7 +99,7 @@ Lazy Package Imports itself. Ruled by the owner in session and recorded on :issue:`2729`. Its :file:`__init__.py` names each export in an import under ``if TYPE_CHECKING:``, for the type checkers, and binds the ``__getattr__`` and ``__dir__`` that -:func:`~pcapkit.utilities.lazy.lazy_exports` returns; :mod:`pcapkit.const` re-exports +:func:`~pcapkit.utilities.importlib.lazy_exports` returns; :mod:`pcapkit.const` re-exports its subpackages' ``__all__`` the same way. The one real import is of :class:`~pcapkit.const.reg.apptype.apptype.AppType` and :class:`~pcapkit.const.reg.apptype.apptype.TransportProtocol`, which diff --git a/docs/source/pcapkit/utilities/lazy.rst b/docs/source/pcapkit/utilities/importlib.rst similarity index 69% rename from docs/source/pcapkit/utilities/lazy.rst rename to docs/source/pcapkit/utilities/importlib.rst index 9d88815078..cfc1446245 100644 --- a/docs/source/pcapkit/utilities/lazy.rst +++ b/docs/source/pcapkit/utilities/importlib.rst @@ -1,9 +1,9 @@ Lazy Imports ============ -.. module:: pcapkit.utilities.lazy +.. module:: pcapkit.utilities.importlib -:mod:`pcapkit.utilities.lazy` holds :func:`lazy_exports`, which gives a package the +:mod:`pcapkit.utilities.importlib` holds :func:`lazy_exports`, which gives a package the :pep:`562` ``__getattr__`` and ``__dir__`` that import each name it exports the first time the name is reached, rather than with the package itself. Every package under :mod:`pcapkit.const` imports its enumerations that way (:issue:`2729`), so a caller @@ -12,4 +12,4 @@ pays only for the enumerations it uses. This module imports nothing from .. versionadded:: 1.6.0 -.. autofunction:: pcapkit.utilities.lazy.lazy_exports +.. autofunction:: pcapkit.utilities.importlib.lazy_exports diff --git a/docs/source/pcapkit/utilities/index.rst b/docs/source/pcapkit/utilities/index.rst index 1589b74b65..589c18089a 100644 --- a/docs/source/pcapkit/utilities/index.rst +++ b/docs/source/pcapkit/utilities/index.rst @@ -9,7 +9,7 @@ built with: user-refined exceptions and warnings, logging, the tunable limits of :mod:`~pcapkit.utilities.config`, a compatibility layer, timestamp conversion, pickle reductions, the :mod:`context variables ` its modules share, -:mod:`lazy imports ` for a package's exports, and +:mod:`lazy imports ` for a package's exports, and wrappers around third-party libraries. It imports nothing from :mod:`pcapkit` outside itself; see :ref:`utilities-or-corekit`. @@ -24,7 +24,7 @@ outside itself; see :ref:`utilities-or-corekit`. datetime pickle contextvars - lazy + importlib Version Compatibility ===================== diff --git a/pcapkit/const/__init__.py b/pcapkit/const/__init__.py index 3010ce5149..a9162b91c3 100644 --- a/pcapkit/const/__init__.py +++ b/pcapkit/const/__init__.py @@ -8,14 +8,14 @@ Each enumeration is imported the first time it is reached -- as an attribute of this package or of the subpackage holding it -- rather than with the -package, through :func:`~pcapkit.utilities.lazy.lazy_exports` +package, through :func:`~pcapkit.utilities.importlib.lazy_exports` (:issue:`2729`). The subpackages themselves are imported with it, and import none of their enumerations. """ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: # IANA registration diff --git a/pcapkit/const/arp/__init__.py b/pcapkit/const/arp/__init__.py index 76dfdab977..37e1d1786e 100644 --- a/pcapkit/const/arp/__init__.py +++ b/pcapkit/const/arp/__init__.py @@ -21,7 +21,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.arp.hardware import Hardware as ARP_Hardware diff --git a/pcapkit/const/dccp/__init__.py b/pcapkit/const/dccp/__init__.py index f7d8db5d41..4fbdf54d3f 100644 --- a/pcapkit/const/dccp/__init__.py +++ b/pcapkit/const/dccp/__init__.py @@ -35,7 +35,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.dccp.ack_vector_state import AckVectorState as DCCP_AckVectorState diff --git a/pcapkit/const/esp/__init__.py b/pcapkit/const/esp/__init__.py index b1f9d281df..aaa00714ff 100644 --- a/pcapkit/const/esp/__init__.py +++ b/pcapkit/const/esp/__init__.py @@ -35,7 +35,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.esp.cipher import Cipher as ESP_Cipher diff --git a/pcapkit/const/ftp/__init__.py b/pcapkit/const/ftp/__init__.py index c7384b7e93..1b2ebf51d0 100644 --- a/pcapkit/const/ftp/__init__.py +++ b/pcapkit/const/ftp/__init__.py @@ -21,7 +21,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.ftp.command import Command as FTP_Command diff --git a/pcapkit/const/hip/__init__.py b/pcapkit/const/hip/__init__.py index 33b77ae313..af7aee897e 100644 --- a/pcapkit/const/hip/__init__.py +++ b/pcapkit/const/hip/__init__.py @@ -71,7 +71,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.hip.certificate import Certificate as HIP_Certificate diff --git a/pcapkit/const/http/__init__.py b/pcapkit/const/http/__init__.py index f52a9b28ca..a322844341 100644 --- a/pcapkit/const/http/__init__.py +++ b/pcapkit/const/http/__init__.py @@ -32,7 +32,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.http.error_code import ErrorCode as HTTP_ErrorCode diff --git a/pcapkit/const/icmp/__init__.py b/pcapkit/const/icmp/__init__.py index 4f5b2ff174..a9390e1477 100644 --- a/pcapkit/const/icmp/__init__.py +++ b/pcapkit/const/icmp/__init__.py @@ -29,7 +29,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.icmp.destination_unreachable_code import \ diff --git a/pcapkit/const/icmpv6/__init__.py b/pcapkit/const/icmpv6/__init__.py index 1bcbd0651e..e4329de5e4 100644 --- a/pcapkit/const/icmpv6/__init__.py +++ b/pcapkit/const/icmpv6/__init__.py @@ -29,7 +29,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.icmpv6.destination_unreachable_code import \ diff --git a/pcapkit/const/ieee802_11/__init__.py b/pcapkit/const/ieee802_11/__init__.py index db34d0e7f4..d16ab37724 100644 --- a/pcapkit/const/ieee802_11/__init__.py +++ b/pcapkit/const/ieee802_11/__init__.py @@ -27,7 +27,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.ieee802_11.control_subtype import ControlSubtype as IEEE802_11_ControlSubtype diff --git a/pcapkit/const/igmp/__init__.py b/pcapkit/const/igmp/__init__.py index e5059ad54a..da35931d80 100644 --- a/pcapkit/const/igmp/__init__.py +++ b/pcapkit/const/igmp/__init__.py @@ -23,7 +23,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.igmp.record_type import RecordType as IGMP_RecordType diff --git a/pcapkit/const/ipv4/__init__.py b/pcapkit/const/ipv4/__init__.py index c87560419c..98c4a76a1c 100644 --- a/pcapkit/const/ipv4/__init__.py +++ b/pcapkit/const/ipv4/__init__.py @@ -41,7 +41,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.ipv4.classification_level import \ diff --git a/pcapkit/const/ipv6/__init__.py b/pcapkit/const/ipv6/__init__.py index d5f75a0fff..c5d0ba147b 100644 --- a/pcapkit/const/ipv6/__init__.py +++ b/pcapkit/const/ipv6/__init__.py @@ -41,7 +41,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.ipv6.extension_header import ExtensionHeader as IPv6_ExtensionHeader diff --git a/pcapkit/const/ipx/__init__.py b/pcapkit/const/ipx/__init__.py index 3d77fee9dc..16d436e83e 100644 --- a/pcapkit/const/ipx/__init__.py +++ b/pcapkit/const/ipx/__init__.py @@ -23,7 +23,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.ipx.packet import Packet as IPX_Packet diff --git a/pcapkit/const/l2tp/__init__.py b/pcapkit/const/l2tp/__init__.py index dac025f72e..e94bc726b0 100644 --- a/pcapkit/const/l2tp/__init__.py +++ b/pcapkit/const/l2tp/__init__.py @@ -18,7 +18,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.l2tp.type import Type as L2TP_Type diff --git a/pcapkit/const/linux/__init__.py b/pcapkit/const/linux/__init__.py index 8741702dd6..625a5cfb45 100644 --- a/pcapkit/const/linux/__init__.py +++ b/pcapkit/const/linux/__init__.py @@ -16,7 +16,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.linux.arphrd import ARPHRD as Linux_ARPHRD diff --git a/pcapkit/const/mh/__init__.py b/pcapkit/const/mh/__init__.py index 11a36b5232..ad75a4d111 100644 --- a/pcapkit/const/mh/__init__.py +++ b/pcapkit/const/mh/__init__.py @@ -143,7 +143,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.mh.access_type import AccessType as MH_AccessType diff --git a/pcapkit/const/ngap/__init__.py b/pcapkit/const/ngap/__init__.py index 7d2c089364..c5466d8215 100644 --- a/pcapkit/const/ngap/__init__.py +++ b/pcapkit/const/ngap/__init__.py @@ -30,7 +30,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.ngap.procedure_code import ProcedureCode as NGAP_ProcedureCode diff --git a/pcapkit/const/ospf/__init__.py b/pcapkit/const/ospf/__init__.py index 8553f78af3..7de969cd73 100644 --- a/pcapkit/const/ospf/__init__.py +++ b/pcapkit/const/ospf/__init__.py @@ -23,7 +23,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.ospf.authentication import Authentication as OSPF_Authentication diff --git a/pcapkit/const/pcapng/__init__.py b/pcapkit/const/pcapng/__init__.py index 4620b333cc..08d903c59a 100644 --- a/pcapkit/const/pcapng/__init__.py +++ b/pcapkit/const/pcapng/__init__.py @@ -41,7 +41,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.pcapng.block_type import BlockType as PCAPNG_BlockType diff --git a/pcapkit/const/radiotap/__init__.py b/pcapkit/const/radiotap/__init__.py index 4e9c4465ce..e2b24a4722 100644 --- a/pcapkit/const/radiotap/__init__.py +++ b/pcapkit/const/radiotap/__init__.py @@ -56,7 +56,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.radiotap.ampdu_flags import AMPDUFlags as Radiotap_AMPDUFlags diff --git a/pcapkit/const/reg/__init__.py b/pcapkit/const/reg/__init__.py index 82342d05a7..38334bde0f 100644 --- a/pcapkit/const/reg/__init__.py +++ b/pcapkit/const/reg/__init__.py @@ -36,7 +36,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.reg.apptype import AppType as APPTYPE diff --git a/pcapkit/const/reg/apptype/__init__.py b/pcapkit/const/reg/apptype/__init__.py index 46ae2b1434..69af9f1d95 100644 --- a/pcapkit/const/reg/apptype/__init__.py +++ b/pcapkit/const/reg/apptype/__init__.py @@ -50,7 +50,7 @@ from pcapkit.const.reg.apptype.apptype import AppType, TransportProtocol from pcapkit.corekit.infoclass import Info, info_final from pcapkit.corekit.module import ModuleDescriptor -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from typing import Any, ItemsView, Iterable, Iterator, Mapping, Optional, SupportsIndex, Type diff --git a/pcapkit/const/sctp/__init__.py b/pcapkit/const/sctp/__init__.py index 23ce0c4b81..5e6d310471 100644 --- a/pcapkit/const/sctp/__init__.py +++ b/pcapkit/const/sctp/__init__.py @@ -29,7 +29,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.sctp.cause_code import CauseCode as SCTP_CauseCode diff --git a/pcapkit/const/sslv2/__init__.py b/pcapkit/const/sslv2/__init__.py index e272210ead..1fb6b97098 100644 --- a/pcapkit/const/sslv2/__init__.py +++ b/pcapkit/const/sslv2/__init__.py @@ -23,7 +23,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.sslv2.handshake_type import HandshakeType as SSLv2_HandshakeType diff --git a/pcapkit/const/tcp/__init__.py b/pcapkit/const/tcp/__init__.py index 23ee5d91bf..e4a15ed045 100644 --- a/pcapkit/const/tcp/__init__.py +++ b/pcapkit/const/tcp/__init__.py @@ -29,7 +29,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.tcp.checksum import Checksum as TCP_Checksum diff --git a/pcapkit/const/tls/__init__.py b/pcapkit/const/tls/__init__.py index a6d30e809e..3cd939f778 100644 --- a/pcapkit/const/tls/__init__.py +++ b/pcapkit/const/tls/__init__.py @@ -28,7 +28,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.tls.content_type import ContentType as TLS_ContentType diff --git a/pcapkit/const/vlan/__init__.py b/pcapkit/const/vlan/__init__.py index 74917a0ead..162e868fd4 100644 --- a/pcapkit/const/vlan/__init__.py +++ b/pcapkit/const/vlan/__init__.py @@ -20,7 +20,7 @@ from typing import TYPE_CHECKING -from pcapkit.utilities.lazy import lazy_exports +from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from pcapkit.const.vlan.priority_level import PriorityLevel as VLAN_PriorityLevel diff --git a/pcapkit/utilities/lazy.py b/pcapkit/utilities/importlib.py similarity index 97% rename from pcapkit/utilities/lazy.py rename to pcapkit/utilities/importlib.py index d758b527d5..974a0794fa 100644 --- a/pcapkit/utilities/lazy.py +++ b/pcapkit/utilities/importlib.py @@ -2,9 +2,9 @@ """Lazy Imports ================== -.. module:: pcapkit.utilities.lazy +.. module:: pcapkit.utilities.importlib -:mod:`pcapkit.utilities.lazy` holds :func:`lazy_exports`, which gives a package +:mod:`pcapkit.utilities.importlib` holds :func:`lazy_exports`, which gives a package the :pep:`562` ``__getattr__`` and ``__dir__`` that import each name it exports the first time the name is reached, rather than with the package itself. Every package under :mod:`pcapkit.const` imports its enumerations that way diff --git a/tests/const/test_const_apptype_lazy_1538_unit.py b/tests/const/test_const_apptype_lazy_1538_unit.py index 7beb4e82a6..8472086b10 100644 --- a/tests/const/test_const_apptype_lazy_1538_unit.py +++ b/tests/const/test_const_apptype_lazy_1538_unit.py @@ -10,7 +10,7 @@ :attr:`AppType.__registries__ ` the first time either is read. GitHub issue #2729 extended that to SCTP and DCCP, and to every package under :mod:`pcapkit.const`, through -:func:`pcapkit.utilities.lazy.lazy_exports`; #2726 made the registries an +:func:`pcapkit.utilities.importlib.lazy_exports`; #2726 made the registries an :class:`~pcapkit.corekit.infoclass.Info` rather than a :obj:`dict` subclass. The subprocess checks run in a fresh interpreter, since the question is what a diff --git a/tests/const/test_const_lazy_exports_2729_unit.py b/tests/const/test_const_lazy_exports_2729_unit.py index beacb593d5..083f688373 100644 --- a/tests/const/test_const_lazy_exports_2729_unit.py +++ b/tests/const/test_const_lazy_exports_2729_unit.py @@ -2,7 +2,7 @@ """Every :mod:`pcapkit.const` package exports what it did eagerly (GitHub issue #2729). Each package under :mod:`pcapkit.const` imports its enumerations on first use, -through :func:`pcapkit.utilities.lazy.lazy_exports`, and names them only under +through :func:`pcapkit.utilities.importlib.lazy_exports`, and names them only under :data:`~typing.TYPE_CHECKING`, for the type checkers. These sweeps read the packages off the tree, so a package the crawlers add is held to them the day it lands, and hold every one to the eager behaviour that statement describes: diff --git a/tests/utilities/test_lazy_exports_2729_unit.py b/tests/utilities/test_lazy_exports_2729_unit.py index 6392673cc1..8dab1e8598 100644 --- a/tests/utilities/test_lazy_exports_2729_unit.py +++ b/tests/utilities/test_lazy_exports_2729_unit.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -""":func:`pcapkit.utilities.lazy.lazy_exports`, on packages written for the test (GitHub issue #2729). +""":func:`pcapkit.utilities.importlib.lazy_exports`, on packages written for the test (GitHub issue #2729). Every :mod:`pcapkit.const` package uses it, and :mod:`tests.const.test_const_lazy_exports_2729_unit` sweeps those. Here it runs @@ -32,7 +32,7 @@ #: subpackages', and records each module the tree imports in ``imported``. TREE = { '__init__.py': ''' - from pcapkit.utilities.lazy import lazy_exports + from pcapkit.utilities.importlib import lazy_exports imported = [] @@ -43,7 +43,7 @@ 'probe/__init__.py': ''' from typing import TYPE_CHECKING - from pcapkit.utilities.lazy import lazy_exports + from pcapkit.utilities.importlib import lazy_exports if TYPE_CHECKING: from {NAME}.probe.sub import Deep @@ -76,7 +76,7 @@ class Renamed: VALUE = 1 ''', 'probe/sub/__init__.py': ''' - from pcapkit.utilities.lazy import lazy_exports + from pcapkit.utilities.importlib import lazy_exports __all__ = ['Deep']