Rename batch_size config to queue_size

The value controls how many files are queued per processing chunk, not a
batch or thread pool size. Renamed across config, client API, tests, and
README. Old config files using batch_size are still accepted with a
deprecation warning.

Author: lfoppiano

Readme.md

@@ -190,7 +190,7 @@ grobid_client --input "~/data/**/*.pdf"   --output ~/results processFulltextDocu
 > [!NOTE]
 > `--input` accepts a directory, a single file, an **archive**, or a **glob pattern**:
 > - **Archives** (`.zip`, `.tar`, `.tar.gz`/`.tgz`, `.tar.bz2`/`.tbz2`) are streamed: eligible entries are read into
->   memory in chunks of `batch_size` and sent to GROBID straight from there — the archive is never fully decompressed and
+>   memory in chunks of `queue_size` and sent to GROBID straight from there — the archive is never fully decompressed and
 >   nothing but the results in `--output` ever touches the disk. If `--output` is omitted, results go to a directory named
 >   after the archive (e.g. `papers.zip` → `papers/`).
 > - **Glob patterns** (`paper.zip`, `paper*.zip`, `**/paper*.zip`, `**/*.pdf`, …) are expanded with `**` recursion; each
@@ -384,7 +384,7 @@ settings.
 ```json
 {
   "grobid_server": "http://localhost:8070",
-  "batch_size": 1000,
+  "queue_size": 1000,
   "sleep_time": 5,
   "timeout": 60,
   "coordinates": [
@@ -403,7 +403,7 @@ settings.
 | Parameter       | Description                                                                                                      | Default                 |
 |-----------------|------------------------------------------------------------------------------------------------------------------|-------------------------|
 | `grobid_server` | GROBID server URL                                                                                                | `http://localhost:8070` |
-| `batch_size`    | Thread pool size. **Tune carefully: a large batch size will result in the data being written less frequently**   | 1000                    |
+| `queue_size`    | Number of files queued per processing chunk. **Tune carefully: a large queue size will result in the data being written less frequently**   | 1000                    |
 | `sleep_time`    | Wait time when server is busy (seconds)                                                                          | 5                       |
 | `timeout`       | Client-side timeout (seconds)                                                                                    | 180                     |
 | `coordinates`   | XML elements for coordinate extraction                                                                           | See above               |

config.json

