path-link 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

{project_paths → path_link}/docs/developer_guide.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-`ptool-serena` is a Python library for type-safe project path management with built-in validation. It uses Pydantic models to dynamically create path configurations from `pyproject.toml` or custom `.paths` files, and can generate static dataclass models for enhanced IDE support.
+`path-link` is a Python library for type-safe project path management with built-in validation. It uses Pydantic models to dynamically create path configurations from `pyproject.toml` or custom `.paths` files, and can generate static dataclass models for enhanced IDE support.
 
 ## Development Setup
 
@@ -43,7 +43,7 @@ uv run ruff format .
 uv run mypy src/
 
 # Regenerate static model (required after pyproject.toml changes)
-uv run python -c "from project_paths import write_dataclass_file; write_dataclass_file()"
+uv run python -c "from path_link import write_dataclass_file; write_dataclass_file()"
 
 # Or use justfile commands
 just test
@@ -58,7 +58,7 @@ Verify setup is working:
 ```bash
 uv run python scripts/smoke_import.py
 # Or one-liner:
-uv run python -c "from project_paths import ProjectPaths; p = ProjectPaths.from_pyproject(); print('✅ OK:', len(p.to_dict()), 'paths loaded')"
+uv run python -c "from path_link import ProjectPaths; p = ProjectPaths.from_pyproject(); print('✅ OK:', len(p.to_dict()), 'paths loaded')"
 ```
 
 ## Architecture
@@ -69,7 +69,7 @@ uv run python -c "from project_paths import ProjectPaths; p = ProjectPaths.from_
    - Main API for path management
    - Uses Pydantic dynamic model creation via `create_model()`
    - Direct instantiation is disabled - use factory methods only:
-     - `ProjectPaths.from_pyproject()` - loads from `[tool.project_paths]` in pyproject.toml
+     - `ProjectPaths.from_pyproject()` - loads from `[tool.path_link]` in pyproject.toml
      - `ProjectPaths.from_config(".paths")` - loads from dotenv-style files
    - All path access returns `pathlib.Path` objects
    - Supports dict-style access via `__getitem__`
@@ -96,7 +96,7 @@ uv run python -c "from project_paths import ProjectPaths; p = ProjectPaths.from_
 5. **Static Model Generation** (`src/project_paths/get_paths.py`)
    - `write_dataclass_file()` generates `project_paths_static.py` from current config
    - Uses atomic file replacement via temp file to avoid TOCTOU issues
-   - Must be regenerated after modifying `[tool.project_paths]` in pyproject.toml
+   - Must be regenerated after modifying `[tool.path_link]` in pyproject.toml
 
 6. **Documentation Access** (`src/project_paths/__init__.py`)
    - `get_ai_guidelines()` - Returns AI assistant usage patterns (bundled assistant_context.md)
@@ -108,11 +108,11 @@ uv run python -c "from project_paths import ProjectPaths; p = ProjectPaths.from_
 
 In `pyproject.toml`:
 ```toml
-[tool.project_paths.paths]
+[tool.path_link.paths]
 config_dir = "config"
 data_dir = "data"
 
-[tool.project_paths.files]
+[tool.path_link.files]
 settings_file = "config/settings.json"
 ```
 
@@ -127,9 +127,9 @@ settings_file=config/settings.json
 
 The project uses `src` layout. All imports should be absolute from package name:
 ```python
-from project_paths import ProjectPaths, ValidationResult, StrictPathValidator
-from project_paths.model import _ProjectPathsBase
-from project_paths.validation import Finding, Severity
+from path_link import ProjectPaths, ValidationResult, StrictPathValidator
+from path_link.model import _ProjectPathsBase
+from path_link.validation import Finding, Severity
 ```
 
 ## Critical Rules
@@ -138,7 +138,7 @@ from project_paths.validation import Finding, Severity
 
 **Correct:**
 ```python
-from project_paths import ProjectPaths
+from path_link import ProjectPaths
 
 # Load from pyproject.toml
 paths = ProjectPaths.from_pyproject()
@@ -159,9 +159,9 @@ paths = ProjectPaths()  # Raises NotImplementedError
 
 ### Static Model Sync
 
-After any change to `[tool.project_paths]` in pyproject.toml, you MUST regenerate the static model:
+After any change to `[tool.path_link]` in pyproject.toml, you MUST regenerate the static model:
 ```bash
