| Name | photoprism-client JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | |
| Summary | A Python client to interact with photoprism. |
| upload_time | 2023-05-09 06:41:15 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | |
| keywords |
photoprism
client
api
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Python client for PhotoPrism
A Python client to interact with photoprism.
Changelog can be found in [here](./changelog.md).
## IMPORTANT
This Python client is build on the undocumented API of PhotoPrism. There may be bugs in there. Please let me know if you find some.
Currently tested on the [version of the 17th of June 2022](https://github.com/photoprism/photoprism/releases/tag/220617-0402b8d3). It will probably work with later versions. Just try it and let me know, I will update the readme accordingly.
## Requirements
- requests (latest)
## Setup
To start interacting with Photoprism set up a session. You always need to do this if you start the script. Otherwise there is no session for the client to interact with PhotoPrism.
``` python
from photoprism.Session import Session
pp_session = Session("admin", "changethis", "demo.photoprism.app")
pp_session.create()
```
### HTTPS
It is possible to connect to Photoprism using HTTPS. Two variables exist for this:
- use_https: Boolean
- verify_cert: Boolean
By default, a connection will be made using HTTP. A session can be set up using HTTPS by setting the use_https variable to _True_. By default the certificate will be verified. This check can be disabled by setting the verify_cert variable to _False_. Only change this if you understand what this means. It is better to leave this variable unchanged.
An example is:
```python
from photoprism.Session import Session
pp_session = Session("admin", "changethis", "demo.photoprism.app", use_https=True, verify_cert=False)
pp_session.create()
```
### User agent
The user agent is _Photoprism Python Client_ by default. You can change this using the variable _user_agent_.
For example:
```python
from photoprism.Session import Session
pp_session = Session("admin", "changethis", "demo.photoprism.app", user_agent="Hello World! This is an example.")
pp_session.create()
```
## Searching
To search for photos. With this example it will return the first 100 results. You can change this with `count=1000`.
```python
from photoprism.Photo import Photo
p = Photo(pp_session)
p.search(query="original:*")
```
## Other functions
This is a list of all other functions within the client. If you want other functions either request them or send a pull request.
| function | description | variables | returns |
| ---- | ----- | ------ | ----- |
| Photo.add_photos_to_album() | Add photos to an album, you will need to provide a list of UIDs of the photos you want to add. Returns True if successfull | photos: list, album_uid: string | True if successfull |
| Photo.add_to_album_from_query() | Provide a search query and add all photos that are returned into an album. Provide the albumname, not the UID of the album. | query: string, albumname: string, count: int (default=1000000), offset: int (default=0), order: string (default="newest") | True if successfull |
| Photo.check_if_album_exists() | Small function to check if an album exists | name: string, create_if_not: bool (default is False) | True if it exists, False if not (will continue to be False if the album is created) |
| Photo.create_album() | Create an album, returns a boolean if it worked | title: string | Dict object with the album information |
| Photo.download_album() | Download an entire album as ZIP. The file will get the same name as the title of the album, by setting the filename variable the name can be changed. | uid: string, path: string (default="."), filename: string (default=None) | True if successfull |
| Photo.download_file() | Download a single file. The file will get the same name as in photoprism, by setting the filename variable the name can be changed. | hash: string, path: string (default="."), filename: string (default=None) | True if succesfull |
| Photo.download_files_from_query() | Download files from a query | query: string, count: int (default=100), offset: int (default=0), order: string (default="newest") | True if succesfull |
| Photo.get_album() | Get all information of an album based upon the UID of the album | uid: string | Dict object with the information of the album, False if it does not exist |
| Photo.get_album_uid_by_name() | Get the UID of an album using the name of the album. Be aware, it uses the list_albums function that is limited to 100000 albums | name: string | String of uid, None if it does not exist |
| Photo.get_uid_list_of_search() | Return a list of UIDs based upon the search | query: string, count: int (default is 100), offset: int (default=0), order: string (default="newest") | list of uids |
| Photo.list_albums() | Provide a list of all albums within the photoprism instance, with a max of 100000 | None | Dict object with all albums and their metadata (max of 100000 results) |
| Photo.raw_call() | Function to perform a request to the photoprism server (usually not needed by a user) | endpoint: string, type: string (default="GET"), data: string (default=False) | requests object |
| Photo.search() | Create the session | query: string, count: int (default=100), offset: int (default=0), order: string (default="newest") | Dict object of the results of the search |
| Photo.start_import() | Start an import job, default path is upload. It returns True when the import started, not when finished | path: string (default="upload"), move: Bool (default=False) | True if successfully started |
| Photo.stop_import() | Stop an import job | None | True if successfully stopped |
| Photo.remove_photos_from_album() | Remove photos from an album, Returns True if successfull | albumname: string, photos: bool (default=False), count: int (default=1000000) | True if succesfull |
| Photo.remove_album() | Remove album based on album name | albumname: string | Dict data returned from the server |
| Photo.remove_album_uid() | Remove album based on album uid | uid: string | Dict of the removed album, False if action failed. |
## License
MIT License
Copyright (c) 2022 maartenvl
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.
Raw data
{
"_id": null,
"home_page": "",
"name": "photoprism-client",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "photoprism,client,api",
"author": "",
"author_email": "mvlnetdev <maartenvanleeuwen1996@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8c/b4/cea253ebeaa3ba97ab4e9a6f227f1a817627a4371f0ca2969be8f354f294/photoprism_client-0.2.1.tar.gz",
"platform": null,
"description": "# Python client for PhotoPrism \nA Python client to interact with photoprism.\n\nChangelog can be found in [here](./changelog.md).\n\n## IMPORTANT\nThis Python client is build on the undocumented API of PhotoPrism. There may be bugs in there. Please let me know if you find some. \n\nCurrently tested on the [version of the 17th of June 2022](https://github.com/photoprism/photoprism/releases/tag/220617-0402b8d3). It will probably work with later versions. Just try it and let me know, I will update the readme accordingly. \n\n## Requirements\n- requests (latest)\n\n## Setup\nTo start interacting with Photoprism set up a session. You always need to do this if you start the script. Otherwise there is no session for the client to interact with PhotoPrism.\n``` python\nfrom photoprism.Session import Session\npp_session = Session(\"admin\", \"changethis\", \"demo.photoprism.app\")\npp_session.create()\n```\n\n### HTTPS\nIt is possible to connect to Photoprism using HTTPS. Two variables exist for this:\n- use_https: Boolean\n- verify_cert: Boolean\n\nBy default, a connection will be made using HTTP. A session can be set up using HTTPS by setting the use_https variable to _True_. By default the certificate will be verified. This check can be disabled by setting the verify_cert variable to _False_. Only change this if you understand what this means. It is better to leave this variable unchanged. \n\nAn example is:\n```python\nfrom photoprism.Session import Session\npp_session = Session(\"admin\", \"changethis\", \"demo.photoprism.app\", use_https=True, verify_cert=False)\npp_session.create()\n```\n\n### User agent\nThe user agent is _Photoprism Python Client_ by default. You can change this using the variable _user_agent_. \nFor example:\n```python\nfrom photoprism.Session import Session\npp_session = Session(\"admin\", \"changethis\", \"demo.photoprism.app\", user_agent=\"Hello World! This is an example.\")\npp_session.create()\n```\n\n## Searching\nTo search for photos. With this example it will return the first 100 results. You can change this with `count=1000`.\n\n```python\nfrom photoprism.Photo import Photo\n\np = Photo(pp_session)\np.search(query=\"original:*\")\n```\n\n## Other functions\nThis is a list of all other functions within the client. If you want other functions either request them or send a pull request.\n| function | description | variables | returns |\n| ---- | ----- | ------ | ----- |\n| Photo.add_photos_to_album() | Add photos to an album, you will need to provide a list of UIDs of the photos you want to add. Returns True if successfull | photos: list, album_uid: string | True if successfull |\n| Photo.add_to_album_from_query() | Provide a search query and add all photos that are returned into an album. Provide the albumname, not the UID of the album. | query: string, albumname: string, count: int (default=1000000), offset: int (default=0), order: string (default=\"newest\") | True if successfull |\n| Photo.check_if_album_exists() | Small function to check if an album exists | name: string, create_if_not: bool (default is False) | True if it exists, False if not (will continue to be False if the album is created) |\n| Photo.create_album() | Create an album, returns a boolean if it worked | title: string | Dict object with the album information |\n| Photo.download_album() | Download an entire album as ZIP. The file will get the same name as the title of the album, by setting the filename variable the name can be changed. | uid: string, path: string (default=\".\"), filename: string (default=None) | True if successfull |\n| Photo.download_file() | Download a single file. The file will get the same name as in photoprism, by setting the filename variable the name can be changed. | hash: string, path: string (default=\".\"), filename: string (default=None) | True if succesfull |\n| Photo.download_files_from_query() | Download files from a query | query: string, count: int (default=100), offset: int (default=0), order: string (default=\"newest\") | True if succesfull | \n| Photo.get_album() | Get all information of an album based upon the UID of the album | uid: string | Dict object with the information of the album, False if it does not exist |\n| Photo.get_album_uid_by_name() | Get the UID of an album using the name of the album. Be aware, it uses the list_albums function that is limited to 100000 albums | name: string | String of uid, None if it does not exist |\n| Photo.get_uid_list_of_search() | Return a list of UIDs based upon the search | query: string, count: int (default is 100), offset: int (default=0), order: string (default=\"newest\") | list of uids |\n| Photo.list_albums() | Provide a list of all albums within the photoprism instance, with a max of 100000 | None | Dict object with all albums and their metadata (max of 100000 results) |\n| Photo.raw_call() | Function to perform a request to the photoprism server (usually not needed by a user) | endpoint: string, type: string (default=\"GET\"), data: string (default=False) | requests object |\n| Photo.search() | Create the session | query: string, count: int (default=100), offset: int (default=0), order: string (default=\"newest\") | Dict object of the results of the search |\n| Photo.start_import() | Start an import job, default path is upload. It returns True when the import started, not when finished | path: string (default=\"upload\"), move: Bool (default=False) | True if successfully started |\n| Photo.stop_import() | Stop an import job | None | True if successfully stopped |\n| Photo.remove_photos_from_album() | Remove photos from an album, Returns True if successfull | albumname: string, photos: bool (default=False), count: int (default=1000000) | True if succesfull |\n| Photo.remove_album() | Remove album based on album name | albumname: string | Dict data returned from the server |\n| Photo.remove_album_uid() | Remove album based on album uid | uid: string | Dict of the removed album, False if action failed. |\n\n\n## License \nMIT License\n\nCopyright (c) 2022 maartenvl\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
"bugtrack_url": null,
"license": "",
"summary": "A Python client to interact with photoprism.",
"version": "0.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/mvlnetdev/photoprism_client/issues",
"Homepage": "https://github.com/mvlnetdev/photoprism_client",
"changelog": "https://github.com/mvlnetdev/photoprism_client/blob/main/changelog.md",
"documentation": "https://github.com/mvlnetdev/photoprism_client/blob/main/README.md"
},
"split_keywords": [
"photoprism",
"client",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "884c30fe7b327251276c83a6d86c8de4c1c73dc706eba716f917e2ca737c9ec7",
"md5": "feecd79ed02c2d752cd5b95431a392e7",
"sha256": "749fffb6eb58f3a7173f39dd325e86e5670a9fd657a01aa5ec0d489b90d8d430"
},
"downloads": -1,
"filename": "photoprism_client-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "feecd79ed02c2d752cd5b95431a392e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8437,
"upload_time": "2023-05-09T06:41:12",
"upload_time_iso_8601": "2023-05-09T06:41:12.903254Z",
"url": "https://files.pythonhosted.org/packages/88/4c/30fe7b327251276c83a6d86c8de4c1c73dc706eba716f917e2ca737c9ec7/photoprism_client-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8cb4cea253ebeaa3ba97ab4e9a6f227f1a817627a4371f0ca2969be8f354f294",
"md5": "0073f0e22b0842d336558443ae13cef7",
"sha256": "9b0c47cd276b675a26814aa8cc0ac7442e771d64b7f9f0e398d474161d9d01fa"
},
"downloads": -1,
"filename": "photoprism_client-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "0073f0e22b0842d336558443ae13cef7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7060,
"upload_time": "2023-05-09T06:41:15",
"upload_time_iso_8601": "2023-05-09T06:41:15.025322Z",
"url": "https://files.pythonhosted.org/packages/8c/b4/cea253ebeaa3ba97ab4e9a6f227f1a817627a4371f0ca2969be8f354f294/photoprism_client-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-09 06:41:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mvlnetdev",
"github_project": "photoprism_client",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "photoprism-client"
}
