linkedin2md 0.1.0__py3-none-any.whl

linkedin2md/__init__.py

@@ -0,0 +1,64 @@
+"""linkedin2md - Convert LinkedIn data exports to Markdown.
+
+SOLID-compliant architecture:
+- S: Each parser/formatter handles one section
+- O: New sections added via registry decorators
+- L: All parsers/formatters are substitutable via protocols
+- I: Focused protocols for each concern
+- D: Converter depends on abstractions, not concretions
+"""
+
+__version__ = "0.1.0"
+
+# Main public API
+from linkedin2md.converter import LinkedInToMarkdownConverter, create_converter
+
+# Backward compatibility - import old API
+# (These are deprecated but kept for compatibility)
+from linkedin2md.formatter import MarkdownFormatter
+from linkedin2md.parser import LinkedInExportParser
+
+# Protocols for type hints and custom implementations
+from linkedin2md.protocols import (
+    BilingualText,
+    DataExtractor,
+    FormatterRegistry,
+    LanguageDetector,
+    OutputWriter,
+    ParserRegistry,
+    SectionFormatter,
+    SectionParser,
+)
+
+# Registries for extension
+from linkedin2md.registry import (
+    get_formatter_registry,
+    get_parser_registry,
+    register_formatter,
+    register_parser,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Main API
+    "LinkedInToMarkdownConverter",
+    "create_converter",
+    # Protocols
+    "BilingualText",
+    "DataExtractor",
+    "FormatterRegistry",
+    "LanguageDetector",
+    "OutputWriter",
+    "ParserRegistry",
+    "SectionFormatter",
+    "SectionParser",
+    # Registry
+    "get_formatter_registry",
+    "get_parser_registry",
+    "register_formatter",
+    "register_parser",
+    # Backward compatibility (deprecated)
+    "LinkedInExportParser",
+    "MarkdownFormatter",
+]

