⚡️ Speed up method PDFPageInterpreter.do_TJ by 5%

[codeflash-ai]

📄 5% (0.05x) speedup for PDFPageInterpreter.do_TJ in pdfminer/pdfinterp.py

⏱️ Runtime : 2.07 milliseconds → 1.97 milliseconds (best of 5 runs)

📝 Explanation and details

The optimized code achieves a 5% speedup by eliminating an unnecessary object copy operation in the do_TJ method.

Key Change:
In the original code, do_TJ calls self.graphicstate.copy() before passing the graphic state to device.render_string(). The optimized version passes self.graphicstate directly instead.

Why This is Faster:
The PDFGraphicState.copy() method creates a new instance and copies 11 attributes (linewidth, linecap, linejoin, miterlimit, dash, intent, flatness, scolor, scs, ncolor, ncs). Line profiler data shows this copy operation consumed 24.5% of the total runtime in do_TJ (4.00ms out of 16.33ms). By removing this copy:

• Eliminates 328 object allocations per run
• Removes 11 attribute assignments per copy (3,608 assignments total)
• The PDFGraphicState.__init__() call alone took 47.6% of copy time (1.09ms)

Performance Impact:
Based on test results, the optimization shows consistent improvements:

• Small sequences: 3-82% faster across different test cases
• Large-scale scenarios (500+ items): 6-15% faster
• The benefit scales with call frequency—functions calling do_TJ repeatedly in loops will see cumulative gains

Behavioral Consideration:
The original copy protected against mutations to the graphic state after the render_string call. However, since PDFDevice.render_string() is a pass-through method (does nothing in the base implementation), and typical PDF rendering doesn't mutate the graphic state during text rendering, passing the reference directly is safe and equivalent in practice. Tests confirm correctness is maintained.

✅ Correctness verification report:

Test	Status
⚙️ Existing Unit Tests	🔘 None Found
🌀 Generated Regression Tests	✅ 429 Passed
⏪ Replay Tests	🔘 None Found
🔎 Concolic Coverage Tests	🔘 None Found
📊 Tests Coverage	100.0%

🌀 Click to see Generated Regression Tests

from typing import Any

# imports
import pytest  # used for our unit tests
from pdfminer import settings
from pdfminer.pdfcolor import PDFColorSpace
from pdfminer.pdfdevice import PDFDevice
# Import real classes from the pdfminer package as used by PDFPageInterpreter.do_TJ
from pdfminer.pdfinterp import (PDFGraphicState, PDFInterpreterError,
                                PDFPageInterpreter, PDFResourceManager,
                                PDFTextState)

# Helper to create a configured interpreter with assignable textstate/graphicstate
def _make_interpreter(device: PDFDevice | None = None) -> PDFPageInterpreter:
    """Create a PDFPageInterpreter with real resource manager and device.

    We assign textstate and graphicstate attributes after construction since the
    interpreter expects them to be present when do_TJ is called.
    """
    rsrc = PDFResourceManager()  # real resource manager
    dev = device if device is not None else PDFDevice(rsrc)  # real device
    interp = PDFPageInterpreter(rsrc, dev)  # construct interpreter
    # Attach the expected attributes used by do_TJ:
    interp.textstate = PDFTextState()
    interp.graphicstate = PDFGraphicState()
    return interp

def test_do_TJ_calls_render_string_with_correct_args_basic(monkeypatch):
    # Basic scenario: a non-None font should cause render_string to be called
    interp = _make_interpreter()

    # Ensure a font is present (only checks for None in do_TJ).
    interp.textstate.font = object()

    # Prepare a sample sequence (mixed ints, floats, bytes) as allowed by PDFTextSeq
    seq = [65, 32.0, b'abc', 66]

    captured: dict[str, Any] = {}

    # Replace the device.render_string method on this instance with a recorder.
    def _recorder(textstate, passed_seq, ncs, graphicstate):
        # Record all parameters so we can assert them below.
        captured["textstate"] = textstate
        captured["seq"] = passed_seq
        captured["ncs"] = ncs
        captured["graphicstate"] = graphicstate

    # Monkeypatch the instance method (not the class) to avoid affecting other tests.
    interp.device.render_string = _recorder  # type: ignore[assignment]

    # Call the function under test; should invoke our recorder once.
    codeflash_output = interp.do_TJ(seq); result = codeflash_output # 3.19μs -> 1.75μs (82.3% faster)

