Refactors the Predicate class in the PredPatt module to introduce a new PredicateType enumeration for better type safety and clarity. Updates the documentation to reflect changes in predicate type handling, enhancing usability and consistency across the module. Modifies various components to utilize the new enumeration, ensuring a more robust implementation of predicate types.

Author: aaronstevenwhite

decomp/semantics/predpatt/core/__init__.py

@@ -7,18 +7,20 @@
 
 from .argument import Argument, sort_by_position
 from .options import PredPattOpts
-from .predicate import AMOD, APPOS, NORMAL, POSS, Predicate, argument_names, no_color
+from .predicate import (
+ Predicate,
+ PredicateType,
+ argument_names,
+ no_color,
+)
 from .token import Token
 
 
 __all__ = [
- "AMOD",
- "APPOS",
- "NORMAL",
- "POSS",
  "Argument",
  "PredPattOpts",
  "Predicate",
+ "PredicateType",
  "Token",
  "argument_names",
  "no_color",

decomp/semantics/predpatt/core/predicate.py

@@ -1,12 +1,41 @@
-"""Predicate class for representing extracted predicates.
-
-This module contains the Predicate class which represents predicates
-extracted from dependency parses, including their arguments and
-various predicate types (normal, possessive, appositive, adjectival).
+"""Predicate representation for semantic role labeling in PredPatt.
+
+This module defines the core predicate structures used in the PredPatt system
+for extracting and representing predicates from dependency parses. It handles
+various predicate types including verbal, possessive, appositional, and
+adjectival predicates.
+
+Key Components
+--------------
+:class:`Predicate`
+ Main class representing a predicate with its root token, arguments, and
+ predicate type. Supports different predicate types (normal, possessive,
+ appositive, adjectival).
+
+:class:`PredicateType`
+ Enumeration defining the four types of predicates that PredPatt can extract:
+ NORMAL, POSS, APPOS, and AMOD.
+
+:func:`argument_names`
+ Utility function to generate alphabetic names for arguments (?a, ?b, etc.)
+ for display and debugging purposes.
+
+:func:`sort_by_position`
+ Helper function to sort items by their position attribute, used for
+ ordering tokens and arguments.
+
+Predicate Types
+---------------
+The module defines a :class:`PredicateType` enum with four values:
+- ``PredicateType.NORMAL``: Standard verbal predicates
+- ``PredicateType.POSS``: Possessive predicates
+- ``PredicateType.APPOS``: Appositional predicates
+- ``PredicateType.AMOD``: Adjectival modifier predicates
 """
 
 from __future__ import annotations
 
+import enum
 from typing import TYPE_CHECKING
 
 from ..typing import T
@@ -23,11 +52,18 @@
 
  ColorFunc = Callable[[str, str], str]
 
-# Predicate type constants
-NORMAL = "normal"
-POSS = "poss"
-APPOS = "appos"
-AMOD = "amod"
+
+class PredicateType(str, enum.Enum):
+ """Enumeration of predicate types in PredPatt.
+ 
+ Inherits from str to maintain backward compatibility with string comparisons.
+ """
+ NORMAL = "normal" # Standard verbal predicates
+ POSS = "poss" # Possessive predicates
+ APPOS = "appos" # Appositional predicates
+ AMOD = "amod" # Adjectival modifier predicates
+
+
 
 
 def argument_names(args: list[T]) -> dict[T, str]:
@@ -84,8 +120,8 @@ class Predicate:
  The Universal Dependencies module to use (default: dep_v1).
  rules : list, optional
  List of rules that led to this predicate's extraction.
- type_ : str, optional
- Type of predicate (NORMAL, POSS, APPOS, or AMOD).
+ type_ : PredicateType, optional
+ Type of predicate (PredicateType.NORMAL, POSS, APPOS, or AMOD).
 
  Attributes
  ----------
@@ -99,7 +135,7 @@ class Predicate:
  The UD version module being used.
  arguments : list[Argument]
  List of arguments for this predicate.
- type : str
+ type : PredicateType
  Type of predicate.
  tokens : list[Token]
  List of tokens forming the predicate phrase.
@@ -110,7 +146,7 @@ def __init__(
  root: Token,
  ud: UDSchema = dep_v1,
  rules: list[Rule] | None = None,
- type_: str = NORMAL
+ type_: PredicateType = PredicateType.NORMAL
  ) -> None:
  """Initialize a Predicate."""
  self.root = root
@@ -149,7 +185,7 @@ def identifier(self) -> str:
  Identifier in format 'pred.{type}.{position}.{arg_positions}'.
  """
  arg_positions = '.'.join(str(a.position) for a in self.arguments)
- return f'pred.{self.type}.{self.position}.{arg_positions}'
+ return f'pred.{self.type.value}.{self.position}.{arg_positions}'
 
 
  def has_token(self, token: Token) -> bool:
@@ -229,7 +265,7 @@ def share_subj(self, other: Predicate) -> bool | None:
  """
  subj = self.subj()
  other_subj = other.subj()
- # use the exact same pattern as original to ensure identical behavior
+ # check both subjects exist before comparing positions
  if subj is None or other_subj is None:
  return None
  return subj.position == other_subj.position
@@ -266,7 +302,7 @@ def is_broken(self) -> bool | None:
  return True
  if any(not a.tokens for a in self.arguments):
  return True
- if self.type == POSS and len(self.arguments) != 2:
+ if self.type == PredicateType.POSS and len(self.arguments) != 2:
  return True
  return None
 
@@ -288,12 +324,12 @@ def _format_predicate(self, name: dict[Argument, str], c: ColorFunc = no_color)
  # collect tokens and arguments
  x = sort_by_position(self.tokens + self.arguments)
 
- if self.type == POSS:
+ if self.type == PredicateType.POSS:
  # possessive format: "?a 's ?b"
  assert len(self.arguments) == 2
- return f'{name[self.arguments[0]]} {self.type} {name[self.arguments[1]]}'
+ return f'{name[self.arguments[0]]} {self.type.value} {name[self.arguments[1]]}'
 
- elif self.type in {APPOS, AMOD}:
+ elif self.type in {PredicateType.APPOS, PredicateType.AMOD}:
  # appositive/adjectival format: "?a is/are [rest]"
  # find governor argument
  gov_arg = None
@@ -381,7 +417,7 @@ def format(
  name = argument_names(self.arguments)
  for arg in self.arguments:
  if (arg.isclausal() and arg.root.gov in self.tokens and
- self.type == NORMAL):
+ self.type == PredicateType.NORMAL):
  s = c('SOMETHING', 'yellow') + ' := ' + arg.phrase()
  else:
  s = c(arg.phrase(), 'green')

decomp/semantics/predpatt/extraction/engine.py

@@ -16,13 +16,14 @@
 
 if TYPE_CHECKING:
  from ..core.argument import Argument
- from ..core.predicate import Predicate
+ from ..core.predicate import Predicate, PredicateType
  from ..core.token import Token
  from ..parsing.udparse import DepTriple, UDParse
  from ..rules.base import Rule
+else:
+ # import at runtime to avoid circular imports
+ from ..core.predicate import PredicateType
 
-# predicate type constants
-NORMAL, POSS, APPOS, AMOD = ("normal", "poss", "appos", "amod")
 
 
 _PARSER = None
@@ -329,7 +330,7 @@ def identify_predicate_roots(self) -> list[Predicate]: # noqa: C901
 
  roots = {}
 
- def nominate(root: Token, rule: Rule, type_: str = NORMAL) -> Predicate:
+ def nominate(root: Token, rule: Rule, type_: PredicateType = PredicateType.NORMAL) -> Predicate:
  """Create or update a predicate instance with rules.
 
  Parameters
@@ -338,8 +339,8 @@ def nominate(root: Token, rule: Rule, type_: str = NORMAL) -> Predicate:
  The root token of the predicate.
  rule : Rule
  The rule that identified this predicate.
- type_ : str, optional
- The predicate type (NORMAL, POSS, APPOS, AMOD).
+ type_ : PredicateType, optional
+ The predicate type (PredicateType.NORMAL, POSS, APPOS, AMOD).
 
  Returns
  -------
@@ -360,17 +361,17 @@ def nominate(root: Token, rule: Rule, type_: str = NORMAL) -> Predicate:
 
  # Special predicate types (conditional on options)
  if self.options.resolve_appos and e.rel == self.ud.appos:
- nominate(e.dep, R.D(), APPOS)
+ nominate(e.dep, R.D(), PredicateType.APPOS)
 
  if self.options.resolve_poss and e.rel == self.ud.nmod_poss:
- nominate(e.dep, R.V(), POSS)
+ nominate(e.dep, R.V(), PredicateType.POSS)
 
  # If resolve amod flag is enabled, then the dependent of an amod
  # arc is a predicate (but only if the dependent is an
  # adjective). We also filter cases where ADJ modifies ADJ.
  if (self.options.resolve_amod and e.rel == self.ud.amod
  and e.dep.tag == postag.ADJ and e.gov.tag != postag.ADJ):
- nominate(e.dep, R.E(), AMOD)
+ nominate(e.dep, R.E(), PredicateType.AMOD)
 
  # Avoid 'dep' arcs, they are normally parse errors.
  # Note: we allow amod, poss, and appos predicates, even with a dep arc.
@@ -480,7 +481,7 @@ def argument_extract(self, predicate: Predicate) -> list[Argument]: # noqa: C90
  # Nominal modifiers (h1 rule) - exclude AMOD predicates
  elif (e.rel is not None and
  (e.rel.startswith(self.ud.nmod) or e.rel.startswith(self.ud.obl))
- and predicate.type != AMOD):
+ and predicate.type != PredicateType.AMOD):
  arguments.append(Argument(e.dep, self.ud, [R.H1()]))
 
  # Clausal arguments (k rule)
