Skip to content

Commit cdff40b

Browse files
committed
fix(foundation): let the pypcap engine fall back when the pcap module cannot load (#2132)
- Add _pcap_backend.engine_reason(): the wrong-backend verdict plus the installed-but-unusable one PCAP_CT already gave. - PyPCAP._reason_for and PCAP_CT._reason_for both return it, so extract(engine='pypcap') now warns and falls back to the default engine instead of raising the loader's OSError, and the two cannot drift again. - Document the new verdict in PyPCAP's docstrings and the engines docs. Tests: tests/foundation/engines/test_pypcap_unusable_module_2132_unit.py, with a fake pcap package raising OSError in a child interpreter; fails on origin/main, passes here, foundation leg green.
1 parent 8fdc2fb commit cdff40b

6 files changed

Lines changed: 255 additions & 20 deletions

File tree

‎docs/source/pcapkit/foundation/engines/3rdparty.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,12 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
207207
not the one in use, and the two have different install requirements and different
208208
version coverage to report.
209209

210+
A |pcap|_ module that is installed but cannot load -- its import raises
211+
:exc:`OSError`, say, because no :manpage:`libpcap(3)` can be found -- is reported
212+
the same way :class:`~pcapkit.foundation.engines.pcap_ct.PCAP_CT` reports it, so the
213+
extraction falls back to the :term:`default engine` with a warning instead of
214+
aborting (:issue:`2132`).
215+
210216
.. important::
211217

212218
`PyPCAP`_ is a :manpage:`libpcap(3)` binding aimed primarily at live capture.
@@ -502,6 +508,8 @@ cycle.
502508

503509
.. autofunction:: pcapkit.foundation.engines._pcap_backend.wrong_backend_reason
504510

511+
.. autofunction:: pcapkit.foundation.engines._pcap_backend.engine_reason
512+
505513
.. autofunction:: pcapkit.foundation.engines._pcap_backend.collision_reason
506514

507515
Internal Definitions

‎docs/source/pcapkit/foundation/engines/index.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,9 @@ actually got, via
235235
name the distribution, version and file actually in use, so a bug report about
236236
"the pypcap engine" says which one ran;
237237
* declines to run on the other one, through ``unsupported_reason()``, with a
238-
message naming the ``engine=`` string that does want it; and
238+
message naming the ``engine=`` string that does want it, and likewise on a
239+
|pcap|_ that is installed but cannot load, falling back to the
240+
:term:`default engine` instead of letting the import error escape; and
239241
* warns with an :class:`~pcapkit.utilities.warnings.EngineWarning` when it finds
240242
both installed, since that state leaves one engine permanently unselectable
241243
and nothing else would explain why.

‎pcapkit/foundation/engines/_pcap_backend.py‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
__all__ = [
3939
'PYPCAP', 'PCAP_CT', 'DISTRIBUTIONS', 'ENGINE_NAMES',
4040
'Probe', 'Memo', 'probe', 'identify', 'installed_distributions',
41-
'wrong_backend_reason', 'collision_reason',
41+
'wrong_backend_reason', 'engine_reason', 'collision_reason',
4242
]
4343

4444
if TYPE_CHECKING:
@@ -308,6 +308,43 @@ def wrong_backend_reason(wanted: 'str', found: 'Probe') -> 'Optional[str]':
308308
f'({found.version or "unknown version"}), not {wanted}{suggestion}')
309309

310310

