mapillary-tools 0.14.0a2__tar.gz → 0.14.1__tar.gz

{mapillary_tools-0.14.0a2 → mapillary_tools-0.14.1}/PKG-INFO

@@ -1,32 +1,38 @@
 Metadata-Version: 2.4
 Name: mapillary_tools
-Version: 0.14.0a2
+Version: 0.14.1
 Summary: Mapillary Image/Video Import Pipeline
-Home-page: https://github.com/mapillary/mapillary_tools
-Author: Mapillary
+Author-email: Mapillary <support@mapillary.com>
 License: BSD
-Requires-Python: >=3.8
+Project-URL: Homepage, https://github.com/mapillary/mapillary_tools
+Project-URL: Repository, https://github.com/mapillary/mapillary_tools
+Project-URL: Issues, https://github.com/mapillary/mapillary_tools/issues
+Keywords: mapillary,gis,computer vision,street view
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: appdirs<2.0.0,>=1.4.4
-Requires-Dist: construct<3.0.0,>=2.10.0
-Requires-Dist: exifread==2.3.2
-Requires-Dist: piexif==1.1.3
-Requires-Dist: gpxpy<1.6.0,>=1.5.0
+Requires-Dist: construct~=2.10.0
+Requires-Dist: exifread~=3.0
+Requires-Dist: gpxpy~=1.6.0
+Requires-Dist: humanize>=4.12.3
+Requires-Dist: jsonschema~=4.17.0
+Requires-Dist: piexif~=1.1
 Requires-Dist: pynmea2<2.0.0,>=1.12.0
 Requires-Dist: requests[socks]<3.0.0,>=2.20.0
 Requires-Dist: tqdm<5.0,>=4.0
-Requires-Dist: typing_extensions
-Requires-Dist: jsonschema~=4.17.3
-Dynamic: author
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
+Requires-Dist: typing-extensions>=4.12.2
 Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 <p align="center">
   <a href="https://github.com/mapillary/mapillary_tools/">
