Add IntOrUUIDConverter URL converter (#801)

Ref:
https://docs.djangoproject.com/en/4.2/topics/http/urls/#registering-custom-path-converters

## Description
This PR adds a new `IntOrUUIDConverter` URL converter that can handle
both integer and UUID values in Django URL patterns. This converter
provides a flexible way to accept either integers or UUIDs in a single
URL parameter, which is useful for APIs that need to support both legacy
integer IDs and newer UUID-based identifiers.

- **What is being changed?** Adding a new URL converter class
`IntOrUUIDConverter` in `ansible_base.lib.utils.converters`
- **Why is this change needed?** To support URL patterns that can accept
either integer or UUID parameters
- **How does this change address the issue?** The converter uses regex
matching and type conversion to handle both data types seamlessly

## Type of Change
- [x] New feature (non-breaking change which adds functionality)

## Self-Review Checklist
- [x] I have performed a self-review of my code
- [x] I have added relevant comments to complex code sections
- [x] I have updated documentation where needed
- [x] I have considered the security impact of these changes
- [x] I have considered performance implications
- [x] I have thought about error handling and edge cases
- [x] I have tested the changes in my local environment

## Testing Instructions

### Prerequisites
- Django development environment set up
- pytest installed

### Steps to Test
1. Import the converter: `from ansible_base.lib.utils.converters import
IntOrUUIDConverter`
2. Test integer conversion: `converter.to_python("123")` should return
`int(123)`
3. Test UUID conversion:
`converter.to_python("550e8400-e29b-41d4-a716-446655440000")` should
return a `UUID` object
4. Test invalid input: `converter.to_python("invalid")` should raise
`ValueError`
5. Run the test suite: `pytest
test_app/tests/lib/utils/test_converters.py`

### Expected Results
- Integer strings are converted to Python `int` objects
- UUID strings are converted to Python `UUID` objects  
- Invalid inputs raise `ValueError` with descriptive message
- The `to_url()` method converts both types back to string
representation
- All tests in the comprehensive test suite pass

## Additional Context

### Implementation Details
- Uses a regex pattern that matches both integers (`[0-9]+`) and
standard UUID format
- Prioritizes integer conversion (checks `isdigit()` first) for
performance
- Handles edge cases like uppercase UUIDs, very large integers, and
invalid formats
- Includes comprehensive test coverage (169 lines of tests for 23 lines
of code)

### Required Actions
- [ ] Requires documentation updates
- [ ] Requires downstream repository changes
- [ ] Requires infrastructure/deployment changes
- [ ] Requires coordination with other teams
- [ ] Blocked by PR/MR: #XXX

Author: fao89

ansible_base/lib/utils/converters.py

@@ -0,0 +1,24 @@
+"""
+Reference:
+- https://docs.djangoproject.com/en/4.2/topics/http/urls/#registering-custom-path-converters
+- https://github.com/django/django/blob/fda3c1712a1eb7b20dfc91e6c9abae32bd64d081/django/urls/converters.py
+"""
+
+import uuid
+
+
+class IntOrUUIDConverter:
+    regex = "([0-9]+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})"
+
+    def to_python(self, value):
+        # Try int first (simpler check)
+        if value.isdigit():
+            return int(value)
+        # Otherwise try UUID
+        try:
+            return uuid.UUID(value)
+        except ValueError:
+            raise ValueError(f"'{value}' is not a valid integer or UUID")
+
+    def to_url(self, value):
+        return str(value)

ansible_base/rbac/urls.py

@@ -1,5 +1,6 @@
-from django.urls import include, path
+from django.urls import include, path, register_converter
 
+from ansible_base.lib.utils.converters import IntOrUUIDConverter
 from ansible_base.rbac.api.router import router
 from ansible_base.rbac.api.views import RoleMetadataView, TeamAccessAssignmentViewSet, TeamAccessViewSet, UserAccessAssignmentViewSet, UserAccessViewSet
 from ansible_base.rbac.apps import AnsibleRBACConfig
@@ -11,18 +12,19 @@
 user_access_assignment_view = UserAccessAssignmentViewSet.as_view({'get': 'list'})
 team_access_assignment_view = TeamAccessAssignmentViewSet.as_view({'get': 'list'})
 
+register_converter(IntOrUUIDConverter, "int_or_uuid")
 api_version_urls = [
     path('', include(router.urls)),
     path(r'role_metadata/', RoleMetadataView.as_view(), name="role-metadata"),
-    path('role_user_access/<str:model_name>/<int:pk>/', user_access_view, name="role-user-access"),
-    path('role_team_access/<str:model_name>/<int:pk>/', team_access_view, name="role-team-access"),
+    path('role_user_access/<str:model_name>/<int_or_uuid:pk>/', user_access_view, name="role-user-access"),
+    path('role_team_access/<str:model_name>/<int_or_uuid:pk>/', team_access_view, name="role-team-access"),
     path(
-        'role_user_access/<str:model_name>/<int:pk>/<str:actor_pk>/',
+        'role_user_access/<str:model_name>/<int_or_uuid:pk>/<str:actor_pk>/',
         user_access_assignment_view,
         name='role-user-access-assignments',
     ),
     path(
-        'role_team_access/<str:model_name>/<int:pk>/<str:actor_pk>/',
+        'role_team_access/<str:model_name>/<int_or_uuid:pk>/<str:actor_pk>/',
         team_access_assignment_view,
         name='role-team-access-assignments',
     ),

test_app/tests/lib/utils/test_converters.py

@@ -0,0 +1,153 @@
+import uuid
+
+import pytest
+
+from ansible_base.lib.utils.converters import IntOrUUIDConverter
+
+
+class TestIntOrUUIDConverter:
+    """Test cases for the IntOrUUIDConverter class."""
+
+    def test_regex_pattern(self):
+        """Test that the regex pattern is correctly defined."""
+        converter = IntOrUUIDConverter()
+        assert converter.regex == "([0-9]+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})"
+
+    @pytest.mark.parametrize(
+        "value,expected_type,expected_value",
+        [
+            # Integer cases
+            ("1", int, 1),
+            ("123", int, 123),
+            ("999999", int, 999999),
+            ("0", int, 0),
+            # UUID cases
+            ("550e8400-e29b-41d4-a716-446655440000", uuid.UUID, uuid.UUID("550e8400-e29b-41d4-a716-446655440000")),
+            ("6ba7b810-9dad-11d1-80b4-00c04fd430c8", uuid.UUID, uuid.UUID("6ba7b810-9dad-11d1-80b4-00c04fd430c8")),
+            ("6ba7b811-9dad-11d1-80b4-00c04fd430c8", uuid.UUID, uuid.UUID("6ba7b811-9dad-11d1-80b4-00c04fd430c8")),
+            # UUID without dashes (valid format for uuid.UUID)
+            ("550e8400e29b41d4a716446655440000", uuid.UUID, uuid.UUID("550e8400e29b41d4a716446655440000")),
+        ],
+    )
+    def test_to_python_valid_values(self, value, expected_type, expected_value):
+        """Test that valid integers and UUIDs are correctly converted."""
+        converter = IntOrUUIDConverter()
+        result = converter.to_python(value)
+        assert isinstance(result, expected_type)
+        assert result == expected_value
+
+    @pytest.mark.parametrize(
+        "invalid_value",
+        [
+            # Invalid integers (negative or with non-digits)
+            "-1",
+            "12.34",
+            "1.0",
+            "12a",
+            "a12",
+            # Invalid UUIDs
+            "not-a-uuid",
+            "550e8400-e29b-41d4-a716",  # Too short
+            "550e8400-e29b-41d4-a716-446655440000-extra",  # Too long
+            "550e8400-e29b-41d4-a716-44665544000z",  # Invalid character
+            # Note: "550e8400e29b41d4a716446655440000" (missing dashes) is actually valid for uuid.UUID()
+            # Empty/None cases
+            "",
+            "   ",
+            # Mixed invalid cases
+            "name",
+            "name surname",
+            "123-456",
+            "uuid-like-string",
+            "12345-67890-abcde",
+        ],
+    )
+    def test_to_python_invalid_values(self, invalid_value):
+        """Test that invalid values raise ValueError."""
+        converter = IntOrUUIDConverter()
+        with pytest.raises(ValueError) as exc_info:
+            converter.to_python(invalid_value)
+        assert f"'{invalid_value}' is not a valid integer or UUID" in str(exc_info.value)
+
+    def test_to_python_large_integer(self):
+        """Test that very large integers are handled correctly."""
+        converter = IntOrUUIDConverter()
+        large_int_str = "999999999999999999999"
+        result = converter.to_python(large_int_str)
+        assert isinstance(result, int)
+        assert result == int(large_int_str)
+
+    @pytest.mark.parametrize(
+        "input_value,expected_output",
+        [
+            # Integer inputs
+            (1, "1"),
+            (123, "123"),
+            (0, "0"),
+            (999999, "999999"),
+            # UUID inputs
+            (uuid.UUID("550e8400-e29b-41d4-a716-446655440000"), "550e8400-e29b-41d4-a716-446655440000"),
+            (uuid.UUID("6ba7b810-9dad-11d1-80b4-00c04fd430c8"), "6ba7b810-9dad-11d1-80b4-00c04fd430c8"),
+            # String inputs (should work with str() call)
+            ("test", "test"),
+            ("123", "123"),
+        ],
+    )
+    def test_to_url(self, input_value, expected_output):
+        """Test that various types are correctly converted to URL strings."""
+        converter = IntOrUUIDConverter()
+        result = converter.to_url(input_value)
+        assert result == expected_output
+        assert isinstance(result, str)
+
+    def test_to_python_int_priority(self):
+        """Test that numeric strings are treated as integers, not UUIDs."""
+        converter = IntOrUUIDConverter()
+        # This string could theoretically be interpreted as a UUID segment,
+        # but should be treated as an integer since it's all digits
+        result = converter.to_python("12345678")
+        assert isinstance(result, int)
+        assert result == 12345678
+
+    def test_uuid_case_handling(self):
+        """Test UUID case handling - uppercase UUIDs are actually valid in uuid.UUID()."""
+        converter = IntOrUUIDConverter()
+
+        # Test with uppercase UUID - uuid.UUID() accepts uppercase
+        uppercase_uuid = "550E8400-E29B-41D4-A716-446655440000"
+        result = converter.to_python(uppercase_uuid)
+        assert isinstance(result, uuid.UUID)
+        # UUID string representation is always lowercase
+        assert str(result) == "550e8400-e29b-41d4-a716-446655440000"
+
+        # Test with lowercase UUID (should work)
+        lowercase_uuid = "550e8400-e29b-41d4-a716-446655440000"
+        result = converter.to_python(lowercase_uuid)
+        assert isinstance(result, uuid.UUID)
+        assert str(result) == lowercase_uuid
+
+    def test_uuid_validation_error_handling(self):
+        """Test that UUID validation errors are properly caught and re-raised."""
+        converter = IntOrUUIDConverter()
+
+        # Test with a string that's not digits but also not a valid UUID
+        invalid_uuid = "this-is-not-a-uuid-at-all"
+        with pytest.raises(ValueError) as exc_info:
+            converter.to_python(invalid_uuid)
+        assert f"'{invalid_uuid}' is not a valid integer or UUID" in str(exc_info.value)
+
+    def test_roundtrip_conversion(self):
+        """Test that to_python and to_url work correctly together."""
+        converter = IntOrUUIDConverter()
+
+        # Test integer roundtrip
+        int_str = "12345"
+        int_val = converter.to_python(int_str)
+        url_str = converter.to_url(int_val)
+        assert url_str == int_str
+
+        # Test UUID roundtrip
+        uuid_str = "550e8400-e29b-41d4-a716-446655440000"
+        uuid_val = converter.to_python(uuid_str)
+        url_str = converter.to_url(uuid_val)
+        assert url_str == uuid_str