housekeeping

- ruff formatter
- readme
- license
- pyproject updates

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Marcin Kornat
+
+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.

README.md

@@ -1 +1,41 @@
-https://docs.photoprism.dev/#/
+# Photoprism Python API Client
+
+## Installation
+
+```bash
+pip install photoprism
+```
+
+## Usage
+
+```python
+import asyncio
+from pathlib import Path
+
+from photoprism import PhotoprismSession, PhotoprismClient
+from photoprism.models.query import Size
+
+
+async def main():
+    session = PhotoprismSession(
+        username="username",
+        password="password",
+        host="localhost",
+        protocol="http",
+    )
+    client = PhotoprismClient(session)
+
+    albums = await client.albums.filter(count=3, q="cats")
+    for album in albums:
+        image_path = await client.albums.download_cover_image(
+            album_uid=album.uid,
+            size=Size.Tile50,
+            file_dir=Path("data/album_covers"),
+        )
+        print(image_path)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())
+
+```

photoprism/__init__.py

@@ -0,0 +1,2 @@
+from photoprism.session import PhotoprismSession
+from photoprism.client import PhotoprismClient

photoprism/api/__init__.py

@@ -6,3 +6,15 @@
 from photoprism.api.errors import PhotoprismErrorsApi
 from photoprism.api.faces import PhotoprismFacesApi
 from photoprism.api.library import PhotoprismLibraryApi
+
+
+__all__ = [
+    "PhotoprismConfigApi",
+    "PhotoprismAlbumsApi",
+    "PhotoprismLabelsApi",
+    "PhotoprismPhotosApi",
+    "PhotoprismFilesApi",
+    "PhotoprismErrorsApi",
+    "PhotoprismFacesApi",
+    "PhotoprismLibraryApi",
+]

photoprism/api/albums.py

@@ -7,11 +7,11 @@
 
 class PhotoprismAlbumsApi(PhotoprismApiBase):
     async def filter(
-            self,
-            count: int,
-            offset: int | None = None,
-            order: Literal["favorites", "name", "title", "added", "edited"] | None = None,
-            q: str | None = None,
+        self,
+        count: int,
+        offset: int | None = None,
+        order: Literal["favorites", "name", "title", "added", "edited"] | None = None,
+        q: str | None = None,
     ) -> list[search.Album]:
         data = await self._session.req(
             method="GET",
@@ -21,7 +21,7 @@ async def filter(
                 "offset": offset,
                 "order": order,
                 "q": q,
-            }
+            },
         )
         return [search.Album(**item) for item in data]
 
@@ -39,15 +39,11 @@ async def create(self, title: str, favorite: bool = False) -> entity.Album:
             data={
                 "Title": title,
                 "Favorite": favorite,
-            }
+            },
         )
         return entity.Album(**data)
 
-    async def update(
-        self,
-        album_uid: str,
-        album_data: form.Album
-    ) -> entity.Album:
+    async def update(self, album_uid: str, album_data: form.Album) -> entity.Album:
         data = await self._session.req(
             method="PUT",
             path="albums/{}".format(album_uid),
@@ -72,13 +68,9 @@ async def batch_delete(self, album_uids: list[str]) -> None:
         )
 
     async def clone(
-        self,
-        source_album_uids: list[str],
-        destination_album_uid: str
+        self, source_album_uids: list[str], destination_album_uid: str
     ) -> entity.Album:
