py-web-text-extractor 0.1.0__tar.gz

py_web_text_extractor-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.3
+Name: py-web-text-extractor
+Version: 0.1.0
+Summary: Library-wrapper for extracting text from Web Pages
+Keywords: web,text,extraction,scraping,html,markdown,trafilatura,markitdown
+Author: Oleksandr Kostenko
+Author-email: Oleksandr Kostenko <sanyokkua@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Text Processing
+Classifier: Typing :: Typed
+Requires-Dist: markitdown>=0.0.2
+Requires-Dist: trafilatura>=2.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/sanyokkua/py_web_text_extractor
+Project-URL: Repository, https://github.com/sanyokkua/py_web_text_extractor
+Project-URL: Issues, https://github.com/sanyokkua/py_web_text_extractor/issues
+Description-Content-Type: text/markdown
+
+# py-web-text-extractor
+
+[![CI](https://github.com/sanyokkua/py_web_text_extractor/actions/workflows/ci.yml/badge.svg)](https://github.com/sanyokkua/py_web_text_extractor/actions)
+[![PyPI version](https://badge.fury.io/py/py-web-text-extractor.svg)](https://pypi.org/project/py-web-text-extractor/)
+[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A CLI tool and Python library to extract clean text content from web pages.
+
+## Overview
+
+`py-web-text-extractor` provides a simple interface for extracting the main text content from HTML documents. It can be used as a command-line tool for quick extractions or as a Python library for integration into other applications. The tool uses a fallback strategy, trying `markitdown` first and then `trafilatura` to ensure high reliability.
+
+## Features
+
+- **Dual Extractor Strategy**: Uses `markitdown` as the primary extractor and falls back to `trafilatura` for robustness.
+- **CLI and Library Interface**: Can be used as a standalone command-line tool or as a Python library.
+- **Error Handling Modes**: Supports a strict mode that raises exceptions on failure and a safe mode that returns an empty string.
+- **Modern Python**: Fully typed with Python 3.14+ support.
+
+## Prerequisites
+
+- Python 3.14 or higher.
+
+## Installation
+
+You can install the package using `pip` or `uv`.
+
+### Using pip
+
+```bash
+pip install py-web-text-extractor
+```
+
+### Using uv
+
+```bash
+uv add py-web-text-extractor
+```
+
+## Usage
+
+The tool can be used via its command-line interface or as a Python library.
+
+### Command-Line Interface (CLI)
+
+The CLI is the quickest way to extract text from a URL.
+
+**Basic Extraction:**
+
+```bash
+py-web-text-extractor https://example.com
+```
+
+**Safe Mode:**
+
+In safe mode, the tool will return an empty string and exit gracefully if an error occurs.
+
+```bash
+py-web-text-extractor https://example.com --safe
+```
+
+**Verbose Mode:**
+
+For troubleshooting, verbose mode provides detailed debug output.
+
+```bash
+py-web-text-extractor https://example.com --verbose
+```
+
+**CLI Exit Codes:**
+
+| Code | Meaning                |
+| ---- | ---------------------- |
+| 0    | Success                |
+| 1    | No text content found  |
+| 2    | Invalid URL            |
+| 3    | Text extraction failed |
+| 4    | Unexpected error       |
+
+
+### Python Library
+
+For programmatic use, you can import the `ExtractorService`.
+
+**Quick Start:**
+
+```python
+from py_web_text_extractor.service.extractor_service import ExtractorService
+from py_web_text_extractor.exception.exceptions import TextExtractionError, UrlIsNotValidException
+
+# Initialize the service
+service = ExtractorService()
+
+# Strict mode: raises an exception on failure
+try:
+    text = service.extract_text_from_page("https://example.com")
+    print(text)
+except UrlIsNotValidException:
+    print("The provided URL is not valid.")
+except TextExtractionError as e:
+    print(f"Failed to extract text: {e}")
+
+# Safe mode: returns an empty string on failure
+text_safe = service.extract_text_from_page_safe("https://invalid-url")
+if not text_safe:
+    print("Extraction failed or no content found.")
+
+```
+
+## API Reference
+
+### `ExtractorService`
+
+The main class for handling text extraction.
+
+**Methods:**
+
+- **`extract_text_from_page(url: str) -> str`**: Extracts text from the given URL. Raises a `TextExtractionError` or `UrlIsNotValidException` on failure.
+- **`extract_text_from_page_safe(url: str) -> str`**: Extracts text from the given URL. Returns an empty string on failure.
+
+### Exceptions
+
+The library uses a set of custom exceptions to allow for specific error handling.
+
+- `TextExtractionError`: Base exception for the library.
+- `UrlIsNotValidException`: Raised for invalid URL formats.
+- `TextExtractionFailure`: Raised when all extraction attempts fail.
+- `MarkItDownExtractionException`: Specific failure from the `markitdown` extractor.
+- `TrafilaturaExtractionException`: Specific failure from the `trafilatura` extractor.
+
+
+## Architecture
+
+The service employs a fallback strategy to maximize reliability:
+1.  It first attempts to extract content using `markitdown`.
+2.  If `markitdown` fails (e.g., returns a blank string or raises an error), the service automatically retries the extraction using `trafilatura`.
+3.  The first successful result is returned. If both extractors fail, an error is raised or an empty string is returned, depending on the mode.
+
+## Testing
+
+To run the test suite, first install the development dependencies and then run `pytest`.
+
+> Patch pydub for Python 3.14 compatibility
+> For Python 3.14 can be required patching of old dependency
+
+```bash
+python scripts/patch_pydub.py
+```
+
+```bash
+# Install dev dependencies
+uv pip install -e ".[dev]"
+
+# Run tests
+uv run pytest
+
+# Run linters and type checkers
+uv run ruff check .
+uv run ruff format .
+uv run mypy src/
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

py_web_text_extractor-0.1.0/README.md

@@ -0,0 +1,166 @@
+# py-web-text-extractor
+
+[![CI](https://github.com/sanyokkua/py_web_text_extractor/actions/workflows/ci.yml/badge.svg)](https://github.com/sanyokkua/py_web_text_extractor/actions)
+[![PyPI version](https://badge.fury.io/py/py-web-text-extractor.svg)](https://pypi.org/project/py-web-text-extractor/)
+[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A CLI tool and Python library to extract clean text content from web pages.
+
+## Overview
+
+`py-web-text-extractor` provides a simple interface for extracting the main text content from HTML documents. It can be used as a command-line tool for quick extractions or as a Python library for integration into other applications. The tool uses a fallback strategy, trying `markitdown` first and then `trafilatura` to ensure high reliability.
+
+## Features
+
+- **Dual Extractor Strategy**: Uses `markitdown` as the primary extractor and falls back to `trafilatura` for robustness.
+- **CLI and Library Interface**: Can be used as a standalone command-line tool or as a Python library.
+- **Error Handling Modes**: Supports a strict mode that raises exceptions on failure and a safe mode that returns an empty string.
+- **Modern Python**: Fully typed with Python 3.14+ support.
+
+## Prerequisites
+
+- Python 3.14 or higher.
+
+## Installation
+
+You can install the package using `pip` or `uv`.
+
+### Using pip
+
+```bash
+pip install py-web-text-extractor
+```
+
+### Using uv
+
+```bash
+uv add py-web-text-extractor
+```
+
+## Usage
+
+The tool can be used via its command-line interface or as a Python library.
+
+### Command-Line Interface (CLI)
+
+The CLI is the quickest way to extract text from a URL.
+
+**Basic Extraction:**
+
+```bash
+py-web-text-extractor https://example.com
+```
+
+**Safe Mode:**
+
+In safe mode, the tool will return an empty string and exit gracefully if an error occurs.
+
+```bash
+py-web-text-extractor https://example.com --safe
+```
+
+**Verbose Mode:**
+
+For troubleshooting, verbose mode provides detailed debug output.
+
+```bash
+py-web-text-extractor https://example.com --verbose
+```
+
+**CLI Exit Codes:**
+
+| Code | Meaning                |
+| ---- | ---------------------- |
+| 0    | Success                |
+| 1    | No text content found  |
+| 2    | Invalid URL            |
+| 3    | Text extraction failed |
+| 4    | Unexpected error       |
+
+
+### Python Library
+
+For programmatic use, you can import the `ExtractorService`.
+
+**Quick Start:**
+
+```python
+from py_web_text_extractor.service.extractor_service import ExtractorService
+from py_web_text_extractor.exception.exceptions import TextExtractionError, UrlIsNotValidException
+
+# Initialize the service
+service = ExtractorService()
+
+# Strict mode: raises an exception on failure
+try:
+    text = service.extract_text_from_page("https://example.com")
+    print(text)
+except UrlIsNotValidException:
+    print("The provided URL is not valid.")
+except TextExtractionError as e:
+    print(f"Failed to extract text: {e}")
+
+# Safe mode: returns an empty string on failure
+text_safe = service.extract_text_from_page_safe("https://invalid-url")
+if not text_safe:
+    print("Extraction failed or no content found.")
+
+```
+
+## API Reference
+
+### `ExtractorService`
+
+The main class for handling text extraction.
+
+**Methods:**
+
+- **`extract_text_from_page(url: str) -> str`**: Extracts text from the given URL. Raises a `TextExtractionError` or `UrlIsNotValidException` on failure.
+- **`extract_text_from_page_safe(url: str) -> str`**: Extracts text from the given URL. Returns an empty string on failure.
+
+### Exceptions
+
+The library uses a set of custom exceptions to allow for specific error handling.
+
+- `TextExtractionError`: Base exception for the library.
+- `UrlIsNotValidException`: Raised for invalid URL formats.
+- `TextExtractionFailure`: Raised when all extraction attempts fail.
+- `MarkItDownExtractionException`: Specific failure from the `markitdown` extractor.
+- `TrafilaturaExtractionException`: Specific failure from the `trafilatura` extractor.
+
+
+## Architecture
+
+The service employs a fallback strategy to maximize reliability:
+1.  It first attempts to extract content using `markitdown`.
+2.  If `markitdown` fails (e.g., returns a blank string or raises an error), the service automatically retries the extraction using `trafilatura`.
+3.  The first successful result is returned. If both extractors fail, an error is raised or an empty string is returned, depending on the mode.
+
+## Testing
+
+To run the test suite, first install the development dependencies and then run `pytest`.
+
+> Patch pydub for Python 3.14 compatibility
+> For Python 3.14 can be required patching of old dependency
+
+```bash
+python scripts/patch_pydub.py
+```
+
+```bash
+# Install dev dependencies
+uv pip install -e ".[dev]"
+
+# Run tests
+uv run pytest
+
+# Run linters and type checkers
+uv run ruff check .
+uv run ruff format .
+uv run mypy src/
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

py_web_text_extractor-0.1.0/pyproject.toml

@@ -0,0 +1,132 @@
+[project]
+name = "py-web-text-extractor"
+version = "0.1.0"
+description = "Library-wrapper for extracting text from Web Pages"
+readme = "README.md"
+authors = [{ name = "Oleksandr Kostenko", email = "sanyokkua@gmail.com" }]
+requires-python = ">=3.14"
+license = { text = "MIT" }
+keywords = [
+    "web",
+    "text",
+    "extraction",
+    "scraping",
+    "html",
+    "markdown",
+    "trafilatura",
+    "markitdown",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Text Processing",
+    "Typing :: Typed",
+]
+dependencies = ["markitdown>=0.0.2", "trafilatura>=2.0.0", "typer>=0.12.0"]
+
+[project.scripts]
+py-web-text-extractor = "py_web_text_extractor.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/sanyokkua/py_web_text_extractor"
+Repository = "https://github.com/sanyokkua/py_web_text_extractor"
+Issues = "https://github.com/sanyokkua/py_web_text_extractor/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.0.2", "pytest-cov>=7.0.0", "ruff>=0.15.0"]
+
+[tool.ruff]
+target-version = "py312"
+src = ["src", "tests"]
+line-length = 120
+extend-exclude = ["tests"]
+
+[tool.ruff.lint]
+dummy-variable-rgx = "^_$"
+
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "ARG", # flake8-unused-arguments
+    "SIM", # flake8-simplify
+    "TCH", # flake8-type-checking
+    "PTH", # flake8-use-pathlib
+    "ERA", # eradicate (commented code)
+    "PL",  # Pylint
+    "RUF", # Ruff-specific rules
+    "D",   # pydocstyle (docstring linting)
+    "ANN", # flake8-annotations (type hints)
+]
+ignore = [
+    "E501",    # line too long (handled by formatter)
+    "PLR0913", # too many arguments
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+indent-style = 'space'
+quote-style = "double"
+
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",
+    "ARG",
+    "PLR2004",
+    "D",
+    "ANN001",
+    "ANN201",
+    "ANN202",
+    "ANN401",
+    "ANN204",
+]
+"**/__init__.py" = ["F401", "D104"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["py_web_text_extractor"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+
+# PYTEST
+[tool.pytest.ini_options]
+minversion = "8.0"
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = ["-ra", "-q", "--strict-markers", "--strict-config"]
+markers = ["slow: marks tests as slow", "integration: marks integration tests"]
+filterwarnings = ["error", "ignore::DeprecationWarning"]
+
+# COVERAGE
+[tool.coverage.run]
+source = ["src"]
+branch = true
+parallel = true
+omit = ["**/__init__.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "@abstractmethod",
+]
+fail_under = 80
+show_missing = true

py_web_text_extractor-0.1.0/src/py_web_text_extractor/__init__.py

@@ -0,0 +1,27 @@
+"""Extract clean text content from web pages."""
+
+from py_web_text_extractor.exception.exceptions import (
+    MarkItDownExtractionException,
+    TextExtractionError,
+    TextExtractionFailure,
+    TrafilaturaExtractionException,
+    UrlIsNotValidException,
+)
+from py_web_text_extractor.main import Extractor, ExtractorService, app, create_extractor_service
+from py_web_text_extractor.tools.validation import is_blank_string, is_valid_url
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Extractor",
+    "ExtractorService",
+    "MarkItDownExtractionException",
+    "TextExtractionError",
+    "TextExtractionFailure",
+    "TrafilaturaExtractionException",
+    "UrlIsNotValidException",
+    "app",
+    "create_extractor_service",
+    "is_blank_string",
+    "is_valid_url",
+]

py_web_text_extractor-0.1.0/src/py_web_text_extractor/abstract/__init__.py

@@ -0,0 +1,9 @@
+"""Abstract base classes and interfaces for the py_web_text_extractor library.
+
+This module contains the foundational abstract classes that define the
+contracts and interfaces for all text extraction services in the library.
+"""
+
+from py_web_text_extractor.abstract.extractor import Extractor
+
+__all__ = ["Extractor"]

py_web_text_extractor-0.1.0/src/py_web_text_extractor/abstract/extractor.py

@@ -0,0 +1,85 @@
+"""Abstract base classes for text extraction services.
+
+This module defines the interface that all text extraction services must implement,
+ensuring consistency across different extraction implementations. The Extractor
+abstract base class serves as the foundation for all concrete extraction services,
+enforcing a uniform API and behavior contract.
+
+All text extraction services in the py_web_text_extractor library must inherit
+from the Extractor ABC and implement its abstract methods to ensure compatibility
+with the library's architecture and fallback strategies.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class Extractor(ABC):
+    """Abstract base class for text extraction services.
+
+    All text extraction services must implement these methods to provide
+    a consistent interface for extracting text content from web pages.
+
+    This ABC defines two core methods:
+    - extract_text_from_page(): Main extraction with exception handling
+    - extract_text_from_page_safe(): Safe extraction that returns empty string on error
+
+    Implementations should follow these guidelines:
+    - Provide comprehensive error handling and logging
+    - Support both strict (exception-raising) and safe (error-suppressing) modes
+    - Maintain consistent return types and exception patterns
+    """
+
+    @abstractmethod
+    def extract_text_from_page_safe(self, url: str) -> str:
+        r"""Extract text content from a web page with safe error handling.
+
+        This method should implement extraction logic that catches all exceptions
+        and returns an empty string on failure, making it suitable for use cases
+        where extraction failures should not disrupt application flow.
+
+        Args:
+            url: The URL of the web page to extract text from. Should be a
+                 valid HTTP/HTTPS URL string.
+
+        Returns:
+            The extracted text content as a string if successful.
+            An empty string if any error occurs during extraction.
+
+        Example:
+            >>> extractor.extract_text_from_page_safe("https://example.com")
+            "Example Domain\\n\\nThis domain is for use in illustrative examples..."
+
+            >>> extractor.extract_text_from_page_safe("invalid-url")
+            ""  # Returns empty string instead of raising exception
+        """
+
+    @abstractmethod
+    def extract_text_from_page(self, url: str) -> str:
+        r"""Extract text content from a web page.
+
+        This method should implement the main extraction logic with comprehensive
+        error handling that raises appropriate exceptions for different failure
+        scenarios. It's suitable for use cases where detailed error information
+        is needed.
+
+        Args:
+            url: The URL of the web page to extract text from. Must be a
+                 valid HTTP/HTTPS URL string.
+
+        Returns:
+            The extracted text content as a string.
+
+        Raises:
+            TextExtractionError: If text extraction fails.
+            UrlIsNotValidException: If the provided URL is invalid or malformed.
+            MarkItDownExtractionException: If MarkItDown extraction specifically fails.
+            TrafilaturaExtractionException: If Trafilatura extraction specifically fails.
+            TextExtractionFailure: If all extraction methods fail.
+
+        Example:
+            >>> extractor.extract_text_from_page("https://example.com")
+            "Example Domain\\n\\nThis domain is for use in illustrative examples..."
+
+            >>> extractor.extract_text_from_page("invalid-url")
+            # Raises UrlIsNotValidException
+        """

py_web_text_extractor-0.1.0/src/py_web_text_extractor/cli.py

@@ -0,0 +1,84 @@
+"""Command-line interface for web text extraction."""
+
+import logging
+import sys
+
+import typer
+
+from py_web_text_extractor.exception.exceptions import (
+    TextExtractionError,
+    UrlIsNotValidException,
+)
+from py_web_text_extractor.service.extractor_service import ExtractorService
+
+app = typer.Typer(
+    name="py-web-text-extractor",
+    help="Extract clean text content from web pages",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+
+def _setup_logging(verbose: bool = False) -> None:
+    """Configure CLI logging level.
+
+    Args:
+        verbose: Enable DEBUG level logging when True; WARNING level when False.
+    """
+    level = logging.DEBUG if verbose else logging.WARNING
+    logging.basicConfig(
+        level=level,
+        format="%(levelname)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+@app.command()
+def main(
+    url: str,
+    safe: bool = False,
+    verbose: bool = False,
+) -> None:
+    """Extract text from a web page.
+
+    Args:
+        url: HTTP/HTTPS URL to extract text from.
+        safe: Return empty string on error instead of exiting with failure code.
+        verbose: Enable debug logging for troubleshooting.
+
+    Exit codes:
+        0: Success (text extracted)
+        1: No text content found
+        2: Invalid URL
+        3: Text extraction failed
+        4: Unexpected error
+    """
+    _setup_logging(verbose)
+
+    logger = logging.getLogger(__name__)
+    logger.debug("Starting extraction for URL: %s", url)
+
+    try:
+        service = ExtractorService()
+        text = service.extract_text_from_page_safe(url) if safe else service.extract_text_from_page(url)
+
+        if text:
+            print(text)
+            sys.exit(0)
+        else:
+            print("No text content found", file=sys.stderr)
+            sys.exit(1)
+
+    except UrlIsNotValidException as e:
+        print(f"Error: Invalid URL - {e}", file=sys.stderr)
+        sys.exit(2)
+    except TextExtractionError as e:
+        print(f"Error: Text extraction failed - {e}", file=sys.stderr)
+        sys.exit(3)
+    except Exception as e:
+        print(f"Error: Unexpected error - {e}", file=sys.stderr)
+        sys.exit(4)
+
+
+if __name__ == "__main__":
+    app()

py_web_text_extractor-0.1.0/src/py_web_text_extractor/exception/__init__.py

@@ -0,0 +1,21 @@
+"""Exception classes for the py_web_text_extractor library.
+
+This module exports all custom exception classes used throughout the text
+extraction process, providing a consistent error handling mechanism.
+"""
+
+from py_web_text_extractor.exception.exceptions import (
+    MarkItDownExtractionException,
+    TextExtractionError,
+    TextExtractionFailure,
+    TrafilaturaExtractionException,
+    UrlIsNotValidException,
+)
+
+__all__ = [
+    "MarkItDownExtractionException",
+    "TextExtractionError",
+    "TextExtractionFailure",
+    "TrafilaturaExtractionException",
+    "UrlIsNotValidException",
+]

py_web_text_extractor-0.1.0/src/py_web_text_extractor/exception/exceptions.py

@@ -0,0 +1,21 @@
+"""Custom exceptions for text extraction failures."""
+
+
+class TextExtractionError(Exception):
+    """Base exception for all text extraction errors."""
+
+
+class UrlIsNotValidException(TextExtractionError):
+    """Invalid or malformed URL provided."""
+
+
+class MarkItDownExtractionException(TextExtractionError):
+    """MarkItDown extraction failed."""
+
+
+class TrafilaturaExtractionException(TextExtractionError):
+    """Trafilatura extraction failed."""
+
+
+class TextExtractionFailure(TextExtractionError):
+    """All extraction methods failed for a URL."""

py_web_text_extractor-0.1.0/src/py_web_text_extractor/main.py

@@ -0,0 +1,27 @@
+"""Text extraction service factory and entry points."""
+
+from py_web_text_extractor.cli import app
+from py_web_text_extractor.service.extractor_service import ExtractorService
+
+
+def create_extractor_service() -> ExtractorService:
+    """Create a new text extraction service instance.
+
+    Returns:
+        Configured ExtractorService ready for text extraction.
+
+    Examples:
+        >>> from py_web_text_extractor import create_extractor_service
+        >>> service = create_extractor_service()
+        >>> text = service.extract_text_from_page("https://example.com")
+        >>> len(text) > 0
+        True
+    """
+    return ExtractorService()
+
+
+# Convenience alias for the main service class
+Extractor = ExtractorService
+
+
+__all__ = ["Extractor", "ExtractorService", "app", "create_extractor_service"]

py_web_text_extractor-0.1.0/src/py_web_text_extractor/service/__init__.py

@@ -0,0 +1,12 @@
+"""Text extraction services for the py_web_text_extractor library.
+
+This module contains the core service implementations for web text extraction,
+including the main ExtractorService with fallback strategy and individual
+extractor implementations for different libraries.
+"""
+
+from py_web_text_extractor.service.extractor_service import ExtractorService
+from py_web_text_extractor.service.markitdown_extractor import extract_text as markitdown_extract
+from py_web_text_extractor.service.trafilatura_extractor import extract_text as trafilatura_extract
+
+__all__ = ["ExtractorService", "markitdown_extract", "trafilatura_extract"]

py_web_text_extractor-0.1.0/src/py_web_text_extractor/service/extractor_service.py

@@ -0,0 +1,112 @@
+"""Web text extraction service with fallback strategy.
+
+Provides a unified interface for extracting clean text content from web pages
+using MarkItDown (primary) and Trafilatura (fallback) extraction methods.
+"""
+
+import logging
+from typing import override
+
+import py_web_text_extractor.service.markitdown_extractor as mk_extractor
+import py_web_text_extractor.service.trafilatura_extractor as tr_extractor
+from py_web_text_extractor.abstract.extractor import Extractor
+from py_web_text_extractor.exception.exceptions import (
+    MarkItDownExtractionException,
+    TextExtractionFailure,
+    TrafilaturaExtractionException,
+    UrlIsNotValidException,
+)
+from py_web_text_extractor.tools.validation import is_blank_string, is_valid_url
+
+logger = logging.getLogger(__name__)
+
+
+class ExtractorService(Extractor):
+    """Text extraction service with MarkItDown/Trafilatura fallback strategy."""
+
+    @override
+    def extract_text_from_page(self, url: str) -> str:
+        """Extract text content from a web page.
+
+        Attempts extraction using MarkItDown first, falling back to Trafilatura
+        if the primary method fails. Raises an exception if both methods fail.
+
+        Args:
+            url: HTTP/HTTPS URL to extract text from. Must be a non-empty string
+                starting with http:// or https://.
+
+        Returns:
+            Cleaned text content from the web page.
+
+        Raises:
+            UrlIsNotValidException: If url is None, empty, or not a valid HTTP/HTTPS URL.
+            TextExtractionFailure: If both extraction methods fail.
+
+        Examples:
+            >>> service = ExtractorService()
+            >>> text = service.extract_text_from_page("https://example.com")
+            >>> len(text) > 0
+            True
+        """
+        if not isinstance(url, str):
+            logger.debug("Non-string URL provided: %s", url)
+            raise UrlIsNotValidException(f"URL must be a string, got {type(url).__name__}")
+
+        if is_blank_string(url):
+            logger.debug("Empty or blank URL provided")
+            raise UrlIsNotValidException("URL cannot be empty or blank")
+
+        if not is_valid_url(url):
+            logger.debug("Invalid URL provided: %s", url)
+            raise UrlIsNotValidException(f"Invalid URL: {url}")
+
+        try:
+            logger.debug("Attempting to extract text from %s using MarkItDown", url)
+            return mk_extractor.extract_text(url)
+        except MarkItDownExtractionException as e:
+            logger.info("MarkItDown extraction failed for %s: %s. Falling back to Trafilatura", url, e)
+
+        try:
+            logger.debug("Attempting to extract text from %s using Trafilatura", url)
+            return tr_extractor.extract_text(url)
+        except TrafilaturaExtractionException as e:
+            logger.warning("Trafilatura extraction failed for %s: %s", url, e)
+
+        error_msg = f"Failed to extract text from {url} using both MarkItDown and Trafilatura"
+        logger.error(error_msg)
+        raise TextExtractionFailure(error_msg)
+
+    @override
+    def extract_text_from_page_safe(self, url: str) -> str:
+        """Extract text content with graceful error handling.
+
+        Returns empty string on any failure instead of raising exceptions.
+        Suitable for batch processing where individual failures should not
+        interrupt the overall workflow.
+
+        Args:
+            url: URL to extract text from (any value accepted).
+
+        Returns:
+            Extracted text if successful, empty string otherwise.
+
+        Examples:
+            >>> service = ExtractorService()
+            >>> text = service.extract_text_from_page_safe("https://example.com")
+            >>> isinstance(text, str)
+            True
+
+            >>> service.extract_text_from_page_safe("invalid-url")
+            ''
+        """
+        try:
+            return self.extract_text_from_page(url)
+        except UrlIsNotValidException as e:
+            logger.warning("Invalid URL provided: %s", e)
+            return ""
+        except TextExtractionFailure as e:
+            logger.warning("Text extraction failed: %s", e)
+            return ""
+        except Exception as e:
+            logger.warning("Unexpected error during text extraction: %s", e)
+            return ""

py_web_text_extractor-0.1.0/src/py_web_text_extractor/service/markitdown_extractor.py

@@ -0,0 +1,45 @@
+"""MarkItDown text extraction module.
+
+Provides text extraction from web pages using the MarkItDown library.
+"""
+
+import logging
+
+from markitdown import MarkItDown
+
+from py_web_text_extractor.exception.exceptions import MarkItDownExtractionException
+
+logger = logging.getLogger(__name__)
+
+
+def extract_text(url: str) -> str:
+    r"""Extract text content from a web page using MarkItDown.
+
+    Args:
+        url: HTTP/HTTPS URL to extract text from.
+
+    Returns:
+        Extracted text content from the web page.
+
+    Raises:
+        MarkItDownExtractionException: If extraction fails due to network issues,
+            invalid HTML, or other MarkItDown processing errors.
+
+    Examples:
+        >>> extract_text("https://example.com")
+        "Example Domain\\n\\nThis domain is for use in illustrative examples..."
+
+        >>> extract_text("https://news.example.com/article")
+        "Article Title\\n\\nThe main content of the article..."
+    """
+    logger.debug("Starting MarkItDown extraction for URL: %s", url)
+
+    try:
+        md = MarkItDown()
+        text = md.convert(url)
+        extracted_text = text.text_content
+        logger.info("Successfully extracted text from %s using MarkItDown", url)
+        return extracted_text
+    except Exception as e:
+        logger.warning("MarkItDown extraction failed for %s: %s", url, e)
+        raise MarkItDownExtractionException(f"MarkItDown extraction failed for {url}: {e!s}") from e

py_web_text_extractor-0.1.0/src/py_web_text_extractor/service/trafilatura_extractor.py

@@ -0,0 +1,54 @@
+"""Trafilatura text extraction module.
+
+Provides text extraction from web pages using the Trafilatura library.
+"""
+
+import logging
+
+from trafilatura import extract, fetch_url
+
+from py_web_text_extractor.exception.exceptions import TrafilaturaExtractionException
+
+logger = logging.getLogger(__name__)
+
+
+def extract_text(url: str) -> str:
+    r"""Extract text content from a web page using Trafilatura.
+
+    Args:
+        url: HTTP/HTTPS URL to extract text from.
+
+    Returns:
+        Extracted text content in markdown format. Returns an empty string if
+        Trafilatura finds no extractable content.
+
+    Raises:
+        TrafilaturaExtractionException: If content cannot be fetched or processed.
+
+    Examples:
+        >>> extract_text("https://example.com")
+        "# Example Domain\\n\\nThis domain is for use in illustrative examples..."
+
+        >>> extract_text("https://blog.example.com/post")
+        "# Post Title\\n\\n## Section Header\\n\\nMain content..."
+    """
+    logger.debug("Starting Trafilatura extraction for URL: %s", url)
+
+    try:
+        content = fetch_url(url)
+        if content is None:
+            logger.warning("Failed to fetch content from %s using Trafilatura", url)
+            raise TrafilaturaExtractionException(f"Failed to fetch content from {url}")
+
+        text = extract(content, output_format="markdown")
+        extracted_text = text or ""
+
+        if extracted_text:
+            logger.info("Successfully extracted text from %s using Trafilatura", url)
+        else:
+            logger.debug("No text content found for %s using Trafilatura", url)
+
+        return extracted_text
+    except Exception as e:
+        logger.warning("Trafilatura extraction failed for %s: %s", url, e)
+        raise TrafilaturaExtractionException(f"Trafilatura extraction failed for {url}: {e!s}") from e

py_web_text_extractor-0.1.0/src/py_web_text_extractor/tools/__init__.py

@@ -0,0 +1,10 @@
+"""Utility functions and tools for the py_web_text_extractor library.
+
+This module provides helper functions and utilities used throughout the text
+extraction process, including validation, formatting, and other supporting
+functionality.
+"""
+
+from py_web_text_extractor.tools.validation import is_blank_string, is_valid_url
+
+__all__ = ["is_blank_string", "is_valid_url"]

py_web_text_extractor-0.1.0/src/py_web_text_extractor/tools/validation.py

@@ -0,0 +1,66 @@
+"""Input validation utilities."""
+
+import re
+from urllib.parse import urlparse
+
+
+def is_blank_string(value: str | None) -> bool:
+    """Check if a string is None, empty, or whitespace-only.
+
+    Args:
+        value: String to check. May be None.
+
+    Returns:
+        True if value is None or contains no non-whitespace characters.
+
+    Examples:
+        >>> is_blank_string(None)
+        True
+        >>> is_blank_string("")
+        True
+        >>> is_blank_string("   ")
+        True
+        >>> is_blank_string("hello")
+        False
+    """
+    return value is None or len(value.strip()) == 0
+
+
+def is_valid_url(value: str | None) -> bool:
+    """Validate HTTP/HTTPS URL format.
+
+    Args:
+        value: URL string to validate. Must start with http:// or https://
+            and contain no whitespace characters.
+
+    Returns:
+        True if value is a properly formatted HTTP/HTTPS URL with scheme and netloc.
+
+    Examples:
+        >>> is_valid_url("https://example.com")
+        True
+        >>> is_valid_url("http://sub.example.com/path")
+        True
+        >>> is_blank_string("example.com")
+        True
+        >>> is_valid_url("")
+        False
+        >>> is_valid_url(None)
+        False
+        >>> is_valid_url("ftp://example.com")
+        False
+    """
+    if value is None:
+        return False
+    if not isinstance(value, str):
+        return False
+    if is_blank_string(value) or re.search(r"\s", value):
+        return False
+    if not (value.startswith("http://") or value.startswith("https://")):
+        return False
+
+    try:
+        result = urlparse(value)
+        return bool(result.scheme and result.netloc)
+    except ValueError:
+        return False