pystylometry 0.1.0__py3-none-any.whl

pystylometry/__init__.py

@@ -0,0 +1,206 @@
+"""
+pystylometry - Comprehensive Python package for stylometric analysis.
+
+A modular package for text analysis with lexical, readability, syntactic,
+authorship, and n-gram metrics.
+
+Installation:
+    pip install pystylometry                    # Core (lexical only)
+    pip install pystylometry[readability]       # With readability metrics
+    pip install pystylometry[syntactic]         # With syntactic analysis
+    pip install pystylometry[authorship]        # With authorship attribution
+    pip install pystylometry[all]               # Everything
+
+Usage:
+    # Direct module imports
+    from pystylometry.lexical import compute_mtld, compute_yule
+    from pystylometry.readability import compute_flesch
+    from pystylometry.syntactic import compute_pos_ratios
+    from pystylometry.authorship import compute_burrows_delta
+
+    # Or use the unified analyze() function
+    from pystylometry import analyze
+
+    results = analyze(text, lexical=True, readability=True)
+    print(results.lexical['mtld'].mtld_average)
+    print(results.readability['flesch'].reading_ease)
+"""
+
+from ._types import AnalysisResult
+
+# Version
+__version__ = "0.1.0"
+
+# Core exports - always available
+from . import lexical
+
+# Optional exports - may raise ImportError if dependencies not installed
+try:
+    from . import readability  # noqa: F401
+
+    _READABILITY_AVAILABLE = True
+except ImportError:
+    _READABILITY_AVAILABLE = False
+
+try:
+    from . import syntactic  # noqa: F401
+
+    _SYNTACTIC_AVAILABLE = True
+except ImportError:
+    _SYNTACTIC_AVAILABLE = False
+
+# Authorship and ngrams use only stdlib (no external dependencies)
+from . import (
+    authorship,  # noqa: F401
+    ngrams,  # noqa: F401
+)
+
+_AUTHORSHIP_AVAILABLE = True
+_NGRAMS_AVAILABLE = True
+
+
+def analyze(
+    text: str,
+    lexical_metrics: bool = True,
+    readability_metrics: bool = False,
+    syntactic_metrics: bool = False,
+    authorship_metrics: bool = False,
+    ngram_metrics: bool = False,
+) -> AnalysisResult:
+    """
+    Unified interface to compute multiple stylometric metrics at once.
+
+    This is a convenience function that calls all requested metric computations
+    and returns a unified result object. Only computes metrics for which the
+    required optional dependencies are installed.
+
+    Args:
+        text: Input text to analyze
+        lexical_metrics: Compute lexical diversity metrics (default: True)
+        readability_metrics: Compute readability metrics (default: False)
+        syntactic_metrics: Compute syntactic metrics (default: False)
+        authorship_metrics: Compute authorship metrics (default: False)
+            Note: Authorship metrics typically require multiple texts for comparison.
+            This will compute features that can be used for authorship analysis.
+        ngram_metrics: Compute n-gram entropy metrics (default: False)
+
+    Returns:
+        AnalysisResult with requested metrics in nested dictionaries
+
+    Raises:
+        ImportError: If requested analysis requires uninstalled dependencies
+
+    Example:
+        >>> from pystylometry import analyze
+        >>> results = analyze(text, lexical=True, readability=True)
+        >>> print(results.lexical['mtld'].mtld_average)
+        >>> print(results.readability['flesch'].reading_ease)
+
+    Example with all metrics:
+        >>> results = analyze(text, lexical=True, readability=True,
+        ...                   syntactic=True, ngrams=True)
+        >>> print(f"MTLD: {results.lexical['mtld'].mtld_average:.2f}")
+        >>> print(f"Flesch: {results.readability['flesch'].reading_ease:.1f}")
+        >>> print(f"Noun ratio: {results.syntactic['pos'].noun_ratio:.3f}")
+        >>> print(f"Bigram entropy: {results.ngrams['word_bigram'].entropy:.3f}")
+    """
+    result = AnalysisResult(metadata={"text_length": len(text)})
+
+    # Lexical metrics (always available)
+    if lexical_metrics:
+        result.lexical = {}
+        # TODO: Add when stylometry-ttr is integrated
+        # result.lexical['ttr'] = lexical.compute_ttr(text)
+        result.lexical["mtld"] = lexical.compute_mtld(text)
+        result.lexical["yule"] = lexical.compute_yule(text)
+        result.lexical["hapax"] = lexical.compute_hapax_ratios(text)
+
+    # Readability metrics (optional dependency)
+    if readability_metrics:
+        if not _READABILITY_AVAILABLE:
+            raise ImportError(
+                "Readability metrics require optional dependencies. "
+                "Install with: pip install pystylometry[readability]"
+            )
+        # Import locally to avoid name conflict
+        from . import readability as readability_module
+
+        result.readability = {}
+        result.readability["flesch"] = readability_module.compute_flesch(text)
+        result.readability["smog"] = readability_module.compute_smog(text)
+        result.readability["gunning_fog"] = readability_module.compute_gunning_fog(text)
+        result.readability["coleman_liau"] = readability_module.compute_coleman_liau(text)
+        result.readability["ari"] = readability_module.compute_ari(text)
+
+    # Syntactic metrics (optional dependency)
+    if syntactic_metrics:
+        if not _SYNTACTIC_AVAILABLE:
+            raise ImportError(
+                "Syntactic metrics require optional dependencies. "
+                "Install with: pip install pystylometry[syntactic]"
+            )
+        # Import locally to avoid name conflict
+        from . import syntactic as syntactic_module
+
+        result.syntactic = {}
+        result.syntactic["pos"] = syntactic_module.compute_pos_ratios(text)
+        result.syntactic["sentence_stats"] = syntactic_module.compute_sentence_stats(text)
+
+    # Authorship metrics (uses stdlib only)
+    # Note: These are typically used for comparison between texts
+    # Here we just note that they're available but don't compute them
+    # since they require multiple texts as input
+    if authorship_metrics:
+        result.authorship = {
+            "note": "Authorship metrics require multiple texts for comparison. "
+            "Use pystylometry.authorship.compute_burrows_delta(text1, text2) directly."
+        }
+
+    # N-gram metrics (uses stdlib only)
+    if ngram_metrics:
+        result.ngrams = {}
+        result.ngrams["character_bigram"] = ngrams.compute_character_bigram_entropy(text)
+        result.ngrams["word_bigram"] = ngrams.compute_word_bigram_entropy(text)
+
+    return result
+
+
+# Convenient access to availability flags
+def get_available_modules() -> dict[str, bool]:
+    """
+    Get dictionary of available optional modules.
+
+    Returns:
+        Dictionary mapping module names to availability status
+
+    Example:
+        >>> from pystylometry import get_available_modules
+        >>> available = get_available_modules()
+        >>> if available['readability']:
+        ...     from pystylometry.readability import compute_flesch
+    """
+    return {
+        "lexical": True,  # Always available
+        "readability": _READABILITY_AVAILABLE,
+        "syntactic": _SYNTACTIC_AVAILABLE,
+        "authorship": _AUTHORSHIP_AVAILABLE,
+        "ngrams": _NGRAMS_AVAILABLE,
+    }
+
+
+__all__ = [
+    "__version__",
+    "analyze",
+    "get_available_modules",
+    "lexical",
+]
+
+# Conditionally add to __all__ based on availability
+if _READABILITY_AVAILABLE:
+    __all__.append("readability")
+if _SYNTACTIC_AVAILABLE:
+    __all__.append("syntactic")
+if _AUTHORSHIP_AVAILABLE:
+    __all__.append("authorship")
+if _NGRAMS_AVAILABLE:
+    __all__.append("ngrams")