-        selection_data = form.Selection(
-            albums=source_album_uids
-        )
+        selection_data = form.Selection(albums=source_album_uids)
         data = await self._session.req(
             method="POST",
             path="albums/{}/clone".format(destination_album_uid),
@@ -170,7 +162,7 @@ async def add_photos(
             albums=albums,
             labels=labels,
             places=places,
-            subjects=subjects
+            subjects=subjects,
         )
         data = await self._session.req(
             method="POST",
@@ -224,4 +216,3 @@ async def download_cover_image(
             filename=filename,
             mode="DOWNLOAD",
         )
-

photoprism/api/files.py

@@ -13,10 +13,7 @@ async def get_by_uid(self, file_hash: str) -> entity.File:
         return entity.File(**data)
 
     async def download(
-        self,
-        file_hash: str,
-        file_dir: Path,
-        filename: str | None = None
+        self, file_hash: str, file_dir: Path, filename: str | None = None
     ) -> Path:
         return await self._session.req(
             method="GET",
@@ -68,10 +65,7 @@ async def delete(self, photo_uid: str, file_uid: str) -> entity.Photo:
         return entity.Photo(**data)
 
     async def update_orientation(
-        self,
-        photo_uid: str,
-        file_uid: str,
-        orientation: int
+        self, photo_uid: str, file_uid: str, orientation: int
     ) -> entity.Photo:
         orientation_data = form.File(orientation=orientation)
         data = await self._session.req(

photoprism/api/labels.py

@@ -1,5 +1,4 @@
 from pathlib import Path
-from pprint import pprint
 
 from photoprism.api.base import PhotoprismApiBase
 from photoprism.models import form, search, entity, query
@@ -8,9 +7,7 @@
 class PhotoprismLabelsApi(PhotoprismApiBase):
     async def search(self, search_labels: form.SearchLabels) -> list[search.Label]:
         data = await self._session.req(
-            method='GET',
-            path='labels',
-            params=search_labels.model_dump()
+            method="GET", path="labels", params=search_labels.model_dump()
         )
         return [search.Label(**item) for item in data]
 

photoprism/api/photos.py

@@ -97,10 +97,7 @@ async def update(self, photo_uid: str, photo_data: form.Photo) -> entity.Photo:
         return entity.Photo(**data)
 
     async def download(
-        self,
-        photo_uid: str,
-        file_dir: Path,
-        filename: str | None = None
+        self, photo_uid: str, file_dir: Path, filename: str | None = None
     ) -> Path:
         return await self._session.req(
             method="GET",
@@ -180,5 +177,3 @@ async def batch_archive(self, selection: form.Selection) -> None:
             path="batch/photos/archive",
             data=selection.model_dump(exclude_none=True),
         )
-
-

photoprism/models/env.py

@@ -11,4 +11,4 @@ class Memory(BaseModel):
 
     cores: int
     memory: Memory
-    routines: int
+    routines: int

photoprism/models/form.py

@@ -161,7 +161,9 @@ class Photo(BaseModel):
     title: str | None = Field(serialization_alias="Title", default=None)
     title_src: str | None = Field(serialization_alias="TitleSrc", default=None)
     description: str | None = Field(serialization_alias="Description", default=None)
-    description_src: str | None = Field(serialization_alias="DescriptionSrc", default=None)
+    description_src: str | None = Field(
+        serialization_alias="DescriptionSrc", default=None
+    )
     details: Details | None = Field(serialization_alias="Details", default=None)
     stack: int | None = Field(serialization_alias="Stack", default=None)
     favorite: bool | None = Field(serialization_alias="Favorite", default=None)

photoprism/session.py

@@ -1,10 +1,9 @@
 import asyncio
-from enum import StrEnum
 from pathlib import Path
-from typing import Any, Literal, overload, reveal_type, Mapping
+from typing import Any, Literal, overload, Mapping
 
 import aiohttp
-from aiohttp import ClientTimeout, ClientResponse
+from aiohttp import ClientTimeout
 from yarl import URL
 
 from photoprism.exceptions import (
@@ -59,8 +58,7 @@ async def req(
         filename: None = None,
         timeout: float | None = None,
         include_auth_token: bool = True,
-    ) -> dict[str, Any] | list[dict[str, Any]]:
-        ...
+    ) -> dict[str, Any] | list[dict[str, Any]]: ...
 
     @overload
     async def req(
@@ -75,8 +73,7 @@ async def req(
         method: Literal["GET", "POST", "PUT", "DELETE"] = "GET",
         timeout: float | None = None,
         include_auth_token: bool = True,
-    ) -> Path:
-        ...
+    ) -> Path: ...
 
     async def req(
         self,
@@ -106,9 +103,7 @@ async def req(
             params["t"] = await self.get_download_token()
         elif mode == "PREVIEW":
             params["t"] = await self.get_preview_token()
-        cleaned_params = {
-            p_k: p_v for p_k, p_v in params.items() if p_v is not None
-        }
+        cleaned_params = {p_k: p_v for p_k, p_v in params.items() if p_v is not None}
         url = URL(self._url).join(URL(path)).update_query(cleaned_params)
         try:
             async with self._session.request(
@@ -149,9 +144,7 @@ async def req(
             raise PhotoprismError(exc) from exc
 
     def determine_filename(self, headers: Mapping[str, str]) -> str:
-        header_filename = (
-            headers["Content-Disposition"].split("; ")[1].split("=")[1]
-        )
+        header_filename = headers["Content-Disposition"].split("; ")[1].split("=")[1]
         # Sometimes the filename in the header is enclosed, sometimes it isn't.
         # This is to account for that.
         if header_filename[0] == '"' and header_filename[-1:] == '"':