From aaccec5d18b82062b22b41aee7bbf608d463ffef Mon Sep 17 00:00:00 2001
From: MartiONE <alej.marti@gmail.com>
Date: Sun, 20 Jul 2025 18:12:48 +0000
Subject: [PATCH] Add support for the "legal" service endpoint

It provides legal status information for patents as documented in
chapter 3.5 of the OPS v3.2 documentation.
---
 CHANGELOG.md                 |  4 ++++
 epo_ops/api.py               | 34 ++++++++++++++++++++++++++++++++++
 tests/helpers/api_helpers.py |  5 +++++
 tests/test_api.py            |  3 +++
 4 files changed, 46 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bb069ea..bf199d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Change Log
 
+- Added support for the "legal" service endpoint, providing legal status
+  information for patents as documented in chapter 3.5 of the OPS v3.2
+  documentation. Thanks, @MartiONE.
+
 ## 4.1.0 (2024-01-25)
 
 - Configure HTTP client to use a network timeout of 10 seconds
diff --git a/epo_ops/api.py b/epo_ops/api.py
index 63f45a7..80eb76d 100644
--- a/epo_ops/api.py
+++ b/epo_ops/api.py
@@ -28,6 +28,7 @@ class Client(object):
 
     __family_path__ = "family"
     __images_path__ = "published-data/images"
+    __legal_path__ = "legal"
     __number_path__ = "number-service"
     __published_data_path__ = "published-data"
     __published_data_search_path__ = "published-data/search"
@@ -119,6 +120,39 @@ def image(
         """
         return self._image_request(path, range, document_format)
 
+    def legal(
+        self,
+        reference_type: str,
+        input: Union[Original, Docdb, Epodoc],
+    ) -> requests.Response:
+        """
+        Retrieval service for legal data.
+
+        Args:
+            reference_type (str): Any of "publication", "application", or "priority".
+            input (Original, Epodoc, or Docdb): The document number as an Original, Epodoc, or Docdb data object.
+        Returns:
+            requests.Response: a requests.Response object.
+
+        Examples:
+            >>> response = client.legal("publication", epo_ops.models.Epodoc("EP1000000"))
+            >>> response
+            <Response [200]>
+            >>> "ops:legal" in response.text
+            True
+
+        Note:
+            This service provides access to legal status information for patents
+            as documented in chapter 3.5 of the OPS v3.2 documentation.˜
+        """
+
+        return self._service_request(
+            dict(
+                service=self.__legal_path__,
+                reference_type=reference_type,
+                input=input,
+            )
+        )
     def number(
         self,
         reference_type: str,
diff --git a/tests/helpers/api_helpers.py b/tests/helpers/api_helpers.py
index 3a15a92..0728deb 100644
--- a/tests/helpers/api_helpers.py
+++ b/tests/helpers/api_helpers.py
@@ -48,6 +48,11 @@ def assert_image_success(client):
     assert_request_success(response)
     return response
 
+def assert_legal_success(client):
+    response = client.legal(*data)
+    assert_request_success(response)
+    assert "ops:legal" in response.text
+    return response
 
 def assert_published_data_success(client):
     response = client.published_data(*data)
diff --git a/tests/test_api.py b/tests/test_api.py
index 77456e1..1067723 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -12,6 +12,7 @@
     assert_family_legal_success,
     assert_family_success,
     assert_image_success,
+    assert_legal_success,
     assert_number_service_success,
     assert_published_data_search_success,
     assert_published_data_search_with_range_success,
@@ -44,6 +45,8 @@ def test_family_legal(all_clients):
 def test_image(all_clients):
     assert_image_success(all_clients)
 
+def test_legal(all_clients):
+    assert_legal_success(all_clients)
 
 def test_published_data(all_clients):
     assert_published_data_success(all_clients)