unctools 0.1.0__tar.gz

unctools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dustin Darcy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unctools-0.1.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include setup.py
+include setup.cfg
+include MANIFEST.in
+
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include docs *.md *.rst *.txt *.png *.jpg
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[cod]
+recursive-exclude * *.so
+recursive-exclude * .DS_Store
+recursive-exclude * Thumbs.db

unctools-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: unctools
+Version: 0.1.0
+Summary: A comprehensive toolkit for handling UNC paths, network drives, and substituted drives
+Home-page: https://github.com/djdacy/unctools
+Author: Dustin Darcy
+Author-email: Dustin Darcy <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/djdarcy/unctools
+Project-URL: Bug Reports, https://github.com/djdarcy/unctools/issues
+Project-URL: Source, https://github.com/djdarcy/unctools
+Project-URL: Documentation, https://github.com/djdarcy/unctools#readme
+Keywords: unc,network,windows,path,file,share,subst
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pathlib; python_version < "3.4"
+Provides-Extra: windows
+Requires-Dist: pywin32>=223; extra == "windows"
+Requires-Dist: pypiwin32>=223; extra == "windows"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.10.0; extra == "dev"
+Requires-Dist: flake8>=3.8.0; extra == "dev"
+Requires-Dist: black>=20.8b1; extra == "dev"
+Requires-Dist: tox>=3.20.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=0.5.0; extra == "docs"
+Requires-Dist: myst-parser>=0.15.0; extra == "docs"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# UNCtools
+
+A comprehensive toolkit for handling UNC paths, network drives, and substituted drives across different environments.
+
+## Features
+
+- Convert between UNC paths (\\\\server\\share) and local drive paths (Z:\\)
+- Detect UNC paths, network drives, and substituted drives
+- Handle Windows security zones for improved UNC path access
+- Provide high-level file operations that work seamlessly with UNC paths
+- Cross-platform compatibility with graceful degradation
+
+## Installation
+
+### Standard Installation
+
+```bash
+pip install unctools
+```
+
+### With Windows-specific Support
+
+```bash
+pip install unctools[windows]
+```
+
+### Development Mode
+
+For development and testing:
+
+```bash
+git clone https://github.com/yourusername/unctools.git
+cd unctools
+pip install -e .[dev]
+```
+
+## Usage
+
+### Basic Path Conversion
+
+```python
+from unctools import convert_to_local, convert_to_unc
+
+# Convert UNC path to local drive path
+local_path = convert_to_local("\\\\server\\share\\folder\\file.txt")
+# Result (if mapped): "Z:\\folder\\file.txt"
+
+# Convert local drive path back to UNC
+unc_path = convert_to_unc("Z:\\folder\\file.txt")
+# Result: "\\\\server\\share\\folder\\file.txt"
+```
+
+### Path Detection
+
+```python
+from unctools import is_unc_path, is_network_drive, is_subst_drive, get_path_type
+
+# Check if a path is a UNC path
+if is_unc_path("\\\\server\\share\\file.txt"):
+    print("This is a UNC path")
+
+# Check if a drive is a network drive
+if is_network_drive("Z:"):
+    print("Z: is a network drive")
+
+# Get the type of a path
+path_type = get_path_type("C:\\Users\\")
+# Result: "local", "network", "subst", "unc", etc.
+```
+
+### Safe File Operations
+
+```python
+from unctools import safe_open, safe_copy, batch_convert
+
+# Open a file, handling UNC paths automatically
+with safe_open("\\\\server\\share\\file.txt", "r") as f:
+    content = f.read()
+
+# Copy a file, handling path conversions
+safe_copy("\\\\server\\share\\file.txt", "local_copy.txt")
+
+# Convert multiple paths at once
+paths = ["\\\\server\\share\\file1.txt", "\\\\server\\share\\file2.txt"]
+converted = batch_convert(paths, to_unc=False)
+```
+
+### Windows Security Zones
+
+```python
+from unctools.windows import fix_security_zone, add_to_intranet_zone
+
+# Fix security zone issues for a server
+fix_security_zone("server")
+
+# Add a server to the Local Intranet zone
+add_to_intranet_zone("server")
+```
+
+### Network Drive Management
+
+```python
+from unctools.windows import create_network_mapping, remove_network_mapping
+
+# Create a network drive mapping
+success, drive = create_network_mapping("\\\\server\\share", "Z:")
+
+# Remove a network drive mapping
+remove_network_mapping("Z:")
+```
+
+## Platform Compatibility
+
+UNCtools is designed to work across various platforms:
+
+- **Windows**: Full functionality including security zones and network drive management
+- **Linux/macOS**: Basic path conversion and detection, with graceful degradation for Windows-specific features
+
+## Development
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Style
+
+```bash
+black unctools
+flake8 unctools
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

unctools-0.1.0/README.md

@@ -0,0 +1,140 @@
+# UNCtools
+
+A comprehensive toolkit for handling UNC paths, network drives, and substituted drives across different environments.
+
+## Features
+
+- Convert between UNC paths (\\\\server\\share) and local drive paths (Z:\\)
+- Detect UNC paths, network drives, and substituted drives
+- Handle Windows security zones for improved UNC path access
+- Provide high-level file operations that work seamlessly with UNC paths
+- Cross-platform compatibility with graceful degradation
+
+## Installation
+
+### Standard Installation
+
+```bash
+pip install unctools
+```
+
+### With Windows-specific Support
+
+```bash
+pip install unctools[windows]
+```
+
+### Development Mode
+
+For development and testing:
+
+```bash
+git clone https://github.com/yourusername/unctools.git
+cd unctools
+pip install -e .[dev]
+```
+
+## Usage
+
+### Basic Path Conversion
+
+```python
+from unctools import convert_to_local, convert_to_unc
+
+# Convert UNC path to local drive path
+local_path = convert_to_local("\\\\server\\share\\folder\\file.txt")
+# Result (if mapped): "Z:\\folder\\file.txt"
+
+# Convert local drive path back to UNC
+unc_path = convert_to_unc("Z:\\folder\\file.txt")
+# Result: "\\\\server\\share\\folder\\file.txt"
+```
+
+### Path Detection
+
+```python
+from unctools import is_unc_path, is_network_drive, is_subst_drive, get_path_type
+
+# Check if a path is a UNC path
+if is_unc_path("\\\\server\\share\\file.txt"):
+    print("This is a UNC path")
+
+# Check if a drive is a network drive
+if is_network_drive("Z:"):
+    print("Z: is a network drive")
+
+# Get the type of a path
+path_type = get_path_type("C:\\Users\\")
+# Result: "local", "network", "subst", "unc", etc.
+```
+
+### Safe File Operations
+
+```python
+from unctools import safe_open, safe_copy, batch_convert
+
+# Open a file, handling UNC paths automatically
+with safe_open("\\\\server\\share\\file.txt", "r") as f:
+    content = f.read()
+
+# Copy a file, handling path conversions
+safe_copy("\\\\server\\share\\file.txt", "local_copy.txt")
+
+# Convert multiple paths at once
+paths = ["\\\\server\\share\\file1.txt", "\\\\server\\share\\file2.txt"]
+converted = batch_convert(paths, to_unc=False)
+```
+
+### Windows Security Zones
+
+```python
+from unctools.windows import fix_security_zone, add_to_intranet_zone
+
+# Fix security zone issues for a server
+fix_security_zone("server")
+
+# Add a server to the Local Intranet zone
+add_to_intranet_zone("server")
+```
+
+### Network Drive Management
+
+```python
+from unctools.windows import create_network_mapping, remove_network_mapping
+
+# Create a network drive mapping
+success, drive = create_network_mapping("\\\\server\\share", "Z:")
+
+# Remove a network drive mapping
+remove_network_mapping("Z:")
+```
+
+## Platform Compatibility
+
+UNCtools is designed to work across various platforms:
+
+- **Windows**: Full functionality including security zones and network drive management
+- **Linux/macOS**: Basic path conversion and detection, with graceful degradation for Windows-specific features
+
+## Development
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Style
+
+```bash
+black unctools
+flake8 unctools
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