@@ -499,19 +500,19 @@ def argument_extract(self, predicate: Predicate) -> list[Argument]: # noqa: C90
  arguments.append(Argument(tr.dep, self.ud, [R.H2()]))
 
  # Special predicate type arguments
- if predicate.type == AMOD:
+ if predicate.type == PredicateType.AMOD:
  # i rule: AMOD predicates get their governor
  if predicate.root.gov is None:
  raise ValueError(f"AMOD predicate {predicate.root} must have a governor but gov is None")
  arguments.append(Argument(predicate.root.gov, self.ud, [R.I()]))
 
- elif predicate.type == APPOS:
+ elif predicate.type == PredicateType.APPOS:
  # j rule: APPOS predicates get their governor
  if predicate.root.gov is None:
  raise ValueError(f"APPOS predicate {predicate.root} must have a governor but gov is None")
  arguments.append(Argument(predicate.root.gov, self.ud, [R.J()]))
 
- elif predicate.type == POSS:
+ elif predicate.type == PredicateType.POSS:
  # w1 rule: POSS predicates get their governor
  if predicate.root.gov is None:
  raise ValueError(f"POSS predicate {predicate.root} must have a governor but gov is None")
@@ -698,7 +699,7 @@ def _argument_resolution(self, events: list[Predicate]) -> list[Predicate]: # n
  # Portuguese. Without it, miss a lot of arguments.
  for p in sort_by_position(events):
  if (not p.has_subj()
- and p.type == NORMAL
+ and p.type == PredicateType.NORMAL
  and p.root.gov_rel not in {self.ud.csubj, self.ud.csubjpass}
  and (p.root.gov_rel is None or not p.root.gov_rel.startswith(self.ud.acl))
  and not p.has_borrowed_arg()
@@ -793,7 +794,7 @@ def expand_coord(self, predicate: Predicate) -> list[Predicate]: # noqa: C901
  import itertools
 
  # Don't expand amod unless resolve_conj is enabled
- if not self.options.resolve_conj or predicate.type == AMOD:
+ if not self.options.resolve_conj or predicate.type == PredicateType.AMOD:
  predicate.arguments = [arg for arg in predicate.arguments if arg.tokens]
  if not predicate.arguments:
  return []
@@ -989,7 +990,7 @@ def _pred_phrase_extract(self, predicate: Predicate) -> None:
  from ..rules import predicate_rules as R # noqa: N812
 
  assert predicate.tokens == []
- if predicate.type == POSS:
+ if predicate.type == PredicateType.POSS:
  predicate.tokens = [predicate.root]
  return
  predicate.tokens.extend(self.subtree(predicate.root,
@@ -1178,7 +1179,7 @@ def _simple_arg(self, pred: Predicate, arg: Argument) -> bool:
  """
  from ..rules import predicate_rules as R # noqa: N812
 
- if pred.type == POSS:
+ if pred.type == PredicateType.POSS:
  return True
  if (pred.root.gov_rel in self.ud.ADJ_LIKE_MODS
  and pred.root.gov == arg.root):

decomp/semantics/predpatt/utils/linearization.py

@@ -18,13 +18,16 @@
  from collections.abc import Iterator
 
  from ..core.argument import Argument
- from ..core.predicate import Predicate
+ from ..core.predicate import Predicate, PredicateType
  from ..core.token import Token
  from ..extraction.engine import PredPattEngine
  from ..utils.ud_schema import DependencyRelationsV1, DependencyRelationsV2
 
  UDSchema = type[DependencyRelationsV1] | type[DependencyRelationsV2]
  TokenIterator = Iterator[tuple[int, str]]
+else:
+ # import at runtime to avoid circular imports
+ from ..core.predicate import PredicateType
 
 
 class HasPosition(Protocol):
@@ -41,11 +44,6 @@ class HasChildren(Protocol):
 
 T = TypeVar('T', bound=HasPosition)
 
-# Import constants directly to avoid circular imports
-NORMAL = "normal"
-POSS = "poss"
-AMOD = "amod"
-APPOS = "appos"
 
 # Regex patterns for parsing linearized forms
 RE_ARG_ENC = re.compile(r"\^\(\( | \)\)\$")
@@ -348,7 +346,7 @@ def flatten_pred(pred: Predicate, opt: LinearizedPPOpts, ud: UDSchema) -> tuple[
  args = pred.arguments
  child_preds = pred.children if hasattr(pred, 'children') else []
 
- if pred.type == POSS:
+ if pred.type == PredicateType.POSS:
  arg_i = 0
  # Only take the first two arguments into account.
  for y in sort_by_position(args[:2] + child_preds):
@@ -358,7 +356,7 @@ def flatten_pred(pred: Predicate, opt: LinearizedPPOpts, ud: UDSchema) -> tuple[
  arg_i += 1
  if arg_i == 1:
  # Generate the special ``poss'' predicate with label.
- poss = POSS + (PRED_HEADER if opt.distinguish_header
+ poss = PredicateType.POSS.value + (PRED_HEADER if opt.distinguish_header
  else PRED_SUF)
  ret += [phrase_and_enclose_arg(arg_y, opt), poss]
  else:
@@ -371,7 +369,7 @@ def flatten_pred(pred: Predicate, opt: LinearizedPPOpts, ud: UDSchema) -> tuple[
  ret.append(repr_y)
  return ' '.join(ret), False
 
- if pred.type in {AMOD, APPOS}:
+ if pred.type in {PredicateType.AMOD, PredicateType.APPOS}:
  # Special handling for `amod` and `appos` because the target
  # relation `is/are` deviates from the original word order.
  arg0 = None

decomp/semantics/predpatt/utils/visualization.py

@@ -96,15 +96,15 @@ def format_predicate(
  str
  Formatted predicate string with argument placeholders
  """
- from decomp.semantics.predpatt.core.predicate import AMOD, APPOS, POSS
+ from decomp.semantics.predpatt.core.predicate import PredicateType
 
  ret = []
  args = predicate.arguments
 
- if predicate.type == POSS:
- return ' '.join([name[args[0]], c(POSS, 'yellow'), name[args[1]]])
+ if predicate.type == PredicateType.POSS:
+ return ' '.join([name[args[0]], c(PredicateType.POSS.value, 'yellow'), name[args[1]]])
 
- if predicate.type in {AMOD, APPOS}:
+ if predicate.type in {PredicateType.AMOD, PredicateType.APPOS}:
  # Special handling for `amod` and `appos` because the target
  # relation `is/are` deviates from the original word order.
  arg0 = None
@@ -173,7 +173,7 @@ def format_predicate_instance(
  str
  Formatted predicate instance with arguments listed below
  """
- from decomp.semantics.predpatt.core.predicate import NORMAL
+ from decomp.semantics.predpatt.core.predicate import PredicateType
 
  lines = []
  name = argument_names(predicate.arguments)
@@ -190,7 +190,7 @@ def format_predicate_instance(
  # Format arguments
  for arg in predicate.arguments:
  if (arg.isclausal() and arg.root.gov in predicate.tokens and
- predicate.type == NORMAL):
+ predicate.type == PredicateType.NORMAL):
  s = c('SOMETHING', 'yellow') + ' := ' + arg.phrase()
  else:
  s = c(arg.phrase(), 'green')