311+
def engine_reason(wanted: 'str', found: 'Probe') -> 'Optional[str]':
312+
"""Why the engine driving ``wanted`` cannot run on ``found``, if it cannot.
313+
314+
The verdict both engines' ``unsupported_reason()`` give, kept here so that
315+
they cannot drift apart. They did once: only
316+
:class:`~pcapkit.foundation.engines.pcap_ct.PCAP_CT` reported a module that is
317+
installed but cannot load, so ``engine='pypcap'`` raised the loader's
318+
:exc:`OSError` where ``engine='pcap_ct'`` fell back (:issue:`2132`).
319+
320+
Args:
321+
wanted: The distribution the calling engine drives -- :data:`PYPCAP` or
322+
:data:`PCAP_CT`.
323+
found: The result of :func:`probe`.
324+
325+
Returns:
326+
:func:`wrong_backend_reason`'s answer when another distribution owns
327+
|pcap|_; a phrase carrying the import failure when |pcap|_ is installed
328+
but raised something other than :exc:`ImportError` -- ``OSError: Cannot
329+
find libpcap.so library`` with no system :manpage:`libpcap(3)`, say; and
330+
:data:`None` otherwise. An absent module is still :data:`None`, since
331+
:meth:`Extractor.import_test
332+
<pcapkit.foundation.extraction.Extractor.import_test>` reports that.
333+
334+
"""
335+
wrong = wrong_backend_reason(wanted, found)
336+
if wrong is not None:
337+
return wrong
338+
339+
# ``missing`` separates "not installed", which the import test reports
340+
# well, from a failure that would otherwise escape it -- the missing
341+
# ``libpcap.so`` being the case this exists for.
342+
if found.name is None and not found.missing:
343+
return f'the `pcap` module is installed but unusable -- {found.failure}'
344+
345+
return None
346+
347+
311348
def collision_reason(found: 'Probe') -> 'Optional[str]':
312349
"""A description of both distributions being installed at once, if they are.
313350

‎pcapkit/foundation/engines/pcap_ct.py‎

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -166,17 +166,7 @@ def _reason_for(cls, found: '_pcap_backend.Probe') -> 'Optional[str]':
166166
import after a failed one does not reproduce the same error.
167167
168168
"""
169-
wrong = _pcap_backend.wrong_backend_reason(cls.__engine_distribution__, found)
170-
if wrong is not None:
171-
return wrong
172-
173-
# ``missing`` separates "not installed", which the import test reports
174-
# well, from a failure that would otherwise escape it -- the missing
175-
# ``libpcap.so`` being the case this exists for.
176-
if found.name is None and not found.missing:
177-
return f'the `pcap` module is installed but unusable -- {found.failure}'
178-
179-
return None
169+
return _pcap_backend.engine_reason(cls.__engine_distribution__, found)
180170

181171
@classmethod
182172
def unsupported_reason(cls) -> 'Optional[str]':

‎pcapkit/foundation/engines/pypcap.py‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ def _reason_for(cls, found: '_pcap_backend.Probe') -> 'Optional[str]':
130130
import after a failed one does not reproduce the same error.
131131
132132
"""
133-
return _pcap_backend.wrong_backend_reason(cls.__engine_distribution__, found)
133+
return _pcap_backend.engine_reason(cls.__engine_distribution__, found)
134134

135135
@classmethod
136136
def unsupported_reason(cls) -> 'Optional[str]':
@@ -150,6 +150,16 @@ def unsupported_reason(cls) -> 'Optional[str]':
150150
interpreter, and would say nothing useful on 3.10 and 3.11, where both
151151
distributions install happily and either could be the one in place.
152152
153+
It also reports a |pcap|_ that is installed but cannot load -- one whose
154+
import raises something other than :exc:`ImportError`, such as the
155+
:exc:`OSError` a loader raises when it cannot find :manpage:`libpcap(3)`.
156+
:meth:`Extractor.import_test
157+
<pcapkit.foundation.extraction.Extractor.import_test>` lets that through,
158+
so without this the extraction would die rather than fall back to the
159+
:term:`default engine` (:issue:`2132`). The verdict is
160+
:func:`~pcapkit.foundation.engines._pcap_backend.engine_reason`, shared
161+
with :class:`~pcapkit.foundation.engines.pcap_ct.PCAP_CT`.
162+
153163
Returns:
154164
A phrase naming the real cause, or :data:`None`. An absent |pcap|_
155165
returns :data:`None`, since the import test reports that case in its
@@ -195,9 +205,9 @@ def __init__(self, extractor: 'Extractor') -> 'None':
195205
196206
Raises:
197207
UnsupportedCall: If the installed |pcap|_ is `pcap-ct`_ rather
198-
than upstream `PyPCAP`_. This is the same condition
199-
:meth:`unsupported_reason` reports, kept here as well because that
200-
hook is only consulted by
208+
than upstream `PyPCAP`_, or is installed but cannot load. These
209+
are the conditions :meth:`unsupported_reason` reports, kept here as
210+
well because that hook is only consulted by
201211
:meth:`Extractor.run <pcapkit.foundation.extraction.Extractor.run>`;
202212
constructing the engine directly bypasses it, and running
203213
`pcap-ct`_ under the :class:`~pcapkit.foundation.engines.pypcap.PyPCAP` name would
@@ -208,9 +218,8 @@ def __init__(self, extractor: 'Extractor') -> 'None':
208218
"""
209219
# NOTE: the probe comes *before* ``import pcap`` so that this engine and
210220
# :class:`~pcapkit.foundation.engines.pcap_ct.PCAP_CT` behave the same way
211-
# here. It matters more for the latter, whose import can raise
212-
# ``OSError`` rather than ``ImportError``, but a shared order is one fewer
213-
# difference between them.
221+
# here. Either import can raise ``OSError`` rather than ``ImportError``
222+
# (#2132), which the probe turns into a reason instead of a crash.
214223
self._backend = _pcap_backend.probe()
215224