unctools-0.1.0/docs/implementation-guide.md

@@ -0,0 +1,213 @@
+# UNCtools - Implementation Guide and Testing Instructions
+
+## Implementation Status
+
+We have successfully completed the initial implementation of the UNCtools package with the following components:
+
+### Core Module Structure
+- ✅ `unctools/__init__.py` - Package initialization and exports
+- ✅ `unctools/converter.py` - Path conversion utilities
+- ✅ `unctools/detector.py` - Path type detection utilities
+- ✅ `unctools/operations.py` - High-level file operations
+
+### Utility Modules
+- ✅ `unctools/utils/__init__.py` - Utilities package initialization
+- ✅ `unctools/utils/logger.py` - Logging configuration
+- ✅ `unctools/utils/compat.py` - Cross-platform compatibility
+- ✅ `unctools/utils/validation.py` - Path validation
+
+### Windows-Specific Modules
+- ✅ `unctools/windows/__init__.py` - Windows package initialization
+- ✅ `unctools/windows/registry.py` - Registry operations
+- ✅ `unctools/windows/network.py` - Network operations
+- ✅ `unctools/windows/security.py` - Security operations
+
+### Package Files
+- ✅ `setup.py` - Installation script
+- ✅ `setup.cfg` - Package configuration
+- ✅ `pyproject.toml` - Modern packaging
+- ✅ `MANIFEST.in` - Package file inclusion
+- ✅ `LICENSE` - MIT License
+- ✅ `README.md` - Package documentation
+- ✅ `.gitignore` - Git ignore patterns
+
+### Examples and Tests
+- ✅ `examples/basic_usage.py` - Basic usage examples
+- ✅ `examples/windows_zone_fix.py` - Windows security zone fixing
+- ✅ `examples/batch_operations.py` - Batch file operations
+- ✅ `tests/__init__.py` - Tests package initialization
+- ✅ `tests/test_converter.py` - Test for the converter module
+- ✅ `tests/basic_functionality_test.py` - Basic functionality verification
+
+## Testing Instructions
+
+To test the UNCtools package, follow these steps:
+
+### 1. Install in Development Mode
+
+First, install the package in development mode to allow for easy modifications:
+
+```bash
+# Navigate to the UNCtools directory
+cd path/to/unctools
+
+# Install in development mode
+pip install -e .
+
+# To include Windows-specific dependencies (on Windows)
+pip install -e ".[windows]"
+
+# To include development tools
+pip install -e ".[dev]"
+```
+
+### 2. Run Basic Functionality Test
+
+Test that the core functionality works correctly:
+
+```bash
+python tests/basic_functionality_test.py
+```
+
+This script verifies that all modules can be imported and basic functions work as expected.
+
+### 3. Test Path Conversion
+
+Test UNC path conversion with:
+
+```bash
+# On Windows with a mapped network drive (e.g., Z: mapped to \\server\share)
+python examples/basic_usage.py
+```
+
+Look for proper path conversion and detection in the output.
+
+### 4. Test Batch Operations
+
+Test batch operations with:
+
+```bash
+# Convert paths in a directory
+python examples/batch_operations.py convert /path/to/directory --pattern "*.txt" --recursive
+
+# Copy files from a directory to another location
+python examples/batch_operations.py copy /path/to/source --dest /path/to/destination --pattern "*.txt" --recursive
+
+# Process files in a directory
+python examples/batch_operations.py process /path/to/directory --pattern "*.txt" --recursive
+```
+
+### 5. Test Windows-Specific Features (Windows Only)
+
+Test Windows security zone features with:
+
+```bash
+# Check and fix security zone issues for a UNC path
+python examples/windows_zone_fix.py "\\server\share\folder"
+
+# Scan a directory for UNC paths and fix security zones
+python examples/windows_zone_fix.py --scan /path/to/directory --fix-all
+```
+
+### 6. Run Unit Tests
+
+Run the unit tests for individual modules:
+
+```bash
+# Run all tests
+pytest
+
+# Run tests for a specific module
+pytest tests/test_converter.py
+```
+
+## Expected Output
+
+The basic functionality test should produce output similar to:
+
+```
+=== UNCtools Basic Functionality Tests ===
+
+Testing imports...
+✓ Import unctools
+
+Checking version information...
+✓ UNCtools version: 0.1.0
+
+Testing core module imports...
+✓ Import core functions
+
+Testing utils module imports...
+✓ Import utils functions
+
+Testing Windows-specific module imports...
+✓ Import Windows-specific functions
+
+Testing basic functionality...
+✓ is_unc_path(C:\Users\username) should be False
+✓ is_unc_path(\\server\share\folder) should be True
+✓ normalize_path(C:\Users\username) => C:\Users\username
+✓ convert_to_local(\\server\share\folder) => \\server\share\folder
+✓ convert_to_unc(C:\Users\username) => C:\Users\username
+✓ batch_convert() returned 2 results
+✓ Platform information: system: Windows, release: 10, ...
+
+Testing file operations with a temporary file...
+✓ safe_open() and read content: 'UNCtools test file'
+✓ Temporary file operations completed
+
+=== Test Summary ===
+Platform: Windows 10
+Python: 3.8.10
+UNCtools: 0.1.0
+All tests completed. Check the results above for any failures.
+
+Basic functionality tests completed successfully.
+```
+
+## Common Issues and Troubleshooting
+
+### Import Errors
+
+If you see import errors:
+
+```
+✗ Import unctools: No module named 'unctools'
+```
+
+Ensure you've installed the package in development mode and are running Python from the correct environment.
+
+### Missing Windows Functionality
+
+If Windows-specific features are unavailable:
+
+```
+✗ Import Windows-specific functions: No module named 'win32api'
+```
+
+Install the Windows extras:
+
+```bash
+pip install -e ".[windows]"
+```
+
+### Path Conversion Issues
+
+If path conversion doesn't work as expected, check:
+
+1. Your network drive mappings are active
+2. The UNC paths are correctly formatted
+3. You have appropriate permissions for the paths
+
+## Next Steps
+
+After completing these tests, we should:
+
+1. Expand the test suite with more comprehensive tests
+2. Create detailed API documentation
+3. Consider integration with your existing tools like `psdelta.py`
+4. Prepare for PyPI distribution
+
+## Conclusion
+
+This initial implementation provides a solid foundation for the UNCtools package. By following these testing instructions, you can verify that the package works correctly in your environment and identify any issues that need to be addressed before further development.