pystylometry/_types.py

@@ -0,0 +1,172 @@
+"""Result dataclasses for all pystylometry metrics."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+# ===== Lexical Results =====
+
+
+@dataclass
+class MTLDResult:
+    """Result from MTLD (Measure of Textual Lexical Diversity) computation."""
+
+    mtld_forward: float
+    mtld_backward: float
+    mtld_average: float
+    metadata: dict[str, Any]
+
+
+@dataclass
+class YuleResult:
+    """Result from Yule's K and I computation."""
+
+    yule_k: float
+    yule_i: float
+    metadata: dict[str, Any]
+
+
+@dataclass
+class HapaxResult:
+    """Result from Hapax Legomena analysis."""
+
+    hapax_count: int
+    hapax_ratio: float
+    dis_hapax_count: int
+    dis_hapax_ratio: float
+    sichel_s: float
+    honore_r: float
+    metadata: dict[str, Any]
+
+
+# ===== Readability Results =====
+
+
+@dataclass
+class FleschResult:
+    """Result from Flesch Reading Ease and Flesch-Kincaid Grade computation."""
+
+    reading_ease: float
+    grade_level: float
+    difficulty: str  # "Very Easy", "Easy", "Fairly Easy", "Standard", etc.
+    metadata: dict[str, Any]
+
+
+@dataclass
+class SMOGResult:
+    """Result from SMOG Index computation."""
+
+    smog_index: float
+    grade_level: int
+    metadata: dict[str, Any]
+
+
+@dataclass
+class GunningFogResult:
+    """Result from Gunning Fog Index computation."""
+
+    fog_index: float
+    grade_level: int
+    metadata: dict[str, Any]
+
+
+@dataclass
+class ColemanLiauResult:
+    """Result from Coleman-Liau Index computation."""
+
+    cli_index: float
+    grade_level: int
+    metadata: dict[str, Any]
+
+
+@dataclass
+class ARIResult:
+    """Result from Automated Readability Index computation."""
+
+    ari_score: float
+    grade_level: int
+    age_range: str
+    metadata: dict[str, Any]
+
+
+# ===== Syntactic Results =====
+
+
+@dataclass
+class POSResult:
+    """Result from Part-of-Speech ratio analysis."""
+
+    noun_ratio: float
+    verb_ratio: float
+    adjective_ratio: float
+    adverb_ratio: float
+    noun_verb_ratio: float
+    adjective_noun_ratio: float
+    lexical_density: float
+    function_word_ratio: float
+    metadata: dict[str, Any]
+
+
+@dataclass
+class SentenceStatsResult:
+    """Result from sentence-level statistics."""
+
+    mean_sentence_length: float
+    sentence_length_std: float
+    sentence_length_range: int
+    min_sentence_length: int
+    max_sentence_length: int
+    sentence_count: int
+    metadata: dict[str, Any]
+
+
+# ===== Authorship Results =====
+
+
+@dataclass
+class BurrowsDeltaResult:
+    """Result from Burrows' Delta computation."""
+
+    delta_score: float
+    distance_type: str  # "burrows", "cosine", "eder"
+    mfw_count: int
+    metadata: dict[str, Any]
+
+
+@dataclass
+class ZetaResult:
+    """Result from Zeta score computation."""
+
+    zeta_score: float
+    marker_words: list[str]
+    anti_marker_words: list[str]
+    metadata: dict[str, Any]
+
+
+# ===== N-gram Results =====
+
+
+@dataclass
+class EntropyResult:
+    """Result from n-gram entropy computation."""
+
+    entropy: float
+    perplexity: float
+    ngram_type: str  # "character_bigram", "word_bigram", "word_trigram"
+    metadata: dict[str, Any]
+
+
+# ===== Unified Analysis Result =====
+
+
+@dataclass
+class AnalysisResult:
+    """Unified result from comprehensive stylometric analysis."""
+
+    lexical: dict[str, Any] | None = None
+    readability: dict[str, Any] | None = None
+    syntactic: dict[str, Any] | None = None
+    authorship: dict[str, Any] | None = None
+    ngrams: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None