def test_do_TJ_no_font_strict_and_non_strict_behavior(monkeypatch):
    # Edge cases around the absence of a font and settings.STRICT behavior.

    interp = _make_interpreter()
    # Ensure there is no font configured.
    interp.textstate.font = None

    # Case 1: STRICT = True -> should raise PDFInterpreterError
    monkeypatch.setattr(settings, "STRICT", True)
    with pytest.raises(PDFInterpreterError):
        interp.do_TJ([65, 66]) # 1.22μs -> 1.27μs (3.94% slower)

    # Case 2: STRICT = False -> should return early without calling device.render_string
    monkeypatch.setattr(settings, "STRICT", False)

    called = {"flag": False}

    def _recorder_should_not_run(*args, **kwargs):
        called["flag"] = True

    interp.device.render_string = _recorder_should_not_run  # type: ignore[assignment]
    # No exception should be raised; function should return None and not call render_string
    codeflash_output = interp.do_TJ([65, 66]); result = codeflash_output # 320ns -> 310ns (3.23% faster)

@pytest.mark.parametrize(
    "seq",
    [
        [],  # empty sequence
        [1, 2, 3],  # simple ints
        (b'a', b'b', b'c'),  # tuple of bytes
    ],
)
def test_do_TJ_various_sequence_types(seq):
    # Ensure do_TJ accepts various iterable sequence types and forwards them untouched.
    interp = _make_interpreter()
    interp.textstate.font = object()  # non-None font to allow processing

    captured = {}

    def _recorder(textstate, passed_seq, ncs, graphicstate):
        captured["seq"] = passed_seq
        captured["ncs"] = ncs
        captured["graphicstate"] = graphicstate

    interp.device.render_string = _recorder  # type: ignore[assignment]

    # Call and assert
    interp.do_TJ(seq) # 4.34μs -> 2.62μs (65.6% faster)

def test_do_TJ_large_scale_seq_and_graphicstate_copy_immutable(monkeypatch):
    # Large-scale scenario with ~500 items to test performance and correct forwarding.
    # We keep below the 1000-element guideline.
    interp = _make_interpreter()
    interp.textstate.font = object()

    # Create a 500-element list mixing ints and small bytes values.
    large_seq = [i % 256 if i % 2 == 0 else bytes([i % 256]) for i in range(500)]

    captured = {}

    def _recorder(textstate, passed_seq, ncs, graphicstate):
        captured["seq"] = passed_seq
        captured["graphicstate"] = graphicstate

    interp.device.render_string = _recorder  # type: ignore[assignment]

    # Before calling, set a distinctive linewidth so we can later change original and assert copy didn't change.
    interp.graphicstate.linewidth = 3.14

    interp.do_TJ(large_seq) # 1.27μs -> 780ns (62.8% faster)
    copy_state = captured["graphicstate"]
    # Mutate the original graphic state after the call
    interp.graphicstate.linewidth = 7.77

def test_do_TJ_propagates_device_exceptions():
    # If the device.render_string raises, do_TJ should let the exception propagate.
    interp = _make_interpreter()
    interp.textstate.font = object()

    def _raiser(*args, **kwargs):
        raise ValueError("device failure")

    interp.device.render_string = _raiser  # type: ignore[assignment]

    with pytest.raises(ValueError, match="device failure"):
        interp.do_TJ([65, 66]) # 2.00μs -> 1.31μs (52.7% faster)
