# Unsplash Library
With this library you can download/upload/delete ... images with just one api key ✨
## Installation
For installation, run the following command ⬇️
```
pip install unsplash_lib
```
Having issue with pip?
## How can i get a unsplash api key?
- Well, at first you should make an [unsplash account](https://unsplash.com/join).
- After that, [create a new application](https://unsplash.com/oauth/applications/new) on the site.
- Then scroll down a bit and copy your Access Key.
## Usage
For importing ⬇️
```python
from unsplash_lib import Photos, Collection, Search
```
---
### Photos explanation
**First step**: make an instance
```python
Photos_instance = Photos('Your api key 🔑')
```
### 1 - random_photo
Download photos by search results.
All parameters are Optional.
|param | Description |
---|---|
| `count`: | The number of photos to return. (Default: 1; max: 30) |
| `query`: | Search terms. |
| `topics`: | Public topic ID('s) to filter selection. If multiple, comma-separated
| `collections`: | Collection ID('s) to narrow search. Optional. If multiple, comma-separated. |
| `content_filter`: | Limit results by [content safety](https://unsplash.com/documentation#content-safety). (Optional; default: low). Valid values are low and high. |
| `orientation`: | The orientation of the images to download. |
| `DownloadImg`: | A boolean value indicating whether to download the images. |
| `FileName`: | The name of the file to save the images to. |
| `UPath`: | The path to the directory to save the images to. |
| `_pass_errors` : | If there an error during the process. It won't break the program. It will just skip the process|
### 2 - photos_statistics
Retrieve total number of downloads, views and likes of a single photo, as well as the historical breakdown of these stats in a specific timeframe (default is 30 days)
|param |Description |
---|---|
|`id`: | The public id of the photo. Required.|
|`resolution`: | The frequency of the stats. (Optional; default: “days”)|
|`quantity`: | The amount of for each stat. (Optional; default: 30)|'''
---
### Search Explanation
### Search_photo
**First step**: make an instance
```python
Photos_instance = Search('Your api key 🔑')
```
### 1 - search_photo
Download photos by search results.
|param | Description |
---|---|
| `query`: | Search terms. |
| `page`: | The page number of the results to download. (Optional; default: 1) |
| `per_page`: | The number of images to download per page. (Optional; default: 10)
| `order_by`: | The order in which to sort the results. (Optional; default: relevant). Valid values are latest and relevant. |
| `collections`: | Collection ID('s) to narrow search. Optional. If multiple, comma-separated. |
| `content_filter`: | Limit results by [content safety](https://unsplash.com/documentation#content-safety). (Optional; default: low). Valid values are low and high. |
| `color`: | Filter results by color. Optional. Valid values are: black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, and blue. |
| `orientation`: | The orientation of the images to download. |
| `DownloadImg`: | A boolean value indicating whether to download the images. |
| `FileName`: | The name of the file to save the images to. |
| `UPath`: | The path to the directory to save the images to. |
| `_pass_errors` : | If there an error during the process. It won't break the program. It will just skip the process|
### 2 - search_users
Search for a user and getting back the results as list that contain a dictionary.
If the operation was successful, returns a list with dictionary inside that contain search info. Raise the error message if the operation was unsuccessful.
| param | Description|
---|---|
| `query` : | Search terms.|
| `page` : | The page number of the results to download. (Optional; default: 1)
| `per_page` : | The number of images to download per page. (Optional; default: 10)
| `_pass_errors` : | If there an error during the process. It won't break the program. It will just skip the process|
---
### Collection Explanation
**First step**: make an instance
```python
Photos_instance = Collection('Your api key 🔑')
```
### 1 - download_collection
Download a collection's photos.
| param | Description |
---|---|
| `ID` : | The collection's ID. Required. |
| `page` : | Page number to retrieve. (Optional; default: 1) |
| `per_page` : | Number of items per page. (Optional; default: 10) |
| `orientation` : | Filter by photo orientation. Optional. (Valid values: landscape, portrait, squarish) |
| `DownloadImg`: | A boolean value indicating whether to download the images. |
| `FileName`: | The name of the file to save the images to. |
| `UPath`: | The path to the directory to save the images to. |
| `_pass_errors` : | If there an error during the process. It won't break the program. It will just skip the process|
### 2 - get_collections_id
You can search for collection and get the collection's id, Then you can use it in download_collection() func to download images.
| param | Description |
---|---|
|`query` : | Search terms. |
| `page`: | The page number of the results to download. (Optional; default: 1) |
| `per_page`: | The number of images to download per page. (Optional; default: 10) |
| `_pass_errors` : | If there an error during the process. It won't break the program. It will just skip the process|
### 3 - create_collection
Create a new collection. This requires the `write_collections` permission. Enable it on Redirect URI & Permissions on your profile.
return True if the operation was successful and return error message if operation was unsuccessful
| param | Description |
---|---|
|`client_id`: | Your Unsplash Access Key. |
| `title`: | The title of the collection. (Required.) |
| `description`: | The collection's description. (Optional.) |
| `private`: | Whether to make this collection private. (Optional; default false). |
| `_pass_errors`: | If there an error during the process. It won't break the program. It will just skip the process|
### 4 - update_collection
Update an existing collection belonging to the logged-in user. This requires the write_collections permission. Enable it on Redirect URI & Permissions on your profile.
return True if the operation was successful and return error message if operation was unsuccessful
| param | Description |
---|---|
| `ID` : | The collection's ID. Required. |
| `title`: | The title of the collection. (Optional.) |
| `description`: | The collection's description. (Optional.) |
| `private`: | Whether to make this collection private. (Optional; default false). |
| `_pass_errors`: | If there an error during the process. It won't break the program. It will just skip the process|
### 4 - delete_collection
Delete a collection belonging to the logged-in user. This requires the write_collections permission. Enable it on Redirect URI & Permissions on your profile.
return True if the operation was successful and return error message if operation was unsuccessful
| param | Description |
---|---|
| `ID` : | The collection's ID. Required. |
| `_pass_errors`: | If there an error during the process. It won't break the program. It will just skip the process|
### 5 - add_to_collection
Add a photo to one of the logged-in user's collections. Requires the write_collections permission. Enable it on Redirect URI & Permissions on your profile.
returns True if the operation was successful and returns an error message if operation was unsuccessful.
Note: If the photo is already in the collection, this action has no effect.
| param | Description |
---|---|
|`client_id`: | Your Unsplash Access Key. |
| `collection_id` : | The collection's ID. Required. |
| `photo_id` : | The photo's ID that you want to add it. Required. |
| `_pass_errors`: | If there an error during the process. It won't break the program. It will just skip the process|
Raw data
{
"_id": null,
"home_page": "https://github.com/beh185/unsplash_lib",
"name": "unsplash-lib",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "download from Unsplash",
"author": "Behnam",
"author_email": "Behii@tutanota.com",
"download_url": "https://files.pythonhosted.org/packages/dc/db/c4b5b6e52f1f37a3c53dd9873f3af033d567a4bb10857dea5e37ed0c95b5/unsplash_lib-0.0.3.tar.gz",
"platform": null,
"description": "# Unsplash Library\n\nWith this library you can download/upload/delete ... images with just one api key \u2728\n\n## Installation\n\nFor installation, run the following command \u2b07\ufe0f\n\n```\npip install unsplash_lib\n```\n\nHaving issue with pip?\n\n## How can i get a unsplash api key?\n- Well, at first you should make an [unsplash account](https://unsplash.com/join).\n- After that, [create a new application](https://unsplash.com/oauth/applications/new) on the site.\n- Then scroll down a bit and copy your Access Key.\n\n## Usage\nFor importing \u2b07\ufe0f\n```python\nfrom unsplash_lib import Photos, Collection, Search\n```\n---\n### Photos explanation\n**First step**: make an instance\n```python\nPhotos_instance = Photos('Your api key \ud83d\udd11')\n```\n### 1 - random_photo\n\nDownload photos by search results.\nAll parameters are Optional.\n|param | Description | \n---|---| \n| `count`: | The number of photos to return. (Default: 1; max: 30) |\n| `query`: | Search terms. |\n| `topics`: | Public topic ID('s) to filter selection. If multiple, comma-separated\n| `collections`: | Collection ID('s) to narrow search. Optional. If multiple, comma-separated. |\n| `content_filter`: | Limit results by [content safety](https://unsplash.com/documentation#content-safety). (Optional; default: low). Valid values are low and high. |\n| `orientation`: | The orientation of the images to download. |\n| `DownloadImg`: | A boolean value indicating whether to download the images. |\n| `FileName`: | The name of the file to save the images to. |\n| `UPath`: | The path to the directory to save the images to. |\n| `_pass_errors` : | If there an error during the process. It won't break the program. It will just skip the process|\n\n### 2 - photos_statistics\nRetrieve total number of downloads, views and likes of a single photo, as well as the historical breakdown of these stats in a specific timeframe (default is 30 days)\n|param |Description |\n---|---|\n|`id`: | The public id of the photo. Required.|\n|`resolution`: | The frequency of the stats. (Optional; default: \u201cdays\u201d)|\n|`quantity`: | The amount of for each stat. (Optional; default: 30)|'''\n\n---\n### Search Explanation\n\n\n### Search_photo\n**First step**: make an instance\n```python\nPhotos_instance = Search('Your api key \ud83d\udd11')\n```\n### 1 - search_photo\nDownload photos by search results.\n\n|param | Description | \n---|---| \n| `query`: | Search terms. |\n| `page`: | The page number of the results to download. (Optional; default: 1) |\n| `per_page`: | The number of images to download per page. (Optional; default: 10)\n| `order_by`: | The order in which to sort the results. (Optional; default: relevant). Valid values are latest and relevant. |\n| `collections`: | Collection ID('s) to narrow search. Optional. If multiple, comma-separated. |\n| `content_filter`: | Limit results by [content safety](https://unsplash.com/documentation#content-safety). (Optional; default: low). Valid values are low and high. |\n| `color`: | Filter results by color. Optional. Valid values are: black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, and blue. |\n| `orientation`: | The orientation of the images to download. |\n| `DownloadImg`: | A boolean value indicating whether to download the images. |\n| `FileName`: | The name of the file to save the images to. |\n| `UPath`: | The path to the directory to save the images to. |\n| `_pass_errors` : | If there an error during the process. It won't break the program. It will just skip the process|\n\n### 2 - search_users\n\nSearch for a user and getting back the results as list that contain a dictionary.\n If the operation was successful, returns a list with dictionary inside that contain search info. Raise the error message if the operation was unsuccessful.\n\n| param | Description|\n---|---|\n| `query` : |\tSearch terms.|\n| `page` : | The page number of the results to download. (Optional; default: 1)\n| `per_page` : | The number of images to download per page. (Optional; default: 10)\n| `_pass_errors` : | If there an error during the process. It won't break the program. It will just skip the process|\n\n---\n\n### Collection Explanation\n**First step**: make an instance\n```python\nPhotos_instance = Collection('Your api key \ud83d\udd11')\n``` \n\n### 1 - download_collection\nDownload a collection's photos.\n| param | Description |\n---|---|\n| `ID` : | \tThe collection's ID. Required. |\n| `page` : | Page number to retrieve. (Optional; default: 1) |\n| `per_page` : | Number of items per page. (Optional; default: 10) | \n| `orientation` : | Filter by photo orientation. Optional. (Valid values: landscape, portrait, squarish) |\n| `DownloadImg`: | A boolean value indicating whether to download the images. |\n| `FileName`: | The name of the file to save the images to. |\n| `UPath`: | The path to the directory to save the images to. |\n| `_pass_errors` : | If there an error during the process. It won't break the program. It will just skip the process|\n\n### 2 - get_collections_id\nYou can search for collection and get the collection's id, Then you can use it in download_collection() func to download images.\n| param | Description |\n---|---|\n|`query` : | Search terms. |\n| `page`: | The page number of the results to download. (Optional; default: 1) |\n| `per_page`: | The number of images to download per page. (Optional; default: 10) |\n| `_pass_errors` : | If there an error during the process. It won't break the program. It will just skip the process|\n\n### 3 - create_collection\nCreate a new collection. This requires the `write_collections` permission. Enable it on Redirect URI & Permissions on your profile.\n\nreturn True if the operation was successful and return error message if operation was unsuccessful\n| param |\tDescription |\n---|---|\n|`client_id`: | Your Unsplash Access Key. |\n| `title`: |\tThe title of the collection. (Required.) |\n| `description`: | \tThe collection's description. (Optional.) |\n| `private`: |\tWhether to make this collection private. (Optional; default false). |\n| `_pass_errors`: | If there an error during the process. It won't break the program. It will just skip the process|\n\n### 4 - update_collection\nUpdate an existing collection belonging to the logged-in user. This requires the write_collections permission. Enable it on Redirect URI & Permissions on your profile.\n\nreturn True if the operation was successful and return error message if operation was unsuccessful\n| param |\tDescription |\n---|---|\n| `ID` : | \tThe collection's ID. Required. |\n| `title`: |\tThe title of the collection. (Optional.) |\n| `description`: | \tThe collection's description. (Optional.) |\n| `private`: |\tWhether to make this collection private. (Optional; default false). |\n| `_pass_errors`: | If there an error during the process. It won't break the program. It will just skip the process|\n\n### 4 - delete_collection\nDelete a collection belonging to the logged-in user. This requires the write_collections permission. Enable it on Redirect URI & Permissions on your profile.\n\nreturn True if the operation was successful and return error message if operation was unsuccessful\n| param | Description |\n---|---|\n| `ID` : | \tThe collection's ID. Required. |\n| `_pass_errors`: | If there an error during the process. It won't break the program. It will just skip the process|\n\n### 5 - add_to_collection\nAdd a photo to one of the logged-in user's collections. Requires the write_collections permission. Enable it on Redirect URI & Permissions on your profile.\n\nreturns True if the operation was successful and returns an error message if operation was unsuccessful.\nNote: If the photo is already in the collection, this action has no effect.\n| param | Description |\n---|---|\n|`client_id`: | Your Unsplash Access Key. |\n| `collection_id` : | The collection's ID. Required. |\n| `photo_id` : | The photo's ID that you want to add it. Required. |\n| `_pass_errors`: | If there an error during the process. It won't break the program. It will just skip the process|\n \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A python library that can download from Unsplash and also manage user account",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/beh185/unsplash_lib"
},
"split_keywords": [
"download",
"from",
"unsplash"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6d305d521525e8b6d3c83bd4de45b694e79fdd27af237caef63b9c3f1410601e",
"md5": "66912a23f4a843d344de7d7871c15d3b",
"sha256": "e25dfb9124e87930aa0b84e9821e4f9e41eb8630b44817ecefb1a799a8f47a3b"
},
"downloads": -1,
"filename": "unsplash_lib-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "66912a23f4a843d344de7d7871c15d3b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 8787,
"upload_time": "2024-03-09T17:58:46",
"upload_time_iso_8601": "2024-03-09T17:58:46.363085Z",
"url": "https://files.pythonhosted.org/packages/6d/30/5d521525e8b6d3c83bd4de45b694e79fdd27af237caef63b9c3f1410601e/unsplash_lib-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dcdbc4b5b6e52f1f37a3c53dd9873f3af033d567a4bb10857dea5e37ed0c95b5",
"md5": "b1f40d0597b787c28fbf0c275f5e0359",
"sha256": "aa635e0583ec7537b2b6761aae00d097297477837ee2b07e9f88206ec6299c7b"
},
"downloads": -1,
"filename": "unsplash_lib-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "b1f40d0597b787c28fbf0c275f5e0359",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 8650,
"upload_time": "2024-03-09T17:58:47",
"upload_time_iso_8601": "2024-03-09T17:58:47.662550Z",
"url": "https://files.pythonhosted.org/packages/dc/db/c4b5b6e52f1f37a3c53dd9873f3af033d567a4bb10857dea5e37ed0c95b5/unsplash_lib-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-09 17:58:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "beh185",
"github_project": "unsplash_lib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "unsplash-lib"
}
JSON