216225
collision = _pcap_backend.collision_reason(self._backend)
Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
"""The pypcap engine falls back when the ``pcap`` module cannot load (#2132).
2+
3+
A ``pcap`` module can be installed and still fail to import with something other
4+
than :exc:`ImportError` -- ``OSError: Cannot find libpcap.so library`` with no
5+
system libpcap, for one. :meth:`Extractor.import_test
6+
<pcapkit.foundation.extraction.Extractor.import_test>` lets that through, so the
7+
engine's ``unsupported_reason()`` has to report it. ``PCAP_CT`` did and ``PyPCAP``
8+
did not, so ``extract(engine='pypcap')`` raised the loader's error where
9+
``engine='pcap_ct'`` warned and fell back. Both now ask
10+
:func:`pcapkit.foundation.engines._pcap_backend.engine_reason`.
11+
12+
"""
13+
from __future__ import annotations
14+
15+
import importlib.util
16+
import json
17+
import os
18+
import pathlib
19+
import subprocess # nosec: B404
20+
import sys
21+
import tempfile
22+
import types
23+
import unittest
24+
from unittest import mock
25+
26+
from tests._support import scale_timeout
27+
from tests._tiers import ROOT
28+
29+
RUNTIME_DEPS = ('tbtrim', 'aenum', 'chardet', 'dictdumper')
30+
HAS_RUNTIME = all(importlib.util.find_spec(name) is not None for name in RUNTIME_DEPS)
31+
32+
#: What the fake ``pcap`` package raises on import: the libpcap loader's message.
33+
LOADER_ERROR = 'Cannot find libpcap.so library'
34+
#: The verdict ``PCAP_CT`` already gave on that failure, which ``PyPCAP`` now shares.
35+
REASON = f'the `pcap` module is installed but unusable -- OSError: {LOADER_ERROR}'
36+
#: Hang guard for the child interpreter, in seconds.
37+
TIMEOUT = 120
38+
39+
#: Child script: run one extraction with the fake ``pcap`` first on the path and
40+
#: report, as JSON, which ``pcapkit`` ran, what was warned and what happened.
41+
CHILD = '''
42+
import json, sys, warnings
43+
engine, capture = sys.argv[1], sys.argv[2]
44+
import pcapkit
45+
from pcapkit.foundation.engines.pcap_ct import PCAP_CT
46+
from pcapkit.foundation.engines.pypcap import PyPCAP
47+
result = {
48+
'pcapkit': pcapkit.__file__,
49+
'pypcap_reason': PyPCAP.unsupported_reason(),
50+
'pcap_ct_reason': PCAP_CT.unsupported_reason(),
51+
}
52+
with warnings.catch_warnings(record=True) as caught:
53+
warnings.simplefilter('always')
54+
try:
55+
extractor = pcapkit.extract(fin=capture, engine=engine, nofile=True)
56+
except BaseException as exc:
57+
result['error'] = f'{type(exc).__name__}: {exc}'
58+
else:
59+
result['engine'] = extractor._exnam
60+
result['frames'] = len(extractor.frame)
61+
result['warnings'] = [f'{w.category.__name__}: {w.message}' for w in caught]
62+
print(json.dumps(result))
63+
'''
64+
65+
66+
@unittest.skipUnless(HAS_RUNTIME, 'runtime dependencies not installed')
67+
class EngineReasonTests(unittest.TestCase):
68+
"""The shared verdict, and both engines giving it."""
69+
70+
def probe(self, **overrides):
71+
from pcapkit.foundation.engines import _pcap_backend
72+
73+
values = dict(name=None, version=None, origin=None,
74+
failure=f'OSError: {LOADER_ERROR}', missing=False, installed=())
75+
values.update(overrides)
76+
return _pcap_backend.Probe(**values)
77+
78+
def test_an_installed_but_unusable_module_is_a_reason_for_either_engine(self) -> None:
79+
from pcapkit.foundation.engines import _pcap_backend
80+
81+
for wanted in _pcap_backend.DISTRIBUTIONS:
82+
with self.subTest(wanted=wanted):
83+
self.assertEqual(_pcap_backend.engine_reason(wanted, self.probe()), REASON)
84+
85+
def test_an_absent_module_is_left_to_the_import_test(self) -> None:
86+
from pcapkit.foundation.engines import _pcap_backend
87+
88+
found = self.probe(failure='no module named `pcap`', missing=True)
89+
self.assertIsNone(_pcap_backend.engine_reason(_pcap_backend.PYPCAP, found))
90+
91+
def test_the_wrong_backend_keeps_its_own_reason(self) -> None:
92+
from pcapkit.foundation.engines import _pcap_backend
93+
94+
found = self.probe(name=_pcap_backend.PCAP_CT, version='1.3.0b3',
95+
origin='/stub/pcap/__init__.py', failure=None)
96+
self.assertEqual(_pcap_backend.engine_reason(_pcap_backend.PYPCAP, found),
97+
_pcap_backend.wrong_backend_reason(_pcap_backend.PYPCAP, found))
98+
99+
def broken_import(self):
100+
from pcapkit.foundation.engines import _pcap_backend
101+
102+
return (mock.patch('importlib.import_module', side_effect=OSError(LOADER_ERROR)),
103+
mock.patch.object(_pcap_backend, 'installed_distributions',
104+
return_value=(_pcap_backend.PYPCAP,)))
105+
106+
def test_pypcap_reports_the_module_that_cannot_load(self) -> None:
107+
from pcapkit.foundation.engines.pcap_ct import PCAP_CT
108+
from pcapkit.foundation.engines.pypcap import PyPCAP
109+
110+
importer, installed = self.broken_import()
111+
with importer, installed:
112+
reason = PyPCAP.unsupported_reason()
113+
peer = PCAP_CT.unsupported_reason()
114+
115+
self.assertEqual(reason, REASON)
116+
self.assertEqual(reason, peer)
117+
118+
def test_pypcap_constructor_refuses_instead_of_raising_the_oserror(self) -> None:
119+
from pcapkit.foundation.engines.pypcap import PyPCAP
120+
from pcapkit.utilities.exceptions import UnsupportedCall
121+
122+
importer, installed = self.broken_import()
123+
with importer, installed:
124+
with self.assertRaises(UnsupportedCall) as caught:
125+
PyPCAP(types.SimpleNamespace()) # type: ignore[arg-type]
126+
127+
self.assertIn(REASON, str(caught.exception))
128+
129+
130+
@unittest.skipUnless(HAS_RUNTIME, 'runtime dependencies not installed')
131+
class FakePcapPackageTests(unittest.TestCase):
132+
"""End to end, with a real ``pcap`` package on :data:`sys.path` that cannot load.
133+
134+
Run in a child interpreter so that the fake package never reaches this
135+
process's :data:`sys.modules` or import caches.
136+
137+
"""
138+
139+
@classmethod
140+
def setUpClass(cls) -> None:
141+
tmp = tempfile.TemporaryDirectory()
142+
cls.addClassCleanup(tmp.cleanup)
143+
package = pathlib.Path(tmp.name) / 'pcap'
144+
package.mkdir()
145+
(package / '__init__.py').write_text(f'raise OSError({LOADER_ERROR!r})\n')
146+
cls.site = tmp.name
147+
148+
def extract(self, engine: str) -> dict:
149+
env = dict(os.environ)
150+
env.pop('PYTHONSAFEPATH', None) # cwd must win, so the tree under test runs
151+
env['PYTHONPATH'] = os.pathsep.join(
152+
filter(None, (self.site, env.get('PYTHONPATH'))))
153+
capture = str(ROOT / 'examples' / 'captures' / 'in.pcap')
154+
completed = subprocess.run( # nosec: B603
155+
[sys.executable, '-c', CHILD, engine, capture],
156+
cwd=str(ROOT), env=env, capture_output=True, text=True,
157+
timeout=scale_timeout(TIMEOUT), check=False,
158+
)
159+
self.assertEqual(completed.returncode, 0, completed.stderr)
160+
result = json.loads(completed.stdout.strip().splitlines()[-1])
161+
loaded = os.path.realpath(result['pcapkit'])
162+
self.assertEqual(os.path.commonpath([loaded, str(ROOT)]), str(ROOT), loaded)
163+
return result
164+
165+
def assert_falls_back(self, engine: str, name: str) -> None:
166+
result = self.extract(engine)
167+
168+
self.assertNotIn('error', result)
169+
self.assertEqual(result['engine'], 'default')
170+
self.assertGreater(result['frames'], 0)
171+
self.assertIn(f'EngineWarning: engine {name} is not supported on this '
172+
f'interpreter ({REASON}); using default engine instead',
173+
result['warnings'])
174+
175+
def test_pcap_ct_falls_back(self) -> None:
176+
self.assert_falls_back('pcap_ct', 'PCAP_CT')
177+
178+
def test_pypcap_falls_back_like_pcap_ct(self) -> None:
179+
self.assert_falls_back('pypcap', 'PyPCAP')
180+
181+
def test_pypcap_unsupported_reason_names_the_loader_error(self) -> None:
182+
result = self.extract('pypcap')
183+
184+
self.assertEqual(result['pypcap_reason'], REASON)
185+
self.assertEqual(result['pypcap_reason'], result['pcap_ct_reason'])
186+
187+
188+
if __name__ == '__main__':
189+
unittest.main()

0 commit comments

Comments
 (0)