# DiceBear Py Wrapper
 \
Always keep an eye on https://dicebear.vhjan.me/ for updates and warnings about this packages!
[`dicebear`](https://pypi.org/project/dicebear/) is a Python API wrapper for https://dicebear.com. Using this wrapper you can get custom avatars for your program. \
For an example go to [`examples/dicebear.py`](https://github.com/jvherck/dicebear/tree/main/examples).
---
## Useful links
* Official Dicebear: https://dicebear.com/
* Docs: https://dicebear.vhjan.me/
* PyPI: https://pypi.org/project/dicebear/
* GitHub: https://github.com/jvherck/dicebear
* Dicebear Python CLI: https://github.com/jvherck/dicebear-cli
---
## Changelog
Find the changelog here: https://dicebear.vhjan.me/changelog
---
## How to install
Run `pip install -U dicebear` \
If that doesn't work try `py -m pip install -U dicebear`
---
## Usage
Important note: *Pillow* is not a required dependency, it's only required when you want to be able to edit the avatar images (using `DAvatar.pillow()`).
When using a `PIL` function while it's not installed it will raise `dicebear.errors.PILError`.
When the environment variable `ENABLE_PYTHON_DICEBEAR_USAGE_STATS` is set to true, an API will be pinged on most function calls to update this package's usage stats. This will be used to analyse Dicebear's usage and improve your overall experience, but may have performance costs.
```py
import PIL.Image
import os
from dicebear import DAvatar, DStyle, DOptions, DColor, DFormat, bulk_create
# Enable anonymous usage statistics
os.environ['ENABLE_PYTHON_DICEBEAR_USAGE_STATS'] = 'true'
# Creating options
options = DOptions(
backgroundColor=DColor("00ddd0"),
rotate=90
)
# Making a DAvatar object
av = DAvatar(
style=DStyle.pixel_art,
seed="John Apple",
options=options
)
print(av.url_svg) # Prints the svg url
# Editing the DAvatar object
av.edit(
extra_options=DOptions(backgroundColor=DColor("000000"))
)
# Using `extra_options` keep the `rotate` option but override the `backgroundColor` option
print(av.url_webp) # Prints the webp url
# Editing the style specific customisations
av.customise(
blank_options={
"face": "variant04"
}
)
# Using `blank_options` will delete your previous customisations for this DAvatar and generate new ones
print(av.url_png) # Prints the png url
# Saving an avatar to your device
av.save(
location=None, # Passing `None` will save it in the current working directory
file_name="dicebear_avatar",
file_format=DFormat.svg,
overwrite=True,
open_after_save=False
)
# Converting the DAvatar object into a PIL.Image.Image object
av_img: PIL.Image.Image = av.pillow()
# Opening and viewing the DAvatar image
av.open(use_pil=True) # or av.view()
# Creating multiple random avatars of the same style at once
avatars: list = bulk_create(style=DStyle.random(), amount=10)
```
---
## CLI Usage
Dicebear has a CLI package that uses Python to generate avatars quickly.
You can't customize each avatar, to do that you'll need to use the Python module.
To use the CLI run `pip install dicebear-cli` in a terminal.
Documentation can be found here: https://github.com/jvherck/dicebear-cli.
---
## Customization
Customize your avatars with these possibilities.
### Styles
All the possible avatar styles. \
https://dicebear.com/styles
* `adventurer`
* `adventurer-neutral`
* `avataaars`
* `avataaars-neutral`
* `big-ears`
* `big-ears-neutral`
* `big-smile`
* `bottts`
* `bottts-neutral`
* `croodles`
* `croodles-neutral`
* `dylan`
* `fun-emoji`
* `glass`
* `icons`
* `identicon`
* `initials`
* `lorelei`
* `lorelei-neutral`
* `micah`
* `miniavs`
* `notionists`
* `notionists-neutral`
* `open-peeps`
* `personas`
* `pixel-art`
* `pixel-art-neutral`
* `rings`
* `shapes`
* `thumbs`
### Base Options
All the possible options for the avatar. These options work for all the styles.
* `seed` (type: `str`) - the seed for the avatar generator, determine its basic looks
* `flip` (type: `bool`) - flips the image vertically (default False)
* `rotate` (type: `int`) - rotates the avatar (default 0, min 0, max 360)
* `scale` (type: `int`) - the scale of the avatar drawing itself (default 100, min 0, max 200)
* `radius` (type: `int`) - the radius of the avatar (default 0, min 0, max 50)
* `size` (type: `int`) - the size of the avatar (px) (default 256, min 1, max 256)
* `backgroundColor` (type: `DColor("transparent")` ) - the background color of the avatar. this can be a list of strings
if you have *backgroundType* set to "gradientLinear". (default transparent)
* `backgroundType` (type: `str` ) - set the background to either `gradientLinear` or `solid` (default solid)
* `backgroundRotation` (type: `int` ) - rotate the background if backgroundType is set to `gradientLinear` (default 0)
* `translateX` (type: `int`) - move the avatar horizontally (default 0, min -100, max 100)
* `translateY` (type: `int`) - move the avatar vertically (default 0, min -100, max 100)
* `randomizeIds` (type: `bool`) - randomize the IDs in the generated SVG/XML, can be useful if the avatars are included
directly in HTML and you want to avoid ID conflicts (default false)
### Specific Style Options
Specific options to get a more detailed avatar. This is different for every style. \
Click the style to see its options.
* [adventurer](https://dicebear.com/styles/adventurer#options)
* [adventurer-neutral](https://dicebear.com/styles/adventurer-neutral#options)
* [avataaars](https://dicebear.com/styles/avataaars#options)
* [avataaars-neutral](https://dicebear.com/styles/avataaars-neutral#options)
* [big-ears](https://dicebear.com/styles/big-ears#options)
* [big-ears-neutral](https://dicebear.com/styles/big-ears-neutral#options)
* [big-smile](https://dicebear.com/styles/big-smile#options)
* [bottts](https://dicebear.com/styles/bottts#options)
* [bottts-neutral](https://dicebear.com/styles/bottts-neutral#options)
* [croodles](https://dicebear.com/styles/croodles#options)
* [croodles-neutral](https://dicebear.com/styles/croodles-neutral#options)
* [dylan](https://dicebear.com/styles/dylan#options)
* [fun-emoji](https://dicebear.com/styles/fun-emoji#options)
* [glass](https://dicebear.com/styles/glass#options)
* [icons](https://dicebear.com/styles/icons#options)
* [identicon](https://dicebear.com/styles/identicon#options)
* [initials](https://dicebear.com/styles/initials#options)
* [lorelei](https://dicebear.com/styles/lorelei#options)
* [lorelei-neutral](https://dicebear.com/styles/lorelei-neutral#options)
* [micah](https://dicebear.com/styles/micah#options)
* [miniavs](https://dicebear.com/styles/miniavs#options)
* [notionists](https://dicebear.com/styles/notionists#options)
* [notionists-neutral](https://dicebear.com/styles/notionists-neutral#options)
* [open-peeps](https://dicebear.com/styles/open-peeps#options)
* [personas](https://dicebear.com/styles/personas#options)
* [pixel-art](https://dicebear.com/styles/pixel-art#options)
* [pixel-art-neutral](https://dicebear.com/styles/pixel-art-neutral#options)
* [rings](https://www.dicebear.com/styles/rings#options)
* [shapes](https://dicebear.com/styles/shapes#options)
* [thumbs](https://dicebear.com/styles/thumbs#options)
### Formats
These are the only supported formats. \
If you have Pillow (PIL) installed you can convert `DAvatar` to a `PIL.Image.Image` object to get a
wider range of formats (Pillow doesn't support svg).
* `DFormat.svg` (default)
* `DFormat.webp`
* `DFormat.avif`
* `DFormat.png`
* `DFormat.jpg`
* `DFormat.jpeg`
* `DFormat.json`
---
## Credits
Special thanks to [DiceBear](https://github.com/dicebear) ([Florian Körner](https://github.com/FlorianKoerner)) for
making this amazing API and to [all artists](https://dicebear.com/licenses) for creating these avatars!
## Licenses and privacy policy
- Dicebear **Licenses**: https://dicebear.com/licenses
- Dicebear **Privacy Policy**: https://dicebear.com/legal/privacy-policy
- Dicebear Python API wrapper (this project): https://dicebear.vhjan.me/license
Raw data
{
"_id": null,
"home_page": "https://dicebear.vhjan.me/",
"name": "dicebear",
"maintainer": "jvherck",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "jan@vhjan.me",
"keywords": "python, dicebear, avatar, avatars, generating, generation, generator, API, wrapper, image, images, picture, pictures, png, jpg, svg, json, cli, pillow, pil, requests, adventurer, adventurer-neutral, avataaars, avataaars-neutral, big-ears, big-ears-neutral, big-smile, bottts, bottts-neutral, croodles, croodles-neutral, fun-emoji, icons, identicon, initials, lorelei, lorelei-neutral, micah, miniavs, notionists, notionists-neutral, open-peeps, personas, pixel-art, pixel-art-neutral, shapes, thumbs",
"author": "jvherck",
"author_email": "jan@vhjan.me",
"download_url": "https://files.pythonhosted.org/packages/6b/e4/84ca8952b264b00f687a01d7013d7c2fb13d7cb886654863796c7abfd391/dicebear-2.9.2.tar.gz",
"platform": null,
"description": "# DiceBear Py Wrapper \r\n\r\n \\\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\nAlways keep an eye on https://dicebear.vhjan.me/ for updates and warnings about this packages!\r\n\r\n[`dicebear`](https://pypi.org/project/dicebear/) is a Python API wrapper for https://dicebear.com. Using this wrapper you can get custom avatars for your program. \\\r\nFor an example go to [`examples/dicebear.py`](https://github.com/jvherck/dicebear/tree/main/examples).\r\n\r\n\r\n---\r\n\r\n\r\n## Useful links \r\n* Official Dicebear: https://dicebear.com/\r\n* Docs: https://dicebear.vhjan.me/ \r\n* PyPI: https://pypi.org/project/dicebear/ \r\n* GitHub: https://github.com/jvherck/dicebear \r\n* Dicebear Python CLI: https://github.com/jvherck/dicebear-cli \r\n\r\n\r\n---\r\n\r\n\r\n## Changelog\r\nFind the changelog here: https://dicebear.vhjan.me/changelog\r\n\r\n\r\n---\r\n\r\n\r\n## How to install \r\nRun `pip install -U dicebear` \\\r\nIf that doesn't work try `py -m pip install -U dicebear` \r\n\r\n\r\n---\r\n\r\n\r\n## Usage \r\nImportant note: *Pillow* is not a required dependency, it's only required when you want to be able to edit the avatar images (using `DAvatar.pillow()`).\r\nWhen using a `PIL` function while it's not installed it will raise `dicebear.errors.PILError`. \r\n\r\nWhen the environment variable `ENABLE_PYTHON_DICEBEAR_USAGE_STATS` is set to true, an API will be pinged on most function calls to update this package's usage stats. This will be used to analyse Dicebear's usage and improve your overall experience, but may have performance costs.\r\n\r\n```py \r\nimport PIL.Image\r\nimport os\r\nfrom dicebear import DAvatar, DStyle, DOptions, DColor, DFormat, bulk_create\r\n\r\n# Enable anonymous usage statistics\r\nos.environ['ENABLE_PYTHON_DICEBEAR_USAGE_STATS'] = 'true'\r\n\r\n# Creating options\r\noptions = DOptions(\r\n backgroundColor=DColor(\"00ddd0\"),\r\n rotate=90\r\n)\r\n\r\n# Making a DAvatar object\r\nav = DAvatar(\r\n style=DStyle.pixel_art,\r\n seed=\"John Apple\",\r\n options=options\r\n)\r\nprint(av.url_svg) # Prints the svg url\r\n\r\n# Editing the DAvatar object\r\nav.edit(\r\n extra_options=DOptions(backgroundColor=DColor(\"000000\"))\r\n)\r\n# Using `extra_options` keep the `rotate` option but override the `backgroundColor` option\r\n\r\nprint(av.url_webp) # Prints the webp url\r\n\r\n# Editing the style specific customisations\r\nav.customise(\r\n blank_options={\r\n \"face\": \"variant04\"\r\n }\r\n)\r\n# Using `blank_options` will delete your previous customisations for this DAvatar and generate new ones\r\n\r\nprint(av.url_png) # Prints the png url\r\n\r\n# Saving an avatar to your device\r\nav.save(\r\n location=None, # Passing `None` will save it in the current working directory\r\n file_name=\"dicebear_avatar\",\r\n file_format=DFormat.svg,\r\n overwrite=True,\r\n open_after_save=False\r\n)\r\n\r\n# Converting the DAvatar object into a PIL.Image.Image object\r\nav_img: PIL.Image.Image = av.pillow()\r\n\r\n# Opening and viewing the DAvatar image\r\nav.open(use_pil=True) # or av.view()\r\n\r\n# Creating multiple random avatars of the same style at once\r\navatars: list = bulk_create(style=DStyle.random(), amount=10)\r\n```\r\n\r\n\r\n---\r\n\r\n\r\n## CLI Usage \r\nDicebear has a CLI package that uses Python to generate avatars quickly.\r\nYou can't customize each avatar, to do that you'll need to use the Python module.\r\n\r\nTo use the CLI run `pip install dicebear-cli` in a terminal. \r\nDocumentation can be found here: https://github.com/jvherck/dicebear-cli.\r\n\r\n\r\n---\r\n\r\n\r\n## Customization\r\nCustomize your avatars with these possibilities. \r\n\r\n\r\n### Styles \r\nAll the possible avatar styles. \\\r\nhttps://dicebear.com/styles \r\n \r\n* `adventurer` \r\n* `adventurer-neutral` \r\n* `avataaars` \r\n* `avataaars-neutral` \r\n* `big-ears` \r\n* `big-ears-neutral` \r\n* `big-smile` \r\n* `bottts` \r\n* `bottts-neutral` \r\n* `croodles` \r\n* `croodles-neutral` \r\n* `dylan`\r\n* `fun-emoji` \r\n* `glass`\r\n* `icons` \r\n* `identicon` \r\n* `initials` \r\n* `lorelei` \r\n* `lorelei-neutral` \r\n* `micah` \r\n* `miniavs` \r\n* `notionists`\r\n* `notionists-neutral`\r\n* `open-peeps` \r\n* `personas` \r\n* `pixel-art` \r\n* `pixel-art-neutral`\r\n* `rings`\r\n* `shapes`\r\n* `thumbs`\r\n\r\n\r\n### Base Options \r\nAll the possible options for the avatar. These options work for all the styles. \r\n\r\n* `seed` (type: `str`) - the seed for the avatar generator, determine its basic looks \r\n* `flip` (type: `bool`) - flips the image vertically (default False) \r\n* `rotate` (type: `int`) - rotates the avatar (default 0, min 0, max 360) \r\n* `scale` (type: `int`) - the scale of the avatar drawing itself (default 100, min 0, max 200) \r\n* `radius` (type: `int`) - the radius of the avatar (default 0, min 0, max 50) \r\n* `size` (type: `int`) - the size of the avatar (px) (default 256, min 1, max 256) \r\n* `backgroundColor` (type: `DColor(\"transparent\")` ) - the background color of the avatar. this can be a list of strings\r\nif you have *backgroundType* set to \"gradientLinear\". (default transparent) \r\n* `backgroundType` (type: `str` ) - set the background to either `gradientLinear` or `solid` (default solid) \r\n* `backgroundRotation` (type: `int` ) - rotate the background if backgroundType is set to `gradientLinear` (default 0) \r\n* `translateX` (type: `int`) - move the avatar horizontally (default 0, min -100, max 100) \r\n* `translateY` (type: `int`) - move the avatar vertically (default 0, min -100, max 100) \r\n* `randomizeIds` (type: `bool`) - randomize the IDs in the generated SVG/XML, can be useful if the avatars are included \r\ndirectly in HTML and you want to avoid ID conflicts (default false) \r\n\r\n\r\n### Specific Style Options \r\nSpecific options to get a more detailed avatar. This is different for every style. \\\r\nClick the style to see its options. \r\n\r\n* [adventurer](https://dicebear.com/styles/adventurer#options) \r\n* [adventurer-neutral](https://dicebear.com/styles/adventurer-neutral#options) \r\n* [avataaars](https://dicebear.com/styles/avataaars#options) \r\n* [avataaars-neutral](https://dicebear.com/styles/avataaars-neutral#options) \r\n* [big-ears](https://dicebear.com/styles/big-ears#options) \r\n* [big-ears-neutral](https://dicebear.com/styles/big-ears-neutral#options) \r\n* [big-smile](https://dicebear.com/styles/big-smile#options) \r\n* [bottts](https://dicebear.com/styles/bottts#options) \r\n* [bottts-neutral](https://dicebear.com/styles/bottts-neutral#options) \r\n* [croodles](https://dicebear.com/styles/croodles#options) \r\n* [croodles-neutral](https://dicebear.com/styles/croodles-neutral#options) \r\n* [dylan](https://dicebear.com/styles/dylan#options) \r\n* [fun-emoji](https://dicebear.com/styles/fun-emoji#options) \r\n* [glass](https://dicebear.com/styles/glass#options) \r\n* [icons](https://dicebear.com/styles/icons#options) \r\n* [identicon](https://dicebear.com/styles/identicon#options) \r\n* [initials](https://dicebear.com/styles/initials#options) \r\n* [lorelei](https://dicebear.com/styles/lorelei#options) \r\n* [lorelei-neutral](https://dicebear.com/styles/lorelei-neutral#options) \r\n* [micah](https://dicebear.com/styles/micah#options) \r\n* [miniavs](https://dicebear.com/styles/miniavs#options) \r\n* [notionists](https://dicebear.com/styles/notionists#options) \r\n* [notionists-neutral](https://dicebear.com/styles/notionists-neutral#options) \r\n* [open-peeps](https://dicebear.com/styles/open-peeps#options) \r\n* [personas](https://dicebear.com/styles/personas#options) \r\n* [pixel-art](https://dicebear.com/styles/pixel-art#options) \r\n* [pixel-art-neutral](https://dicebear.com/styles/pixel-art-neutral#options) \r\n* [rings](https://www.dicebear.com/styles/rings#options)\r\n* [shapes](https://dicebear.com/styles/shapes#options) \r\n* [thumbs](https://dicebear.com/styles/thumbs#options) \r\n\r\n\r\n### Formats \r\nThese are the only supported formats. \\\r\nIf you have Pillow (PIL) installed you can convert `DAvatar` to a `PIL.Image.Image` object to get a\r\nwider range of formats (Pillow doesn't support svg). \r\n \r\n* `DFormat.svg` (default) \r\n* `DFormat.webp` \r\n* `DFormat.avif` \r\n* `DFormat.png` \r\n* `DFormat.jpg` \r\n* `DFormat.jpeg` \r\n* `DFormat.json` \r\n\r\n\r\n---\r\n\r\n\r\n## Credits \r\nSpecial thanks to [DiceBear](https://github.com/dicebear) ([Florian K\u00f6rner](https://github.com/FlorianKoerner)) for \r\nmaking this amazing API and to [all artists](https://dicebear.com/licenses) for creating these avatars! \r\n\r\n\r\n## Licenses and privacy policy \r\n- Dicebear **Licenses**: https://dicebear.com/licenses \r\n- Dicebear **Privacy Policy**: https://dicebear.com/legal/privacy-policy \r\n- Dicebear Python API wrapper (this project): https://dicebear.vhjan.me/license\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A python wrapper for DiceBear's avatar generating API.",
"version": "2.9.2",
"project_urls": {
"Documentation": "https://dicebear.vhjan.me/",
"Homepage": "https://dicebear.vhjan.me/",
"Source": "https://github.com/jvherck/dicebear",
"Tracker": "https://github.com/jvherck/dicebear/issues"
},
"split_keywords": [
"python",
" dicebear",
" avatar",
" avatars",
" generating",
" generation",
" generator",
" api",
" wrapper",
" image",
" images",
" picture",
" pictures",
" png",
" jpg",
" svg",
" json",
" cli",
" pillow",
" pil",
" requests",
" adventurer",
" adventurer-neutral",
" avataaars",
" avataaars-neutral",
" big-ears",
" big-ears-neutral",
" big-smile",
" bottts",
" bottts-neutral",
" croodles",
" croodles-neutral",
" fun-emoji",
" icons",
" identicon",
" initials",
" lorelei",
" lorelei-neutral",
" micah",
" miniavs",
" notionists",
" notionists-neutral",
" open-peeps",
" personas",
" pixel-art",
" pixel-art-neutral",
" shapes",
" thumbs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "011dbf3f929a1ac34d65353b482dc5fbd706d619179a12bcc588c4ef8d826dac",
"md5": "0c49f34eb0377b7497af9ffb7f7cc11c",
"sha256": "4fa789ec116c0c4b90546f5f3b1466cee9cf96ca44c5ecc0cc73706ae1494a9f"
},
"downloads": -1,
"filename": "dicebear-2.9.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c49f34eb0377b7497af9ffb7f7cc11c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 20384,
"upload_time": "2024-07-28T15:05:26",
"upload_time_iso_8601": "2024-07-28T15:05:26.974648Z",
"url": "https://files.pythonhosted.org/packages/01/1d/bf3f929a1ac34d65353b482dc5fbd706d619179a12bcc588c4ef8d826dac/dicebear-2.9.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6be484ca8952b264b00f687a01d7013d7c2fb13d7cb886654863796c7abfd391",
"md5": "e8d81011c0870a4525ce566367a23ac4",
"sha256": "20bc8779551044951b043daeb811d13585c96bc65bcdcdda248b016ee8226d35"
},
"downloads": -1,
"filename": "dicebear-2.9.2.tar.gz",
"has_sig": false,
"md5_digest": "e8d81011c0870a4525ce566367a23ac4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 20334,
"upload_time": "2024-07-28T15:05:28",
"upload_time_iso_8601": "2024-07-28T15:05:28.309341Z",
"url": "https://files.pythonhosted.org/packages/6b/e4/84ca8952b264b00f687a01d7013d7c2fb13d7cb886654863796c7abfd391/dicebear-2.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-28 15:05:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jvherck",
"github_project": "dicebear",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "dicebear"
}
JSON