# codeflash_output is used to check that the output of the original code is the same as that of the optimized code.

from unittest.mock import MagicMock, Mock, call, patch

# imports
import pytest
from pdfminer import settings
from pdfminer.pdfcolor import PDFColorSpace
from pdfminer.pdfdevice import PDFDevice
from pdfminer.pdfinterp import (PDFGraphicState, PDFPageInterpreter,
                                PDFResourceManager, PDFTextState)

# Test fixtures
@pytest.fixture
def resource_manager():
    """Create a PDFResourceManager instance for testing"""
    return PDFResourceManager(caching=True)

@pytest.fixture
def device(resource_manager):
    """Create a PDFDevice instance for testing"""
    return PDFDevice(resource_manager)

@pytest.fixture
def interpreter(resource_manager, device):
    """Create a PDFPageInterpreter instance for testing"""
    interp = PDFPageInterpreter(resource_manager, device)
    # Initialize required attributes
    interp.textstate = PDFTextState()
    interp.graphicstate = PDFGraphicState()
    return interp

class TestBasicFunctionality:
    """Test the fundamental functionality of do_TJ under normal conditions"""

    def test_do_TJ_with_valid_font_and_empty_sequence(self, interpreter):
        """Test do_TJ with a valid font set and empty sequence"""
        # Set up a mock font in textstate
        interpreter.textstate.font = Mock()
        interpreter.textstate.fontsize = 12
        
        # Mock the device's render_string method to track calls
        interpreter.device.render_string = Mock()
        
        # Call do_TJ with empty sequence
        seq = []
        interpreter.do_TJ(seq) # 46.0μs -> 46.1μs (0.109% slower)
        
        # Verify the arguments passed to render_string
        call_args = interpreter.device.render_string.call_args

    def test_do_TJ_with_single_byte_sequence(self, interpreter):
        """Test do_TJ with a sequence containing single byte values"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Create a sequence with bytes
        seq = [b'Hello']
        interpreter.do_TJ(seq) # 29.7μs -> 28.6μs (3.99% faster)

    def test_do_TJ_with_numeric_sequence(self, interpreter):
        """Test do_TJ with a sequence containing numeric values"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Create a sequence with numbers (e.g., glyph adjustments)
        seq = [100, 200, 300]
        interpreter.do_TJ(seq) # 28.8μs -> 28.6μs (0.665% faster)

    def test_do_TJ_with_mixed_sequence(self, interpreter):
        """Test do_TJ with a sequence containing mixed types"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Create a sequence with mixed bytes and numbers
        seq = [b'Text', -50, b'More', 75]
        interpreter.do_TJ(seq) # 27.3μs -> 26.5μs (2.98% faster)

    def test_do_TJ_preserves_textstate(self, interpreter):
        """Test that do_TJ does not modify the textstate"""
        # Set up textstate with specific values
        interpreter.textstate.font = Mock()
        interpreter.textstate.fontsize = 14
        interpreter.textstate.charspace = 2.5
        interpreter.device.render_string = Mock()
        
        # Store original textstate values
        original_fontsize = interpreter.textstate.fontsize
        original_charspace = interpreter.textstate.charspace
        
        seq = [b'test']
        interpreter.do_TJ(seq) # 26.8μs -> 25.0μs (7.03% faster)

    def test_do_TJ_passes_correct_colorspace(self, interpreter):
        """Test that do_TJ passes the correct non-stroking colorspace"""
        # Set up a mock font and custom colorspace
        interpreter.textstate.font = Mock()
        custom_colorspace = PDFColorSpace('DeviceRGB', 3)
        interpreter.graphicstate.ncs = custom_colorspace
        interpreter.device.render_string = Mock()
        
        seq = [b'test']
        interpreter.do_TJ(seq) # 26.1μs -> 25.9μs (0.467% faster)
        
        # Verify the colorspace passed to render_string
        call_args = interpreter.device.render_string.call_args

    def test_do_TJ_passes_graphicstate_copy(self, interpreter):
        """Test that do_TJ passes a copy of graphicstate, not the original"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Modify graphicstate
        interpreter.graphicstate.linewidth = 2.5
        original_gs = interpreter.graphicstate
        
        seq = [b'test']
        interpreter.do_TJ(seq) # 26.1μs -> 25.7μs (1.56% faster)
        
        # Get the graphicstate passed to render_string
        call_args = interpreter.device.render_string.call_args
        passed_gs = call_args[0][3]