@@ -58,18 +64,40 @@ mapillary_tools --help
 <!--ts-->
 
 - [Supported File Formats](#supported-file-formats)
+  - [Image Formats](#image-formats)
+  - [Video Formats](#video-formats)
 - [Installation](#installation)
+  - [Standalone Executable](#standalone-executable)
+  - [Installing via pip](#installing-via-pip)
+    - [Installing on Android Devices](#installing-on-android-devices)
 - [Usage](#usage)
   - [Process and Upload](#process-and-upload)
   - [Process](#process)
   - [Upload](#upload)
 - [Advanced Usage](#advanced-usage)
   - [Local Video Processing](#local-video-processing)
+    - [Install FFmpeg](#install-ffmpeg)
+    - [Video Processing](#video-processing)
   - [Geotagging with GPX](#geotagging-with-gpx)
+  - [New video geotagging features (experimental)](#new-video-geotagging-features-experimental)
+    - [Usage](#usage-1)
+    - [Examples](#examples)
+      - [Generic supported videos](#generic-supported-videos)
+      - [External GPX](#external-gpx)
+      - [Insta360 stitched videos](#insta360-stitched-videos)
+    - [Limitations of `--video_geotag_source`](#limitations-of---video_geotag_source)
   - [Authenticate](#authenticate)
+    - [Examples](#examples-1)
   - [Image Description](#image-description)
   - [Zip Images](#zip-images)
 - [Development](#development)
+  - [Setup](#setup)
+    - [Option 1: Using uv (Recommended)](#option-1-using-uv-recommended)
+    - [Option 2: Using pip with virtual environment](#option-2-using-pip-with-virtual-environment)
+  - [Running the code](#running-the-code)
+  - [Tests](#tests)
+  - [Code Quality](#code-quality)
+  - [Release and Build](#release-and-build)
 
 <!--te-->
 
@@ -495,29 +523,49 @@ git clone git@github.com:mapillary/mapillary_tools.git
 cd mapillary_tools
 ```
 
-Set up the virtual environment. It is optional but recommended:
+### Option 1: Using uv (Recommended)
+
+Use [uv](https://docs.astral.sh/uv/) - a fast Python package manager.
+
+Install the project in development mode with all dependencies:
 
 ```sh
-pip install pipenv
+# Install the project and development dependencies
+uv sync --group dev
+
+# Activate the virtual environment
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 ```
 
-Install dependencies:
+### Option 2: Using pip with virtual environment
+
+Set up a virtual environment (recommended):
 
 ```sh
-pipenv install -r requirements.txt
-pipenv install -r requirements-dev.txt
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 ```
 
-Enter the virtualenv shell:
+Install the project in development mode:
 
 ```sh
-pipenv shell
+# Install the project and all dependencies in editable mode
+pip install -e .
+
+# Install development dependencies
+pip install --group dev
 ```
 
+## Running the code
+
 Run the code from the repository:
 
 ```sh
-python3 -m mapillary_tools.commands --version
+# If you have mapillary_tools installed in editable mode
+mapillary_tools --version
+
+# Alternatively
+python -m mapillary_tools.commands --version
 ```
 
 ## Tests
@@ -525,19 +573,28 @@ python3 -m mapillary_tools.commands --version
 Run tests:
 
 ```sh
-# test all cases
-python3 -m pytest -s -vv tests
-# or test a single case specifically
-python3 -m pytest -s -vv tests/unit/test_camm_parser.py::test_build_and_parse
+# Test all cases
+pytest -s -vv tests
+# Or test a single case specifically
+pytest -s -vv tests/unit/test_camm_parser.py::test_build_and_parse
 ```
 
-Run linting:
+## Code Quality
+
+Run code formatting and linting:
 
 ```sh
-# format code
-black mapillary_tools tests
-# sort imports
+# Format code with ruff
+ruff format mapillary_tools tests
+
+# Lint code with ruff
+ruff check mapillary_tools tests
+
+# Sort imports with usort
 usort format mapillary_tools tests
+
+# Type checking with mypy
+mypy mapillary_tools
 ```
 
 ## Release and Build

mapillary_tools-0.14.0a2/mapillary_tools.egg-info/PKG-INFO → mapillary_tools-0.14.1/README.md

@@ -1,33 +1,3 @@
-Metadata-Version: 2.4
-Name: mapillary_tools
-Version: 0.14.0a2
-Summary: Mapillary Image/Video Import Pipeline
-Home-page: https://github.com/mapillary/mapillary_tools
-Author: Mapillary
-License: BSD
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: appdirs<2.0.0,>=1.4.4
-Requires-Dist: construct<3.0.0,>=2.10.0
-Requires-Dist: exifread==2.3.2
-Requires-Dist: piexif==1.1.3
-Requires-Dist: gpxpy<1.6.0,>=1.5.0
-Requires-Dist: pynmea2<2.0.0,>=1.12.0
-Requires-Dist: requests[socks]<3.0.0,>=2.20.0
-Requires-Dist: tqdm<5.0,>=4.0
-Requires-Dist: typing_extensions
-Requires-Dist: jsonschema~=4.17.3
-Dynamic: author
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
 <p align="center">
   <a href="https://github.com/mapillary/mapillary_tools/">
     <img src="https://raw.githubusercontent.com/mapillary/mapillary_tools/main/docs/images/logo.png">
@@ -58,18 +28,40 @@ mapillary_tools --help
 <!--ts-->
 
 - [Supported File Formats](#supported-file-formats)
+  - [Image Formats](#image-formats)
+  - [Video Formats](#video-formats)
 - [Installation](#installation)
+  - [Standalone Executable](#standalone-executable)
+  - [Installing via pip](#installing-via-pip)
+    - [Installing on Android Devices](#installing-on-android-devices)
 - [Usage](#usage)
   - [Process and Upload](#process-and-upload)
   - [Process](#process)
   - [Upload](#upload)
 - [Advanced Usage](#advanced-usage)
   - [Local Video Processing](#local-video-processing)
+    - [Install FFmpeg](#install-ffmpeg)
+    - [Video Processing](#video-processing)
   - [Geotagging with GPX](#geotagging-with-gpx)
+  - [New video geotagging features (experimental)](#new-video-geotagging-features-experimental)
+    - [Usage](#usage-1)
+    - [Examples](#examples)
+      - [Generic supported videos](#generic-supported-videos)
+      - [External GPX](#external-gpx)
+      - [Insta360 stitched videos](#insta360-stitched-videos)
+    - [Limitations of `--video_geotag_source`](#limitations-of---video_geotag_source)
   - [Authenticate](#authenticate)
+    - [Examples](#examples-1)
   - [Image Description](#image-description)
   - [Zip Images](#zip-images)
 - [Development](#development)
+  - [Setup](#setup)
+    - [Option 1: Using uv (Recommended)](#option-1-using-uv-recommended)
+    - [Option 2: Using pip with virtual environment](#option-2-using-pip-with-virtual-environment)
+  - [Running the code](#running-the-code)
+  - [Tests](#tests)
+  - [Code Quality](#code-quality)
+  - [Release and Build](#release-and-build)
 
 <!--te-->
 
@@ -495,29 +487,49 @@ git clone git@github.com:mapillary/mapillary_tools.git
 cd mapillary_tools
 ```
 
-Set up the virtual environment. It is optional but recommended:
+### Option 1: Using uv (Recommended)
+
+Use [uv](https://docs.astral.sh/uv/) - a fast Python package manager.
+
+Install the project in development mode with all dependencies:
 
 ```sh
-pip install pipenv
+# Install the project and development dependencies
+uv sync --group dev
+
+# Activate the virtual environment
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 ```
 
-Install dependencies:
+### Option 2: Using pip with virtual environment
+
+Set up a virtual environment (recommended):
 
 ```sh
-pipenv install -r requirements.txt
-pipenv install -r requirements-dev.txt
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 ```
 
-Enter the virtualenv shell:
+Install the project in development mode:
 
 ```sh
-pipenv shell
+# Install the project and all dependencies in editable mode
+pip install -e .
+
+# Install development dependencies
+pip install --group dev
 ```
 
+## Running the code
+
 Run the code from the repository:
 
 ```sh
-python3 -m mapillary_tools.commands --version
+# If you have mapillary_tools installed in editable mode
+mapillary_tools --version
+
+# Alternatively
+python -m mapillary_tools.commands --version
 ```
 
 ## Tests
@@ -525,19 +537,28 @@ python3 -m mapillary_tools.commands --version
 Run tests:
 
 ```sh
-# test all cases
-python3 -m pytest -s -vv tests
-# or test a single case specifically
-python3 -m pytest -s -vv tests/unit/test_camm_parser.py::test_build_and_parse
+# Test all cases
+pytest -s -vv tests
+# Or test a single case specifically
+pytest -s -vv tests/unit/test_camm_parser.py::test_build_and_parse
 ```
 
-Run linting:
+## Code Quality
+
+Run code formatting and linting:
 
 ```sh
-# format code
-black mapillary_tools tests
-# sort imports
+# Format code with ruff
+ruff format mapillary_tools tests
+
+# Lint code with ruff
+ruff check mapillary_tools tests
+
+# Sort imports with usort
 usort format mapillary_tools tests
+
+# Type checking with mypy
+mypy mapillary_tools
 ```
 
 ## Release and Build

mapillary_tools-0.14.1/mapillary_tools/__init__.py

@@ -0,0 +1 @@
+VERSION = "0.14.1"

mapillary_tools-0.14.1/mapillary_tools/api_v4.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import enum
+import logging
+import os
+import typing as T
+
+import requests
+
+from . import http
+
+LOG = logging.getLogger(__name__)
+MAPILLARY_CLIENT_TOKEN = os.getenv(
+    "MAPILLARY_CLIENT_TOKEN", "MLY|5675152195860640|6b02c72e6e3c801e5603ab0495623282"
+)
+MAPILLARY_GRAPH_API_ENDPOINT = os.getenv(
+    "MAPILLARY_GRAPH_API_ENDPOINT", "https://graph.mapillary.com"
+)
+REQUESTS_TIMEOUT: float = 60  # 1 minutes
+
+
+class HTTPContentError(Exception):
+    """
+    Raised when the HTTP response is ok (200) but the content is not as expected
+    e.g. not JSON or not a valid response.
+    """
+
+    def __init__(self, message: str, response: requests.Response):
+        self.response = response
+        super().__init__(message)
+
+
+class ClusterFileType(enum.Enum):
+    ZIP = "zip"
+    BLACKVUE = "mly_blackvue_video"
+    CAMM = "mly_camm_video"
+    MLY_BUNDLE_MANIFEST = "mly_bundle_manifest"
+
+
+def create_user_session(user_access_token: str) -> requests.Session:
+    session = http.Session()
+    session.headers["Authorization"] = f"OAuth {user_access_token}"
+    return session
+
+
+def create_client_session(disable_logging: bool = False) -> requests.Session:
+    session = http.Session()
+    session.headers["Authorization"] = f"OAuth {MAPILLARY_CLIENT_TOKEN}"
+    if disable_logging:
+        session.disable_logging_request = True
+        session.disable_logging_response = True
+    return session
+
+
+def is_auth_error(resp: requests.Response) -> bool:
+    if resp.status_code in [401, 403]:
+        return True
+
+    if resp.status_code in [400]:
+        try:
+            error_body = resp.json()
+        except Exception:
+            error_body = {}
+
+        type = error_body.get("debug_info", {}).get("type")
+        if type in ["NotAuthorizedError"]:
+            return True
+
+    return False
+
+
+def extract_auth_error_message(resp: requests.Response) -> str:
+    assert is_auth_error(resp), "has to be an auth error"
+
+    try:
+        error_body = resp.json()
+    except Exception:
+        error_body = {}
+
+    # from Graph APIs
+    message = error_body.get("error", {}).get("message")
+    if message is not None:
+        return str(message)
+
+    # from upload service
+    message = error_body.get("debug_info", {}).get("message")
+    if message is not None:
+        return str(message)
+
+    return resp.text
+
+
+def get_upload_token(
+    client_session: requests.Session, email: str, password: str
+) -> requests.Response:
+    url = f"{MAPILLARY_GRAPH_API_ENDPOINT}/login"
+    json_data = {"email": email, "password": password, "locale": "en_US"}
+
+    resp = client_session.post(url, json=json_data, timeout=REQUESTS_TIMEOUT)
+    resp.raise_for_status()
+
+    return resp
+
+
+def fetch_organization(
+    user_session: requests.Session, organization_id: int | str
+) -> requests.Response:
+    url = f"{MAPILLARY_GRAPH_API_ENDPOINT}/{organization_id}"
+    params = {"fields": ",".join(["slug", "description", "name"])}
+
+    resp = user_session.get(url, params=params, timeout=REQUESTS_TIMEOUT)
+    resp.raise_for_status()
+
+    return resp
+
+
+def fetch_user_or_me(
+    user_session: requests.Session, user_id: int | str | None = None
+) -> requests.Response:
+    if user_id is None:
+        url = f"{MAPILLARY_GRAPH_API_ENDPOINT}/me"
+    else:
+        url = f"{MAPILLARY_GRAPH_API_ENDPOINT}/{user_id}"
+    params = {"fields": ",".join(["id", "username"])}
+
+    resp = user_session.get(url, params=params, timeout=REQUESTS_TIMEOUT)
+    resp.raise_for_status()
+
+    return resp
+
+
+ActionType = T.Literal[
+    "upload_started_upload", "upload_finished_upload", "upload_failed_upload"
+]
+
+
+def log_event(
+    client_session: requests.Session, action_type: ActionType, properties: dict
+) -> requests.Response:
+    url = f"{MAPILLARY_GRAPH_API_ENDPOINT}/logging"
+    json_data = {"action_type": action_type, "properties": properties}
+
+    resp = client_session.post(url, json=json_data, timeout=REQUESTS_TIMEOUT)
+    resp.raise_for_status()
+
+    return resp
+
+
+def finish_upload(
+    user_session: requests.Session,
+    file_handle: str,
+    cluster_filetype: ClusterFileType,
+    organization_id: int | str | None = None,
+) -> requests.Response:
+    url = f"{MAPILLARY_GRAPH_API_ENDPOINT}/finish_upload"
+    json_data: dict[str, str | int] = {
+        "file_handle": file_handle,
+        "file_type": cluster_filetype.value,
+    }
+    if organization_id is not None:
+        json_data["organization_id"] = organization_id
+
+    resp = user_session.post(url, json=json_data, timeout=REQUESTS_TIMEOUT)
+    resp.raise_for_status()
+
+    return resp
+
+
+def jsonify_response(resp: requests.Response) -> T.Any:
+    """
+    Convert the response to JSON, raising HTTPContentError if the response is not JSON.
+    """
+    try:
+        return resp.json()
+    except requests.JSONDecodeError as ex:
+        raise HTTPContentError("Invalid JSON response", resp) from ex