pystylometry/_utils.py

@@ -0,0 +1,197 @@
+"""Shared utility functions for pystylometry."""
+
+from __future__ import annotations
+
+import re
+
+from .tokenizer import Tokenizer
+
+# ===== Convenience Functions =====
+
+# Default tokenizer instance for backward compatibility
+_default_tokenizer = Tokenizer(
+    lowercase=False,
+    strip_punctuation=False,
+)
+
+
+def tokenize(text: str) -> list[str]:
+    """
+    Simple tokenization using default settings.
+
+    Convenience function that maintains backward compatibility
+    with the original simple tokenizer interface.
+
+    Args:
+        text: Input text to tokenize
+
+    Returns:
+        List of tokens
+
+    Example:
+        >>> tokens = tokenize("Hello, world!")
+        >>> print(tokens)
+        ['Hello', ',', 'world', '!']
+    """
+    return _default_tokenizer.tokenize(text)
+
+
+def advanced_tokenize(
+    text: str,
+    lowercase: bool = True,
+    strip_punctuation: bool = True,
+    expand_contractions: bool = False,
+) -> list[str]:
+    """
+    Tokenization with commonly-used advanced options.
+
+    Args:
+        text: Input text to tokenize
+        lowercase: Convert to lowercase (default: True)
+        strip_punctuation: Remove punctuation tokens (default: True)
+        expand_contractions: Expand contractions (default: False)
+
+    Returns:
+        List of tokens
+
+    Example:
+        >>> tokens = advanced_tokenize("Hello, world! It's nice.", lowercase=True)
+        >>> print(tokens)
+        ['hello', 'world', "it's", 'nice']
+    """
+    tokenizer = Tokenizer(
+        lowercase=lowercase,
+        strip_punctuation=strip_punctuation,
+        expand_contractions=expand_contractions,
+    )
+    return tokenizer.tokenize(text)
+
+
+# ===== Sentence Splitting =====
+
+# Common abbreviations that shouldn't trigger sentence boundaries
+_ABBREVIATIONS = {
+    "mr.",
+    "mrs.",
+    "ms.",
+    "dr.",
+    "prof.",
+    "sr.",
+    "jr.",
+    "st.",
+    "vs.",
+    "etc.",
+    "e.g.",
+    "i.e.",
+    "al.",
+    "fig.",
+    "vol.",
+    "no.",
+    "inc.",
+    "corp.",
+    "ltd.",
+    "co.",
+    "ph.d.",
+    "m.d.",
+    "b.a.",
+    "m.a.",
+    "j.d.",
+    "rev.",
+    "gen.",
+    "rep.",
+    "sen.",
+    "capt.",
+}
+
+
+def split_sentences(text: str) -> list[str]:
+    """
+    Split text into sentences with improved boundary detection.
+
+    Handles common abbreviations and edge cases better than simple
+    splitting on sentence-ending punctuation. Uses a two-pass approach:
+    1. Protect known abbreviations from splitting
+    2. Split on sentence boundaries
+    3. Restore abbreviations
+
+    Args:
+        text: Input text to split
+
+    Returns:
+        List of sentences
+
+    Example:
+        >>> sentences = split_sentences("Dr. Smith arrived. He was happy.")
+        >>> print(sentences)
+        ['Dr. Smith arrived.', 'He was happy.']
+    """
+    if not text:
+        return []
+
+    # Temporarily replace abbreviations with placeholders
+    protected_text = text
+    replacements = {}
+    for i, abbr in enumerate(_ABBREVIATIONS):
+        if abbr in text.lower():
+            placeholder = f"__ABBR{i}__"
+            # Case-insensitive replacement
+            pattern = re.compile(re.escape(abbr), re.IGNORECASE)
+            matches = pattern.findall(protected_text)
+            if matches:
+                replacements[placeholder] = matches[0]
+                protected_text = pattern.sub(placeholder, protected_text, count=1)
+
+    # Split on sentence boundaries: period/question/exclamation + whitespace + capital letter
+    # Simple pattern that avoids variable-width look-behind
+    sentences = re.split(r"([.!?]+)\s+(?=[A-Z])", protected_text)
+
+    # Reconstruct sentences (regex split includes the captured groups)
+    result = []
+    i = 0
+    while i < len(sentences):
+        if i + 1 < len(sentences) and sentences[i + 1] in (".", "!", "?", ".!", "!?", "?.", "..."):
+            # Combine text with its punctuation
+            sentence = sentences[i] + sentences[i + 1]
+            i += 2
+        else:
+            sentence = sentences[i]
+            i += 1
+
+        # Restore abbreviations
+        for placeholder, original in replacements.items():
+            sentence = sentence.replace(placeholder, original)
+
+        sentence = sentence.strip()
+        if sentence:
+            result.append(sentence)
+
+    # Fallback: if we only got one sentence, try simpler split
+    if len(result) <= 1 and text:
+        sentences = re.split(r"[.!?]+\s+", text)
+        result = [s.strip() for s in sentences if s.strip()]
+
+    return result
+
+
+def check_optional_dependency(module_name: str, extra_name: str) -> bool:
+    """
+    Check if an optional dependency is installed.
+
+    Args:
+        module_name: Name of the module to check
+        extra_name: Name of the extra in pyproject.toml
+
+    Returns:
+        True if module is available
+
+    Raises:
+        ImportError: If module is not installed with instructions
+    """
+    try:
+        __import__(module_name)
+        return True
+    except ImportError:
+        raise ImportError(
+            f"The '{module_name}' package is required for this functionality. "
+            f"Install it with: pip install pystylometry[{extra_name}]"
+        )

pystylometry/authorship/__init__.py

@@ -0,0 +1,10 @@
+"""Authorship attribution metrics."""
+
+from .burrows_delta import compute_burrows_delta, compute_cosine_delta
+from .zeta import compute_zeta
+
+__all__ = [
+    "compute_burrows_delta",
+    "compute_cosine_delta",
+    "compute_zeta",
+]