fix: report a locked folder as FolderLockedException

Fetching a locked folder before its password is sent returns 200 with
only its listing fields, without metadata, sub_folders and path, so
FoldersApi.retrieve failed with a pydantic ValidationError. The DOI
route fetches the folder before it can see the lock, so a
password-protected DOI folder could not be opened even with its
password.

- Add FolderLockedException, a subclass of UnauthorizedException, and
  raise it from retrieve on that short record and from the lock checks.
- On a DOI folder, send the password and fetch it again when the first
  fetch finds it locked.

mdrsclient/api/folders.py

@@ -6,7 +6,7 @@ from pydantic.dataclasses import dataclass
 
 from mdrsclient.api.base import BaseApi
 from mdrsclient.api.utils import retry_on_expired_token, token_check
-from mdrsclient.exceptions import UnauthorizedException
+from mdrsclient.exceptions import FolderLockedException, UnauthorizedException
 from mdrsclient.models import Folder, FolderSimple
 
 
@@ -38,7 +38,12 @@ class FoldersApi(BaseApi):
         token_check(self.connection)
         response = self.connection.get(url)
         self._raise_response_error(response)
-        ret = TypeAdapter(Folder).validate_python(response.json())
+        data = response.json()
+        # A locked folder not yet opened with its password comes back with 200 but only
+        # its listing fields, without `metadata`, `sub_folders` and `path`.
+        if data.get("lock") and "sub_folders" not in data:
+            raise FolderLockedException(f"Folder `{data.get('name', id)}` is locked.")
+        ret = TypeAdapter(Folder).validate_python(data)
         return ret
 
     @retry_on_expired_token