API¶

class photoprysm.User(username, password, uid=None)[source]¶

login(server_api)[source]¶

Login to the server as a User

Parameters:: server_api (str) – Base URL to the server API
Raises:: requests.HTTPError – If the credentials are invalid or the server is not accepting requests
Returns:: Pre-configured Session with the authentication token for this User
Return type:: requests.Session

logout()[source]¶

Logout of the server as a User

Return type:: None

request(**kwargs)[source]¶

Send a request to the server as a User

Return type:: Response

class photoprysm.Client(client_id, client_secret)[source]¶

Dataclass for holding authentication information for the application’s Client credentials.

Parameters:

client_id (str) – Client ID generated from Photoprism CLI. See the note below.
client_secret (str) – Client secret generated from Photoprism CLI. See the note below.

login(server_api)[source]¶

Login to the server as a Client

Parameters:: server_api (str) – Base URL to the server API
Raises:: requests.HTTPError – If the credentials are invalid or the server is not accepting requests
Returns:: Pre-configured Session with the authentication token for this Client
Return type:: requests.Session

logout()[source]¶

Logout of the server as a Client

Return type:: None

request(**kwargs)[source]¶

Send a request to the server as a Client

Return type:: Response

Note

To create Client sessions, you will need to generate the client ID and secret from the Photoprism CLI. From within the Photoprism environment, run the following command:

>>> photoprism clients add [client_name]

with the name of the client in the placeholder. See Photoprism’s Client Credentials page for more information.

Warning

Despite the existence of the “albums” and “photos” scopes listed in the Photoprism documentation on Client Authorization Scopes, interfacing with albums or photos requires User access. It will not work using a Client session, even if you have not limited the Client’s scope (i.e. setting --scope * when you generated the Client Credentials). Since nearly all functionality of this package relies on access to these scopes, functionality through Client sessions has been minimally tested and may result in unexpected issues.

photoprysm.user_session(user, server_api)[source]¶

Context manager for creating and deleting a User session.

Parameters:

user (User) – User to create the session with
server_api (str) – Base URL of the server API

Return type:

Session

>>> with user_session(user, server_api) as session:
>>>     # Do stuff

photoprysm.client_session(client, server_api)[source]¶

Context manager for creating and deleting a Client session.

Parameters:

client (Client) – Client to create the session with
server_api (str) – Base URL of the server API

>>> with client_session(client, server_api) as session:
>>>     # Do stuff

photoprysm.get_api_url(netloc=None, scheme=None)[source]¶

Constructs the base URL for the Photoprism server API.

Parameters:

netloc (Optional[str]) – Network location. This is the hostname, with the port if necessary. Defaults to 'localhost:2342'.
scheme (Optional[str]) – Scheme to send requests with. Must be either 'http' or 'https'.

Return type:

str

photoprysm.request(session, url, method, **kwargs)[source]¶

Send the request from a pre-configured requests.Session instance.

Parameters:

session (requests.Session) – requests.Session handle with the access token pre-configured
url (str) – URL to send the requests to
method (str) – Method of request, e.g. GET, POST, PUT, DELETE

Return type:

Response

Returns:

Response from the server after sending the request

General¶

photoprysm.start_import(session, server_api, path=None, move=None, *albums)[source]¶

Start the import process. See Importing Files from the Photoprism documentation for more information.

Parameters:

session (Session) – Session to make the request from
server_api (str) – String with the base URL for the API
path (str) – (optional) Path relative to the import path that you are importing files from. Leave blank to import everything in /photoprism/import volume. See Photoprism Volumes for more information.
move (bool) – (optional) Set to True to move files out of the /photoprism/import volume upon import. See more information here.

Return type:

None

photoprysm.start_index(session, server_api, path=None, cleanup=None, rescan=None)[source]¶

Start the index process. See Indexing Your Library from the Photoprism documentation for more information.

Parameters:

session (Session) – Session to make the request from
server_api (str) – String with the base URL for the API
path (str) – (optional) Path relative to the originals path that you want to index. Leave blank to index everything in /photoprism/originals volume
cleanup (bool) – (optional) Set to cleanup after the index process has completed. Defaults to True.
rescan (bool) – (optional) Set to rescan for more files after the index process has completed. Defaults to True.