unctools-0.1.0/docs/implementation-summary.md

@@ -0,0 +1,129 @@
+# UNCtools Implementation Summary
+
+## Project Overview
+
+UNCtools is a comprehensive Python package for handling UNC paths, network drives, and substituted drives across different environments. It provides tools for path conversion, detection, and seamless file operations with proper handling of Windows-specific features.
+
+## Implemented Components
+
+### Core Modules
+
+1. **`converter.py`**
+   - UNC ⇔ local path conversion
+   - Path normalization
+   - UNC path parsing and construction
+
+2. **`detector.py`**
+   - Path type detection (UNC, network drive, subst drive)
+   - Network mapping discovery
+   - Path issue detection
+
+3. **`operations.py`**
+   - Safe file operations
+   - Batch path conversion
+   - File processing utilities 
+
+### Windows-Specific Modules
+
+1. **`windows/registry.py`**
+   - Windows security zone management
+   - Registry operations
+
+2. **`windows/network.py`**
+   - Network drive mapping creation/removal
+   - Share management
+   - Network connection testing
+
+### Package Infrastructure
+
+1. **Package structure**
+   - Proper organization with sub-packages
+   - Clear separation of Windows-specific functionality
+
+2. **Documentation**
+   - Comprehensive docstrings
+   - README with usage examples
+   - Example scripts
+
+3. **Distribution**
+   - `setup.py` for pip installation
+   - `pyproject.toml` for modern packaging
+   - Optional dependencies
+
+4. **Testing**
+   - Unit tests for core functionality
+   - Test infrastructure
+
+## Key Features
+
+1. **Path Conversion**
+   - Convert between UNC paths and mapped drive paths
+   - Support for multiple path formats
+   - Cross-platform compatible with graceful degradation
+
+2. **Path Detection**
+   - Identify UNC paths, network drives, and substituted drives
+   - Determine path types and detect potential issues
+   - Windows-specific drive type detection
+
+3. **File Operations**
+   - Safe file opening with automatic path conversion
+   - Batch file operations
+   - Path accessibility checks
+
+4. **Windows Integration**
+   - Security zone management for UNC paths
+   - Network drive mapping and share administration
+   - Detailed logging and error handling
+
+5. **Extensibility**
+   - Well-defined interfaces for future additions
+   - Modular design for optional components
+   - Fallback mechanisms when dependencies aren't available
+
+## Next Steps
+
+### Immediate Tasks
+
+1. **Testing**
+   - Complete test suite for all modules
+   - Add integration tests that exercise real file system access
+   - Implement Windows-specific tests that can be conditionally skipped
+
+2. **Documentation**
+   - Add more example scripts demonstrating different use cases
+   - Create detailed API documentation with Sphinx
+   - Add tutorials for common scenarios
+
+3. **Edge Case Handling**
+   - Add more robust error handling for network failures
+   - Implement retry logic for transient issues
+   - Enhance logging with more detailed diagnostics
+
+### Future Enhancements
+
+1. **Extended Platform Support**
+   - Add better support for macOS network shares
+   - Implement Linux SMB/CIFS compatibility
+   - Support for other network file systems
+
+2. **Advanced Windows Features**
+   - Support for Windows credential management
+   - Integration with admin privileges and UAC
+   - Advanced security and permission handling
+
+3. **Performance Optimizations**
+   - Caching strategies for path conversions
+   - Lazy initialization for better startup time
+   - Parallel processing for batch operations
+
+4. **Integration with Other Tools**
+   - File synchronization utilities
+   - Backup tools
+   - Development environment integrations
+
+## Conclusion
+
+The initial implementation of UNCtools provides a solid foundation for handling UNC paths and network drives across different environments. The modular design allows for easy extension and customization, while the cross-platform approach ensures usability beyond Windows environments.
+
+The package addresses the core issues identified from previous tools like `psdelta.py`, `temp_renamer.py`, and `dazzlelink.py`, consolidating their UNC path handling capabilities into a single, reusable library with a clear API and comprehensive documentation.