@@ -1,6 +1,6 @@
 {
   "grobid_server": "http://localhost:8070",
-  "batch_size": 1000,
+  "queue_size": 1000,
   "timeout": 180,
   "sleep_time": 5,
   "coordinates": [

grobid_client/grobid_client.py

@@ -91,7 +91,7 @@ class GrobidClient(ApiClient):
     # Default configuration values
     DEFAULT_CONFIG: dict = {
         'grobid_server': 'http://localhost:8070',
-        'batch_size': 10,
+        'queue_size': 10,
         'sleep_time': 5,
         'timeout': 180,
         'coordinates': [
@@ -121,7 +121,7 @@ class GrobidClient(ApiClient):
     def __init__(
             self,
             grobid_server: Optional[str] = None,
-            batch_size: Optional[int] = None,
+            queue_size: Optional[int] = None,
             coordinates: Optional[list] = None,
             sleep_time: Optional[int] = None,
             timeout: Optional[int] = None,
@@ -143,7 +143,7 @@ def __init__(
         # This ensures CLI arguments override config file values
         self._set_config_params({
             'grobid_server': grobid_server,
-            'batch_size': batch_size,
+            'queue_size': queue_size,
             'coordinates': coordinates,
             'sleep_time': sleep_time,
             'timeout': timeout
@@ -328,6 +328,11 @@ def _load_config(self, path: str = "./config.json") -> None:
                 config_json = config_file.read()
                 # Update the default config with values from the file
                 file_config = json.loads(config_json)
+                if 'batch_size' in file_config:
+                    file_config.setdefault('queue_size', file_config.pop('batch_size'))
+                    temp_logger.warning(
+                        "Config key 'batch_size' is deprecated, use 'queue_size' instead"
+                    )
                 self.config.update(file_config)
                 temp_logger.info("Configuration file loaded successfully")
         except FileNotFoundError as e:
@@ -850,11 +855,11 @@ def _run_file_batches(
             markdown_output: bool,
             skip_errors: bool = False
     ) -> Tuple[int, int, int]:
-        """Run process_batch over a list of files in chunks of batch_size.
+        """Run process_batch over a list of files in chunks of queue_size.
 
         Returns the aggregated (processed, errors, skipped) counts.
         """
-        batch_size_pdf = self.config["batch_size"]
+        queue_size = self.config["queue_size"]
         processed_files_count = 0
         errors_files_count = 0
         skipped_files_count = 0
@@ -870,7 +875,7 @@ def _run_file_batches(
 
             batch.append(input_file)
 
-            if len(batch) == batch_size_pdf:
+            if len(batch) == queue_size:
                 batch_processed, batch_errors, batch_skipped = self.process_batch(
                     service, batch, input_path, output, n, generate_ids,
                     consolidate_header, consolidate_citations, include_raw_citations,
@@ -1057,7 +1062,7 @@ def process_archive(
         """Process the eligible files contained in a zip/tar archive.
 
         The archive is never fully decompressed: entries are read straight into
-        memory in chunks of ``batch_size`` (from the config) and each chunk is
+        memory in chunks of ``queue_size`` (from the config) and each chunk is
         sent to GROBID via ``process_batch``, so memory usage stays bounded by
         the chunk size and nothing but the results ever touches the disk. (The
         exception is ``processCitationList``, whose ``.txt`` inputs are read
@@ -1112,7 +1117,7 @@ def _process_archive_core(
         Does not print the final summary (the caller does), so it can be
         aggregated with other inputs when resolving a glob pattern.
         """
-        batch_size_pdf = self.config["batch_size"]
+        queue_size = self.config["queue_size"]
 
         # Results must survive the temporary extraction directories, so when no
         # output is given we default to a directory named after the archive. For
@@ -1151,8 +1156,8 @@ def _process_archive_core(
             # read straight from the archive into memory and posted from there.
             use_disk = service == 'processCitationList'
 
-            for chunk_start in range(0, total_files, batch_size_pdf):
-                chunk = eligible_members[chunk_start:chunk_start + batch_size_pdf]
+            for chunk_start in range(0, total_files, queue_size):
+                chunk = eligible_members[chunk_start:chunk_start + queue_size]
 
                 if not use_disk:
                     documents = []
@@ -1273,7 +1278,7 @@ def _process_remote_files(
         if output is None:
             output = "."
 
-        batch_size_pdf = self.config["batch_size"]
+        queue_size = self.config["queue_size"]
         print(f"Found {total} remote file(s) to process")
         processed_count = 0
         error_count = 0
@@ -1284,8 +1289,8 @@ def _process_remote_files(
         # fetched straight into memory and posted from there.
         use_disk = service == 'processCitationList'
 
-        for chunk_start in range(0, total, batch_size_pdf):
-            chunk = uris[chunk_start:chunk_start + batch_size_pdf]
+        for chunk_start in range(0, total, queue_size):
+            chunk = uris[chunk_start:chunk_start + queue_size]
 
             if not use_disk:
                 documents = []

tests/conftest.py

@@ -23,7 +23,7 @@ def temp_config_file(temp_dir):
     """Create a temporary config file for tests."""
     config = {
         'grobid_server': 'http://localhost:8070',
-        'batch_size': 10,
+        'queue_size': 10,
         'coordinates': ["persName", "figure"],
         'sleep_time': 2,
         'timeout': 30,

tests/test_config.json

@@ -1,6 +1,6 @@
 {
     "grobid_server": "http://localhost:8070",
-    "batch_size": 10,
+    "queue_size": 10,
     "coordinates": ["persName", "figure", "ref"],
     "sleep_time": 2,
     "timeout": 30,

tests/test_conversions.py

@@ -39,7 +39,7 @@ def setup_method(self):
 
         self.test_config = {
             'grobid_server': 'http://localhost:8070',
-            'batch_size': 10,
+            'queue_size': 10,
             'sleep_time': 5,
             'timeout': 180,
             'logging': {

tests/test_grobid_client.py

@@ -22,7 +22,7 @@ def setup_method(self):
         """Set up test fixtures."""
         self.test_config = {
             'grobid_server': 'http://localhost:8070',
-            'batch_size': 1000,
+            'queue_size': 1000,
             'coordinates': ["persName", "figure", "ref"],
             'sleep_time': 5,
             'timeout': 60,
@@ -43,7 +43,7 @@ def test_init_default_values(self, mock_configure_logging, mock_test_server):
         client = GrobidClient(check_server=False)
 
         assert client.config['grobid_server'] == 'http://localhost:8070'
-        assert client.config['batch_size'] == 10
+        assert client.config['queue_size'] == 10
         assert client.config['sleep_time'] == 5
         assert client.config['timeout'] == 180
         assert 'persName' in client.config['coordinates']
@@ -58,15 +58,15 @@ def test_init_custom_values(self, mock_configure_logging, mock_test_server):
         custom_coords = ["figure", "ref"]
         client = GrobidClient(
             grobid_server='http://custom:9090',
-            batch_size=500,
+            queue_size=500,
             coordinates=custom_coords,
             sleep_time=10,
             timeout=120,
             check_server=False
         )
 
         assert client.config['grobid_server'] == 'http://custom:9090'
-        assert client.config['batch_size'] == 500
+        assert client.config['queue_size'] == 500
         assert client.config['coordinates'] == custom_coords
         assert client.config['sleep_time'] == 10
         assert client.config['timeout'] == 120
@@ -114,6 +114,19 @@ def test_load_config_success(self, mock_configure_logging, mock_test_server, moc
         mock_file.assert_called_once_with('/path/to/config.json', 'r')
         assert client.config['grobid_server'] == 'http://test:8080'
 
+    @patch('builtins.open', new_callable=mock_open, read_data='{"batch_size": 250}')
+    @patch('grobid_client.grobid_client.GrobidClient._test_server_connection')
+    @patch('grobid_client.grobid_client.GrobidClient._configure_logging')
+    def test_load_config_legacy_batch_size(self, mock_configure_logging, mock_test_server, mock_file):
+        """Test that the deprecated batch_size config key is mapped to queue_size."""
+        mock_test_server.return_value = (True, 200)
+
+        client = GrobidClient(check_server=False)
+        client._load_config('/path/to/config.json')
+
+        assert client.config['queue_size'] == 250
+        assert 'batch_size' not in client.config
+
     @patch('grobid_client.grobid_client.GrobidClient._test_server_connection')
     @patch('grobid_client.grobid_client.GrobidClient._configure_logging')
     def test_load_config_file_not_found(self, mock_configure_logging, mock_test_server):
@@ -680,12 +693,12 @@ def test_get_server_url_edge_cases(self, mock_configure_logging, mock_test_serve
 class TestArchiveInput:
     """Tests for streaming zip/tar archives as input (process_archive)."""
 
-    def _client(self, batch_size=2):
+    def _client(self, queue_size=2):
         with patch('grobid_client.grobid_client.GrobidClient._test_server_connection'):
             with patch('grobid_client.grobid_client.GrobidClient._configure_logging'):
                 client = GrobidClient(check_server=False)
         client.logger = Mock()
-        client.config['batch_size'] = batch_size
+        client.config['queue_size'] = queue_size
         return client
 
     @staticmethod
@@ -757,7 +770,7 @@ def test_safe_member_path_blocks_traversal(self):
         assert client._safe_member_path(dest, '.') is None
 
     def test_process_zip_streams_all_pdfs(self):
-        client = self._client(batch_size=2)
+        client = self._client(queue_size=2)
         with tempfile.TemporaryDirectory() as d:
             zip_path = os.path.join(d, 'docs.zip')
             self._make_zip(zip_path, {
@@ -779,7 +792,7 @@ def test_process_zip_streams_all_pdfs(self):
             ]
 
     def test_process_targz(self):
-        client = self._client(batch_size=10)
+        client = self._client(queue_size=10)
         with tempfile.TemporaryDirectory() as d:
             tar_path = os.path.join(d, 'docs.tar.gz')
             self._make_targz(tar_path, {'x.pdf': b'%PDF-x', 'nested/y.pdf': b'%PDF-y'}, d)
@@ -802,7 +815,7 @@ def test_process_routes_archive_to_core(self):
                 assert mock_core.call_args.args[1] == zip_path
 
     def test_process_zip_default_output_named_after_archive(self):
-        client = self._client(batch_size=10)
+        client = self._client(queue_size=10)
         with tempfile.TemporaryDirectory() as d:
             zip_path = os.path.join(d, 'mydocs.zip')
             self._make_zip(zip_path, {'a.pdf': b'%PDF'})
@@ -811,7 +824,7 @@ def test_process_zip_default_output_named_after_archive(self):
 
     def test_archive_entries_never_touch_disk(self):
         """PDFs go from the archive straight to GROBID, without a temp dir."""
-        client = self._client(batch_size=2)
+        client = self._client(queue_size=2)
         with tempfile.TemporaryDirectory() as d:
             zip_path = os.path.join(d, 'docs.zip')
             self._make_zip(zip_path, {'a.pdf': b'%PDF-a', 'sub/b.pdf': b'%PDF-b'})
@@ -831,7 +844,7 @@ def fake_post(url, files=None, data=None, headers=None, timeout=None):
 
     def test_citation_lists_are_still_extracted_to_disk(self):
         """process_txt reads from a path, so citation lists keep the temp-dir route."""
-        client = self._client(batch_size=10)
+        client = self._client(queue_size=10)
         with tempfile.TemporaryDirectory() as d:
             zip_path = os.path.join(d, 'refs.zip')
             self._make_zip(zip_path, {'refs.txt': b'one reference per line'})
@@ -954,7 +967,7 @@ def fake_post(url=None, files=None, data=None, headers=None, timeout=None):
     def test_archive_processing_runs_the_preflight(self):
         import zipfile
         client = self._client()
-        client.config['batch_size'] = 10
+        client.config['queue_size'] = 10
         with tempfile.TemporaryDirectory() as d:
             zip_path = os.path.join(d, 'docs.zip')
             with zipfile.ZipFile(zip_path, 'w') as z:
@@ -974,7 +987,7 @@ def fake_post(url, files=None, data=None, headers=None, timeout=None):
     def test_local_files_skip_the_preflight(self):
         """Plain file processing does not gain a new health call."""
         client = self._client()
-        client.config['batch_size'] = 10
+        client.config['queue_size'] = 10
         with tempfile.TemporaryDirectory() as d:
             with open(os.path.join(d, 'a.pdf'), 'wb') as f:
                 f.write(b'%PDF')
@@ -994,12 +1007,12 @@ def fake_post(url, files=None, data=None, headers=None, timeout=None):
 class TestGlobInput:
     """Tests for glob-pattern input resolution (--input as a glob)."""
 
-    def _client(self, batch_size=50):
+    def _client(self, queue_size=50):
         with patch('grobid_client.grobid_client.GrobidClient._test_server_connection'):
             with patch('grobid_client.grobid_client.GrobidClient._configure_logging'):
                 client = GrobidClient(check_server=False)
         client.logger = Mock()
-        client.config['batch_size'] = batch_size
+        client.config['queue_size'] = queue_size
         return client
 
     @staticmethod
@@ -1213,7 +1226,7 @@ def _client(self):
             with patch('grobid_client.grobid_client.GrobidClient._configure_logging'):
                 client = GrobidClient(check_server=False)
         client.logger = Mock()
-        client.config['batch_size'] = 50
+        client.config['queue_size'] = 50
         return client
 
     @staticmethod

tests/test_integration.py

@@ -22,7 +22,7 @@ def setup_method(self):
         # Create a temporary config file
         self.temp_config = {
             'grobid_server': self.test_server_url,
-            'batch_size': 10,
+            'queue_size': 10,
             'coordinates': ["persName", "figure"],
             'sleep_time': 2,
             'timeout': 30,
@@ -60,7 +60,7 @@ def test_client_initialization_with_config_file(self, mock_get):
 
         # Verify config was loaded
         assert client.config['grobid_server'] == self.test_server_url
-        assert client.config['batch_size'] == 10
+        assert client.config['queue_size'] == 10
         assert client.config['sleep_time'] == 2
         assert client.config['timeout'] == 30
 
@@ -91,14 +91,14 @@ def test_configuration_validation(self):
             with patch('grobid_client.grobid_client.GrobidClient._configure_logging'):
                 client = GrobidClient(
                     grobid_server='http://custom:9090',
-                    batch_size=500,
+                    queue_size=500,
                     config_path=self.config_file,
                     check_server=False
                 )
 
                 # Constructor values should override config file values (CLI precedence)
                 assert client.config['grobid_server'] == 'http://custom:9090'
-                assert client.config['batch_size'] == 500
+                assert client.config['queue_size'] == 500
 
     def test_logging_configuration(self):
         """Test logging configuration from config file."""

tests/test_s3.py

@@ -34,12 +34,12 @@ def _aws_env(monkeypatch):
     monkeypatch.setenv("AWS_DEFAULT_REGION", REGION)
 
 
-def _client(batch_size=2):
+def _client(queue_size=2):
     with patch.object(GrobidClient, "_test_server_connection"):
         with patch.object(GrobidClient, "_configure_logging"):
             c = GrobidClient(check_server=False)
     c.logger = Mock()
-    c.config["batch_size"] = batch_size
+    c.config["queue_size"] = queue_size
     return c