temporal-normalization-spacy 2.0.2__tar.gz → 2.1.0__tar.gz

{temporal_normalization_spacy-2.0.2 → temporal_normalization_spacy-2.1.0}/MANIFEST.in

@@ -1,5 +1,5 @@
 include README.md
-include temporal_normalization/libs/temporal-normalization-2.0.jar
+include temporal_normalization/libs/temporal-normalization-2.1.0.jar
 
 recursive-include temporal_normalizer/commons *
 recursive-include temporal_normalizer/libs *

{temporal_normalization_spacy-2.0.2/temporal_normalization_spacy.egg-info → temporal_normalization_spacy-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: temporal_normalization_spacy
-Version: 2.0.2
+Version: 2.1.0
 Summary: A spaCy plugin for identifying and parsing historical data in Romanian texts
 Home-page: https://github.com/iliedorobat/timespan-normalization-spacy
 Author: Ilie Cristian Dorobat
@@ -18,6 +18,7 @@ Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: license-file
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -167,8 +168,17 @@ for entity in doc.ents:
 still be loaded on first run,** and this process may take a few seconds/tens of seconds.
 
 ### Importing Modules & Defining Constants
+
 ```python
-from temporal_normalization import console, TemporalExpression, start_process
+from pathlib import Path
+
+from temporal_normalization import (
+    close_conn,
+    console,
+    extract_temporal_expressions,
+    start_conn,
+    TemporalExpression,
+)
 
 LANG = "ro"
 TEXT_RO = (
@@ -183,8 +193,10 @@ TEXT_RO = (
 # Display a warning if the language of the text is not Romanian.
 console.lang_warning(TEXT_RO, target_lang=LANG)
 
-expressions: list[TemporalExpression] = []
-start_process(TEXT_RO, expressions)
+root_path = str(Path(__file__).resolve().parent.parent.parent)
+java_process, gateway = start_conn(root_path)
+expressions: list[TemporalExpression] = extract_temporal_expressions(gateway, TEXT_RO)
+close_conn(java_process, gateway)
 ```
 
 ### Accessing the Parsed Temporal Expressions

{temporal_normalization_spacy-2.0.2 → temporal_normalization_spacy-2.1.0}/README.md

@@ -143,8 +143,17 @@ for entity in doc.ents:
 still be loaded on first run,** and this process may take a few seconds/tens of seconds.
 
 ### Importing Modules & Defining Constants
+
 ```python
-from temporal_normalization import console, TemporalExpression, start_process
+from pathlib import Path
+
+from temporal_normalization import (
+    close_conn,
+    console,
+    extract_temporal_expressions,
+    start_conn,
+    TemporalExpression,
+)
 
 LANG = "ro"
 TEXT_RO = (
@@ -159,8 +168,10 @@ TEXT_RO = (
 # Display a warning if the language of the text is not Romanian.
 console.lang_warning(TEXT_RO, target_lang=LANG)
 
-expressions: list[TemporalExpression] = []
-start_process(TEXT_RO, expressions)
+root_path = str(Path(__file__).resolve().parent.parent.parent)
+java_process, gateway = start_conn(root_path)
+expressions: list[TemporalExpression] = extract_temporal_expressions(gateway, TEXT_RO)
+close_conn(java_process, gateway)
 ```
 
 ### Accessing the Parsed Temporal Expressions

{temporal_normalization_spacy-2.0.2 → temporal_normalization_spacy-2.1.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="temporal_normalization_spacy",
-    version="2.0.2",
+    version="2.1.0",
     author="Ilie Cristian Dorobat",
     description="A spaCy plugin for identifying and parsing historical data "
     "in Romanian texts",
@@ -12,7 +12,7 @@ setup(
     packages=find_packages(),
     include_package_data=True,
     package_data={
-        "temporal_normalization.libs": ["temporal-normalization-2.0.jar"],
+        "temporal_normalization.libs": ["temporal-normalization-2.1.0.jar"],
     },
     install_requires=["spacy>=3.0", "py4j", "langdetect"],
     classifiers=[

{temporal_normalization_spacy-2.0.2 → temporal_normalization_spacy-2.1.0}/temporal_normalization/commons/temporal_models.py

@@ -1,6 +1,6 @@
 import json
 
-from py4j.java_gateway import JavaObject
+from py4j.java_gateway import JavaObject, JavaGateway
 
 from temporal_normalization.commons.temporal_types import TemporalType
 
@@ -14,6 +14,7 @@ class TemporalExpression:
         is_valid (bool): A flag that specifies whether the text processed
             through timespan-normalization library is a temporal expression.
         input_value (str or None): The original temporal expression before processing.
+        prepared_value (str or None): The temporal expression after processing.
         time_series (list[TimeSeries]): The list of normalized temporal expressions.
         matches (list[str]): A unique list of matched values found in the normalized
             entities.
@@ -23,10 +24,12 @@ class TemporalExpression:
         serialize = java_object.serialize()
         json_obj = json.loads(serialize)
 
+        # fmt: off
         self.is_valid = TemporalExpression.is_valid_json(json_obj)
         self.input_value: str | None = json_obj["inputValue"] if self.is_valid else None
+        self.prepared_value: str | None = json_obj["preparedValue"] if self.is_valid else None
         self.time_series: list[TimeSeries] = [
-            TimeSeries(item) for item in json_obj["timeSeries"]
+            TimeSeries(item, self.input_value, self.prepared_value) for item in json_obj["timeSeries"]
         ] if self.is_valid else []
         self.matches: list[str] = list(
             set(
@@ -37,6 +40,7 @@ class TemporalExpression:
                 ]
             )
         )
+        # fmt: on
 
     def __str__(self):
         if self.input_value is None:
@@ -52,12 +56,40 @@ class TemporalExpression:
         return "inputValue" in json_obj and "timeSeries" in json_obj
 
 
+def extract_temporal_expressions(
+    gateway: JavaGateway, text: str
+) -> list[TemporalExpression]:
+    """
+    Extracts valid temporal expressions from the given text using the Java temporal
+    normalization gateway.
+
+    Args:
+        gateway (JavaGateway): Active Py4J gateway connected to the Java temporal
+            normalization process.
+        text (str): Input text from which to extract temporal expressions.
+
+    Returns:
+        list[TemporalExpression]: A list containing valid temporal expressions.
+    """
+
+    expressions: list[TemporalExpression] = []
+    java_object = gateway.jvm.ro.webdata.normalization.timespan.ro.TimeExpression(text)
+    temporal_expression = TemporalExpression(java_object)
+
+    if temporal_expression.is_valid:
+        expressions.append(temporal_expression)
+
+    return expressions
+
+
 class TimeSeries:
     """
     A data structure representing a temporal expression that has been normalized
     into a list of periods and temporal edges.
 
     Attributes:
+        input_value (str or None): The original temporal expression before processing.
+        prepared_value (str or None): The temporal expression after processing.
         edges (list[EdgeModel]): A list of temporal intervals represented as edges.
         periods (list[DBpediaModel]): A list of normalized DBpedia entities
             extracted from the expression.
@@ -65,7 +97,9 @@ class TimeSeries:
             entities.
     """
 
-    def __init__(self, data: dict):
+    def __init__(self, data: dict, input_value: str, prepared_value: str):
+        self.input_value = input_value
+        self.prepared_value = prepared_value
         self.edges: EdgeModel = EdgeModel(data["edges"]) if "edges" in data else None
         self.periods: list[DBpediaModel] = (
             [DBpediaModel(item) for item in data["periods"]]
@@ -80,10 +114,12 @@ class TimeSeries:
         return f"TimeSeries(edges={self.edges}, periods={self.periods})"
 
     def serialize(self, indent: str = ""):
+        # fmt: off
         return (
             f"{indent}Edges: {self.edges}\n"
             f"{indent}Periods: {self.periods}"
         )
+        # fmt: on
 
 
 class DBpediaModel:

{temporal_normalization_spacy-2.0.2 → temporal_normalization_spacy-2.1.0}/temporal_normalization/index.py

@@ -1,17 +1,26 @@
 import re
+import subprocess
+from pathlib import Path
 
+from py4j.java_gateway import JavaGateway
 from spacy import Language
 from spacy.tokens import Doc, Span
+from spacy.tokens._retokenize import Retokenizer
 from spacy.util import filter_spans
 
 from temporal_normalization import TimeSeries
-from temporal_normalization.commons.temporal_models import TemporalExpression
-from temporal_normalization.process.java_process import start_process
+from temporal_normalization.commons.temporal_models import (
+    extract_temporal_expressions,
+    TemporalExpression,
+)
+from temporal_normalization.process.java_process import start_conn, close_conn
 
 try:
+
     @Language.factory("temporal_normalization")
     def create_normalized_component(nlp, name):
         return TemporalNormalization(nlp, name)
+
 except AttributeError:
     # spaCy 2.x
     pass
@@ -21,7 +30,7 @@ class TemporalNormalization:
     """
     spaCy pipeline component for identifying and annotating temporal expressions in text.
 
-    This component calls the ``start_process`` method to extract temporal expressions, then
+    This component calls the ``start_conn`` method to extract temporal expressions, then
     aligns the matches with spaCy tokens using retokenization and sets a custom attribute
     containing associated time series metadata.
     """
@@ -40,6 +49,11 @@ class TemporalNormalization:
         Span.set_extension(TemporalNormalization.__FIELD, default=None, force=True)
         self.nlp = nlp
 
+        root_path = str(Path(__file__).resolve().parent.parent)
+        java_process, gateway = start_conn(root_path)
+        self.java_process: subprocess.Popen = java_process
+        self.gateway: JavaGateway = gateway
+
     def __call__(self, doc: Doc) -> Doc:
         """
         Apply the component to a spaCy Doc object.
@@ -54,14 +68,17 @@ class TemporalNormalization:
             Doc: The modified Doc object with temporal expressions processed.
         """
 
-        expressions: list[TemporalExpression] = []
-        start_process(doc.text, expressions)
+        expressions: list[TemporalExpression] = extract_temporal_expressions(
+            self.gateway, doc.text
+        )
         str_matches: list[str] = _prepare_str_patterns(expressions)
-
         _retokenize(doc, str_matches, expressions)
 
         return doc
 
+    def __del__(self):
+        close_conn(self.java_process, self.gateway)
+
 
 def _prepare_str_patterns(expressions: list[TemporalExpression]) -> list[str]:
     """
@@ -101,7 +118,8 @@ def _retokenize(
                                                 each with time series metadata.
     """
 
-    regex_matches: list[str] = [rf"{item}" for item in str_matches]
+    # TODO: WIP
+    regex_matches: list[str] = [rf"{re.escape(item)}" for item in str_matches]
     pattern = f"({'|'.join(regex_matches)})"
     matches = (
         list(re.finditer(pattern, doc.text, re.IGNORECASE))
@@ -126,6 +144,7 @@ def _retokenize(
                 if token.idx + len(token.text) == end_char:
                     end_token = token.i
 
+            # fmt: off
             if start_token is not None and end_token is not None:
                 # use exact token boundaries to create a custom `Span` for well-defined
                 # time expressions with known character offsets.
@@ -144,6 +163,8 @@ def _retokenize(
                         matched_ts = [ts for ts in time_series if _is_substring(entity.text, ts.matches)]
                         _retokenize_entity(doc, matched_ts, entity, True, retokenized_entities, retokenizer)
 
+            # fmt: on
+
 
 def _retokenize_entity(
     doc: Doc,
@@ -151,7 +172,7 @@ def _retokenize_entity(
     entity: Span,
     existed_entity: bool,
     retokenized_entities: list[Span],
-    retokenizer: Doc.retokenize,
+    retokenizer: Retokenizer,
 ) -> None:
     """
     Retokenizes and enriches a temporal entity span with matched time series data.
@@ -173,6 +194,8 @@ def _retokenize_entity(
     _update_doc_ents(doc, entity)
     _merge_entity(doc, entity, retokenized_entities, retokenizer)
 
+    return None
+
 
 def _assign_time_series(
     matched_ts: list[TimeSeries], entity: Span, existed_entity: bool
@@ -214,7 +237,7 @@ def _merge_entity(
     doc: Doc,
     entity: Span,
     retokenized_entities: list[Span],
-    retokenizer: Doc.retokenize,
+    retokenizer: Retokenizer,
 ) -> None:
     """
     Merges a custom entity span into the spaCy Doc if it is not already part of
@@ -223,7 +246,7 @@ def _merge_entity(
     Args:
         entity (Span): The named entity to enrich.
         retokenized_entities (list): Accumulator for entities that require retokenization.
-        retokenizer (Doc.retokenize): The spaCy retokenizer context.
+        retokenizer (Retokenizer): The spaCy retokenizer context.
     """
 
     if entity not in doc.ents:

temporal_normalization_spacy-2.1.0/temporal_normalization/process/java_process.py

@@ -0,0 +1,129 @@
+import re
+import shutil
+import subprocess
+
+from py4j.java_gateway import JavaGateway
+from py4j.protocol import Py4JNetworkError
+
+from temporal_normalization.commons.print_utils import console
+
+
+def start_conn(root_path: str) -> tuple[subprocess.Popen, JavaGateway]:
+    """
+    Starts the Java temporal normalization process and establishes a Py4J gateway connection.
+
+    Args:
+        root_path (str): The root directory of the project.
+
+    Returns:
+        tuple[subprocess.Popen, JavaGateway]:
+            - The subprocess.Popen object representing the running Java process.
+            - The JavaGateway object representing the active Py4J connection.
+
+    Note:
+        - Requires Java 11 or higher to be installed and accessible in the system PATH.
+        - Requires `temporal-normalization-2.1.0.jar` to be present in the `libs` directory.
+        - The caller is responsible for closing the gateway and terminating the Java process
+            after usage to avoid orphaned processes.
+    """
+
+    check_java_version()
+
+    jar_path = (
+        f"{root_path}/temporal_normalization/libs/temporal-normalization-2.1.0.jar"
+    )
+
+    java_process = subprocess.Popen(
+        ["java", "-jar", jar_path, "--python"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+    for line in java_process.stdout:
+        if "Gateway Server Started." in line:
+            print(line.strip())
+            break
+
+    gateway = JavaGateway()
+    print("Python connection established.")
+
+    return java_process, gateway
+
+
+def close_conn(java_process: subprocess.Popen, gateway: JavaGateway) -> None:
+    """
+    Closes the active connection between Python and the Java process started via Py4J.
+
+    This function ensures a proper shutdown sequence:
+    1. Attempts to gracefully shut down the Py4J gateway connection.
+       - If the Java process is already closed, a Py4JNetworkError is caught and logged.
+    2. Terminates the underlying Java process.
+    3. Prints status messages for debugging/confirmation.
+
+    Args:
+        java_process (subprocess.Popen): The Java process launched with subprocess.
+        gateway (JavaGateway): The active Py4J gateway connection.
+
+    Notes:
+        - Call this function once you have finished all interactions with the Java process.
+        - It is safe to call even if the Java process has already exited.
+    """
+
+    try:
+        # Proper way to shut down Py4J
+        gateway.shutdown()
+        print("Python connection closed.")
+    except Py4JNetworkError:
+        print("Java process already shut down.")
+
+    # Terminate Java process
+    java_process.terminate()
+    print("Java server is shutting down...")
+
+
+def check_java_version() -> None:
+    """
+    Verifies that Java is installed and meets the minimum required version.
+
+    This function checks for the presence of the Java executable in the system PATH,
+    runs ``java -version``, and ensures that the version is at least 11. If Java is not
+    installed or the version is too low, it logs an error using ``console.error``.
+
+    Raises:
+        Logs error messages, but does not raise exceptions directly.
+    """
+
+    min_version = 11
+    java_path = shutil.which("java")
+
+    try:
+        if java_path:
+            # Run the command to check the Java version
+            result = subprocess.run(
+                [java_path, "-version"], capture_output=True, text=True
+            )
+
+            # Print the version information (Java version is printed to stderr)
+            if result.returncode == 0:
+                version_output = result.stderr
+                match = re.search(r'version "(\d+\.\d+)', version_output)
+
+                if match:
+                    crr_version = float(match.group(1))
+                    if crr_version < min_version:
+                        console.error(
+                            f"Java {crr_version} is installed, but version {min_version} is required."  # noqa 501
+                        )
+                else:
+                    console.error("Could not extract Java version.")
+            else:
+                console.error("Error occurred while checking the version.")
+        else:
+            console.error("Java not found.")
+    except Exception as e:
+        console.error(e.__str__())
+
+
+if __name__ == "__main__":
+    pass

{temporal_normalization_spacy-2.0.2 → temporal_normalization_spacy-2.1.0/temporal_normalization_spacy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: temporal_normalization_spacy
-Version: 2.0.2
+Version: 2.1.0
 Summary: A spaCy plugin for identifying and parsing historical data in Romanian texts
 Home-page: https://github.com/iliedorobat/timespan-normalization-spacy
 Author: Ilie Cristian Dorobat
@@ -18,6 +18,7 @@ Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: license-file
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -167,8 +168,17 @@ for entity in doc.ents:
 still be loaded on first run,** and this process may take a few seconds/tens of seconds.
 
 ### Importing Modules & Defining Constants
+
 ```python
-from temporal_normalization import console, TemporalExpression, start_process
+from pathlib import Path
+
+from temporal_normalization import (
+    close_conn,
+    console,
+    extract_temporal_expressions,
+    start_conn,
+    TemporalExpression,
+)
 
 LANG = "ro"
 TEXT_RO = (
@@ -183,8 +193,10 @@ TEXT_RO = (
 # Display a warning if the language of the text is not Romanian.
 console.lang_warning(TEXT_RO, target_lang=LANG)
 
-expressions: list[TemporalExpression] = []
-start_process(TEXT_RO, expressions)
+root_path = str(Path(__file__).resolve().parent.parent.parent)
+java_process, gateway = start_conn(root_path)
+expressions: list[TemporalExpression] = extract_temporal_expressions(gateway, TEXT_RO)
+close_conn(java_process, gateway)
 ```
 
 ### Accessing the Parsed Temporal Expressions

{temporal_normalization_spacy-2.0.2 → temporal_normalization_spacy-2.1.0}/temporal_normalization_spacy.egg-info/SOURCES.txt

@@ -8,7 +8,7 @@ temporal_normalization/commons/__init__.py
 temporal_normalization/commons/print_utils.py
 temporal_normalization/commons/temporal_models.py
 temporal_normalization/commons/temporal_types.py
-temporal_normalization/libs/temporal-normalization-2.0.jar
+temporal_normalization/libs/temporal-normalization-2.1.0.jar
 temporal_normalization/process/__init__.py
 temporal_normalization/process/java_process.py
 temporal_normalization_spacy.egg-info/PKG-INFO

temporal_normalization_spacy-2.0.2/temporal_normalization/process/java_process.py

@@ -1,153 +0,0 @@
-import os
-import re
-import shutil
-import subprocess
-
-from py4j.java_gateway import JavaGateway
-from py4j.protocol import Py4JNetworkError
-
-from temporal_normalization.commons.print_utils import console
-from temporal_normalization.commons.temporal_models import TemporalExpression
-
-
-def start_process(text: str, expressions: list[TemporalExpression]):
-    """
-    Launches the Java-based temporal normalization process and populates a list
-    of temporal expressions extracted from the input text.
-
-    This function starts a Java subprocess that hosts the temporal-normalization
-    server via Py4J. Once the gateway is connected, it sends the input text for
-    processing, retrieves the temporal expressions, and then shuts down both
-    the Python and Java sides of the connection.
-
-    Args:
-        text (str): The input text to be analyzed for temporal expressions.
-        expressions (list[TemporalExpression]): A list to be populated with
-            extracted temporal expressions.
-
-    Example:
-        >>> expressions: list[TemporalExpression] = []
-        >>> start_process("Sec al II-lea a.ch. a fost o perioadă de mari schimbări.", expressions)
-        >>> # ... use the list of normalized temporal expressions.
-
-    Note:
-        Requires `temporal-normalization-2.0.jar` to be present in the `libs` directory.
-        Also requires Java 11 or higher to be installed and accessible in the system PATH.
-    """
-
-    check_java_version()
-
-    jar_path = os.path.join(
-        os.path.dirname(__file__), "../libs/temporal-normalization-2.0.jar"
-    )
-
-    java_process = subprocess.Popen(
-        ["java", "-jar", jar_path, "--python"],
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-        text=True,
-    )
-
-    for line in java_process.stdout:
-        if "Gateway Server Started..." in line:
-            print(line.strip())
-            break
-
-    gateway = gateway_conn(text, expressions)
-
-    try:
-        # Proper way to shut down Py4J
-        gateway.shutdown()
-        print("Python connection closed.")
-    except Py4JNetworkError:
-        print("Java process already shut down.")
-
-    # Terminate Java process
-    java_process.terminate()
-    print("Java server is shutting down...")
-
-
-def gateway_conn(text: str, expressions: list[TemporalExpression]) -> JavaGateway:
-    """
-    Establishes a connection to the Java Py4J gateway and initializes the
-    temporal expression extraction.
-
-    It creates an instance of the Java class ``TimeExpression``, wraps it in
-    a Python ``TemporalExpression``, and appends it to the given list if valid.
-
-    Args:
-        text (str): The input text to analyze.
-        expressions (list[TemporalExpression]): A list to store extracted expressions.
-
-    Returns:
-        JavaGateway: The Py4J JavaGateway object used to manage the connection.
-
-    Example:
-        >>> from py4j.java_gateway import JavaGateway
-        >>> expressions: list[TemporalExpression] = []
-        >>> gateway = gateway_conn("Sec al II-lea a.ch. a fost o perioadă de mari schimbări.", expressions)
-        >>> # ... use the list of normalized temporal expressions.
-        >>> gateway.shutdown()
-
-    Note:
-        Assumes that a Py4J-compatible Java process is already running and exposing
-        the `ro.webdata.normalization.timespan.ro.TimeExpression` class.
-    """
-
-    gateway = JavaGateway()
-    print("Python connection established.")
-
-    java_object = gateway.jvm.ro.webdata.normalization.timespan.ro.TimeExpression(text)
-    time_expression = TemporalExpression(java_object)
-
-    if time_expression.is_valid:
-        expressions.append(time_expression)
-
-    return gateway
-
-
-def check_java_version():
-    """
-    Verifies that Java is installed and meets the minimum required version.
-
-    This function checks for the presence of the Java executable in the system PATH,
-    runs ``java -version``, and ensures that the version is at least 11. If Java is not
-    installed or the version is too low, it logs an error using ``console.error``.
-
-    Raises:
-        Logs error messages, but does not raise exceptions directly.
-    """
-
-    min_version = 11
-    java_path = shutil.which("java")
-
-    try:
-        if java_path:
-            # Run the command to check the Java version
-            result = subprocess.run(
-                [java_path, "-version"], capture_output=True, text=True
-            )
-
-            # Print the version information (Java version is printed to stderr)
-            if result.returncode == 0:
-                version_output = result.stderr
-                match = re.search(r'version "(\d+\.\d+)', version_output)
-
-                if match:
-                    crr_version = float(match.group(1))
-                    if crr_version < min_version:
-                        console.error(
-                            f"Java {crr_version} is installed, but version {min_version} is required."  # noqa 501
-                        )
-                else:
-                    console.error("Could not extract Java version.")
-            else:
-                console.error("Error occurred while checking the version.")
-        else:
-            console.error("Java not found.")
-    except Exception as e:
-        console.error(e.__str__())
-
-
-if __name__ == "__main__":
-    pass