linkedin2md/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m linkedin2md."""
+
+from linkedin2md.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

linkedin2md/cli.py

@@ -0,0 +1,81 @@
+"""CLI for linkedin2md.
+
+Dependency Inversion: Uses factory function, doesn't create dependencies directly.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from linkedin2md.converter import create_converter
+
+# Maximum allowed file size in megabytes (500 MB)
+MAX_FILE_SIZE_MB = 500
+
+
+def main() -> int:
+    """Main entry point."""
+    args = _parse_args(sys.argv[1:])
+
+    if not args.source.exists():
+        print(f"Error: File not found: {args.source}", file=sys.stderr)
+        return 1
+
+    if not args.source.suffix.lower() == ".zip":
+        print(f"Error: Expected .zip file, got {args.source.suffix}", file=sys.stderr)
+        return 1
+
+    # Check file size to prevent resource exhaustion
+    file_size_mb = args.source.stat().st_size / (1024 * 1024)
+    if file_size_mb > MAX_FILE_SIZE_MB:
+        print(
+            f"Error: File too large ({file_size_mb:.1f} MB). "
+            f"Maximum allowed is {MAX_FILE_SIZE_MB} MB",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        # Use factory to create converter with all dependencies
+        converter = create_converter(args.source, args.output)
+        files = converter.convert(lang=args.lang)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    print(f"Created {len(files)} files in {args.output}/")
+    for f in files:
+        print(f"  - {f.name}")
+
+    return 0
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(
+        prog="linkedin2md",
+        description="Convert LinkedIn data exports to Markdown",
+    )
+    parser.add_argument(
+        "source",
+        type=Path,
+        help="LinkedIn ZIP export file",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=Path("linkedin_export"),
+        help="Output directory (default: linkedin_export)",
+    )
+    parser.add_argument(
+        "--lang",
+        choices=["en", "es"],
+        default="en",
+        help="Output language (default: en)",
+    )
+    return parser.parse_args(argv)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

linkedin2md/converter.py

@@ -0,0 +1,136 @@
+"""Main converter orchestrator with dependency injection.
+
+Implements the Dependency Inversion Principle:
+- Depends on abstractions (protocols), not concretions
+- All dependencies are injected, not created internally
+"""
+
+from pathlib import Path
+
+from linkedin2md.protocols import (
+    DataExtractor,
+    FormatterRegistry,
+    OutputWriter,
+    ParserRegistry,
+)
+
+
+class LinkedInToMarkdownConverter:
+    """Main orchestrator for LinkedIn to Markdown conversion.
+
+    SOLID Principles:
+    - Single Responsibility: Only orchestrates the conversion process
+    - Open/Closed: New parsers/formatters added via registries
+    - Dependency Inversion: Depends on protocols, not implementations
+
+    All dependencies are injected via constructor.
+    """
+
+    def __init__(
+        self,
+        extractor: DataExtractor,
+        parser_registry: ParserRegistry,
+        formatter_registry: FormatterRegistry,
+        writer: OutputWriter,
+    ):
+        """Initialize with injected dependencies.
+
+        Args:
+            extractor: Extracts raw data from source
+            parser_registry: Registry of section parsers
+            formatter_registry: Registry of section formatters
+            writer: Writes formatted output
+        """
+        self._extractor = extractor
+        self._parsers = parser_registry
+        self._formatters = formatter_registry
+        self._writer = writer
+
+    def convert(self, lang: str = "en") -> list[Path]:
+        """Convert LinkedIn export to Markdown files.
+
+        Args:
+            lang: Output language ('en' or 'es')
+
+        Returns:
+            List of paths to created files
+        """
+        # Step 1: Extract raw CSV data
+        raw_data = self._extractor.extract()
+
+        # Step 2: Parse all sections
+        parsed_data = self._parse_all(raw_data)
+
+        # Step 3: Format and write all sections
+        return self._format_and_write_all(parsed_data, lang)
+
+    def _parse_all(self, raw_data: dict[str, list[dict]]) -> dict[str, object]:
+        """Parse all sections using registered parsers."""
+        parsed = {}
+
+        for parser in self._parsers.get_all():
+            try:
+                result = parser.parse(raw_data)
+                parsed[parser.section_key] = result
+            except Exception as e:
+                # Log but don't fail on individual section errors
+                print(f"Warning: Failed to parse {parser.section_key}: {e}")
+
+        return parsed
+
+    def _format_and_write_all(self, data: dict[str, object], lang: str) -> list[Path]:
+        """Format and write all sections."""
+        files = []
+
+        # Special handling for profile (needs full data)
+        profile_formatter = self._formatters.get("profile")
+        if profile_formatter:
+            content = profile_formatter.format(data, lang)
+            if content and content.strip():
+                path = self._writer.write("profile", content)
+                files.append(path)
+
+        # Format other sections
+        for formatter in self._formatters.get_all():
+            if formatter.section_key == "profile":
+                continue  # Already handled
+
+            section_data = data.get(formatter.section_key)
+            if not section_data:
+                continue
+
+            try:
+                content = formatter.format(section_data, lang)
+                if content and content.strip():
+                    path = self._writer.write(formatter.section_key, content)
+                    files.append(path)
+            except Exception as e:
+                print(f"Warning: Failed to format {formatter.section_key}: {e}")
+
+        return files
+
+
+def create_converter(
+    source: Path,
+    output_dir: Path,
+) -> LinkedInToMarkdownConverter:
+    """Factory function to create a converter with default dependencies.
+
+    This provides a convenient way to create a fully configured converter
+    while still allowing dependency injection for testing.
+    """
+    # Import here to trigger registration of parsers and formatters
+    from linkedin2md import (
+        formatters,  # noqa: F401
+        parsers,  # noqa: F401
+    )
+    from linkedin2md.extractor import ZipDataExtractor
+    from linkedin2md.registry import get_formatter_registry, get_parser_registry
+    from linkedin2md.writer import MarkdownFileWriter
+
+    return LinkedInToMarkdownConverter(
+        extractor=ZipDataExtractor(source),
+        parser_registry=get_parser_registry(),
+        formatter_registry=get_formatter_registry(),
+        writer=MarkdownFileWriter(output_dir),
+    )

linkedin2md/extractor.py

@@ -0,0 +1,80 @@
+"""Data extraction implementations.
+
+Single Responsibility: Extract raw data from sources.
+"""
+
+import csv
+import io
+import zipfile
+from pathlib import Path
+
+from linkedin2md.protocols import DataExtractor
+
+
+class ZipDataExtractor(DataExtractor):
+    """Extract CSV data from LinkedIn ZIP export.
+
+    Single Responsibility: Only handles ZIP I/O and CSV parsing.
+    Does NOT transform or interpret the data.
+    """
+
+    def __init__(self, zip_path: Path | str):
+        self.zip_path = Path(zip_path)
+
+    def extract(self) -> dict[str, list[dict]]:
+        """Extract all CSVs from ZIP into raw dict format.
+
+        Raises:
+            ValueError: If the ZIP file is invalid or corrupted.
+        """
+        data: dict[str, list[dict]] = {}
+
+        try:
+            with zipfile.ZipFile(self.zip_path, "r") as zf:
+                for name in zf.namelist():
+                    if name.endswith(".csv"):
+                        with zf.open(name) as f:
+                            content = f.read().decode("utf-8")
+                            content = self._skip_header_notes(content)
+                            reader = csv.DictReader(io.StringIO(content))
+                            key = Path(name).stem.lower().replace(" ", "_")
+                            data[key] = list(reader)
+        except zipfile.BadZipFile as err:
+            raise ValueError(f"Invalid or corrupted ZIP file: {self.zip_path}") from err
+
+        return data
+
+    def _skip_header_notes(self, content: str) -> str:
+        """Skip header notes in LinkedIn CSVs.
+
+        Some files like Connections.csv start with:
+        Notes:
+        "When exporting your connection data..."
+
+        First Name,Last Name,URL,...
+        """
+        lines = content.split("\n")
+
+        if lines and lines[0].strip().startswith("Notes"):
+            for i, line in enumerate(lines):
+                stripped = line.strip()
+                if not stripped:
+                    continue
+                if "," in stripped and not stripped.startswith('"'):
+                    return "\n".join(lines[i:])
+
+        return content
+
+
+class DictDataExtractor(DataExtractor):
+    """Extract data from a pre-loaded dict (for testing).
+
+    Single Responsibility: Wraps existing data in extractor interface.
+    """
+
+    def __init__(self, data: dict[str, list[dict]]):
+        self._data = data
+
+    def extract(self) -> dict[str, list[dict]]:
+        """Return the pre-loaded data."""
+        return self._data