Socket_Singleton v2.0.0

Major Release: Code Quality Overhaul & New Features

This release represents a comprehensive refactoring of Socket_Singleton after 5 years,
focusing on improved code quality, new features, and maintainability while maintaining
backward compatibility with existing code.

🎉 New Features

• verbose parameter: Optional logging for debugging connection failures, encoding errors, and observer exceptions
• secret parameter: Client verification to prevent unauthorized applications from injecting arguments
• release_threshold parameter: (Formerly max_clients) Releases port after N client connections
• max_clients: Stops processing arguments after N clients
• Input validation: Proper ValueError exceptions for invalid constructor parameters

🔧 Improvements

• Argument handling: Clients now send complete argument sets as tuples, preserving context for each invocation.
• Robust delimiter: Changed from newline (\n) to null byte (\x00) for more reliable argument parsing
• Cross-platform error handling: Improved Windows compatibility
• Enhanced error recovery: Better handling of connection failures, encoding errors, and observer exceptions
• Improved properties: arguments now returns immutable snapshot, better __str__ and __repr__ methods

🧪 Testing

• Comprehensive test suite: 32 tests covering all functionality
• Organized test architecture: 7 test classes for different concerns
• Reliable subprocess testing: Improved test helpers for parallel execution

📚 Documentation

• Complete readme reorganization: Clear sections for installation, usage, parameters, and examples
• Enhanced examples: Comprehensive examples for all features including secret verification
• Testing guide: Added section on how to run and structure tests

🛠️ Developer Experience

• Code formatting: Added Black and isort configuration via pyproject.toml
• Editor integration: VSCode/Cursor settings for format-on-save
• Better docstrings: Comprehensive documentation throughout the codebase

🐛 Bug Fixes

• Fixed release_threshold comparison logic
• Fixed argument consumption when no observers registered
• Fixed hardcoded localhost addresses
• Fixed observer exception handling to prevent server crashes
• Various edge case improvements

⚠️ Breaking Changes

This release maintains backward compatibility for most use cases, but includes two breaking changes:

1. max_clients Parameter Behavior

• Old behavior: max_clients released the port after N client connections
• New behavior: max_clients only stops processing arguments after N clients (port remains bound)
• Migration: Use release_threshold if you need the old port-release behavior

2. trace() Observer Callback Signature

• Old behavior: Callbacks received individual arguments as separate calls (one per argument)
• New behavior: Callbacks receive a single tuple containing all arguments from a client process
• Migration: Update your observer functions to accept (args_tuple, ...) instead of (arg, ...)

This code can cause a lot of extra churn in your codebase without the context of the rest of the arguments for the given invocation:

# Old: callback(arg) called multiple times
def callback(arg):
	print(arg)

Now we have all the arguments per invocation at once, and immediately do something meaningful:

# New: callback(args_tuple) called once per client
def callback(args_tuple):
    print(' '.join(args_tuple))

No need to think about timing or the structure of what a meaningful set of arguments look like in the context of your application before getting along with the rest of your business logic.

📦 Installation

pip install Socket_Singleton -U

🔗 Links

• Documentation
• Test Suite

1.0

Version 1.0

• New clients property
• arguments is a property now
• max_clients kwarg

We're on PyPi now.

pip install Socket_Singleton