Return type:

None

photoprysm.get_tokens_from_session(session, server_api)[source]¶

Get auth tokens (access, download, preview) from Session

>>> get_tokens_from_session(session, server_api)
{'access_token': 'example_value', 'download_token': 'example_value', 'preview_token': 'example_value'}

Parameters:

session (Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API

Return type:

dict[str, str]

Albums¶

Models¶

These dataclasses hold information about various models to be used for interfacing with. They do not have many (if any) methods and are purely for holding data in a convenient way.

class photoprysm.Album(uid, title=None, favorite=None, private=None, description=None)[source]¶

Dataclass for holding data about an album.

Parameters:

uid (str) – UID of the album
title (str) – (optional) Title of the album
favorite (bool) – (optional) True if the current authenticated User has set the album as a favorite
private (bool) – (optional) True if the album has been marked private
description (str or None) – (optional) Description for the album
json (dict[str,str] or None) – (optional) Album response that was received as JSON data

class photoprysm.AlbumProperties(caption=None, category=None, country=None, description=None, favorite=None, _filter=None, location=None, notes=None, order=None, private=None, template=None, thumb=None, thumb_src=None, title=None, _type=None)[source]¶

This is for updating album properties.

Parameters:

caption (str|None) – (optional)
category (str|None) – (optional)
country (str|None) – (optional)
description (str|None) – (optional)
favorite (bool|None) – (optional)
filter (str|None) – (optional) Pass to the constructor as _filter. Access as filter.
location (str|None) – (optional)
notes (str|None) – (optional)
order (str|None) – (optional)
private (bool|None) – (optional)
template (str|None) – (optional)
thumb (str|None) – (optional)
thumb_src (str|None) – (optional)
title (str|None) – (optional)
type (str|None) – (optional) Pass to the constructor as _type. Access as type.

Functions¶

photoprysm.get_albums(session, server_api, *, count=1, query=None, offset=None, order=None)¶

Get albums matching the provided query.

Parameters:

session (Session) – Session to make the request from
server_api (str) – String with the base URL for the API
count (int) – Maximum number of results
query (Optional[str]) – Query to send to the server.
offset (Optional[int]) – Search result offset
order (Optional[str]) – Sort order. Choose from favorites, name, title, added, or edited.

Raises:

ValueError – If an invalid order is provided
requests.HTTPError – If the HTTP request fails

Return type:

list[Album]

photoprysm.get_album_by_uid(session, server_api, uid)¶

Gets the Album handle from the provided UID.

Parameters:

session (Session) – Session to make the request from
server_api (str) – String with the base URL for the API
uid (str) – UID of the album to get

Return type:

Album

Returns:

Album with matching UID

photoprysm.create_album(session, server_api, title, favorite=False)¶

Creates a new album.

Parameters:

session (Session) – Session to make the request from
server_api (str) – String with the base URL for the API
title (str) – Title of the new album
favorite (bool) – Mark as favorite or not

Returns:

Newly created Album

Return type:

Album

photoprysm.delete_album(session, server_api, *albums)¶

Parameters:

session (Session) – Session to make the request from
server_api (str) – String with the base URL for the API
albums (Album | str) – One more Albums to delete

Return type:

None

photoprysm.like_album(session, server_api, album)¶

Sets the favorite flag for an album.

Parameters:

session (requests.Session) – Session to make the request from
server_api (str) – String with the base URL for the API
uid (str) – Album UID

Return type:

None

photoprysm.unlike_album(session, server_api)¶

Removes the favorite flag from an album.

Parameters:

session (requests.Session) – Session to make the request from
server_api (str) – String with the base URL for the API
uid (str) – Album UID

Return type:

None

photoprysm.update_album(session, server_api, album, properties)¶

Update the album properties.

Parameters:

session (requests.Session) – Session to make the request from
server_api (str) – String with the base URL for the API
album (Album|str) – Album to update
properties (AlbumProperties) – Properties to update the album with

Returns:

Updated album

Return type:

Album

photoprysm.clone_album(session, server_api, album, *albums_to_copy)¶

Copies the photos from other albums to an existing album

Parameters:

session (Session) – Session to make the request from
server_api (str) – String with the base URL for the API
album (Album | str) – Album to which the pictures are to be added
albums_to_copy (Album | str) – One or more Albums containing the photos that will be copied

Return type:

Album

Share Links¶

As of writing, the Link Sharing feature in the latest Photoprism release is limited to sharing albums. Currently, share links cannot be generated for anything except albums.

Models¶

class photoprysm.ShareLink(token, share_uid, slug, uid, comment=None, created_at=None, modified_at=None, created_by=None, expires=None, max_views=None, perm=None, verify_password=None, views=None)[source]¶

Data class for holding information about a share link

Parameters:

token (str) – Token of the share link, used to construct the URL
share_uid (str) – UID of the album the link points to
slug (str) – URL slug of the album the share link is for
uid (str) – UID of the share link itself
comment (str) – (optional) Comment that was added when the share link was created
created_at (str) – (optional) Time when the link was created
created_by (str) – (optional) UID of the User who created this ShareLink
expires (int) – (optional) Seconds until the link expires
max_views (int) – (optional) Maximum number of views until the link expires
modified_at (str) – (optional) Time when the link was last modified
perm (int) – (optional) I literally do not know what this is.
verify_password (bool) – (optional) Set to True to require user to verify password when they visit the share link
views (int) – (optional) Number of views the share link has so far

get_url(host=None, https=None)[source]¶

Construct the URL of the ShareLink.

Parameters:

host (str) – (optional) Hostname where the Photoprism server is. Defaults to ‘localhost’.
https (bool) – (optional) Set to True to use https. Defaults to False.

Return type:

str

class photoprysm.ShareLinkProperties(can_comment=None, can_edit=None, expires=0, max_views=0, slug=None, token=None, password=None)[source]¶

Share link properties. This is for setting and updating properties of share links.

Parameters:

can_comment (bool) – (optional) Allow visitors using the share link to comment.
can_edit (bool) – (optional) Allow visitors using the share link to edit.
expires (int) – (optional) Set expiration time for the link in seconds. Defaults to 0 to disable expiration.
max_views (int) – (optional) Set maximum number of views before link is disabled. Defaults to 0 to disable limit.
password (str) – (optional) Set a password that visitors must enter before they can view the media

Functions¶

photoprysm.get_album_share_links(session, server_api, album)¶

Returns all share links for the album matching the UID

Parameters:

session (Session) – Session to make the request from
server_api (str) – String with the base URL for the API
album (Album | str) – Album to get the share links for

Return type:

list[ShareLink]

Returns:

List of ShareLink objects for each share link generated for this Album. Note that if no share links have been generated, this will return an empty list.

photoprysm.add_album_share_link(session, server_api, album)¶

Add share link to Album

Parameters:

session (Session) – Session to make the request from
server_api (str) – String with the base URL for the API
album (Album | str) – Album to generate the share link for

Return type:

ShareLink

Returns:

ShareLink with info about the link that was just generated

photoprysm.parse_album_share_link(session, server_api, url, album)¶

Return type:: ShareLink

photoprysm.update_album_share_link(session, server_api, share_link, link_props, album=None)¶

Update share link with the given properties. Note that if you provide share_link as the URL itself, you must also provide the Album that the link is for.

Return type:: ShareLink

Photos¶

Models¶

class photoprysm.Photo(uid, path=None, name=None, title=None, description=None, width=None, height=None, files=None)[source]¶

Dataclass for holding data about a photo.

Parameters:

uid (str)
path (str) – (optional)
name (str) – (optional)
title (str) – (optional)
description (str) – (optional)
width (int) – (optional)
height (int) – (optional)
files (list[PhotoFile]) – (optional)

class photoprysm.PhotoFile(uid, photo_uid, name=None, root=None, hash=None, size=None, primary=None, time_index=None, media_id=None, media_utc=None, instance_id=None, codec=None, file_type=None, media_type=None, mime=None, width=None, height=None, orientation=None, orientation_src=None, aspect_ratio=None, color_profile=None, main_color=None, colors=None, luminance=None, diff=None, chroma=None, software=None, mod_time=None, created_at=None, created_in=None, updated_at=None, markers=None)[source]¶

Dataclass for holding data about a file.

Parameters:

uid (str)
photo_uid (str)
name (str) – (optional)
root (str) – (optional)
hash (str) – (optional)
size (int) – (optional)
primary (bool) – (optional)
time_index (int) – (optional)
media_id (str) – (optional)
media_utc (int) – (optional)
instance_id (str) – (optional)
codec (str) – (optional)
file_type (str) – (optional)
media_type (str) – (optional)
mime (str) – (optional)
width (int) – (optional)
height (int) – (optional)
orientation (int) – (optional)
orientation_src (str) – (optional)
aspect_ratio (float) – (optional)
color_profile (str) – (optional)
main_color (str) – (optional)
colors (str) – (optional)
luminance (str) – (optional)
diff (int) – (optional)
chroma (int) – (optional)
software (str) – (optional)
mod_time (int) – (optional)
created_at (datetime) – (optional)
created_in (datetime) – (optional)
updated_at (datetime) – (optional)
markers (list) – (optional)

class photoprysm.PhotoDetails(artist=(None,), artist_src=(None,), copyright=(None,), copyright_src=(None,), keywords=(None,), keywords_src=(None,), license=(None,), license_src=(None,), notes=(None,), notes_src=(None,), photo_id=(None,), subject=(None,), subject_src=None)[source]¶

Details from the PhotoProperties

Parameters:

artist (str) – (optional)
artist_src (str) – (optional)
copyright (str) – (optional)
copyright_src (str) – (optional)
keywords (str) – (optional)
keywords_src (str) – (optional)
license (str) – (optional)
license_src (str) – (optional)
notes (str) – (optional)
notes_src (str) – (optional)
photo_id (int) – (optional)
subject (str) – (optional)
subject_src (str) – (optional)

class photoprysm.PhotoProperties(altitude=(None,), camera_id=(None,), camera_src=(None,), cell_accuracy=(None,), cell_id=(None,), country=(None,), day=(None,), description=(None,), description_src=(None,), details=(None,), exposure=(None,), f_number=(None,), favorite=(None,), focal_length=(None,), iso=(None,), lat=(None,), lens_id=(None,), lng=(None,), month=(None,), original_name=(None,), panorama=(None,), place_id=(None,), place_src=(None,), private=(None,), scan=(None,), stack=(None,), taken_at=(None,), taken_at_local=(None,), taken_src=(None,), time_zone=(None,), title=(None,), title_src=(None,), type=(None,), type_src=(None,), year=None)[source]¶

Properties of the Photo object

Parameters:

altitude (int) – (optional)
camera_id (int) – (optional)
camera_src (str) – (optional)
cell_accuracy (int) – (optional)
cell_id (str) – (optional)
country (str) – (optional)
day (int) – (optional)
description (str) – (optional)
description_src (str) – (optional)
details (PhotoDetails) – (optional)
exposure (str) – (optional)
f_number (int) – (optional)
favorite (bool) – (optional)
focal_length (int) – (optional)
iso (int) – (optional)
lat (int) – (optional)
lens_id (int) – (optional)
lng (int) – (optional)
month (int) – (optional)
original_name (str) – (optional)
panorama (bool) – (optional)
place_id (str) – (optional)
place_src (str) – (optional)
private (bool) – (optional)
scan (bool) – (optional)
stack (int) – (optional)
taken_at (str) – (optional)
taken_at_local (str) – (optional)
taken_src (str) – (optional)
time_zone (str) – (optional)
title (str) – (optional)
title_src (str) – (optional)
type (str) – (optional)
type_src (str) – (optional)
year (int) – (optional)

Functions¶

photoprysm.get_photos(session, server_api, *, count=1, quality=0, merged=None, query=None, offset=None, order=None, public=None, album=None, path=None, video=None)¶

Get list of Photos by query.

Parameters:

session (Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
count (int) – (optional) Number of matches to return. Defaults to 1.
quality (int) – (optional) Minimum quality score. Defaults to 0 to disable limit. Must be within range of 1-7.
merged (bool) – (optional) If True, consecutive files with the same photo ID are merged into a single result with the Files property containing the related files.
query (str) – (optional) Query to search for. See documentation for valid Photoprism Search Filters.
offset (int) – (optional) Search result offset
order (str) – (optional) Sort order. Choose from favorites, name, title, added, or edited.
public (bool) – (optional) Limit searches to those with public access.
album (Album|str) – (optional) Album to search under. You can provide a handle to an Album instance or you can provide the UID as a string directly.
path (os.PathLike) – (optional) Path to the photo
video (bool) – (optional) True if result should be of type video

Raises:

requests.HTTPError – If the request is poorly formed or the server is not accepting requests

Return type:

list[Photo]

Returns:

List of Photos that match from the query

photoprysm.get_photo_by_uid(session, server_api, uid)¶

Get Photo handle by UID.

Parameters:

session (requests.Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
uid (str) – UID of the Photo to retrieve

Raises:

requests.HTTPError – If it runs into an HTTP error while sending the request

Returns:

Photo with matching UID

Return type:

Photo

photoprysm.get_photo_by_file(session, server_api, f)¶

Get Photo by file-like object.

Parameters:

session (requests.Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
f (IOBase) – File object to find the Photo of

Return type:

Photo

photoprysm.upload(session, server_api, f, /, albums=None)[source]¶

Upload a file to the server as the authenticated user.

>>> from pathlib import Path
>>> from hashlib import sha1
>>> with photoprysm.user_session(user, server_api) as session:
>>>     with open('my_photo.jpg', 'rb') as f:
>>>         photo = photoprysm.upload_photo(session, server_api, f)
>>> assert any([fp.hash == sha1(Path('my_photo.jpg').read_bytes()).hexdigest() for fp in photo.files])

Parameters:

session (Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
f (IOBase | list[IOBase]) – Raw binary file(s) object to upload
albums (list[Album|str]) – (optional) List of albums to add the files to

Return type:

Photo | list[Photo] | None

photoprysm.archive_photo(session, server_api, *photos)¶

Archive one or more photos.

Parameters:

session (Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
photos (Photo | str) – One or more Photo objects or UIDs to archive

Return type:

None

photoprysm.restore_photo(session, server_api, *photos)¶

Return type:: None

photoprysm.clear_photo_from_archive(session, server_api, *photos)¶

Permanently delete one or more Photos from the archive.

Parameters:

session (Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
photos (Photo | str) – One or more Photos to remove from the archive

Return type:

None

photoprysm.delete_photo(session, server_api, *photos)¶

Return type:: None

photoprysm.update_photo(session, server_api, photo, photo_props)¶

Update a photo with new properties

Parameters:

session (requests.Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
photo (Photo) – Photo to update
photo_props (PhotoProperties) – Properties to update the Photo with

Raises:

requests.HTTPError – If it runs into an HTTP error while sending the request

Returns:

Updated Photo

Return type:

Photo

photoprysm.approve_photo(session, server_api, photo)¶

Mark a Photo in review as approved

Parameters:

session (requests.Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
photo (Photo) – Photo to approve

Raises:

requests.HTTPError – If it runs into an HTTP error while sending the request

Returns:

Approved Photo

Return type:

Photo

photoprysm.set_photo_as_private(session, server_api, *photos)¶

Set multiple photos as private.

Parameters:

session (requests.Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
photos (list[Photo]) – Photos to set as private

Raises:

requests.HTTPError – If it runs into an HTTP error while sending the request

Return type:

None

Returns:

None

photoprysm.like_photo(session, server_api, photo)¶

Mark a Photo as a favorite

Parameters:

session (requests.Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
photo (Photo) – Photo to mark as favorite

Raises:

requests.HTTPError – If it runs into an HTTP error while sending the request

Return type:

None

Returns:

None

photoprysm.unlike_photo(session, server_api, photo)¶

Unmark a Photo as a favorite

Parameters:

session (requests.Session) – Pre-configured requests.Session object to send the request with
server_api (str) – Base URL of the server API
photo (Photo) – Photo to unmark as favorite

Raises:

requests.HTTPError – If it runs into an HTTP error while sending the request

Return type:

None

Returns:

None

API¶

General¶

Albums¶

Models¶

Functions¶

Photos¶

Models¶

Functions¶

Photoprysm

Navigation

Related Topics