opencage-cli 1.0.0__tar.gz

opencage_cli-1.0.0/LICENSE.txt

@@ -0,0 +1,13 @@
+3-Clause BSD License
+
+Copyright (c) 2014-21 OpenCage GmbH - https://opencagedata.com
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

opencage_cli-1.0.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: opencage-cli
+Version: 1.0.0
+Summary: Command-line tool for the OpenCage Geocoding API
+Author-email: OpenCage GmbH <info@opencagedata.com>
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/OpenCageData/opencage-cli
+Project-URL: Download, https://github.com/OpenCageData/opencage-cli
+Keywords: geocoding,geocoder,cli,command-line,batch
+Classifier: Environment :: Console
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: opencage>=3.3.1
+Requires-Dist: tqdm>=4.66.4
+Requires-Dist: backoff>=2.2.1
+Requires-Dist: certifi>=2024.07.04
+Provides-Extra: dev
+Requires-Dist: responses>=0.25.7; extra == "dev"
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Dynamic: license-file
+
+# OpenCage CLI
+
+A command-line tool for the [OpenCage Geocoding API](https://opencagedata.com/), for forward and reverse geocoding of CSV files.
+
+## Build Status / Code Quality / etc
+
+[![PyPI version](https://badge.fury.io/py/opencage-cli.svg)](https://badge.fury.io/py/opencage-cli)
+[![Versions](https://img.shields.io/pypi/pyversions/opencage-cli)](https://pypi.org/project/opencage-cli/)
+[![Build Status](https://github.com/OpenCageData/opencage-cli/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/OpenCageData/opencage-cli/actions/workflows/build.yml)
+
+## Tutorial
+
+See the [CLI tutorial on the OpenCage site](https://opencagedata.com/tutorials/geocode-commandline) for a full walk-through.
+
+## Installation
+
+Supports Python 3.9 or newer.
+
+```bash
+pip install opencage-cli
+```
+
+This installs an `opencage` executable on your `PATH`. The Python geocoding library it uses (the `opencage` package on PyPI) is pulled in as a dependency.
+
+## Usage
+
+Use `opencage forward` or `opencage reverse`:
+
+```
+opencage forward --help
+
+options:
+  -h, --help            show this help message and exit
+  --api-key API_KEY     Your OpenCage API key
+  --input FILENAME      Input file name
+  --output FILENAME     Output file name
+  --headers             If the first row should be treated as a header row
+  --input-columns       Comma-separated list of integers (default '1')
+  --add-columns         Comma-separated list of output columns (default 'lat,lng,_type,_category,country_code,country,state,county,_normalized_city,postcode,road,house_number,confidence,formatted')
+  --workers             Number of parallel geocoding requests (default 1)
+  --timeout             Timeout in seconds (default 10)
+  --retries             Number of retries (default 10)
+  --api-domain          API domain (default api.opencagedata.com)
+  --optional-api-params
+                        Extra parameters for each request (e.g. language=fr,no_dedupe=1)
+  --unordered           Allow the output lines to be in different order (can be faster)
+  --limit               Stop after this number of lines in the input
+  --dry-run             Read the input file but no geocoding
+  --no-progress         Display no progress bar
+  --quiet               No progress bar and no messages
+  --overwrite           Delete the output file first if it exists
+  --verbose             Display debug information for each request
+```
+
+<img src="batch-progress.gif"/>
+
+See [`examples/addresses.csv`](examples/addresses.csv) for sample input.
+
+## Working with AI / Agent Skill
+
+There is an [Agent Skill for working with the OpenCage Geocoding API](https://github.com/OpenCageData/opencage-skills/).
+
+## Python library
+
+If you want to call the OpenCage API directly from Python rather than via this CLI, install [the `opencage` library](https://pypi.org/project/opencage/) — `pip install opencage`.
+
+## Copyright & License
+
+This software is copyright OpenCage GmbH.
+Please see `LICENSE.txt`
+
+### Who is OpenCage GmbH?
+
+<a href="https://opencagedata.com"><img src="opencage_logo_300_150.png"/></a>
+
+We run a worldwide [geocoding API](https://opencagedata.com/api) and [geosearch](https://opencagedata.com/geosearch) service based on open data.
+Learn more [about us](https://opencagedata.com/about).
+
+We also run [Geomob](https://thegeomob.com), a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy [the Geomob podcast](https://thegeomob.com/podcast/).

opencage_cli-1.0.0/README.md

@@ -0,0 +1,79 @@
+# OpenCage CLI
+
+A command-line tool for the [OpenCage Geocoding API](https://opencagedata.com/), for forward and reverse geocoding of CSV files.
+
+## Build Status / Code Quality / etc
+
+[![PyPI version](https://badge.fury.io/py/opencage-cli.svg)](https://badge.fury.io/py/opencage-cli)
+[![Versions](https://img.shields.io/pypi/pyversions/opencage-cli)](https://pypi.org/project/opencage-cli/)
+[![Build Status](https://github.com/OpenCageData/opencage-cli/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/OpenCageData/opencage-cli/actions/workflows/build.yml)
+
+## Tutorial
+
+See the [CLI tutorial on the OpenCage site](https://opencagedata.com/tutorials/geocode-commandline) for a full walk-through.
+
+## Installation
+
+Supports Python 3.9 or newer.
+
+```bash
+pip install opencage-cli
+```
+
+This installs an `opencage` executable on your `PATH`. The Python geocoding library it uses (the `opencage` package on PyPI) is pulled in as a dependency.
+
+## Usage
+
+Use `opencage forward` or `opencage reverse`:
+
+```
+opencage forward --help
+
+options:
+  -h, --help            show this help message and exit
+  --api-key API_KEY     Your OpenCage API key
+  --input FILENAME      Input file name
+  --output FILENAME     Output file name
+  --headers             If the first row should be treated as a header row
+  --input-columns       Comma-separated list of integers (default '1')
+  --add-columns         Comma-separated list of output columns (default 'lat,lng,_type,_category,country_code,country,state,county,_normalized_city,postcode,road,house_number,confidence,formatted')
+  --workers             Number of parallel geocoding requests (default 1)
+  --timeout             Timeout in seconds (default 10)
+  --retries             Number of retries (default 10)
+  --api-domain          API domain (default api.opencagedata.com)
+  --optional-api-params
+                        Extra parameters for each request (e.g. language=fr,no_dedupe=1)
+  --unordered           Allow the output lines to be in different order (can be faster)
+  --limit               Stop after this number of lines in the input
+  --dry-run             Read the input file but no geocoding
+  --no-progress         Display no progress bar
+  --quiet               No progress bar and no messages
+  --overwrite           Delete the output file first if it exists
+  --verbose             Display debug information for each request
+```
+
+<img src="batch-progress.gif"/>
+
+See [`examples/addresses.csv`](examples/addresses.csv) for sample input.
+
+## Working with AI / Agent Skill
+
+There is an [Agent Skill for working with the OpenCage Geocoding API](https://github.com/OpenCageData/opencage-skills/).
+
+## Python library
+
+If you want to call the OpenCage API directly from Python rather than via this CLI, install [the `opencage` library](https://pypi.org/project/opencage/) — `pip install opencage`.
+
+## Copyright & License
+
+This software is copyright OpenCage GmbH.
+Please see `LICENSE.txt`
+
+### Who is OpenCage GmbH?
+
+<a href="https://opencagedata.com"><img src="opencage_logo_300_150.png"/></a>
+
+We run a worldwide [geocoding API](https://opencagedata.com/api) and [geosearch](https://opencagedata.com/geosearch) service based on open data.
+Learn more [about us](https://opencagedata.com/about).
+
+We also run [Geomob](https://thegeomob.com), a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy [the Geomob podcast](https://thegeomob.com/podcast/).

opencage_cli-1.0.0/opencage_cli/__init__.py

@@ -0,0 +1,6 @@
+"""Command-line interface for the OpenCage Geocoding API."""
+
+from .version import __version__
+
+__author__ = "OpenCage GmbH"
+__email__ = "support@opencagedata.com"

opencage_cli-1.0.0/opencage_cli/batch.py

@@ -0,0 +1,409 @@
+import sys
+import ssl
+import asyncio
+import collections
+import traceback
+import threading
+import random
+import json
+
+from contextlib import suppress
+from decimal import Decimal
+from urllib.parse import urlencode
+from tqdm import tqdm
+import certifi
+import backoff
+from opencage.geocoder import OpenCageGeocode, OpenCageGeocodeError
+
+
+class OpenCageBatchGeocoder():
+    """Batch geocoder that processes CSV files using the OpenCage API.
+
+    Reads rows from a CSV input, geocodes each address using async workers,
+    and writes results to a CSV output.
+
+    Args:
+        options: Parsed command-line options from argparse.
+    """
+
+    def __init__(self, options):
+        self.options = options
+        self.sslcontext = ssl.create_default_context(cafile=certifi.where())
+        self.user_agent_comment = 'OpenCage CLI'
+        self.write_counter = 1
+
+    def __call__(self, *args, **kwargs):
+        """Run the batch geocoder synchronously via asyncio.run."""
+        asyncio.run(self.geocode(*args, **kwargs))
+
+    async def geocode(self, csv_input, csv_output):
+        """Process a CSV input, geocode each row, and write results.
+
+        Args:
+            csv_input: CSV reader for input rows.
+            csv_output: CSV writer for output rows.
+        """
+        if not self.options.dry_run:
+            test = await self.test_request()
+            if test['error']:
+                self.log(test['error'])
+                return
+            if test['free'] is True and self.options.workers > 1:
+                sys.stderr.write("Free trial account detected. Resetting number of workers to 1.\n")
+                self.options.workers = 1
+
+        if self.options.headers:
+            header_columns = next(csv_input, None)
+            if header_columns is None:
+                return
+
+        queue = asyncio.Queue(maxsize=self.options.limit)
+
+        read_warnings = await self.read_input(csv_input, queue)
+
+        if self.options.dry_run:
+            if not read_warnings:
+                print('All good.')
+            return
+
+        if self.options.headers:
+            csv_output.writerow(header_columns + self.options.add_columns)
+
+        progress_bar = not (self.options.no_progress or self.options.quiet) and \
+            tqdm(total=queue.qsize(), position=0, desc="Addresses geocoded", dynamic_ncols=True)
+
+        tasks = []
+        for _ in range(self.options.workers):
+            task = asyncio.create_task(self.worker(csv_output, queue, progress_bar))
+            tasks.append(task)
+
+        # This starts the workers and waits until all are finished
+        await queue.join()
+
+        # All tasks done
+        for task in tasks:
+            task.cancel()
+
+        if progress_bar:
+            progress_bar.close()
+
+    async def test_request(self):
+        """Send a test geocoding request to verify the API key.
+
+        Returns:
+            Dict with 'error' (None or exception) and 'free' (bool indicating
+            whether a free trial account is being used).
+        """
+        try:
+            async with OpenCageGeocode(
+                self.options.api_key,
+                domain=self.options.api_domain,
+                sslcontext=self.sslcontext,
+                user_agent_comment=self.user_agent_comment
+            ) as geocoder:
+                result = await geocoder.geocode_async('Kendall Sq, Cambridge, MA', raw_response=True)
+
+                free = False
+                with suppress(KeyError):
+                    free = result['rate']['limit'] == 2500
+
+                return {'error': None, 'free': free}
+        except Exception as exc:
+            return {'error': exc}
+
+    async def read_input(self, csv_input, queue):
+        """Read all rows from CSV input and add them to the work queue.
+
+        Args:
+            csv_input: CSV reader for input rows.
+            queue: Async queue to populate with parsed input items.
+
+        Returns:
+            True if any warnings were encountered while reading, False otherwise.
+        """
+        any_warnings = False
+        for index, row in enumerate(csv_input):
+            line_number = index + 1
+
+            if len(row) == 0:
+                self.log(f"Line {line_number} - Empty line")
+                any_warnings = True
+                row = ['']
+
+            item = await self.read_one_line(row, line_number)
+            if item['warnings'] is True:
+                any_warnings = True
+            await queue.put(item)
+
+            if queue.full():
+                break
+
+        return any_warnings
+
+    async def read_one_line(self, row, row_id):
+        """Parse a single CSV row into a work item for geocoding.
+
+        Args:
+            row: List of column values from the CSV reader.
+            row_id: 1-based line number of the row in the input.
+
+        Returns:
+            Dict with keys 'row_id', 'address', 'original_columns',
+            and 'warnings'.
+        """
+        warnings = False
+
+        if self.options.input_columns:
+            input_columns = self.options.input_columns
+        elif self.options.command == 'reverse':
+            input_columns = [1, 2]
+        else:
+            input_columns = None
+
+        if input_columns:
+            address = []
+            try:
+                for column in input_columns:
+                    # input_columns option uses 1-based indexing
+                    address.append(row[column - 1])
+            except IndexError:
+                self.log(f"Line {row_id} - Missing input column {column} in {row}")
+                warnings = True
+        else:
+            address = row
+
+        if self.options.command == 'reverse':
+
+            if len(address) != 2:
+                self.log(
+                    f"Line {row_id} - Expected two comma-separated values for reverse geocoding, got {address}")
+            else:
+                # _query_for_reverse_geocoding attempts to convert into numbers. We rather have it fail
+                # now than during the actual geocoding
+                try:
+                    self._query_for_reverse_geocoding(address[0], address[1])
+                except BaseException:
+                    self.log(
+                        f"Line {row_id} - Does not look like latitude and longitude: '{address[0]}' and '{address[1]}'")
+                    warnings = True
+                    address = []
+
+        return {'row_id': row_id, 'address': ','.join(address), 'original_columns': row, 'warnings': warnings}
+
+    async def worker(self, csv_output, queue, progress):
+        """Consume items from the queue and geocode each one.
+
+        Args:
+            csv_output: CSV writer for output rows.
+            queue: Async queue of work items to process.
+            progress: tqdm progress bar, or False if disabled.
+        """
+        while True:
+            item = await queue.get()
+
+            try:
+                await self.geocode_one_address(csv_output, item['row_id'], item['address'], item['original_columns'])
+
+                if progress:
+                    progress.update(1)
+            except Exception as exc:
+                traceback.print_exception(exc, file=sys.stderr)
+            finally:
+                queue.task_done()
+
+    async def geocode_one_address(self, csv_output, row_id, address, original_columns):
+        """Geocode a single address and write the result to the output.
+
+        Args:
+            csv_output: CSV writer for output rows.
+            row_id: 1-based line number of the row in the input.
+            address: Address string (or lat,lng for reverse geocoding).
+            original_columns: Original CSV row columns to preserve in output.
+        """
+        def on_backoff(details):
+            if not self.options.quiet:
+                sys.stderr.write("Backing off {wait:0.1f} seconds afters {tries} tries "
+                                 "calling function {target} with args {args} and kwargs "
+                                 "{kwargs}\n".format(**details))
+
+        @backoff.on_exception(backoff.expo,
+                              asyncio.TimeoutError,
+                              max_time=self.options.timeout,
+                              max_tries=self.options.retries,
+                              on_backoff=on_backoff)
+        async def _geocode_one_address():
+            async with OpenCageGeocode(
+                self.options.api_key,
+                domain=self.options.api_domain,
+                sslcontext=self.sslcontext,
+                user_agent_comment=self.user_agent_comment
+            ) as geocoder:
+                geocoding_results = None
+                response = None
+                params = {'no_annotations': 1, 'raw_response': True, **self.options.optional_api_params}
+
+                try:
+                    if self.options.command == 'reverse':
+                        if ',' in address:
+                            lon, lat = address.split(',')
+                            response = await geocoder.reverse_geocode_async(lon, lat, **params)
+                            geocoding_results = self._floatify_latlng(response['results'])
+                    else:
+                        response = await geocoder.geocode_async(address, **params)
+                        geocoding_results = self._floatify_latlng(response['results'])
+                except OpenCageGeocodeError as exc:
+                    self.log(str(exc))
+                except Exception as exc:
+                    traceback.print_exception(exc, file=sys.stderr)
+
+                try:
+                    if geocoding_results is not None and len(geocoding_results):
+                        geocoding_result = geocoding_results[0]
+                    else:
+                        geocoding_result = None
+
+                    if self.options.verbose:
+                        self.log({
+                            'row_id': row_id,
+                            'thread_id': threading.get_native_id(),
+                            'request': geocoder.url + '?' + urlencode(geocoder._parse_request(address, params)),
+                            'response': response
+                        })
+
+                    await self.write_one_geocoding_result(
+                        csv_output,
+                        row_id,
+                        geocoding_result,
+                        response,
+                        original_columns
+                    )
+                except Exception as exc:
+                    traceback.print_exception(exc, file=sys.stderr)
+
+        await _geocode_one_address()
+
+    async def write_one_geocoding_result(
+            self,
+            csv_output,
+            row_id,
+            geocoding_result,
+            raw_response,
+            original_columns):
+        """Write a single geocoding result row to the CSV output.
+
+        Appends the requested output columns to the original CSV columns.
+        Rows are written in order unless the --unordered option is set.
+
+        Args:
+            csv_output: CSV writer for output rows.
+            row_id: 1-based line number of the row in the input.
+            geocoding_result: First result dict from the API, or None.
+            raw_response: Full API response dict.
+            original_columns: Original CSV row columns to preserve in output.
+        """
+        row = original_columns
+
+        for column in self.options.add_columns:
+            if column == 'status':
+                row.append(self.deep_get_result_value(raw_response, ['status', 'message']))
+            elif geocoding_result is None:
+                row.append('')
+            elif column in geocoding_result:
+                row.append(self.deep_get_result_value(geocoding_result, [column], ''))
+            elif column in geocoding_result['components']:
+                row.append(self.deep_get_result_value(geocoding_result, ['components', column], ''))
+            elif column in geocoding_result['geometry']:
+                row.append(self.deep_get_result_value(geocoding_result, ['geometry', column], ''))
+            elif column == 'FIPS':
+                row.append(
+                    self.deep_get_result_value(
+                        geocoding_result, [
+                            'annotations', 'FIPS', 'county'], ''))
+            elif column == 'json':
+                row.append(json.dumps(geocoding_result, separators=(',', ':')))  # Compact JSON
+            else:
+                row.append('')
+
+        # Enforce that row are written ordered. That means we might wait for other threads
+        # to finish a task and make the overall process slower. Alternative would be to
+        # use a second queue, or keep some results in memory.
+        if not self.options.unordered:
+            while row_id > self.write_counter:
+                if self.options.verbose:
+                    self.log(f"Want to write row {row_id}, but write_counter is at {self.write_counter}")
+                await asyncio.sleep(random.uniform(0.01, 0.1))
+
+            if self.options.verbose:
+                self.log(f"Writing row {row_id}")
+        csv_output.writerow(row)
+        self.write_counter = self.write_counter + 1
+
+    def log(self, message):
+        """Write a message to stderr unless quiet mode is enabled.
+
+        Args:
+            message: Message string to display.
+        """
+        if not self.options.quiet:
+            sys.stderr.write(f"{message}\n")
+
+    def deep_get_result_value(self, data, keys, default=None):
+        """Retrieve a nested value from a dict using a list of keys.
+
+        Args:
+            data: Dict to traverse.
+            keys: List of keys to follow in sequence.
+            default: Value to return if any key is missing.
+
+        Returns:
+            The nested value, or default if the path doesn't exist.
+
+        Example:
+            >>> data = {'status': {'code': 200, 'message': 'OK'}}
+            >>> self.deep_get_result_value(data, ['status', 'message'])
+            'OK'
+            >>> self.deep_get_result_value(data, ['missing', 'key'], '')
+            ''
+        """
+        for key in keys:
+            if isinstance(data, dict):
+                data = data.get(key, default)
+            else:
+                return default
+        return data
+
+    def _query_for_reverse_geocoding(self, lat, lng):
+        """Format a (lat, lng) pair as the string the API expects for reverse geocoding.
+
+        Uses ``Decimal(str(...))`` to preserve the precision the caller specified
+        and to avoid scientific notation (e.g. ``1e-5``).
+        """
+        return f"{Decimal(str(lat)):f},{Decimal(str(lng)):f}"
+
+    def _floatify_latlng(self, input_value):
+        """Recursively convert ``{'lat': ..., 'lng': ...}`` dicts to floats.
+
+        Walks lists and dicts; any dict that contains exactly the two keys
+        ``lat`` and ``lng`` is rewritten with float values. Other structures
+        pass through unchanged. Works around the API occasionally returning
+        lat/lng as strings.
+        """
+        if isinstance(input_value, collections.abc.Mapping):
+            if len(input_value) == 2 and sorted(input_value.keys()) == ['lat', 'lng']:
+                return {
+                    'lat': self._float_if_float(input_value['lat']),
+                    'lng': self._float_if_float(input_value['lng']),
+                }
+
+            return dict((key, self._floatify_latlng(value)) for key, value in input_value.items())
+
+        if isinstance(input_value, collections.abc.MutableSequence):
+            return [self._floatify_latlng(x) for x in input_value]
+
+        return input_value
+
+    def _float_if_float(self, value):
+        try:
+            return float(value)
+        except ValueError:
+            return value

opencage_cli-1.0.0/opencage_cli/command_line.py

@@ -0,0 +1,234 @@
+import argparse
+import sys
+import io
+from pathlib import Path
+import re
+import csv
+
+from opencage_cli.batch import OpenCageBatchGeocoder
+from opencage_cli.version import __version__
+
+
+def main(args=sys.argv[1:]):
+    """Entry point for the OpenCage CLI.
+
+    Args:
+        args: Command-line arguments (defaults to sys.argv[1:]).
+    """
+    options = parse_args(args)
+
+    geocoder = OpenCageBatchGeocoder(options)
+
+    with options.input as input_filename:
+        with (io.StringIO() if options.dry_run else open(options.output, 'x', encoding='utf-8')) as output_io:
+            reader = csv.reader(input_filename, strict=True, skipinitialspace=True)
+            writer = csv.writer(output_io)
+
+            geocoder(csv_input=reader, csv_output=writer)
+
+
+def parse_args(args):
+    """Parse and validate command-line arguments.
+
+    Args:
+        args: List of command-line argument strings.
+
+    Returns:
+        Parsed argparse.Namespace with all options set.
+    """
+    if len(args) == 0:
+        print("To display help use 'opencage -h', 'opencage forward -h' or 'opencage reverse -h'", file=sys.stderr)
+        sys.exit(1)
+
+    parser = argparse.ArgumentParser(description=f'OpenCage CLI {__version__}')
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+
+    subparsers = parser.add_subparsers(dest='command')
+    subparsers.required = True
+
+    subparser_forward = subparsers.add_parser(
+        'forward', help="Forward geocode a file (input is address, add coordinates)")
+    subparser_reverse = subparsers.add_parser(
+        'reverse', help="Reverse geocode a file (input is coordinates, add full address)")
+
+    for subparser in [subparser_forward, subparser_reverse]:
+        subparser.add_argument("--api-key", required=True, type=api_key_type, help="Your OpenCage API key")
+        subparser.add_argument(
+            "--input",
+            required=True,
+            type=argparse.FileType(
+                'r',
+                encoding='utf-8'),
+            help="Input file name",
+            metavar='FILENAME')
+        subparser.add_argument(
+            "--output",
+            required=True,
+            type=str,
+            help="Output file name",
+            metavar='FILENAME')
+
+        add_optional_arguments(subparser)
+
+    options = parser.parse_args(args)
+
+    if Path(options.output).exists() and not options.dry_run:
+        if options.overwrite:
+            Path(options.output).unlink()
+        else:
+            print(
+                f"Error: The output file '{options.output}' already exists. You can add --overwrite to your command.",
+                file=sys.stderr)
+            sys.exit(1)
+
+    if 0 in options.input_columns:
+        print("Error: A column 0 in --input-columns does not exist. The lowest possible number is 1.", file=sys.stderr)
+        sys.exit(1)
+
+    return options
+
+
+def add_optional_arguments(parser):
+    """Add optional arguments shared by forward and reverse subcommands.
+
+    Args:
+        parser: argparse subparser to add arguments to.
+
+    Returns:
+        The parser with arguments added.
+    """
+    parser.add_argument(
+        "--headers",
+        action="store_true",
+        help="If the first row should be treated as a header row")
+    default_input_cols = '1,2' if re.match(r'.*reverse', parser.prog) else '1'
+    parser.add_argument(
+        "--input-columns",
+        type=comma_separated_type(int),
+        default=default_input_cols,
+        help=f"Comma-separated list of integers (default '{default_input_cols}')",
+        metavar='')
+    default_add_cols = (
+        'lat,lng,_type,_category,country_code,country,state,county,_normalized_city,'
+        'postcode,road,house_number,confidence,formatted'
+    )
+    parser.add_argument(
+        "--add-columns",
+        type=comma_separated_type(str),
+        default=default_add_cols,
+        help=f"Comma-separated list of output columns (default '{default_add_cols}')",
+        metavar='')
+    parser.add_argument("--workers", type=ranged_type(int, 1, 20), default=1,
+                        help="Number of parallel geocoding requests (default 1)", metavar='')
+    parser.add_argument("--timeout", type=ranged_type(int, 1, 60), default=10,
+                        help="Timeout in seconds (default 10)", metavar='')
+    parser.add_argument("--retries", type=ranged_type(int, 1, 60), default=10,
+                        help="Number of retries (default 10)", metavar='')
+    parser.add_argument("--api-domain", type=str, default="api.opencagedata.com",
+                        help="API domain (default api.opencagedata.com)", metavar='')
+    parser.add_argument("--optional-api-params", type=comma_separated_dict_type, default="",
+                        help="Extra parameters for each request (e.g. language=fr,no_dedupe=1)", metavar='')
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=0,
+        help="Stop after this number of lines in the input",
+        metavar='')
+    parser.add_argument(
+        "--unordered",
+        action="store_true",
+        help="Allow the output lines to be in different order (can be faster)")
+    parser.add_argument("--dry-run", action="store_true", help="Read the input file but no geocoding")
+    parser.add_argument("--no-progress", action="store_true", help="Display no progress bar")
+    parser.add_argument("--quiet", action="store_true", help="No progress bar and no messages")
+    parser.add_argument("--overwrite", action="store_true", help="Delete the output file first if it exists")
+    parser.add_argument("--verbose", action="store_true", help="Display debug information for each request")
+
+    return parser
+
+
+def api_key_type(apikey):
+    """Validate an OpenCage API key format.
+
+    Expects a 32-character lowercase hex string, optionally prefixed
+    with ``oc_gc_`` (e.g. ``oc_gc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d``
+    or ``1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d``).
+
+    Args:
+        apikey: API key string to validate.
+
+    Returns:
+        The validated API key string.
+
+    Raises:
+        argparse.ArgumentTypeError: If the key doesn't match the expected format.
+    """
+    pattern = re.compile(r"^(oc_gc_)?[0-9a-f]{32}$")
+
+    if not pattern.match(apikey):
+        raise argparse.ArgumentTypeError("invalid API key")
+
+    return apikey
+
+
+def ranged_type(value_type, min_value, max_value):
+    """Create an argparse type function that enforces a value range.
+
+    Args:
+        value_type: Type to convert the argument to (e.g. int, float).
+        min_value: Minimum allowed value (inclusive).
+        max_value: Maximum allowed value (inclusive).
+
+    Returns:
+        A type-checking function suitable for argparse's type parameter.
+    """
+    def range_checker(arg: str):
+        try:
+            f = value_type(arg)
+        except ValueError as exc:
+            raise argparse.ArgumentTypeError(f'must be a valid {value_type}') from exc
+        if f < min_value or f > max_value:
+            raise argparse.ArgumentTypeError(f'must be within [{min_value}, {max_value}]')
+        return f
+
+    # Return function handle to checking function
+    return range_checker
+
+
+def comma_separated_type(value_type):
+    """Create an argparse type function that parses comma-separated values.
+
+    Args:
+        value_type: Type to convert each element to (e.g. int, str).
+
+    Returns:
+        A type-checking function suitable for argparse's type parameter.
+    """
+    def comma_separated(arg: str):
+        if not arg:
+            return []
+
+        return [value_type(x) for x in arg.split(',')]
+
+    return comma_separated
+
+
+def comma_separated_dict_type(arg):
+    """Parse a comma-separated list of key=value pairs into a dict.
+
+    Args:
+        arg: String like "key1=val1,key2=val2".
+
+    Returns:
+        Dict of parsed key-value pairs, or empty dict if arg is empty.
+
+    Raises:
+        argparse.ArgumentTypeError: If the string is not valid key=value format.
+    """
+    if not arg:
+        return {}
+
+    try:
+        return dict([x.split('=') for x in arg.split(',')])
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be a valid comma separated list of key=value pairs") from exc

opencage_cli-1.0.0/opencage_cli/version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

opencage_cli-1.0.0/opencage_cli.egg-info/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: opencage-cli
+Version: 1.0.0
+Summary: Command-line tool for the OpenCage Geocoding API
+Author-email: OpenCage GmbH <info@opencagedata.com>
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/OpenCageData/opencage-cli
+Project-URL: Download, https://github.com/OpenCageData/opencage-cli
+Keywords: geocoding,geocoder,cli,command-line,batch
+Classifier: Environment :: Console
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: opencage>=3.3.1
+Requires-Dist: tqdm>=4.66.4
+Requires-Dist: backoff>=2.2.1
+Requires-Dist: certifi>=2024.07.04
+Provides-Extra: dev
+Requires-Dist: responses>=0.25.7; extra == "dev"
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Dynamic: license-file
+
+# OpenCage CLI
+
+A command-line tool for the [OpenCage Geocoding API](https://opencagedata.com/), for forward and reverse geocoding of CSV files.
+
+## Build Status / Code Quality / etc
+
+[![PyPI version](https://badge.fury.io/py/opencage-cli.svg)](https://badge.fury.io/py/opencage-cli)
+[![Versions](https://img.shields.io/pypi/pyversions/opencage-cli)](https://pypi.org/project/opencage-cli/)
+[![Build Status](https://github.com/OpenCageData/opencage-cli/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/OpenCageData/opencage-cli/actions/workflows/build.yml)
+
+## Tutorial
+
+See the [CLI tutorial on the OpenCage site](https://opencagedata.com/tutorials/geocode-commandline) for a full walk-through.
+
+## Installation
+
+Supports Python 3.9 or newer.
+
+```bash
+pip install opencage-cli
+```
+
+This installs an `opencage` executable on your `PATH`. The Python geocoding library it uses (the `opencage` package on PyPI) is pulled in as a dependency.
+
+## Usage
+
+Use `opencage forward` or `opencage reverse`:
+
+```
+opencage forward --help
+
+options:
+  -h, --help            show this help message and exit
+  --api-key API_KEY     Your OpenCage API key
+  --input FILENAME      Input file name
+  --output FILENAME     Output file name
+  --headers             If the first row should be treated as a header row
+  --input-columns       Comma-separated list of integers (default '1')
+  --add-columns         Comma-separated list of output columns (default 'lat,lng,_type,_category,country_code,country,state,county,_normalized_city,postcode,road,house_number,confidence,formatted')
+  --workers             Number of parallel geocoding requests (default 1)
+  --timeout             Timeout in seconds (default 10)
+  --retries             Number of retries (default 10)
+  --api-domain          API domain (default api.opencagedata.com)
+  --optional-api-params
+                        Extra parameters for each request (e.g. language=fr,no_dedupe=1)
+  --unordered           Allow the output lines to be in different order (can be faster)
+  --limit               Stop after this number of lines in the input
+  --dry-run             Read the input file but no geocoding
+  --no-progress         Display no progress bar
+  --quiet               No progress bar and no messages
+  --overwrite           Delete the output file first if it exists
+  --verbose             Display debug information for each request
+```
+
+<img src="batch-progress.gif"/>
+
+See [`examples/addresses.csv`](examples/addresses.csv) for sample input.
+
+## Working with AI / Agent Skill
+
+There is an [Agent Skill for working with the OpenCage Geocoding API](https://github.com/OpenCageData/opencage-skills/).
+
+## Python library
+
+If you want to call the OpenCage API directly from Python rather than via this CLI, install [the `opencage` library](https://pypi.org/project/opencage/) — `pip install opencage`.
+
+## Copyright & License
+
+This software is copyright OpenCage GmbH.
+Please see `LICENSE.txt`
+
+### Who is OpenCage GmbH?
+
+<a href="https://opencagedata.com"><img src="opencage_logo_300_150.png"/></a>
+
+We run a worldwide [geocoding API](https://opencagedata.com/api) and [geosearch](https://opencagedata.com/geosearch) service based on open data.
+Learn more [about us](https://opencagedata.com/about).
+
+We also run [Geomob](https://thegeomob.com), a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy [the Geomob podcast](https://thegeomob.com/podcast/).

opencage_cli-1.0.0/opencage_cli.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE.txt
+README.md
+pyproject.toml
+setup.py
+opencage_cli/__init__.py
+opencage_cli/batch.py
+opencage_cli/command_line.py
+opencage_cli/version.py
+opencage_cli.egg-info/PKG-INFO
+opencage_cli.egg-info/SOURCES.txt
+opencage_cli.egg-info/dependency_links.txt
+opencage_cli.egg-info/entry_points.txt
+opencage_cli.egg-info/requires.txt
+opencage_cli.egg-info/top_level.txt
+test/test_batch.py

opencage_cli-1.0.0/opencage_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opencage_cli-1.0.0/opencage_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+opencage = opencage_cli.command_line:main

opencage_cli-1.0.0/opencage_cli.egg-info/requires.txt

@@ -0,0 +1,11 @@
+opencage>=3.3.1
+tqdm>=4.66.4
+backoff>=2.2.1
+certifi>=2024.07.04
+
+[dev]
+responses>=0.25.7
+flake8>=7.0.0
+pytest>=7.4.0
+pytest-asyncio>=0.21.0
+pytest-cov>=4.1.0

opencage_cli-1.0.0/opencage_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+opencage_cli

opencage_cli-1.0.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=65.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opencage-cli"
+dynamic = ["version"]
+description = "Command-line tool for the OpenCage Geocoding API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "BSD-3-Clause"
+authors = [{name = "OpenCage GmbH", email = "info@opencagedata.com"}]
+keywords = ["geocoding", "geocoder", "cli", "command-line", "batch"]
+classifiers = [
+    "Environment :: Console",
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "opencage>=3.3.1",
+    "tqdm>=4.66.4",
+    "backoff>=2.2.1",
+    "certifi>=2024.07.04",
+]
+
+[project.optional-dependencies]
+dev = [
+    "responses>=0.25.7",
+    "flake8>=7.0.0",
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.1.0",
+]
+
+[project.scripts]
+opencage = "opencage_cli.command_line:main"
+
+[project.urls]
+Repository = "https://github.com/OpenCageData/opencage-cli"
+Download = "https://github.com/OpenCageData/opencage-cli"
+
+[tool.setuptools.dynamic]
+version = {attr = "opencage_cli.version.__version__"}
+
+[tool.coverage.run]
+branch = true
+source = ["opencage_cli"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]

opencage_cli-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

opencage_cli-1.0.0/setup.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+"""Backwards-compatible setup.py shim. All config is in pyproject.toml."""
+
+from setuptools import setup
+
+setup()

opencage_cli-1.0.0/test/test_batch.py

@@ -0,0 +1,25 @@
+from opencage_cli.batch import OpenCageBatchGeocoder
+
+batch = OpenCageBatchGeocoder({})
+
+
+def test_deep_get_result_value():
+    result = {
+        'annotations': {
+            'FIPS': {
+                'state': 'CA'
+            }
+        },
+        'components': {
+            'street': 'Main Road'
+        }
+    }
+
+    assert batch.deep_get_result_value(result, ['hello', 'world']) is None
+
+    assert batch.deep_get_result_value(result, ['components', 'street']) == 'Main Road'
+    assert batch.deep_get_result_value(result, ['components', 'city']) is None
+    assert batch.deep_get_result_value(result, ['components', 'city'], '') == ''
+
+    assert batch.deep_get_result_value([], ['hello', 'world']) is None
+    assert batch.deep_get_result_value(None, ['hello', 'world']) is None