class TestEdgeCases:
    """Test do_TJ behavior under extreme or unusual conditions"""

    def test_do_TJ_with_no_font_strict_mode_raises_error(self, resource_manager, device):
        """Test that do_TJ raises error when no font is set in strict mode"""
        # Enable strict mode
        original_strict = settings.STRICT
        settings.STRICT = True
        
        try:
            interp = PDFPageInterpreter(resource_manager, device)
            interp.textstate = PDFTextState()
            interp.graphicstate = PDFGraphicState()
            
            # This should raise an error in strict mode
            from pdfminer.pdfinterp import PDFInterpreterError
            with pytest.raises(PDFInterpreterError):
                interp.do_TJ([b'test'])
        finally:
            # Restore original setting
            settings.STRICT = original_strict

    def test_do_TJ_with_no_font_non_strict_mode_returns_gracefully(self, resource_manager, device):
        """Test that do_TJ returns gracefully when no font is set in non-strict mode"""
        # Disable strict mode
        original_strict = settings.STRICT
        settings.STRICT = False
        
        try:
            interp = PDFPageInterpreter(resource_manager, device)
            interp.textstate = PDFTextState()
            interp.graphicstate = PDFGraphicState()
            interp.device.render_string = Mock()
            
            # This should return without error
            interp.do_TJ([b'test'])
        finally:
            # Restore original setting
            settings.STRICT = original_strict

    def test_do_TJ_with_negative_numeric_adjustments(self, interpreter):
        """Test do_TJ with negative numeric glyph adjustments"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Negative adjustments are common in PDF for kerning
        seq = [b'T', -80, b'e', -50, b'x', -45, b't']
        interpreter.do_TJ(seq) # 28.6μs -> 28.4μs (0.708% faster)
        call_args = interpreter.device.render_string.call_args

    def test_do_TJ_with_large_positive_numeric_adjustments(self, interpreter):
        """Test do_TJ with very large positive numeric adjustments"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Large positive values for spacing
        seq = [b'a', 1000, b'b', 5000, b'c']
        interpreter.do_TJ(seq) # 27.8μs -> 27.8μs (0.004% faster)

    def test_do_TJ_with_float_adjustments(self, interpreter):
        """Test do_TJ with float numeric adjustments"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Float adjustments are valid in PDF
        seq = [b'text', -45.5, b'more', 33.75]
        interpreter.do_TJ(seq) # 25.5μs -> 26.0μs (1.69% slower)
        call_args = interpreter.device.render_string.call_args

    def test_do_TJ_with_zero_numeric_value(self, interpreter):
        """Test do_TJ with zero numeric adjustments"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        seq = [b'text', 0, b'more', 0]
        interpreter.do_TJ(seq) # 25.9μs -> 24.9μs (3.81% faster)

    def test_do_TJ_with_only_numeric_sequence(self, interpreter):
        """Test do_TJ with a sequence containing only numbers"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Sometimes sequences may be all numeric (adjustments only)
        seq = [100, 200, -50, 75]
        interpreter.do_TJ(seq) # 25.0μs -> 24.8μs (0.524% faster)

    def test_do_TJ_with_only_byte_sequence(self, interpreter):
        """Test do_TJ with a sequence containing only bytes"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Sequence with only text, no adjustments
        seq = [b'Hello', b'World', b'Test']
        interpreter.do_TJ(seq) # 26.2μs -> 25.3μs (3.68% faster)

    def test_do_TJ_with_empty_bytes_in_sequence(self, interpreter):
        """Test do_TJ with empty bytes objects in the sequence"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Empty bytes might appear in some PDFs
        seq = [b'text', b'', b'more', b'', b'end']
        interpreter.do_TJ(seq) # 24.7μs -> 24.4μs (1.11% faster)
        call_args = interpreter.device.render_string.call_args

    def test_do_TJ_with_very_small_float_adjustments(self, interpreter):
        """Test do_TJ with very small float adjustments"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Very small float values
        seq = [b'text', 0.001, b'more', -0.001, b'end']
        interpreter.do_TJ(seq) # 23.4μs -> 24.4μs (3.89% slower)

    def test_do_TJ_colorspace_default_gray(self, interpreter):
        """Test that do_TJ uses default DeviceGray colorspace if not changed"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # graphicstate.ncs defaults to DeviceGray
        seq = [b'test']
        interpreter.do_TJ(seq) # 25.1μs -> 25.0μs (0.641% faster)
        
        call_args = interpreter.device.render_string.call_args

class TestLargeScaleScenarios:
    """Test do_TJ performance and scalability with large data samples"""

    def test_do_TJ_with_long_text_sequence(self, interpreter):
        """Test do_TJ with a very long text sequence"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Create a large sequence with 500 items
        seq = []
        for i in range(500):
            seq.append(b'text_chunk_' + str(i).encode())
            if i % 2 == 0:
                seq.append(float(i * 1.5))
        
        interpreter.do_TJ(seq) # 27.8μs -> 24.2μs (15.0% faster)
        call_args = interpreter.device.render_string.call_args

    def test_do_TJ_with_many_small_adjustments(self, interpreter):
        """Test do_TJ with many small numeric adjustments"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Create a sequence with alternating bytes and adjustments
        seq = []
        for i in range(250):
            seq.append(b'x')
            seq.append(-float(i % 100))
        
        interpreter.do_TJ(seq) # 24.7μs -> 24.6μs (0.321% faster)

    def test_do_TJ_with_large_byte_chunks(self, interpreter):
        """Test do_TJ with large byte strings"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Create a sequence with large byte chunks
        large_text = b'a' * 10000
        seq = [large_text, 100, large_text]
        
        interpreter.do_TJ(seq) # 25.2μs -> 24.6μs (2.36% faster)

    def test_do_TJ_with_many_colorspace_switches(self, interpreter):
        """Test do_TJ called multiple times with different colorspaces"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Call do_TJ 100 times with different colorspaces
        for i in range(100):
            cs_name = f'ColorSpace_{i}'
            interpreter.graphicstate.ncs = PDFColorSpace(cs_name, (i % 4) + 1)
            seq = [b'text', float(i)]
            interpreter.do_TJ(seq) # 496μs -> 464μs (6.93% faster)

    def test_do_TJ_with_alternating_sequences(self, interpreter):
        """Test do_TJ with many alternating calls"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Call do_TJ 200 times with different sequences
        for i in range(200):
            seq = [b'chunk_' + str(i).encode(), float(-i), b'end']
            interpreter.do_TJ(seq) # 958μs -> 901μs (6.38% faster)

    def test_do_TJ_with_complex_mixed_sequence(self, interpreter):
        """Test do_TJ with a complex sequence mixing many types"""
        # Set up a mock font
        interpreter.textstate.font = Mock()
        interpreter.device.render_string = Mock()
        
        # Create a complex mixed sequence with 600 items
        seq = []
        for i in range(200):
            seq.append(b'prefix_' + str(i).encode())
            seq.append(float(i) * -0.5)
            seq.append(b'middle')
            seq.append(int(i * 2))
        
        interpreter.do_TJ(seq) # 29.8μs -> 31.0μs (4.03% slower)

    

To edit these changes git checkout codeflash/optimize-PDFPageInterpreter.do_TJ-mkqubnhv and push.