-uv run python -c "from project_paths import write_dataclass_file; write_dataclass_file()"
+uv run python -c "from path_link import write_dataclass_file; write_dataclass_file()"
 ```
 
 The CI check `just check-regen` verifies this file is in sync.
@@ -193,7 +193,7 @@ Use `SandboxPathValidator` to prevent path traversal attacks and ensure paths st
 
 **Maximum Security (Recommended):**
 ```python
-from project_paths import ProjectPaths, SandboxPathValidator
+from path_link import ProjectPaths, SandboxPathValidator
 
 paths = ProjectPaths.from_pyproject()
 validator = SandboxPathValidator(
@@ -259,7 +259,7 @@ uv run pytest tests/test_validators.py::test_strict_validator_required
 
 ### Basic Validation
 ```python
-from project_paths import ProjectPaths, validate_or_raise, StrictPathValidator
+from path_link import ProjectPaths, validate_or_raise, StrictPathValidator
 
 paths = ProjectPaths.from_pyproject()
 validator = StrictPathValidator(
@@ -274,7 +274,7 @@ validate_or_raise(paths, validator)
 
 ### Composite Validation
 ```python
-from project_paths import CompositeValidator
+from path_link import CompositeValidator
 
 validator = CompositeValidator(parts=[
     StrictPathValidator(required=["config_dir"]),
@@ -292,7 +292,7 @@ if not result.ok():
 Implement the `PathValidator` protocol:
 ```python
 from dataclasses import dataclass
-from project_paths import ValidationResult, Finding, Severity
+from path_link import ValidationResult, Finding, Severity
 
 @dataclass
 class CustomValidator:
@@ -314,7 +314,7 @@ class CustomValidator:
 The package includes bundled documentation accessible via three helper functions. This enables offline access and is especially useful for AI assistants helping users.
 
 ```python
-from project_paths import get_ai_guidelines, get_developer_guide, get_metadata
+from path_link import get_ai_guidelines, get_developer_guide, get_metadata
 import json
 
 # Access AI assistant guidelines (assistant_context.md)
@@ -387,7 +387,7 @@ scripts/
 ### Import errors
 - Ensure virtual environment is activated
 - Verify editable install: `uv pip install -e ".[test]"`
-- Check import uses package name: `from project_paths import ...`
+- Check import uses package name: `from path_link import ...`
 
 ### Static model out of sync
 - Run: `just check-regen` to detect

{project_paths → path_link}/docs/metadata.json

@@ -1,5 +1,5 @@
 {
-  "dist_name": "ptool-serena",
+  "dist_name": "path-link",
   "import_name": "project_paths",
   "version": "0.2.0",
   "factories": [
@@ -26,17 +26,17 @@
   "validators": [
     {
       "name": "StrictPathValidator",
-      "module": "project_paths.builtin_validators.strict",
+      "module": "path_link.builtin_validators.strict",
       "description": "Ensures paths exist and match expected types (file/directory)"
     },
     {
       "name": "SandboxPathValidator",
-      "module": "project_paths.builtin_validators.sandbox",
+      "module": "path_link.builtin_validators.sandbox",
       "description": "Prevents path traversal attacks and enforces base directory sandbox"
     },
     {
       "name": "CompositeValidator",
-      "module": "project_paths.validation",
+      "module": "path_link.validation",
       "description": "Combines multiple validators into a single validation pipeline"
     }
   ],
@@ -69,10 +69,10 @@
     "last_verified": "2025-10-10"
   },
   "critical_commands": {
-    "smoke_test": "uv run python -c \"from project_paths import ProjectPaths; p = ProjectPaths.from_pyproject(); print('✅ OK:', len(p.to_dict()), 'paths loaded')\"",
+    "smoke_test": "uv run python -c \"from path_link import ProjectPaths; p = ProjectPaths.from_pyproject(); print('✅ OK:', len(p.to_dict()), 'paths loaded')\"",
     "run_tests": "uv run pytest",
     "check_coverage": "uv run pytest --cov=src --cov-report=term-missing:skip-covered",
-    "regenerate_static": "uv run python -c \"from project_paths import write_dataclass_file; write_dataclass_file()\"",
+    "regenerate_static": "uv run python -c \"from path_link import write_dataclass_file; write_dataclass_file()\"",
     "verify_static_sync": "just check-regen"
   },
   "known_issues": {

{project_paths → path_link}/get_paths.py

@@ -3,7 +3,7 @@ import os
 from pathlib import Path
 from typing import Optional, Union
 
-from .model import ProjectPaths
+from path_link.model import ProjectPaths
 
 
 def generate_static_model_text() -> str:
@@ -14,8 +14,8 @@ def generate_static_model_text() -> str:
         "from pathlib import Path",
         "from dataclasses import dataclass, field",
         "",
-        "# This file is auto-generated by ptool-serena. Do not edit manually.",
-        "# Run `ptool gen-static` or `just regen` to regenerate.",
+        "# This file is auto-generated by path-link. Do not edit manually.",
+        "# Run `pathlink gen-static` or `just regen` to regenerate.",
         "",
         "@dataclass(frozen=True)",
         "class ProjectPathsStatic:",

{project_paths → path_link}/model.py

@@ -4,7 +4,7 @@ from typing import Union, Any
 
 from pydantic import BaseModel, ConfigDict, create_model
 
-from .builder import (
+from path_link.builder import (
     build_field_definitions,
     get_paths_from_dot_paths,
     get_paths_from_pyproject,

{project_paths → path_link}/project_paths_static.py

@@ -1,8 +1,8 @@
 from pathlib import Path
 from dataclasses import dataclass, field
 
-# This file is auto-generated by ptool-serena. Do not edit manually.
-# Run `ptool gen-static` or `just regen` to regenerate.
+# This file is auto-generated by path-link. Do not edit manually.
+# Run `pathlink gen-static` or `just regen` to regenerate.
 
 @dataclass(frozen=True)
 class ProjectPathsStatic:

path_link/url_factory.py

@@ -0,0 +1,225 @@
+"""Factory for creating ProjectUrls instances with validation mode support.
+
+This module provides factory methods to create ProjectUrls instances from
+various configuration sources (pyproject.toml, .urls files) with configurable
+validation modes (lenient or strict).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Union, Any
+
+from pydantic import create_model, Field
+
+from path_link.url_model import _ProjectUrlsBase, ValidationMode, validate_url
+from path_link.builder import (
+    get_urls_from_pyproject,
+    get_urls_from_dot_urls,
+    get_urls_merged,
+)
+
+
+def _get_validation_mode_from_env() -> ValidationMode:
+    """
+    Determine validation mode from environment variable.
+
+    Checks PTOOL_URL_MODE environment variable:
+    - "strict" -> ValidationMode.STRICT
+    - anything else -> ValidationMode.LENIENT (default)
+
+    Returns:
+        ValidationMode enum value
+    """
+    mode_str = os.getenv("PTOOL_URL_MODE", "lenient").lower()
+    if mode_str == "strict":
+        return ValidationMode.STRICT
+    return ValidationMode.LENIENT
+
+
+def _make_url_field(url_value: str, mode: ValidationMode) -> tuple[type[str], Any]:
+    """
+    Create a Pydantic field definition for a URL with validation.
+
+    Args:
+        url_value: The URL string to validate
+        mode: Validation mode (lenient or strict)
+
+    Returns:
+        Tuple of (type, Field) for Pydantic model definition
+    """
+    # Validate the URL according to the mode
+    validated_url = validate_url(url_value, mode)
+
+    # Return a field with the validated URL as default
+    return (str, Field(default=validated_url))
+
+
+def _build_url_field_definitions(
+    url_dict: dict[str, str], mode: ValidationMode
+) -> dict[str, tuple[type[str], Any]]:
+    """
+    Build Pydantic field definitions from URL dictionary.
+
+    Args:
+        url_dict: Dictionary of URL key-value pairs
+        mode: Validation mode to use for all URLs
+
+    Returns:
+        Dictionary of field definitions for dynamic Pydantic model
+    """
+    fields = {}
+
+    for key, url_value in url_dict.items():
+        fields[key] = _make_url_field(url_value, mode)
+
+    return fields
+
+
+class ProjectUrls:
+    """
+    Main URL management class.
+
+    Do not instantiate this class directly. Use the factory methods:
+    - `ProjectUrls.from_pyproject(mode=ValidationMode.LENIENT)`
+    - `ProjectUrls.from_config("path/to/.urls", mode=ValidationMode.LENIENT)`
+    - `ProjectUrls.from_merged(mode=ValidationMode.LENIENT)`
+    """
+
+    def __init__(self, **kwargs: Any):
+        raise NotImplementedError(
+            "Direct instantiation of ProjectUrls is not supported. "
+            "Use a factory method: `from_pyproject()`, `from_config()`, or `from_merged()`."
+        )
+
+    @classmethod
+    def from_pyproject(
+        cls, mode: Union[ValidationMode, str, None] = None
+    ) -> _ProjectUrlsBase:
+        """
+        Creates a ProjectUrls instance from pyproject.toml [tool.path_link.urls].
+
+        Args:
+            mode: Validation mode (lenient or strict). If None, reads from
+                  PTOOL_URL_MODE environment variable (default: lenient)
+
+        Returns:
+            Dynamic Pydantic model instance with validated URLs
+
+        Raises:
+            ValidationError: If any URL fails validation for the given mode
+            TypeError: If urls section is not a dict in pyproject.toml
+        """
+        # Determine validation mode
+        if mode is None:
+            validation_mode = _get_validation_mode_from_env()
+        elif isinstance(mode, str):
+            validation_mode = ValidationMode(mode.lower())
+        else:
+            validation_mode = mode
+
+        # Load URLs from pyproject.toml
+        url_dict = get_urls_from_pyproject()
+
+        # Build field definitions with validation
+        field_defs = _build_url_field_definitions(url_dict, validation_mode)
+
+        # Create dynamic model
+        DynamicModel = create_model(  # type: ignore[call-overload]
+            "ProjectUrlsDynamic",
+            __base__=(_ProjectUrlsBase,),
+            **field_defs,
+        )
+
+        return DynamicModel()  # type: ignore[no-any-return]
+
+    @classmethod
+    def from_config(
+        cls, config_path: Union[str, Path], mode: Union[ValidationMode, str, None] = None
+    ) -> _ProjectUrlsBase:
+        """
+        Creates a ProjectUrls instance from a .urls file.
+
+        Args:
+            config_path: Path to .urls configuration file
+            mode: Validation mode (lenient or strict). If None, reads from
+                  PTOOL_URL_MODE environment variable (default: lenient)
+
+        Returns:
+            Dynamic Pydantic model instance with validated URLs
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            ValidationError: If any URL fails validation for the given mode
+        """
+        # Determine validation mode
+        if mode is None:
+            validation_mode = _get_validation_mode_from_env()
+        elif isinstance(mode, str):
+            validation_mode = ValidationMode(mode.lower())
+        else:
+            validation_mode = mode
+
+        # Load URLs from .urls file
+        resolved_path = Path(config_path)
+        url_dict = get_urls_from_dot_urls(resolved_path)
+
+        # Build field definitions with validation
+        field_defs = _build_url_field_definitions(url_dict, validation_mode)
+
+        # Create dynamic model
+        DynamicModel = create_model(  # type: ignore[call-overload]
+            "ProjectUrlsDynamic",
+            __base__=(_ProjectUrlsBase,),
+            **field_defs,
+        )
+
+        return DynamicModel()  # type: ignore[no-any-return]
+
+    @classmethod
+    def from_merged(
+        cls,
+        dotenv_path: Union[str, Path, None] = None,
+        mode: Union[ValidationMode, str, None] = None,
+    ) -> _ProjectUrlsBase:
+        """
+        Creates a ProjectUrls instance from merged pyproject.toml and .urls sources.
+
+        Precedence: pyproject.toml > .urls file
+        Missing keys are merged; duplicates resolved by pyproject.toml.
+
+        Args:
+            dotenv_path: Optional path to .urls file (default: ./.urls)
+            mode: Validation mode (lenient or strict). If None, reads from
+                  PTOOL_URL_MODE environment variable (default: lenient)
+
+        Returns:
+            Dynamic Pydantic model instance with validated URLs
+
+        Raises:
+            ValidationError: If any URL fails validation for the given mode
+        """
+        # Determine validation mode
+        if mode is None:
+            validation_mode = _get_validation_mode_from_env()
+        elif isinstance(mode, str):
+            validation_mode = ValidationMode(mode.lower())
+        else:
+            validation_mode = mode
+
+        # Load merged URLs
+        resolved_dotenv = Path(dotenv_path) if dotenv_path else None
+        url_dict = get_urls_merged(resolved_dotenv)
+
+        # Build field definitions with validation
+        field_defs = _build_url_field_definitions(url_dict, validation_mode)
+
+        # Create dynamic model
+        DynamicModel = create_model(  # type: ignore[call-overload]
+            "ProjectUrlsDynamic",
+            __base__=(_ProjectUrlsBase,),
+            **field_defs,
+        )
+
+        return DynamicModel()  # type: ignore[no-any-return]

path_link/url_model.py

@@ -0,0 +1,151 @@
+"""URL validation models with lenient and strict modes.
+
+This module provides Pydantic validators for URL strings with two validation modes:
+- lenient: Allows localhost, private IPs, custom ports (for development)
+- strict: RFC-aligned HTTP(S) only (for production)
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import AnyUrl, HttpUrl, field_validator, BaseModel, ConfigDict
+
+
+class ValidationMode(str, Enum):
+    """URL validation mode."""
+
+    LENIENT = "lenient"
+    STRICT = "strict"
+
+
+class _ProjectUrlsBase(BaseModel):
+    """
+    Internal base class for ProjectUrls.
+    Provides core functionality and should not be used directly by end-users.
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    def to_dict(self) -> dict[str, str]:
+        """Returns a dictionary of all resolved URL attributes as strings."""
+        return {k: str(v) for k, v in self.model_dump(include=set(self.__class__.model_fields.keys())).items()}  # type: ignore[no-any-return]
+
+    def get_urls(self) -> list[str]:
+        """Returns a list of all resolved URL strings."""
+        return [str(v) for v in self.to_dict().values()]
+
+    def __getitem__(self, key: str) -> str:
+        """Enables dictionary-style access to URL attributes."""
+        if key not in self.__class__.model_fields:
+            raise KeyError(f"'{key}' is not a configured URL.")
+        value = getattr(self, key)
+        return str(value)  # type: ignore[no-any-return]
+
+
+class LenientUrlModel(BaseModel):
+    """
+    Lenient URL validator that accepts localhost, private IPs, and custom ports.
+
+    Suitable for development environments where URLs like http://localhost:8000
+    are common.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    url: AnyUrl
+
+    @field_validator("url", mode="before")
+    @classmethod
+    def validate_lenient_url(cls, v: Any) -> Any:
+        """
+        Lenient validation: accept any syntactically valid URL.
+
+        This includes:
+        - localhost and 127.0.0.1
+        - Private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+        - Custom ports
+        - http and https schemes
+        """
+        if not isinstance(v, str):
+            v = str(v)
+
+        # Basic checks for obviously invalid URLs
+        if not v or v.isspace():
+            raise ValueError("URL cannot be empty or whitespace")
+
+        # Let Pydantic's AnyUrl handle the rest of the validation
+        # It's permissive enough for development use cases
+        return v
+
+
+class StrictUrlModel(BaseModel):
+    """
+    Strict URL validator that only accepts RFC-compliant HTTP(S) URLs.
+
+    Suitable for production environments where URLs must be publicly accessible
+    and follow strict HTTP(S) standards.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    url: HttpUrl
+
+    @field_validator("url", mode="after")
+    @classmethod
+    def validate_strict_url(cls, v: HttpUrl) -> HttpUrl:
+        """
+        Strict validation: only accept HTTP(S) URLs with proper hosts.
+
+        This rejects:
+        - localhost URLs
+        - Private IP addresses
+        - Non-HTTP(S) schemes
+        - Malformed URLs
+        """
+        # Check for localhost
+        host = v.host
+        if host in ("localhost", "127.0.0.1", "::1"):
+            raise ValueError("localhost URLs are not allowed in strict mode")
+
+        # Check for private IP ranges
+        if host:
+            # Check IPv4 private ranges
+            if host.startswith("10."):
+                raise ValueError("Private IP addresses (10.0.0.0/8) are not allowed in strict mode")
+            if host.startswith("172.") and len(host.split(".")) == 4:
+                second_octet = int(host.split(".")[1])
+                if 16 <= second_octet <= 31:
+                    raise ValueError("Private IP addresses (172.16.0.0/12) are not allowed in strict mode")
+            if host.startswith("192.168."):
+                raise ValueError("Private IP addresses (192.168.0.0/16) are not allowed in strict mode")
+
+        return v
+
+
+def validate_url(url_string: str, mode: ValidationMode = ValidationMode.LENIENT) -> str:
+    """
+    Validate a URL string according to the specified mode.
+
+    Args:
+        url_string: The URL string to validate
+        mode: Validation mode (lenient or strict)
+
+    Returns:
+        The validated URL as a string
+
+    Raises:
+        ValidationError: If the URL is invalid for the given mode
+
+    Examples:
+        >>> validate_url("http://localhost:8000", ValidationMode.LENIENT)
+        'http://localhost:8000/'
+
+        >>> validate_url("https://example.com/api", ValidationMode.STRICT)
+        'https://example.com/api'
+    """
+    if mode == ValidationMode.LENIENT:
+        lenient_model = LenientUrlModel(url=url_string)  # type: ignore[arg-type]
+        return str(lenient_model.url)
+    else:
+        strict_model = StrictUrlModel(url=url_string)  # type: ignore[arg-type]
+        return str(strict_model.url)