path-link 0.2.0__tar.gz → 0.3.0__tar.gz

{path_link-0.2.0/src/path_link.egg-info → path_link-0.3.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: path-link
-Version: 0.2.0
-Summary: Type-safe path and URL configuration for Python projects with validation, static models, and IDE autocompletion. Currently supports local paths, URL support coming in v0.3.0.
+Version: 0.3.0
+Summary: Type-safe path and URL configuration for Python projects with validation, static models, and IDE autocompletion. Features path management and URL validation with lenient/strict modes.
 Author-email: Lasse Tammilehto <lasse@jaahdytyspalvelu.fi>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, http://jaahdytyspalvelu.fi
 Project-URL: Documentation, https://github.com/jaahdytyspalvelu/path-link#readme
 Project-URL: Issue Tracker, https://github.com/jaahdytyspalvelu/path-link/issues
@@ -11,7 +11,6 @@ Project-URL: AI Guidelines, https://github.com/jaahdytyspalvelu/path-link/blob/m
 Project-URL: Developer Guide, https://github.com/jaahdytyspalvelu/path-link/blob/main/CLAUDE.md
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -23,6 +22,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic>=2.11.0
 Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: twine>=6.2.0
 Provides-Extra: test
 Requires-Dist: pytest>=8.4.2; extra == "test"
 Requires-Dist: pytest-cov>=7.0.0; extra == "test"
@@ -35,17 +35,31 @@ Dynamic: license-file
 
 Type-safe path and URL configuration for Python projects with validation, static models, and IDE autocompletion.
 
-**Current:** Local path management ✅
-**Coming in v0.3.0:** URL support (API endpoints, external resources)
+**Features:**
+- ✅ Local path management
+- ✅ URL configuration with lenient/strict validation
+- ✅ Static model generation for both paths and URLs
+- ✅ CLI tools for validation and inspection
 
 ## 🚀 Features
 
+### Path Management
 - **Dynamic Path Management**: Load paths from `pyproject.toml` or custom `.paths` files
 - **Type-Safe Static Models**: Generate static dataclasses for IDE autocomplete and type checking
-- **Extensible Validation**: Protocol-based validator system with built-in and custom validators
+- **Environment Variable Expansion**: Support for `$VAR`, `${VAR}`, and `~` expansion
 - **Cross-Platform**: Works on Linux, Windows, and macOS
-- **Zero Runtime Dependencies**: Only requires `pydantic` and `python-dotenv`
-- **Developer Friendly**: Full type hints, comprehensive testing, and clear error messages
+
+### URL Management
+- **Dual Validation Modes**: Lenient (dev/localhost) and strict (production) URL validation
+- **Multiple Sources**: Load from `pyproject.toml`, `.urls` files, or merge both
+- **Static URL Models**: Generate dataclasses for type-safe URL access
+- **CLI Tools**: Validate, print, and generate static models from command line
+
+### General
+- **Extensible Validation**: Protocol-based validator system with built-in and custom validators
+- **Security Features**: Path traversal protection, sandbox validation
+- **Minimal Dependencies**: Only requires `pydantic` and `python-dotenv`
+- **Developer Friendly**: Full type hints, comprehensive testing (212 tests), and clear error messages
 
 ## 📦 Installation
 
@@ -71,7 +85,7 @@ uv sync
 ### Basic Usage
 
 ```python
-from project_paths import ProjectPaths
+from path_link import ProjectPaths
 
 # Load paths from pyproject.toml
 paths = ProjectPaths.from_pyproject()
@@ -91,14 +105,14 @@ all_paths = paths.to_dict()
 ### Configuration in pyproject.toml
 
 ```toml
-[tool.project_paths.paths]
+[tool.path_link.paths]
 config = "config"
 icons = "icons"
 data = "data"
 cache = ".cache"
 logs = "logs"
 
-[tool.project_paths.files]
+[tool.path_link.files]
 settings = "config/settings.json"
 database = "data/app.db"
 ```
@@ -151,43 +165,202 @@ config_dir = ~/.config/myapp
 
 **Example `pyproject.toml`:**
 ```toml
-[tool.project_paths.paths]
+[tool.path_link.paths]
 data_dir = "${DATA_ROOT}/files"
 config_dir = "~/.config/myapp"
 ```
 
+## 🌐 URL Management
+
+path-link includes powerful URL configuration management with validation modes for different environments.
+
+### Basic URL Usage
+
+```python
+from path_link import ProjectUrls, ValidationMode
+
+# Load URLs from pyproject.toml (lenient mode by default)
+urls = ProjectUrls.from_pyproject()
+
+# Access URLs
+print(urls.api_base)      # API base URL
+print(urls.webhook_url)   # Webhook endpoint
+
+# Dictionary-style access
+api_url = urls["api_base"]
+
+# Get all URLs as dictionary
+all_urls = urls.to_dict()
+```
+
+### URL Configuration
+
+**In `pyproject.toml`:**
+```toml
+[tool.path_link.urls]
+api_base = "https://api.example.com"
+webhook_url = "https://example.com/webhooks/callback"
+docs_url = "https://docs.example.com"
+
+# Development URLs (use lenient mode)
+dev_api = "http://localhost:8000"
+dev_db = "http://127.0.0.1:5432"
+```
+
+**In `.urls` file (dotenv format):**
+```bash
+# Production URLs
+api_base=https://api.example.com
+webhook_url=https://example.com/webhooks/callback
+
+# Development URLs
+dev_api=http://localhost:8000
+dev_db=http://127.0.0.1:5432
+```
+
+### Validation Modes
+
+**Lenient Mode (Development):**
+- Accepts `localhost` and `127.0.0.1`
+- Allows private IP addresses (10.x.x.x, 192.168.x.x, 172.16-31.x.x)
+- Permits custom ports
+- Suitable for development and testing
+
+**Strict Mode (Production):**
+- Only accepts public HTTP(S) URLs
+- Rejects localhost and private IPs
+- RFC-compliant validation
+- Suitable for production deployments
+
+```python
+from path_link import ProjectUrls, ValidationMode
+
+# Lenient mode (default) - allows localhost
+dev_urls = ProjectUrls.from_pyproject(mode=ValidationMode.LENIENT)
+# ✅ http://localhost:8000 is valid
+
+# Strict mode - only public URLs
+prod_urls = ProjectUrls.from_pyproject(mode=ValidationMode.STRICT)
+# ❌ http://localhost:8000 raises ValidationError
+# ✅ https://api.example.com is valid
+```
+
+### Loading from Multiple Sources
+
+```python
+# Load from .urls file only
+urls = ProjectUrls.from_config(".urls")
+
+# Merge pyproject.toml and .urls (pyproject takes precedence)
+urls = ProjectUrls.from_merged()
+
+# Merge with custom .urls file
+urls = ProjectUrls.from_merged(dotenv_path="config/.urls.prod")
+```
+
+### Environment-Based Mode Selection
+
+Set the validation mode via environment variable:
+
+```bash
+# Development
+export PTOOL_URL_MODE=lenient
+python your_app.py
+
+# Production
+export PTOOL_URL_MODE=strict
+python your_app.py
+```
+
+```python
+# Automatically uses environment variable
+urls = ProjectUrls.from_pyproject()  # Respects PTOOL_URL_MODE
+```
+
+### Static URL Model Generation
+
+Generate a static dataclass for IDE autocomplete:
+
+```python
+from path_link import write_url_dataclass_file, ValidationMode
+
+# Generate with lenient validation (default)
+write_url_dataclass_file()
+
+# Generate with strict validation for production
+write_url_dataclass_file(mode=ValidationMode.STRICT)
+
+# Custom output location
+write_url_dataclass_file(
+    output_path="config/urls_static.py",
+    mode=ValidationMode.LENIENT
+)
+```
+
+Then import and use:
+
+```python
+from path_link.project_urls_static import ProjectUrlsStatic
+
+urls = ProjectUrlsStatic()
+# Full IDE autocomplete for all configured URLs!
+print(urls.api_base)
+```
+
+### URL CLI Commands
+
+```bash
+# Print all URLs as JSON
+pathlink print-urls
+
+# Print in table format
+pathlink print-urls --format table
+
+# Validate URLs (lenient mode)
+pathlink validate-urls
+
+# Validate with strict mode
+pathlink validate-urls --mode strict
+
+# Generate static URL model
+pathlink gen-static-urls
+
+# Generate with strict mode
+pathlink gen-static-urls --mode strict
+```
+
 ## 🖥️ Command Line Interface
 
-ptool-serena includes a `ptool` CLI for quick operations without writing Python code.
+path-link includes a `pathlink` CLI for quick operations without writing Python code.
 
 ### Available Commands
 
 ```bash
 # Print all configured paths as JSON
-ptool print
+pathlink print
 
 # Validate project structure
-ptool validate
+pathlink validate
 
 # Generate static dataclass model
-ptool gen-static
+pathlink gen-static
 
 # Show help
-ptool --help
+pathlink --help
 ```
 
 ### Command Reference
 
-#### `ptool print` - Display Paths
+#### `pathlink print` - Display Paths
 
 Prints all configured paths as formatted JSON.
 
 ```bash
 # Print from pyproject.toml (default)
-ptool print
+pathlink print
 
 # Print from custom .paths file
-ptool print --source config --config my.paths
+pathlink print --source config --config my.paths
 
 # Output example:
 # {
@@ -202,22 +375,22 @@ ptool print --source config --config my.paths
 - `--source {pyproject,config}` - Configuration source (default: pyproject)
 - `--config PATH` - Path to .paths file (default: .paths)
 
-#### `ptool validate` - Validate Paths
+#### `pathlink validate` - Validate Paths
 
 Validates that your project structure matches the configuration.
 
 ```bash
 # Basic validation (check paths can be loaded)
-ptool validate
+pathlink validate
 
 # Strict validation (check paths exist, no symlinks)
-ptool validate --strict
+pathlink validate --strict
 
 # Raise exception on validation failure
-ptool validate --strict --raise
+pathlink validate --strict --raise
 
 # Validate from custom config
-ptool validate --source config --config production.paths
+pathlink validate --source config --config production.paths
 ```
 
 **Options:**
@@ -230,57 +403,57 @@ ptool validate --source config --config production.paths
 - `0` - Validation passed
 - `1` - Validation failed or error occurred
 
-#### `ptool gen-static` - Generate Static Model
+#### `pathlink gen-static` - Generate Static Model
 
 Generates a static dataclass for IDE autocomplete and type checking.
 
 ```bash
-# Generate at default location (src/project_paths/project_paths_static.py)
-ptool gen-static
+# Generate at default location (src/path_link/project_paths_static.py)
+pathlink gen-static
 
 # Generate at custom location
-ptool gen-static --out custom/path/static_paths.py
+pathlink gen-static --out custom/path/static_paths.py
 ```
 
 **Options:**
 - `--out PATH` - Output path for static model
 
-**When to use:** After modifying `[tool.project_paths]` in `pyproject.toml` to keep static model in sync.
+**When to use:** After modifying `[tool.path_link]` in `pyproject.toml` to keep static model in sync.
 
 ### CLI Usage Examples
 
 **Quick project validation:**
 ```bash
 cd your-project/
-ptool validate --strict
+pathlink validate --strict
 # ✅ All paths valid (strict mode)
 ```
 
 **View all configured paths:**
 ```bash
-ptool print
+pathlink print
 # Outputs JSON with all resolved paths
 ```
 
 **Generate static model for IDE support:**
 ```bash
-ptool gen-static
+pathlink gen-static
 # ✅ Static model generated successfully
 ```
 
 **CI/CD integration:**
 ```bash
 # In your CI script
-ptool validate --strict --raise || exit 1
+pathlink validate --strict --raise || exit 1
 ```
 
 **Multiple environments:**
 ```bash
 # Development
-ptool validate --source config --config .paths.dev
+pathlink validate --source config --config .paths.dev
 
 # Production
-ptool validate --source config --config .paths.prod
+pathlink validate --source config --config .paths.prod
 ```
 
 ### With Validation
@@ -288,8 +461,8 @@ ptool validate --source config --config .paths.prod
 You can validate your project's structure by using one of the built-in validators.
 
 ```python
-from project_paths import ProjectPaths, validate_or_raise, PathValidationError
-from project_paths.builtin_validators import StrictPathValidator
+from path_link import ProjectPaths, validate_or_raise, PathValidationError
+from path_link.builtin_validators import StrictPathValidator
 
 # 1. Load your paths
 paths = ProjectPaths.from_pyproject()
@@ -321,8 +494,8 @@ if not result.ok():
 The `SandboxPathValidator` prevents path traversal attacks by ensuring all paths stay within your project's base directory. This is crucial for applications that handle user input or load paths from external sources.
 
 ```python
-from project_paths import ProjectPaths
-from project_paths.builtin_validators import SandboxPathValidator
+from path_link import ProjectPaths
+from path_link.builtin_validators import SandboxPathValidator
 
 paths = ProjectPaths.from_pyproject()
 
@@ -386,7 +559,7 @@ targeted_sandbox = SandboxPathValidator(
 Generate a static dataclass for better IDE support:
 
 ```python
-from project_paths import write_dataclass_file
+from path_link import write_dataclass_file
 
 # Generate src/project_paths/project_paths_static.py
 write_dataclass_file()
@@ -395,7 +568,7 @@ write_dataclass_file()
 This creates a fully typed dataclass that can be imported:
 
 ```python
-from project_paths.project_paths_static import ProjectPathsStatic
+from path_link.project_paths_static import ProjectPathsStatic
 
 paths = ProjectPathsStatic()
 # Now you get full IDE autocomplete!
@@ -407,7 +580,7 @@ Create your own validators by creating a class with a `validate` method that ret
 
 ```python
 from dataclasses import dataclass
-from project_paths import Finding, Severity, ValidationResult, ProjectPaths
+from path_link import Finding, Severity, ValidationResult, ProjectPaths
 
 @dataclass
 class MyCustomValidator:
@@ -443,7 +616,7 @@ Combine multiple validators to run them as a single pipeline.
 
 ```python
 # Assuming MyCustomValidator is defined as in the previous example
-from project_paths.builtin_validators import CompositeValidator, StrictPathValidator
+from path_link.builtin_validators import CompositeValidator, StrictPathValidator
 
 # 1. Load paths
 paths = ProjectPaths.from_pyproject()
@@ -469,7 +642,7 @@ if not final_result.ok():
 The package includes bundled documentation that can be accessed programmatically, even in offline or airgapped environments. This is especially useful for AI assistants helping users with the package.
 
 ```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
 
 # Get AI assistant guidelines (comprehensive usage patterns and best practices)
@@ -533,8 +706,8 @@ uv run pytest tests/test_validators.py
 
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/ptool-serena.git
-cd ptool-serena
+git clone https://github.com/jaahdytyspalvelu/path-link.git
+cd path-link
 
 # Install with uv
 uv sync
@@ -619,8 +792,8 @@ MIT License - see LICENSE file for details.
 
 ## 🔗 Links
 
-- [Documentation](https://github.com/yourusername/ptool-serena/docs)
-- [Issue Tracker](https://github.com/yourusername/ptool-serena/issues)
+- [Documentation](https://github.com/jaahdytyspalvelu/path-link/docs)
+- [Issue Tracker](https://github.com/jaahdytyspalvelu/path-link/issues)
 - [Changelog](CHANGELOG.md)
 
 ## 💡 Examples
@@ -640,4 +813,4 @@ Check out the `tests/examples/` directory for more usage examples:
 
 ---
 
-Made with ❤️ for Python developers who value type safety and clean configuration management.
+Made with ❤️ for Python developers who value type safety and clean configuration management.# path-link