PyObjC DataDetection Framework

Warnings

• breaking PyObjC has periodically dropped support for older Python versions. PyObjC 12.0 dropped Python 3.9, and PyObjC 11.0 dropped Python 3.8. Ensure your Python environment meets the `>=3.10` requirement.
  Fix: Upgrade Python to 3.10 or later, or use an older PyObjC version compatible with your Python environment.
• breaking Changes in `__init__` and `__new__` behavior can break custom class implementations. PyObjC 10.3 initially removed `__init__` support when `__new__` was provided by PyObjC, which was partially reverted in 10.3.1 to allow `__init__` when the user implements `__new__`.
  Fix: Carefully review custom PyObjC class implementations, especially those overriding `__new__`, to ensure `__init__` is called correctly. Refer to the PyObjC 10.3 and 10.3.1 release notes for details.
• gotcha PyObjC 11.1 aligned its `alloc`/`init` behavior with Clang's Automatic Reference Counting (ARC) documentation. This means methods in the 'init' family now correctly steal a reference to `self` and return a new one. This can subtly change object lifecycle behavior and may require adjustments in specific patterns of object creation and retention.
  Fix: Understand ARC principles when working with PyObjC `init` methods, especially when manually managing object references or subclassing Objective-C classes in Python. Most common usage patterns are unaffected.
• gotcha PyObjC's support for Python 3.13's experimental free-threading (PEP 703) is not yet fully stable or recommended. While significant changes were made in PyObjC 11.0 for experimental support, caution is advised for production use.
  Fix: Avoid using PyObjC in a free-threaded Python 3.13 environment unless absolutely necessary and after thorough testing. Stick to regular Python threading models for stability.
• gotcha The `os.fspath()` function will not work with `NSURL` or `CFURLRef` objects that refer to local filesystem paths in PyObjC versions prior to 10.1, raising a `TypeError` for other URLs. This was fixed in PyObjC 10.1.
  Fix: Upgrade to PyObjC 10.1 or later to enable `os.fspath()` compatibility with Cocoa URLs for local filesystem paths. For older versions, convert URLs to Python strings manually using appropriate PyObjC wrappers.

Install

• pip install pyobjc-framework-datadetection Install `pyobjc-framework-datadetection`

Imports

• DDScanner

  from DataDetection import DDScanner

• DDConditionIsPhoneNumber

  from DataDetection import DDConditionIsPhoneNumber

• DDScannerResult

  from DataDetection import DDScannerResult

• NSString

  from Foundation import NSString

  While Python strings often bridge automatically, explicit NSString can sometimes be beneficial for clarity or specific API requirements, especially for methods expecting `NSString`.

Quickstart

This quickstart demonstrates how to use `DDScanner` to detect phone numbers, dates, and email addresses in a given string. It combines multiple detection conditions using the bitwise OR operator (`|`) and then iterates through the `DDScannerResult` objects to extract matched strings and their specific values.

from DataDetection import DDScanner, DDConditionIsPhoneNumber, DDConditionIsDate, DDConditionIsEmail
from Foundation import NSString # Can be used for explicit Objective-C string creation, though Python strings often bridge automatically

# Constants for content types (exposed directly from the DataDetection module)
PHONE_NUMBER = DDConditionIsPhoneNumber
DATE = DDConditionIsDate
EMAIL = DDConditionIsEmail

text = "My phone number is 123-456-7890 and the date is January 15, 2024. Email me at test@example.com."

# Create a scanner for phone numbers, dates, and emails
# The | operator is used to combine multiple conditions
scanner = DDScanner.scannerWithContentTypes_(PHONE_NUMBER | DATE | EMAIL)

# Scan the string
# PyObjC automatically converts Python strings to NSString for Objective-C APIs
results = scanner.scanString_(text)

print(f"Scanning text: '{text}'")
print("Found results:")
for result in results:
    print(f"  Matched String: '{result.matchedString()}'")
    print(f"    Type (raw): {result.type()}") # Raw Objective-C type constant
    # The 'value()' method returns an Objective-C object specific to the detected type
    if result.type() == PHONE_NUMBER:
        print(f"    Value (Phone Number): {result.value()}")
    elif result.type() == DATE:
        print(f"    Value (Date): {result.value()}")
    elif result.type() == EMAIL:
        print(f"    Value (Email): {result.value()}")